sln build fix (again), tests fixes, audit work and doctors work

2026-01-12 22:15:51 +02:00
parent 9873f80830
commit 9330c64349
812 changed files with 48051 additions and 3891 deletions
--- a/docs-archived/implplan/sprint_3200/SPRINT_3200_0000_0000_attestation_ecosystem_interop.md
+++ b/docs-archived/implplan/sprint_3200/SPRINT_3200_0000_0000_attestation_ecosystem_interop.md
@@ -1,472 +0,0 @@
-# SPRINT_3200_0000_0000 — Attestation Ecosystem Interoperability (Master)
-
-> **Status:** Planning → Implementation
-> **Sprint ID:** 3200_0000_0000
-> **Epic:** Attestor + Scanner + CLI Integration
-> **Priority:** CRITICAL
-> **Owner:** Attestor, Scanner, CLI & Docs Guilds
-> **Advisory Origin:** `docs/product/advisories/23-Dec-2026 - Distinctive Edge for Docker Scanning.md`
-
---
-
-## Executive Summary
-
-**Strategic Opportunity:** Trivy and other scanners lack full SPDX attestation support (only CycloneDX attestations are mature). StellaOps can capture the "attested-first scanning" market by supporting **both SPDX and CycloneDX attestations** from third-party tools (Cosign, Trivy, Syft) while maintaining our deterministic, verifiable scanning advantage.
-
-**Current Gap:** StellaOps generates excellent SPDX/CycloneDX SBOMs with DSSE signing, but cannot **ingest** SBOM attestations from the Sigstore/Cosign ecosystem. This prevents users from:
- Verifying third-party attestations with `stella attest verify`
- Extracting SBOMs from DSSE envelopes created by Cosign/Trivy/Syft
- Running StellaOps scans on already-attested SBOMs
-
-**Deliverables:**
-1. Support standard SBOM predicate types (`https://spdx.dev/Document`, `https://cyclonedx.org/bom`)
-2. Extract and verify third-party DSSE attestations
-3. Ingest attested SBOMs through BYOS pipeline
-4. CLI commands for extraction and verification
-5. Comprehensive interoperability documentation
-
---
-
-## Overview
-
-This master sprint coordinates four parallel implementation tracks:
-
-| Sprint | Focus | Priority | Effort | Team |
-|--------|-------|----------|--------|------|
-| **3200.0001.0001** | Standard Predicate Types | CRITICAL | M | Attestor Guild |
-| **3200.0002.0001** | DSSE SBOM Extraction | CRITICAL | M | Scanner Guild |
-| **4300.0004.0001** | CLI Attestation Commands | HIGH | M | CLI Guild |
-| **5100.0005.0001** | Interop Documentation | HIGH | L | Docs Guild |
-
-**Total Estimated Effort:** 6-8 weeks (parallel execution: 2-3 weeks)
-
---
-
-## Context
-
-### Problem Statement
-
-**Current State:**
- ✅ StellaOps generates SPDX 3.0.1 and CycloneDX 1.4-1.7 SBOMs
- ✅ StellaOps signs SBOMs with DSSE and anchors to Rekor v2
- ✅ BYOS accepts raw SPDX/CycloneDX JSON files
- ❌ **No support for extracting SBOMs from DSSE envelopes**
- ❌ **No support for verifying third-party Cosign/Sigstore signatures**
- ❌ **Only StellaOps predicate types accepted** (`StellaOps.SBOMAttestation@1`)
-
-**Market Context (from Advisory):**
-> "Trivy already ingests CycloneDX‑type SBOM attestations (SBOM wrapped in DSSE). Formal parsing of SPDX in‑toto attestations is still tracked and not fully implemented. This means there's a window where CycloneDX attestation support is ahead of SPDX attestation support."
-
-**Competitive Advantage:**
-By supporting **both** SPDX and CycloneDX attestations, StellaOps becomes the **only scanner** with full attested SBOM parity across both formats.
-
-### Success Criteria
-
-1. **Standard Predicate Support:**
-   - Attestor accepts `https://spdx.dev/Document` predicate type
-   - Attestor accepts `https://cyclonedx.org/bom` and `https://cyclonedx.org/bom/1.6` predicate types
-   - Attestor accepts `https://slsa.dev/provenance/v1` predicate type
-
-2. **Third-Party Verification:**
-   - Verify Cosign-signed attestations with Fulcio trust roots
-   - Verify Syft-generated attestations
-   - Verify Trivy-generated attestations
-   - Support offline verification with bundled checkpoints
-
-3. **SBOM Extraction:**
-   - Extract SBOM payload from DSSE envelope
-   - Validate SBOM format (SPDX/CycloneDX)
-   - Pass extracted SBOM to BYOS pipeline
-
-4. **CLI Workflows:**
-   - `stella attest extract-sbom` - Extract SBOM from DSSE
-   - `stella attest verify --extract-sbom` - Verify and extract
-   - `stella sbom upload --from-attestation` - Direct upload from DSSE
-
-5. **Documentation:**
-   - Cosign integration guide
-   - Sigstore trust configuration
-   - API documentation for attestation endpoints
-   - Examples for Trivy/Syft/Cosign workflows
-
---
-
-## Architecture Overview
-
-### Component Interaction
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│                     Third-Party Tools                         │
-│  (Cosign, Trivy, Syft generate DSSE-wrapped SBOMs)          │
-└────────────────┬─────────────────────────────────────────────┘
-                 │ DSSE Envelope
-                 │ { payload: base64(SBOM), signatures: [...] }
-                 ▼
-┌──────────────────────────────────────────────────────────────┐
-│              StellaOps.Attestor.StandardPredicates           │
-│  NEW: Parsers for SPDX/CycloneDX/SLSA predicate types       │
-│  - StandardPredicateRegistry                                  │
-│  - SpdxPredicateParser                                        │
-│  - CycloneDxPredicateParser                                   │
-│  - SlsaProvenancePredicateParser                             │
-└────────────────┬─────────────────────────────────────────────┘
-                 │ Verified + Extracted SBOM
-                 ▼
-┌──────────────────────────────────────────────────────────────┐
-│           StellaOps.Scanner.Ingestion.Attestation            │
-│  NEW: BYOS extension for attested SBOM ingestion             │
-│  - DsseEnvelopeExtractor                                      │
-│  - AttestationVerifier                                        │
-│  - SbomPayloadNormalizer                                      │
-└────────────────┬─────────────────────────────────────────────┘
-                 │ Normalized SBOM
-                 ▼
-┌──────────────────────────────────────────────────────────────┐
-│          StellaOps.Scanner.WebService (BYOS API)             │
-│  EXISTING: POST /api/v1/sbom/upload                          │
-│  - Now accepts DSSE envelopes via new parameter              │
-└──────────────────────────────────────────────────────────────┘
-
-                 CLI Commands
-         ┌───────────────────────────┐
-         │  stella attest            │
-         │  - extract-sbom           │
-         │  - verify                 │
-         │  - inspect                │
-         └───────────────────────────┘
-```
-
-### New Libraries/Projects
-
-1. **StellaOps.Attestor.StandardPredicates** (New)
-   - Location: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/`
-   - Purpose: Parse and validate standard SBOM predicate types
-   - Dependencies: System.Text.Json, StellaOps.Attestor.ProofChain
-
-2. **StellaOps.Scanner.Ingestion.Attestation** (New)
-   - Location: `src/Scanner/__Libraries/StellaOps.Scanner.Ingestion.Attestation/`
-   - Purpose: Extract and normalize attested SBOMs for BYOS
-   - Dependencies: StellaOps.Attestor.StandardPredicates, StellaOps.Scanner.Models
-
-3. **CLI Command Extensions** (Existing + Enhancements)
-   - Location: `src/Cli/StellaOps.Cli/Commands/Attest/`
-   - New commands: `ExtractSbomCommand`, `InspectCommand`
-   - Enhanced: `VerifyCommand` with `--extract-sbom` flag
-
---
-
-## Sprint Breakdown
-
-### Sprint 3200.0001.0001 — Standard Predicate Types
-
-**Owner:** Attestor Guild
-**Priority:** CRITICAL
-**Effort:** Medium (2 weeks)
-**Dependencies:** None
-
-**Deliverables:**
- Create `StellaOps.Attestor.StandardPredicates` library
- Implement SPDX Document predicate parser
- Implement CycloneDX BOM predicate parser
- Implement SLSA Provenance predicate parser
- Update Attestor to accept standard predicate types
- Unit tests for all parsers
- Integration tests with sample attestations
-
-**See:** `SPRINT_3200_0001_0001_standard_predicate_types.md`
-
---
-
-### Sprint 3200.0002.0001 — DSSE SBOM Extraction
-
-**Owner:** Scanner Guild
-**Priority:** CRITICAL
-**Effort:** Medium (2 weeks)
-**Dependencies:** Sprint 3200.0001.0001 (for predicate parsers)
-
-**Deliverables:**
- Create `StellaOps.Scanner.Ingestion.Attestation` library
- Implement DSSE envelope extractor
- Implement attestation verification service
- Implement SBOM payload normalizer
- Extend BYOS API to accept DSSE envelopes
- Unit tests for extraction logic
- Integration tests with Trivy/Syft/Cosign samples
-
-**See:** `SPRINT_3200_0002_0001_dsse_sbom_extraction.md`
-
---
-
-### Sprint 4300.0004.0001 — CLI Attestation Commands
-
-**Owner:** CLI Guild
-**Priority:** HIGH
-**Effort:** Medium (2 weeks)
-**Dependencies:** Sprints 3200.0001.0001 + 3200.0002.0001
-
-**Deliverables:**
- Implement `stella attest extract-sbom` command
- Enhance `stella attest verify` with `--extract-sbom` flag
- Implement `stella attest inspect` command
- Implement `stella sbom upload --from-attestation` flag
- CLI integration tests
- Example workflows for Cosign/Trivy/Syft
-
-**See:** `SPRINT_4300_0004_0001_cli_attestation_extraction.md`
-
---
-
-### Sprint 5100.0005.0001 — Interop Documentation
-
-**Owner:** Docs Guild
-**Priority:** HIGH
-**Effort:** Low (1 week)
-**Dependencies:** Sprints 3200.0001.0001 + 3200.0002.0001 + 4300.0004.0001
-
-**Deliverables:**
- Create `docs/interop/cosign-integration.md`
- Create `docs/interop/sigstore-trust-configuration.md`
- Create `docs/interop/trivy-attestation-workflow.md`
- Create `docs/interop/syft-attestation-workflow.md`
- Update `docs/modules/attestor/architecture.md`
- Update `docs/modules/scanner/byos-ingestion.md`
- Create sample attestations in `docs/samples/attestations/`
- Update CLI reference documentation
-
-**See:** `SPRINT_5100_0005_0001_attestation_interop_docs.md`
-
---
-
-## Execution Timeline
-
-### Parallel Execution Plan
-
-**Week 1-2:**
- Sprint 3200.0001.0001 (Standard Predicates) — Start immediately
- Sprint 3200.0002.0001 (DSSE Extraction) — Start Day 3 (after predicate parsers stubbed)
-
-**Week 2-3:**
- Sprint 4300.0004.0001 (CLI Commands) — Start Day 10 (after core libraries complete)
- Sprint 5100.0005.0001 (Documentation) — Start Day 10 (parallel with CLI)
-
-**Critical Path:** 3200.0001 → 3200.0002 → 4300.0004
-**Documentation Path:** Can run in parallel once APIs are defined
-
---
-
-## Risks & Mitigations
-
-| Risk | Impact | Probability | Mitigation |
-|------|--------|-------------|------------|
-| Cosign signature format changes | HIGH | LOW | Pin to Cosign v2.x format, version predicate parsers |
-| SPDX 3.0.1 schema evolution | MEDIUM | MEDIUM | Implement schema version detection, support multiple versions |
-| Third-party trust root configuration | MEDIUM | MEDIUM | Provide sensible defaults (Sigstore public instance), document custom roots |
-| Performance impact of DSSE verification | LOW | MEDIUM | Implement verification caching, async verification option |
-| Breaking changes to existing BYOS API | HIGH | LOW | Add new endpoints, maintain backward compatibility |
-
---
-
-## Testing Strategy
-
-### Unit Tests
- Predicate parser tests (100+ test cases across SPDX/CycloneDX/SLSA)
- DSSE extraction tests
- Signature verification tests
- SBOM normalization tests
-
-### Integration Tests
- End-to-end: Cosign-signed SBOM → Verify → Extract → Upload → Scan
- End-to-end: Trivy attestation → Verify → Extract → Upload → Scan
- End-to-end: Syft attestation → Verify → Extract → Upload → Scan
-
-### Fixtures
- Sample attestations from Cosign, Trivy, Syft
- Golden hashes for deterministic verification
- Offline verification test cases
- Negative test cases (invalid signatures, tampered payloads)
-
-### Performance Tests
- Verify 1000 attestations/second throughput
- Extract 100 SBOMs/second throughput
- Offline verification <100ms P95
-
---
-
-## Observability
-
-### New Metrics
-
-```prometheus
-# Attestor
-attestor_standard_predicate_parse_total{type,result}
-attestor_standard_predicate_parse_duration_seconds{type}
-attestor_third_party_signature_verify_total{issuer,result}
-
-# Scanner
-scanner_attestation_ingest_total{source,format,result}
-scanner_attestation_extract_duration_seconds{format}
-scanner_byos_attestation_upload_total{result}
-
-# CLI
-cli_attest_extract_total{format,result}
-cli_attest_verify_total{issuer,result}
-```
-
-### Logs
-
-All attestation operations include structured logging:
- `predicateType` - Standard or StellaOps predicate
- `issuer` - Certificate subject or key ID
- `source` - Tool that generated attestation (Cosign, Trivy, Syft, StellaOps)
- `format` - SBOM format (SPDX, CycloneDX)
- `verificationStatus` - Success, failed, skipped
-
---
-
-## Documentation Requirements
-
-### User-Facing
- Cosign integration guide
- Trivy workflow guide
- Syft workflow guide
- CLI command reference updates
- Troubleshooting guide
-
-### Developer-Facing
- Standard predicate parser architecture
- DSSE extraction pipeline design
- API contract updates
- Test fixture creation guide
-
-### Operations
- Trust root configuration
- Offline verification setup
- Performance tuning guide
- Monitoring and alerting
-
---
-
-## Acceptance Criteria
-
-### Must Have (MVP)
- ✅ Support `https://spdx.dev/Document` predicate type
- ✅ Support `https://cyclonedx.org/bom` predicate type
- ✅ Verify Cosign-signed attestations
- ✅ Extract SBOM from DSSE envelope
- ✅ Upload extracted SBOM via BYOS
- ✅ CLI `extract-sbom` command
- ✅ CLI `verify --extract-sbom` command
- ✅ Cosign integration documentation
- ✅ Unit tests (80%+ coverage)
- ✅ Integration tests (happy path)
-
-### Should Have (MVP+)
- ✅ Support `https://slsa.dev/provenance/v1` predicate type
- ✅ Verify Trivy-generated attestations
- ✅ Verify Syft-generated attestations
- ✅ CLI `inspect` command (show attestation details)
- ✅ Offline verification with bundled checkpoints
- ✅ Trivy/Syft workflow documentation
- ✅ Integration tests (error cases)
-
-### Could Have (Future)
- Support CycloneDX CDXA (attestation extensions)
- Support multiple signatures per envelope
- Batch attestation verification
- Attestation caching service
- UI for attestation browsing
-
---
-
-## Go/No-Go Criteria
-
-**Go Decision Prerequisites:**
- [ ] All sub-sprint delivery trackers created
- [ ] Module AGENTS.md files reviewed
- [ ] Architecture documents reviewed
- [ ] Test strategy approved
- [ ] Guild capacity confirmed (2 eng/guild minimum)
-
-**No-Go Conditions:**
- Breaking changes to existing BYOS API required
- Performance degradation >20% on existing workflows
- Cosign signature format incompatibility discovered
- Critical security vulnerability in DSSE verification
-
---
-
-## References
-
-### Advisory
- `docs/product/advisories/23-Dec-2026 - Distinctive Edge for Docker Scanning.md`
-
-### Gap Analysis
- `docs/implplan/analysis/3200_attestation_ecosystem_gap_analysis.md`
-
-### Related Sprints
- SPRINT_0501_0003_0001 - Proof Chain DSSE Predicates (StellaOps-specific)
- SPRINT_3000_0001_0001 - Rekor Merkle Proof Verification
- SPRINT_3000_0100_0001 - Signed Delta-Verdicts
-
-### External Standards
- [in-toto Attestation Specification](https://github.com/in-toto/attestation)
- [SPDX 3.0.1 Specification](https://spdx.github.io/spdx-spec/v3.0.1/)
- [CycloneDX 1.6 Specification](https://cyclonedx.org/docs/1.6/)
- [SLSA Provenance v1.0](https://slsa.dev/spec/v1.0/provenance)
- [Sigstore Cosign Documentation](https://docs.sigstore.dev/cosign/overview/)
-
---
-
-## Decisions & Risks
-
-### Architectural Decisions
-
-**AD-3200-001:** Use separate library for standard predicates
-**Rationale:** Keep StellaOps-specific predicates isolated, allow versioning
-**Alternatives Considered:** Extend existing ProofChain library (rejected: tight coupling)
-
-**AD-3200-002:** Extend BYOS API vs new attestation endpoint
-**Decision:** Extend BYOS with `dsseEnvelope` parameter
-**Rationale:** Maintains single ingestion path, simpler user model
-**Alternatives Considered:** New `/api/v1/attestations/ingest` endpoint (rejected: duplication)
-
-**AD-3200-003:** Inline vs reference SBOM payloads
-**Decision:** Support both (inline base64 payload, external URI reference)
-**Rationale:** Matches Cosign/Trivy behavior, supports large SBOMs
-
-**AD-3200-004:** Trust root configuration
-**Decision:** Default to Sigstore public instance, support custom roots via config
-**Rationale:** Works out-of-box for most users, flexible for air-gapped deployments
-
-### Open Questions
-
-**Q-3200-001:** Should we support legacy DSSE envelope formats (pre-v1)?
-**Status:** BLOCKED - Awaiting security guild review
-**Decision By:** End of Week 1
-
-**Q-3200-002:** Should verification caching be persistent or in-memory?
-**Status:** OPEN - Need performance benchmarks
-**Decision By:** During Sprint 3200.0002.0001
-
-**Q-3200-003:** Should we emit Unknowns for unparseable predicates?
-**Status:** OPEN - Need Signal guild input
-**Decision By:** End of Week 2
-
---
-
-## Status Updates
-
-### 2025-12-23 (Sprint Created)
- Master sprint document created
- Sub-sprint documents pending
- Awaiting guild capacity confirmation
- Architecture review scheduled for 2025-12-24
-
---
-
-**Next Steps:**
-1. Review and approve master sprint plan
-2. Create sub-sprint documents
-3. Schedule kickoff meetings with each guild
-4. Begin Sprint 3200.0001.0001 (Standard Predicates)