old sprints work, new sprints for exposing functionality via cli, improve code_of_conduct and other agents instructions

2026-01-15 18:37:59 +02:00
parent c631bacee2
commit 88a85cdd92
208 changed files with 32271 additions and 2287 deletions
--- a/docs/compliance/COMPLIANCE_READINESS_TRACKER.md
+++ b/docs/compliance/COMPLIANCE_READINESS_TRACKER.md
@@ -0,0 +1,320 @@
+# Compliance Readiness Tracker
+
+**Version**: 1.0.0
+**Created**: 2026-01-15
+**Last Updated**: 2026-01-15
+**Status**: Active
+
+This document tracks implementation progress for the 7-Item Compliance Readiness Checklist for regulated customer deployments.
+
+## Executive Summary
+
+| Item | Description | Coverage | Status | Target |
+|------|-------------|----------|--------|--------|
+| 1 | Attestation caching (offline) | 75% | In Progress | Demo Ready |
+| 2 | Offline RBAC & break-glass | 60% | In Progress | Demo Ready |
+| 3 | Signed SBOM archives | 55% | In Progress | Demo Ready |
+| 4 | HSM / key escrow | 50% | In Progress | RFP Ready |
+| 5 | Local Rekor mirrors | 60% | In Progress | RFP Ready |
+| 6 | Offline policy engine | 80% | In Progress | RFP Ready |
+| 7 | Upgrade & evidence migration | 45% | In Progress | Audit Ready |
+
+## Sprint Allocation
+
+### Phase 1: Demo Blockers (016)
+
+Target: Features needed for 10-minute compliance demo.
+
+| Sprint | Module | Description | Status |
+|--------|--------|-------------|--------|
+| [016_CLI_attest_verify_offline](../implplan/SPRINT_20260112_016_CLI_attest_verify_offline.md) | CLI | Offline attestation verification CLI | TODO |
+| [016_CLI_sbom_verify_offline](../implplan/SPRINT_20260112_016_CLI_sbom_verify_offline.md) | CLI | Offline SBOM verification CLI | TODO |
+| [016_SCANNER_signed_sbom_archive_spec](../implplan/SPRINT_20260112_016_SCANNER_signed_sbom_archive_spec.md) | Scanner | Signed SBOM archive format | TODO |
+| [016_DOCS_blue_green_deployment](../implplan/SPRINT_20260112_016_DOCS_blue_green_deployment.md) | Docs | Blue/green deployment guide | TODO |
+
+### Phase 2: RFP Compliance (017)
+
+Target: Features needed to pass RFP security questionnaires.
+
+| Sprint | Module | Description | Status |
+|--------|--------|-------------|--------|
+| [017_CRYPTO_pkcs11_hsm_implementation](../implplan/SPRINT_20260112_017_CRYPTO_pkcs11_hsm_implementation.md) | Crypto | PKCS#11 HSM implementation | TODO |
+| [017_ATTESTOR_periodic_rekor_sync](../implplan/SPRINT_20260112_017_ATTESTOR_periodic_rekor_sync.md) | Attestor | Periodic Rekor checkpoint sync | TODO |
+| [017_ATTESTOR_checkpoint_divergence_detection](../implplan/SPRINT_20260112_017_ATTESTOR_checkpoint_divergence_detection.md) | Attestor | Checkpoint divergence detection | TODO |
+| [017_POLICY_cvss_threshold_gate](../implplan/SPRINT_20260112_017_POLICY_cvss_threshold_gate.md) | Policy | CVSS threshold policy gate | TODO |
+| [017_POLICY_sbom_presence_gate](../implplan/SPRINT_20260112_017_POLICY_sbom_presence_gate.md) | Policy | SBOM presence policy gate | TODO |
+| [017_POLICY_signature_required_gate](../implplan/SPRINT_20260112_017_POLICY_signature_required_gate.md) | Policy | Signature required policy gate | TODO |
+
+### Phase 3: Audit Readiness (018)
+
+Target: Features needed to pass security audits.
+
+| Sprint | Module | Description | Status |
+|--------|--------|-------------|--------|
+| [018_SIGNER_dual_control_ceremonies](../implplan/SPRINT_20260112_018_SIGNER_dual_control_ceremonies.md) | Signer | Dual-control signing ceremonies | TODO |
+| [018_CRYPTO_key_escrow_shamir](../implplan/SPRINT_20260112_018_CRYPTO_key_escrow_shamir.md) | Crypto | Key escrow with Shamir | TODO |
+| [018_AUTH_local_rbac_fallback](../implplan/SPRINT_20260112_018_AUTH_local_rbac_fallback.md) | Authority | Local RBAC policy fallback | TODO |
+| [018_EVIDENCE_reindex_tooling](../implplan/SPRINT_20260112_018_EVIDENCE_reindex_tooling.md) | Evidence | Evidence re-index tooling | TODO |
+| [018_DOCS_upgrade_runbook_evidence_continuity](../implplan/SPRINT_20260112_018_DOCS_upgrade_runbook_evidence_continuity.md) | Docs | Upgrade runbook with evidence | TODO |
+
+## Detailed Item Status
+
+### Item 1: Attestation Caching (Offline)
+
+**Why it matters**: Regulated shops can't reach public Sigstore/Rekor during audits.
+
+| Requirement | Implementation | Status | Sprint |
+|-------------|---------------|--------|--------|
+| DSSE caching | `TrustVerdictCache`, `CachedAttestorVerificationService` | DONE | Existing |
+| Transparency proofs | `RekorOfflineReceiptVerifier` | DONE | Existing |
+| Exportable bundles | `EvidencePortableBundleService` | DONE | Existing |
+| Hash manifest | `EvidenceBundleManifest` | DONE | Existing |
+| Offline CLI verify | `stella attest verify --offline` | TODO | 016_CLI |
+| Bundle test fixtures | Golden test fixtures | TODO | 016_CLI |
+| VERIFY.md generation | Bundled verification script | TODO | 016_SCANNER |
+
+**Proof Artifacts**:
+- [ ] Demo verifying image on laptop with Wi-Fi off
+- [ ] SHA-256 match + signature chain report
+
+### Item 2: Offline RBAC & Break-Glass
+
+**Why it matters**: No cloud IdP during outages/air-gap. Auditors want least-privilege and emergency access trails.
+
+| Requirement | Implementation | Status | Sprint |
+|-------------|---------------|--------|--------|
+| Incident mode tokens | `obs:incident` scope | DONE | Existing |
+| 5-minute freshness | `auth_time` claim validation | DONE | Existing |
+| Reason codes | `incident_reason` claim | DONE | Existing |
+| Audit logging | `/authority/audit/incident` endpoint | DONE | Existing |
+| Local file policy | `FileBasedPolicyStore` | TODO | 018_AUTH |
+| Break-glass account | Bootstrap bypass account | TODO | 018_AUTH |
+| Auto-revocation | Session timeout enforcement | TODO | 018_AUTH |
+
+**Proof Artifacts**:
+- [ ] RBAC matrix (roles -> verbs -> resources)
+- [ ] Audit log showing break-glass entry/exit
+
+### Item 3: Signed SBOM Archives (Immutable)
+
+**Why it matters**: SBOMs must be tamper-evident and tied to exact build inputs.
+
+| Requirement | Implementation | Status | Sprint |
+|-------------|---------------|--------|--------|
+| CycloneDX/SPDX | `SbomExportService` | DONE | Existing |
+| DSSE signing | `SignerPipeline` | DONE | Existing |
+| Archive format | Signed SBOM archive spec | TODO | 016_SCANNER |
+| Tool versions | `metadata.json` in archive | TODO | 016_SCANNER |
+| Source hashes | Scanner image digest capture | TODO | 016_SCANNER |
+| One-click verify | `stella sbom verify` CLI | TODO | 016_CLI |
+| RFC 3161 TSA | TSA integration | DEFERRED | Future |
+
+**Proof Artifacts**:
+- [ ] One-click "Verify SBOM" checking signature, timestamps, content hashes
+
+### Item 4: HSM / Key Escrow Patterns
+
+**Why it matters**: Key custody is a governance hotspot.
+
+| Requirement | Implementation | Status | Sprint |
+|-------------|---------------|--------|--------|
+| PKCS#11 support | `HsmPlugin` architecture | PARTIAL | Existing |
+| AWS/GCP KMS | `AwsKmsClient`, `GcpKmsClient` | DONE | Existing |
+| Key rotation | `KeyRotationService` | DONE | Existing |
+| PKCS#11 impl | `Pkcs11HsmClient` with Interop | TODO | 017_CRYPTO |
+| Dual-control | M-of-N ceremonies | TODO | 018_SIGNER |
+| Key escrow | Shamir secret sharing | TODO | 018_CRYPTO |
+| HSM runbook | Setup and config guide | TODO | 017_CRYPTO |
+
+**Proof Artifacts**:
+- [ ] Config targeting HSM slot
+- [ ] Simulated key rotation with attestation continuity
+
+### Item 5: Local Rekor (Transparency) Mirrors
+
+**Why it matters**: Auditors want inclusion proofs even when offline.
+
+| Requirement | Implementation | Status | Sprint |
+|-------------|---------------|--------|--------|
+| Tile verification | `IRekorTileClient`, `HttpRekorTileClient` | DONE | Existing |
+| Checkpoint verify | `CheckpointSignatureVerifier` | DONE | Existing |
+| Offline receipts | `RekorOfflineReceiptVerifier` | DONE | Existing |
+| Periodic sync | `RekorSyncBackgroundService` | TODO | 017_ATTESTOR |
+| Checkpoint store | `PostgresRekorCheckpointStore` | TODO | 017_ATTESTOR |
+| Divergence detect | Root mismatch alarms | TODO | 017_ATTESTOR |
+
+**Proof Artifacts**:
+- [ ] Verify inclusion proof against local checkpoint without internet
+- [ ] Mismatch alarm if roots diverge
+
+### Item 6: Offline Policy Engine (OPA/Conftest-class)
+
+**Why it matters**: Gates must hold when the network doesn't.
+
+| Requirement | Implementation | Status | Sprint |
+|-------------|---------------|--------|--------|
+| Policy bundles | `PolicyBundle` with versioning | DONE | Existing |
+| Sealed mode | `SealedModeService` | DONE | Existing |
+| VEX gates | `VexProofGate`, `VexTrustGate` | DONE | Existing |
+| Unknowns gate | `UnknownsBudgetGate` | DONE | Existing |
+| Evidence gates | `EvidenceFreshnessGate`, etc. | DONE | Existing |
+| CVSS gate | `CvssThresholdGate` | TODO | 017_POLICY |
+| SBOM gate | `SbomPresenceGate` | TODO | 017_POLICY |
+| Signature gate | `SignatureRequiredGate` | TODO | 017_POLICY |
+
+**Proof Artifacts**:
+- [ ] Local policy pack on sample image showing fail
+- [ ] Compliant pass after adding VEX exception with justification
+
+### Item 7: Upgrade & Evidence-Migration Paths
+
+**Why it matters**: "Can we upgrade without invalidating proofs?" is a top blocker.
+
+| Requirement | Implementation | Status | Sprint |
+|-------------|---------------|--------|--------|
+| DB migrations | Forward-only strategy | DONE | Existing |
+| Evidence bundles | Merkle roots in manifests | DONE | Existing |
+| Backup/restore | Per-module procedures | DONE | Existing |
+| Blue/green docs | Deployment guide | TODO | 016_DOCS |
+| Upgrade runbook | Step-by-step procedures | TODO | 018_DOCS |
+| Re-index tools | `stella evidence reindex` | TODO | 018_EVIDENCE |
+| Root cross-ref | Old/new root mapping | TODO | 018_EVIDENCE |
+
+**Proof Artifacts**:
+- [ ] Staged upgrade in test namespace
+- [ ] Before/after verification reports
+- [ ] Unchanged artifact digests
+
+## Documentation Deliverables
+
+| Document | Path | Status |
+|----------|------|--------|
+| Blue/Green Deployment | [docs/operations/blue-green-deployment.md](../operations/blue-green-deployment.md) | DONE |
+| Upgrade Runbook | [docs/operations/upgrade-runbook.md](../operations/upgrade-runbook.md) | DONE |
+| HSM Setup Runbook | [docs/operations/hsm-setup-runbook.md](../operations/hsm-setup-runbook.md) | DONE |
+| Signed SBOM Spec | [docs/modules/scanner/signed-sbom-archive-spec.md](../modules/scanner/signed-sbom-archive-spec.md) | DONE |
+| Break-Glass Account | [docs/modules/authority/operations/break-glass-account.md](../modules/authority/operations/break-glass-account.md) | DONE |
+
+## Demo Script (10 Minutes)
+
+### Preparation
+
+```bash
+# Ensure test artifacts are available
+export DEMO_IMAGE="registry.company.com/demo-app:v1.0"
+export DEMO_BUNDLE="demo-evidence.tar.gz"
+export DEMO_SBOM="demo-sbom.tar.gz"
+```
+
+### Demo 1: Verify Image + SBOM Offline (2 min)
+
+```bash
+# Disconnect network (demo mode)
+# Verify attestation bundle offline
+stella attest verify --offline \
+  --bundle ${DEMO_BUNDLE} \
+  --trust-root /demo/roots/
+
+# Verify SBOM archive offline
+stella sbom verify --offline \
+  --archive ${DEMO_SBOM}
+
+# Show pass/fail output
+```
+
+### Demo 2: Policy Gate with VEX Exception (2 min)
+
+```bash
+# Show policy gate denying high CVSS
+stella policy evaluate \
+  --artifact sha256:demo123 \
+  --environment production
+
+# Output: BLOCKED - CVE-2024-12345 (CVSS 9.8) exceeds threshold
+
+# Add VEX exception with justification
+stella vex add \
+  --cve CVE-2024-12345 \
+  --status not_affected \
+  --justification "Vulnerable code path not reachable" \
+  --sign
+
+# Re-evaluate - should pass
+stella policy evaluate \
+  --artifact sha256:demo123 \
+  --environment production
+
+# Output: PASSED - VEX exception applied
+```
+
+### Demo 3: HSM Key Rotation (2 min)
+
+```bash
+# Show current signing key
+stella key list --active
+
+# Rotate signing key in HSM
+stella key rotate \
+  --new-key-label "signing-2027" \
+  --hsm-slot 0
+
+# Re-sign attestation
+stella attest sign \
+  --subject sha256:demo123 \
+  --key signing-2027
+
+# Show proofs remain valid
+stella attest verify --bundle new-attestation.tar.gz
+```
+
+### Demo 4: Local Rekor Mirror Verification (2 min)
+
+```bash
+# Query local Rekor mirror
+stella rekor query \
+  --artifact sha256:demo123 \
+  --offline
+
+# Verify inclusion proof against local checkpoint
+stella rekor verify \
+  --proof inclusion-proof.json \
+  --checkpoint checkpoint.sig \
+  --offline
+
+# Output: VERIFIED - Inclusion proof valid
+```
+
+### Demo 5: Upgrade Simulation (2 min)
+
+```bash
+# Run upgrade pre-check
+stella evidence verify-all --output pre-upgrade.json
+
+# Simulate upgrade (in demo namespace)
+stella upgrade simulate --target 2027.Q2
+
+# Re-index proofs
+stella evidence reindex --dry-run
+
+# Show continuity report
+stella evidence verify-continuity \
+  --baseline pre-upgrade.json \
+  --output continuity-report.html
+
+# Open report showing unchanged digests
+```
+
+## Stakeholder Sign-Off
+
+| Role | Name | Date | Signature |
+|------|------|------|-----------|
+| Engineering Lead | | | |
+| Security Lead | | | |
+| Product Manager | | | |
+| Customer Success | | | |
+
+## Change Log
+
+| Date | Version | Author | Changes |
+|------|---------|--------|---------|
+| 2026-01-15 | 1.0.0 | Planning | Initial tracker creation |