# CVE-to-Symbol Mapping Service

## Module
ReachGraph

## Status
IMPLEMENTED

## Description
CVE-to-symbol mapping service with controller endpoint and service interface for reachability analysis in the ReachGraph module.

## Implementation Details
- **ICveSymbolMappingService interface**: `src/__Libraries/StellaOps.Reachability.Core/CveMapping/ICveSymbolMappingService.cs` -- `GetMappingsForCveAsync`, `GetMappingsForPackageAsync`, `SearchBySymbolAsync`, `AddOrUpdateMappingAsync`, `AnalyzePatchAsync`, `EnrichFromOsvAsync`, `GetStatsAsync`
- **CveSymbolMappingService**: `src/__Libraries/StellaOps.Reachability.Core/CveMapping/CveSymbolMappingService.cs` -- core implementation
- **CveMappingController**: `src/ReachGraph/StellaOps.ReachGraph.WebService/Controllers/CveMappingController.cs` -- REST API at `v1/cve-mappings` with endpoints: GET `{cveId}`, GET `by-package?purl=`, GET `by-symbol?symbol=`, POST (upsert), POST `analyze-patch`, POST `{cveId}/enrich`, GET `stats`; rate limiting (`reachgraph-read`/`reachgraph-write`); response caching (1h for reads, 5m for stats)
- **CveSymbolMapping model**: `src/__Libraries/StellaOps.Reachability.Core/CveMapping/CveSymbolMapping.cs` -- CVE-to-symbol mapping with PURL, `VulnerableSymbol`, `MappingSource` (OSV/NVD/Manual/PatchAnalysis/Vendor), confidence score, `VulnerabilityType`, affected/fixed versions
- **VulnerableSymbol**: `src/__Libraries/StellaOps.Reachability.Core/CveMapping/VulnerableSymbol.cs` -- symbol with canonical ID, file path, line range
- **Patch analysis**: `src/__Libraries/StellaOps.Reachability.Core/CveMapping/IPatchSymbolExtractor.cs`, `FunctionBoundaryDetector.cs`, `GitDiffExtractor.cs`, `UnifiedDiffParser.cs` -- extract vulnerable symbols from commits/patches
- **OSV enrichment**: `src/__Libraries/StellaOps.Reachability.Core/CveMapping/IOsvEnricher.cs`, `OsvEnricher.cs` -- enrich mappings from OSV database
- **Tests**: `src/ReachGraph/__Tests/StellaOps.ReachGraph.WebService.Tests/ReachGraphApiIntegrationTests.cs`
- **Source**: Feature matrix scan

## E2E Test Plan
- [ ] Verify GET `v1/cve-mappings/{cveId}` returns symbol mappings with PURL, confidence, and evidence URI
- [ ] Test GET `by-package?purl=` returns all CVE mappings for a given package
- [ ] Verify GET `by-symbol?symbol=&language=` searches by symbol name with optional language filter
- [ ] Test POST upsert creates/updates mappings idempotently
- [ ] Verify POST `analyze-patch` extracts vulnerable symbols from diff content
- [ ] Test POST `{cveId}/enrich` retrieves and persists OSV-sourced mappings
- [ ] Verify GET `stats` returns corpus statistics (total mappings, unique CVEs/packages, average confidence)