stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 12 Releases Wiki Activity

chore(docs): normalize reachability sprint references

Browse Source
This commit is contained in:
StellaOps Bot
2025-11-22 16:36:27 +00:00
parent dc7c75b496
commit ca09400069
3 changed files with 313 additions and 313 deletions
Download Patch File Download Diff File Expand all files Collapse all files

278
docs/benchmarks/vex-evidence-playbook.md
View File

@@ -1,140 +1,140 @@
# VEX Evidence Playbook (Bench Repo Blueprint)
> **Status:** Draft – aligns with the “provable vulnerability decisions” advisory (Nov 2025).
> **Owners:** Policy Guild · VEX Lens Guild · CLI Guild · Docs Guild.
This playbook defines the public benchmark repository layout, artifact shapes, verification tooling, and metrics that prove Stella Ops VEX decisions are reproducible, portable, and superior to baseline scanners. Treat it as the contract for every guild contributing artifacts to `bench/`.
---
## 1. Repository layout
```
bench/
README.md # repo overview + quickstart
findings/
CVE-YYYY-NNNNN/ # one folder per advisory/product tuple
evidence/
reachability.json # static+runtime call graph for the finding
sbom.cdx.json # CycloneDX slice containing the involved components
decision.openvex.json # OpenVEX statement (status + justification)
decision.dsse.json # DSSE envelope wrapping the OpenVEX payload
rekor.txt # optional Rekor UUID/index/checkpoint
metadata.json # producer info (policy rev, analyzer digests, CAS URIs)
tools/
verify.sh # shell helper: dsse verify + optional rekor verification
verify.py # python verifier (offline) that recomputes digests
compare.py # baseline diff against Trivy/Syft/Grype/Snyk/Xray outputs
replay.sh # reruns reachability graphs via `stella replay`
results/
summary.csv # FP reduction, MTTD, reproducibility metrics
runs/2025-11-10/ # pinned scanner/policy versions + raw outputs
stella/
findings.json
runtime-facts.ndjson
reachability.manifest.json
trivy/
findings.json
...
```
### File contracts
- `reachability.json` is the canonical export from `cas://reachability/graphs/...` with symbol IDs, call edges, runtime hits, analyzer fingerprints, and CAS references.
- `decision.openvex.json` follows OpenVEX v1 with Stella Ops-specific `status_notes`, `justification`, `impact_statement`, and `action_statement` text.
- `decision.dsse.json` is the DSSE envelope returned by Signer (see §3). Always include the PEM cert chain (keyless) or KMS key id.
- `rekor.txt` captures `{uuid, logIndex, checkpoint}` from Attestor when the decision is logged to Rekor.
- `metadata.json` binds the DSSE payload back to internal evidence: `{policy_revision, reachability_graph_sha256, runtime_trace_sha256, evidence_cas_uri[], analyzer_versions[], createdBy, createdAt}`.
---
## 2. Evidence production flow
1. **Scanner Worker**
- Generate `reachability.json` + `sbom.cdx.json` per prioritized CVE.
- Store artifacts under CAS and surface URIs via `ReachabilityReplayWriter`.
2. **Policy Engine / VEXer**
- Evaluate reachability states + policy lattice to produce an OpenVEX statement.
- Persist `decision.openvex.json` and forward it to Signer.
3. **Signer & Attestor**
- Sign the OpenVEX payload via DSSE (`payloadType: application/vnd.in-toto+json`) and return `decision.dsse.json`.
- Optionally call Attestor to log the DSSE bundle to Rekor; write `{uuid, logIndex, checkpoint}` to `rekor.txt`.
4. **Bench harness**
- Collect SBOM slice, reachability proof, OpenVEX, DSSE, Rekor metadata, and companion metrics into `bench/findings/CVE-...`.
- Record tool versions + CAS digests under `metadata.json`.
All steps must be deterministic: repeated scans with the same inputs produce identical artifacts and digests.
---
## 3. Signing & transparency requirements
| Artifact | Producer | Format | Notes |
|-------------------------|---------------|----------------------------------------|-------|
| Reachability evidence | Scanner | Canonical JSON (sorted keys) | CAS URI recorded in metadata. |
| SBOM slice | Scanner | CycloneDX 1.6 JSON | Keep only components relevant to the finding. |
| OpenVEX decision | Policy/VEXer | OpenVEX v1 | One statement per `(CVE, product)` tuple. |
| DSSE bundle | Signer | DSSE envelope over OpenVEX payload | Include Fulcio cert or KMS key id. |
| Rekor record (optional) | Attestor | Rekor UUID/index/checkpoint | Store alongside DSSE for offline verification. |
Signer must expose a predicate alias `stella.ops/vexDecision@v1` (see Sprint task `SIGN-VEX-401-018`). Payload = OpenVEX JSON. Rekor logging reuses the existing Attestor `/rekor/entries` pipeline.
---
## 4. Verification tooling
The repo ships two verifiers:
1. `tools/verify.sh` (bash) — wraps `cosign verify-attestation`/`in-toto verify`, Rekor inclusion checks (`rekor-cli logproof`), and digest comparison.
2. `tools/verify.py` — pure-Python offline verifier for air-gapped environments:
- Validates DSSE signature using the embedded Fulcio cert or configured root.
- Recomputes `sha256` over `reachability.json`, `sbom.cdx.json`, and `decision.openvex.json` to ensure the DSSE payload matches.
- Optionally replays reachability by invoking `stella replay --manifest ... --finding CVE-...`.
CLI addition (`stella decision verify`) should shell out to these helpers when `--from bench` is provided.
---
## 5. Metrics & comparison harness
`tools/compare.py` ingests raw outputs from Stella Ops and baseline scanners (Trivy, Syft, Grype, Snyk, Xray) stored under `results/runs/<date>/<scanner>/findings.json`. For each target:
- **False-positive reduction (FPR)** = `1 - (# of findings confirmed true positives / # of baseline findings)`.
- **Mean time to decision (MTTD)** = average wall-clock time between scan start and DSSE-signed OpenVEX emission.
- **Reproducibility score** = `1` if re-running reachability produces identical digests for all artifacts, else `0`; aggregated per run.
`results/summary.csv` columns:
```
target,cve,baseline_scanner,baseline_hits,stella_hits,fp_reduction,mttd_seconds,reproducible,rekor_uuid
```
Automate collection via `Makefile` or `bench/run.sh` pipeline (task `BENCH-AUTO-401-019`).
---
## 6. Publication & README checklist
`bench/README.md` must include:
- High-level workflow diagram (scan → reachability → OpenVEX → DSSE → Rekor → bench).
- Prerequisites (`cosign`, `rekor-cli`, `stella` CLI).
- Quickstart commands:
```bash
./tools/verify.sh CVE-2023-12345 pkg:purl/example@1.2.3
./tools/compare.py --target sample/nginx --baseline trivy --run 2025-11-10
```
- How to recreate a finding: `stella replay --manifest results/runs/.../replay.yaml --finding CVE-...`.
- Contribution guide (where to place new findings, how to update metrics, required metadata).
---
## 7. Implementation tasks (see Sprint 401+)
- `POLICY-VEX-401-010` — emit OpenVEX per finding and publish to bench repo.
- `SIGN-VEX-401-018` — add DSSE predicate + Rekor logging for decision payloads.
- `CLI-VEX-401-011` — new `stella decision` verbs (`export`, `verify`, `compare`).
- `BENCH-AUTO-401-019` — automation to populate `bench/findings/**`, run baseline scanners, and update `results/summary.csv`.
- `DOCS-VEX-401-012` — maintain this playbook + README templates, document verification workflow.
# VEX Evidence Playbook (Bench Repo Blueprint)
> **Status:** Draft – aligns with the “provable vulnerability decisions” advisory (Nov 2025).
> **Owners:** Policy Guild · VEX Lens Guild · CLI Guild · Docs Guild.
This playbook defines the public benchmark repository layout, artifact shapes, verification tooling, and metrics that prove Stella Ops VEX decisions are reproducible, portable, and superior to baseline scanners. Treat it as the contract for every guild contributing artifacts to `bench/`.
---
## 1. Repository layout
```
bench/
README.md # repo overview + quickstart
findings/
CVE-YYYY-NNNNN/ # one folder per advisory/product tuple
evidence/
reachability.json # static+runtime call graph for the finding
sbom.cdx.json # CycloneDX slice containing the involved components
decision.openvex.json # OpenVEX statement (status + justification)
decision.dsse.json # DSSE envelope wrapping the OpenVEX payload
rekor.txt # optional Rekor UUID/index/checkpoint
metadata.json # producer info (policy rev, analyzer digests, CAS URIs)
tools/
verify.sh # shell helper: dsse verify + optional rekor verification
verify.py # python verifier (offline) that recomputes digests
compare.py # baseline diff against Trivy/Syft/Grype/Snyk/Xray outputs
replay.sh # reruns reachability graphs via `stella replay`
results/
summary.csv # FP reduction, MTTD, reproducibility metrics
runs/2025-11-10/ # pinned scanner/policy versions + raw outputs
stella/
findings.json
runtime-facts.ndjson
reachability.manifest.json
trivy/
findings.json
...
```
### File contracts
- `reachability.json` is the canonical export from `cas://reachability/graphs/...` with symbol IDs, call edges, runtime hits, analyzer fingerprints, and CAS references.
- `decision.openvex.json` follows OpenVEX v1 with Stella Ops-specific `status_notes`, `justification`, `impact_statement`, and `action_statement` text.
- `decision.dsse.json` is the DSSE envelope returned by Signer (see §3). Always include the PEM cert chain (keyless) or KMS key id.
- `rekor.txt` captures `{uuid, logIndex, checkpoint}` from Attestor when the decision is logged to Rekor.
- `metadata.json` binds the DSSE payload back to internal evidence: `{policy_revision, reachability_graph_sha256, runtime_trace_sha256, evidence_cas_uri[], analyzer_versions[], createdBy, createdAt}`.
---
## 2. Evidence production flow
1. **Scanner Worker**
- Generate `reachability.json` + `sbom.cdx.json` per prioritized CVE.
- Store artifacts under CAS and surface URIs via `ReachabilityReplayWriter`.
2. **Policy Engine / VEXer**
- Evaluate reachability states + policy lattice to produce an OpenVEX statement.
- Persist `decision.openvex.json` and forward it to Signer.
3. **Signer & Attestor**
- Sign the OpenVEX payload via DSSE (`payloadType: application/vnd.in-toto+json`) and return `decision.dsse.json`.
- Optionally call Attestor to log the DSSE bundle to Rekor; write `{uuid, logIndex, checkpoint}` to `rekor.txt`.
4. **Bench harness**
- Collect SBOM slice, reachability proof, OpenVEX, DSSE, Rekor metadata, and companion metrics into `bench/findings/CVE-...`.
- Record tool versions + CAS digests under `metadata.json`.
All steps must be deterministic: repeated scans with the same inputs produce identical artifacts and digests.
---
## 3. Signing & transparency requirements
| Artifact | Producer | Format | Notes |
|-------------------------|---------------|----------------------------------------|-------|
| Reachability evidence | Scanner | Canonical JSON (sorted keys) | CAS URI recorded in metadata. |
| SBOM slice | Scanner | CycloneDX 1.6 JSON | Keep only components relevant to the finding. |
| OpenVEX decision | Policy/VEXer | OpenVEX v1 | One statement per `(CVE, product)` tuple. |
| DSSE bundle | Signer | DSSE envelope over OpenVEX payload | Include Fulcio cert or KMS key id. |
| Rekor record (optional) | Attestor | Rekor UUID/index/checkpoint | Store alongside DSSE for offline verification. |
Signer must expose a predicate alias `stella.ops/vexDecision@v1` (see Sprint task `SIGN-VEX-401-018`). Payload = OpenVEX JSON. Rekor logging reuses the existing Attestor `/rekor/entries` pipeline.
---
## 4. Verification tooling
The repo ships two verifiers:
1. `tools/verify.sh` (bash) — wraps `cosign verify-attestation`/`in-toto verify`, Rekor inclusion checks (`rekor-cli logproof`), and digest comparison.
2. `tools/verify.py` — pure-Python offline verifier for air-gapped environments:
- Validates DSSE signature using the embedded Fulcio cert or configured root.
- Recomputes `sha256` over `reachability.json`, `sbom.cdx.json`, and `decision.openvex.json` to ensure the DSSE payload matches.
- Optionally replays reachability by invoking `stella replay --manifest ... --finding CVE-...`.
CLI addition (`stella decision verify`) should shell out to these helpers when `--from bench` is provided.
---
## 5. Metrics & comparison harness
`tools/compare.py` ingests raw outputs from Stella Ops and baseline scanners (Trivy, Syft, Grype, Snyk, Xray) stored under `results/runs/<date>/<scanner>/findings.json`. For each target:
- **False-positive reduction (FPR)** = `1 - (# of findings confirmed true positives / # of baseline findings)`.
- **Mean time to decision (MTTD)** = average wall-clock time between scan start and DSSE-signed OpenVEX emission.
- **Reproducibility score** = `1` if re-running reachability produces identical digests for all artifacts, else `0`; aggregated per run.
`results/summary.csv` columns:
```
target,cve,baseline_scanner,baseline_hits,stella_hits,fp_reduction,mttd_seconds,reproducible,rekor_uuid
```
Automate collection via `Makefile` or `bench/run.sh` pipeline (task `BENCH-AUTO-401-019`).
---
## 6. Publication & README checklist
`bench/README.md` must include:
- High-level workflow diagram (scan → reachability → OpenVEX → DSSE → Rekor → bench).
- Prerequisites (`cosign`, `rekor-cli`, `stella` CLI).
- Quickstart commands:
```bash
./tools/verify.sh CVE-2023-12345 pkg:purl/example@1.2.3
./tools/compare.py --target sample/nginx --baseline trivy --run 2025-11-10
```
- How to recreate a finding: `stella replay --manifest results/runs/.../replay.yaml --finding CVE-...`.
- Contribution guide (where to place new findings, how to update metrics, required metadata).
---
## 7. Implementation tasks (see Sprint 401+)
- `POLICY-VEX-401-010` — emit OpenVEX per finding and publish to bench repo.
- `SIGN-VEX-401-018` — add DSSE predicate + Rekor logging for decision payloads.
- `CLI-VEX-401-011` — new `stella decision` verbs (`export`, `verify`, `compare`).
- `BENCH-AUTO-401-019` — automation to populate `bench/findings/**`, run baseline scanners, and update `results/summary.csv`.
- `DOCS-VEX-401-012` — maintain this playbook + README templates, document verification workflow.
Update `docs/implplan/SPRINT_0401_0001_0001_reachability_evidence_chain.md` whenever these tasks move state.

