git.stella-ops.org/src/Scanner/AGENTS.md

AGENTS · Scanner Module

Roles

• Backend / Analyzer Engineer: .NET 10 (preview) for analyzers, worker, web service, plug-ins; keep outputs deterministic.
• QA / Bench Engineer: Adds golden fixtures, regression tests, and perf/determinism benchmarks under __Tests / __Benchmarks.
• Docs Touches (light): Update module docs under src/Scanner/docs when behavior/contracts change; mirror in sprint notes.

Required Reading

• docs/README.md
• docs/07_HIGH_LEVEL_ARCHITECTURE.md
• docs/modules/platform/architecture-overview.md
• docs/modules/scanner/architecture.md
• docs/reachability/DELIVERY_GUIDE.md (sections 5.5–5.9 for native/JS/PHP updates)
• docs/reachability/purl-resolved-edges.md
• docs/reachability/patch-oracles.md
• docs/product-advisories/14-Dec-2025 - Smart-Diff Technical Reference.md (for Smart-Diff predicates)
• Current sprint file (e.g., docs/implplan/SPRINT_401_reachability_evidence_chain.md).

Working Directory & Boundaries

• Primary scope: src/Scanner/** (analyzers, worker, web service, plugins, __Libraries, __Tests, __Benchmarks, docs).
• Avoid cross-module edits unless sprint explicitly permits; note any cross-module change in sprint tracker.
• Keep fixtures minimal/deterministic; store under src/Scanner/__Tests/Fixtures or __Benchmarks.

Smart-Diff Contracts (Sprint 3500)

The Scanner module now includes Smart-Diff foundation primitives:

Libraries

• StellaOps.Scanner.SmartDiff - Core Smart-Diff predicate models and serialization
• StellaOps.Scanner.Reachability - Reachability gate computation with 3-bit class

Key Types

• SmartDiffPredicate - Attestation predicate for differential scans
• ReachabilityGate - 3-bit class (0-7) indicating entry/sink reachability
• SinkCategory - Taxonomy of sensitive sinks (file, network, crypto, etc.)
• SinkRegistry - Registry of known sinks with category mappings

Predicate Schema

• URI: stellaops.dev/predicates/smart-diff@v1
• Schema: docs/schemas/stellaops-smart-diff.v1.schema.json
• DSSE-signed predicates for evidence chain

Integration Points

• Integrates with StellaOps.Policy.Suppression for pre-filter rules
• Emits to Attestor module for DSSE envelope wrapping
• Consumed by Findings Ledger for triage decisions

Reachability Drift (Sprint 3600)

Reachability Drift Detection tracks function-level reachability changes between scans:

Libraries

• StellaOps.Scanner.ReachabilityDrift - Drift detection engine, API models, attestation
• StellaOps.Scanner.CallGraph - Language-specific call graph extractors
• StellaOps.Scanner.VulnSurfaces - Vulnerability surface computation (trigger methods)

Key Types

• ReachabilityDriftResult - Drift analysis output (newly reachable, mitigated paths)
• DriftedSink - Sink that changed reachability state with cause attribution
• DriftCause - Causal explanation (guard removed, new route, code change)
• CompressedPath - Compact path representation (entrypoint → key nodes → sink)
• ReachabilityConfidenceTier - Confirmed/Likely/Present/Unreachable tiers

Predicate Schema

• URI: stellaops.dev/predicates/reachability-drift@v1
• DSSE-signed attestations for drift evidence chain

Call Graph Extractors (Sprint 20251226-005)

All language-specific call graph extractors are now registered in CallGraphExtractorRegistry via DI:

Language	Extractor	Analysis Method	Key Sinks Detected
.NET	DotNetCallGraphExtractor	Roslyn semantic analysis	SQL injection, deserialization, command execution
Java	JavaCallGraphExtractor	ASM bytecode parsing	SQL, LDAP, XXE, deserialization, SSRF, template injection
Node.js	NodeCallGraphExtractor	Babel AST / stella-callgraph-node tool	eval, child_process, fs, SQL templates
Python	PythonCallGraphExtractor	Python AST analysis	subprocess, pickle, eval, SQL string formatting
Go	GoCallGraphExtractor	SSA analysis via external tool	os/exec, database/sql, net/http

Registry Usage:

// Inject the registry
ICallGraphExtractorRegistry registry;

// Get extractor by language
var extractor = registry.GetExtractor("java");
if (extractor is not null)
{
    var request = new CallGraphExtractionRequest(scanId, "java", "/path/to/target");
    var snapshot = await extractor.ExtractAsync(request, cancellationToken);
}

// Check if language is supported
if (registry.IsLanguageSupported("python"))
{
    // ...
}

DI Registration:

services.AddCallGraphServices(configuration);

Entrypoint Detection

• ASP.NET Core: [HttpGet], [Route], minimal APIs
• Express/Fastify: route handlers
• Background: IHostedService, BackgroundService
• CLI: Main, command handlers

Drift API Endpoints

• GET /api/v1/scans/{scanId}/drift - Get or compute drift between two scans
• GET /api/v1/drift/{driftId}/sinks - Page drifted sinks
• POST /api/v1/scans/{scanId}/compute-reachability - Trigger reachability computation
• GET /api/v1/scans/{scanId}/reachability/components - List component reachability
• GET /api/v1/scans/{scanId}/reachability/findings - List reachability findings
• GET /api/v1/scans/{scanId}/reachability/explain - Explain reachability for CVE + PURL

Drift Documentation

• docs/modules/scanner/reachability-drift.md
• docs/api/scanner-drift-api.md
• docs/operations/reachability-drift-guide.md

Testing

• Unit tests: src/Scanner/__Tests/StellaOps.Scanner.ReachabilityDrift.Tests/
• Benchmark cases: bench/reachability-benchmark/
• Golden fixtures: deterministic path compression, DSSE output

Vulnerability Surfaces (Sprint 3700)

Compute vulnerability surfaces by diffing vulnerable vs fixed package versions:

Libraries

• StellaOps.Scanner.VulnSurfaces - Surface builder, method fingerprinting, trigger extraction

Key Types

• VulnSurface - Computed surface with sink methods and triggers
• VulnSurfaceSink - Method that changed in security fix
• VulnSurfaceTrigger - Public API that can reach sink
• MethodFingerprint - Stable method identity across versions

Per-Ecosystem Support

• NuGet: Cecil IL fingerprinting
• npm: Babel AST fingerprinting
• Maven: ASM bytecode fingerprinting
• PyPI: Python AST fingerprinting

Integration with Reachability

• ISurfaceQueryService - Query triggers for CVE during scan
• Confidence tiers: Confirmed (trigger reachable) > Likely (API reachable) > Present (dep only)
• Path witnesses include surface evidence for audit trail

Binary + Call-Stack Reachability (Sprint 3800 Series)

Layered binary reachability with attestable slices for CVE triage:

Sprint Summary

• 3800: Binary call-edge enhancement (disassembly, PLT/IAT, dynamic loading)
• 3810: CVE→Symbol mapping and slice format
• 3820: Slice query and replay APIs
• 3830: VEX integration and policy binding
• 3840: Runtime trace merge (eBPF/ETW)
• 3850: OCI storage and CLI commands

See: docs/implplan/SPRINT_3800_0000_0000_summary.md

Libraries

• StellaOps.Scanner.Reachability.Slices - Slice extraction, DSSE signing, verdict computation
• StellaOps.Scanner.Advisory - CVE→symbol mapping integration with Concelier
• StellaOps.Scanner.Runtime - eBPF/ETW runtime trace collectors
• StellaOps.Scanner.Storage.Oci - OCI artifact storage for slices

Key Types

• ReachabilitySlice - Minimal attestable proof unit for CVE reachability
• SliceQuery - Query parameters (CVE, symbols, entrypoints, policy)
• SliceVerdict - Result status (reachable/unreachable/unknown/gated)
• VulnSurfaceResult - CVE→symbol mapping result with confidence

Predicate Schema

• URI: stellaops.dev/predicates/reachability-slice@v1
• Schema: docs/schemas/stellaops-slice.v1.schema.json
• DSSE-signed slices for audit trail

Slice API Endpoints

• POST /api/slices/query - Query reachability for CVE/symbols
• GET /api/slices/{digest} - Retrieve attested slice
• POST /api/slices/replay - Verify slice reproducibility

CLI Commands (Sprint 3850)

• stella binary submit - Submit binary graph
• stella binary info - Display graph info
• stella binary symbols - List symbols
• stella binary verify - Verify attestation

Documentation

• docs/reachability/slice-schema.md - Slice format specification
• docs/reachability/cve-symbol-mapping.md - CVE→symbol service design
• docs/reachability/replay-verification.md - Replay workflow guide

Engineering Rules

• Target net10.0; prefer latest C# preview allowed in repo.
• Offline-first: no new external network calls; use .nuget/packages/ cache.
• Determinism: stable ordering, UTC ISO-8601 timestamps, no DateTime.Now/random without seed; normalize path separators.
• Logging: structured (ILogger message templates); avoid secrets/paths leakage.
• Security: no executing untrusted payloads; keep analyzers pure; include redaction guidance for runtime capture adapters.
• Native analyzers: capture .note.gnu.build-id when present and thread into SymbolID/code_id; add synthetic roots for .preinit_array/.init_array/_init; emit purl+symbol-digest on call edges; emit Unknowns when symbol→purl or edges are unresolved.
• Tests: keep patch-oracle fixtures deterministic (strip binaries; stable compilers); add/maintain tests/reachability/patch-oracles/** when touching native analyzers.

Testing & Verification

• Default: dotnet test src/Scanner/StellaOps.Scanner.sln.
• Add/extend tests in src/Scanner/__Tests/**; golden outputs should be deterministic (sorted keys, stable ordering).
• Benchmarks under src/Scanner/__Benchmarks/**; document input and expected ceilings in comments.
• Cover multi-RID, trimmed/NativeAOT, self-contained vs framework-dependent cases where applicable.
• Smart-Diff: Run schema validation tests (SmartDiffSchemaValidationTests) for predicate contract changes.

Workflow Expectations

• Mirror task state in sprint tracker (TODO → DOING → DONE/BLOCKED); note blockers with the specific decision needed.
• Keep resolvers/analyzers parametric on environment data (RID, TFM, search paths); avoid host-global state.
• When adding DI/manifest registrations, ensure restart-time and worker compatibility; update module docs if contracts change.