# 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/](./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.Storage.Postgres` - PostgreSQL storage for snapshots
- `StellaOps.AirGap.Storage.Postgres.Tests` - Storage 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

## 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/`

## 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

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

### Bundle Import and Verification

```bash
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:

```bash
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](../binary-index/golden-corpus-layout.md)
- [Golden Corpus Maintenance](../binary-index/golden-corpus-maintenance.md)
- [Golden Corpus Operations Runbook](../../runbooks/golden-corpus-operations.md)

## 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.