stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
7b5bdcf4d3bee4e6f398d0226ba8cd3c2754e07a
git.stella-ops.org/docs/airgap/airgap-mode.md
master 7b5bdcf4d3 feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules 
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes.
- Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes.
- Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables.
- Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
2025-10-30 00:09:39 +02:00

4.9 KiB
Raw Blame History

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, Conseiller (Feedser), Excitator (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 Excitator 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 / Excitator 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.
  • Incident response: maintain scripts for replaying imports, regenerating manifests, and exporting forensic data without egress.

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