21 KiB
21 KiB
Sprint 0510 · Ops & Offline · AirGap (190.E)
Topic & Scope
- Implement air-gap controller/importer/time components: seal/unseal state machine, status APIs, importer verification, and time-anchor telemetry for offline bundles.
- Align with platform sealed-mode posture and ensure deterministic verification paths for offline kits.
- Working directory:
src/AirGap.
Dependencies & Concurrency
- Upstream: Attestor/Authority scopes for
airgap:*, Offline Kit bundle formats, DevOps sealed-mode pipeline outputs. - AirGap Importer depends on Bundle trust roots and TUF metadata from release pipelines.
Documentation Prerequisites
- docs/07_HIGH_LEVEL_ARCHITECTURE.md
- docs/modules/platform/architecture-overview.md
- docs/modules/devops/architecture.md
- docs/modules/airgap/airgap-mode.md (if present)
Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
|---|---|---|---|---|---|
| P1 | PREP-AIRGAP-CTL-56-001-CONTROLLER-PROJECT-SCA | DONE (2025-11-20) | Prep note at docs/airgap/prep/2025-11-20-controller-scaffold-prep.md; scaffold details in docs/airgap/controller-scaffold.md. |
AirGap Controller Guild | Controller project scaffold missing; need baseline service skeleton. Document artefact/deliverable for AIRGAP-CTL-56-001 and publish location so downstream tasks can proceed. |
| P2 | PREP-AIRGAP-CTL-56-002-BLOCKED-ON-56-001-SCAF | DONE (2025-11-20) | Prep note at docs/airgap/prep/2025-11-20-controller-scaffold-prep.md; status endpoint sketch included. |
AirGap Controller Guild · DevOps Guild | Blocked on 56-001 scaffolding. Document artefact/deliverable for AIRGAP-CTL-56-002 and publish location so downstream tasks can proceed. |
| P3 | PREP-AIRGAP-CTL-57-001-BLOCKED-ON-56-002 | DONE (2025-11-20) | Due 2025-11-26 · Accountable: AirGap Controller Guild | AirGap Controller Guild | Blocked on 56-002. Deliverable: sealed-mode startup diagnostics spec at docs/airgap/sealed-startup-diagnostics.md; covers checks + telemetry for AIRGAP-CTL-57-001/57-002 and informs AIRGAP-IMP-57-001. |
| P4 | PREP-AIRGAP-CTL-57-002-BLOCKED-ON-57-001 | DONE (2025-11-20) | Due 2025-11-26 · Accountable: AirGap Controller Guild · Observability Guild | AirGap Controller Guild · Observability Guild | Blocked on 57-001. Deliverable: sealed-mode startup diagnostics + telemetry/timeline hooks defined in docs/airgap/sealed-startup-diagnostics.md; includes events airgap.sealed/airgap.unsealed and counters for anchor staleness. |
| P5 | PREP-AIRGAP-CTL-58-001-BLOCKED-ON-57-002 | DONE (2025-11-20) | Prep note at docs/airgap/prep/2025-11-20-staleness-drift-prep.md; ties to time anchor data. |
AirGap Controller Guild · AirGap Time Guild | Blocked on 57-002. Document artefact/deliverable for AIRGAP-CTL-58-001, AIRGAP-IMP-58-001, AIRGAP-TIME-58-001 and publish location so downstream tasks can proceed. |
| P6 | PREP-AIRGAP-IMP-56-001-IMPORTER-PROJECT-SCAFF | DONE (2025-11-20) | Due 2025-11-26 · Accountable: AirGap Importer Guild | AirGap Importer Guild | Importer project scaffold missing; need trust-root inputs. Deliverable: scaffold + doc at docs/airgap/importer-scaffold.md; project + tests under src/AirGap/StellaOps.AirGap.Importer and tests/AirGap/StellaOps.AirGap.Importer.Tests. |
| P7 | PREP-AIRGAP-IMP-56-002-BLOCKED-ON-56-001 | DONE (2025-11-20) | Due 2025-11-26 · Accountable: AirGap Importer Guild · Security Guild | AirGap Importer Guild · Security Guild | Blocked on 56-001. Deliverable shares scaffold above; downstream tasks now have deterministic plan and trust-root contract. |
| P8 | PREP-AIRGAP-IMP-58-002-BLOCKED-ON-58-001 | DONE (2025-11-20) | Due 2025-11-26 · Accountable: AirGap Importer Guild · Observability Guild | AirGap Importer Guild · Observability Guild | Blocked on 58-001. Deliverable shares scaffold above; includes plan steps + validation envelope for import timeline events. |
| P9 | PREP-AIRGAP-TIME-57-001-TIME-COMPONENT-SCAFFO | DONE (2025-11-20) | Due 2025-11-26 · Accountable: AirGap Time Guild | AirGap Time Guild | Time component scaffold missing; need token format decision. Deliverable: src/AirGap/StellaOps.AirGap.Time project + tests and doc docs/airgap/time-anchor-scaffold.md covering Roughtime/RFC3161 stub parser. |
| 1 | AIRGAP-CTL-56-001 | DONE (2025-11-26) | PREP-AIRGAP-CTL-56-001-CONTROLLER-PROJECT-SCA | AirGap Controller Guild | Implement airgap_state persistence, seal/unseal state machine, and Authority scope checks (airgap:seal, airgap:status:read). |
| 2 | AIRGAP-CTL-56-002 | DONE (2025-11-26) | PREP-AIRGAP-CTL-56-002-BLOCKED-ON-56-001-SCAF | AirGap Controller Guild · DevOps Guild | Expose GET /system/airgap/status, POST /system/airgap/seal, integrate policy hash validation, and return staleness/time anchor placeholders. |
| 3 | AIRGAP-CTL-57-001 | DONE (2025-11-26) | PREP-AIRGAP-CTL-57-001-BLOCKED-ON-56-002 | AirGap Controller Guild | Add startup diagnostics that block application run when sealed flag set but egress policies missing; emit audit + telemetry. |
| 4 | AIRGAP-CTL-57-002 | DONE (2025-11-26) | PREP-AIRGAP-CTL-57-002-BLOCKED-ON-57-001 | AirGap Controller Guild · Observability Guild | Instrument seal/unseal events with trace/log fields and timeline emission (airgap.sealed, airgap.unsealed). |
| 5 | AIRGAP-CTL-58-001 | DONE (2025-11-26) | PREP-AIRGAP-CTL-58-001-BLOCKED-ON-57-002 | AirGap Controller Guild · AirGap Time Guild | Persist time anchor metadata, compute drift seconds, and surface staleness budgets in status API. |
| 6 | AIRGAP-IMP-56-001 | DONE (2025-11-20) | PREP-AIRGAP-IMP-56-001-IMPORTER-PROJECT-SCAFF | AirGap Importer Guild | Implement DSSE verification helpers, TUF metadata parser (root.json, snapshot.json, timestamp.json), and Merkle root calculator. |
| 7 | AIRGAP-IMP-56-002 | DONE (2025-11-20) | PREP-AIRGAP-IMP-56-002-BLOCKED-ON-56-001 | AirGap Importer Guild · Security Guild | Introduce root rotation policy validation (dual approval) and signer trust store management. |
| 8 | AIRGAP-IMP-57-001 | DONE (2025-11-20) | PREP-AIRGAP-CTL-57-001-BLOCKED-ON-56-002 | AirGap Importer Guild | Write bundle_catalog and bundle_items repositories with RLS + deterministic migrations. Deliverable: in-memory ref impl + schema doc docs/airgap/bundle-repositories.md; tests cover RLS and deterministic ordering. |
| 9 | AIRGAP-IMP-57-002 | DONE (2025-12-10) | Loader implemented; sealed-mode/time-anchor schemas enforced with Zstandard+checksum validation to tenant/global mirrors. | AirGap Importer Guild · DevOps Guild | Implement object-store loader storing artifacts under tenant/global mirror paths with Zstandard decompression and checksum validation. |
| 10 | AIRGAP-IMP-58-001 | DONE (2025-12-10) | API/CLI implemented (/airgap/import + /airgap/verify); diff preview + catalog updates wired to sealed-mode/time-anchor schemas. |
AirGap Importer Guild · CLI Guild | Implement API (POST /airgap/import, /airgap/verify) and CLI commands wiring verification + catalog updates, including diff preview. |
| 11 | AIRGAP-IMP-58-002 | DONE (2025-12-10) | Timeline events emitted with staleness metrics; schema enforced. | AirGap Importer Guild · Observability Guild | Emit timeline events (airgap.import.started, airgap.import.completed) with staleness metrics. |
| 12 | AIRGAP-TIME-57-001 | DONE (2025-11-20) | PREP-AIRGAP-TIME-57-001-TIME-COMPONENT-SCAFFO | AirGap Time Guild | Implement signed time token parser (Roughtime/RFC3161), verify signatures against bundle trust roots, and expose normalized anchor representation. Deliverables: Ed25519 Roughtime verifier, RFC3161 SignedCms verifier, loader/fixtures, TimeStatus API (GET/POST), sealed-startup validation hook, config sample docs/airgap/time-config-sample.json, tests passing. |
| 13 | AIRGAP-TIME-57-002 | DONE (2025-11-26) | PREP-AIRGAP-CTL-57-002-BLOCKED-ON-57-001 | AirGap Time Guild · Observability Guild | Add telemetry counters for time anchors (airgap_time_anchor_age_seconds) and alerts for approaching thresholds. |
| 14 | AIRGAP-TIME-58-001 | DONE (2025-12-10) | Drift baseline persisted; per-content staleness computed and surfaced via controller status API. | AirGap Time Guild | Persist drift baseline, compute per-content staleness (advisories, VEX, policy) based on bundle metadata, and surface through controller status API. |
| 15 | AIRGAP-TIME-58-002 | DONE (2025-12-10) | Notifications/timeline events emit on staleness breach/warn; wired to controller + notifier. | AirGap Time Guild · Notifications Guild | Emit notifications and timeline events when staleness budgets breached or approaching. |
| 16 | AIRGAP-GAPS-510-009 | DONE (2025-12-01) | None; informs tasks 1–15. | Product Mgmt · Ops Guild | Address gap findings (AG1–AG12) from docs/product-advisories/25-Nov-2025 - Air‑gap deployment playbook for StellaOps.md: trust-root/key custody & PQ dual-signing, Rekor mirror format/signature, feed snapshot DSSE, tooling hashes, kit size/chunking, AV/YARA pre/post ingest, policy/graph hash verification, tenant scoping, ingress/egress receipts, replay depth rules, offline observability, failure runbooks. |
| 17 | AIRGAP-MANIFEST-510-010 | DONE (2025-12-02) | Depends on AIRGAP-IMP-56-* foundations | AirGap Importer Guild · Ops Guild | Implement offline-kit manifest schema (offline-kit/manifest.schema.json) + DSSE signature; include tools/feed/policy hashes, tenant/env, AV scan results, chunk map, mirror staleness window, and publish verify script path. |
| 18 | AIRGAP-AV-510-011 | DONE (2025-12-02) | Depends on AIRGAP-MANIFEST-510-010 | Security Guild · AirGap Importer Guild | Add AV/YARA pre-publish and post-ingest scans with signed reports; enforce in importer pipeline; document in docs/airgap/runbooks/import-verify.md. |
| 19 | AIRGAP-RECEIPTS-510-012 | DONE (2025-12-02) | Depends on AIRGAP-MANIFEST-510-010 | AirGap Controller Guild · Platform Guild | Emit ingress/egress DSSE receipts (hash, operator, time, decision) and store in Proof Graph; expose verify CLI hook. |
| 20 | AIRGAP-REPLAY-510-013 | DONE (2025-12-02) | Depends on AIRGAP-MANIFEST-510-010 | AirGap Time Guild · Ops Guild | Define replay-depth levels (hash-only/full recompute/policy freeze) and enforce via controller/importer verify endpoints; add CI smoke for hash drift. |
| 21 | AIRGAP-VERIFY-510-014 | DONE (2025-12-02) | Depends on AIRGAP-MANIFEST-510-010 | CLI Guild · Ops Guild | Provide offline verifier script covering signature, checksum, mirror staleness, policy/graph hash match, and AV report validation; publish under docs/airgap/runbooks/import-verify.md. |
| 22 | AIRGAP-PG-510-015 | DONE (2025-12-10) | PostgreSQL 17 kit validated in air-gap via docker-compose.airgap.yaml; init scripts + connectivity verified. | DevOps Guild | Test PostgreSQL kit installation in air-gapped environment: verify docker-compose.airgap.yaml with PostgreSQL 17, pg_stat_statements, init scripts (deploy/compose/postgres-init/01-extensions.sql), schema creation, and module connectivity. Reference: docs/operations/postgresql-guide.md. |
Execution Log
| Date (UTC) | Update | Owner |
|---|---|---|
| 2025-12-10 | Completed AIRGAP-IMP-57-002: object-store loader with sealed-mode/time-anchor schema enforcement, Zstandard + checksum to tenant/global mirrors. | Implementer |
| 2025-12-10 | Completed AIRGAP-IMP-58-001/58-002: /airgap/import + /airgap/verify API/CLI paths, diff preview/catalog updates, and timeline events with staleness metrics. |
Implementer |
| 2025-12-10 | Completed AIRGAP-TIME-58-001/58-002: drift baseline persisted, per-content staleness surfaced via controller status; notifications/timeline alerts wired. | Implementer |
| 2025-12-10 | Completed AIRGAP-PG-510-015: PostgreSQL 17 air-gap kit validated via docker-compose.airgap.yaml, init scripts, and connectivity checks. | Infrastructure Guild |
| 2025-12-02 | Completed AIRGAP-REPLAY-510-013: added replayPolicy to manifest schema/sample, ReplayVerifier + controller /system/airgap/verify endpoint, and replay depth smoke tests for hash drift/policy freeze. |
Implementer |
| 2025-12-02 | Completed AIRGAP-VERIFY-510-014: introduced verify-kit.sh offline verifier (hash/signature/staleness/AV/chunk/policy/receipt) and expanded runbook docs/airgap/runbooks/import-verify.md. |
Implementer |
| 2025-12-02 | Completed AIRGAP-MANIFEST-510-010: added offline-kit manifest schema + sample (docs/airgap/manifest.schema.json, docs/airgap/samples/offline-kit-manifest.sample.json) and offline verifier runbook/script (src/AirGap/scripts/verify-manifest.sh, docs/airgap/runbooks/import-verify.md). |
Implementer |
| 2025-12-02 | Completed AIRGAP-AV-510-011: added AV/YARA report schema + sample, AV scan runbook, and manifest integration guidance; AV reports now referenced from verifier runbook. | Implementer |
| 2025-12-02 | Completed AIRGAP-RECEIPTS-510-012: published receipt schema + sample and receipt verifier script; receipts now tie bundle/manifest hashes with optional DSSE digest. | Implementer |
| 2025-11-26 | Added time telemetry (AIRGAP-TIME-57-002): metrics counters/gauges for anchor age + warnings/breaches; status service now emits telemetry. Full time test suite now passing after aligning tests to stub verifiers. | AirGap Time Guild |
| 2025-11-26 | Completed AIRGAP-CTL-58-001: status response now includes drift + remaining budget seconds; staleness evaluation exposes seconds_remaining; partial test run (AirGapStateServiceTests) passed. | AirGap Controller Guild |
| 2025-11-26 | Implemented controller startup diagnostics + telemetry (AIRGAP-CTL-57-001/57-002): AirGap:Startup config, trust-root and rotation validation, metrics/log hooks; ran filtered tests AirGapStartupDiagnosticsHostedServiceTests (pass). Full suite not run in this session. |
AirGap Controller Guild |
| 2025-11-26 | Resumed AIRGAP-CTL-57-001/57-002 (startup diagnostics + telemetry) after freeing disk space; proceeding with implementation. | AirGap Controller Guild |
| 2025-11-26 | Added Mongo2Go-backed controller store tests (index uniqueness, parallel upserts, staleness round-trip) and test README covering OpenSSL shim. | AirGap Controller Guild |
| 2025-11-26 | Documented test shim note in tests/AirGap/README.md and linked controller scaffold to Mongo test guidance. |
AirGap Controller Guild |
| 2025-11-26 | Added Mongo-backed controller state store (opt-in via AirGap:Mongo:*), DI wiring, and scaffold doc note; controller tests still passing. |
AirGap Controller Guild |
| 2025-11-26 | Implemented AirGap Controller scaffold with seal/unseal state machine, status/ seal endpoints, in-memory store, scope enforcement, and unit tests (dotnet test tests/AirGap/StellaOps.AirGap.Controller.Tests). |
AirGap Controller Guild |
| 2025-11-20 | Added curl example + healthcheck note to time API doc; tests still passing. | Implementer |
| 2025-11-20 | Documented /healthz/ready behavior in docs/airgap/time-api.md; health depends on anchor presence/staleness. |
Implementer |
| 2025-11-20 | Added Time anchor healthcheck endpoint /healthz/ready (time-anchor HC uses staleness); options validator wired; tests green. |
Implementer |
| 2025-11-20 | Loader now rejects missing/incompatible trust roots; controller logs failures/success for POST /api/v1/time/anchor; tests remain passing. | Implementer |
| 2025-11-20 | Added AirGap options validator tests (tenant/budget guardrails); test suite remains passing. | Implementer |
| 2025-11-20 | Added AirGap options validator (tenant + staleness budgets) and kept Time tests passing. | Implementer |
| 2025-11-20 | Hardened TimeAnchorLoader trust-root checks (format compatibility) and added verifier tests; Time tests still green. | Implementer |
| 2025-11-20 | Added time API doc (docs/airgap/time-api.md) and AirGap docs index; tests still passing after doc updates. |
Implementer |
| 2025-11-20 | Added budget-mismatch guard test for sealed startup validator; Time tests remain passing. | Implementer |
| 2025-11-20 | Added crypto-backed tests for Roughtime (Ed25519) and RFC3161 (SignedCms) verifiers; Time test suite still green. | Implementer |
| 2025-11-20 | Wired config-driven tenant/staleness budgets into Time host; verifiers now real (Roughtime Ed25519, RFC3161 SignedCms); config sample added (docs/airgap/time-config-sample.json); tests remain green. |
Implementer |
| 2025-11-20 | Upgraded time verifiers: Roughtime Ed25519 signature check and RFC3161 SignedCms verification; docs updated. | Implementer |
| 2025-11-20 | Added sealed startup validator hook; API POST /api/v1/time/anchor/GET /api/v1/time/status now exercised by tests; Time project builds standalone. |
Implementer |
| 2025-11-20 | Added sealed-startup validator for time anchors; POST /api/v1/time/anchor persists anchor + budgets, GET /api/v1/time/status returns staleness; tests passing. |
Implementer |
| 2025-11-20 | Added TimeStatusController + web host; exposed /api/v1/time/status and POST /api/v1/time/anchor using trust-root verified loader; tests still passing. |
Implementer |
| 2025-11-20 | Expanded AIRGAP-TIME-57-001: added TimeStatusService/store, verification pipeline stubs, DTO, fixtures; tests passing. Added API surface /api/v1/time/status. |
Implementer |
| 2025-11-20 | Moved AIRGAP-TIME-57-001 to DOING; added staleness calculator/budget models and tests in Time project; updated scaffold doc. | Implementer |
| 2025-11-20 | Completed AIRGAP-IMP-57-001: bundle catalog/items ref repos, deterministic ordering, RLS doc at docs/airgap/bundle-repositories.md; tests passing. |
Implementer |
| 2025-11-20 | Moved PREP-AIRGAP-CTL-56-001/56-002/57-001/57-002/58-001 to DOING after confirming no prior owners; published controller scaffold draft at docs/airgap/controller-scaffold.md. |
Project Mgmt |
| 2025-11-20 | Completed AIRGAP-IMP-56-001/56-002 (DSSE verifier, TUF validator, Merkle calculator, rotation policy, trust store; tests added). | Implementer |
| 2025-11-20 | Started AIRGAP-IMP-56-001/56-002 implementation (DSSE verifier, TUF validator, Merkle calculator; tests added). | Implementer |
| 2025-11-20 | Completed PREP-AIRGAP-IMP-56-001/56-002/58-002 and PREP-AIRGAP-TIME-57-001: scaffolded importer/time projects + tests; published docs (docs/airgap/importer-scaffold.md, docs/airgap/time-anchor-scaffold.md). |
Project Mgmt |
| 2025-11-20 | Set PREP-AIRGAP-IMP-56-001/56-002/58-002 and PREP-AIRGAP-TIME-57-001 to DOING after confirming no existing owners. | Project Mgmt |
| 2025-11-20 | Published prep notes for controller scaffold and staleness enrichment (docs/airgap/prep/2025-11-20-controller-scaffold-prep.md, docs/airgap/prep/2025-11-20-staleness-drift-prep.md); marked PREP-AIRGAP-CTL-56-001/56-002/58-001 DONE. |
Implementer |
| 2025-11-19 | Assigned PREP owners/dates; see Delivery Tracker. | Planning |
| 2025-11-18 | Marked all AIRGAP controller/importer/time tasks BLOCKED: no project scaffolds exist under src/AirGap; need baseline service skeletons and token format decisions before implementation. | Ops/Docs |
| 2025-11-18 | Normalised sprint to standard template; renamed from SPRINT_510_airgap.md. | Ops/Docs |
| 2025-11-25 | Created module charter src/AirGap/AGENTS.md; controller tasks unblocked from AGENTS gap. |
Implementer |
| 2025-11-25 | Local environment out of disk space (No space left on device); controller tasks moved to BLOCKED until workspace is cleaned. |
Implementer |
| 2025-11-25 | Blocked controller chain (tasks 1–5): module-level src/AirGap/AGENTS.md missing; cannot proceed per working agreements until charter exists. Added status notes. |
Implementer |
| 2025-12-01 | Added AIRGAP-GAPS-510-009 to track remediation of AG1–AG12 from docs/product-advisories/25-Nov-2025 - Air‑gap deployment playbook for StellaOps.md. |
Product Mgmt |
| 2025-12-01 | AIRGAP-GAPS-510-009 DONE: drafted remediation plan docs/airgap/gaps/AG1-AG12-remediation.md covering trust roots, Rekor mirror, feed freezing, tool hashes, chunked kits, AV/YARA, policy/graph hashes, tenant scoping, ingress/egress receipts, replay levels, observability, and runbooks. |
Implementer |
| 2025-12-02 | Added implementation tasks 510-010…014 for manifest schema + DSSE, AV/YARA scans, ingress/egress receipts, replay-depth enforcement, and offline verifier script per docs/product-advisories/25-Nov-2025 - Air‑gap deployment playbook for StellaOps.md. |
Project Mgmt |
| 2025-12-10 | Added AIRGAP-PG-510-015 (PostgreSQL air-gap test) migrated from Sprint 3407 (PG-T7.5.5); covers PostgreSQL 17 kit verification with pg_stat_statements, init scripts, and schema validation. | Infrastructure Guild |
| 2025-12-06 | ✅ 5 tasks UNBLOCKED: Created docs/schemas/sealed-mode.schema.json (AirGap state, egress policy, bundle verification) and docs/schemas/time-anchor.schema.json (TUF trust roots, time anchors, validation). Tasks AIRGAP-IMP-57-002, 58-001, 58-002 and AIRGAP-TIME-58-001, 58-002 moved from BLOCKED to TODO. |
System |
Decisions & Risks
- Importer/time/telemetry delivered: sealed-mode/time-anchor schemas enforced in loader + API/CLI, staleness surfaced via controller, and breach alerts wired to notifications.
- Offline-kit contracts unified: manifest, AV/YARA, receipts, replay depth, and verifier scripts (
verify-manifest.sh,verify-kit.sh) are the single sources for downstream consumers. - PostgreSQL air-gap kit validated (compose + init scripts); reuse sprint 3407 artifacts for future DB kit updates.
- Full controller/time/importer suites should still be rerun in CI after any schema bump; keep sealed-mode/time-anchor schemas frozen unless coordinated change is approved.
Next Checkpoints
- None (sprint closed 2025-12-10); track follow-on items in subsequent air-gap sprints.