f98cea3bcf
- Introduced AuthorityAdvisoryAiOptions and related classes for managing advisory AI configurations, including remote inference options and tenant-specific settings. - Added AuthorityApiLifecycleOptions to control API lifecycle settings, including legacy OAuth endpoint configurations. - Implemented validation and normalization methods for both advisory AI and API lifecycle options to ensure proper configuration. - Created AuthorityNotificationsOptions and its related classes for managing notification settings, including ack tokens, webhooks, and escalation options. - Developed IssuerDirectoryClient and related models for interacting with the issuer directory service, including caching mechanisms and HTTP client configurations. - Added support for dependency injection through ServiceCollectionExtensions for the Issuer Directory Client. - Updated project file to include necessary package references for the new Issuer Directory Client library.
73 lines
5.1 KiB
Markdown
73 lines
5.1 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, 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.
|
|
- **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.
|
|
|
|
## 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`
|