stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
491e8836535ab3daa30eff7a77f76f5b00331a74
git.stella-ops.org/docs/_archive/vuln/findings-ledger.md
master 491e883653 Add tests for SBOM generation determinism across multiple formats 
- 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.
2025-12-24 00:36:14 +02:00

3.0 KiB
Raw Blame History

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)