stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/airgap/advisory-implementation-roadmap.md
master 5a480a3c2a
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
Export Center CI / export-ci (push) Has been cancelled
Details
Findings Ledger CI / build-test (push) Has been cancelled
Details
Findings Ledger CI / migration-validation (push) Has been cancelled
Details
Findings Ledger CI / generate-manifest (push) Has been cancelled
Details
Lighthouse CI / Lighthouse Audit (push) Has been cancelled
Details
Lighthouse CI / Axe Accessibility Audit (push) Has been cancelled
Details
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Details
Reachability Corpus Validation / validate-corpus (push) Has been cancelled
Details
Reachability Corpus Validation / validate-ground-truths (push) Has been cancelled
Details
Scanner Analyzers / Discover Analyzers (push) Has been cancelled
Details
Scanner Analyzers / Validate Test Fixtures (push) Has been cancelled
Details
Signals CI & Image / signals-ci (push) Has been cancelled
Details
Signals Reachability Scoring & Events / reachability-smoke (push) Has been cancelled
Details
Reachability Corpus Validation / determinism-check (push) Has been cancelled
Details
Scanner Analyzers / Build Analyzers (push) Has been cancelled
Details
Scanner Analyzers / Test Language Analyzers (push) Has been cancelled
Details
Scanner Analyzers / Verify Deterministic Output (push) Has been cancelled
Details
Signals Reachability Scoring & Events / sign-and-upload (push) Has been cancelled
Details
Add call graph fixtures for various languages and scenarios 
- Introduced `all-edge-reasons.json` to test edge resolution reasons in .NET.
- Added `all-visibility-levels.json` to validate method visibility levels in .NET.
- Created `dotnet-aspnetcore-minimal.json` for a minimal ASP.NET Core application.
- Included `go-gin-api.json` for a Go Gin API application structure.
- Added `java-spring-boot.json` for the Spring PetClinic application in Java.
- Introduced `legacy-no-schema.json` for legacy application structure without schema.
- Created `node-express-api.json` for an Express.js API application structure.
2025-12-16 10:44:24 +02:00

340 lines
13 KiB
Markdown
Raw Permalink Blame History

