2eb6852d34
Some checks are pending
Docs CI / lint-and-preview (push) Waiting to run
- Implement `SbomIngestServiceCollectionExtensionsTests` to verify the SBOM ingestion pipeline exports snapshots correctly. - Create `SbomIngestTransformerTests` to ensure the transformation produces expected nodes and edges, including deduplication of license nodes and normalization of timestamps. - Add `SbomSnapshotExporterTests` to test the export functionality for manifest, adjacency, nodes, and edges. - Introduce `VexOverlayTransformerTests` to validate the transformation of VEX nodes and edges. - Set up project file for the test project with necessary dependencies and configurations. - Include JSON fixture files for testing purposes.
77 lines
6.6 KiB
Markdown
77 lines
6.6 KiB
Markdown
# 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.
|
|
- **CLI guard:** the CLI now routes outbound HTTP through the shared egress policy. When sealed, commands that would dial external endpoints (for example, `scanner download` or remote `sources ingest` URIs) are refused with `AIRGAP_EGRESS_BLOCKED` messaging and remediation guidance instead of attempting the network call.
|
|
- **Observability exporters:** `StellaOps.Telemetry.Core` now binds OTLP exporters to the configured egress policy. When sealed, any collector endpoint that is not loopback or allow-listed is skipped at startup and a structured warning is written so operators see the remediation guidance without leaving sealed mode.
|
|
- **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`
|