up

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.
+