stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
e716bc6adca8d1a3ac5a24ad491e5fa99e31cf1c
git.stella-ops.org/docs/modules/evidence-locker/portable-audit-pack-determinism.md
master cf5b72974f save checkpoint
2026-02-11 01:32:14 +02:00

1.8 KiB
Raw Blame History

Portable Audit Pack Determinism Profile

Status: Draft frozen for implementation handoff (2026-02-10).

Scope

Deterministic requirements for portable pack generation (manifest.json, BOM, DSSE envelope, Rekor material, optional VEX/Parquet artifacts).

Normative rules

  1. Canonical JSON MUST use RFC 8785/JCS-compatible serialization.
  2. File inventory in manifest.files MUST be lexicographically sorted by canonical path.
  3. Archive entries MUST have fixed metadata:
    • mtime: 2026-01-01T00:00:00Z
    • uid/gid: 0/0
    • file mode 0644, directory mode 0755
  4. Digests MUST be lowercase SHA-256 hex.
  5. Optional artifacts (merged_vex.json, components.parquet) MUST not change ordering of required files.
  6. Compression toolchain versions MUST be pinned in release manifests.

Canonicalization conformance tests (required)

  • Nested object key ordering stability.
  • Unicode normalization and escaping stability.
  • Non-finite number rejection (NaN, Infinity).
  • DSSE payload preimage digest stability across repeated runs.

Byte stability gate

  • CI must generate the same pack twice from identical frozen input fixtures.
  • Outputs must be byte-identical (sha256sum pack1 == pack2).
  • On mismatch, pipeline fails with ERR_PACK_NON_DETERMINISTIC.

Deterministic fixture layout

  • testvectors/portable-audit-pack/minimal/
  • testvectors/portable-audit-pack/with-vex/
  • testvectors/portable-audit-pack/with-parquet/

Each fixture set should include:

  • inputs (sbom.json, optional vex.json)
  • expected canonical files
  • expected per-file SHA-256 digests
  • expected package archive digest

Toolchain pin set (to be implemented)

  • JCS canonicalizer version
  • DSSE signer library version
  • tar implementation/version
  • compression implementation/version
  • Parquet writer version (if profile enabled)