docs consolidation and others

2026-01-06 19:02:21 +02:00
parent d7bdca6d97
commit 4789027317
849 changed files with 16551 additions and 66770 deletions
--- a/docs/modules/reach-graph/guides/cve-symbol-mapping.md
+++ b/docs/modules/reach-graph/guides/cve-symbol-mapping.md
@@ -0,0 +1,143 @@
+# CVE-to-Symbol Mapping
+
+_Last updated: 2025-12-22. Owner: Scanner Guild + Concelier Guild._
+
+This document describes how StellaOps maps CVE identifiers to specific binary symbols/functions for reachability slices.
+
+---
+
+## 1. Overview
+
+To determine if a vulnerability is reachable, StellaOps resolves:
+
+- **CVE identifiers** (e.g., `CVE-2024-1234`)
+- **Package coordinates** (e.g., `pkg:npm/lodash@4.17.21`)
+- **Affected symbols** (e.g., `lodash.template`, `openssl:EVP_PKEY_decrypt`)
+
+The mapping is used by `SliceExtractor` to target the right symbols and by downstream VEX decisions.
+
+---
+
+## 2. Data Sources
+
+### 2.1 Patch Diff Surfaces (Preferred)
+
+Highest-fidelity source: compute method-level diffs between vulnerable and fixed versions.
+
+**Implementation**: `StellaOps.Scanner.VulnSurfaces`
+
+### 2.2 Advisory Linksets (Concelier)
+
+Scanner queries Concelier's LNM linksets for package coordinates and optional symbol hints.
+
+**Implementation**: `StellaOps.Scanner.Advisory` -> Concelier `/v1/lnm/linksets/{cveId}` or `/v1/lnm/linksets/search`
+
+### 2.3 Offline Bundles
+
+For air-gapped environments, precomputed bundles map CVEs to packages and symbols.
+
+**Implementation**: `FileAdvisoryBundleStore`
+
+---
+
+## 3. Service Contracts
+
+### 3.1 CVE -> Package/Symbol Mapping
+
+```csharp
+public interface IAdvisoryClient
+{
+    Task<AdvisorySymbolMapping?> GetCveSymbolsAsync(string cveId, CancellationToken ct = default);
+}
+
+public sealed record AdvisorySymbolMapping
+{
+    public required string CveId { get; init; }
+    public ImmutableArray<AdvisoryPackageSymbols> Packages { get; init; }
+    public required string Source { get; init; } // "concelier" | "bundle"
+}
+
+public sealed record AdvisoryPackageSymbols
+{
+    public required string Purl { get; init; }
+    public ImmutableArray<string> Symbols { get; init; }
+}
+```
+
+### 3.2 CVE + PURL -> Affected Symbols
+
+```csharp
+public interface IVulnSurfaceService
+{
+    Task<VulnSurfaceResult> GetAffectedSymbolsAsync(
+        string cveId,
+        string purl,
+        CancellationToken ct = default);
+}
+
+public sealed record VulnSurfaceResult
+{
+    public required string CveId { get; init; }
+    public required string Purl { get; init; }
+    public required ImmutableArray<AffectedSymbol> Symbols { get; init; }
+    public required string Source { get; init; } // "surface" | "package-symbols" | "heuristic"
+    public required double Confidence { get; init; }
+}
+
+public sealed record AffectedSymbol
+{
+    public required string SymbolId { get; init; }
+    public string? MethodKey { get; init; }
+    public string? DisplayName { get; init; }
+    public string? ChangeType { get; init; }
+    public double Confidence { get; init; }
+}
+```
+
+---
+
+## 4. Caching Strategy
+
+| Data | TTL | Notes |
+|------|-----|------|
+| Advisory linksets | 1 hour | In-memory cache; configurable TTL |
+| Offline bundles | Process lifetime | Loaded once from file |
+
+---
+
+## 5. Offline Bundle Format
+
+```json
+{
+  "items": [
+    {
+      "cveId": "CVE-2024-1234",
+      "source": "bundle",
+      "packages": [
+        {
+          "purl": "pkg:npm/lodash@4.17.21",
+          "symbols": ["template", "templateSettings"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## 6. Fallback Behavior
+
+When no surface or advisory mapping is available, the service returns an empty symbol list with low confidence and `Source = "heuristic"`. Callers may inject an `IPackageSymbolProvider` to supply public-symbol fallbacks.
+
+---
+
+## 7. Related Documentation
+
+- [Slice Schema](./slice-schema.md)
+- [Patch Oracles](./patch-oracles.md)
+- [Concelier Architecture](../modules/concelier/architecture.md)
+
+---
+
+_Created: 2025-12-22. See Sprint 3810 for implementation details._