30
docs/implplan/tasks-all.md
View File

@@ -938,11 +938,11 @@
| EXC-25-006 | TODO | | SPRINT_303_docs_tasks_md_iii | Docs Guild · DevEx Guild | docs/modules/excititor | CLEX0101 CLI updates | CLEX0101 CLI updates | DOEX0101 |
| EXC-25-007 | TODO | | SPRINT_304_docs_tasks_md_iv | Docs Guild · DevOps Guild | docs/modules/excititor | UIEX0101 console outputs | UIEX0101 console outputs | DOEX0101 |
| EXCITITOR-AIRGAP-56 | TODO | | SPRINT_110_ingestion_evidence | Excititor Guild · AirGap Guilds | | Air-gap + connector parity depend on schema + attestation readiness. | CONCELIER-GRAPH-21-001; CONCELIER-GRAPH-21-002; ATTEST-PLAN-2001 | EXAG0101 |
| EXCITITOR-AIRGAP-56-001 | DOING (2025-11-22) | | SPRINT_0119_0001_0001_excititor_i | Excititor Core Guild (`src/Excititor/__Libraries/StellaOps.Excititor.Core`) | src/Excititor/__Libraries/StellaOps.Excititor.Core | Wire mirror bundle ingestion paths that preserve upstream digests, bundle IDs, and provenance metadata exactly so offline Advisory-AI/Lens deployments can replay evidence with AOC parity. | EXCITITOR-AIRGAP-56 | EXAG0101 |
| EXCITITOR-AIRGAP-56-001 | DOING (2025-11-22) | 2025-11-22 | SPRINT_0119_0001_0001_excititor_i | Excititor Core Guild (`src/Excititor/__Libraries/StellaOps.Excititor.Core`) | src/Excititor/__Libraries/StellaOps.Excititor.Core | Wire mirror bundle ingestion paths that preserve upstream digests, bundle IDs, and provenance metadata exactly so offline Advisory-AI/Lens deployments can replay evidence with AOC parity. | EXCITITOR-AIRGAP-56 | EXAG0101 |
| EXCITITOR-AIRGAP-57 | TODO | | SPRINT_110_ingestion_evidence | Excititor Guild · AirGap Guilds | | Same as -56 plus Evidence Locker | CONCELIER-GRAPH-21-001; CONCELIER-GRAPH-21-002; ATTEST-PLAN-2001 | EXAG0101 |
| EXCITITOR-AIRGAP-57-001 | TODO | | SPRINT_0119_0001_0001_excititor_i | Excititor AirGap Policy Guild (`src/Excititor/__Libraries/StellaOps.Excititor.Core`) | src/Excititor/__Libraries/StellaOps.Excititor.Core | Enforce sealed-mode policies that disable external connectors, emit actionable remediation errors, and record staleness annotations that Advisory AI can surface as “evidence freshness” signals. Depends on EXCITITOR-AIRGAP-56-001. | EXCITITOR-AIRGAP-57 | EXAG0101 |
| EXCITITOR-AIRGAP-57-001 | BLOCKED (2025-11-22) | 2025-11-22 | SPRINT_0119_0001_0001_excititor_i | Excititor AirGap Policy Guild (`src/Excititor/__Libraries/StellaOps.Excititor.Core`) | src/Excititor/__Libraries/StellaOps.Excititor.Core | Enforce sealed-mode policies that disable external connectors, emit actionable remediation errors, and record staleness annotations that Advisory AI can surface as “evidence freshness” signals. Depends on EXCITITOR-AIRGAP-56-001. | EXCITITOR-AIRGAP-57 | EXAG0101 |
| EXCITITOR-AIRGAP-58 | TODO | | SPRINT_110_ingestion_evidence | Excititor Guild · AirGap Guilds | | Same upstream | CONCELIER-GRAPH-21-001; CONCELIER-GRAPH-21-002; ATTEST-PLAN-2001 | EXAG0101 |
| EXCITITOR-AIRGAP-58-001 | TODO | | SPRINT_0119_0001_0001_excititor_i | Excititor Core + Evidence Locker Guilds | src/Excititor/__Libraries/StellaOps.Excititor.Core | Package tenant-scoped VEX evidence (raw JSON, normalization diff, provenance) into portable bundles tied to timeline events so Advisory AI can hydrate contexts in sealed environments. Depends on EXCITITOR-AIRGAP-57-001. | EXCITITOR-AIRGAP-58 | EXAG0101 |
| EXCITITOR-AIRGAP-58-001 | BLOCKED (2025-11-22) | 2025-11-22 | SPRINT_0119_0001_0001_excititor_i | Excititor Core + Evidence Locker Guilds | src/Excititor/__Libraries/StellaOps.Excititor.Core | Package tenant-scoped VEX evidence (raw JSON, normalization diff, provenance) into portable bundles tied to timeline events so Advisory AI can hydrate contexts in sealed environments. Depends on EXCITITOR-AIRGAP-57-001. | EXCITITOR-AIRGAP-58 | EXAG0101 |
| EXCITITOR-ATTEST-73-001 | DONE | 2025-11-17 | SPRINT_0119_0001_0001_excititor_i | Excititor Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Attestation payloads emitted with supplier identity, justification summary, and scope metadata for trust chaining. | EXCITITOR-ATTEST-01-003 | EXAT0101 |
| EXCITITOR-ATTEST-73-002 | DONE | 2025-11-17 | SPRINT_0119_0001_0001_excititor_i | Excititor Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | APIs link attestation IDs back to observation/linkset/product tuples for provenance citations without derived verdicts. | EXCITITOR-ATTEST-73-001 | EXAT0101 |
| EXCITITOR-CONN-SUSE-01-003 | TODO | | SPRINT_120_excititor_ii | Excititor Guild (SUSE connector) | src/Excititor/__Libraries/StellaOps.Excititor.Connectors.SUSE.RancherVEXHub | DONE (2025-11-09) – Emit provider trust configuration (signer fingerprints, trust tier notes) into the raw provenance envelope so downstream VEX Lens/Policy components can weigh issuers. Connector must not apply weighting or consensus inside ingestion. | EXCITITOR-CONN-SUSE-01-002; EXCITITOR-POLICY-01-001 | EXCN0101 |
@@ -1090,7 +1090,7 @@
| GRAPH-24-101 | TODO | | SPRINT_113_concelier_ii | UI Guild | src/Concelier/StellaOps.Concelier.WebService | GRAPH-24-001 | GRAPH-24-001 | GRUI0101 |
| GRAPH-24-102 | TODO | | SPRINT_120_excititor_ii | UI Guild | src/Excititor/StellaOps.Excititor.WebService | GRAPH-24-101 | GRAPH-24-101 | GRUI0101 |
| GRAPH-28-102 | TODO | | SPRINT_113_concelier_ii | Concelier WebService Guild (src/Concelier/StellaOps.Concelier.WebService) | src/Concelier/StellaOps.Concelier.WebService | | | GRAPI0101 |
| GRAPH-API-28-001 | TODO | | SPRINT_0207_0001_0001_graph | Graph API Guild (src/Graph/StellaOps.Graph.Api) | src/Graph/StellaOps.Graph.Api | Define OpenAPI + JSON schema for graph search/query/paths/diff/export endpoints, including cost metadata and streaming tile schema. | — | ORGR0101 |
| GRAPH-API-28-001 | DOING | | SPRINT_0207_0001_0001_graph | Graph API Guild (src/Graph/StellaOps.Graph.Api) | src/Graph/StellaOps.Graph.Api | Define OpenAPI + JSON schema for graph search/query/paths/diff/export endpoints, including cost metadata and streaming tile schema. | — | ORGR0101 |
| GRAPH-API-28-002 | TODO | | SPRINT_0207_0001_0001_graph | Graph API Guild (src/Graph/StellaOps.Graph.Api) | src/Graph/StellaOps.Graph.Api | Implement `/graph/search` with multi-type index lookup, prefix/exact match, RBAC enforcement, and result ranking + caching. Dependencies: GRAPH-API-28-001. | — | ORGR0101 |
| GRAPH-API-28-003 | TODO | | SPRINT_0207_0001_0001_graph | Graph API Guild (src/Graph/StellaOps.Graph.Api) | src/Graph/StellaOps.Graph.Api | Build query planner + cost estimator for `/graph/query`, stream tiles (nodes/edges/stats) progressively, enforce budgets, provide cursor tokens. Dependencies: GRAPH-API-28-002. | — | ORGR0101 |
| GRAPH-API-28-004 | TODO | | SPRINT_0207_0001_0001_graph | Graph API Guild (src/Graph/StellaOps.Graph.Api) | src/Graph/StellaOps.Graph.Api | Implement `/graph/paths` with depth ≤6, constraint filters, heuristic shortest path search, and optional policy overlay rendering. Dependencies: GRAPH-API-28-003. | — | ORGR0101 |
@@ -1470,7 +1470,7 @@
| PROV-BACKFILL-401-029 | DOING | | SPRINT_0401_0001_0001_reachability_evidence_chain | Platform Guild | `docs/provenance/inline-dsse.md`, `scripts/publish_attestation_with_provenance.sh` | Backfill historical Mongo events with DSSE/Rekor metadata by resolving known attestations per subject digest (wiring ingestion helpers + endpoint tests in progress). | Depends on #1 | RBRE0101 |
| PROV-INDEX-401-030 | TODO | | SPRINT_0401_0001_0001_reachability_evidence_chain | Platform + Ops Guilds | `docs/provenance/inline-dsse.md`, `ops/mongo/indices/events_provenance_indices.js` | Deploy provenance indexes (`events_by_subject_kind_provenance`, etc.) and expose compliance/replay queries. | Depends on #3 | RBRE0101 |
| PROV-INLINE-401-028 | DONE | | SPRINT_0401_0001_0001_reachability_evidence_chain | Authority Guild · Feedser Guild (`docs/provenance/inline-dsse.md`, `src/__Libraries/StellaOps.Provenance.Mongo`) | `docs/provenance/inline-dsse.md`, `src/__Libraries/StellaOps.Provenance.Mongo` | Extend Authority/Feedser event writers to attach inline DSSE + Rekor references on every SBOM/VEX/scan event using `StellaOps.Provenance.Mongo`. | | |
| PROV-OBS-53-001 | TODO | | SPRINT_110_ingestion_evidence | Exporter Guild · AirGap Time Guild · CLI Guild | | PROGRAM-STAFF-1001 | PROGRAM-STAFF-1001 | ATMI0102 |
| PROV-OBS-53-001 | DONE | 2025-11-17 | SPRINT_0513_0001_0001_provenance | Provenance Guild / `src/Provenance/StellaOps.Provenance.Attestation` | src/Provenance/StellaOps.Provenance.Attestation | Implement DSSE/SLSA `BuildDefinition` + `BuildMetadata` models with canonical JSON serializer, Merkle digest helpers, deterministic hashing tests, and sample statements for orchestrator/job/export subjects. | — | PROB0101 |
| PROV-OBS-53-002 | BLOCKED | | SPRINT_0513_0001_0001_provenance | Provenance Guild · Security Guild | src/Provenance/StellaOps.Provenance.Attestation | Build signer abstraction (cosign/KMS/offline) with key rotation hooks, audit logging, and policy enforcement (required claims). Provide unit tests using fake signer + real cosign fixture. Dependencies: PROV-OBS-53-001. | Await CI rerun to clear MSB6006 and verify signer abstraction | PROB0101 |
| PROV-OBS-53-003 | BLOCKED | | SPRINT_0513_0001_0001_provenance | Provenance Guild | src/Provenance/StellaOps.Provenance.Attestation | Deliver `PromotionAttestationBuilder` that materialises the `stella.ops/promotion@v1` predicate (image digest, SBOM/VEX materials, promotion metadata, Rekor proof) and feeds canonicalised payload bytes to Signer via StellaOps.Cryptography. | Blocked on PROV-OBS-53-002 CI verification | PROB0101 |
| PROV-OBS-54-001 | TODO | | SPRINT_0513_0001_0001_provenance | Provenance Guild · Evidence Locker Guild | src/Provenance/StellaOps.Provenance.Attestation | Deliver verification library that validates DSSE signatures, Merkle roots, and timeline chain-of-custody, exposing reusable CLI/service APIs. Include negative-case fixtures and offline timestamp verification. Dependencies: PROV-OBS-53-002. | Starts after PROV-OBS-53-002 clears in CI | PROB0101 |
@@ -2113,9 +2113,9 @@
| WEB-CONSOLE-23-003 | TODO | | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild, Policy Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Add `/console/exports` POST/GET routes coordinating evidence bundle creation, streaming CSV/JSON exports, checksum manifest retrieval, and signed attestation references. Ensure requests honor tenant + policy scopes and expose job tracking metadata. Dependencies: WEB-CONSOLE-23-002. | | |
| WEB-CONSOLE-23-004 | TODO | | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Implement `/console/search` endpoint accepting CVE/GHSA/PURL/SBOM identifiers, performing fan-out queries with caching, ranking, and deterministic tie-breaking. Return typed results for Console navigation; respect result caps and latency SLOs. Dependencies: WEB-CONSOLE-23-003. | | |
| WEB-CONSOLE-23-005 | TODO | | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild, DevOps Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Serve `/console/downloads` JSON manifest (images, charts, offline bundles) sourced from signed registry metadata; include integrity hashes, release notes links, and offline instructions. Provide caching headers and documentation. Dependencies: WEB-CONSOLE-23-004. | | |
| WEB-CONTAINERS-44-001 | DONE | | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Expose `/welcome` state, config discovery endpoint (safe values), and `QUICKSTART_MODE` handling for Console banner; add `/health/liveness`, `/health/readiness`, `/version` if missing. | | |
| WEB-CONTAINERS-45-001 | DONE | | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Ensure readiness endpoints reflect DB/queue readiness, add feature flag toggles via config map, and document NetworkPolicy ports. Dependencies: WEB-CONTAINERS-44-001. | | |
| WEB-CONTAINERS-46-001 | DONE | | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Provide offline-friendly asset serving (no CDN), allow overriding object store endpoints via env, and document fallback behavior. Dependencies: WEB-CONTAINERS-45-001. | | |
| WEB-CONTAINERS-44-001 | DONE | 2025-11-18 | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Expose `/welcome` state, config discovery endpoint (safe values), and `QUICKSTART_MODE` handling for Console banner; add `/health/liveness`, `/health/readiness`, `/version` if missing. | | |
| WEB-CONTAINERS-45-001 | DONE | 2025-11-19 | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Ensure readiness endpoints reflect DB/queue readiness, add feature flag toggles via config map, and document NetworkPolicy ports. Dependencies: WEB-CONTAINERS-44-001. | | |
| WEB-CONTAINERS-46-001 | DONE | 2025-11-19 | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Provide offline-friendly asset serving (no CDN), allow overriding object store endpoints via env, and document fallback behavior. Dependencies: WEB-CONTAINERS-45-001. | | |
| WEB-EXC-25-001 | TODO | | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Implement `/exceptions` API (create, propose, approve, revoke, list, history) with validation, pagination, and audit logging. | | |
| WEB-EXC-25-002 | TODO | | SPRINT_213_web_ii | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Extend `/policy/effective` and `/policy/simulate` responses to include exception metadata and accept overrides for simulations. Dependencies: WEB-EXC-25-001. | | |
| WEB-EXC-25-003 | TODO | | SPRINT_213_web_ii | BE-Base Platform Guild, Platform Events Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Publish `exception.*` events, integrate with notification hooks, enforce rate limits. Dependencies: WEB-EXC-25-002. | | |
@@ -3160,9 +3160,9 @@
| EXCITITOR-AIRGAP-56 | TODO | | SPRINT_110_ingestion_evidence | Excititor Guild · AirGap Guilds | | Air-gap + connector parity depend on schema + attestation readiness. | CONCELIER-GRAPH-21-001; CONCELIER-GRAPH-21-002; ATTEST-PLAN-2001 | EXAG0101 |
| EXCITITOR-AIRGAP-56-001 | DOING (2025-11-22) | 2025-11-22 | SPRINT_0119_0001_0001_excititor_i | Excititor Core Guild (`src/Excititor/__Libraries/StellaOps.Excititor.Core`) | src/Excititor/__Libraries/StellaOps.Excititor.Core | Wire mirror bundle ingestion paths that preserve upstream digests, bundle IDs, and provenance metadata exactly so offline Advisory-AI/Lens deployments can replay evidence with AOC parity. | EXCITITOR-AIRGAP-56 | EXAG0101 |
| EXCITITOR-AIRGAP-57 | TODO | | SPRINT_110_ingestion_evidence | Excititor Guild · AirGap Guilds | | Same as -56 plus Evidence Locker | CONCELIER-GRAPH-21-001; CONCELIER-GRAPH-21-002; ATTEST-PLAN-2001 | EXAG0101 |
| EXCITITOR-AIRGAP-57-001 | TODO | | SPRINT_0119_0001_0001_excititor_i | Excititor AirGap Policy Guild (`src/Excititor/__Libraries/StellaOps.Excititor.Core`) | src/Excititor/__Libraries/StellaOps.Excititor.Core | Enforce sealed-mode policies that disable external connectors, emit actionable remediation errors, and record staleness annotations that Advisory AI can surface as “evidence freshness” signals. Depends on EXCITITOR-AIRGAP-56-001. | EXCITITOR-AIRGAP-57 | EXAG0101 |
| EXCITITOR-AIRGAP-57-001 | BLOCKED (2025-11-22) | 2025-11-22 | SPRINT_0119_0001_0001_excititor_i | Excititor AirGap Policy Guild (`src/Excititor/__Libraries/StellaOps.Excititor.Core`) | src/Excititor/__Libraries/StellaOps.Excititor.Core | Enforce sealed-mode policies that disable external connectors, emit actionable remediation errors, and record staleness annotations that Advisory AI can surface as “evidence freshness” signals. Depends on EXCITITOR-AIRGAP-56-001. | EXCITITOR-AIRGAP-57 | EXAG0101 |
| EXCITITOR-AIRGAP-58 | TODO | | SPRINT_110_ingestion_evidence | Excititor Guild · AirGap Guilds | | Same upstream | CONCELIER-GRAPH-21-001; CONCELIER-GRAPH-21-002; ATTEST-PLAN-2001 | EXAG0101 |
| EXCITITOR-AIRGAP-58-001 | TODO | | SPRINT_0119_0001_0001_excititor_i | Excititor Core + Evidence Locker Guilds | src/Excititor/__Libraries/StellaOps.Excititor.Core | Package tenant-scoped VEX evidence (raw JSON, normalization diff, provenance) into portable bundles tied to timeline events so Advisory AI can hydrate contexts in sealed environments. Depends on EXCITITOR-AIRGAP-57-001. | EXCITITOR-AIRGAP-58 | EXAG0101 |
| EXCITITOR-AIRGAP-58-001 | BLOCKED (2025-11-22) | 2025-11-22 | SPRINT_0119_0001_0001_excititor_i | Excititor Core + Evidence Locker Guilds | src/Excititor/__Libraries/StellaOps.Excititor.Core | Package tenant-scoped VEX evidence (raw JSON, normalization diff, provenance) into portable bundles tied to timeline events so Advisory AI can hydrate contexts in sealed environments. Depends on EXCITITOR-AIRGAP-57-001. | EXCITITOR-AIRGAP-58 | EXAG0101 |
| EXCITITOR-ATTEST-01-003 | DONE | 2025-11-17 | SPRINT_0119_0001_0001_excititor_i | Excititor Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Attestation verifier harness + diagnostics prove DSSE bundle verification without consensus logic. | EXCITITOR-AIAI-31-002; ELOCKER-CONTRACT-2001 | EXAT0101 |
| EXCITITOR-ATTEST-73-001 | DONE | 2025-11-17 | SPRINT_0119_0001_0001_excititor_i | Excititor Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | Attestation payloads emitted with supplier identity, justification summary, and scope metadata for trust chaining. | EXCITITOR-ATTEST-01-003 | EXAT0101 |
| EXCITITOR-ATTEST-73-002 | DONE | 2025-11-17 | SPRINT_0119_0001_0001_excititor_i | Excititor Guild | src/Excititor/__Libraries/StellaOps.Excititor.Core | APIs link attestation IDs back to observation/linkset/product tuples for provenance citations without derived verdicts. | EXCITITOR-ATTEST-73-001 | EXAT0101 |
@@ -3311,7 +3311,7 @@
| GRAPH-24-101 | TODO | | SPRINT_113_concelier_ii | UI Guild | src/Concelier/StellaOps.Concelier.WebService | GRAPH-24-001 | GRAPH-24-001 | GRUI0101 |
| GRAPH-24-102 | TODO | | SPRINT_120_excititor_ii | UI Guild | src/Excititor/StellaOps.Excititor.WebService | GRAPH-24-101 | GRAPH-24-101 | GRUI0101 |
| GRAPH-28-102 | TODO | | SPRINT_113_concelier_ii | Concelier WebService Guild (src/Concelier/StellaOps.Concelier.WebService) | src/Concelier/StellaOps.Concelier.WebService | | | GRAPI0101 |
| GRAPH-API-28-001 | TODO | | SPRINT_0207_0001_0001_graph | Graph API Guild (src/Graph/StellaOps.Graph.Api) | src/Graph/StellaOps.Graph.Api | Define OpenAPI + JSON schema for graph search/query/paths/diff/export endpoints, including cost metadata and streaming tile schema. | — | ORGR0101 |
| GRAPH-API-28-001 | DOING | | SPRINT_0207_0001_0001_graph | Graph API Guild (src/Graph/StellaOps.Graph.Api) | src/Graph/StellaOps.Graph.Api | Define OpenAPI + JSON schema for graph search/query/paths/diff/export endpoints, including cost metadata and streaming tile schema. | — | ORGR0101 |
| GRAPH-API-28-002 | TODO | | SPRINT_0207_0001_0001_graph | Graph API Guild (src/Graph/StellaOps.Graph.Api) | src/Graph/StellaOps.Graph.Api | Implement `/graph/search` with multi-type index lookup, prefix/exact match, RBAC enforcement, and result ranking + caching. Dependencies: GRAPH-API-28-001. | — | ORGR0101 |
| GRAPH-API-28-003 | TODO | | SPRINT_0207_0001_0001_graph | Graph API Guild (src/Graph/StellaOps.Graph.Api) | src/Graph/StellaOps.Graph.Api | Build query planner + cost estimator for `/graph/query`, stream tiles (nodes/edges/stats) progressively, enforce budgets, provide cursor tokens. Dependencies: GRAPH-API-28-002. | — | ORGR0101 |
| GRAPH-API-28-004 | TODO | | SPRINT_0207_0001_0001_graph | Graph API Guild (src/Graph/StellaOps.Graph.Api) | src/Graph/StellaOps.Graph.Api | Implement `/graph/paths` with depth ≤6, constraint filters, heuristic shortest path search, and optional policy overlay rendering. Dependencies: GRAPH-API-28-003. | — | ORGR0101 |
@@ -3691,7 +3691,7 @@
| PROV-BACKFILL-401-029 | DOING | | SPRINT_0401_0001_0001_reachability_evidence_chain | Platform Guild | `docs/provenance/inline-dsse.md`, `scripts/publish_attestation_with_provenance.sh` | Backfill historical Mongo events with DSSE/Rekor metadata by resolving known attestations per subject digest (wiring ingestion helpers + endpoint tests in progress). | Depends on #1 | RBRE0101 |
| PROV-INDEX-401-030 | TODO | | SPRINT_0401_0001_0001_reachability_evidence_chain | Platform + Ops Guilds | `docs/provenance/inline-dsse.md`, `ops/mongo/indices/events_provenance_indices.js` | Deploy provenance indexes (`events_by_subject_kind_provenance`, etc.) and expose compliance/replay queries. | Depends on #3 | RBRE0101 |
| PROV-INLINE-401-028 | DONE | | SPRINT_0401_0001_0001_reachability_evidence_chain | Authority Guild · Feedser Guild (`docs/provenance/inline-dsse.md`, `src/__Libraries/StellaOps.Provenance.Mongo`) | `docs/provenance/inline-dsse.md`, `src/__Libraries/StellaOps.Provenance.Mongo` | Extend Authority/Feedser event writers to attach inline DSSE + Rekor references on every SBOM/VEX/scan event using `StellaOps.Provenance.Mongo`. | | |
| PROV-OBS-53-001 | TODO | | SPRINT_110_ingestion_evidence | Exporter Guild · AirGap Time Guild · CLI Guild | | PROGRAM-STAFF-1001 | PROGRAM-STAFF-1001 | ATMI0102 |
| PROV-OBS-53-001 | DONE | 2025-11-17 | SPRINT_0513_0001_0001_provenance | Provenance Guild / `src/Provenance/StellaOps.Provenance.Attestation` | src/Provenance/StellaOps.Provenance.Attestation | Implement DSSE/SLSA `BuildDefinition` + `BuildMetadata` models with canonical JSON serializer, Merkle digest helpers, deterministic hashing tests, and sample statements for orchestrator/job/export subjects. | — | PROB0101 |
| PROV-OBS-53-002 | BLOCKED | | SPRINT_0513_0001_0001_provenance | Provenance Guild · Security Guild | src/Provenance/StellaOps.Provenance.Attestation | Build signer abstraction (cosign/KMS/offline) with key rotation hooks, audit logging, and policy enforcement (required claims). Provide unit tests using fake signer + real cosign fixture. Dependencies: PROV-OBS-53-001. | Await CI rerun to clear MSB6006 and verify signer abstraction | PROB0101 |
| PROV-OBS-53-003 | BLOCKED | | SPRINT_0513_0001_0001_provenance | Provenance Guild | src/Provenance/StellaOps.Provenance.Attestation | Deliver `PromotionAttestationBuilder` that materialises the `stella.ops/promotion@v1` predicate (image digest, SBOM/VEX materials, promotion metadata, Rekor proof) and feeds canonicalised payload bytes to Signer via StellaOps.Cryptography. | Blocked on PROV-OBS-53-002 CI verification | PROB0101 |
| PROV-OBS-54-001 | TODO | | SPRINT_0513_0001_0001_provenance | Provenance Guild · Evidence Locker Guild | src/Provenance/StellaOps.Provenance.Attestation | Deliver verification library that validates DSSE signatures, Merkle roots, and timeline chain-of-custody, exposing reusable CLI/service APIs. Include negative-case fixtures and offline timestamp verification. Dependencies: PROV-OBS-53-002. | Starts after PROV-OBS-53-002 clears in CI | PROB0101 |
@@ -4334,9 +4334,9 @@
| WEB-CONSOLE-23-003 | TODO | | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild, Policy Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Add `/console/exports` POST/GET routes coordinating evidence bundle creation, streaming CSV/JSON exports, checksum manifest retrieval, and signed attestation references. Ensure requests honor tenant + policy scopes and expose job tracking metadata. Dependencies: WEB-CONSOLE-23-002. | | |
| WEB-CONSOLE-23-004 | TODO | | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Implement `/console/search` endpoint accepting CVE/GHSA/PURL/SBOM identifiers, performing fan-out queries with caching, ranking, and deterministic tie-breaking. Return typed results for Console navigation; respect result caps and latency SLOs. Dependencies: WEB-CONSOLE-23-003. | | |
| WEB-CONSOLE-23-005 | TODO | | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild, DevOps Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Serve `/console/downloads` JSON manifest (images, charts, offline bundles) sourced from signed registry metadata; include integrity hashes, release notes links, and offline instructions. Provide caching headers and documentation. Dependencies: WEB-CONSOLE-23-004. | | |
| WEB-CONTAINERS-44-001 | DONE | | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Expose `/welcome` state, config discovery endpoint (safe values), and `QUICKSTART_MODE` handling for Console banner; add `/health/liveness`, `/health/readiness`, `/version` if missing. | | |
| WEB-CONTAINERS-45-001 | DONE | | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Ensure readiness endpoints reflect DB/queue readiness, add feature flag toggles via config map, and document NetworkPolicy ports. Dependencies: WEB-CONTAINERS-44-001. | | |
| WEB-CONTAINERS-46-001 | DONE | | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Provide offline-friendly asset serving (no CDN), allow overriding object store endpoints via env, and document fallback behavior. Dependencies: WEB-CONTAINERS-45-001. | | |
| WEB-CONTAINERS-44-001 | DONE | 2025-11-18 | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Expose `/welcome` state, config discovery endpoint (safe values), and `QUICKSTART_MODE` handling for Console banner; add `/health/liveness`, `/health/readiness`, `/version` if missing. | | |
| WEB-CONTAINERS-45-001 | DONE | 2025-11-19 | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Ensure readiness endpoints reflect DB/queue readiness, add feature flag toggles via config map, and document NetworkPolicy ports. Dependencies: WEB-CONTAINERS-44-001. | | |
| WEB-CONTAINERS-46-001 | DONE | 2025-11-19 | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Provide offline-friendly asset serving (no CDN), allow overriding object store endpoints via env, and document fallback behavior. Dependencies: WEB-CONTAINERS-45-001. | | |
| WEB-EXC-25-001 | TODO | | SPRINT_0212_0001_0001_web_i | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Implement `/exceptions` API (create, propose, approve, revoke, list, history) with validation, pagination, and audit logging. | | |
| WEB-EXC-25-002 | TODO | | SPRINT_213_web_ii | BE-Base Platform Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Extend `/policy/effective` and `/policy/simulate` responses to include exception metadata and accept overrides for simulations. Dependencies: WEB-EXC-25-001. | | |
| WEB-EXC-25-003 | TODO | | SPRINT_213_web_ii | BE-Base Platform Guild, Platform Events Guild (src/Web/StellaOps.Web) | src/Web/StellaOps.Web | Publish `exception.*` events, integrate with notification hooks, enforce rate limits. Dependencies: WEB-EXC-25-002. | | |

