Airgapped (Offline) Scanning

Run the Xygeni scanner inside a network-isolated enclave. Findings never leave the air gap in cleartext; reports are encrypted at rest and opened only through a metered online unlock.

In airgapped mode a scan completes without any interaction with the Xygeni cloud platform: nothing is uploaded, and the scan needs no reply from the backend to finish. Findings stay inside your network and reports are written encrypted at rest — the console shows only statistics (counts, files, duration). To read a report you run a small, metered online unlock from a connected host; the report body itself never crosses the boundary.

How much other outbound traffic the scan may use (internal mirrors, public registries, nothing at all) is up to you — see Isolation modes. The default is a fully isolated run with no network calls.

Nothing leaves the enclave. Only a few-KB, findings-free key request is carried out of the air gap, and a few-KB key response is carried back in. No source code, dependency manifests, secret values, vulnerability details, or plaintext repository names are ever transmitted.

Airgapped scanning is a licensed capability. It is enabled per customer and delivered through your standard scanner package — there is no separate download or Docker image. The same licence can still run normal, online scans; airgap is engaged per run with the --airgap-mode option.

Before you start

You need:

• An air-gapped (offline) licence issued by Xygeni for your account.

• The scanner installed on the isolated host (see Xygeni CLI Installation).

• A connected host with the scanner and your Xygeni API token, used only for the read/unlock step (The Unlock Ceremony).

Setup

1. Request an air-gapped licence

Ask Xygeni (sales or support) to enable air-gapped scanning for your account. The licence is short-lived and rolling-renewed; it carries only public key material — no secret is placed on your host.

2. Send your host fingerprint(s)

An air-gapped licence is bound to one or more approved enclave hosts. On each host that will run scans, print its fingerprint and send the values to Xygeni:

xygeni util airgap fingerprint

This prints a value like v1:9f3c… (and the hostname, as a label). It needs no licence or token and makes no network call. Xygeni binds the licence to the fingerprints you supply.

The fingerprint suits fixed enclave hosts (bare metal or pinned VMs). On containers or autoscaled hosts the value may be weak or change; run xygeni util airgap fingerprint with enough privileges to read the hardware serials and confirm the value with Xygeni. Re-imaging a host means requesting a refreshed licence.

3. Install the licence

Place the licence file at conf/xygeni.lic on the isolated host, exactly as for a normal Xygeni licence.

4. Run a scan

Add the top-level --airgap-mode option before the scan type:

xygeni --airgap-mode isolated sast -n my-project /path/to/code

The scanner validates the licence locally (signature, host fingerprint, expiry), runs the offline engines, and writes for each scan type an encrypted report plus a small key request:

my-project.sast.json.enc        <- encrypted report (stays in the enclave)
sast.unlock-req                 <- key request (carry this out; no findings inside)

The console prints counts by severity, files scanned, and duration — never the findings. --fail-on exit codes still work (they derive from the counts).

--airgap-mode is a top-level option: it must come before the scan type (xygeni --airgap-mode <mode> sast …), not after it. If the option is present but the level is missing or invalid, the scanner fails closed to isolated rather than silently going online.

To read the reports, continue with The Unlock Ceremony.

Isolation modes

--airgap-mode takes one of three levels. All three encrypt reports and require the unlock; they differ only in how much outbound traffic the scan is allowed during enrichment.

Mode	Outbound traffic	Use it when
isolated	None (default, fail-safe).	A strict enclave with no reachable services.
filtered	Only hosts you list in conf/airgap-allowlist.txt.	You have internal mirrors/registries/SCM to reach.
no-upload	All outbound allowed, including the Xygeni backend for data retrieval — but findings are never uploaded.	A connected network where you still require findings to stay confidential.

Loopback (localhost, 127.0.0.0/8, ::1) is always allowed and never counts as outbound traffic.

The filtered allowlist

In filtered mode the scanner reaches only the hosts listed in conf/airgap-allowlist.txt (one per line):

# conf/airgap-allowlist.txt
registry.npmjs.org
search.maven.org
*.github.com
artifactory.internal

• One host, or a *.suffix wildcard that matches any sub-domain (*.github.com matches api.github.com, but not the apex github.com — list it separately).

• Blank lines and # comments are ignored; matching is case-insensitive.

• An empty or missing file means block everything — identical to isolated. It is never inverted to "allow all".

Finding what to allow. Run once under isolated (or filtered with an empty list). Blocked lookups don't fail the scan — they are skipped, and the summary reports the hosts it skipped:

Airgap: reduced coverage - 2 outbound lookup host(s) were skipped offline (registry.npmjs.org, search.maven.org)

Add the hosts you want to reach to conf/airgap-allowlist.txt and re-run in filtered mode.

What runs under air-gap

Local analysis runs offline; checks that need Xygeni's online data or your SCM/CI degrade or are skipped in the offline modes. no-upload allows retrieval from Xygeni — so SCA and enrichment run — and withholds only the upload of findings. A blocked lookup never aborts the scan: it is skipped and reported as reduced coverage.

Scan	isolated / filtered	no-upload
SAST (code security)	✅ Full	✅ Full
IaC	✅ Full	✅ Full
Misconfigurations	✅ Full	✅ Full
API Security	✅ Full	✅ Full
Secrets	⚠️ Full — no live verification	✅ Full
Dependencies	⚠️ Degraded — registry enrichment skipped	✅ Full
Malware	⚠️ Degraded — reputation checks skipped	✅ Full
Inventory	⚠️ Degraded — SCM/CI enrichment skipped	✅ Full
SuspectDeps	❌ Not run — needs registry data	✅ Full
Code Tampering	❌ Not run — needs SCM/CI	✅ Full
Compliance	❌ Not run — needs SCM/CI posture	✅ Full
SCA (dependency CVEs)	❌ Not run — needs Xygeni's vuln database	✅ Full
AI Security (early access)	Local / self-hosted model only	✅ Full

Legend: ✅ Full — runs completely · ⚠️ degraded — runs with offline gaps · ❌ not run — unavailable in that mode.

SCA requires no-upload. Software Composition Analysis correlates your dependencies against the Xygeni vulnerability database, so it runs only in no-upload mode. Under isolated/filtered, SCA and the other wholesale-online scans (SuspectDeps, Code Tampering, Compliance) are skipped up front with a single notice. Under no-upload every scan runs — only the upload of findings is withheld, and reports stay encrypted.

Enforcing a policy offline (optional)

Detector policy and CI/CD gating work without the server:

• Guardrails / --fail-on. Local guardrails — --fail-on 'critical', --fail-on 'file:my.xyflow', or inline expressions — run offline and produce a pass/fail exit code from the same counts shown on the console. Server-reference forms (--fail-on '#name', --audit-project) are not available offline.

• Detector policy. Apply an exported policy with --policy <dir> (one <scantype>.json per scan type). Export it on a connected host from a named server policy:

  xygeni util airgap policy-export --policy-name "My Policy" -o ./policy

  Carry the ./policy directory into the enclave and pass it with --policy ./policy. Re-export after upgrading the scanner so newly-shipped detectors are not left disabled.