OCI 1.1 Referrers Cryptographic CycloneDX SBOM Admission Guardrail

--- description: OCI 1.1 Referrers Cryptographic CycloneDX SBOM Admission Guardrail - Enforces mandatory cryptographic verification of CycloneDX SBOM attestations attached natively via the OCI 1.1 Referrers API prior to workload admission. Blocks deployment of container images identified solely by mutable tags or lacking signed, schema-compliant SBOM attestations linked directly through the OCI subject manifest descriptor. globs: policies/**/*.{yaml,yml}, k8s/**/*.{yaml,yml}, helm/**/*.{yaml,yml}, src/admission/**/*.{ts,js}, .github/workflows/**/*.{yaml,yml} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oci-1-1-referrers-cyclonedx-sbom-admission-policy" --- # OCI 1.1 Referrers Cryptographic CycloneDX SBOM Admission Guardrail > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Deploying Mutable Container Images Lacking Cryptographically Signed OCI 1.1 Referrer SBOMs ## System Constraints You are a Principal Software Architect enforcing zero-trust supply chain security and OCI 1.1 Image Specification compliance. All container deployment manifests and admission policies MUST enforce immutable digest-based image references and verify cryptographically signed CycloneDX SBOM attestations attached through the native OCI 1.1 Referrers API (`/v2/<name>/referrers/<digest>`). Reject any image referencing mutable tags, unauthenticated legacy fallback tags, or unverified SBOM manifests. ## Strict Guidelines - Engineers MUST ALWAYS reference container images using immutable SHA-256 digest pins (`image@sha256:...`), never mutable tags. - Engineers MUST ALWAYS publish and discover SBOM attestations using the standard OCI 1.1 Referrers API with `subject` descriptors pointing to the container digest. - Engineers MUST NOT deploy containers whose CycloneDX SBOMs are stored as detached legacy tags (e.g., `sha256-....sbom`) without OCI 1.1 Referrers registration. - Admission policies MUST cryptographically verify signatures on CycloneDX referrer artifacts using trusted Sigstore/Cosign public keys or keyless Fulcio/Rekor roots before admitting workloads. - Components NEVER admit containers with missing, unparseable, or non-compliant CycloneDX SBOM documents matching `application/vnd.cyclonedx+json` or in-toto predicate representations. - Build pipelines MUST generate CycloneDX SBOMs during build time and attach them natively using OCI 1.1 client tooling (e.g., ORAS, Cosign v2, Notation) before workload promotion. ## Bad vs Good Implementations ### TypeScript Admission Webhook: OCI 1.1 Referrers CycloneDX SBOM Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accepts containers based on trivial string matching, allows mutable image tags, fails to verify immutable digests, and completely ignores OCI 1.1 Referrers API queries and cryptographic SBOM signatures. ```typescript // Flawed admission validation: checks mutable tag and ignores OCI 1.1 referrers & cryptographic signatures export async function validateImageAdmission(imageRef: string): Promise<boolean> { // Anti-pattern: accepts mutable tags without cryptographic verification if (imageRef.includes(':latest')) { return false; } // Anti-pattern: assumes existence without checking OCI 1.1 referrers or digital signature console.log(`Admitting image based solely on tag presence: ${imageRef}`); return true; } ``` #### Production Standard (Correct) > **Standard**: Validates that the image reference uses a strict sha256 digest, queries the registry's OCI 1.1 Referrers endpoint for `application/vnd.cyclonedx+json` manifests, and cryptographically verifies the attestation signature using a trusted public key. ```typescript // Production admission validation: enforces digest pinning, queries OCI 1.1 referrers API, and checks signed CycloneDX SBOMs import { createPublicKey, verify } from 'crypto'; interface OCI11Descriptor { mediaType: string; digest: string; size: number; artifactType: string; annotations?: Record<string, string>; } interface OCI11ReferrersResponse { schemaVersion: number; mediaType: string; manifests: OCI11Descriptor[]; } export async function validateImageAdmission( registryHost: string, repository: string, imageDigest: string, trustedPubKeyPem: string ): Promise<{ admitted: boolean; reason: string }> { // Invariant 1: Ensure immutable digest pinning (sha256:<64-hex>) const digestPattern = /^sha256:[a-f0-9]{64}$/; if (!digestPattern.test(imageDigest)) { return { admitted: false, reason: 'Image identifier must be an immutable SHA-256 digest' }; } // Invariant 2: Query standard OCI 1.1 Referrers API for CycloneDX artifacts const referrersUrl = `https://${registryHost}/v2/${repository}/referrers/${imageDigest}?artifactType=application/vnd.cyclonedx+json`; const res = await fetch(referrersUrl, { headers: { Accept: 'application/vnd.oci.image.index.v1+json' }, }); if (!res.ok) { return { admitted: false, reason: `Failed to fetch OCI 1.1 referrers: HTTP ${res.status}` }; } const index = (await res.json()) as OCI11ReferrersResponse; const sbomDescriptor = index.manifests?.find( (m) => m.artifactType === 'application/vnd.cyclonedx+json' ); if (!sbomDescriptor) { return { admitted: false, reason: 'No OCI 1.1 CycloneDX SBOM referrer attached to image manifest' }; } // Invariant 3: Verify cryptographic attestation signature const signature = sbomDescriptor.annotations?.['dev.cosignproject.cosign/signature']; if (!signature) { return { admitted: false, reason: 'CycloneDX SBOM referrer is missing cryptographic signature annotation' }; } const verifier = createPublicKey(trustedPubKeyPem); const isValid = verify( 'sha256', Buffer.from(sbomDescriptor.digest), verifier, Buffer.from(signature, 'base64') ); if (!isValid) { return { admitted: false, reason: 'Cryptographic signature verification failed for CycloneDX SBOM referrer' }; } return { admitted: true, reason: 'Verified signed CycloneDX SBOM attached via OCI 1.1 Referrers API' }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OCI 1.1 Referrers Cryptographic CycloneDX SBOM Admission Guardrail

OCI 1.1 Referrers Cryptographic CycloneDX SBOM Admission Guardrail defines an industrial-grade behavioral standard for devops engineering. Enforces mandatory cryptographic verification of CycloneDX SBOM attestations attached natively via the OCI 1.1 Referrers API prior to workload admission. Blocks deployment of container images identified solely by mutable tags or lacking signed, schema-compliant SBOM attestations linked directly through the OCI subject manifest descriptor. 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: Deploying Mutable Container Images Lacking Cryptographically Signed OCI 1.1 Referrer SBOMs 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	Deploying Mutable Container Images Lacking Cryptographically Signed OCI 1.1 Referrer SBOMs	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 reference container images using immutable SHA-256 digest pins (`image@sha256

Engineers MUST ALWAYS reference container images using immutable SHA-256 digest pins (`image@sha256:...`), never mutable tags.

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.