Skip to content

feat(compliance)!: stamp deployment posture in batch attestations - #767

Merged
lahlfors merged 2 commits into
mainfrom
feat/attestation-posture-stamp
Nov 15, 2026
Merged

lahlfors merged 2 commits into
mainfrom
feat/attestation-posture-stamp

Conversation

@lahlfors

@lahlfors lahlfors commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Stacked on #766 (fix/gate-w-tunnel-ordering).

Stamps deployment_posture inside KMS-signed WORM batch attestations (cage-evidence-batch/2) emitted by EvidenceCustodian, surfaces structural posture provenance and v1 qualification in CustodyVerifier, and binds all three post-8956f505 archive disclosures (POAM-2026-220, POAM-2026-219, EP-1) to a single APAC_MAS (asia-southeast1) --fresh-project Gate W discharge in compliance/gate_w_certification.json:

  1. cage-evidence-batch/2 posture stamping (EvidenceCustodian):
    • Emits "schema": "cage-evidence-batch/2" with "deployment_posture" ("production" or "staging") inside the RFC 8785 JCS-canonicalized KMS signing payload (EVIDENCE_KMS_KEY).
    • Rejects require_signature=True when deployment_posture is outside {"production", "staging"} (dev, test, ci, local), ensuring permissive software/local runs write .attestation.unsigned.json only.
    • Rejects cross-posture v2 batches during cold-store cursor recovery (EvidenceCustodian._recover_cursor_from_cold_store), archive verification (CustodyVerifier._check_posture_consistency), and authoritative custody-chain metrics reads (metrics._read_cold_store_records_async), while allowing seamless v1 -> v2 upgrades.
  2. Structural citable qualification + three-valued posture_status (CustodyVerifier):
    • Pre-stamping cage-evidence-batch/1 archives (gate-w-8956f505, fa772122) remain citable=True by default without requiring any opt-in flag, accompanied by citable_qualifications=["unstamped_v1_posture"] (vs. [] for v2), making citable and not citable_qualifications a distinct machine-readable state (assert_citable(allow_qualifications=False), CLI --require-unqualified, HTTP GET /v1/evidence/verify?require_unqualified=true).
    • Adds three-valued posture_status ("production" | "staging" | "unstamped_v1", or None when !ok / empty). Because "unstamped_v1" is neither "staging" nor "production", any consumer handling only the two stamped postures fails loudly rather than defaulting to "production".
    • Propagates evidence-custody-posture-status and evidence-custody-qualification props into OSCAL Assessment Results (oscal_exporter.py), supports v1 and v2 preimage corroboration in cage-conformance (AS-6), requires posture_status == "staging" and citable_qualifications == [] on --fresh-project clean-room Gate W runs (scripts/staging_lifecycle.sh), and updates OSCAL au-9.3 census/register artifacts, compliance/gate_w_certification.json (custody_posture_qualification + combined next_gate_w_discharge), and EP-1 in docs/BREAKING_CHANGES.md.

Security Bound on Accepting cage-evidence-batch/1

Accepting pre-stamping cage-evidence-batch/1 attestations alongside cage-evidence-batch/2 does not open a posture-downgrade path:

  • Both "schema" and "deployment_posture" live inside the RFC 8785 JCS-canonicalized preimage signed by EVIDENCE_KMS_KEY and verified against out-of-band trust anchors (EVIDENCE_TRUST_ANCHORS_FILE / KMS public key).
  • Relabelling a signed cage-evidence-batch/2 attestation as "cage-evidence-batch/1", stripping "deployment_posture", or mutating "staging" to "production" alters the canonical preimage and fails asymmetric signature verification without possession of the KMS signing key (TestPostureStampingAndV1Qualification::test_downgrade_or_posture_mutation_without_signing_key_breaks_signature).
  • Current EvidenceCustodian emits only cage-evidence-batch/2, and assert_citable() rejects v1 payloads carrying deployment_posture, v2 payloads missing deployment_posture, and v2 payloads carrying any posture outside {"production", "staging"} even if signed.

Verification

  • uv run pytest (make test-fast): 10,884 passed, 75 skipped, 6 subtests passed (0 failed), including v1/v2 posture stamping, structural qualification, cross-posture archive rejection, KMS preimage downgrade-attack resistance, CLI/HTTP --require-unqualified, OSCAL posture props, cage-conformance v1/v2 corroboration, and staging_lifecycle.sh --fresh-project posture gate tests.
  • uv run bandit -r src/ scripts/ -c pyproject.toml -ll -ii: 0 issues across 136,257 lines of code (src/: 108,245 lines; scripts/: 28,012 lines).
  • Deterministic compliance & architecture gates:
    • python scripts/check_oscal_claim_census.py (209 census entries validated, 0 errors)
    • python scripts/check_poam_lula_divergence.py (0 divergences)
    • python scripts/check_doc_references.py (70 doc files, 0 broken references)
    • python scripts/check_import_boundaries.py, check_vendor_brands.py, check_gate_w_freshness.py
    • CAGE_DEPLOYMENT_REGION={US_FED,EU_ECB,APAC_MAS} python -m src.gateway.governance.oscal_ssp_exporter export --check

