up

docs/modules/scanner/README.md

@@ -2,13 +2,14 @@
 
 Scanner analyses container images layer-by-layer, producing deterministic SBOM fragments, diffs, and signed reports.
 
-## Latest updates (2025-12-03)
+## 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`.
 - 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.
@@ -38,6 +39,7 @@ Scanner analyses container images layer-by-layer, producing deterministic SBOM f
 - ./operations/entrypoint.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

docs/modules/scanner/os-analyzers-evidence.md

@@ -0,0 +1,74 @@
+# OS Analyzer Evidence Semantics (Non-Language Scanners)
+
+This document defines the **evidence contract** produced by OS/non-language analyzers (apk/dpkg/rpm + Windows/macOS OS analyzers) so downstream SBOM/attestation logic can rely on stable, deterministic semantics.
+
+## Evidence Paths
+
+- `OSPackageFileEvidence.Path` is **rootfs-relative** and **normalized**:
+  - No leading slash (`/`).
+  - Forward slashes only (`/`), even on Windows inputs.
+  - Never a host path.
+- Any analyzer-specific absolute path must be converted to rootfs-relative before emission.
+  - Helper: `StellaOps.Scanner.Analyzers.OS.Helpers.OsPath.TryGetRootfsRelative(...)`.
+
+Examples:
+
+- Good: `usr/bin/bash`
+- Bad: `/usr/bin/bash`
+- Bad: `C:\scans\rootfs\usr\bin\bash`
+
+## Layer Attribution
+
+- `OSPackageFileEvidence.LayerDigest` is **best-effort** attribution derived from scan metadata:
+  - `ScanMetadataKeys.LayerDirectories` (optional mapping of layer digest → extracted directory)
+  - `ScanMetadataKeys.CurrentLayerDigest` (fallback/default)
+- Helper: `StellaOps.Scanner.Analyzers.OS.Helpers.OsFileEvidenceFactory`.
+
+## Digest & Hashing Strategy
+
+Default posture is **avoid unbounded hashing**:
+
+- Prefer package-manager-provided digests when present (`OSPackageFileEvidence.Digests` / `OSPackageFileEvidence.Sha256`).
+- Compute `sha256` only when:
+  - No digests are present, and
+  - File exists, and
+  - File size is ≤ 16 MiB (`OsFileEvidenceFactory` safeguard).
+- Primary digest selection for file evidence metadata prefers strongest available:
+  - `sha512` → `sha384` → `sha256` → `sha1` → `md5`
+
+## Analyzer Warnings
+
+OS analyzers may emit `AnalyzerWarning` entries (`Code`, `Message`) for partial/edge conditions (missing db, parse errors, unexpected layout).
+
+Normalization rules (in `OsPackageAnalyzerBase`):
+
+- Deduplicate by `(Code, Message)`.
+- Stable sort by `Code` then `Message` (ordinal).
+- Cap at 50 warnings.
+
+## OS Analyzer Caching (Surface Cache)
+
+Linux OS analyzers (apk/dpkg/rpm) support **safe, deterministic reuse** via `ISurfaceCache`:
+
+- Cache key: `(tenant, analyzerId, rootfsFingerprint)` under namespace `scanner/os/analyzers`.
+- Fingerprint inputs are intentionally narrow: a single **analyzer-specific** “DB fingerprint file”:
+  - `apk`: `lib/apk/db/installed`
+  - `dpkg`: `var/lib/dpkg/status`
+  - `rpm`: `var/lib/rpm/rpmdb.sqlite` (preferred) or legacy `Packages` fallback
+- Fingerprint payload includes:
+  - Root path + analyzerId
+  - Relative fingerprint file path
+  - File length + `LastWriteTimeUtc` (ms)
+  - Optional file-content sha256 when the file is ≤ 8 MiB
+
+Worker wiring:
+
+- `StellaOps.Scanner.Worker.Processing.CompositeScanAnalyzerDispatcher` records cache hit/miss counters per analyzer.
+
+## RPM sqlite Reader Notes
+
+When `rpmdb.sqlite` is present, the reader avoids `SELECT *` and column scanning:
+
+- Uses `PRAGMA table_info(Packages)` to select a likely RPM header blob column (prefers `hdr`/`header`, excludes `pkgId` when possible).
+- Queries only `pkgKey` + header blob column for parsing.
+