All tutorials

Air-gapped installs

Cordon 0.7.03 sections · 3 diagramsView this tutorial on GitHub

Cordon never sends anything about the code it scans, which makes an air-gap the easy case, not the hard one. Since 0.6.0 a default scan makes one kind of request: it asks OSV (osv-vulnerabilities.storage.googleapis.com) which advisories changed since its bundled database was built, with requests that are the same for everyone and name no package. On an air-gapped runner that request cannot succeed, and the scan would report its intel as stale (OPERATIONAL.INTEL.STALE). So set CORDON_OFFLINE=1 (or pass --offline) there: no request is attempted at all, and intel is refreshed with the bundle installed below.

Air-gapped installs, figure 1
   INTERNET SIDE                    │  AIR GAP │              SECURE SIDE
   ─────────────                    │          │              ──────────
   cordon-scanner bundle create ───▶│  copy    │───▶ cordon-scanner bundle verify
     (wheel + rules + advisories)   │  the     │     cordon-scanner bundle install
                                    │  bundle  │              │
                                    │          │              ▼
                                    │          │        scan, fully offline
   bundle create  -o cordon-bundle.tar  <source-dir>    build a bundle from a dir   bundle verify     cordon-bundle.tar                   check it against its manifest   bundle install    cordon-bundle.tar --into DIR        verify, THEN extract into DIR
Air-gapped installs, figure 2
   VERIFY-BEFORE-EXTRACT
   ┌──────────────────────────────────────────────────────────────┐
   │ install = verify the manifest, then safe-extract (no path    │
   │ traversal, no symlink escape). A bundle that fails the check │
   │ is never unpacked.                                           │
   └──────────────────────────────────────────────────────────────┘

Intel older than a week makes a scan incomplete, so an isolated machine needs fresh intel carried to it, verified on arrival:

Air-gapped installs, figure 3
   internet host:   the release's two assets, cordon-advisories.tar.gz and its .sig
        │           carry the folder across the gap
        ▼
   air-gapped host: cordon-scanner advisories sync --bundle /media/usb/cordon-0.7.0/
                    (the Ed25519 signature is checked against the key pinned in the
                    scanner before a single byte is unpacked)

Once a release pins the signed feed's root (0.7.0 does not), a site with an internal HTTPS mirror can mirror the feed instead and set CORDON_FEED_URL; every byte is still verified against the pinned root. Do not copy one machine's synced cache to another: it is sealed by the install that wrote it, and copied files are reported as OPERATIONAL.ADVISORY.TAMPERED and ignored. Tutorial 40 is the full procedure, the hash-pinned install included.

   same input  +  same rules  +  same advisory data   ─▶   byte-identical result   no network  =  no "it changed between runs"          =  auditable, cacheable

Next: 12 · Vetting a package before you install it.