Diff API: Your new ally in navigating Chainguard Image daily rebuilds

Adam Dawson, Principal Product Manager
  •  
January 31, 2024

To allow our customers and users to control our hardened image “overflow,” we have created two approval gateways that can be placed between your pipeline and ours. Digestabot, a free GitHub Action, automates upgrading your Chainguard Images to the latest version, and our Diff API feature helps engineers understand what changes are being merged when a Chainguard Image is updated.

Digestabot takes the burden of keeping Images up to date off of engineers, and works across Dockerfiles and Kubernetes manifests.

If rollouts are expensive or time consuming, it’s important to understand what benefit you may get by upgrading a Chainguard Image before deciding to do so. And that’s what we are announcing today: Diff API is more than an approval gateway, it is the perfect way to see what a new Chainguard Image contains compared to the Image already in use. It will provide all the necessary information customers need to make the right decision to upgrade the container image stack. 

The Diff API allows you to understand the following differences between two Chainguard Images:

  1. If any APK package versions have been added, removed, or updated
  2. If any vulnerabilities have been added or fixed
  3. If the image config has changed

With this information, Chainguard Images customers can make informed decisions on when they should upgrade their Images.

So how does Diff API work? 

Diff API compares two versions of an image, and returns any differences in the package versions, vulnerabilities, or image configs of the images. It’s able to do this by retrieving the SBOM for each image version and generating up-to-date vulnerability scans with Grype. 

The Diff API offers insights into package changes and CVE fixes, making it much easier to make informed decisions about image updates. Learn more in the Diff API documentation on Chainguard Academy. 

Follow these three steps to use the Diff API to compare the contents of two image versions:

  1. Authenticate with Chainguard
  2. Get the repo UIDs
  3. Get the Image digests
  4. Call the Diff API

You’ll need the following tools installed for this tutorial:

Step 1: Authenticate with Chainguard

-- CODE language-bash -- chainctl auth login

Step 2: Get the Repo UIDP

First, set the repository you want to diff against:

-- CODE language-bash -- REPO_URL=cgr.dev/your registry/><repo>

Next, you’ll need to get the Repo UIDP for this repository to call the Diff API:

-- CODE language-bash -- REPO_NAME=$(echo $REPO_URL | cut -d'/' -f3) REPO_UIDP=$(curl -X GET -H "Authorization: Bearer $(cat ~/Library/Caches/chainguard/https:--console-api.enforce.dev/oidc-token)" "https://console-api.enforce.dev/registry/v1/repos?name=${REPO_NAME}" | jq ".items[] | select(.id | startswith(\"${GROUP_UIDP}\")) | .id" -r)

Step 3: Get the digests of Chainguard Images

Next, you’ll need the digests of the two images you want to diff. You can use the tag history api to get all of the digests previously associated with a specific tag.

In this example, we’ll diff the latest and latest-dev tags of the image specified by REPO_URL, but you can replace with any two digests you want to diff:

-- CODE language-bash -- FROM_DIGEST=$(crane digest --platform "linux/amd64" "${REPO_URL}:latest") TO_DIGEST=$(crane digest --platform "linux/amd64" "${REPO_URL}:latest-dev")

Step 4: Call the Diff API

Finally, call the Diff API with curl:

