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:

If any APK package versions have been added, removed, or updated
If any vulnerabilities have been added or fixed
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:

Authenticate with Chainguard
Get the repo UIDs
Get the Image digests
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.