git.stella-ops.org/docs/modules/scanner/deterministic-execution.md

Scanner Deterministic Execution Invariants

Imposed rule: Deterministic mode must pin clock, RNG, feeds, policy, tooling, and concurrency; any nondeterministic output is a test failure.

This note collects the invariants required for reproducible Scanner runs and replays.

Runtime switches (config/env)

• Clock: scanner:determinism:fixedClock=true, scanner:determinism:fixedInstantUtc=2024-01-01T00:00:00Z or SCANNER__DETERMINISM__FIXEDCLOCK=true, SCANNER__DETERMINISM__FIXEDINSTANTUTC=....
• RNG: scanner:determinism:rngSeed=1337 or SCANNER__DETERMINISM__RNGSEED=1337.
• Concurrency cap: scanner:determinism:concurrencyLimit=1 (worker clamps MaxConcurrentJobs to this) or SCANNER__DETERMINISM__CONCURRENCYLIMIT=1.
• Feed/policy pins: scanner:determinism:feedSnapshotId=<frozen-feed> and scanner:determinism:policySnapshotId=<rev> to stamp submissions and reject mismatched runtime policies.
• Log filtering: scanner:determinism:filterLogs=true to strip timestamps/PIDs before hashing.
• Evidence: worker emits determinism.json into the surface manifest (view replay) summarising fixed clock, seed, concurrency cap, feed/policy pins, per-payload hashes, and a Merkle root over payload hashes for quick verification.
• Sealed replay intake: worker reads replay.bundle.uri + replay.bundle.sha256 (and determinism.feed/determinism.policy pins) from job metadata; stores bundle pins in analysis so downstream stages stay hermetic. Stage: ingest-replay runs before image resolution.
• Surface manifest includes replayBundle (uri + sha256 + pins) so offline kits can verify sealed inputs without scheduler context.

Ordering

• Sort inputs (images, layers, files, findings) deterministically before processing/serialization.
• Canonical JSON writers: sorted keys, UTF-8, stable float formatting.

Hashing & manifests

• Compute SHA-256 for each artefact; aggregate into Merkle root for replay bundles.
• Record tool/policy/feed hashes in replay.yaml; include analyzer versions.

Outputs to verify

• SBOM (CycloneDX/SPDX), findings, VEX, reachability graphs, logs.
• Optional entropy reports (entropy.report.json, layer_summary.json).
• determinism.json when harness is run.

CI/bench hooks

• bench:determinism runs replay with fixed switches; fails on hash deltas.
• stella replay run --sealed --fixed-clock ... --seed 1337 --single-threaded for local.

Offline/air-gap

• All inputs from bundle; no egress.
• Rekor lookups skipped; rely on bundled proofs.

References

• docs/replay/DETERMINISTIC_REPLAY.md
• docs/replay/TEST_STRATEGY.md
• docs/modules/scanner/determinism-score.md