318
docs/reachability/DELIVERY_GUIDE.md
View File

@@ -1,159 +1,159 @@
# Reachability Evidence Delivery Guide
_Last updated: November 8, 2025. Owner: Reachability Tiger Team (Scanner, Signals, Replay, Policy, Authority, UI)._
This guide translates the deterministic reachability blueprint into concrete work streams that average contributors can pick up without re-reading the entire proposal. Use it as the single navigation point when you land a reachability ticket. For a task-centric view of remaining gaps, see `docs/reachability/REACHABILITY_GAP_TASKS.md`.
---
## 1. Scope & Principles
**Goal**: ship a verifiable reachability signal for every scan by chaining SBOM → graph → runtime facts → VEX into DSSE-attested, replayable evidence.
**Principles**
1. **Deterministic inputs** – canonical IDs, sorted payloads, normalized timestamps.
2. **Provable facts** – every artifact has a DSSE envelope anchored in Authority + Rekor mirror.
3. **Replay-first** – manifests pin feed snapshots, analyzer digests, and policies so auditors can rerun.
4. **Least surprise** – same API and file layouts across languages; tests run fixture packs at CI time.
---
## 2. Evidence Chain Overview
| Stage | Producer | Artifact | Requirements |
|-------|----------|----------|--------------|
| SBOM per layer & composed image | Scanner Worker + Sbomer | `sbom.layer.cdx.json`, `sbom.image.cdx.json` | Deterministic CycloneDX 1.6, DSSE envelope, CAS URI |
| Static reachability graph | Scanner Worker lifters (DotNet, Go, Node/Deno, Rust, Swift, JVM, Binary, Shell) | `richgraph-v1.json` + `sha256` | Canonical SymbolIDs, framework entries, predicates, graph hash |
| Runtime facts | Zastava Observer / runtime probes | `runtime-trace.ndjson` (gzip or JSON) | EntryTrace schema, CAS pointer, process/socket/container metadata, optional compression |
| Replay manifest | Scanner Worker + Replay Core | `replay.yaml` | Contains analyzer versions, feed locks, graph hash, runtime trace digests |
| VEX statements | Scanner WebService + Policy Engine | `reachability.json` + OpenVEX doc | Links SBOM attn, graph attn, runtime evidence IDs |
| Signed bundle | Authority + Signer | DSSE envelope referencing above | Support FIPS + PQ variants (Dilithium where required) |
---
## 3. Work Streams (modules + hand-offs)
| Stream | Owner Guild(s) | Key deliverables |
|--------|----------------|------------------|
| **Native symbols & callgraphs** | Scanner Worker · Symbols Guild | Ship `Scanner.Symbols.Native` + `Scanner.CallGraph.Native`, integrate Symbol Manifest v1, demangle Itanium/MSVC names, emit `FuncNode`/`CallEdge` CAS bundles (task `SCANNER-NATIVE-401-015`). |
| **Reachability store** | Signals · BE-Base Platform | Provision shared Mongo collections (`func_nodes`, `call_edges`, `cve_func_hits`), indexes, and repositories plus REST hooks for reuse (task `SIG-STORE-401-016`). |
| **Language lifters** | Scanner Worker | CLI/hosted lifters for DotNet, Go, Node/Deno, JVM, Rust, Swift, Binary, Shell with CAS uploads and richgraph output |
| **Signals ingestion & scoring** | Signals | `/callgraphs`, `/runtime-facts` (JSON + NDJSON/gzip), `/graphs/{id}`, `/reachability/recompute` GA; CAS-backed storage, runtime dedupe, BFS+predicates scoring |
| **Runtime capture** | Zastava + Runtime Guild | EntryTrace/eBPF samplers, NDJSON batches (symbol IDs + timestamps + counts) |
| **Replay evidence** | Replay Core + Scanner Worker | Manifest schema v2, `ReachabilityReplayWriter` integration, hash-lock tests |
| **Authority attestations** | Authority + Signer | DSSE predicates for SBOM, Graph, Replay, VEX; Rekor mirror alignment |
| **Policy & VEX** | Policy Engine + Web + CLI + UI | Accept reachability states, render “Why safe” call paths, CLI/UI explain flows |
| **QA & Docs** | QA + Docs Guilds | `reachbench-2025-expanded` fixtures wired to CI; operator + developer runbooks |
| **Binary quality guardrails (Nov 2026)** | Scanner · Signals · QA | Build-id capture, init-array roots, purl-resolved edges, unknowns emission, and patch-oracle fixtures; see sections 5.7–5.9 |
---
## 4. Sprint Targets
| Sprint | Nickname | Focus | Exit Criteria |
|--------|----------|-------|---------------|
| **401** | Evidence Pipeline | Finish static lifters + CAS graph storage + runtime ingestion endpoint | Graph CAS layout documented, lifter fixtures passing, `/runtime-facts` receives NDJSON batches |
| **402** | Replay & Attest | Manifest v2, DSSE envelopes, Authority/Rekor publishing | Replay packs include hashes + analyzer fingerprint; DSSE statements passed integration; Rekor mirror updated |
| **403** | Policy & Explain | VEX generation, SPL predicates, UI/CLI explainers | Policy engine uses reachability states, CLI `stella graph explain` returns signed paths, UI shows explain drawer |
Each sprint is two weeks; refer to `docs/implplan/SPRINT_0401_0001_0001_reachability_evidence_chain.md` (new) for per-task tracking.
---
## 5. Task Breakdown Cheat Sheet
### 5.1 Scanner Worker
1. **Lifter SDK** – Define `RichGraphWriter`, canonical SymbolID helpers, analyzer interface updates.
2. **Language passes** – deliverables per language: discovery, graph build, framework wiring, predicate extraction, runtime overlay.
3. **Replay hooks** – plug lifter output + runtime traces into `ReachabilityReplayWriter`; enforce CAS registration before emitting manifest references.
4. **Fixture runs** – add tests under `tests/reachability/StellaOps.ScannerSignals.IntegrationTests` to execute lifter outputs against reachbench A/B cases.
### 5.2 Signals Service
1. **Callgraph CAS layout** – migrate from filesystem to CAS (`cas://reachability/graphs/{hash}`), include metadata doc.
2. **Runtime facts API** – accept NDJSON or gzip, dedupe events, compute hit stats, link to graph nodes.
3. **Scoring engine v2** – support multi-state lattice (`Unknown → Observed`), record predicates, blocked edges, runtime evidence CAS URIs.
4. **API responses** – `/graphs/{scanId}` returns graph CAS refs + manifest pointers; `/reachability/recompute` accepts replay manifest IDs.
### 5.3 Replay Core & Authority
1. **Manifest schema v2** – YAML + JSON versions, includes feeds/analyzers/policies.
2. **CAS naming** – standardize `cas://reachability/{kind}/{sha256}`.
3. **DSSE predicate types** – `SbomAttestation`, `GraphAttestation`, `VexAttestation`, `ReplayManifest`.
4. **Authority integration** – new endpoints for submitting reachability predicates, rotation tests, Rekor mirror update instructions.
### 5.4 Policy / Web / UI / CLI
1. **Policy Engine** – ingest reachability fact from Signals, expose via SPL, produce metrics, integrate into explanation tree.
2. **Web API** – join reachability fields in vuln responses, add override endpoints, simulate support.
3. **UI/CLI** – Visual explain drawer/CLI command showing signed call-path, predicates, runtime hits; counterfactual toggles.
4. **VEX emitter** – generate OpenVEX statements with evidence references, DSSE sign via Signer.
### 5.5 Native binaries (build-id + init roots)
- Capture ELF build-id (`.note.gnu.build-id`) alongside soname/path and propagate into `SymbolID`/`code_id` so SBOM/runtime joins stay stable even when paths change.
- Treat `.preinit_array`, `.init_array`, `.ctors`, and `_init` as synthetic graph roots with `phase=load`; include constructors from `DT_NEEDED` deps. Persist the root list in scan evidence.
- Add deterministic tests covering build-id present/absent and init-array edge creation.
### 5.6 PURL-resolved edges
- Annotate every call edge with callee `purl` and `symbol_digest` per `docs/reachability/purl-resolved-edges.md`.
- Update `richgraph-v1` schema, CAS metadata, and CLI/UI explainers to display `purl@version` + demangled name.
- Signals merges graphs by `(purl, symbol_digest)`; Policy uses the same keys when mapping CVE-affected functions.
### 5.7 Unknowns Registry integration
- Emit structured Unknowns when symbol→purl mapping, edge targets, or hashes are ambiguous; write them via Signals API per `docs/signals/unknowns-registry.md`.
- Scoring adds `unknowns_pressure` so `not_affected` claims cannot bypass unresolved evidence.
- UI/CLI should surface unknown chips and triage actions.
### 5.8 Patch-oracle guardrails
- Add `tests/reachability/patch-oracles/**` with paired vuln/fixed binaries and `oracle.yml` expectations (functions/edges added/removed).
- Scanner binary analyzer tests must fail if expected guard functions or edges are missing; CI job ensures determinism.
- See `docs/reachability/patch-oracles.md` for fixture layout and manifest schema.
### 5.9 JS/PHP framework reachability
- Model framework entrypoints explicitly: Express/Fastify/Nest handlers, Laravel/Symfony routes/commands/hooks. Generate graph roots from route/handler catalogs instead of generic `main` only.
- Represent dynamic import/require/include resolution as graph nodes so ambiguity stays visible (`resolution` edges with confidence).
- Keep multi-layer graphs: source-level (TS/JS/PHP) plus bundled output (Webpack/Vite). Merge with runtime hints when available.
- Status model: `always_reachable`, `conditional`, `not_reachable`, `not_analyzed`, `ambiguous`, each with confidence and evidence tags.
- Deliver language-specific profiles + fixture cases to prove coverage; update CLI/UI explainers to show framework route context.
---
## 6. Acceptance Tests
1. **Hash-lock** – reorder analyzer flags and confirm graph hash unchanged.
2. **Replay** – delete caches, replay manifest, verify DSSE + hash equality.
3. **Tamper** – alter single edge and expect VEX verification failure with specific path mismatch.
4. **Golden corpus** – run all reachbench cases; ensure NotReachable vs Reachable twins align with expectations JSON.
5. **Runtime sanity** – feed staged runtime traces and ensure confidence bump + `observed=true` path chips propagate to UI.
---
## 7. Documentation & Runbooks
- Place developer-facing updates here (`docs/reachability`).
- [Function-level evidence guide](function-level-evidence.md) captures the Nov 2025 advisory scope, task references, and schema expectations; keep it in lockstep with sprint status.
- [Reachability runtime runbook](../runbooks/reachability-runtime.md) now documents ingestion, CAS staging, air-gap handling, and troubleshooting—link every runtime feature PR to this guide.
- [VEX Evidence Playbook](../benchmarks/vex-evidence-playbook.md) defines the bench repo layout, artifact shapes, verifier tooling, and metrics; keep it updated when Policy/Signer/CLI features land.
- [Reachability lattice](lattice.md) describes the confidence states, evidence/mitigation kinds, scoring policy, event graph schema, and VEX gates; update it when lattices or probes change.
- [PURL-resolved edges spec](purl-resolved-edges.md) defines the purl + symbol-digest annotation rules for graphs and SBOM joins.
- [Patch-oracles QA pattern](patch-oracles.md) describes the fixture layout and expectations for binary reachability guards.
- [Unknowns registry](../signals/unknowns-registry.md) documents how unresolved symbols/edges are recorded and how scoring uses `unknowns_pressure`.
- [Evidence schema](evidence-schema.md) is the canonical field list for richgraph, runtime facts, and Unknowns CAS objects.
- Update module dossiers (Scanner, Signals, Replay, Authority, Policy, UI) once each guild lands work.
---
## 8. Contact & Rituals
- **Daily reachability stand-up** in `#reachability-build`.
- **Fixture sync** every Friday: QA leads run reachbench matrix, post report to Confluence + link in `docs/reachability/DELIVERY_GUIDE.md`.
- **Decision log** – Append ADRs under `docs/adr/reachability-*` for schema changes.
Keep this guide updated whenever scope shifts or a new sprint is added.
# Reachability Evidence Delivery Guide
_Last updated: November 8, 2025. Owner: Reachability Tiger Team (Scanner, Signals, Replay, Policy, Authority, UI)._
This guide translates the deterministic reachability blueprint into concrete work streams that average contributors can pick up without re-reading the entire proposal. Use it as the single navigation point when you land a reachability ticket. For a task-centric view of remaining gaps, see `docs/reachability/REACHABILITY_GAP_TASKS.md`.
---
## 1. Scope & Principles
**Goal**: ship a verifiable reachability signal for every scan by chaining SBOM → graph → runtime facts → VEX into DSSE-attested, replayable evidence.
**Principles**
1. **Deterministic inputs** – canonical IDs, sorted payloads, normalized timestamps.
2. **Provable facts** – every artifact has a DSSE envelope anchored in Authority + Rekor mirror.
3. **Replay-first** – manifests pin feed snapshots, analyzer digests, and policies so auditors can rerun.
4. **Least surprise** – same API and file layouts across languages; tests run fixture packs at CI time.
---
## 2. Evidence Chain Overview
| Stage | Producer | Artifact | Requirements |
|-------|----------|----------|--------------|
| SBOM per layer & composed image | Scanner Worker + Sbomer | `sbom.layer.cdx.json`, `sbom.image.cdx.json` | Deterministic CycloneDX 1.6, DSSE envelope, CAS URI |
| Static reachability graph | Scanner Worker lifters (DotNet, Go, Node/Deno, Rust, Swift, JVM, Binary, Shell) | `richgraph-v1.json` + `sha256` | Canonical SymbolIDs, framework entries, predicates, graph hash |
| Runtime facts | Zastava Observer / runtime probes | `runtime-trace.ndjson` (gzip or JSON) | EntryTrace schema, CAS pointer, process/socket/container metadata, optional compression |
| Replay manifest | Scanner Worker + Replay Core | `replay.yaml` | Contains analyzer versions, feed locks, graph hash, runtime trace digests |
| VEX statements | Scanner WebService + Policy Engine | `reachability.json` + OpenVEX doc | Links SBOM attn, graph attn, runtime evidence IDs |
| Signed bundle | Authority + Signer | DSSE envelope referencing above | Support FIPS + PQ variants (Dilithium where required) |
---
## 3. Work Streams (modules + hand-offs)
| Stream | Owner Guild(s) | Key deliverables |
|--------|----------------|------------------|
| **Native symbols & callgraphs** | Scanner Worker · Symbols Guild | Ship `Scanner.Symbols.Native` + `Scanner.CallGraph.Native`, integrate Symbol Manifest v1, demangle Itanium/MSVC names, emit `FuncNode`/`CallEdge` CAS bundles (task `SCANNER-NATIVE-401-015`). |
| **Reachability store** | Signals · BE-Base Platform | Provision shared Mongo collections (`func_nodes`, `call_edges`, `cve_func_hits`), indexes, and repositories plus REST hooks for reuse (task `SIG-STORE-401-016`). |
| **Language lifters** | Scanner Worker | CLI/hosted lifters for DotNet, Go, Node/Deno, JVM, Rust, Swift, Binary, Shell with CAS uploads and richgraph output |
| **Signals ingestion & scoring** | Signals | `/callgraphs`, `/runtime-facts` (JSON + NDJSON/gzip), `/graphs/{id}`, `/reachability/recompute` GA; CAS-backed storage, runtime dedupe, BFS+predicates scoring |
| **Runtime capture** | Zastava + Runtime Guild | EntryTrace/eBPF samplers, NDJSON batches (symbol IDs + timestamps + counts) |
| **Replay evidence** | Replay Core + Scanner Worker | Manifest schema v2, `ReachabilityReplayWriter` integration, hash-lock tests |
| **Authority attestations** | Authority + Signer | DSSE predicates for SBOM, Graph, Replay, VEX; Rekor mirror alignment |
| **Policy & VEX** | Policy Engine + Web + CLI + UI | Accept reachability states, render “Why safe” call paths, CLI/UI explain flows |
| **QA & Docs** | QA + Docs Guilds | `reachbench-2025-expanded` fixtures wired to CI; operator + developer runbooks |
| **Binary quality guardrails (Nov 2026)** | Scanner · Signals · QA | Build-id capture, init-array roots, purl-resolved edges, unknowns emission, and patch-oracle fixtures; see sections 5.7–5.9 |
---
## 4. Sprint Targets
| Sprint | Nickname | Focus | Exit Criteria |
|--------|----------|-------|---------------|
| **401** | Evidence Pipeline | Finish static lifters + CAS graph storage + runtime ingestion endpoint | Graph CAS layout documented, lifter fixtures passing, `/runtime-facts` receives NDJSON batches |
| **402** | Replay & Attest | Manifest v2, DSSE envelopes, Authority/Rekor publishing | Replay packs include hashes + analyzer fingerprint; DSSE statements passed integration; Rekor mirror updated |
| **403** | Policy & Explain | VEX generation, SPL predicates, UI/CLI explainers | Policy engine uses reachability states, CLI `stella graph explain` returns signed paths, UI shows explain drawer |
Each sprint is two weeks; refer to `docs/implplan/SPRINT_0401_0001_0001_reachability_evidence_chain.md` (new) for per-task tracking.
---
## 5. Task Breakdown Cheat Sheet
### 5.1 Scanner Worker
1. **Lifter SDK** – Define `RichGraphWriter`, canonical SymbolID helpers, analyzer interface updates.
2. **Language passes** – deliverables per language: discovery, graph build, framework wiring, predicate extraction, runtime overlay.
3. **Replay hooks** – plug lifter output + runtime traces into `ReachabilityReplayWriter`; enforce CAS registration before emitting manifest references.
4. **Fixture runs** – add tests under `tests/reachability/StellaOps.ScannerSignals.IntegrationTests` to execute lifter outputs against reachbench A/B cases.
### 5.2 Signals Service
1. **Callgraph CAS layout** – migrate from filesystem to CAS (`cas://reachability/graphs/{hash}`), include metadata doc.
2. **Runtime facts API** – accept NDJSON or gzip, dedupe events, compute hit stats, link to graph nodes.
3. **Scoring engine v2** – support multi-state lattice (`Unknown → Observed`), record predicates, blocked edges, runtime evidence CAS URIs.
4. **API responses** – `/graphs/{scanId}` returns graph CAS refs + manifest pointers; `/reachability/recompute` accepts replay manifest IDs.
### 5.3 Replay Core & Authority
1. **Manifest schema v2** – YAML + JSON versions, includes feeds/analyzers/policies.
2. **CAS naming** – standardize `cas://reachability/{kind}/{sha256}`.
3. **DSSE predicate types** – `SbomAttestation`, `GraphAttestation`, `VexAttestation`, `ReplayManifest`.
4. **Authority integration** – new endpoints for submitting reachability predicates, rotation tests, Rekor mirror update instructions.
### 5.4 Policy / Web / UI / CLI
1. **Policy Engine** – ingest reachability fact from Signals, expose via SPL, produce metrics, integrate into explanation tree.
2. **Web API** – join reachability fields in vuln responses, add override endpoints, simulate support.
3. **UI/CLI** – Visual explain drawer/CLI command showing signed call-path, predicates, runtime hits; counterfactual toggles.
4. **VEX emitter** – generate OpenVEX statements with evidence references, DSSE sign via Signer.
### 5.5 Native binaries (build-id + init roots)
- Capture ELF build-id (`.note.gnu.build-id`) alongside soname/path and propagate into `SymbolID`/`code_id` so SBOM/runtime joins stay stable even when paths change.
- Treat `.preinit_array`, `.init_array`, `.ctors`, and `_init` as synthetic graph roots with `phase=load`; include constructors from `DT_NEEDED` deps. Persist the root list in scan evidence.
- Add deterministic tests covering build-id present/absent and init-array edge creation.
### 5.6 PURL-resolved edges
- Annotate every call edge with callee `purl` and `symbol_digest` per `docs/reachability/purl-resolved-edges.md`.
- Update `richgraph-v1` schema, CAS metadata, and CLI/UI explainers to display `purl@version` + demangled name.
- Signals merges graphs by `(purl, symbol_digest)`; Policy uses the same keys when mapping CVE-affected functions.
### 5.7 Unknowns Registry integration
- Emit structured Unknowns when symbol→purl mapping, edge targets, or hashes are ambiguous; write them via Signals API per `docs/signals/unknowns-registry.md`.
- Scoring adds `unknowns_pressure` so `not_affected` claims cannot bypass unresolved evidence.
- UI/CLI should surface unknown chips and triage actions.
### 5.8 Patch-oracle guardrails
- Add `tests/reachability/patch-oracles/**` with paired vuln/fixed binaries and `oracle.yml` expectations (functions/edges added/removed).
- Scanner binary analyzer tests must fail if expected guard functions or edges are missing; CI job ensures determinism.
- See `docs/reachability/patch-oracles.md` for fixture layout and manifest schema.
### 5.9 JS/PHP framework reachability
- Model framework entrypoints explicitly: Express/Fastify/Nest handlers, Laravel/Symfony routes/commands/hooks. Generate graph roots from route/handler catalogs instead of generic `main` only.
- Represent dynamic import/require/include resolution as graph nodes so ambiguity stays visible (`resolution` edges with confidence).
- Keep multi-layer graphs: source-level (TS/JS/PHP) plus bundled output (Webpack/Vite). Merge with runtime hints when available.
- Status model: `always_reachable`, `conditional`, `not_reachable`, `not_analyzed`, `ambiguous`, each with confidence and evidence tags.
- Deliver language-specific profiles + fixture cases to prove coverage; update CLI/UI explainers to show framework route context.
---
## 6. Acceptance Tests
1. **Hash-lock** – reorder analyzer flags and confirm graph hash unchanged.
2. **Replay** – delete caches, replay manifest, verify DSSE + hash equality.
3. **Tamper** – alter single edge and expect VEX verification failure with specific path mismatch.
4. **Golden corpus** – run all reachbench cases; ensure NotReachable vs Reachable twins align with expectations JSON.
5. **Runtime sanity** – feed staged runtime traces and ensure confidence bump + `observed=true` path chips propagate to UI.
---
## 7. Documentation & Runbooks
- Place developer-facing updates here (`docs/reachability`).
- [Function-level evidence guide](function-level-evidence.md) captures the Nov 2025 advisory scope, task references, and schema expectations; keep it in lockstep with sprint status.
- [Reachability runtime runbook](../runbooks/reachability-runtime.md) now documents ingestion, CAS staging, air-gap handling, and troubleshooting—link every runtime feature PR to this guide.
- [VEX Evidence Playbook](../benchmarks/vex-evidence-playbook.md) defines the bench repo layout, artifact shapes, verifier tooling, and metrics; keep it updated when Policy/Signer/CLI features land.
- [Reachability lattice](lattice.md) describes the confidence states, evidence/mitigation kinds, scoring policy, event graph schema, and VEX gates; update it when lattices or probes change.
- [PURL-resolved edges spec](purl-resolved-edges.md) defines the purl + symbol-digest annotation rules for graphs and SBOM joins.
- [Patch-oracles QA pattern](patch-oracles.md) describes the fixture layout and expectations for binary reachability guards.
- [Unknowns registry](../signals/unknowns-registry.md) documents how unresolved symbols/edges are recorded and how scoring uses `unknowns_pressure`.
- [Evidence schema](evidence-schema.md) is the canonical field list for richgraph, runtime facts, and Unknowns CAS objects.
- Update module dossiers (Scanner, Signals, Replay, Authority, Policy, UI) once each guild lands work.
---
## 8. Contact & Rituals
- **Daily reachability stand-up** in `#reachability-build`.
- **Fixture sync** every Friday: QA leads run reachbench matrix, post report to Confluence + link in `docs/reachability/DELIVERY_GUIDE.md`.
- **Decision log** – Append ADRs under `docs/adr/reachability-*` for schema changes.
Keep this guide updated whenever scope shifts or a new sprint is added.