tests fixes and some product advisories tunes ups

2026-01-30 07:57:43 +02:00
parent 644887997c
commit 55744f6a39
345 changed files with 26290 additions and 2267 deletions
--- a/docs/modules/binary-index/architecture.md
+++ b/docs/modules/binary-index/architecture.md
@@ -1496,5 +1496,101 @@ A mismatch fails the blob replay verification step.

 ---

-*Document Version: 1.2.0*
-*Last Updated: 2026-01-21*
+## 12. Binary Micro-Witnesses
+
+Binary micro-witnesses provide cryptographic proof of patch status at the binary level. They formalize the output of BinaryIndex's semantic diffing capabilities into an auditor-friendly, portable format.
+
+### 12.1 Overview
+
+A micro-witness is a DSSE (Dead Simple Signing Envelope) predicate that captures:
+- Subject binary digest (SHA-256)
+- CVE/patch reference
+- Function-level evidence with confidence scores
+- Delta-Sig fingerprint hash
+- Tool versions and analysis metadata
+- Optional SBOM component mapping
+
+### 12.2 Predicate Schema
+
+**Predicate Type:** `https://stellaops.dev/predicates/binary-micro-witness@v1`
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "binary": {
+    "digest": "sha256:...",
+    "purl": "pkg:deb/debian/openssl@3.0.11",
+    "arch": "linux-amd64",
+    "filename": "libssl.so.3"
+  },
+  "cve": {
+    "id": "CVE-2024-0567",
+    "advisory": "https://...",
+    "patchCommit": "abc123"
+  },
+  "verdict": "patched",
+  "confidence": 0.95,
+  "evidence": [
+    {
+      "function": "SSL_CTX_new",
+      "state": "patched",
+      "score": 0.97,
+      "method": "semantic_ksg",
+      "hash": "sha256:..."
+    }
+  ],
+  "deltaSigDigest": "sha256:...",
+  "sbomRef": {
+    "sbomDigest": "sha256:...",
+    "purl": "pkg:...",
+    "bomRef": "component-ref"
+  },
+  "tooling": {
+    "binaryIndexVersion": "2.1.0",
+    "lifter": "b2r2",
+    "matchAlgorithm": "semantic_ksg"
+  },
+  "computedAt": "2026-01-28T12:00:00Z"
+}
+```
+
+### 12.3 Verdicts
+
+| Verdict | Meaning |
+|---------|---------|
+| `patched` | Binary matches patched version signature |
+| `vulnerable` | Binary matches vulnerable version signature |
+| `inconclusive` | Unable to determine (insufficient evidence) |
+| `partial` | Some functions patched, others not |
+
+### 12.4 CLI Commands
+
+```bash
+# Generate a micro-witness
+stella witness generate /path/to/binary --cve CVE-2024-0567 --sbom sbom.json --output witness.json
+
+# Verify a micro-witness
+stella witness verify witness.json --offline
+
+# Create portable bundle for air-gapped verification
+stella witness bundle witness.json --output ./audit-bundle
+```
+
+### 12.5 Integration with Rekor
+
+When `--rekor` is specified during generation, witnesses are logged to the Rekor transparency log using v2 tile-based inclusion proofs. This provides tamper-evidence and enables auditors to verify witnesses weren't backdated.
+
+Offline verification bundles include tile proofs for air-gapped environments.
+
+### 12.6 Related Documentation
+
+- **Auditor Guide:** `docs/guides/binary-micro-witness-verification.md`
+- **Predicate Schema:** `src/Attestor/StellaOps.Attestor.Types/schemas/stellaops-binary-micro-witness.v1.schema.json`
+- **CLI Commands:** `src/Cli/StellaOps.Cli/Commands/Witness/`
+- **Demo Bundle:** `demos/binary-micro-witness/`
+- **Sprint:** `docs-archived/implplan/SPRINT_0128_001_BinaryIndex_binary_micro_witness.md`
+
+---
+
+*Document Version: 1.3.0*
+*Last Updated: 2026-01-28*