The Unlock Ceremony

Read the encrypted reports produced by an airgapped scan through a small, metered online unlock — without the report body ever leaving the enclave.

An airgapped scan writes its reports encrypted (*.json.enc) and, per scan type, a tiny key request (*.unlock-req). The encrypted report stays inside the enclave; to read it you exchange only the key request for a key response with Xygeni, from a connected host. Think of it as a self-locking strongbox (the .enc report) and a sealed envelope only Xygeni can open (the .unlock-req).

The round-trip has three steps:

ISOLATED ENCLAVE                    SNEAKERNET            CONNECTED HOST
────────────────                    ──────────            ──────────────
xygeni --airgap-mode … sast …
  ├─ my-project.sast.json.enc  (stays in the enclave)
  └─ sast.unlock-req ──────────[ carry out ]──►  xygeni util airgap unlock sast.unlock-req
                                               → returns sast.unlock-resp
                               ◄──[ carry back ]──  (a few KB, no findings)
xygeni util airgap decrypt my-project.sast.json.enc sast.unlock-resp
  └─ my-project.sast.json      (plaintext, stays in the enclave)

1. Carry out the key requests

Copy only the *.unlock-req files out of the enclave on your approved media. Do not copy the *.enc reports — they never need to leave, and the plaintext is never exposed outside the air gap. The *.unlock-req files are a few KB and contain no findings.

2. Unlock on a connected host

On an internet-connected machine with the scanner installed, run:

xygeni util airgap unlock sast.unlock-req

This calls the Xygeni unlock service, which meters the scan, verifies your account is entitled and the request comes from an approved host, and returns a sast.unlock-resp. Authentication uses the Xygeni API token configured on the connected host (in xygeni.yml or XYGENI_TOKEN) — the isolated scan host never needs it.

The connected host does not need the air-gapped licence — only the scanner and your API token. You can pass several files or a glob; each is unlocked in one call:

xygeni util airgap unlock *.unlock-req

3. Decrypt back in the enclave

Carry the *.unlock-resp files back into the enclave and pair each encrypted report with its response:

xygeni util airgap decrypt my-project.sast.json.enc sast.unlock-resp

This recovers the report locally and writes the plaintext my-project.sast.json inside the enclave. Globs work here too, and files are matched by scan id:

xygeni util airgap decrypt *.json.enc *.unlock-resp

One-pass unlock-and-decrypt

If your workflow allows the reports to be decrypted outside the enclave (i.e. on the connected host itself), a single command does both steps:

xygeni util airgap unlock-decrypt *.json.enc *.unlock-req

unlock-decrypt writes the plaintext reports on the connected host, so the findings leave the enclave. Use it only when that is acceptable for your environment; otherwise keep the two steps separate and decrypt inside the air gap.

Metering

Each scan type is one metered unlock, regardless of how many report files it produced (JSON, SARIF, SBOM/CBOM all share one key). A grouped scan of N scan types produces N key requests and counts as N unlocks. Re-decrypting a report you have already unlocked is free — the key is reused; only a new scan needs a new unlock.

Command reference

Command	Where	What it does
xygeni util airgap fingerprint	any host	Prints the host fingerprint to send to Xygeni for licence binding.
xygeni util airgap unlock <*.unlock-req>	connected	Meters and exchanges key requests for key responses (*.unlock-resp).
xygeni util airgap decrypt <*.enc> <*.unlock-resp>	enclave	Decrypts reports locally using the key responses.
xygeni util airgap unlock-decrypt <*.enc> <*.unlock-req>	connected	Unlocks and decrypts in one step (plaintext leaves the enclave).

Troubleshooting

Symptom	Cause / fix
Licence has expired	Air-gapped licences are short-lived. Request a renewal from Xygeni and reinstall conf/xygeni.lic.
Host fingerprint … not approved	The host is not bound to the licence. Run xygeni util airgap fingerprint and send the value to Xygeni.
Unlock refused	The account is not entitled / over its allowance, the API token lacks access, or the request was tampered with. Check the token and account status.
Console shows counts but no findings	Expected under air-gap — the findings are in the encrypted report and appear only after you decrypt it.
reduced coverage - N host(s) skipped	Enrichment lookups were blocked. Add those hosts to conf/airgap-allowlist.txt and re-run in filtered mode, or use no-upload.
SCA produced nothing	SCA needs the Xygeni vulnerability database; run it under --airgap-mode no-upload.