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

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

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

{
  "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.

Created: 2025-12-22. See Sprint 3810 for implementation details.

3.6 KiB Raw Blame History