Skip to content

Air-gapped units and bundles

An air-gapped unit cannot reach the Affectra API. Its collector writes each report as a bundle, a file in an outbox directory. You carry the files to a place that is online and import them. In the app these units are shown with the delivery Bundle.

Install the collector on the unit, but set the outbox instead of the API in /etc/affectra/collector.env:

Terminal window
AFFECTRA_TENANT=acme
AFFECTRA_COLLECTOR_ARGS=--out /var/lib/affectra/outbox

Every run writes one file named <unit id>-<number>.json. The collector writes a hidden temporary file first and renames it when it is complete, so a courier never picks up half a file. A file whose name starts with a dot is not finished: leave it.

The bundle names the tenant it was collected for. Affectra refuses to import it into another organization.

Copy the files from /var/lib/affectra/outbox/ to removable media. Delete the copies on the unit once you have them, or the outbox grows with every run. The files list the packages of the unit, so treat the media like the unit itself.

Send each bundle to the API as one request to POST /v1/reports, with an API key of your organization. Keep the key in an environment variable, not on the command line:

Terminal window
export AFFECTRA_TOKEN="exk_example_not_a_real_key"
for f in bundles/*.json; do
curl --fail --silent --show-error \
--header "Authorization: Bearer $AFFECTRA_TOKEN" \
--header "Content-Type: application/json" \
--data-binary "@$f" \
https://api.example.com/v1/reports
done

Use the API address of your Affectra installation. Imported bundles use the same rate limits as online collectors, so import tooling should:

  • send batches no larger than the burst of your organization, and pace them below its rate, so that online collectors keep room;
  • when the API answers 429 Too Many Requests, wait for the time in Retry-After, then continue where you stopped. Never retry in a tight loop;
  • when one unit has many bundles, such as a site that is visited rarely, send only the newest few. The newest report wins, and older ones only use up the unit’s hourly budget.

A 403 means the bundle names another organization. It is not a rate limit, so do not retry it.

A unit’s data is only as fresh as the last import. When you check a vulnerability under Fleet lookup, Affectra tells you how many of the affected units were reported through offline bundles, so you know which results may be out of date.