git.stella-ops.org/docs/airgap/airgap-mode.md

Air-Gapped Mode Playbook

Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

Overview

Air-Gapped Mode is the supported operating profile for deployments with zero external egress. All inputs arrive via signed mirror bundles, and every surface (CLI, Console, APIs, schedulers, scanners) operates under sealed-network constraints while preserving Aggregation-Only Contract invariants.

• Primary components: Web Services API, Console, CLI, Orchestrator, Task Runner, Conselier (formerly Feedser), Excitor (formerly Vexer), Policy Engine, Findings Ledger, Export Center, Authority & Tenancy, Notifications, Observability & Forensics.
• Surfaces: offline bootstrap, mirror ingestion, deterministic jobs, offline advisories/VEX/policy packs/notifications, evidence exports.
• Dependencies: Export Center, Containerized Distribution, Authority-backed scopes & tenancy, Observability & Forensics, Policy Studio.

Guiding principles

1. Zero egress: all outbound network calls are disabled unless explicitly allowed. Any feature requiring online data must degrade gracefully with clear UX messaging.
2. Deterministic inputs: the platform accepts only signed Mirror Bundles (advisories, VEX, policy packs, vendor feeds, images, dashboards). Bundles carry provenance attestations and chain-of-custody manifests.
3. Auditable exchange: every import/export records provenance, signatures, and operator identity. Evidence bundles and reports remain verifiable offline.
4. Aggregation-Only Contract compliance: Conseiller and Excitor continue to aggregate without mutating source records, even when ingesting mirrored feeds.
5. Operator ergonomics: offline bootstrap, upgrade, and verification steps are reproducible and scripted.

Lifecycle & modes

Mode	Description	Tooling
Connected	Standard deployment with online feeds. Operators use Export Center to build mirror bundles for offline environments.	stella export bundle create --profile mirror:full
Staging mirror	Sealed host that fetches upstream feeds, runs validation, and signs mirror bundles.	Export Center, cosign, bundle validation scripts
Air-gapped	Production cluster with egress sealed, consuming validated bundles, issuing provenance for inward/outward transfers.	Mirror import CLI, sealed-mode runtime flags

Installation & bootstrap

1. Prepare mirror bundles (images, charts, advisories/VEX, policy packs, dashboards, telemetry configs).
2. Transfer bundles via approved media and validate signatures (cosign verify, bundle manifest hash).
3. Deploy platform using offline artefacts (helm install --set airgap.enabled=true), referencing local registry/object storage.

Updates

1. Staging host generates incremental bundles (mirror delta) with provenance.
2. Offline site imports bundles via the CLI (stella airgap import --bundle) and records chain-of-custody.
3. Scheduler triggers replay jobs with deterministic timelines; results remain reproducible across imports.

Component responsibilities

Component	Offline duties
Export Center	Produce full/delta mirror bundles, signed manifests, provenance attestations.
Authority & Tenancy	Provide offline scope enforcement, short-lived tokens, revocation via local CRLs.
Conseiller / Excitor	Ingest mirrored advisories/VEX, enforce AOC, versioned observations.
Policy Engine & Findings Ledger	Replay evaluations using offline feeds, emit explain traces, support sealed-mode hints.
Notifications	Deliver locally via approved channels (email relay, webhook proxies) or queue for manual export.
Observability	Collect metrics/logs/traces locally, generate forensic bundles for external analysis.

Operational guardrails

• Network policy: enforce allowlists (airgap.egressAllowlist=[]). Any unexpected outbound request raises an alert.
• Bundle validation: double-sign manifests (bundle signer + site-specific cosign key); reject on mismatch.
• Time synchronization: rely on local NTP or manual clock audits; many signatures require monotonic time.
• Key rotation: plan for offline key ceremonies; Export Center and Authority document rotation playbooks.
• Authority scopes: enforce airgap:status:read, airgap:import, and airgap:seal via tenant-scoped roles; require operator reason/ticket metadata for sealing.
• Incident response: maintain scripts for replaying imports, regenerating manifests, and exporting forensic data without egress.
• EgressPolicy facade: all services route outbound calls through StellaOps.AirGap.Policy. In sealed mode EgressPolicy enforces the airgap.egressAllowlist, auto-permits loopback targets, and raises AIRGAP_EGRESS_BLOCKED exceptions with remediation text (add host to allowlist or coordinate break-glass). Unsealed mode logs intents but does not block, giving operators a single toggle for rehearsals. Task Runner now feeds every run.egress declaration and runtime network hint into the shared policy during planning, preventing sealed-mode packs from executing unless destinations are declared and allow-listed.
• Linting/CI: enable the StellaOps.AirGap.Policy.Analyzers package in solution-level analyzers so CI fails on raw HttpClient usage. The analyzer emits AIRGAP001 and the bundled code fix rewrites to EgressHttpClientFactory.Create(...); treat analyzer warnings as errors in sealed-mode pipelines.

Testing & verification

• Integration tests mimic offline installs by running with AIRGAP_ENABLED=true in CI.
• Mirror bundles include validation scripts to compare hash manifests across staging and production.
• Sealed-mode smoke tests ensure services fail closed when attempting egress.

References

• Export workflows: docs/modules/export-center/overview.md
• Policy sealed-mode hints: docs/policy/overview.md
• Observability forensic bundles: docs/modules/telemetry/architecture.md
• Runtime posture enforcement: docs/modules/zastava/operations/runtime.md