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 Support

• .NET: Roslyn semantic analysis (DotNetCallGraphExtractor)
• Node.js: Babel AST analysis (NodeCallGraphExtractor)
• Future: Java (ASM), Go (SSA), Python (AST)

Entrypoint Detection

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

Drift API Endpoints

• POST /api/drift/analyze - Compute drift between two scans
• GET /api/drift/{driftId} - Retrieve drift result
• GET /api/drift/{driftId}/paths - Get detailed paths

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

Engineering Rules

• Target net10.0; prefer latest C# preview allowed in repo.
• Offline-first: no new external network calls; use cached feeds (/local-nugets).
• 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.