Use Case: Offline Vulnerability Scanning
Scenario
A security engineer needs to check software deployed on an air-gapped system for known vulnerabilities. Since the system has no internet access, vulnerability databases must be transferred across the air gap and scanning must run entirely offline.
Scan deployed software for known vulnerabilities using a locally available SBOM and an offline vulnerability database. The vulnerability database is periodically updated on the connected side and transferred across the air gap. Connected side: Download vulnerability database updates (Grype DB or Trivy DB). Optionally pre-scan known SBOMs and generate alert summaries. Transfer: Move the vulnerability database across the air gap via USB alongside regular software updates. Air-gapped side: Run Success Criteria: Vulnerabilities identified without network access, reports generated in both machine-readable and human-readable formats, severity thresholds enforced via exit codes. |
Prerequisites
Connected machine: System with internet access for downloading vulnerability databases
Air-gapped machine: Target system with deployed software and corresponding SBOMs
SBOM: CycloneDX SBOM generated by AirGap Deploy (see SBOM/CBOM Generation During... (UC-DEPLOY-003))
Transfer method: USB drives or AirGap Transfer utility
AirGap Deploy v1.1: Version with
scansubcommand
Workflow Steps
Phase 1: Database Preparation (Connected Machine)
Download Vulnerability Database
# Download Grype vulnerability database (~65MB)
grype db update
# Or download Trivy database (~34MB)
trivy db download
# Package for transfer
cp ~/.grype/db/vulnerability.db /staging/vuln-db-2026-02-08/
tar -czf vuln-db-2026-02-08.tar.gz -C /staging vuln-db-2026-02-08/
The vulnerability database is a self-contained file that can be updated independently of the software being scanned. For ongoing maintenance, this download can run as a daily or weekly cron job.
Optional: Pre-Scan on Connected Side
If SBOMs from previous deployments are available on the connected side, a pre-scan can identify urgent vulnerabilities before the next transfer window:
# Pre-scan against known SBOMs
airgap-deploy scan --sbom previous-deploy-sbom.cdx.json --db ~/.grype/db/
# Generate alert summary for review
airgap-deploy scan --sbom previous-deploy-sbom.cdx.json --db ~/.grype/db/ \
--format json > alerts-2026-02-08.json
Phase 2: Transfer
Transfer the vulnerability database across the air gap alongside regular software updates:
# Pack vulnerability database for transfer
airgap-transfer pack vuln-db-2026-02-08.tar.gz /media/usb-drive
# Or simply copy if it fits on a single drive
cp vuln-db-2026-02-08.tar.gz /media/usb-drive/
Physically move USB drive(s) across air-gap boundary
Maintain chain of custody if required for security compliance
Phase 3: Scanning (Air-Gapped Machine)
Extract Vulnerability Database
# On air-gapped machine
tar -xzf /media/usb/vuln-db-2026-02-08.tar.gz -C /opt/vuln-db/
Run Vulnerability Scan
# Scan a specific deployment's SBOM
airgap-deploy scan \
--sbom /opt/deployments/secure-app/sbom.cdx.json \
--db /opt/vuln-db/vuln-db-2026-02-08/
# Output: vulnerability report to stdout (human-readable)
# Generate machine-readable report
airgap-deploy scan \
--sbom /opt/deployments/secure-app/sbom.cdx.json \
--db /opt/vuln-db/vuln-db-2026-02-08/ \
--format json > vuln-report-2026-02-08.json
Enforce Severity Thresholds
# Fail if critical vulnerabilities are found (for CI/CD pipelines)
airgap-deploy scan \
--sbom sbom.cdx.json \
--db /opt/vuln-db/vuln-db-2026-02-08/ \
--fail-on critical
# Exit code:
# 0 = no vulnerabilities above threshold
# 1 = vulnerabilities found above threshold
Scan All Deployed Software
# Scan all SBOMs in the deployments directory
for sbom in /opt/deployments/*/sbom.cdx.json; do
echo "=== Scanning: $sbom ==="
airgap-deploy scan --sbom "$sbom" --db /opt/vuln-db/vuln-db-2026-02-08/
done
Phase 4: Remediation Planning
Review the vulnerability report and plan remediation:
Identify affected components — which dependencies have known vulnerabilities
Assess severity — prioritize critical and high vulnerabilities
Plan update transfers — prepare patched versions on the connected side
Schedule remediation — coordinate the next transfer window for patches
The same deployment workflow that originally delivered the software handles the updates: prepare a new package on the connected side, transfer it across the gap, install it on the air-gapped system.
Success Criteria
Vulnerability scan runs entirely offline — no network calls
All components in the SBOM checked against the vulnerability database
Report generated in both human-readable and JSON formats
Exit code reflects severity threshold compliance
Scan completes in reasonable time (seconds, not minutes) for typical SBOMs
Error Scenarios
Error |
Cause |
Recovery |
|---|---|---|
“Vulnerability database not found” |
Database path incorrect or not extracted |
Verify path and extract database archive |
“Database too old” |
Database exceeds freshness threshold |
Transfer a more recent database update |
“Invalid SBOM format” |
SBOM not in CycloneDX format |
Regenerate SBOM with |
“Unknown component in SBOM” |
Component not in vulnerability database |
May indicate a proprietary or unlisted dependency |
The Update Cycle
Air-gapping does not mean freezing. Vulnerability scanning across the air gap follows a deliberate cadence:
Connected side monitors — poll vulnerability databases for new entries affecting deployed SBOMs
Package database updates — create dated archives of vulnerability database snapshots
Transfer on cadence — weekly or biweekly, bundle database updates with regular software transfers
Re-scan on the air-gapped side — run
airgap-deploy scanagainst all deployed SBOMsPrioritize and patch — review reports, plan remediation, prepare update packages