OCI 1.1 Referrers Index In-Toto Provenance Admission Gate Guardrail

--- description: OCI 1.1 Referrers Index In-Toto Provenance Admission Gate Guardrail - Enforces deterministic traversal and cryptographic verification of the OCI 1.1 referrers index to mandate in-toto SLSA provenance at Kubernetes admission. Workloads referencing mutable tags, missing cryptographically signed attestations, or failing trusted root builder identity checks must be strictly rejected prior to scheduling. globs: admission/**/*.{ts,go}, policies/**/*.{rego,yaml}, src/controllers/**/*.{ts,go}, k8s/admission/**/*.{ts,yaml} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oci-v1-1-referrers-intoto-provenance-admission-guardrail" --- # OCI 1.1 Referrers Index In-Toto Provenance Admission Gate Guardrail > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Admitting Pods Based on Mutable Image Tags with Unverified or Missing OCI 1.1 In-Toto Provenance Attestations ## System Constraints You are a Principal Software Architect and Rules Author enforcing strict OCI 1.1 Referrers Index In-Toto Provenance Admission standards. You must mandate that every container image admitted into Kubernetes clusters is resolved strictly by its immutable digest (`sha256:...`), verified against an OCI 1.1 Referrers index (`/v2/<name>/referrers/<digest>`), and evaluated for valid in-toto attestation envelopes containing SLSA Provenance. Ensure that builder identities, cryptographic signatures, and subject digests strictly match before admitting any workload. ## Strict Guidelines - Engineers MUST ALWAYS resolve container images to an immutable SHA-256 digest before initiating admission queries, rejecting any image specified solely by mutable tag. - Engineers MUST query the registry using the OCI 1.1 Referrers API (`/v2/<name>/referrers/<digest>?artifactType=application/vnd.in-toto+json`) to locate cryptographic attestations deterministically. - Engineers MUST NOT trust in-cluster or webhook runtime caches that bypass cryptographic signature verification against a pinned Sigstore TUF root or enterprise KMS key. - Code SHOULD verify the predicate type `https://slsa.dev/provenance/v1` and strictly validate that `subject.digest.sha256` in the in-toto statement matches the admitting image digest. - Services MUST reject admissions with an explicit HTTP 403 / AdmissionResponse Denied if the image lacks an in-toto provenance attestation signed by an authorized builder identity. - Components NEVER fall back to unauthenticated or insecure HTTP registries when querying the OCI 1.1 referrers index tree. ## Bad vs Good Implementations ### Validating OCI 1.1 Referrers Index and In-Toto Provenance in Admission Webhook #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The handler allows images without resolving immutable digests and relies on basic string heuristics. It completely ignores OCI 1.1 referrers index traversal, skips cryptographic in-toto provenance envelope verification, and fails to authenticate the builder identity. ```typescript import { AdmissionReview, AdmissionResponse } from './types'; export async function validateAdmission(review: AdmissionReview): Promise<AdmissionResponse> { const pod = review.request.object; for (const container of pod.spec.containers) { // ANTI-PATTERN: Admitting based purely on mutable tags without digest resolution // and trusting external annotations without cryptographically checking OCI 1.1 referrers. if (container.image.endsWith(':latest')) { return { uid: review.request.uid, allowed: false, status: { message: 'latest tag forbidden' } }; } if (container.image.includes('trusted-registry.io')) { // Implicit trust without verifying cryptographic in-toto provenance continue; } } return { uid: review.request.uid, allowed: true }; } ``` #### Production Standard (Correct) > **Standard**: The production-ready validator mandates pinned digest references, traverses the OCI 1.1 referrers tree for the exact in-toto provenance descriptor, cryptographically verifies the DSSE envelope against the trusted root, and ensures the SLSA predicate and builder identity match expected policy constraints. ```typescript import { AdmissionReview, AdmissionResponse } from './types'; import { verifyOciReferrersProvenance } from './crypto/oci11-verifier'; const EXPECTED_BUILDER_ID = 'https://github.com/org/repo/.github/workflows/release.yml@refs/heads/main'; const DIGEST_REGEX = /^[a-z0-9._/-]+@sha256:[a-f0-9]{64}$/; export async function validateAdmission(review: AdmissionReview): Promise<AdmissionResponse> { const uid = review.request.uid; const pod = review.request.object; const containers = [...(pod.spec.initContainers || []), ...pod.spec.containers]; for (const container of containers) { const imageRef = container.image; // Invariant 1: Force immutable digest pinning if (!DIGEST_REGEX.test(imageRef)) { return { uid, allowed: false, status: { code: 400, message: `Image '${imageRef}' must be pinned by SHA-256 digest.` } }; } const [repository, digest] = imageRef.split('@'); const cleanDigest = digest.replace('sha256:', ''); try { // Invariant 2 & 3: Traversal of OCI 1.1 Referrers tree and cryptographic in-toto SLSA check const verificationResult = await verifyOciReferrersProvenance({ repository, digest: cleanDigest, artifactType: 'application/vnd.in-toto+json', expectedPredicateType: 'https://slsa.dev/provenance/v1', expectedBuilderId: EXPECTED_BUILDER_ID }); if (!verificationResult.isValid) { return { uid, allowed: false, status: { code: 403, message: `Provenance verification failed for '${imageRef}': ${verificationResult.reason}` } }; } } catch (err) { return { uid, allowed: false, status: { code: 500, message: `Error verifying OCI 1.1 referrers for '${imageRef}': ${(err as Error).message}` } }; } } return { uid, allowed: true }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OCI 1.1 Referrers Index In-Toto Provenance Admission Gate Guardrail

OCI 1.1 Referrers Index In-Toto Provenance Admission Gate Guardrail defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic traversal and cryptographic verification of the OCI 1.1 referrers index to mandate in-toto SLSA provenance at Kubernetes admission. Workloads referencing mutable tags, missing cryptographically signed attestations, or failing trusted root builder identity checks must be strictly rejected prior to scheduling. 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: Admitting Pods Based on Mutable Image Tags with Unverified or Missing OCI 1.1 In-Toto Provenance Attestations 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	Admitting Pods Based on Mutable Image Tags with Unverified or Missing OCI 1.1 In-Toto Provenance Attestations	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 resolve container images to an immutable SHA-256 digest before initiating admission queries, rejecting any image specified solely by mutable tag.

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.