feat(scanner): Complete PoE implementation with Windows compatibility fix

- Fix namespace conflicts (Subgraph → PoESubgraph)
- Add hash sanitization for Windows filesystem (colon → underscore)
- Update all test mocks to use It.IsAny<>()
- Add direct orchestrator unit tests
- All 8 PoE tests now passing (100% success rate)
- Complete SPRINT_3500_0001_0001 documentation

Fixes compilation errors and Windows filesystem compatibility issues.
Tests: 8/8 passing
Files: 8 modified, 1 new test, 1 completion report

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
master
2025-12-23 14:52:08 +02:00
parent 84d97fd22c
commit fcb5ffe25d
90 changed files with 9457 additions and 2039 deletions

View File

@@ -0,0 +1,54 @@
# Evidence and trust model
## Determinism rules
- Content-address all artifacts by digest.
- Canonicalize JSON and sort arrays deterministically.
- Use UTC timestamps only.
- Do not use wall-clock or RNG in decision paths.
- Pin inputs: analyzer versions, policy hash, advisory and VEX snapshots.
## Evidence categories
- Inputs: SBOMs, advisories, VEX statements, provenance, runtime facts.
- Transforms: normalization outputs, linksets, reachability graphs.
- Decisions: verdicts, explain traces, derived VEX.
- Audit: token issuance, policy changes, signing events.
## Decision Capsules
A Decision Capsule is the minimal audit bundle for a decision. It includes:
- The exact SBOM (inventory and usage views)
- Advisory and VEX snapshot identifiers
- Reachability evidence and unknowns metadata
- Policy version and policy hash
- Decision trace and derived VEX
- DSSE envelopes and optional Rekor proofs
## Attestation chain
- in-toto statements wrapped in DSSE envelopes.
- Signer produces DSSE; Attestor logs and verifies in Rekor when enabled.
- Offline kits include cached proofs for air-gapped verification.
## Aggregation-Only Contract (AOC)
- Ingestion services store raw facts only.
- No derived severity, consensus, or policy hints at ingest time.
- All derived findings are produced by the Policy Engine.
- Idempotent writes use content hash and supersedes chains.
- Append-only revisions preserve upstream provenance and conflicts.
## Content-addressed storage
- RustFS stores SBOM fragments, reports, reachability graphs, and evidence bundles.
- Replay bundles store inputs and outputs with deterministic ordering.
## Replay bundles (typical layout)
- manifest.json and manifest.dsse.json
- input bundle with feeds, policy, and tool manifests
- output bundle with SBOMs, findings, VEX, and logs
## Verification steps (offline or online)
1) Verify DSSE envelope signature against trusted keys.
2) Recompute payload hash and compare to manifest digest.
3) Verify Rekor proof when available or against offline checkpoints.
4) Ensure all referenced CAS objects are present and hashed.
## Retention
- Evidence retention is configurable, but must preserve decision reproducibility
for the required audit window.

View File

@@ -0,0 +1,38 @@
# Architecture overview
## System boundary
- Self-hosted by default with optional licensing validation.
- Offline-first, with all critical verification paths available without network access.
## Core infrastructure
- PostgreSQL: the only canonical database, with schema isolation per module.
- Valkey: cache, queues, and streams (Redis compatible).
- RustFS: object storage for content-addressed artifacts.
- Optional: NATS JetStream as an alternative queue and stream transport.
## External dependencies
- OCI registry with referrers for SBOM and attestation discovery.
- Fulcio or KMS-backed signing (optional, depending on crypto profile).
- Rekor (optional) for transparency log anchoring.
## Core services (high level)
- Authority: OIDC and OAuth2 token issuance, DPoP and mTLS sender constraints.
- Signer: DSSE signing with entitlement checks and scanner integrity verification.
- Attestor: transparency logging and attestation verification.
- Scanner (Web + Worker): SBOM generation, analyzers, inventory and usage views, diffs.
- Concelier: advisory ingest under the Aggregation-Only Contract (AOC).
- Excititor: VEX ingest under AOC with consensus and evidence preservation.
- Policy Engine: deterministic policy evaluation with explain traces.
- Scheduler: impact selection and analysis-only re-evaluation.
- Notify: rules, channels, and delivery workflows.
- Export Center: deterministic exports and offline bundles.
- UI and CLI: operator and automation surfaces.
- Zastava: runtime observer and optional admission enforcement.
- Advisory AI: evidence-based guidance with guardrails.
- Orchestrator: job DAGs and pack runs.
## Trust boundaries
- Authority issues short-lived OpTok tokens with sender constraints (DPoP or mTLS).
- Signer enforces Proof of Entitlement (PoE) and scanner image integrity before signing.
- Only Signer produces DSSE; only Attestor writes to Rekor.
- All evidence is content-addressed and immutable once written.

View File

@@ -0,0 +1,25 @@
# Reachability and VEX
## Reachability evidence
- Static call graphs are produced by Scanner analyzers.
- Runtime traces are collected by Zastava when enabled.
- Union bundles combine static and runtime evidence for scoring and replay.
## Hybrid reachability attestations
- Graph-level DSSE is required for every reachability graph.
- Optional edge-bundle DSSE captures contested or runtime edges.
- Rekor publishing can be tiered; offline kits cache proofs when available.
## Reachability scoring (Signals)
- Bucket model: entrypoint, direct, runtime, unknown, unreachable.
- Default weights: entrypoint 1.0, direct 0.85, runtime 0.45, unknown 0.5, unreachable 0.0.
- Unknowns pressure reduces the final score to avoid false safety.
## VEX consensus
- Excititor ingests and normalizes VEX statements (OpenVEX, CSAF VEX).
- Policy Engine merges evidence using lattice logic with explicit Unknown handling.
- Decisions include evidence refs and can be exported as downstream VEX.
## Unknowns registry
- Unknowns are first-class objects with scoring, SLA bands, and evidence links.
- Unknowns are stored with deterministic ordering and exported for offline review.

View File

@@ -0,0 +1,36 @@
# Architecture workflows
## Advisory and VEX ingestion (AOC)
1) Concelier and Excititor fetch upstream documents.
2) AOC guards validate provenance and append-only rules.
3) Raw facts are stored in PostgreSQL without derived severity.
4) Deterministic exports are produced for downstream policy evaluation.
## Scan and report
1) CLI or API submits an image digest or SBOM.
2) Scanner Worker analyzes layers and produces SBOM fragments.
3) Scanner Web composes inventory and usage SBOMs and runs diffs.
4) Policy Engine evaluates findings against advisories and VEX evidence.
5) Signer produces DSSE bundles; Attestor logs to Rekor when enabled.
## Reachability and unknowns
1) Scanner produces static call graphs.
2) Zastava produces runtime facts when enabled.
3) Signals computes reachability scores and unknowns pressure.
4) Policy Engine incorporates reachability evidence into VEX decisions.
## Scheduler re-evaluation
1) Concelier and Excititor emit delta events.
2) Scheduler identifies impacted images using BOM index metadata.
3) Scanner Web runs analysis-only reports against existing SBOMs.
4) Notify emits delta notifications to operators.
## Notifications
1) Scanner and Scheduler publish events to Valkey streams.
2) Notify Web applies routing rules and templates.
3) Notify Worker delivers to Slack, Teams, email, or webhooks.
## Export and offline bundles
1) Export Center creates deterministic export bundles (JSON, Trivy DB, mirror layouts).
2) Offline kits package feeds, images, analyzers, and manifests for air-gapped sites.
3) CLI verifies signatures and imports bundles atomically.