-- CODE language-bash -- curl -X GET -H "Authorization: Bearer $(cat ~/Library/Caches/chainguard/https:--console-api.enforce.dev/oidc-token)" "https://console-api.enforce.dev/registry/v1/repos/${REPO_UIDP}/diff?from_digest=${FROM_DIGEST}&to_digest=${TO_DIGEST}" { "packages": { "added": [ { "name": "apk-tools", "version": "2.14.0-r1", "reference": "pkg:apk/wolfi/apk-tools@2.14.0-r1?arch=x86_64" }, { "name": "sha256:4a4b3fb1c180b2deadd819155f65a995eda3b8945761c7a02e763580e7fc7958", "version": "20230214", "reference": "pkg:oci/image@sha256%3A4a4b3fb1c180b2deadd819155f65a995eda3b8945761c7a02e763580e7fc7958?arch=amd64&mediaType=application%2Fvnd.oci.image.layer.v1.tar%2Bgzip&os=linux" }, { "name": "sha256:f4d5d575340fb0f541bf628164b147880ef518f06774ed8dfffc7252e856c906", "version": "sha256:f4d5d575340fb0f541bf628164b147880ef518f06774ed8dfffc7252e856c906", "reference": "pkg:oci/image@sha256%3Af4d5d575340fb0f541bf628164b147880ef518f06774ed8dfffc7252e856c906?arch=amd64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux" } ], "removed": [ { "name": "sha256:8e9325825a64030b9e4ff892fb511be2c1938025778d4e7c2fec149fe86fc034", "version": "20230214", "reference": "pkg:oci/image@sha256%3A8e9325825a64030b9e4ff892fb511be2c1938025778d4e7c2fec149fe86fc034?arch=amd64&mediaType=application%2Fvnd.oci.image.layer.v1.tar%2Bgzip&os=linux" }, { "name": "sha256:abbe5a20dafad91f6ed5d3a54999a613587f456c84c847e9ef886cf988aa314e", "version": "sha256:abbe5a20dafad91f6ed5d3a54999a613587f456c84c847e9ef886cf988aa314e", "reference": "pkg:oci/image@sha256%3Aabbe5a20dafad91f6ed5d3a54999a613587f456c84c847e9ef886cf988aa314e?arch=amd64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux" } ], "changed": [] }, "vulnerabilities": { "added": [], "removed": [] }, "config": { "changed": null }, "warnings": [] }

Why Diff API

Speed is safety,” says Charity Majors: “... software physics are different. It's more like ice skating, or riding a bicycle: the slower you go the more dangerously you wobble.” And we agree. Chainguard Images are all about enabling teams to run secure and nimble containers. 

We created the Diff API to empower our customers to make informed decisions around when they want to upgrade to the latest version of a Chainguard Image. With Diff API, customers get the best of both worlds: the ability to update an image every day if they choose to, and an understanding of when upgrading will have the most impact. 

New to Chainguard Images and want to learn more? Get in touch with our team to learn how we can help you on your hardened container image journey.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse varius enim in eros elementum tristique. Duis cursus, mi quis viverra ornare, eros dolor interdum nulla, ut commodo diam libero vitae erat. Aenean faucibus nibh et justo cursus id rutrum lorem imperdiet. Nunc ut sem vitae risus tristique posuere.

Don’t break the chain – secure your supply chain today!

Product

Diff API: Your new ally in navigating Chainguard Image daily rebuilds

Adam Dawson, Principal Product Manager
January 31, 2024
copied

To allow our customers and users to control our hardened image “overflow,” we have created two approval gateways that can be placed between your pipeline and ours. Digestabot, a free GitHub Action, automates upgrading your Chainguard Images to the latest version, and our Diff API feature helps engineers understand what changes are being merged when a Chainguard Image is updated.

Digestabot takes the burden of keeping Images up to date off of engineers, and works across Dockerfiles and Kubernetes manifests.

If rollouts are expensive or time consuming, it’s important to understand what benefit you may get by upgrading a Chainguard Image before deciding to do so. And that’s what we are announcing today: Diff API is more than an approval gateway, it is the perfect way to see what a new Chainguard Image contains compared to the Image already in use. It will provide all the necessary information customers need to make the right decision to upgrade the container image stack. 

The Diff API allows you to understand the following differences between two Chainguard Images:

  1. If any APK package versions have been added, removed, or updated
  2. If any vulnerabilities have been added or fixed
  3. If the image config has changed

With this information, Chainguard Images customers can make informed decisions on when they should upgrade their Images.

So how does Diff API work? 

Diff API compares two versions of an image, and returns any differences in the package versions, vulnerabilities, or image configs of the images. It’s able to do this by retrieving the SBOM for each image version and generating up-to-date vulnerability scans with Grype. 

The Diff API offers insights into package changes and CVE fixes, making it much easier to make informed decisions about image updates. Learn more in the Diff API documentation on Chainguard Academy. 

Follow these three steps to use the Diff API to compare the contents of two image versions:

  1. Authenticate with Chainguard
  2. Get the repo UIDs
  3. Get the Image digests
  4. Call the Diff API

You’ll need the following tools installed for this tutorial:

Step 1: Authenticate with Chainguard

-- CODE language-bash -- chainctl auth login

Step 2: Get the Repo UIDP

First, set the repository you want to diff against:

