From 833e68575a5a34af32913c30bc0780a7c1286573 Mon Sep 17 00:00:00 2001 From: master <> Date: Mon, 17 Nov 2025 10:05:16 +0000 Subject: [PATCH] docs(scanner): add AGENTS and log governance completion --- .../SPRINT_0132_0001_0001_scanner_surface.md | 59 +++++++++++++++++++ docs/implplan/tasks-all.md | 3 +- src/Scanner/AGENTS.md | 36 +++++++++++ 3 files changed, 97 insertions(+), 1 deletion(-) create mode 100644 docs/implplan/SPRINT_0132_0001_0001_scanner_surface.md create mode 100644 src/Scanner/AGENTS.md diff --git a/docs/implplan/SPRINT_0132_0001_0001_scanner_surface.md b/docs/implplan/SPRINT_0132_0001_0001_scanner_surface.md new file mode 100644 index 000000000..d040ad214 --- /dev/null +++ b/docs/implplan/SPRINT_0132_0001_0001_scanner_surface.md @@ -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. \ No newline at end of file diff --git a/docs/implplan/tasks-all.md b/docs/implplan/tasks-all.md index 37a44dd4b..d9cdccdf7 100644 --- a/docs/implplan/tasks-all.md +++ b/docs/implplan/tasks-all.md @@ -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 | diff --git a/src/Scanner/AGENTS.md b/src/Scanner/AGENTS.md new file mode 100644 index 000000000..e64499231 --- /dev/null +++ b/src/Scanner/AGENTS.md @@ -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.