491e883653
- Created `StellaOps.TestKit.Tests` project for unit tests related to determinism. - Implemented `DeterminismManifestTests` to validate deterministic output for canonical bytes and strings, file read/write operations, and error handling for invalid schema versions. - Added `SbomDeterminismTests` to ensure identical inputs produce consistent SBOMs across SPDX 3.0.1 and CycloneDX 1.6/1.7 formats, including parallel execution tests. - Updated project references in `StellaOps.Integration.Determinism` to include the new determinism testing library.
50 lines
3.0 KiB
Markdown
50 lines
3.0 KiB
Markdown
# Findings Ledger (Vuln Explorer) — Event Model & Replay (Md.XI draft)
|
|
|
|
> Status: DRAFT — depends on GRAP0101 alignment and security review. Do not publish until hashes and schema cross-checks are complete.
|
|
|
|
## Scope
|
|
- Explain event schema, hashing strategy, Merkle roots, and replay tooling as consumed by Vuln Explorer.
|
|
- Align with canonical ledger docs: `docs/modules/findings-ledger/schema.md`, `merkle-anchor-policy.md`, `replay-harness.md`.
|
|
- Provide deterministic examples and hash manifests (record in `docs/assets/vuln-explorer/SHA256SUMS`).
|
|
|
|
## Dependencies
|
|
| Input | Status | Notes |
|
|
| --- | --- | --- |
|
|
| GRAP0101 contract | pending | Confirm field names/identifiers to keep Explorer/ledger in sync. |
|
|
| Security review (hashing/attachments) | pending | Required before publication. |
|
|
| Replay fixtures | available | See `docs/modules/findings-ledger/replay-harness.md` and `golden-checksums.json`. |
|
|
|
|
## Event Schema (summary)
|
|
- `finding_records` (canonical): includes advisory/VEX/SBOM refs, `policyVersion`, `sourceRunId`, `explainBundleRef`, tenant, artifact identifiers.
|
|
- `finding_history`: append-only transitions with actor, scope, justification, timestamps (UTC, ISO-8601), hash-chained.
|
|
- `triage_actions`: discrete operator actions (comment, assign, remediation, ticket link) with immutable provenance.
|
|
- `remediation_plans`: planned fixes linked to findings; optional due dates and checkpoints.
|
|
|
|
> See `docs/modules/findings-ledger/schema.md` for authoritative field names; update this section when GRAP0101 finalizes.
|
|
|
|
## Hashing & Merkle Roots
|
|
- Per-event SHA-256 digests; history and actions chained by previous hash to ensure tamper evidence.
|
|
- Periodic Merkle roots anchored per tenant + artifact namespace; policy version included in leaf payloads.
|
|
- Export bundles carry `manifest.json` + `audit_log.jsonl` with hashes; verify against Merkle roots.
|
|
|
|
## Replay & Verification
|
|
- Replay harness (`replay-harness.md`) replays `finding_history` + `triage_actions` to reconstruct `finding_records` and compare hashes.
|
|
- Use `golden-checksums.json` to validate deterministic output; include hash of replay output in `SHA256SUMS` once fixtures copied here.
|
|
|
|
## Offline/Determinism Notes
|
|
- All sample logs/responses added to this doc must have hashes recorded in `docs/assets/vuln-explorer/SHA256SUMS`.
|
|
- Use fixed fixture IDs; avoid live timestamps; maintain sorted outputs.
|
|
|
|
### Hash Capture Checklist (when fixtures are pulled)
|
|
- `assets/vuln-explorer/ledger-history.jsonl` (sample history entries)
|
|
- `assets/vuln-explorer/ledger-actions.jsonl` (triage actions snippet)
|
|
- `assets/vuln-explorer/ledger-replay-output.json` (replay harness output)
|
|
- `assets/vuln-explorer/ledger-manifest.json` (export manifest sample)
|
|
|
|
## Open Items
|
|
- Replace schema placeholders once GRAP0101 and security review land.
|
|
- Add sample history/action entries and replay verification commands with hashes.
|
|
- Document attachment token validation path when security review provides final wording.
|
|
|
|
_Last updated: 2025-12-05 (UTC)_
|