-- CODE language-bash -- REPO_URL=cgr.dev/your registry/><repo>

Next, you’ll need to get the Repo UIDP for this repository to call the Diff API:

-- CODE language-bash -- REPO_NAME=$(echo $REPO_URL | cut -d'/' -f3) REPO_UIDP=$(curl -X GET -H "Authorization: Bearer $(cat ~/Library/Caches/chainguard/https:--console-api.enforce.dev/oidc-token)" "https://console-api.enforce.dev/registry/v1/repos?name=${REPO_NAME}" | jq ".items[] | select(.id | startswith(\"${GROUP_UIDP}\")) | .id" -r)

Step 3: Get the digests of Chainguard Images

Next, you’ll need the digests of the two images you want to diff. You can use the tag history api to get all of the digests previously associated with a specific tag.

In this example, we’ll diff the latest and latest-dev tags of the image specified by REPO_URL, but you can replace with any two digests you want to diff:

-- CODE language-bash -- FROM_DIGEST=$(crane digest --platform "linux/amd64" "${REPO_URL}:latest") TO_DIGEST=$(crane digest --platform "linux/amd64" "${REPO_URL}:latest-dev")

Step 4: Call the Diff API

Finally, call the Diff API with curl:

-- CODE language-bash -- curl -X GET -H "Authorization: Bearer $(cat ~/Library/Caches/chainguard/https:--console-api.enforce.dev/oidc-token)" "https://console-api.enforce.dev/registry/v1/repos/${REPO_UIDP}/diff?from_digest=${FROM_DIGEST}&to_digest=${TO_DIGEST}" { "packages": { "added": [ { "name": "apk-tools", "version": "2.14.0-r1", "reference": "pkg:apk/wolfi/apk-tools@2.14.0-r1?arch=x86_64" }, { "name": "sha256:4a4b3fb1c180b2deadd819155f65a995eda3b8945761c7a02e763580e7fc7958", "version": "20230214", "reference": "pkg:oci/image@sha256%3A4a4b3fb1c180b2deadd819155f65a995eda3b8945761c7a02e763580e7fc7958?arch=amd64&mediaType=application%2Fvnd.oci.image.layer.v1.tar%2Bgzip&os=linux" }, { "name": "sha256:f4d5d575340fb0f541bf628164b147880ef518f06774ed8dfffc7252e856c906", "version": "sha256:f4d5d575340fb0f541bf628164b147880ef518f06774ed8dfffc7252e856c906", "reference": "pkg:oci/image@sha256%3Af4d5d575340fb0f541bf628164b147880ef518f06774ed8dfffc7252e856c906?arch=amd64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux" } ], "removed": [ { "name": "sha256:8e9325825a64030b9e4ff892fb511be2c1938025778d4e7c2fec149fe86fc034", "version": "20230214", "reference": "pkg:oci/image@sha256%3A8e9325825a64030b9e4ff892fb511be2c1938025778d4e7c2fec149fe86fc034?arch=amd64&mediaType=application%2Fvnd.oci.image.layer.v1.tar%2Bgzip&os=linux" }, { "name": "sha256:abbe5a20dafad91f6ed5d3a54999a613587f456c84c847e9ef886cf988aa314e", "version": "sha256:abbe5a20dafad91f6ed5d3a54999a613587f456c84c847e9ef886cf988aa314e", "reference": "pkg:oci/image@sha256%3Aabbe5a20dafad91f6ed5d3a54999a613587f456c84c847e9ef886cf988aa314e?arch=amd64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux" } ], "changed": [] }, "vulnerabilities": { "added": [], "removed": [] }, "config": { "changed": null }, "warnings": [] }

Why Diff API

Speed is safety,” says Charity Majors: “... software physics are different. It's more like ice skating, or riding a bicycle: the slower you go the more dangerously you wobble.” And we agree. Chainguard Images are all about enabling teams to run secure and nimble containers. 

We created the Diff API to empower our customers to make informed decisions around when they want to upgrade to the latest version of a Chainguard Image. With Diff API, customers get the best of both worlds: the ability to update an image every day if they choose to, and an understanding of when upgrading will have the most impact. 

New to Chainguard Images and want to learn more? Get in touch with our team to learn how we can help you on your hardened container image journey.

Related articles

Ready to lock down your supply chain?

Talk to our customer obsessed, community-driven team.