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/contracts/witness-v1.md
+++ b/docs/contracts/witness-v1.md
@@ -183,6 +183,140 @@ The following constants are used for DSSE envelope creation and verification:

 ---

+## Canonical Predicate Type and Aliases
+
+> **Sprint:** SPRINT_20260112_004_SCANNER_path_witness_nodehash  
+> **Sprint:** SPRINT_20260112_008_DOCS_path_witness_contracts (PW-DOC-001)
+
+The **canonical predicate type** for path witnesses is:
+
+```
+https://stella.ops/predicates/path-witness/v1
+```
+
+The following **aliases** are recognized for backward compatibility:
+
+| Alias | Status |
+|-------|--------|
+| `stella.ops/pathWitness@v1` | Active (legacy short form) |
+| `https://stella.ops/pathWitness/v1` | Active (URL variant) |
+
+**Consumers must accept all aliases when verifying**; producers should emit the canonical form.
+
+---
+
+## Node Hash Recipe
+
+Canonical node hash recipe for deterministic static/runtime evidence joining.
+
+### Recipe
+
+```
+NodeHash = SHA256(normalize(PURL) + ":" + normalize(SYMBOL_FQN))
+```
+
+Output format: `sha256:<64-hex-chars>`
+
+### PURL Normalization Rules
+
+1. Lowercase scheme (`pkg:`)
+2. Lowercase type (e.g., `NPM` -> `npm`)
+3. Preserve namespace/name case (some ecosystems are case-sensitive)
+4. Sort qualifiers alphabetically by key
+5. Remove trailing slashes
+6. Normalize empty version to `unversioned`
+
+### Symbol FQN Normalization Rules
+
+1. Trim whitespace
+2. Normalize multiple dots (`..`) to single dot
+3. Normalize signature whitespace: `(type,type)` -> `(type, type)`
+4. Empty signatures become `()`
+5. Replace `_` type placeholders for module-level functions
+
+### Example
+
+```
+Input:
+  PURL: pkg:npm/lodash@4.17.21
+  Symbol: lodash.merge(object, object)
+
+Normalized Input:
+  "pkg:npm/lodash@4.17.21:lodash.merge(object, object)"
+
+Output:
+  sha256:a1b2c3d4e5f6... (64 hex chars)
+```
+
+### Implementation
+
+See `src/__Libraries/StellaOps.Reachability.Core/NodeHashRecipe.cs`
+
+---
+
+## Path Hash Recipe
+
+Canonical path hash recipe for deterministic path fingerprinting.
+
+### Recipe
+
+```
+PathHash = SHA256(nodeHash1 + ">" + nodeHash2 + ">" + ... + nodeHashN)
+```
+
+The `>` separator represents directed edges in the path.
+
+### Top-K Selection
+
+For efficiency, witnesses include a top-K subset of node hashes:
+
+1. Take first K/2 nodes (entry points)
+2. Take last K/2 nodes (exit/vulnerable points)
+3. Deduplicate while preserving order
+4. Default K = 10
+
+### PathFingerprint Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `path_hash` | string | `sha256:<hex>` of full path |
+| `node_count` | integer | Total nodes in path |
+| `top_k_node_hashes` | array | Top-K node hashes for lookup |
+| `source_node_hash` | string | Hash of entry node |
+| `sink_node_hash` | string | Hash of vulnerable sink |
+
+### Implementation
+
+See `src/__Libraries/StellaOps.Reachability.Core/PathHashRecipe.cs`
+
+---
+
+## Evidence URI Fields
+
+Path witnesses may include URIs to supporting evidence:
+
+| Field | Format | Description |
+|-------|--------|-------------|
+| `graph_uri` | `cas://<hash>` | Content-addressed graph reference |
+| `sbom_uri` | `cas://<hash>` | SBOM used during analysis |
+| `attestation_uri` | `cas://<hash>` | DSSE envelope reference |
+| `rekor_uri` | `https://rekor.sigstore.dev/...` | Transparency log entry |
+
+Example:
+
+```json
+{
+  "evidence_uris": {
+    "graph": "cas://sha256:abc123...",
+    "sbom": "cas://sha256:def456...",
+    "attestation": "cas://sha256:ghi789...",
+    "rekor": "https://rekor.sigstore.dev/api/v1/log/entries/abc123def456"
+  }
+}
+```
+
+---
+
 ## DSSE Signing

 Witnesses are signed using [DSSE (Dead Simple Signing Envelope)](https://github.com/secure-systems-lab/dsse):