# 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.