stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity

up
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
sdk-generator-smoke / sdk-smoke (push) Has been cancelled
Details
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Details
api-governance / spectral-lint (push) Has been cancelled
Details
oas-ci / oas-validate (push) Has been cancelled
Details
Mirror Thin Bundle Sign & Verify / mirror-sign (push) Has been cancelled
Details

Browse Source
This commit is contained in:
StellaOps Bot
2025-11-27 07:46:56 +02:00
parent d63af51f84
commit ea970ead2a
302 changed files with 43161 additions and 1534 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/modules/scanner/architecture.md
View File

@@ -478,9 +478,16 @@ ResolveEntrypoint(ImageConfig cfg, RootFs fs):
return Unknown(reason)
```
### Appendix A.1 — EntryTrace Explainability
EntryTrace emits structured diagnostics and metrics so operators can quickly understand why resolution succeeded or degraded:
### Appendix A.1 — EntryTrace Explainability
### Appendix A.0 — Replay / Record mode
- WebService ships a **RecordModeService** that assembles replay manifests (schema v1) with policy/feed/tool pins and reachability references, then writes deterministic input/output bundles to the configured object store (RustFS default, S3/Minio fallback) under `replay/<head>/<digest>.tar.zst`.
- Bundles contain canonical manifest JSON plus inputs (policy/feed/tool/analyzer digests) and outputs (SBOM, findings, optional VEX/logs); CAS URIs follow `cas://replay/...` and are attached to scan snapshots as `ReplayArtifacts`.
- Reachability graphs/traces are folded into the manifest via `ReachabilityReplayWriter`; manifests and bundles hash with stable ordering for replay verification (`docs/replay/DETERMINISTIC_REPLAY.md`).
- Deterministic execution switches (`docs/modules/scanner/deterministic-execution.md`) must be enabled when generating replay bundles to keep hashes stable.
EntryTrace emits structured diagnostics and metrics so operators can quickly understand why resolution succeeded or degraded:
| Reason | Description | Typical Mitigation |
|--------|-------------|--------------------|

38
docs/modules/scanner/deterministic-execution.md Normal file
View File

@@ -0,0 +1,38 @@
# 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`