# 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 outlines the implementation roadmap for gaps identified between the 14-Dec-2025 Offline and Air-Gap Technical Reference advisory and the current StellaOps codebase. The implementation is organized into 5 sprints addressing security-critical, high-priority, and enhancement-level improvements.
---
## Implementation Overview
### Sprint Summary
| Sprint | Topic | Priority | Gaps | Effort | Dependencies |
|--------|-------|----------|------|--------|--------------|
| [0338](../implplan/SPRINT_0338_0001_0001_airgap_importer_core.md) | AirGap Importer Core | P0 | G6, G7 | Medium | None |
| [0339](../implplan/SPRINT_0339_0001_0001_cli_offline_commands.md) | CLI Offline Commands | P1 | G4 | Medium | 0338 |
| [0340](../implplan/SPRINT_0340_0001_0001_scanner_offline_config.md) | Scanner Offline Config | P2 | G5 | Medium | 0338 |
| [0341](../implplan/SPRINT_0341_0001_0001_observability_audit.md) | Observability & Audit | P1-P2 | G11-G14 | Medium | 0338 |
| [0342](../implplan/SPRINT_0342_0001_0001_evidence_reconciliation.md) | Evidence Reconciliation | P3 | G10 | High | 0338, 0340 |
### 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)
| Gap ID | Description | Sprint | Rationale |
|--------|-------------|--------|-----------|
| **G6** | Monotonicity enforcement | 0338 | Rollback prevention is security-critical; prevents replay attacks |
| **G7** | Quarantine directory handling | 0338 | Essential for forensic analysis of failed imports |
### P1 - High Priority
| Gap ID | Description | Sprint | Rationale |
|--------|-------------|--------|-----------|
| **G4** | CLI `offline` command group | 0339 | Primary operator interface; competitive parity |
| **G11** | Prometheus metrics | 0341 | Operational visibility in air-gap environments |
| **G13** | Error reason codes | 0341 | Automation and troubleshooting |
### P2 - Important
| Gap ID | Description | Sprint | Rationale |
|--------|-------------|--------|-----------|
| **G5** | Scanner offline config surface | 0340 | Enterprise trust anchor management |
| **G12** | Structured logging fields | 0341 | Log aggregation and correlation |
| **G14** | Audit schema enhancement | 0341 | Compliance and chain-of-custody |
### P3 - Lower Priority
| Gap ID | Description | Sprint | Rationale |
|--------|-------------|--------|-----------|
| **G10** | Evidence reconciliation algorithm | 0342 | Complex but valuable; VEX-first decisioning |
### Deferred (Not Implementing)
| Gap ID | Description | Rationale |
|--------|-------------|-----------|
| **G9** | YAML verification policy schema | Over-engineering; existing JSON/code config sufficient |
---
## 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
| Table | Schema | Sprint | Purpose |
|-------|--------|--------|---------|
| `airgap.bundle_versions` | New | 0338 | Track active bundle versions per tenant/type |
| `airgap.bundle_version_history` | New | 0338 | Version history for audit trail |
| `authority.offline_kit_audit` | New | 0341 | Enhanced audit with Rekor/DSSE fields |
### Configuration Changes
| Section | Sprint | Fields |
|---------|--------|--------|
| `AirGap:Quarantine` | 0338 | `QuarantineRoot`, `RetentionPeriod`, `MaxQuarantineSizeBytes` |
| `Scanner:OfflineKit` | 0340 | `RequireDsse`, `RekorOfflineMode`, `TrustAnchors[]` |
### CLI Commands
| Command | Sprint | Description |
|---------|--------|-------------|
| `stellaops offline import` | 0339 | Import offline kit with verification |
| `stellaops offline status` | 0339 | Display current kit status |
| `stellaops verify offline` | 0339 | Offline evidence verification |
### Metrics
| Metric | Type | Sprint | Labels |
|--------|------|--------|--------|
| `offlinekit_import_total` | Counter | 0341 | `status`, `tenant_id` |
| `offlinekit_attestation_verify_latency_seconds` | Histogram | 0341 | `attestation_type`, `success` |
| `attestor_rekor_success_total` | Counter | 0341 | `mode` |
| `attestor_rekor_retry_total` | Counter | 0341 | `reason` |
| `rekor_inclusion_latency` | Histogram | 0341 | `success` |
---
## 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
| Document | Sprint | Updates |
|----------|--------|---------|
| `docs/airgap/importer-scaffold.md` | 0338 | Add monotonicity, quarantine sections |
| `docs/airgap/runbooks/quarantine-investigation.md` | 0338 | New runbook |
| `docs/modules/cli/commands/offline.md` | 0339 | New command reference |
| `docs/modules/cli/guides/airgap.md` | 0339 | Update with CLI examples |
| `docs/modules/scanner/configuration.md` | 0340 | Add offline kit config section |
| `docs/airgap/observability.md` | 0341 | Metrics and logging reference |
| `docs/airgap/evidence-reconciliation.md` | 0342 | Algorithm documentation |
---
## Risk Register
| Risk | Impact | Mitigation |
|------|--------|------------|
| Monotonicity breaks existing workflows | High | Provide `--force-activate` escape hatch |
| Quarantine disk exhaustion | Medium | Implement quota and TTL cleanup |
| Trust anchor config complexity | Medium | Provide sensible defaults, validate at startup |
| Evidence reconciliation performance | Medium | Streaming processing, caching |
| Cross-platform determinism failures | High | CI matrix, golden-file tests |
---
## Success Metrics
| Metric | Target | Sprint |
|--------|--------|--------|
| Rollback attack prevention | 100% | 0338 |
| Failed bundle quarantine rate | 100% | 0338 |
| CLI command adoption | 50% operators | 0339 |
| Metric collection uptime | 99.9% | 0341 |
| Audit completeness | 100% events | 0341 |
| Reconciliation determinism | 100% | 0342 |
---
## References
- [14-Dec-2025 Offline and Air-Gap Technical Reference](../product-advisories/14-Dec-2025%20-%20Offline%20and%20Air-Gap%20Technical%20Reference.md)
- [Air-Gap Mode Playbook](./airgap-mode.md)
- [Offline Kit Documentation](../24_OFFLINE_KIT.md)
- [Importer Scaffold](./importer-scaffold.md)
Reference in New Issue View Git Blame Copy Permalink