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/technical/cicd/sarif-integration.md
+++ b/docs/technical/cicd/sarif-integration.md
@@ -219,6 +219,100 @@ stellaops scan image:tag --output-format sarif --tier executed,tainted_sink
 stellaops smart-diff --output-format sarif --min-priority 0.7
 ```

+---
+
+## StellaOps Property Keys
+
+> **Sprint:** SPRINT_20260112_008_DOCS_path_witness_contracts (PW-DOC-003)
+
+SARIF `properties` bag extensions for StellaOps-specific metadata.
+
+### Result-Level Properties
+
+| Property Key | Type | Description |
+|--------------|------|-------------|
+| `stellaops/nodeHash` | string | Canonical node hash (`sha256:<hex>`) for static/runtime joining |
+| `stellaops/pathHash` | string | Canonical path hash for full reachability path |
+| `stellaops/topKNodeHashes` | array | Top-K node hashes for efficient lookup |
+| `stellaops/evidenceUri` | string | `cas://<hash>` URI to evidence bundle |
+| `stellaops/attestationUri` | string | `cas://<hash>` URI to DSSE envelope |
+| `stellaops/rekorUri` | string | Rekor transparency log entry URL |
+| `stellaops/witnessId` | string | Path witness identifier |
+| `stellaops/witnessHash` | string | BLAKE3 hash of witness payload |
+
+### Run-Level Properties
+
+| Property Key | Type | Description |
+|--------------|------|-------------|
+| `stellaops/scanId` | string | UUID of the scan |
+| `stellaops/graphHash` | string | BLAKE3 hash of the rich graph |
+| `stellaops/sbomDigest` | string | SHA256 digest of source SBOM |
+| `stellaops/feedSnapshot` | string | ISO8601 timestamp of feed data |
+
+### Example with StellaOps Properties
+
+```json
+{
+  "results": [
+    {
+      "ruleId": "SDIFF001",
+      "level": "warning",
+      "message": {
+        "text": "CVE-2024-1234 became reachable via 3-hop path"
+      },
+      "locations": [
+        {
+          "logicalLocations": [
+            {
+              "name": "pkg:npm/lodash@4.17.20",
+              "kind": "package"
+            },
+            {
+              "name": "lodash.merge(object, object)",
+              "kind": "function"
+            }
+          ]
+        }
+      ],
+      "properties": {
+        "vulnerability": "CVE-2024-1234",
+        "tier": "executed",
+        "direction": "increased",
+        "stellaops/nodeHash": "sha256:a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd",
+        "stellaops/pathHash": "sha256:fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321",
+        "stellaops/topKNodeHashes": [
+          "sha256:entry1111111111111111111111111111111111111111111111111111111111",
+          "sha256:sink22222222222222222222222222222222222222222222222222222222222"
+        ],
+        "stellaops/evidenceUri": "cas://sha256:evidence123...",
+        "stellaops/attestationUri": "cas://sha256:dsse456...",
+        "stellaops/rekorUri": "https://rekor.sigstore.dev/api/v1/log/entries/abc123",
+        "stellaops/witnessId": "550e8400-e29b-41d4-a716-446655440000"
+      }
+    }
+  ]
+}
+```
+
+### Joining Static and Runtime Evidence
+
+Use `stellaops/nodeHash` to correlate:
+
+1. **Static analysis** findings (SARIF from Scanner)
+2. **Runtime telemetry** (execution traces from agents)
+3. **Policy decisions** (gating results)
+
+```bash
+# Query findings by node hash
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://scanner.example.com/api/v1/findings?nodeHash=sha256:a1b2c3..."
+
+# Verify path witness by hash
+stellaops witness verify --path-hash sha256:fedcba...
+```
+
+---
+
 ## Troubleshooting

 ### SARIF Validation Errors