stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 12 Releases Wiki Activity

docs: add scanner bun sprint and align docs md.i tracker

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-05 23:52:42 +00:00
parent 02849cc955
commit bf6ab6ba6f
2 changed files with 110 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
docs/implplan/SPRINT_0139_0001_0001_scanner_bun.md Normal file
View File

@@ -0,0 +1,90 @@
# Sprint 0139 · Scanner & Surface — Bun Analyzer
## Topic & Scope
- Implement Bun analyzer for npm-ecosystem vulnerability scanning of Bun-installed JavaScript dependencies in container filesystems.
- Support `bun.lock` (text lockfile), `node_modules` installed packages, and `node_modules/.bun/` isolated linker store.
- Emit `bun.lockb` unsupported remediation messages with migration guidance.
- Symlink-aware traversal for isolated installs; deduplicated inventory by (name, version) with occurrence traceability.
- CLI verbs (`stellaops-cli bun inspect|resolve`) and WebService endpoints for Bun package inventory lookup.
- Worker plugin wiring for analyzer hot-loading.
- **Working directory:** `src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Bun` (new), tests under `src/Scanner/__Tests/StellaOps.Scanner.Analyzers.Lang.Bun.Tests`, CLI under `src/Cli/StellaOps.Cli`.
## Dependencies & Concurrency
- Upstream: Sprint 0138 (Scanner & Surface — Ruby Analyzer Parity) should be stable.
- Reuses: `StellaOps.Scanner.Analyzers.Lang` core interfaces (`ILanguageAnalyzer`, `LanguageComponentWriter`, `LanguageComponentRecord`).
- Parallel-safe with other analyzer work; Mongo required for inventory store integration (WebService tasks).
- Node analyzer patterns (`StellaOps.Scanner.Analyzers.Lang.Node`) serve as reference implementation.
- CLI patterns from Ruby analyzer (`SCANNER-CLI-0001`) serve as reference for verb implementation.
## Wave Coordination
- **Wave A (prep + scaffold):** P1 design doc, task 1 scaffold; gates all downstream.
- **Wave B (discovery + inventory):** Tasks 2–12 implement core analyzer pipeline.
- **Wave C (assembly + perf):** Tasks 13–14 integrate analyzer stages with performance guards.
- **Wave D (testing):** Tasks 15–21 create golden fixtures and test suite.
- **Wave E (integration):** Tasks 22–27 wire CLI/WebService/Worker surfaces.
- **Wave F (docs):** Tasks 28–29 document coverage and gotchas.
## Documentation Prerequisites
- `docs/README.md`
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
- `docs/modules/platform/architecture-overview.md`
- `docs/modules/scanner/architecture.md`
- `src/Scanner/AGENTS.md`
- `src/Scanner/StellaOps.Scanner.Worker/AGENTS.md`
- `src/Scanner/StellaOps.Scanner.WebService/AGENTS.md`
> **BLOCKED Tasks:** Before working on BLOCKED tasks, review [BLOCKED_DEPENDENCY_TREE.md](./BLOCKED_DEPENDENCY_TREE.md) for root blockers and dependencies.
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| P1 | PREP-SCANNER-BUN-001-DESIGN-DOC | TODO | Due TBD · Accountable: Bun Analyzer Guild | Bun Analyzer Guild | Document Bun analyzer design at `docs/modules/scanner/prep/bun-analyzer-design.md` covering lockfile schema, discovery heuristics, evidence model, and CLI/WebService contract. |
| 1 | SCANNER-BUN-001 | TODO | Await P1 | Bun Analyzer Guild | Create project scaffold: `StellaOps.Scanner.Analyzers.Lang.Bun.csproj`, plugin manifest (`manifest.json`), and `BunAnalyzerPlugin` implementing `ILanguageAnalyzerPlugin`. |
| 2 | SCANNER-BUN-002 | TODO | Depends on task 1 | Bun Analyzer Guild | Implement `BunProjectDiscoverer`: identify candidate roots by presence of `package.json` + (`bun.lock` \| `bun.lockb` \| `bunfig.toml` \| `node_modules/.bun/`). |
| 3 | SCANNER-BUN-003 | TODO | Depends on task 2 | Bun Analyzer Guild | Implement `BunInputNormalizer`: classify each root as installed-path (node_modules exists) or lockfile-path (`bun.lock` only) or unsupported (`bun.lockb` only). |
| 4 | SCANNER-BUN-004 | TODO | Depends on task 3 | Bun Analyzer Guild | Implement `bun.lockb` unsupported handler: emit remediation finding with migration command (`bun install --save-text-lockfile`). |
| 5 | SCANNER-BUN-005 | TODO | Depends on task 3 | Bun Analyzer Guild | Implement `BunLockParser`: tolerant JSONC parser for `bun.lock` text format; extract (name, version, resolved, integrity) tuples. |
| 6 | SCANNER-BUN-006 | TODO | Depends on task 5 | Bun Analyzer Guild | Implement dev/prod dependency filtering for lockfile path; expose `include_dev` configuration option. |
| 7 | SCANNER-BUN-007 | TODO | Depends on task 3 | Bun Analyzer Guild | Implement `BunInstalledCollector`: traverse `node_modules/**/package.json` and `node_modules/.bun/**/package.json` with symlink-safe walker. |
| 8 | SCANNER-BUN-008 | TODO | Depends on task 7 | Bun Analyzer Guild | Implement symlink safety: follow symlinks only within root prefix; maintain visited inode/realpath set; record logical + real paths for evidence. |
| 9 | SCANNER-BUN-009 | TODO | Depends on task 7 | Bun Analyzer Guild | Extract package metadata from `package.json`: name, version, private flag; attach lockfile evidence (resolved, integrity) when available. |
| 10 | SCANNER-BUN-010 | TODO | Depends on tasks 5, 9 | Bun Analyzer Guild | Implement `BunPackageNormalizer`: deduplicate by (name, version); accumulate occurrence paths for traceability; emit `LanguageComponentRecord`. |
| 11 | SCANNER-BUN-011 | TODO | Depends on task 10 | Bun Analyzer Guild | PURL generation: emit `pkg:npm/<name>@<version>` with correct scoped-package encoding (`@scope/pkg` → `%40scope/pkg`). |
| 12 | SCANNER-BUN-012 | TODO | Depends on task 10 | Bun Analyzer Guild | Evidence emission: attach `LanguageComponentEvidence` with kind (File/Metadata), source (`node_modules`/`bun.lock`), locator (path), and optional sha256. |
| 13 | SCANNER-BUN-013 | TODO | Depends on task 12 | Bun Analyzer Guild | Assemble `BunLanguageAnalyzer` orchestrating discovery → input normalization → collection → normalization → emit via `LanguageComponentWriter`. |
| 14 | SCANNER-BUN-014 | TODO | Depends on task 13 | Bun Analyzer Guild | Performance guards: implement max-files-per-root cap, max-symlink-depth limit, prefix pruning to avoid full image traversal. |
| 15 | SCANNER-BUN-015 | TODO | Depends on task 13 | QA Guild | Create test project `StellaOps.Scanner.Analyzers.Lang.Bun.Tests` with golden fixture harness using `LanguageAnalyzerTestHarness.AssertDeterministicAsync`. |
| 16 | SCANNER-BUN-016 | TODO | Depends on task 15 | QA Guild | Fixture: Standard Bun install (hoisted/default linker) with `node_modules` and `bun.lock`; verify installed inventory path. |
| 17 | SCANNER-BUN-017 | TODO | Depends on task 15 | QA Guild | Fixture: Isolated linker install (`bun install --linker isolated`) with packages under `node_modules/.bun/`; verify `.bun/` traversal. |
| 18 | SCANNER-BUN-018 | TODO | Depends on task 15 | QA Guild | Fixture: Lockfile-only image (no `node_modules`); verify lockfile inventory path and dev/prod filtering. |
| 19 | SCANNER-BUN-019 | TODO | Depends on task 15 | QA Guild | Fixture: Binary lockfile only (`bun.lockb`); verify unsupported remediation message emitted. |
| 20 | SCANNER-BUN-020 | TODO | Depends on task 15 | QA Guild | Fixture: Monorepo/workspaces with multiple `package.json` under single lock; verify workspace member handling. |
| 21 | SCANNER-BUN-021 | TODO | Depends on task 15 | QA Guild | Fixture: Symlink corner cases (verify no traversal outside root, no infinite loops, both logical/real paths in evidence). |
| 22 | SCANNER-BUN-022 | TODO | Depends on task 14 | CLI Guild | Implement `stellaops-cli bun inspect` verb: display Bun package inventory for local root or scan ID; wire into `CommandFactory`. |
| 23 | SCANNER-BUN-023 | TODO | Depends on task 22 | CLI Guild | Implement `stellaops-cli bun resolve` verb: resolve Bun packages by scan ID, digest, or image reference with JSON/table output. |
| 24 | SCANNER-BUN-024 | TODO | Depends on task 23 | CLI Guild | Add CLI unit tests for Bun verbs (`CommandFactoryTests`, JSON output assertions); update CLI help text and golden outputs. |
| 25 | SCANNER-BUN-025 | TODO | Depends on task 14 | WebService Guild | Implement `BunPackageInventoryStore` with Mongo-backed storage and Null fallback for offline/unit modes. |
| 26 | SCANNER-BUN-026 | TODO | Depends on task 25 | WebService Guild | Expose `GET /api/scans/{scanId}/bun-packages` endpoint; support digest/reference resolution via `SurfaceManifestStageExecutor`. |
| 27 | SCANNER-BUN-027 | TODO | Depends on task 14 | Worker Guild | Wire Bun analyzer into Worker DI; deploy plugin manifest + assembly to Worker loadout for hot-loading; verify `ScannerWorker` discovers analyzer. |
| 28 | SCANNER-BUN-028 | TODO | Depends on all | Docs Guild | Update `docs/modules/scanner/architecture.md` with Bun analyzer coverage, limitations, and supported artifacts. |
| 29 | SCANNER-BUN-029 | TODO | Depends on all | Docs Guild | Document developer gotchas: isolated installs symlink-heavy, `.bun/` scanning requirement, `bun.lockb` migration path, multi-stage build implications. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-05 | Sprint file created from product advisory; 29 tasks across 6 waves (A–F) covering core analyzer, testing, CLI/WebService/Worker integration, and docs. | Planning |
## Decisions & Risks
- **Risk:** `bun.lock` format may evolve; parser should be tolerant (JSONC-like with comments/trailing commas).
- **Risk:** Bun isolated installs are symlink-heavy; incorrect handling will cause missed dependencies or traversal issues.
- **Decision:** Treat `bun.lockb` as unsupported; binary format is undocumented and unstable. Emit clear migration guidance.
- **Decision:** Reuse npm vulnerability intelligence—Bun packages are npm packages; ecosystem = `npm`, package_manager = `bun`.
- **Decision:** Default `include_dev: true` for lockfile-only scans (repo context); recommend image scanning for prod-only accuracy.
- **Mitigation:** Reference Node analyzer patterns extensively for symlink handling, evidence emission, and determinism.
- **Mitigation:** Keep Mongo store optional (Null fallback) for offline/unit modes; aligns with Ruby analyzer pattern.
## Next Checkpoints
- P1 design doc review and approval (owner: Bun Analyzer Guild)
- Task 14 analyzer integration checkpoint with perf guards (owner: Bun Analyzer Guild)
- Task 21 fixture suite completion (owner: QA Guild)
- Task 27 Worker hot-load verification (owner: Worker Guild)

