docs(scanner): add AGENTS and log governance completion
This commit is contained in:
master
59
docs/implplan/SPRINT_0132_0001_0001_scanner_surface.md
Normal file
59
docs/implplan/SPRINT_0132_0001_0001_scanner_surface.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# Sprint 132 · Scanner & Surface
|
||||
|
||||
## Topic & Scope
|
||||
- Phase III of the Scanner & Surface track, focusing on deepening language analyzers and surface evidence for Scanner.
|
||||
- Deliver runtime + static fusion for .NET analyzer outputs, and observation export wiring into SBOM entrypoint tagging.
|
||||
- Stand up native analyzer coverage (ELF/PE/Mach-O) including loader resolver heuristics and runtime capture adapters.
|
||||
- Expand Node analyzer input/VFS, entrypoint discovery, resolver, and package manager adapters across pnpm/Yarn/npm virtual layouts.
|
||||
- **Working directory:** `src/Scanner` (and this tracking file under `docs/implplan`).
|
||||
|
||||
## Dependencies & Concurrency
|
||||
- Upstream: Sprint 131 · Scanner & Surface (phase II) must land before starting this sprint’s execution.
|
||||
- Sprints 130–139 remain sequential; do not pull tasks from later sprints until predecessors are complete.
|
||||
- Within this sprint, guild tasks can proceed in parallel once their listed dependencies are satisfied.
|
||||
|
||||
## Documentation Prerequisites
|
||||
- docs/README.md
|
||||
- docs/07_HIGH_LEVEL_ARCHITECTURE.md
|
||||
- docs/modules/platform/architecture-overview.md
|
||||
- docs/modules/scanner/architecture.md
|
||||
- Ensure module-level AGENTS.md exists for `src/Scanner`; if missing, complete the governance task below.
|
||||
|
||||
## Delivery Tracker
|
||||
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 1 | SCANNER-ANALYZERS-LANG-11-002 | TODO | Depends on SCANNER-ANALYZERS-LANG-11-001 | StellaOps.Scanner EPDR Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | Implement static analyzer (IL + reflection heuristics) capturing AssemblyRef, ModuleRef/PInvoke, DynamicDependency, reflection literals, DI patterns, and custom AssemblyLoadContext probing hints; emit dependency edges with reason codes and confidence. |
|
||||
| 2 | SCANNER-ANALYZERS-LANG-11-003 | TODO | Depends on SCANNER-ANALYZERS-LANG-11-002 | StellaOps.Scanner EPDR Guild; Signals Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | Ingest optional runtime evidence (AssemblyLoad, Resolving, P/Invoke) via event listener harness; merge runtime edges with static/declared ones and attach reason codes/confidence. |
|
||||
| 3 | SCANNER-ANALYZERS-LANG-11-004 | TODO | Depends on SCANNER-ANALYZERS-LANG-11-003 | StellaOps.Scanner EPDR Guild; SBOM Service Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | Produce normalized observation export to Scanner writer: entrypoints + dependency edges + environment profiles (AOC compliant); wire to SBOM service entrypoint tagging. |
|
||||
| 4 | SCANNER-ANALYZERS-LANG-11-005 | TODO | Depends on SCANNER-ANALYZERS-LANG-11-004 | StellaOps.Scanner EPDR Guild; QA Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | Add comprehensive fixtures/benchmarks covering framework-dependent, self-contained, single-file, trimmed, NativeAOT, multi-RID scenarios; include explain traces and perf benchmarks vs previous analyzer. |
|
||||
| 5 | SCANNER-ANALYZERS-NATIVE-20-001 | TODO | None | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Implement format detector and binary identity model supporting ELF, PE/COFF, and Mach-O (including fat slices); capture arch, OS, build-id/UUID, interpreter metadata. |
|
||||
| 6 | SCANNER-ANALYZERS-NATIVE-20-002 | TODO | Depends on SCANNER-ANALYZERS-NATIVE-20-001 | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Parse ELF dynamic sections: `DT_NEEDED`, `DT_RPATH`, `DT_RUNPATH`, symbol versions, interpreter, and note build-id; emit declared dependency records with reason `elf-dtneeded` and attach version needs. |
|
||||
| 7 | SCANNER-ANALYZERS-NATIVE-20-003 | TODO | Depends on SCANNER-ANALYZERS-NATIVE-20-002 | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Parse PE imports, delay-load tables, manifests/SxS metadata, and subsystem flags; emit edges with reasons `pe-import` and `pe-delayimport`, plus SxS policy metadata. |
|
||||
| 8 | SCANNER-ANALYZERS-NATIVE-20-004 | TODO | Depends on SCANNER-ANALYZERS-NATIVE-20-003 | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Parse Mach-O load commands (`LC_LOAD_DYLIB`, `LC_REEXPORT_DYLIB`, `LC_RPATH`, `LC_UUID`, fat headers); handle `@rpath/@loader_path` placeholders and slice separation. |
|
||||
| 9 | SCANNER-ANALYZERS-NATIVE-20-005 | TODO | Depends on SCANNER-ANALYZERS-NATIVE-20-004 | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Implement resolver engine modeling loader search order for ELF (rpath/runpath/cache/default), PE (SafeDll search + SxS), and Mach-O (`@rpath` expansion); works against virtual image roots, producing explain traces. |
|
||||
| 10 | SCANNER-ANALYZERS-NATIVE-20-006 | TODO | Depends on SCANNER-ANALYZERS-NATIVE-20-005 | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Build heuristic scanner for `dlopen`/`LoadLibrary` strings, plugin ecosystem configs, and Go/Rust static hints; emit edges with `reason_code` (`string-dlopen`, `config-plugin`, `ecosystem-heuristic`) and confidence levels. |
|
||||
| 11 | SCANNER-ANALYZERS-NATIVE-20-007 | TODO | Depends on SCANNER-ANALYZERS-NATIVE-20-006 | Native Analyzer Guild; SBOM Service Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Serialize AOC-compliant observations: entrypoints + dependency edges + environment profiles (search paths, interpreter, loader metadata); integrate with Scanner writer API. |
|
||||
| 12 | SCANNER-ANALYZERS-NATIVE-20-008 | TODO | Depends on SCANNER-ANALYZERS-NATIVE-20-007 | Native Analyzer Guild; QA Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Author cross-platform fixtures (ELF dynamic/static, PE delay-load/SxS, Mach-O @rpath, plugin configs) and determinism benchmarks (<25 ms / binary, <250 MB). |
|
||||
| 13 | SCANNER-ANALYZERS-NATIVE-20-009 | TODO | Depends on SCANNER-ANALYZERS-NATIVE-20-008 | Native Analyzer Guild; Signals Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Provide optional runtime capture adapters (Linux eBPF `dlopen`, Windows ETW ImageLoad, macOS dyld interpose) writing append-only runtime evidence; include redaction/sandbox guidance. |
|
||||
| 14 | SCANNER-ANALYZERS-NATIVE-20-010 | TODO | Depends on SCANNER-ANALYZERS-NATIVE-20-009 | Native Analyzer Guild; DevOps Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Package native analyzer as restart-time plug-in with manifest/DI registration; update Offline Kit bundle and documentation. |
|
||||
| 15 | SCANNER-ANALYZERS-NODE-22-001 | TODO | None | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | Build input normalizer + VFS for Node projects: dirs, tgz, container layers, pnpm store, Yarn PnP zips; detect Node version targets (`.nvmrc`, `.node-version`, Dockerfile) and workspace roots deterministically. |
|
||||
| 16 | SCANNER-ANALYZERS-NODE-22-002 | TODO | Depends on SCANNER-ANALYZERS-NODE-22-001 | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | Implement entrypoint discovery (bin/main/module/exports/imports, workers, electron, shebang scripts) and condition set builder per entrypoint. |
|
||||
| 17 | SCANNER-ANALYZERS-NODE-22-003 | TODO | Depends on SCANNER-ANALYZERS-NODE-22-002 | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | Parse JS/TS sources for static `import`, `require`, `import()` and string concat cases; flag dynamic patterns with confidence levels; support source map de-bundling. |
|
||||
| 18 | SCANNER-ANALYZERS-NODE-22-004 | TODO | Depends on SCANNER-ANALYZERS-NODE-22-003 | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | Implement Node resolver engine for CJS + ESM (core modules, exports/imports maps, conditions, extension priorities, self-references) parameterised by node_version. |
|
||||
| 19 | SCANNER-ANALYZERS-NODE-22-005 | TODO | Depends on SCANNER-ANALYZERS-NODE-22-004 | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | Add package manager adapters: Yarn PnP (.pnp.data/.pnp.cjs), pnpm virtual store, npm/Yarn classic hoists; operate entirely in virtual FS. |
|
||||
| 20 | AGENTS-SCANNER-00-001 | DONE | Create module-level AGENTS.md for `src/Scanner` aligned with scanner architecture docs | Project Management; Scanner Guild | Author/update Scanner AGENTS.md covering roles, required docs, allowed shared directories, determinism/testing rules; ensure implementers can work autonomously. |
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2025-11-16 | Normalised sprint file to standard template; renamed from `SPRINT_132_scanner_surface.md` to `SPRINT_0132_0001_0001_scanner_surface.md`; scope unchanged; added governance task for missing Scanner AGENTS.md. | Planning |
|
||||
| 2025-11-17 | AGENTS-SCANNER-00-001 completed; module AGENTS.md added under src/Scanner. | Implementer |
|
||||
|
||||
## Decisions & Risks
|
||||
- Scanner AGENTS.md added 2025-11-16; keep in sync with scanner architecture and future advisories.
|
||||
- Sprint execution gated on completion of Sprint 131; monitor for slippage to avoid cascading delays in 130–139 chain.
|
||||
- Maintain offline-first and deterministic outputs for analyzers; ensure runtime capture adapters include redaction/sandbox guidance before rollout.
|
||||
|
||||
## Next Checkpoints
|
||||
- Schedule sprint kickoff once Sprint 131 is marked DONE.
|
||||
- Plan mid-sprint review after initial analyzer implementations land to validate observation exports and resolver behaviour.
|
||||
@@ -136,7 +136,8 @@
|
||||
| ANALYZERS-JAVA-21-009 | TODO | | SPRINT_131_scanner_surface | Java Analyzer Guild, QA Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java) | src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java | SCANNER-ANALYZERS-JAVA-21-008 | SCANNER-ANALYZERS-JAVA-21-008 | SCSA0102 |
|
||||
| ANALYZERS-JAVA-21-010 | TODO | | SPRINT_131_scanner_surface | Java Analyzer Guild, Signals Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java) | src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java | SCANNER-ANALYZERS-JAVA-21-009 | SCANNER-ANALYZERS-JAVA-21-009 | SCSA0101 |
|
||||
| ANALYZERS-JAVA-21-011 | TODO | | SPRINT_131_scanner_surface | Java Analyzer Guild · DevOps Guild | src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Java | Requires SCANNER-ANALYZERS-JAVA-21-010 + DevOps packaging | SCANNER-ANALYZERS-JAVA-21-010 | SCSA0301 |
|
||||
| ANALYZERS-LANG-11-001 | TODO | | SPRINT_131_scanner_surface | StellaOps.Scanner EPDR Guild · Language Analyzer Guild | src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet | Requires SCANNER-ANALYZERS-LANG-10-309 artifact | SCANNER-ANALYZERS-LANG-10-309 | SCSA0103 |
|
||||
| ANALYZERS-LANG-11-001 | BLOCKED | 2025-11-17 | SPRINT_131_scanner_surface | StellaOps.Scanner EPDR Guild · Language Analyzer Guild | src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet | Requires SCANNER-ANALYZERS-LANG-10-309 artifact; local dotnet tests hanging, needs clean runner/CI diagnostics | SCANNER-ANALYZERS-LANG-10-309 | SCSA0103 |
|
||||
| AGENTS-SCANNER-00-001 | DONE | 2025-11-17 | SPRINT_0132_0001_0001_scanner_surface | Project Management Guild · Scanner Guild | src/Scanner | Create or update module-level AGENTS.md covering roles, required docs, allowed shared directories, determinism/testing rules | — | SCSS-GOV-0001 |
|
||||
| ANALYZERS-LANG-11-002 | TODO | | SPRINT_132_scanner_surface | StellaOps.Scanner EPDR Guild | src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet | Depends on #1 for shared metadata | SCANNER-ANALYZERS-LANG-11-001 | SCSA0103 |
|
||||
| ANALYZERS-LANG-11-003 | TODO | | SPRINT_132_scanner_surface | StellaOps.Scanner EPDR Guild · Signals Guild | src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet | Needs #2 plus Signals schema for entry-trace | SCANNER-ANALYZERS-LANG-11-002 | SCSA0103 |
|
||||
| ANALYZERS-LANG-11-004 | TODO | | SPRINT_132_scanner_surface | StellaOps.Scanner EPDR Guild · SBOM Service Guild | src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet | Requires #3 and SBOM service hooks | SCANNER-ANALYZERS-LANG-11-003 | SCSA0103 |
|
||||
|
||||
36
src/Scanner/AGENTS.md
Normal file
36
src/Scanner/AGENTS.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# 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`
|
||||
- Current sprint file (e.g., `docs/implplan/SPRINT_131_scanner_surface.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`.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user