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 It 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/ 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/ 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:
Enable referrers API using the following feature flag in your system configuration file:
artifactory.oci.referrers.api.enabled=true
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, to use Cosign to attach an SBOM certificate to an OCI image, use the following command:
Note
To use Cosign with OCI spec version 1.1, add the following feature flag to your system configuration file:
export COSIGN_EXPERIMENTAL=1
Also, make sure that you are using Cosign version 2.0.0 and above. For more information, see the Cosign Changelog.
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/ TAG>