git.stella-ops.org/docs/modules/scanner/os-analyzers-evidence.md

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.