stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
7503c19b8ffa7f2891e5e672f9cfbf7efa4e2efb
git.stella-ops.org/docs/airgap/importer.md
StellaOps Bot 7503c19b8f Add determinism tests for verdict artifact generation and update SHA256 sums script 
- 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.
2025-12-24 02:17:34 +02:00

3.7 KiB
Raw Blame History

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