new advisories work and features gaps work

2026-01-14 18:39:19 +02:00
parent 95d5898650
commit 15aeac8e8b
148 changed files with 16731 additions and 554 deletions
--- a/docs/modules/reach-graph/guides/reachability.md
+++ b/docs/modules/reach-graph/guides/reachability.md
@@ -42,6 +42,121 @@
 - Ensure `analysisId` is propagated from Scanner/Zastava into Signals ingest to keep replay manifests linked.
 - Keep feeds frozen for reproducibility; avoid external downloads in union preparation.

+---
+
+## Node Hash Joins and Runtime Evidence Linkage
+
+Sprint: SPRINT_20260112_008_DOCS_path_witness_contracts (PW-DOC-002)
+
+### Overview
+
+Node hashes provide a canonical way to join static reachability analysis with runtime observations. Each node in a callgraph can be identified by a stable hash computed from its PURL and symbol information, enabling:
+
+1. **Static-to-runtime correlation**: Match runtime stack traces to static callgraph nodes
+2. **Cross-scan consistency**: Compare reachability across different analysis runs
+3. **Evidence linking**: Associate attestations with specific code paths
+
+### Node Hash Recipe
+
+A node hash is computed as:
+
+```
+nodeHash = SHA256(normalize(purl) + ":" + normalize(symbol))
+```
+
+Where:
+- `normalize(purl)` lowercases the PURL and sorts qualifiers alphabetically
+- `normalize(symbol)` removes whitespace and normalizes platform-specific decorations
+
+Example:
+```json
+{
+  "purl": "pkg:npm/express@4.18.2",
+  "symbol": "Router.handle",
+  "nodeHash": "sha256:a1b2c3d4..."
+}
+```
+
+### Path Hash and Top-K Selection
+
+A path hash identifies a specific call path from entrypoint to sink:
+
+```
+pathHash = SHA256(entryNodeHash + ":" + joinedIntermediateHashes + ":" + sinkNodeHash)
+```
+
+For long paths, only the **top-K** most significant nodes are included (default K=10):
+- Entry node (always included)
+- Sink node (always included)  
+- Intermediate nodes ranked by call frequency or security relevance
+
+### Runtime Evidence Linkage
+
+Runtime observations from Zastava can be linked to static analysis using node hashes:
+
+| Field | Description |
+|-------|-------------|
+| `observedNodeHashes` | Node hashes seen at runtime |
+| `observedPathHashes` | Path hashes confirmed by runtime traces |
+| `runtimeEvidenceAt` | Timestamp of runtime observation (RFC3339) |
+| `callstackHash` | Hash of the observed call stack |
+
+### Join Example
+
+To correlate static reachability with runtime evidence:
+
+```sql
+-- Find statically-reachable vulnerabilities confirmed at runtime
+SELECT 
+  s.vulnerability_id,
+  s.path_hash,
+  r.observed_at
+FROM static_reachability s
+JOIN runtime_observations r 
+  ON s.sink_node_hash = ANY(r.observed_node_hashes)
+WHERE s.reachable = true
+  AND r.observed_at > NOW() - INTERVAL '7 days';
+```
+
+### SARIF Integration
+
+Node hashes are exposed in SARIF outputs via `stellaops/*` property keys:
+
+```json
+{
+  "results": [{
+    "ruleId": "CVE-2024-1234",
+    "properties": {
+      "stellaops/nodeHash": "sha256:abc123...",
+      "stellaops/pathHash": "sha256:def456...",
+      "stellaops/topKNodeHashes": ["sha256:...", "sha256:..."],
+      "stellaops/evidenceUri": "cas://evidence/...",
+      "stellaops/observedAtRuntime": true
+    }
+  }]
+}
+```
+
+### Policy Gate Usage
+
+Policy rules can reference node and path hashes for fine-grained control:
+
+```yaml
+rules:
+  - name: block-confirmed-critical-path
+    match:
+      severity: CRITICAL
+      reachability:
+        pathHash:
+          exists: true
+        observedAtRuntime: true
+    action: block
+```
+
+See `policies/path-gates-advanced.yaml` for comprehensive examples.
+
+---
+
 ## References
 - Schema: `docs/modules/reach-graph/schemas/runtime-static-union-schema.md`
 - Delivery guide: `docs/modules/reach-graph/guides/DELIVERY_GUIDE.md`