For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

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:

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:

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.

Last updated