# Multi-Ecosystem Vulnerability Surface Builder

## Module
Scanner

## Status
VERIFIED

## Description
Per-ecosystem method-level vulnerability surface computation with fingerprinters for NuGet (Cecil), npm (Babel), Maven (ASM), and PyPI (Python AST). Includes VulnSurfaceBuilder, MethodDiffEngine, and PostgresVulnSurfaceRepository. 24/24 tasks DONE.

## Implementation Details
- **VulnSurface Builder**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Builder/IVulnSurfaceBuilder.cs` - `IVulnSurfaceBuilder` interface for building vulnerability surfaces
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Builder/VulnSurfaceBuilder.cs` - `VulnSurfaceBuilder` computes per-ecosystem method-level vulnerability surfaces
- **Per-Ecosystem Fingerprinters** (each implements `IMethodFingerprinter`):
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Fingerprint/CecilMethodFingerprinter.cs` - NuGet/.NET method fingerprinting using Cecil IL analysis
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Fingerprint/JavaScriptMethodFingerprinter.cs` - npm/JavaScript method fingerprinting using Babel AST
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Fingerprint/JavaBytecodeFingerprinter.cs` - Maven/Java method fingerprinting using ASM bytecode analysis
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Fingerprint/PythonAstFingerprinter.cs` - PyPI/Python method fingerprinting using Python AST
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Fingerprint/IMethodFingerprinter.cs` - Common fingerprinter interface
- **Method Diff Engine**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Fingerprint/MethodDiffEngine.cs` - `MethodDiffEngine` compares method fingerprints across versions to detect vulnerable method changes
- **Method Key Builders** (per-ecosystem):
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/MethodKeys/DotNetMethodKeyBuilder.cs` - .NET method key generation
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/MethodKeys/JavaMethodKeyBuilder.cs` - Java method key generation
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/MethodKeys/NodeMethodKeyBuilder.cs` - Node.js method key generation
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/MethodKeys/PythonMethodKeyBuilder.cs` - Python method key generation
- **Package Downloaders** (per-ecosystem):
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Download/NuGetPackageDownloader.cs` - NuGet package download
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Download/NpmPackageDownloader.cs` - npm package download
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Download/MavenPackageDownloader.cs` - Maven package download
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Download/PyPIPackageDownloader.cs` - PyPI package download
- **Internal Call Graph Builders**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/CallGraph/CecilInternalGraphBuilder.cs` - .NET internal call graph via Cecil
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/CallGraph/JavaInternalGraphBuilder.cs` - Java internal call graph
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/CallGraph/JavaScriptInternalGraphBuilder.cs` - JavaScript internal call graph
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/CallGraph/PythonInternalGraphBuilder.cs` - Python internal call graph
- **Storage**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Storage/IVulnSurfaceRepository.cs` - Repository interface
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Storage/PostgresVulnSurfaceRepository.cs` - PostgreSQL-backed vulnerability surface repository
- **Trigger Method Extraction**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Triggers/ITriggerMethodExtractor.cs` - Interface for extracting vulnerable trigger methods
  - `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/Triggers/TriggerMethodExtractor.cs` - Extracts trigger methods from vulnerability advisories

## E2E Test Plan
- [ ] Scan a .NET project and verify NuGet vulnerability surfaces are computed using Cecil method fingerprinting
- [ ] Scan a Node.js project and verify npm vulnerability surfaces are computed using JavaScript AST fingerprinting
- [ ] Scan a Java project and verify Maven vulnerability surfaces are computed using bytecode fingerprinting
- [ ] Scan a Python project and verify PyPI vulnerability surfaces are computed using Python AST fingerprinting
- [ ] Verify the MethodDiffEngine detects method-level changes between vulnerable and patched package versions
- [ ] Verify vulnerability surfaces are persisted in PostgreSQL and retrievable for subsequent scans
- [ ] Verify trigger method extraction correctly identifies the specific vulnerable functions from advisories

---

## Verification

| Check | Result |
|-------|--------|
| Tier 0 - Source files exist | PASS |
| Tier 1 - Build + code review | PASS |
| Tier 2 - Integration tests | PASS |
| Verified | 2026-02-13T18:10:00Z |