7503c19b8f
- Implemented comprehensive tests for verdict artifact generation to ensure deterministic outputs across various scenarios, including identical inputs, parallel execution, and change ordering. - Created helper methods for generating sample verdict inputs and computing canonical hashes. - Added tests to validate the stability of canonical hashes, proof spine ordering, and summary statistics. - Introduced a new PowerShell script to update SHA256 sums for files, ensuring accurate hash generation and file integrity checks.
78 lines
3.7 KiB
Markdown
78 lines
3.7 KiB
Markdown
# AirGap Importer
|
|
|
|
The AirGap Importer verifies and ingests offline bundles (mirror, bootstrap, evidence kits) into a sealed or constrained deployment. It fails closed by default: imports are rejected when verification fails, and failures are diagnosable offline.
|
|
|
|
This document describes importer behavior and its key building blocks. For bundle formats and operational workflow, see `docs/airgap/offline-bundle-format.md`, `docs/airgap/mirror-bundles.md`, and `docs/airgap/operations.md`.
|
|
|
|
## Responsibilities
|
|
|
|
- Verify bundle integrity and authenticity (DSSE signatures; optional TUF metadata where applicable).
|
|
- Enforce monotonicity (prevent version rollback unless explicitly force-activated with a recorded reason).
|
|
- Stage verified content into deterministic layouts (catalog + item repository + object-store paths).
|
|
- Quarantine failed bundles for forensic analysis with deterministic logs and metadata.
|
|
- Emit an audit trail for every dry-run and import attempt (success or failure).
|
|
|
|
## Verification pipeline (conceptual)
|
|
|
|
1. **Plan**: build an ordered list of validation/ingest steps for the bundle (`BundleImportPlanner`).
|
|
2. **Validate signatures**: verify DSSE envelopes and trusted key fingerprints.
|
|
3. **Validate metadata** (when present): verify TUF root/snapshot/timestamp consistency against trust roots.
|
|
4. **Compute deterministic roots**: compute a Merkle root over staged bundle items (stable ordering).
|
|
5. **Check monotonicity**: ensure the incoming bundle version is newer than the currently active version.
|
|
6. **Quarantine on failure**: preserve the bundle + verification log and emit a stable failure reason code.
|
|
7. **Commit**: write catalog/item entries and activation record; emit audit/timeline events.
|
|
|
|
The step order must remain stable; if steps change, treat it as a contract change and update CLI/UI guidance.
|
|
|
|
## Quarantine
|
|
|
|
When verification fails, the importer quarantines the bundle with enough information to debug offline.
|
|
|
|
Typical structure:
|
|
|
|
- `/updates/quarantine/<tenantId>/<timestamp>-<reason>-<id>/`
|
|
- `bundle.tar.zst` (original)
|
|
- `manifest.json` (if extracted)
|
|
- `verification.log` (deterministic, no machine-specific paths)
|
|
- `failure-reason.txt` (human-readable)
|
|
- `quarantine.json` (structured metadata: tenant, reason, timestamps, sizes, hashes)
|
|
|
|
Operational expectations:
|
|
|
|
- Quarantine is bounded: enforce per-tenant quota + TTL cleanup.
|
|
- Listing is deterministic: sort by `quarantined_at` then `quarantine_id` (ordinal).
|
|
|
|
## Version monotonicity
|
|
|
|
Rollback resistance is enforced via:
|
|
|
|
- A per-tenant version store (`IBundleVersionStore`) backed by Postgres in production.
|
|
- A monotonicity checker (`IVersionMonotonicityChecker`) that compares incoming bundle versions to the active version.
|
|
- Optional force-activate path requiring a human reason, stored alongside the activation record.
|
|
|
|
## Storage model
|
|
|
|
The importer writes deterministic metadata that other components can query:
|
|
|
|
- **Bundle catalog**: (tenant, bundle_id, digest, imported_at_utc, content paths).
|
|
- **Bundle items**: (tenant, bundle_id, path, digest, size).
|
|
|
|
For the logical schema and deterministic ordering rules, see `docs/airgap/bundle-repositories.md`.
|
|
|
|
## Telemetry and auditing
|
|
|
|
Minimum signals:
|
|
|
|
- Counters: imports attempted/succeeded/failed, dry-runs, quarantines created, monotonicity failures, force-activations.
|
|
- Structured logs with stable reason codes (e.g., `dsse_signature_invalid`, `tuf_root_invalid`, `merkle_mismatch`, `version_rollback_blocked`).
|
|
- Audit emission: include tenant, bundle_id, digest, operator identity, and whether sealed mode was active.
|
|
|
|
## References
|
|
|
|
- `docs/airgap/offline-bundle-format.md`
|
|
- `docs/airgap/mirror-bundles.md`
|
|
- `docs/airgap/bundle-repositories.md`
|
|
- `docs/airgap/operations.md`
|
|
- `docs/airgap/controller.md`
|
|
|