git.stella-ops.org/docs/modules/airgap/README.md

AirGap

Status: Implemented Source: src/AirGap/ Owner: Platform Team

Note: This is the module dossier with architecture and implementation details. For operational guides and workflows, see docs/modules/airgap/guides/.

Purpose

AirGap manages sealed knowledge snapshot export and import for offline/air-gapped deployments. Provides time-anchored snapshots with staleness policies, deterministic bundle creation, and secure import validation for complete offline operation.

Components

Services:

• StellaOps.AirGap.Controller - Snapshot orchestration and staleness enforcement
• StellaOps.AirGap.Importer - Import validation and bundle ingestion

Libraries:

• StellaOps.AirGap.Policy - Staleness policy evaluation
• StellaOps.AirGap.Time - Time anchor validation and trust
• StellaOps.AirGap.Persistence - PostgreSQL persistence (EF Core v10)
• StellaOps.AirGap.Persistence.Tests - Persistence integration tests

Configuration

See etc/airgap.yaml.sample for configuration options.

Key settings:

• Staleness policy (maxAgeHours, warnAgeHours, staleAction)
• Time anchor requirements (requireTimeAnchor)
• Per-content staleness budgets (advisories, VEX, packages, mitigations)
• PostgreSQL connection (schema: airgap)
• Export/import paths and validation rules

EF Core Persistence Workflow

AirGap persistence now uses EF Core v10 models generated from the module migration schema.

Scaffold baseline context/models:

dotnet ef dbcontext scaffold \
  "Host=...;Port=...;Database=...;Username=...;Password=..." \
  Npgsql.EntityFrameworkCore.PostgreSQL \
  --project src/AirGap/__Libraries/StellaOps.AirGap.Persistence/StellaOps.AirGap.Persistence.csproj \
  --startup-project src/AirGap/__Libraries/StellaOps.AirGap.Persistence/StellaOps.AirGap.Persistence.csproj \
  --schema airgap \
  --table state \
  --table bundle_versions \
  --table bundle_version_history \
  --context-dir EfCore/Context \
  --context AirGapDbContext \
  --output-dir EfCore/Models \
  --namespace StellaOps.AirGap.Persistence.EfCore.Models \
  --context-namespace StellaOps.AirGap.Persistence.EfCore.Context \
  --use-database-names

Regenerate compiled model artifacts after model updates:

dotnet ef dbcontext optimize \
  --project src/AirGap/__Libraries/StellaOps.AirGap.Persistence/StellaOps.AirGap.Persistence.csproj \
  --startup-project src/AirGap/__Libraries/StellaOps.AirGap.Persistence/StellaOps.AirGap.Persistence.csproj \
  --context AirGapDbContext \
  --output-dir EfCore/CompiledModels \
  --namespace StellaOps.AirGap.Persistence.EfCore.CompiledModels

Runtime behavior:

• The static compiled model is used explicitly for the default airgap schema path.
• Non-default schemas (for integration fixtures) use runtime model construction to preserve schema isolation.

Bundle manifest (v2) additions

• canonicalManifestHash: sha256 of canonical JSON for deterministic verification.
• subject: sha256 (+ optional sha512) digest of the bundle target.
• timestamps: RFC3161/eIDAS timestamp entries with TSA chain/OCSP/CRL refs.
• rekorProofs: entry body/inclusion proof paths plus signed entry timestamp for offline verification.
• Inline artifacts (no path) are capped at 4 MiB; larger artifacts are written under artifacts/.

Dependencies

• PostgreSQL (schema: airgap)
• Authority (authentication)
• ExportCenter (bundle creation)
• Mirror (snapshot sources)
• All data modules (Concelier, VexHub, SbomService, etc.)

Related Documentation

• Operations: ./operations/ (if exists)
• Offline Kit: ../../OFFLINE_KIT.md
• Mirror: ../mirror/
• ExportCenter: ../export-center/
• Promotion Rekor tile runbook: ./guides/promotion-rekor-tile-verification.md

Evidence Bundles for Air-Gapped Verification

The AirGap module supports golden corpus evidence bundles for offline verification of patch provenance. These bundles enable auditors to verify security patch status without network access.

Bundle Contents

Evidence bundles follow the OCI format and contain:

• Pre/post binaries with debug symbols
• Canonical SBOM for each binary
• DSSE delta-sig predicate proving patch status
• Build provenance (if available from buildinfo)
• RFC 3161 timestamps for each signed artifact
• Validation run results and KPIs

Bundle Export

stella groundtruth bundle export \
  --packages openssl,zlib,glibc \
  --distros debian,fedora \
  --output symbol-bundle.tar.gz \
  --sign-with cosign

Bundle Import and Verification

stella groundtruth bundle import \
  --input symbol-bundle.tar.gz \
  --verify-signature \
  --trusted-keys /etc/stellaops/trusted-keys.pub \
  --output verification-report.md

Standalone Verifier

For air-gapped environments without the full Stella Ops stack, use the standalone verifier:

stella-verifier verify \
  --bundle evidence-bundle.oci.tar \
  --trusted-keys trusted-keys.pub \
  --trust-profile eu-eidas.trustprofile.json \
  --output report.json

Exit codes:

• 0: All verifications passed
• 1: One or more verifications failed
• 2: Invalid input or configuration error

Related Documentation

• Golden Corpus Layout
• Golden Corpus Maintenance
• Golden Corpus Operations Runbook

Current Status

Implemented with Controller for snapshot export and Importer for secure ingestion. Staleness policies enforce time-bound validity. Integrated with ExportCenter for bundle packaging and all data modules for content export/import.