ea970ead2a
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
sdk-generator-smoke / sdk-smoke (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
api-governance / spectral-lint (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
Mirror Thin Bundle Sign & Verify / mirror-sign (push) Has been cancelled
39 lines
2.0 KiB
Markdown
39 lines
2.0 KiB
Markdown
# 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.
|
|
|
|
## 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`
|