From 4d4f7013678a16da8c0848b0301faea5a31e2bfa Mon Sep 17 00:00:00 2001 From: Mark Drake Date: Tue, 5 Sep 2023 18:14:56 -0700 Subject: [PATCH 1/3] chainctl images diff documentation --- .../chainguard-images/comparing-images.md | 145 ++++++++++++++++++ ...ompared.md => vulnerabilities-compared.md} | 0 nginx.conf | 3 +- 3 files changed, 147 insertions(+), 1 deletion(-) create mode 100644 content/chainguard/chainguard-images/comparing-images.md rename content/chainguard/chainguard-images/{images-compared.md => vulnerabilities-compared.md} (100%) diff --git a/content/chainguard/chainguard-images/comparing-images.md b/content/chainguard/chainguard-images/comparing-images.md new file mode 100644 index 0000000000..dfb485c2e8 --- /dev/null +++ b/content/chainguard/chainguard-images/comparing-images.md @@ -0,0 +1,145 @@ +--- +title: "How To Compare Chainguard Images with chainctl" +linktitle: "Comparing Images" +type: "article" +description: "An overview of how to use the chainctl images diff command to compare two Chainguard Images." +date: 2023-08-30T11:07:52+02:00 +lastmod: 2023-08-30T11:07:52+02:00 +draft: false +tags: ["Chainguard Images", "Product"] +images: [] +menu: + docs: + parent: "chainguard-images" +weight: 400 +toc: true +--- + +Say that you're curious about the difference between two Chainguard Images. For example, you might want to know if there are any significant differences between yesterday's build and today's; or perhaps you want to know if any CVEs are present in a newer version of a custom Image. + +[`chainctl`](/chainguard/chainctl/) — Chainguard's command line interface tool — allows you to directly compare two Chainguard Images with its `images diff` feature. This guide outlines how to use the Image diffing feature and highlights a few potential use cases for it. + + +## Prerequisites + +In order to use the `chainctl images diff` subcommand, you'll need to have a few tools installed. + +* You'll need `chainctl` installed on your local machine. Follow our guide on [How to Install chainctl](/chainguard/chainguard-enforce/how-to-install-chainctl/) to set this up. +* Next, ensure you have Cosign installed. Our guide on [How to Install Cosign](/open-source/sigstore/cosign/how-to-install-cosign/) outlines several methods for installing Cosign. +* You'll also need Grype installed on your local machine, as `chainctl` uses this to scan the images when performing the diff. Follow the installation instructions for your operating system on the [Grype project GitHub repository](https://github.com/anchore/grype#installation). + + +## Using `chainctl images diff` + +The `chainctl images diff` subcommand accepts the names of two Chainguard Images as arguments and uses Grype to perform a vulnerability scan on each of them. It then retrieves both Images' SBOM information and outputs the difference between the two along with the previously obtained Grype data. + +The `diff` subcommand follows this general syntax. + +```sh +chainctl images diff $FROM_IMAGE $TO_IMAGE +``` + +As an example, try comparing the `latest` public `go` Chainguard Image with its `latest-dev` version. + +```sh +chainctl images diff cgr.dev/chainguard/go:latest cgr.dev/chainguard/go:latest-dev | jq +``` + +This will return output like the following. + +``` +Fetching vulnerabilities for cgr.dev/chainguard/go@sha256:6fee3fff87854aa6e4762c7998c127436a68b09877f9c1010deca35e0f1e27bc +Fetching vulnerabilities for cgr.dev/chainguard/go@sha256:e62ce9fe5e62296186066e647d22cd8d16565d8eee9c2d18541094cec9ddd7a3 +{ + "packages": { + "added": [ + { + "name": "sha256:e62ce9fe5e62296186066e647d22cd8d16565d8eee9c2d18541094cec9ddd7a3", + "reference": "pkg:oci/index@sha256:e62ce9fe5e62296186066e647d22cd8d16565d8eee9c2d18541094cec9ddd7a3?mediaType=application%2Fvnd.oci.image.index.v1%2Bjson" + }, + { + "name": "sha256:a5910c192d3bd6e473cd98a0553d55dba1e9ddee240732a91bf4985116f893d0", + "reference": "pkg:oci/image@sha256:a5910c192d3bd6e473cd98a0553d55dba1e9ddee240732a91bf4985116f893d0?arch=amd64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux" + }, + { + "name": "sha256:35b2716760a4ec6652830a453d692cc7c55893eb8a6b4cc2afabc2bdfad2a10f", + "reference": "pkg:oci/image@sha256:35b2716760a4ec6652830a453d692cc7c55893eb8a6b4cc2afabc2bdfad2a10f?arch=arm64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux" + } + ], + "removed": [ + { + "name": "sha256:6fee3fff87854aa6e4762c7998c127436a68b09877f9c1010deca35e0f1e27bc", + "reference": "pkg:oci/index@sha256:6fee3fff87854aa6e4762c7998c127436a68b09877f9c1010deca35e0f1e27bc?mediaType=application%2Fvnd.oci.image.index.v1%2Bjson" + }, + { + "name": "sha256:eaeb73fe40e46eabd28837f3b981791984fc40cac4833f872169f09c7c3cb4df", + "reference": "pkg:oci/image@sha256:eaeb73fe40e46eabd28837f3b981791984fc40cac4833f872169f09c7c3cb4df?arch=arm64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux" + }, + { + "name": "sha256:87d4c21ede568d79d4ca51271dda3bf46a4164be2bcd7405b6b85b49801d3504", + "reference": "pkg:oci/image@sha256:87d4c21ede568d79d4ca51271dda3bf46a4164be2bcd7405b6b85b49801d3504?arch=amd64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux" + } + ] + }, + "vulnerabilities": {} +} +``` + +This command first uses Grype to scan each Image's vulnerability data and then retrieves both Images' [SBOMs](/open-source/sbom/what-is-an-sbom/). It then outputs the differences that it finds between the two. This sample output indicates that compared to the `go:latest` Image, the `go:latest-dev` Image has three packages added, three removed, and no unique vulnerabilities. + +`chainctl`compares the Images like this because of the order they appear in the command. If you reversed the order of the Images in the example command, the packages shown as `added` and `removed` would also be flipped: + +``` +Fetching vulnerabilities for cgr.dev/chainguard/go@sha256:e62ce9fe5e62296186066e647d22cd8d16565d8eee9c2d18541094cec9ddd7a3 +Fetching vulnerabilities for cgr.dev/chainguard/go@sha256:6fee3fff87854aa6e4762c7998c127436a68b09877f9c1010deca35e0f1e27bc +{ + "packages": { + "added": [ + { + "name": "sha256:6fee3fff87854aa6e4762c7998c127436a68b09877f9c1010deca35e0f1e27bc", + "reference": "pkg:oci/index@sha256:6fee3fff87854aa6e4762c7998c127436a68b09877f9c1010deca35e0f1e27bc?mediaType=application%2Fvnd.oci.image.index.v1%2Bjson" + }, + { + "name": "sha256:eaeb73fe40e46eabd28837f3b981791984fc40cac4833f872169f09c7c3cb4df", + "reference": "pkg:oci/image@sha256:eaeb73fe40e46eabd28837f3b981791984fc40cac4833f872169f09c7c3cb4df?arch=arm64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux" + }, + { + "name": "sha256:87d4c21ede568d79d4ca51271dda3bf46a4164be2bcd7405b6b85b49801d3504", + "reference": "pkg:oci/image@sha256:87d4c21ede568d79d4ca51271dda3bf46a4164be2bcd7405b6b85b49801d3504?arch=amd64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux" + } + ], + "removed": [ + { + "name": "sha256:e62ce9fe5e62296186066e647d22cd8d16565d8eee9c2d18541094cec9ddd7a3", + "reference": "pkg:oci/index@sha256:e62ce9fe5e62296186066e647d22cd8d16565d8eee9c2d18541094cec9ddd7a3?mediaType=application%2Fvnd.oci.image.index.v1%2Bjson" + }, + { + "name": "sha256:a5910c192d3bd6e473cd98a0553d55dba1e9ddee240732a91bf4985116f893d0", + "reference": "pkg:oci/image@sha256:a5910c192d3bd6e473cd98a0553d55dba1e9ddee240732a91bf4985116f893d0?arch=amd64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux" + }, + { + "name": "sha256:35b2716760a4ec6652830a453d692cc7c55893eb8a6b4cc2afabc2bdfad2a10f", + "reference": "pkg:oci/image@sha256:35b2716760a4ec6652830a453d692cc7c55893eb8a6b4cc2afabc2bdfad2a10f?arch=arm64&mediaType=application%2Fvnd.oci.image.manifest.v1%2Bjson&os=linux" + } + ] + }, + "vulnerabilities": {} +} +``` + +Note that in order to make this information more readable, we've piped the command through `jq`, a command line JSON processor. This isn't necessary, but if you'd like you can install `jq` by following [the official documentation](https://jqlang.github.io/jq/download/). + + +## Potential use cases + +Being able to find the exact difference between two Chainguard Images with a single command allows users to make more informed decisions about what Images they use in their applications. This section goes over a couple scenarios where you may want to use the `chainctl images diff` command. + +One potential use case for why you would want to find the differences between two Chainguard Images is that you're curious about the differences between available release versions. Say you're using Custom Chainguard Images and your application is pinned to a specific version of `go`. By diffing the two Images, you could check what vulnerabilities you could remove by updating to the next patch or minor version. + +Another potential use could be in cases where you're interested in knowing the difference between a Chainguard Image's daily builds. For example, say you'd like to keep your Images updated but only when there are significant changes between daily builds. You could diff between the running versions and the latest builds, only updating if there’s a meaningful difference. + + +## Learn more + +To learn more about the `chainctl image` subcommands, we encourage you to check out our +[`chainctl` command resources](/chainguard/chainctl/chainctl-docs/chainctl_images/). You can also explore the rest of our [Chainguard Images resources](/chainguard/chainguard-images/) to learn more about how Images can help you keep your software secure by default. \ No newline at end of file diff --git a/content/chainguard/chainguard-images/images-compared.md b/content/chainguard/chainguard-images/vulnerabilities-compared.md similarity index 100% rename from content/chainguard/chainguard-images/images-compared.md rename to content/chainguard/chainguard-images/vulnerabilities-compared.md diff --git a/nginx.conf b/nginx.conf index 71b4394fd8..16d3e9b893 100644 --- a/nginx.conf +++ b/nginx.conf @@ -32,6 +32,7 @@ http { "~^/chainguard/chainguard-enforce/chainguard-enforce-kubernetes/chainguard-enforce-policy-examples(.+)?$" /chainguard/chainguard-enforce/policies/chainguard-enforce-policy-examples$1; "~^/open-source/melange/getting-started-with-melange(.+)?$" /open-source/melange/tutorials/getting-started-with-melange/; "~^/chainguard/chainguard-enforce/sboms/sboms-and-attestations/(.+)?$" /open-source/sbom/sboms-and-attestations/; + "~^/chainguard/chainguard-images/images-compared/(.+)?$" /chainguard/chainguard-images/vulnerabilities-compared/; # complete content directory redirects here "~^/chainguard/chainguard-enforce/events/(.+)$" /chainguard/chainguard-enforce/cloudevents/$1; @@ -81,4 +82,4 @@ http { } } } -error_log stderr notice; +error_log stderr notice; \ No newline at end of file From 150dc6aa13e455c64cdcded9974a07db23a9a41c Mon Sep 17 00:00:00 2001 From: Mark Drake Date: Tue, 5 Sep 2023 18:40:08 -0700 Subject: [PATCH 2/3] cleanup --- .../chainguard/chainguard-images/vulnerabilities-compared.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/chainguard/chainguard-images/vulnerabilities-compared.md b/content/chainguard/chainguard-images/vulnerabilities-compared.md index 68feadbf2e..98e969b2af 100644 --- a/content/chainguard/chainguard-images/vulnerabilities-compared.md +++ b/content/chainguard/chainguard-images/vulnerabilities-compared.md @@ -1,11 +1,11 @@ --- title: "Comparison of Vulnerabilities in Container Images" -linktitle: "Images Compared" +linktitle: "Comparing Vulnerabilities" lead: "Detected CVEs Over Time" type: "article" description: "Comparing popular base images with Chainguard Images in number of CVEs detected over time" date: 2022-09-15T08:49:31+00:00 -lastmod: 2023-08-22T08:49:31+00:00 +lastmod: 2022-09-15T08:49:31+00:00 draft: false tags: ["Chainguard Images", "Product"] images: [] From 70aaa589f5251feff76563f0aa44f0ea99a75b95 Mon Sep 17 00:00:00 2001 From: Mark Drake Date: Wed, 6 Sep 2023 13:45:40 -0700 Subject: [PATCH 3/3] implementing changes --- .../chainguard-images/comparing-images.md | 11 ++++---- .../vulnerabilities-compared.md | 27 ------------------- nginx.conf | 2 +- 3 files changed, 7 insertions(+), 33 deletions(-) delete mode 100644 content/chainguard/chainguard-images/vulnerabilities-compared.md diff --git a/content/chainguard/chainguard-images/comparing-images.md b/content/chainguard/chainguard-images/comparing-images.md index dfb485c2e8..1781315dad 100644 --- a/content/chainguard/chainguard-images/comparing-images.md +++ b/content/chainguard/chainguard-images/comparing-images.md @@ -1,12 +1,12 @@ --- title: "How To Compare Chainguard Images with chainctl" -linktitle: "Comparing Images" +linktitle: "Compare Images with chainctl" type: "article" description: "An overview of how to use the chainctl images diff command to compare two Chainguard Images." date: 2023-08-30T11:07:52+02:00 lastmod: 2023-08-30T11:07:52+02:00 draft: false -tags: ["Chainguard Images", "Product"] +tags: ["Chainguard Images", "Product", ] images: [] menu: docs: @@ -15,7 +15,7 @@ weight: 400 toc: true --- -Say that you're curious about the difference between two Chainguard Images. For example, you might want to know if there are any significant differences between yesterday's build and today's; or perhaps you want to know if any CVEs are present in a newer version of a custom Image. +There may be times when you'd like to understand the difference between two Chainguard Images. For example, you might want to know if there are any significant differences between yesterday's build and today's; or perhaps you want to know if any CVEs are present in a newer version of a custom Image. [`chainctl`](/chainguard/chainctl/) — Chainguard's command line interface tool — allows you to directly compare two Chainguard Images with its `images diff` feature. This guide outlines how to use the Image diffing feature and highlights a few potential use cases for it. @@ -24,9 +24,10 @@ Say that you're curious about the difference between two Chainguard Images. For In order to use the `chainctl images diff` subcommand, you'll need to have a few tools installed. -* You'll need `chainctl` installed on your local machine. Follow our guide on [How to Install chainctl](/chainguard/chainguard-enforce/how-to-install-chainctl/) to set this up. +* You'll need `chainctl` installed on your local machine. Follow our guide on [How to Install chainctl](/chainguard/chainguard-enforce/how-to-install-chainctl/) to set this up. If you already have `chainctl` installed, be sure to update it to the latest version with `chainctl update`. * Next, ensure you have Cosign installed. Our guide on [How to Install Cosign](/open-source/sigstore/cosign/how-to-install-cosign/) outlines several methods for installing Cosign. * You'll also need Grype installed on your local machine, as `chainctl` uses this to scan the images when performing the diff. Follow the installation instructions for your operating system on the [Grype project GitHub repository](https://github.com/anchore/grype#installation). +* Lastly, an example command in this guide uses `jq` — a command-line JSON processor — to make the command's output more readable. You don't strictly need to have `jq` installed in order to use the `diff` subcommand, but if you'd like you can install it by following [the official documentation](https://jqlang.github.io/jq/download/). ## Using `chainctl images diff` @@ -127,7 +128,7 @@ Fetching vulnerabilities for cgr.dev/chainguard/go@sha256:6fee3fff87854aa6e4762c } ``` -Note that in order to make this information more readable, we've piped the command through `jq`, a command line JSON processor. This isn't necessary, but if you'd like you can install `jq` by following [the official documentation](https://jqlang.github.io/jq/download/). +Be aware that because this is a relatively new feature, the format of the `diff` subcommand's output is subject to change. ## Potential use cases diff --git a/content/chainguard/chainguard-images/vulnerabilities-compared.md b/content/chainguard/chainguard-images/vulnerabilities-compared.md deleted file mode 100644 index 98e969b2af..0000000000 --- a/content/chainguard/chainguard-images/vulnerabilities-compared.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: "Comparison of Vulnerabilities in Container Images" -linktitle: "Comparing Vulnerabilities" -lead: "Detected CVEs Over Time" -type: "article" -description: "Comparing popular base images with Chainguard Images in number of CVEs detected over time" -date: 2022-09-15T08:49:31+00:00 -lastmod: 2022-09-15T08:49:31+00:00 -draft: false -tags: ["Chainguard Images", "Product"] -images: [] -menu: - docs: - parent: "chainguard-images" -weight: 700 -toc: true ---- - -On this page you can find comparison graphs showing the number of CVEs (common vulnerabilities and exposures) detected by [Grype](https://github.com/anchore/grype) on popular official base images versus [Chainguard Images](https://www.chainguard.dev/chainguard-images?utm_source=docs). - -## Comparing the latest official Nginx image with cgr.dev/chainguard/nginx - -{{< rumble title="Nginx" description="Comparing the latest official Nginx image with cgr.dev/chainguard/nginx" left="nginx:latest" right="cgr.dev/chainguard/nginx:latest" >}} - -## Comparing the latest official PHP image with cgr.dev/chainguard/php - -{{< rumble title="PHP" description="Comparing the latest official PHP image with cgr.dev/chainguard/php" left="php:latest" right="cgr.dev/chainguard/php:latest" >}} diff --git a/nginx.conf b/nginx.conf index 16d3e9b893..0bcbb6ce6c 100644 --- a/nginx.conf +++ b/nginx.conf @@ -32,7 +32,7 @@ http { "~^/chainguard/chainguard-enforce/chainguard-enforce-kubernetes/chainguard-enforce-policy-examples(.+)?$" /chainguard/chainguard-enforce/policies/chainguard-enforce-policy-examples$1; "~^/open-source/melange/getting-started-with-melange(.+)?$" /open-source/melange/tutorials/getting-started-with-melange/; "~^/chainguard/chainguard-enforce/sboms/sboms-and-attestations/(.+)?$" /open-source/sbom/sboms-and-attestations/; - "~^/chainguard/chainguard-images/images-compared/(.+)?$" /chainguard/chainguard-images/vulnerabilities-compared/; + "~^/chainguard/chainguard-images/images-compared/(.+)?$" /chainguard/chainguard-images/vuln-comparison/; # complete content directory redirects here "~^/chainguard/chainguard-enforce/events/(.+)$" /chainguard/chainguard-enforce/cloudevents/$1;