Merge branch 'main' of https://git.stella-ops.org/stella-ops.org/git.stella-ops.org

2025-12-26 15:19:07 +02:00
parent 907783f625 c8f3120174
commit 41f3ac7aba
25 changed files with 3377 additions and 132 deletions
--- a/docs/modules/binaryindex/architecture.md
+++ b/docs/modules/binaryindex/architecture.md
@@ -436,6 +436,143 @@ Binary matches are recorded as proof segments:

 ---

+## 5b. Fix Evidence Chain
+
+The **Fix Evidence Chain** provides auditable proof of why a CVE is marked as fixed (or not) for a specific distro/package combination. This is critical for patch-aware backport handling where package versions can be misleading.
+
+### 5b.1 Evidence Sources
+
+| Source | Confidence | Description |
+|--------|------------|-------------|
+| **Security Feed (OVAL)** | 0.95-0.99 | Authoritative feed from distro (Debian Security Tracker, Red Hat OVAL) |
+| **Patch Header (DEP-3)** | 0.87-0.95 | CVE reference in Debian/Ubuntu patch metadata |
+| **Changelog** | 0.75-0.85 | CVE mention in debian/changelog or RPM %changelog |
+| **Upstream Patch Match** | 0.90 | Binary diff matches known upstream fix |
+
+### 5b.2 Evidence Storage
+
+Evidence is stored in two PostgreSQL tables:
+
+```sql
+-- Fix index: one row per (distro, release, source_pkg, cve_id)
+CREATE TABLE binaries.cve_fix_index (
+    id UUID PRIMARY KEY,
+    tenant_id TEXT NOT NULL,
+    distro TEXT NOT NULL,        -- debian, ubuntu, alpine, rhel
+    release TEXT NOT NULL,       -- bookworm, jammy, v3.19
+    source_pkg TEXT NOT NULL,
+    cve_id TEXT NOT NULL,
+    state TEXT NOT NULL,         -- fixed, vulnerable, not_affected, wontfix, unknown
+    fixed_version TEXT,
+    method TEXT NOT NULL,        -- security_feed, changelog, patch_header, upstream_match
+    confidence DECIMAL(3,2) NOT NULL,
+    evidence_id UUID REFERENCES binaries.fix_evidence(id),
+    snapshot_id UUID,
+    indexed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    UNIQUE (tenant_id, distro, release, source_pkg, cve_id)
+);
+
+-- Evidence blobs: audit trail
+CREATE TABLE binaries.fix_evidence (
+    id UUID PRIMARY KEY,
+    tenant_id TEXT NOT NULL,
+    evidence_type TEXT NOT NULL, -- changelog, patch_header, security_feed
+    source_file TEXT,            -- Path to source file (changelog, patch)
+    source_sha256 TEXT,          -- Hash of source file
+    excerpt TEXT,                -- Relevant snippet (max 1KB)
+    metadata JSONB NOT NULL,     -- Structured metadata
+    snapshot_id UUID,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+### 5b.3 Evidence Types
+
+**ChangelogEvidence:**
+```json
+{
+  "evidence_type": "changelog",
+  "source_file": "debian/changelog",
+  "excerpt": "* Fix CVE-2024-0727: PKCS12 decoding crash",
+  "metadata": {
+    "version": "3.0.11-1~deb12u2",
+    "line_number": 5
+  }
+}
+```
+
+**PatchHeaderEvidence:**
+```json
+{
+  "evidence_type": "patch_header",
+  "source_file": "debian/patches/CVE-2024-0727.patch",
+  "excerpt": "CVE: CVE-2024-0727\nOrigin: upstream, https://github.com/openssl/commit/abc123",
+  "metadata": {
+    "patch_sha256": "abc123def456..."
+  }
+}
+```
+
+**SecurityFeedEvidence:**
+```json
+{
+  "evidence_type": "security_feed",
+  "metadata": {
+    "feed_id": "debian-security-tracker",
+    "entry_id": "DSA-5678-1",
+    "published_at": "2024-01-15T10:00:00Z"
+  }
+}
+```
+
+### 5b.4 Confidence Resolution
+
+When multiple evidence sources exist for the same CVE, the system keeps the **highest confidence** entry:
+
+```csharp
+ON CONFLICT (tenant_id, distro, release, source_pkg, cve_id)
+DO UPDATE SET
+    confidence = GREATEST(existing.confidence, new.confidence),
+    method = CASE
+        WHEN existing.confidence < new.confidence THEN new.method
+        ELSE existing.method
+    END,
+    evidence_id = CASE
+        WHEN existing.confidence < new.confidence THEN new.evidence_id
+        ELSE existing.evidence_id
+    END
+```
+
+### 5b.5 Parsers
+
+The following parsers extract CVE fix information:
+
+| Parser | Distros | Input | Confidence |
+|--------|---------|-------|------------|
+| `DebianChangelogParser` | Debian, Ubuntu | debian/changelog | 0.80 |
+| `PatchHeaderParser` | Debian, Ubuntu | debian/patches/*.patch (DEP-3) | 0.87 |
+| `AlpineSecfixesParser` | Alpine | APKBUILD secfixes block | 0.95 |
+| `RpmChangelogParser` | RHEL, Fedora, CentOS | RPM spec %changelog | 0.75 |
+
+### 5b.6 Query Flow
+
+```mermaid
+sequenceDiagram
+    participant SW as Scanner.Worker
+    participant BVS as BinaryVulnerabilityService
+    participant FIR as FixIndexRepository
+    participant PG as PostgreSQL
+
+    SW->>BVS: GetFixStatusAsync(debian, bookworm, openssl, CVE-2024-0727)
+    BVS->>FIR: GetFixStatusAsync(...)
+    FIR->>PG: SELECT FROM cve_fix_index WHERE ...
+    PG-->>FIR: FixIndexEntry (state=fixed, confidence=0.87)
+    FIR-->>BVS: FixStatusResult
+    BVS-->>SW: {state: Fixed, confidence: 0.87, method: PatchHeader}
+```
+
+---
+
 ## 6. Security Considerations

 ### 6.1 Trust Boundaries