# 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:**
```csharp
// 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:**
```csharp
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.