Offline and Air-Gap Advisory Implementation Roadmap

Source advisory: 14-Dec-2025 — Offline and Air-Gap Technical Reference Document version: 1.0 Last updated: 2025-12-15

Executive summary

This document is the implementation roadmap for gaps identified between the 14-Dec-2025 Offline and Air-Gap Technical Reference advisory and the Stella Ops codebase. The work is organized into five sprints (0338–0342) spanning security-critical, high-priority, and enhancement-level improvements.

Status: planning artifact. Sprint IDs (0338–0342) and the source advisory live in the implementation-plan repo; the links below resolve there, not in the published docs tree.

Implementation Overview

Sprint Summary

Dependency Graph

            ┌─────────────────────────────────────────────┐
            │                                             │
            │   Sprint 0338: AirGap Importer Core (P0)   │
            │   - Monotonicity enforcement (G6)           │
            │   - Quarantine handling (G7)                │
            │                                             │
            └──────────────────┬──────────────────────────┘
                               │
         ┌─────────────────────┼─────────────────────┐
         │                     │                     │
         ▼                     ▼                     ▼
┌────────────────┐   ┌────────────────┐   ┌────────────────┐
│ Sprint 0339    │   │ Sprint 0340    │   │ Sprint 0341    │
│ CLI Commands   │   │ Scanner Config │   │ Observability  │
│ (P1)           │   │ (P2)           │   │ (P1-P2)        │
│ - G4           │   │ - G5           │   │ - G11-G14      │
└────────────────┘   └───────┬────────┘   └────────────────┘
                             │
                             ▼
                    ┌────────────────┐
                    │ Sprint 0342    │
                    │ Evidence Recon │
                    │ (P3)           │
                    │ - G10          │
                    └────────────────┘

Gap-to-Sprint Mapping

P0 - Critical (Must Implement First)

P1 - High Priority

P2 - Important

P3 - Lower Priority

Deferred (Not Implementing)

Technical Architecture

New Components

src/AirGap/
├── StellaOps.AirGap.Importer/
│   ├── Versioning/
│   │   ├── BundleVersion.cs                 # Sprint 0338
│   │   ├── IVersionMonotonicityChecker.cs   # Sprint 0338
│   │   └── IBundleVersionStore.cs           # Sprint 0338
│   ├── Quarantine/
│   │   ├── IQuarantineService.cs            # Sprint 0338
│   │   ├── FileSystemQuarantineService.cs   # Sprint 0338
│   │   └── QuarantineOptions.cs             # Sprint 0338
│   ├── Telemetry/
│   │   ├── OfflineKitMetrics.cs             # Sprint 0341
│   │   ├── OfflineKitLogFields.cs           # Sprint 0341
│   │   └── OfflineKitLogScopes.cs           # Sprint 0341
│   ├── Reconciliation/
│   │   ├── ArtifactIndex.cs                 # Sprint 0342
│   │   ├── EvidenceCollector.cs             # Sprint 0342
│   │   ├── DocumentNormalizer.cs            # Sprint 0342
│   │   ├── PrecedenceLattice.cs             # Sprint 0342
│   │   └── EvidenceGraphEmitter.cs          # Sprint 0342
src/Scanner/
├── __Libraries/StellaOps.Scanner.Core/
│   ├── Configuration/
│   │   ├── OfflineKitOptions.cs             # Sprint 0340
│   │   ├── TrustAnchorConfig.cs             # Sprint 0340
│   │   └── OfflineKitOptionsValidator.cs    # Sprint 0340
│   └── TrustAnchors/
│       ├── PurlPatternMatcher.cs            # Sprint 0340
│       ├── ITrustAnchorRegistry.cs          # Sprint 0340
│       └── TrustAnchorRegistry.cs           # Sprint 0340

