Vuln Surface Contract v1

Schema: stella.ops/vulnSurface@v1 Status: Draft Sprint: SPRINT_3700_0002_0001 (task SURF-024)

Overview

A vulnerability surface captures the specific methods that changed between a vulnerable and a fixed version of a package. By identifying the exact “trigger” methods that are dangerous — rather than treating the whole package as vulnerable — it lets Stella Ops perform precise reachability analysis.

This contract is for engineers working on Scanner surface computation, the reachability call-graph integration, and VEX automation that consumes surfaces.

Use Cases

1. Noise Reduction - Only flag findings where code actually calls vulnerable methods
2. Confidence Tiers - “Confirmed reachable” (calls trigger) vs “Potentially reachable” (uses package)
3. Remediation Guidance - Show developers exactly which API calls to avoid
4. VEX Precision - Automatically generate VEX “not_affected” for unreachable triggers

Data Model

VulnSurface

Root object representing a computed vulnerability surface.

VulnSurfaceSink

A method that changed between vulnerable and fixed versions.

VulnSurfaceTrigger

A call site that invokes a vulnerable sink method.

Enums

VulnSurfaceStatus

MethodChangeType

Reachability Buckets

Fingerprinting Methods

cecil-il (NuGet/.NET)

Uses Mono.Cecil to compute SHA-256 hash of IL instruction sequence:

IL_0000: ldarg.0
IL_0001: call System.Object::.ctor()
IL_0006: ret

Normalized to remove:

• NOP instructions
• Debug sequence points
• Local variable indices (replaced with placeholders)

babel-ast (npm/Node.js)

Uses Babel to parse JavaScript/TypeScript and compute hash of normalized AST:

function vulnerable(input) {
  eval(input); // dangerous!
}

Normalized to remove:

• Comments
• Whitespace
• Variable names (renamed to positional)

asm-bytecode (Maven/Java)

Uses ASM to compute hash of Java bytecode:

ALOAD 0
INVOKESPECIAL java/lang/Object.<init>()V
RETURN

Normalized to remove:

• Line number tables
• Local variable tables
• Stack map frames

python-ast (PyPI)

Uses Python’s ast module to compute hash of normalized AST:

def vulnerable(user_input):
    exec(user_input)  # dangerous!

Normalized to remove:

• Docstrings
• Comments
• Variable names

Database Schema

-- Surfaces table
CREATE TABLE scanner.vuln_surfaces (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL,
    cve_id TEXT NOT NULL,
    package_ecosystem TEXT NOT NULL,
    package_name TEXT NOT NULL,
    vuln_version TEXT NOT NULL,
    fixed_version TEXT,
    fingerprint_method TEXT NOT NULL,
    total_methods_vuln INTEGER,
    total_methods_fixed INTEGER,
    changed_method_count INTEGER,
    computed_at TIMESTAMPTZ DEFAULT now(),
    UNIQUE (tenant_id, cve_id, package_ecosystem, package_name, vuln_version)
);

-- Sinks table
CREATE TABLE scanner.vuln_surface_sinks (
    id UUID PRIMARY KEY,
    surface_id UUID REFERENCES scanner.vuln_surfaces(id) ON DELETE CASCADE,
    method_key TEXT NOT NULL,
    method_name TEXT NOT NULL,
    declaring_type TEXT NOT NULL,
    change_type TEXT NOT NULL,
    UNIQUE (surface_id, method_key)
);

-- Triggers table
CREATE TABLE scanner.vuln_surface_triggers (
    id UUID PRIMARY KEY,
    sink_id UUID REFERENCES scanner.vuln_surface_sinks(id) ON DELETE CASCADE,
    scan_id UUID NOT NULL,
    caller_node_id TEXT NOT NULL,
    reachability_bucket TEXT NOT NULL,
    confidence REAL NOT NULL,
    UNIQUE (sink_id, scan_id, caller_node_id)
);

API Endpoints

POST /api/v1/surfaces/compute

Request surface computation for a CVE + package.

Request:

{
  "cveId": "CVE-2024-12345",
  "ecosystem": "nuget",
  "packageName": "Newtonsoft.Json",
  "vulnVersion": "13.0.1",
  "fixedVersion": "13.0.2"
}

Response:

{
  "surfaceId": "uuid",
  "status": "pending"
}

GET /api/v1/surfaces/{surfaceId}

Get computed surface with sinks.

GET /api/v1/surfaces/{surfaceId}/triggers?scanId={scanId}

Get triggers for a surface in a specific scan.

Integration Points

1. Concelier - Feeds CVE + affected version ranges
2. Scanner - Computes surfaces during SBOM analysis
3. Call Graph - Provides reachability analysis
4. VEX Lens - Uses surfaces for automated VEX decisions
5. UI - Displays surface details and trigger paths

References

• Vuln Surfaces Sprint
• Reachability Architecture
• RichGraph Contract