# 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._