OCI referrers link an artifact to an image, not to a trusted signer
Container registries have become artifact stores. An OCI image may carry a software bill of materials, a vulnerability report, a signature, or another attestation as a separate manifest related to the image. OCI 1.1 added a subject field and an API for listing referrers. That makes the association easier to discover and easier to automate. It does not make the associated artifact trustworthy.
A scanner can ask a registry for referrers to an image digest, find an artifact whose artifactType says signature, and report the image as signed. The useful question comes next: who created the artifact, what exactly did they sign, which policy accepted that identity, and can a deployment enforce the result? A registry reference is a transport relationship. Trust is a separate decision.
What the specification defines
The OCI Distribution Specification defines a protocol for storing and distributing content. A manifest can reference other manifests and blobs through descriptors. The image specification's subject field associates one manifest with another, typically to attach an artifact to an image. artifactType gives the attached artifact a type.
The referrers API returns manifests that reference a subject digest. A client that pushes a manifest with a subject field should verify that the API is available or use the fallback tag schema defined by the specification. The fallback exists because registries may implement partial or older versions of the distribution API.
That fallback is one reason not to equate a query result with a complete security record. A registry can expose artifacts through a different path or at a different time from the image. A client that only reads one endpoint may miss a signature, or it may find a stale association that the operator no longer wants to honor.
Association and authenticity are different
The subject descriptor includes a digest. Changing the referenced content changes the digest and therefore changes which subject the artifact is attached to. That gives the association content integrity. It does not prove who pushed the artifact. A registry may allow a repository writer to attach a manifest with any supported artifact type and annotations.
A signature artifact should be verified with the cryptographic rules of its own format. If it uses a signing system such as Sigstore, the verifier must check the signature over the intended payload, the certificate or key identity, the issuer or trust root, and the transparency or timestamp evidence that the policy requires. artifactType is metadata supplied by the artifact and should not be the only clue the verification tool uses.
The same caution applies to SBOMs and vulnerability attestations. A valid JSON document attached to an image can be syntactically correct and still describe a different image, a different build, or a different dependency set. The attestation should bind the subject digest, the signer, and the policy-relevant claims.
Registry behavior belongs in the threat model
OCI registries differ in how they handle mutable tags, deletion, garbage collection, and referrer retention. A deployment should resolve images by digest rather than assume that a tag points to the same content on every day. Referrer discovery should use the digest that admission or deployment actually evaluates.
If the registry does not support the referrers API, clients can use the fallback image index tag. That mechanism is specified, but an operational review should still test it against the registry version in use. A policy that treats an empty result as "no signature" should also distinguish a valid empty result from an API error or an unsupported endpoint.
Repository permissions need the same attention. An account with push access can add a new artifact to a repository even when it cannot alter the original image. Depending on registry policy, it may also be able to push a new image manifest under a familiar tag. The control is not the presence of a referrer. The controls are repository authorization, immutable tags or digest-only deployment, artifact retention, and a verifier that trusts a narrow signer identity.
A practical verification path
Begin with the exact image digest selected for deployment. Query the referrers endpoint and record the response status, registry host, repository, subject digest, artifact digests, and artifact types. Do not record credentials or full response bodies containing private metadata.
For every candidate signature, verify the artifact digest and the signature payload, then evaluate identity against a policy you control. Require the workload to prove that the signer is the expected build service or release identity, not merely that some valid key signed some manifest. If an attestation is required, validate its schema and confirm that its subject digest matches the image being deployed.
Then test the negative cases. Remove the referrer or point it at another subject in a lab registry. Confirm that the deployment policy fails closed. Disable the referrers API in a test registry and verify that the client either uses the documented fallback or reports an error. A production system that silently turns an error into "unsigned" or "signed" is not enforcing the policy.
What the team should document
The registry is part of the supply chain, and its referrer behavior should be written down like any other control. Record which artifact types are accepted, which identities may create them, which repository roles can push them, how they survive image deletion, and what the admission controller does when discovery is unavailable.
The final policy can be strict without pretending that OCI solves identity. Require a digest, a trusted signer identity, a verifiable payload, and an explicit failure mode. Treat the referrer as the pointer that makes the evidence discoverable. The verification result, not the attachment, is what authorizes a deployment.
Top comments (0)