Skip to content
CommonLayer
Documentation menu
On this page

ADR-0028: Verification-policy waivers are explicit, and some checks are never waivable

Status: Accepted (WP-11). Implemented in crates/commonlayer-artifacts/src/domain/policy.rs.

Context

The verification policy (17 checks) must block anything that is not what it claims to be, but some standards have legitimate exceptions (the base image cannot have a health check of its own; an upstream may need a different user).

Decision

  • A failing check becomes waived only through a recorded exception:
    1. a deviation in the project's manifest for the image standards non-root (check image.nonroot) and labels (check image.labels), or
    2. a waiver in the platform policy naming the project, the check, a reason of at least 20 characters, who recorded it and an optional expiry (PUT /api/v1/verification-policy, platform.settings.manage).
  • source.matches_manifest, digest.verified, version.declared, signature.valid and signature.identity can never be waived.
  • A project policy can only tighten the platform policy (stricter scan gate, more platforms or labels, fewer accepted SBOM formats); it can never carry waivers or turn provenance off.
  • scan.gate exceptions come from the security domain's approved exceptions and not_affected VEX statements, not from the verification policy.

Consequences

  • The checks that establish what an artifact is and who built it cannot be bypassed by any configuration.
  • Each verification stores the effective policy and the signing identity in force, and the verification instructions are built from that snapshot.