git.stella-ops.org/docs/modules/scanner/README.md

StellaOps Scanner

Scanner analyses container images layer-by-layer, producing deterministic SBOM fragments, diffs, and signed reports.

Latest updates (2025-12-12)

• Deterministic SBOM composition fixture published at docs/modules/scanner/fixtures/deterministic-compose/ with DSSE, _composition.json, BOM, and hashes; doc deterministic-sbom-compose.md promoted to Ready v1.0 with offline verification steps.
• Node analyzer now ingests npm/yarn/pnpm lockfiles, emitting DeclaredOnly components with lock provenance. The CLI companion command stella node lock-validate runs the collector offline, surfaces declared-only or missing-lock packages, and emits telemetry via stellaops.cli.node.lock_validate.count. See docs/modules/scanner/analyzers-node.md and bench scenario node_detection_gaps_fixture.
• Python analyzer picks up requirements*.txt, Pipfile.lock, and poetry.lock, tagging installed distributions with lock provenance and generating declared-only components for policy. Use stella python lock-validate to run the same checks locally before images are built.
• Java analyzer now parses gradle.lockfile, gradle/dependency-locks/**/*.lockfile, and pom.xml dependencies via the new JavaLockFileCollector, merging lock metadata onto jar evidence and emitting declared-only components when jars are absent. The new CLI verb stella java lock-validate reuses that collector offline (table/JSON output) and records stellaops.cli.java.lock_validate.count{outcome} for observability.
• Worker/WebService now resolve cache roots and feature flags via StellaOps.Scanner.Surface.Env; misconfiguration warnings are documented in docs/modules/scanner/design/surface-env.md and surfaced through startup validation.
• Platform events rollout (2025-10-19) continues to publish scanner.report.ready@1 and scanner.scan.completed@1 envelopes with embedded DSSE payloads (see docs/updates/2025-10-19-scanner-policy.md and docs/updates/2025-10-19-platform-events.md). Service and consumer tests should round-trip the canonical samples under docs/events/samples/.
• OS/non-language analyzers: evidence is rootfs-relative, warnings are structured/capped, hashing is bounded, and Linux OS analyzers support surface-cache reuse. See os-analyzers-evidence.md.

Responsibilities

• Expose APIs (WebService) for scan orchestration, diffing, and artifact retrieval.
• Run Worker analyzers for OS, language, and native ecosystems with restart-only plug-ins.
• Store SBOM fragments and artifacts in RustFS/object storage.
• Publish DSSE-ready metadata for Signer/Attestor and downstream policy evaluation.

Key components

• StellaOps.Scanner.WebService minimal API host.
• StellaOps.Scanner.Worker analyzer executor.
• Analyzer libraries under StellaOps.Scanner.Analyzers.*.

Integrations & dependencies

• Scheduler for job intake and retries.
• Policy Engine for evidence handoff.
• Export Center / Offline Kit for artifact packaging.

Operational notes

• CAS caches, bounded retries, DSSE integration.
• Monitoring dashboards (see ./operations/analyzers-grafana-dashboard.json).
• RustFS migration playbook.

Related resources

• ./operations/analyzers.md
• ./operations/analyzers-grafana-dashboard.json
• ./operations/rustfs-migration.md
• ./operations/entrypoint.md
• ./analyzers-node.md
• ./operations/secret-leak-detection.md
• ./operations/dsse-rekor-operator-guide.md
• ./os-analyzers-evidence.md
• ./design/macos-analyzer.md
• ./design/windows-analyzer.md
• ../benchmarks/scanner/deep-dives/macos.md
• ../benchmarks/scanner/deep-dives/windows.md
• ../benchmarks/scanner/windows-macos-demand.md
• ../benchmarks/scanner/windows-macos-interview-template.md
• ./operations/field-engagement.md
• ./design/README.md

Backlog references

• DOCS-SCANNER updates tracked in ../../TASKS.md.
• Analyzer parity work in src/Scanner/**/TASKS.md.

Epic alignment

• Epic 6 – Vulnerability Explorer: provide policy-aware scan outputs, explain traces, and findings ledger hooks for triage workflows.
• Epic 10 – Export Center: generate export-ready artefacts, manifests, and DSSE metadata for bundles.