A few weeks ago I wrote about how to use an intermediate quarantine registry for validating images and how to implement an approval workflow for images that don’t pass your security policies. In this post, I will describe how you can use OCI annotations and referrers to improve the auditing capabilities when you promote images from the quarantine registry to your golden registry. The example approval workflow I implemented already creates an issue in GitHub, which is the simplest step you can take to improve auditing. However, there is nothing that ties the image back to the issue that approved its promotion to the golden registry.

Every step of the supply chain for a cloud-native artifact or a container image that involves OCI registry can be instrumented with an attestation artifact describing what happened in that step and also adding metadata that can be used later on for reporting, analysis, or audit. The simplest attestation that you can do is an empty artifact that has no layer blobs but only a manifest and attestations.

This is exactly what I have implemented in my promotion from quarantine workflow. In addition to the GitHub issue that is used to approve the promotion, I also create a referrer artifact with additional metadata about the promotion. Here is how this artifact looks like:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "artifactType": "application/vnd.cssc.scan-report.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.empty.v1+json",
    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
    "size": 2,
    "data": "e30="
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.empty.v1+json",
      "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
      "size": 2,
      "data": "e30="
    }
  ],
  "subject": {
    "mediaType": "application/vnd.oci.image.index.v1+json",
    "digest": "sha256:b877e50bd90de10af8d82c57a022fc2e0dc731c5320d762a27986facfc3355c1",
    "size": 10365
  },
  "annotations": {
    "com.cssc.scan.exceptions": "",
    "com.cssc.scan.method": "image",
    "com.cssc.scan.override": "true",
    "com.cssc.scan.override-approver": "toddysm",
    "com.cssc.scan.override-cves": "CVE-2025-69720|CVE-2026-41992|CVE-2026-42496|CVE-2026-42497|CVE-2026-48962|CVE-2026-53615|CVE-2026-54369|CVE-2026-8376|CVE-2026-9538",
    "com.cssc.scan.override-issue": "https://github.com/toddysm/cssc-framework/issues/107",
    "com.cssc.scan.scanner": "trivy",
    "com.cssc.scan.scanner-version": "0.71.0",
    "com.cssc.scan.source": "ghcr.io/toddysm/quarantine/python",
    "com.cssc.scan.tag": "3.14-slim",
    "com.cssc.scan.threshold": "HIGH",
    "org.opencontainers.image.created": "2026-07-10T03:11:54Z"
  }
}

You can retrieve the manifest with ORAS:

~ oras manifest fetch ghcr.io/toddysm/golden/python@sha256:ebe76f6ca0edffdc61f81201bf6686dc87e30d9c17cb38fa9fcb33c57354201b | jq .

The important parts in this manifest are the following:

• It is an empty artifact as you can see from the config property on the manifest.
• It has one empty layer as per the OCI specification.
• The subject is the promoted container image.
• It has a custom artifactType that can be recognized by any other tools down the supply chain.
• It has several custom annotations in addition to the standard OCI org.opencontainers.image.created.

What Annotations Should You Use for Promotion from Quarantine?

You can be as concise as just adding link to the issue or ticket that was used to approve the image promotion (i.e. the com.cssc.scan.override-issue annotation in my case). However, you should not rely that the end-user of the image will have access to the issue to gather additional details. One typical example is an air-gapped environment that uses images built outside the environment. I opted out to save more details as annotations and added the following information:

• Scanner information in the annotations com.cssc.scan.scanner and com.cssc.scan.scanner-version.
• Source or scanned image details in the annotations com.cssc.scan.source and com.cssc.scan.tag.
• Security policy threshold details in com.cssc.scan.threshold and the list of the discovered CVEs in com.cssc.scan.override-cves.
• The ID of the approver in com.cssc.scan.override-approver.
• And, of course, the issue used to approve the promotion in com.cssc.scan.override-issue.

This information can travel with the image throughout the supply chain and can be leveraged for more detailed and helpful reporting.

Annotating Container Images Promoted to Golden Registry Video

Here is also a short video showing how those annotations look like:

 In future posts I will describe how you can report on the data that you capture in the various steps of your containers supply chain and how you can use the metadata to automate security processes.