Use Keryn air-gapped
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.
Before you start
Section titled “Before you start”- 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
gitif 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.
1. Bring the files in
Section titled “1. Bring the files in”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:
shasum -a 256 -c SHA256SUMS --ignore-missingSet KERYN_CLI_TARBALL to the path of the reviewed local CLI archive, then install without a registry:
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.
2. Scan with the network denied
Section titled “2. Scan with the network denied”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:
sandbox-exec -p '(version 1)(allow default)(deny network*)' keryn scan . --no-cache --quiet --sarif keryn-out/keryn.sarifThe 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:
bwrap --unshare-net --ro-bind / / --dev /dev --proc /proc \ --bind "$PWD" "$PWD" --bind "${TMPDIR:-/tmp}" "${TMPDIR:-/tmp}" \ -- keryn scan . --quiet --sarif keryn-out/linux.sarifSet KERYN_IMAGE to the private image tag you loaded, then run it with networking disabled:
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.
3. Keep the documentation with the tool
Section titled “3. Keep the documentation with the tool”The command help, the exit codes, the output formats and the eight edge kinds are inside the CLI:
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.
keryn bundle . --out ../runkeryn verify-bundle ../run.bundle.jsonwrote evidence bundle -> ../run.bundle.jsonOK: 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.
- 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.zipand so on (fromhttps://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). - Carry the folder in and build the snapshot on the machine that scans:
keryn sca db update --from ./osv-exports --check # read and verify, write nothingkeryn sca db update --from ./osv-exports # build, verify, then swap in atomicallykeryn sca db status # per ecosystem: records, source, date- Scan as before. The verdict now reads
Dependency advisories: checked (snapshot 2026-11-17), andkeryn sca imageuses the same snapshot when you give it neither--advisoriesnor--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-advisoriesturns that into exit 3. - Advisory data ages.
--advisory-max-age 30(oradvisoryMaxAge: 30in.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.mdlisting 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:
keryn nday-db update --from ./nday-db-2026-11 --check # verify the signature, write nothingkeryn nday-db update --from ./nday-db-2026-11 # verify, then swap in atomicallyIn 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.
What you just proved
Section titled “What you just proved”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.
- What each surface may call: local by design and privacy.
- Pipelines without internet access: CI, air-gapped runners.
- The checks that prove a bundle is intact: evidence for auditors.