144 lines
3.6 KiB
Markdown
144 lines
3.6 KiB
Markdown
# 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._
|