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:
54
docs2/architecture/evidence-and-trust.md
Normal file
54
docs2/architecture/evidence-and-trust.md
Normal 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.
|
||||
38
docs2/architecture/overview.md
Normal file
38
docs2/architecture/overview.md
Normal 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.
|
||||
25
docs2/architecture/reachability-vex.md
Normal file
25
docs2/architecture/reachability-vex.md
Normal 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.
|
||||
36
docs2/architecture/workflows.md
Normal file
36
docs2/architecture/workflows.md
Normal 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.
|
||||
Reference in New Issue
Block a user