src/Cli/
├── StellaOps.Cli/
│   ├── Commands/
│       ├── Offline/
│       │   ├── OfflineCommandGroup.cs       # Sprint 0339
│       │   ├── OfflineImportHandler.cs      # Sprint 0339
│       │   ├── OfflineStatusHandler.cs      # Sprint 0339
│       │   └── OfflineExitCodes.cs          # Sprint 0339
│       └── Verify/
│           └── VerifyOfflineHandler.cs      # Sprint 0339
│   └── Output/
│       └── OfflineKitReasonCodes.cs         # Sprint 0341

src/Authority/
├── __Libraries/StellaOps.Authority.Storage.Postgres/
│   └── Migrations/
│       └── 004_offline_kit_audit.sql        # Sprint 0341

Database Changes

Configuration Changes

CLI Commands

Metrics

Implementation Sequence

Phase 1: Foundation (Sprint 0338)

Duration: 1 sprint Focus: Security-critical infrastructure

1. Implement BundleVersion model with semver parsing
2. Create IVersionMonotonicityChecker and Postgres store
3. Integrate monotonicity check into ImportValidator
4. Implement --force-activate with audit trail
5. Create IQuarantineService and file-system implementation
6. Integrate quarantine into all import failure paths
7. Write comprehensive tests

Exit Criteria:

• [ ] Rollback attacks are prevented
• [ ] Failed bundles are preserved for investigation
• [ ] Force activation requires justification

Phase 2: Operator Experience (Sprints 0339, 0341)

Duration: 1-2 sprints (can parallelize) Focus: CLI and observability

Sprint 0339 (CLI):

1. Create offline command group
2. Implement offline import with all flags
3. Implement offline status with output formats
4. Implement verify offline with policy loading
5. Add exit code standardization
6. Write CLI integration tests

Sprint 0341 (Observability):

1. Add Prometheus metrics infrastructure
2. Implement offline kit metrics
3. Standardize structured logging fields
4. Complete error reason codes
5. Create audit schema migration
6. Implement audit repository and emitter
7. Create Grafana dashboard

Blockers: Prometheus /metrics endpoint hosting and audit emitter call-sites await an owning Offline Kit import/activation flow (POST /api/offline-kit/import).

Exit Criteria:

• [ ] Operators can import/verify kits via CLI
• [ ] Metrics are visible in Prometheus/Grafana
• [ ] All operations are auditable

Phase 3: Configuration (Sprint 0340)

Duration: 1 sprint Focus: Trust anchor management

1. Create OfflineKitOptions configuration class
2. Implement PURL pattern matcher
3. Create TrustAnchorRegistry with precedence resolution
4. Add options validation
5. Integrate trust anchors with DSSE verification
6. Update Helm chart values
7. Write configuration tests

Exit Criteria:

• [ ] Trust anchors configurable per ecosystem
• [ ] DSSE verification uses configured anchors
• [ ] Invalid configuration fails startup

Phase 4: Advanced Features (Sprint 0342)

Duration: 1-2 sprints Focus: Evidence reconciliation

1. Design artifact indexing
2. Implement evidence collection
3. Create document normalization
4. Implement VEX precedence lattice
5. Create evidence graph emitter
6. Integrate with CLI verify offline
7. Write golden-file determinism tests

Exit Criteria:

• [ ] Evidence reconciliation is deterministic
• [ ] VEX conflicts resolved by precedence
• [ ] Graph output is signed and verifiable

Testing Strategy

Unit Tests

• All new classes have corresponding test classes
• Mock dependencies for isolation
• Property-based tests for lattice operations

Integration Tests

• Testcontainers for PostgreSQL
• Full import → verification → audit flow
• CLI command execution tests

Determinism Tests

• Golden-file tests for evidence reconciliation
• Cross-platform validation (Windows, Linux, macOS)
• Reproducibility across runs

Security Tests

• Monotonicity bypass attempts
• Signature verification edge cases
• Trust anchor configuration validation

Documentation Updates

Risk Register

Success Metrics

References

• Air-Gap Mode Guide
• Importer
• Offline Kit Documentation
• 14-Dec-2025 Offline and Air-Gap Technical Reference (source advisory; tracked in the implementation-plan repo)