39
docs/implplan/SPRINT_0301_0001_0001_docs_md_i.md
View File

@@ -1,4 +1,4 @@
# Sprint 0301-0001-0001 · Documentation & Process · Docs Tasks Md.I
# Sprint 0301 · Documentation & Process · Docs Tasks Md.I
## Topic & Scope
- Establish the first milestone (`Md.I`) for docs process reform covering Advisory AI guardrails, air-gap guides, and deterministic scanner documentation.
@@ -20,28 +20,29 @@
> **BLOCKED Tasks:** Before working on BLOCKED tasks, review [BLOCKED_DEPENDENCY_TREE.md](./BLOCKED_DEPENDENCY_TREE.md) for root blockers and dependencies.
## Task Board
| Task ID | Status | Owner(s) | Dependencies | Notes |
| --- | --- | --- | --- | --- |
| DOCS-UNBLOCK-CLI-KNOBS-301 | DONE (2025-11-25) | CLI Guild · Policy Guild · DevEx Guild | CLI-VULN-29-001; CLI-VEX-30-001; POLICY-ENGINE-31-001 delivered 2025-11-24. | Packaged fixtures/changelogs consumed by DOCS-AIAI-31-005..009. |
| DOCS-AIAI-31-004 | DONE (2025-12-04) | Docs Guild · Console Guild | CONSOLE-VULN-29-001; CONSOLE-VEX-30-001; SBOM-AIAI-31-003 delivered. | Guardrail console guide now renders command-output snapshots (no inline screenshots) backed by deterministic capture/payload + consolidated hash manifest (`docs/advisory-ai/console-fixtures.sha256`) and verification steps. |
| DOCS-AIAI-31-005 | DONE (2025-11-25) | Docs Guild · DevEx/CLI Guild | DOCS-AIAI-31-004; CLI-VULN-29-001; CLI-VEX-30-001 | CLI guide published with exit codes + offline hashes (`docs/advisory-ai/cli.md`). |
| DOCS-AIAI-31-006 | DONE (2025-11-25) | Docs Guild · Policy Guild | DOCS-AIAI-31-005; POLICY-ENGINE-31-001 | Assistant parameter doc refreshed (`docs/policy/assistant-parameters.md`). |
| DOCS-AIAI-31-008 | DONE (2025-11-25) | Docs Guild · SBOM Service Guild | DOCS-AIAI-31-007; SBOM-AIAI-31-001 | Remediation heuristics documented with fixtures (`docs/sbom/remediation-heuristics.md`). |
| DOCS-AIAI-31-009 | DONE (2025-11-25) | Docs Guild · DevOps Guild | DEVOPS-AIAI-31-001 | Ops runbook published (`docs/runbooks/assistant-ops.md`). |
| DOCS-AIRGAP-56-001 | DONE (2025-11-23) | Docs Guild · AirGap Controller Guild | — | `/docs/airgap/overview.md` outlining modes, lifecycle, responsibilities, rule banner. |
| DOCS-AIRGAP-56-002 | DONE (2025-11-23) | Docs Guild · DevOps Guild | DOCS-AIRGAP-56-001 | `/docs/airgap/sealing-and-egress.md` (network policies, EgressPolicy facade, verification). |
| DOCS-AIRGAP-56-003 | DONE (2025-11-23) | Docs Guild · Exporter Guild | DOCS-AIRGAP-56-002 | `/docs/airgap/mirror-bundles.md` (bundle format, DSSE/TUF/Merkle validation, workflows). |
| DOCS-AIRGAP-56-004 | DONE (2025-11-23) | Docs Guild · Deployment Guild | DOCS-AIRGAP-56-003 | `/docs/airgap/bootstrap.md` covering Bootstrap Pack creation + install. |
| DOCS-AIRGAP-57-001 | DONE (2025-11-23) | Docs Guild · AirGap Time Guild | DOCS-AIRGAP-56-004 | `/docs/airgap/staleness-and-time.md` (time anchors, drift, UI indicators). |
| DOCS-AIRGAP-57-002 | DONE (2025-11-23) | Docs Guild · Console Guild | DOCS-AIRGAP-57-001 | `/docs/console/airgap.md` (sealed badge, import wizard, staleness dashboards). |
| DOCS-SCANNER-DET-01 | DONE (2025-12-03) | Docs Guild · Scanner Guild | Sprint 136 determinism fixtures (now landed in doc fixtures) | `/docs/modules/scanner/deterministic-sbom-compose.md` plus scan guide updates + fixture bundle (`docs/modules/scanner/fixtures/deterministic-compose/`). |
| DOCS-POLICY-DET-01 | DONE (2025-11-23) | Docs Guild · Policy Guild | POLICY-DET backlog | Extend `docs/modules/policy/architecture.md` with determinism gate semantics and provenance references. |
| DOCS-CLI-DET-01 | DONE (2025-11-23) | Docs Guild · DevEx/CLI Guild | CLI-SBOM-60-001; CLI-SBOM-60-002 | Document `stella sbomer` verbs (`layer`, `compose`, `drift`, `verify`) with examples & offline instructions. |
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | DOCS-UNBLOCK-CLI-KNOBS-301 | DONE (2025-11-25) | CLI-VULN-29-001; CLI-VEX-30-001; POLICY-ENGINE-31-001 delivered 2025-11-24. | CLI Guild · Policy Guild · DevEx Guild | Packaged fixtures/changelogs consumed by DOCS-AIAI-31-005..009. |
| 2 | DOCS-AIAI-31-004 | DONE (2025-12-04) | — | Docs Guild · Console Guild | Guardrail console guide renders command-output snapshots with deterministic payloads + `docs/advisory-ai/console-fixtures.sha256` hash manifest. |
| 3 | DOCS-AIAI-31-005 | DONE (2025-11-25) | DOCS-AIAI-31-004; CLI-VULN-29-001; CLI-VEX-30-001 | Docs Guild · DevEx/CLI Guild | CLI guide published with exit codes + offline hashes (`docs/advisory-ai/cli.md`). |
| 4 | DOCS-AIAI-31-006 | DONE (2025-11-25) | DOCS-AIAI-31-005; POLICY-ENGINE-31-001 | Docs Guild · Policy Guild | Assistant parameter doc refreshed (`docs/policy/assistant-parameters.md`). |
| 5 | DOCS-AIAI-31-008 | DONE (2025-11-25) | DOCS-AIAI-31-007; SBOM-AIAI-31-001 | Docs Guild · SBOM Service Guild | Remediation heuristics documented with fixtures (`docs/sbom/remediation-heuristics.md`). |
| 6 | DOCS-AIAI-31-009 | DONE (2025-11-25) | DEVOPS-AIAI-31-001 | Docs Guild · DevOps Guild | Ops runbook published (`docs/runbooks/assistant-ops.md`). |
| 7 | DOCS-AIRGAP-56-001 | DONE (2025-11-23) | — | Docs Guild · AirGap Controller Guild | `/docs/airgap/overview.md` outlining modes, lifecycle, responsibilities, rule banner. |
| 8 | DOCS-AIRGAP-56-002 | DONE (2025-11-23) | DOCS-AIRGAP-56-001 | Docs Guild · DevOps Guild | `/docs/airgap/sealing-and-egress.md` (network policies, EgressPolicy facade, verification). |
| 9 | DOCS-AIRGAP-56-003 | DONE (2025-11-23) | DOCS-AIRGAP-56-002 | Docs Guild · Exporter Guild | `/docs/airgap/mirror-bundles.md` (bundle format, DSSE/TUF/Merkle validation, workflows). |
| 10 | DOCS-AIRGAP-56-004 | DONE (2025-11-23) | DOCS-AIRGAP-56-003 | Docs Guild · Deployment Guild | `/docs/airgap/bootstrap.md` covering Bootstrap Pack creation and install. |
| 11 | DOCS-AIRGAP-57-001 | DONE (2025-11-23) | DOCS-AIRGAP-56-004 | Docs Guild · AirGap Time Guild | `/docs/airgap/staleness-and-time.md` (time anchors, drift, UI indicators). |
| 12 | DOCS-AIRGAP-57-002 | DONE (2025-11-23) | DOCS-AIRGAP-57-001 | Docs Guild · Console Guild | `/docs/console/airgap.md` (sealed badge, import wizard, staleness dashboards). |
| 13 | DOCS-SCANNER-DET-01 | DONE (2025-12-03) | Sprint 136 determinism fixtures landed | Docs Guild · Scanner Guild | `/docs/modules/scanner/deterministic-sbom-compose.md` plus fixture bundle `docs/modules/scanner/fixtures/deterministic-compose/`. |
| 14 | DOCS-POLICY-DET-01 | DONE (2025-11-23) | POLICY-DET backlog | Docs Guild · Policy Guild | Extended `docs/modules/policy/architecture.md` with determinism gate semantics and provenance references. |
| 15 | DOCS-CLI-DET-01 | DONE (2025-11-23) | CLI-SBOM-60-001; CLI-SBOM-60-002 | Docs Guild · DevEx/CLI Guild | Documented `stella sbomer` verbs with examples and offline instructions. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-05 | Normalised sprint file to standard template (Delivery Tracker table, header ID) without altering task content. | Project Mgmt |
| 2025-12-04 | DOCS-AIAI-31-004 reopened to replace screenshot embeds with command-rendered markdown outputs; set task DOING during update. | Docs Guild |
| 2025-12-04 | DOCS-AIAI-31-004 DONE: swapped inline screenshots for command-output snippets; hashes unchanged. | Docs Guild |
| 2025-12-04 | DOCS-AIAI-31-004 DONE: added `docs/advisory-ai/console-fixtures.sha256`, hash table + verification snippet to console guide. | Docs Guild |