BREAKING CHANGE: Signed custody batch attestations now emit schema cage-evidence-batch/2 with a required deployment_posture field (EP-1 in docs/BREAKING_CHANGES.md). External tools pinning schema == "cage-evidence-batch/1" must accept cage-evidence-batch/2; strict posture consumers should check posture_status and citable_qualifications == [].

@lahlfors
lahlfors force-pushed the fix/gate-w-tunnel-ordering branch from cdb9c77 to 63af3d0 Compare November 15, 2026 18:53
Stamp deployment_posture inside KMS-signed cage-evidence-batch/2 custody
attestations emitted by EvidenceCustodian and surface structural posture
provenance in CustodyVerifier without invalidating pre-stamping v1 archives.

- Bump EvidenceCustodian schema from cage-evidence-batch/1 to
  cage-evidence-batch/2 with deployment_posture in {production, staging} inside
  the JCS-canonicalized KMS signing preimage; refuse require_signature=True on
  non-citable postures and refuse cross-posture v2 batches on cold-store cursor
  recovery, archive verification, and metrics aggregation.
- Keep pre-stamping cage-evidence-batch/1 archives (gate-w-8956f505, fa77212)
  citable=True by default while returning
  citable_qualifications=["unstamped_v1_posture"] (vs. [] on v2) and
  three-valued posture_status in {production, staging, unstamped_v1} (None when
  !ok or empty).
- Add allow_qualifications=False, CLI --require-unqualified, HTTP
  GET /v1/evidence/verify?require_unqualified=true, OSCAL Assessment Results
  custody posture/qualification props, v1/v2 audit corroboration support, and
  clean-room Gate W staging posture assertions.

BREAKING CHANGE: Signed custody batch attestations now emit schema
cage-evidence-batch/2 with a required deployment_posture field (EP-1 in
docs/BREAKING_CHANGES.md). External tools pinning
schema == "cage-evidence-batch/1" must accept cage-evidence-batch/2; strict
posture consumers should check posture_status and citable_qualifications == [].
Add next_gate_w_discharge to compliance/gate_w_certification.json tying
residency_result_breakdown (POAM-2026-220),
lula_result_breakdown.ratings_from_2026_11_14 (POAM-2026-219), and
custody_posture_qualification (EP-1) to a single APAC_MAS (asia-southeast1)
--fresh-project Gate W run so all three archive disclosures discharge together
rather than piecemeal, and reconcile the posture-stamping note in README.md.
@lahlfors
lahlfors force-pushed the feat/attestation-posture-stamp branch from 5c66378 to 46af4af Compare November 15, 2026 19:06
@lahlfors
lahlfors changed the base branch from fix/gate-w-tunnel-ordering to main November 15, 2026 19:06
@lahlfors
lahlfors merged commit 9b2b745 into main Nov 15, 2026
50 checks passed
@lahlfors
lahlfors deleted the feat/attestation-posture-stamp branch November 15, 2026 19:19
lahlfors added a commit that referenced this pull request Nov 15, 2026
Open POAM-2026-221 documenting the vacuous GitHub Actions windows uncovered
by failing check_stpa_freshness.py closed in #768:
- ci.yml::stpa-freshness-check (49c0d09 #694 2026-11-08 through 9b2b745
  #767 2026-11-15, 70 squash-merged PRs) caught ModuleNotFoundError for
  opentelemetry inside render_default_oscal_artifacts(raise_on_error=False)
  and fell back to commit-order checking on all 3 US_FED OSCAL files.
- ci.yml::sbom-generate (8c6e936 #16, 2026-06-15..2026-11-15) and
  security-scan.yml::sbom-generation (1902c92, 2026-06-01..2026-11-15)
  ran cyclonedx against unsynced runner environments containing zero CAGE
  packages.

Default render_default_oscal_artifacts() to raise_on_error=True, delete
ContentCheck.UNAVAILABLE and the commit-order fallback from
check_stpa_freshness.py so inability-to-check is unconditionally a failure,
enforce MIN_PYTHON_SBOM_COMPONENTS=20 in generate_sbom.py and ci.yml,
switch all six narrow-pip workflow jobs to uv sync, add an in-job
red-before-green planted-drift canary on both STPA and US_FED OSCAL
artifacts, qualify POAM-2026-176 and POAM-010 citations with dated notes,
and guard workflow uv-sync parity in test_ci_workflow_dependency_sync.py.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant