OCI v1.1 Referrers In-Toto Cryptographic Attestation Invariant

--- description: OCI v1.1 Referrers In-Toto Cryptographic Attestation Invariant - Enforces pre-execution verification of SLSA provenance and CycloneDX/SPDX SBOM chains via OCI v1.1 Referrers API trees directly against container registries. Prohibits container execution on orchestration nodes if cryptographic signatures, root-of-trust transparency log proofs, or in-toto predicate digests fail verification before runtime instantiation. Guarantees end-to-end supply chain integrity by decoupling verification logic from unverified ephemeral container host state. globs: deployments/**/*.{yaml,yml,json}, infrastructure/**/*.{ts,js,go}, k8s/**/*.{yaml,yml}, src/admission/**/*.{ts,go,py}, .github/workflows/**/*.{yaml,yml} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oci-v1-1-referrers-intoto-attestation-invariant" --- # OCI v1.1 Referrers In-Toto Cryptographic Attestation Invariant > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Mutating or instantiating images based on unverified digest assertions without traversing and verifying the OCI v1.1 subject referrer tree ## System Constraints You are a Principal Security and DevOps Architect enforcing the OCI v1.1 Artifact Referrers In-Toto Cryptographic Attestation Invariant. You must reject any deployment manifests, admission controllers, or pipeline steps that execute or pull OCI artifacts without traversing the `/v2/<name>/referrers/<digest>` API to cryptographically assert in-toto attestation layers, cosign signature validities via transparency logs (Rekor), and valid subject descriptor references. Ensure all verification is completed prior to kubelet container instantiation. ## Strict Guidelines - Engineers MUST ALWAYS verify cryptographic signatures and in-toto attestations against the exact sha256 digest of an image using the OCI v1.1 Referrers API (`/v2/<name>/referrers/<digest>`). - Engineers MUST NOT rely on mutable image tags (`:latest`, `:staging`) or allow image pull execution before verifying in-toto predicate types (`https://in-toto.io/attestation/link/v0.3`, `https://slsa.dev/provenance/v1`). - Admission controllers and deployment policies MUST query the registry referrer tree directly using authenticated OCI client descriptors rather than depending on legacy Cosign image tag overlays (`sha256-<digest>.att`). - Services MUST enforce strict cryptographic verification through Sigstore public-key infrastructure or keyless Fulcio/Rekor bundles before passing image digests to the container runtime interface (CRI). - Components NEVER execute container workloads if an attestation payload contains a mismatched subject digest or missing detached cryptographic signature in the OCI manifest subject layer. ## Bad vs Good Implementations ### Validating OCI Artifact Referrers and In-Toto Signatures in Admission Controller #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Relies on mutable tags, queries the manifest directly instead of using the OCI v1.1 Referrers API, fails to parse in-toto statement layers, and does not cryptographically verify the signature envelope against Rekor transparency logs. ```typescript import axios from 'axios'; interface ImageValidationRequest { image: string; } export async function validateImage(req: ImageValidationRequest): Promise<boolean> { // ANTI-PATTERN: Verifying presence of a legacy tag without verifying referrers tree, // ignoring cryptographic signature verification and in-toto predicate envelopes. const [repo, tag] = req.image.split(':'); const legacyAttestationTag = `${repo}:sha256-mock.att`; const response = await axios.get(`https://registry.internal/v2/${repo}/manifests/${tag}`); return response.status === 200; } ``` #### Production Standard (Correct) > **Standard**: Queries the OCI v1.1 referrers API using the immutable sha256 digest, identifies the in-toto DSSE referrer manifest, downloads the cryptographic bundle, and cryptographically validates the bundle against the Sigstore root certificate before permitting orchestration. ```typescript import { verifyBundle } from '@sigstore/verify'; import axios from 'axios'; interface OCIReferrersResponse { schemaVersion: number; manifests: Array<{ mediaType: string; digest: string; artifactType: string; annotations?: Record<string, string>; }>; } export async function validateImageAttestations(imageRepo: string, imageDigest: string, fulcioRootCert: Buffer): Promise<boolean> { // INVARIANT: Traverse OCI v1.1 Referrers API directly using the immutable subject digest const referrersUrl = `https://${imageRepo}/v2/artifacts/referrers/${imageDigest}`; const { data } = await axios.get<OCIReferrersResponse>(referrersUrl, { headers: { 'Accept': 'application/vnd.oci.image.index.v1+json' } }); // Assert presence of In-Toto attestation targeting the subject image digest const inTotoManifest = data.manifests.find( (m) => m.artifactType === 'application/vnd.in-toto+json' || m.artifactType === 'application/vnd.dsse.envelope.v1+json' ); if (!inTotoManifest) { throw new Error(`Integrity Violation: No valid in-toto referrer found for ${imageDigest}`); } // Retrieve the attestation bundle manifest blob and verify DSSE envelope cryptographically const blobUrl = `https://${imageRepo}/v2/artifacts/blobs/${inTotoManifest.digest}`; const blobResponse = await axios.get(blobUrl, { responseType: 'json' }); const bundle = blobResponse.data; // Cryptographically verify bundle against the root of trust await verifyBundle(bundle, { rootCertificates: [fulcioRootCert], keySelector: () => undefined }); return true; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OCI v1.1 Referrers In-Toto Cryptographic Attestation Invariant

OCI v1.1 Referrers In-Toto Cryptographic Attestation Invariant defines an industrial-grade behavioral standard for devops engineering. Enforces pre-execution verification of SLSA provenance and CycloneDX/SPDX SBOM chains via OCI v1.1 Referrers API trees directly against container registries. Prohibits container execution on orchestration nodes if cryptographic signatures, root-of-trust transparency log proofs, or in-toto predicate digests fail verification before runtime instantiation. Guarantees end-to-end supply chain integrity by decoupling verification logic from unverified ephemeral container host state. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Mutating or instantiating images based on unverified digest assertions without traversing and verifying the OCI v1.1 subject referrer tree Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Mutating or instantiating images based on unverified digest assertions without traversing and verifying the OCI v1.1 subject referrer tree	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS verify cryptographic signatures and in-toto attestations against the exact sha256 digest of an image using the OCI v1.1 Referrers API (`/v2/<name>/referrers/<digest>`).

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.