# Use Keryn air-gapped

> Install from files, scan with the network denied, read the docs offline and verify evidence on a machine that never touches the internet.

Source: https://keryn.dev/docs/guides/air-gapped/

## Goal

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

- 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](https://keryn.dev/docs/guides/web-app/) 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

On the connected machine, download the release artifact you will use (see [install](https://keryn.dev/docs/start/install/) and [download](https://keryn.dev/download/)) together with its `SHA256SUMS`. Check it there, carry both files across, and check again on the other side:

```sh
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:

```sh
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

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:

```sh
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:

```sh
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:

```sh
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](https://keryn.dev/privacy/) for the complete list of network calls of every surface.

## 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:

```sh
keryn docs exit-codes | grep -E '^\| (0|2) '
```

```text
| 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](https://keryn.dev/docs/guides/explain-and-docs/). Both read from the package and make no request.

## 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.

```sh
keryn bundle . --out ../run
keryn verify-bundle ../run.bundle.json
```

```text
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](https://keryn.dev/docs/guides/auditors/).

## 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:

```sh
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
```

3. 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

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:

```sh
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](https://keryn.dev/docs/guides/known-fix/).

## 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.

## Next

- What each surface may call: [local by design](https://keryn.dev/docs/concepts/local-only/) and [privacy](https://keryn.dev/privacy/).
- Pipelines without internet access: [CI](https://keryn.dev/docs/guides/ci/), air-gapped runners.
- The checks that prove a bundle is intact: [evidence for auditors](https://keryn.dev/docs/guides/auditors/).
