git.stella-ops.org/docs/modules/policy/cvss-v4.md

CVSS v4.0 Receipts – Hardening Guide

Source advisory: docs/product-advisories/25-Nov-2025 - Add CVSS v4.0 Score Receipts for Transparency.md (CV1–CV10). This guide turns the gaps into implementable rules for Sprint 0190.

Canonical hashing (CV2)

• Serializer: JSON Canonicalization Scheme (JCS).
• Ordering: lexicographic keys; arrays keep order; drop nulls.
• Numbers: fixed 4-decimal precision; invariant culture; no exponent.
• Time: UTC ISO-8601 Z; strip milliseconds unless non-zero.
• Hash: SHA-256 of canonical JSON; store as inputsHash and DSSE subject.
• Test vectors: tests/Policy/StellaOps.Policy.Scoring.Tests/Fixtures/hashing/ (receipt-input.json + receipt-input.sha256).
• Recompute locally:

  python - <<'PY'
  import json, hashlib, pathlib
  data=json.loads(pathlib.Path('tests/Policy/StellaOps.Policy.Scoring.Tests/Fixtures/hashing/receipt-input.json').read_text())
  canon=json.dumps(data, sort_keys=True, separators=(',', ':'), ensure_ascii=False)
  print(hashlib.sha256(canon.encode()).hexdigest())
  PY
  

Policy replay & backfill (CV1)

• Policies immutable; bump version for any change.
• On change, emit new receipts with supersedesReceiptId and retain old ones.
• Backfill job: re-score under new policy, append history, re-sign DSSE.

Tenant segregation & RBAC (CV4, CV9)

• Storage keys include tenantId; hashes/DSSE annotate tenant.
• Roles: Security Engineer (Base), SOC Analyst (Threat), Customer Admin (Env), Viewer (read-only).
• Enforce at API/repo layer and in canonical hash.

Deterministic exports (CV8)

• JSON export: JCS ordering, UTF-8, UTC timestamps, stable severity palette.
• PDF export: embed fonts (Source Sans 3 + Roboto Mono), A4, fixed margins; hash PDF bytes and persist exportHash.
• Offline receipt bundle: include JSON, PDF, DSSE envelope, and policy hash; tar with sorted names + fixed mtime.

v3.1 → v4.0 conversion (CV5)

• Deterministic mapping; tag source: "converted-v3.1", set conversionMethod + confidence; retain vendor vector.
• Record conversionHash of the original v3.1 vector (JCS + SHA-256) and store in receipt history for audit.

Evidence provenance (CV6)

• Evidence items use CAS URIs + DSSE refs, include retentionClass, redactionStatus, verifiedAt, hashMismatch.
• Receipt schema enforces evidence array; DSSE subject hash must match inputsHash.

Immutability & monitoring (CV7, CV10)

• Receipts append-only; amendments create new IDs + DSSE.
• Alerts: DSSE verify failures, policy hash drift, hash mismatch, engine version skew. Prometheus counters: cvss_receipt_dsse_failures_total, cvss_policy_drift_total, cvss_hash_mismatch_total.
• Receipt history includes supersedesReceiptId and amendsReceiptId; policy backfill job must set supersedesReceiptId when replaying.
• Dashboard SLO: DSSE failure rate <0.1% per 24h; policy drift alerts page security on-call.

Golden fixtures & locations

• Hashing vectors: tests/Policy/StellaOps.Policy.Scoring.Tests/Fixtures/hashing/receipt-input.json with expected hash receipt-input.sha256.
• Receipt DSSE/PDF examples to live under tests/Policy/StellaOps.Policy.Scoring.Tests/Fixtures/receipts/ as exports land.
• Sample PDFs in Fixtures/exports/ once generated; hash each to *.pdf.sha256.

Implementation checklist

• Wire ReceiptCanonicalizer to JCS rules above.
• Add backfill job + history persistence.
• Enforce tenant/RBAC and annotate hashes/DSSE.
• Implement deterministic PDF export and record exportHash.
• Store conversion metadata for v3.1 sources.
• Verify evidence CAS/DSSE on ingest; fail closed.
• Expose metrics/alerts listed above.