119 lines
4.0 KiB
Markdown
119 lines
4.0 KiB
Markdown
# 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.
|