Use Referrers REST API to Discover OCI References

JFrog Artifactory Documentation
Products
JFrog Artifactory
Content Type
User Guide

Starting from Artifactory version 7.90.1, Artifactory supports Referrers API, part of the OCI specification version 1.1 which provides a new way to link between images and their related information.

Using referrers API, you can connect an image to its signatures, SBOM certificates, attestations, Xray scan results, and other related artifacts, easily retrieve them together, and transfer them between repositories.

For more information, see Open Container Initiative Distribution Specification.

How Referrers API Works in Artifactory

When deploying an image to a repository, you can use many different OCI-compliant tools to add referrers and attestations. This will create a new signature image in the folder of the original image- when you open the manifest.json file for that image, it will contain a ‘subject’ field that points to the original image. Using the Referrers API also creates a referrers.json index file only visible to Admin users, which will be updated whenever this image is updated or new referrers are added.

Now these images are linked, and you can discover the connection via CLI or REST API.

To use the CLI, you can use functions like oras discover to find all associated artifacts, such as signatures, attestations, and SBOMs, that reference a specific image. For example, when running the following command:

oras discover <JFROG_PLATFORM_URL>/<REPOSITORY_NAME>/<IMAGE>:<DIGEST_OR_TAG>

You will get a list of all of the artifacts referencing your image.

To use REST API, use the following GET request:

GET <ARTIFACTORY_URL>/<REPOSITORY_NAME>/<IMAGE>/referrers/<DIGEST_OR_TAG>

To get a JSON file with a manifest list detailing all of the signatures associated with your image.

How to Use Referrers API

To enable referrers API on an image in an Artifactory repository:

  1. Select an image and a reference you would like to attach to it. Use the CLI command for the client you selected for attaching a signature. For example, cosign attest.

    Note

    If you are using Cosign, use Cosign version 2.0.0 and above. Using OCI 1.1 with earlier versions of Cosign required adding the following feature flag to your system configuration file:

    export COSIGN_EXPERIMENTAL=1

    For more information, see the Cosign Changelog.

  2. To verify that Referrers API is activated on an image, when pushing an image with a subject field, make sure that the response contains the following header with the SHA256 digest for the referenced image:

    OCI-Subject: <DIGEST_OR_TAG>