Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Use Keryn air-gapped

    View as Markdown

    Run Keryn on a machine or a network segment with no route to the internet, and be able to show that it did not need one: installed from files you carried in, scanned with the network denied, with the rules, the docs and the evidence check all local.

    • A machine with internet access to fetch the release files once, and a way to carry them (a transfer share, a signed artifact repository). The air-gapped side needs only git if you diff against a ref, and Node.js 22 or later if you install the npm package. The single binary and the container image need neither.
    • Which surface you can use. The CLI, the language server, the editor extensions and Keryn Desktop run locally. Keryn Web is a page you open from keryn.app and fetches the repositories you name, so it is not an air-gapped tool; its folder scan still reads files in place, but the page itself must be loaded from the internet. Keryn is licensed to run unmodified copies obtained from Keryn, so do not host the page yourself.

    On the connected machine, download the release artifact you will use (see install and download) together with its SHA256SUMS. Check it there, carry both files across, and check again on the other side:

    Terminal window
    shasum -a 256 -c SHA256SUMS --ignore-missing

    Set KERYN_CLI_TARBALL to the path of the reviewed local CLI archive, then install without a registry:

    Terminal window
    npm install --offline --ignore-scripts --global --prefix "$HOME/.local" "$KERYN_CLI_TARBALL"
    export PATH="$HOME/.local/bin:$PATH"

    or run the single binary, or load the container image (docker load < keryn-<version>.tar). The rules ship inside the package, sealed. Nothing is downloaded at scan time or install time beyond the files you brought.

    Keryn never opens a network connection to scan. --offline is accepted and does nothing, because there is nothing to switch off. Do not take that on trust: run the scan where the network is denied by the operating system.

    On macOS, a sandbox profile that denies every network call:

    Terminal window
    sandbox-exec -p '(version 1)(allow default)(deny network*)' keryn scan . --no-cache --quiet --sarif keryn-out/keryn.sarif

    The scan completes and exits 1 (this fixture has findings). A tool that needed the network would fail here with a connection error instead. On Linux, Bubblewrap creates the network namespace. The repository and temporary directory stay writable for reports and engine scratch files; the rest of the filesystem is read-only:

    Terminal window
    bwrap --unshare-net --ro-bind / / --dev /dev --proc /proc \
    --bind "$PWD" "$PWD" --bind "${TMPDIR:-/tmp}" "${TMPDIR:-/tmp}" \
    -- keryn scan . --quiet --sarif keryn-out/linux.sarif

    Set KERYN_IMAGE to the private image tag you loaded, then run it with networking disabled:

    Terminal window
    docker run --rm --network none -v "$PWD:/work:ro" "$KERYN_IMAGE" scan /work --quiet --sarif -

    The one command that can reach the network is one you start yourself, with an https:// address that you pass. See the privacy page for the complete list of network calls of every surface.

    The command help, the exit codes, the output formats and the eight edge kinds are inside the CLI:

    Terminal window
    keryn docs exit-codes | grep -E '^\| (0|2) '
    | 0 | pass | Nothing failed the gate. |
    | 2 | usage | The command line or a config, policy or rules file is wrong. Nothing was scanned. |

    keryn docs exit-codes prints the whole table, including the codes for incomplete coverage and internal errors. Every rule’s message, remediation and references are inside it too (keryn explain <rule-id>); see explain and docs. Both read from the package and make no request.

    4. Produce evidence that can be checked later, anywhere

    Section titled “4. Produce evidence that can be checked later, anywhere”

    The successful verification below uses a scan with at least one finding anchored to a non-blank source line. A bundle with zero digest-backed code anchors exits 1 even when its document digests match.

    Terminal window
    keryn bundle . --out ../run
    keryn verify-bundle ../run.bundle.json
    wrote evidence bundle -> ../run.bundle.json
    OK: 7 verified anchor(s), 2 unanchored, 0 digest mismatch(es)

    The bundle is one file; carrying it out of the segment and verifying it on another machine, offline, gives the same answer, because every digest in it is a SHA-256 of content in the same file. See evidence for auditors.

    5. Dependency advisories, from files you carry in

    Section titled “5. Dependency advisories, from files you carry in”

    On main, not in Keryn 0.5.2. Without a network a scan reads lockfiles but cannot ask OSV.dev, so it reports dependencies as not checked. An advisory snapshot on the machine closes that gap.

    1. On a machine with a network, download OSV’s per-ecosystem export files into a folder laid out as OSV publishes them: npm/all.zip, PyPI/all.zip, Maven/all.zip and so on (from https://osv-vulnerabilities.storage.googleapis.com/<ecosystem>/all.zip). The npm export is about 220 MB, PyPI about 40 MB; distribution exports are larger (Ubuntu is over 800 MB).
    2. Carry the folder in and build the snapshot on the machine that scans:
    Terminal window
    keryn sca db update --from ./osv-exports --check # read and verify, write nothing
    keryn sca db update --from ./osv-exports # build, verify, then swap in atomically
    keryn sca db status # per ecosystem: records, source, date
    1. Scan as before. The verdict now reads Dependency advisories: checked (snapshot 2026-11-17), and keryn sca image uses the same snapshot when you give it neither --advisories nor --online.

    What to know:

    • Carry the export files, not a snapshot built elsewhere. A snapshot that arrives already built is installed only when it is signed, and Keryn does not publish signed snapshots yet. One built on the machine is checked for integrity (size and SHA-256 of every file, on every change), which catches truncation and alteration after the build; it cannot prove where the export files came from, because OSV does not sign them.
    • An ecosystem you did not carry in is reported as not checked, never as clean. --require-advisories turns that into exit 3.
    • Advisory data ages. --advisory-max-age 30 (or advisoryMaxAge: 30 in .keryn.yml) makes a scan against a snapshot older than 30 days an incomplete run, so a stale snapshot cannot pass unnoticed.
    • The snapshot carries a NOTICES.md listing each advisory source and its licence.

    6. The known-fix database, updated from a directory

    Section titled “6. The known-fix database, updated from a directory”

    Known-fix matching reads a signed database of fingerprints. In an air-gapped network you update it from a directory you carry in, never from the internet:

    Terminal window
    keryn nday-db update --from ./nday-db-2026-11 --check # verify the signature, write nothing
    keryn nday-db update --from ./nday-db-2026-11 # verify, then swap in atomically

    In the Node CLI, nday-db hands over to a helper called keryn-native, which the CLI archives ship beside keryn; when it is missing (the npm package does not include it), the command stops and says so instead of doing less. An unsigned or altered database is refused as a whole. More on known-fix matching.

    The scan crosses no network edge. The only edge it uses is the file system, in one direction: it reads your checkout and writes the files you named. You showed it by denying the network and getting the same result, not by reading a promise. The remaining crossings in an air-gapped setup are the ones you carry by hand, and each has a checksum or a signature.