diff --git a/content/docs/features/bill-of-materials.md b/content/docs/features/bill-of-materials.md index 296d7e731..fc821c563 100644 --- a/content/docs/features/bill-of-materials.md +++ b/content/docs/features/bill-of-materials.md @@ -1,14 +1,14 @@ +++ -title="Bill of Materials" -summary="A Software `Bill-of-Materials` (`BOM`) gives you a layer-by-layer view of what's inside your container in a variety of formats including `JSON`." +title="Structured Bill of Materials" +summary="A Software `Structured Bill-of-Materials` (`SBoM`) gives you a layer-by-layer view of what's inside your container in a variety of formats." +++ ## Summary -A Software **Bill-of-Materials** (`BOM`) provides information necessary to know what's inside your container and how it was constructed. -Cloud Native Buildpacks provide two forms of Bill-of-Materials. +A **Structured-Bill-of-Materials** (`SBoM`) provides information necessary to know what's inside your container and how it was constructed. +Cloud Native Buildpacks provides Structured-Bill-of-Materials in either CycloneDX, SPDX, or Syft format. -1. Buildpacks can populate `BOM` information about the dependencies they have provided. +1. Buildpacks can populate `SBoM` information about the dependencies they have provided. 2. A list of what buildpacks were used to build the application. ## Adding Bill of Materials @@ -18,76 +18,36 @@ Use the following tutorial to add a `Bill-of-Materials` using buildpacks.
## Viewing Bill of Materials -You can use this command to inspect your app for it's `Bill-of-Materials`. +You can use the `sbom download` command to inspect your app for its `Structured-Bill-of-Materials`. The following command will download the application layer containing the `SBoM` files to `./layers/sbom/...` on your local filesystem. ```bash -pack inspect-image your-image-name --bom +pack sbom download your-image-name ``` -It can also be accessed by looking at the label `io.buildpacks.build.metadata`. For example, running Docker CLI, jq and using the following command. +You can also choose to download the `SBoM` from an image hosted in a remote registry, as opposed to an image hosted in a Docker daemon. You use the `--remote` flag to do so. ```bash -docker inspect your-image-name | jq -r '.[0].Config.Labels["io.buildpacks.build.metadata"] | fromjson' +pack sbom download your-image-name --remote ``` -Following is the the information listed in `io.buildpacks.build.metadata` for [Sample Java App](https://github.com/buildpacks/samples/tree/main/apps/java-maven) obtained by building the app using buildpacks and running the above command. +Cloud Native Buildpacks support `SBoM` metadata in [CycloneDX](https://cyclonedx.org/), [Syft](https://github.com/anchore/syft) or [Spdx](https://spdx.dev/) formats. The following example demonstrates `syft` format `SBoM` metadata to the local filesystem. The combined metadata from all of the `sbom.syft.json` files is the image `SBoM`. Where CycloneDX `SBoM` metadata is generated, the files are named `sbom.cdx.json`. Similarly, Spdx files are named `sbom.cdx.json`. -For this output: - -1. `bom` is the buildpack populated bom. -2. `buildpacks` is the list of buildpacks. +```bash +. +└── layers + └── sbom + └── launch + └── paketo-buildpacks_ca-certificates + ├── helper + │ └── sbom.syft.json + └── sbom.syft.json +``` -```json +The layer information is stored under the `io.buildpacks.lifecycle.metadata` label of the application image. +```bash +docker inspect your-image-name | jq -r '.[0].Config.Labels["io.buildpacks.lifecycle.metadata"]' | jq -r .sbom { - "bom": [ - { - "name": "java", - "metadata": { - "version": "11.0.12+7" - }, - "buildpack": { - "id": "google.java.runtime", - "version": "0.9.1" - } - } - ], - "buildpacks": [ - { - "id": "google.java.runtime", - "version": "0.9.1" - }, - { - "id": "google.java.maven", - "version": "0.9.0" - }, - { - "id": "google.java.entrypoint", - "version": "0.9.0" - }, - { - "id": "google.utils.label", - "version": "0.0.1" - } - ], - "launcher": { - "version": "0.11.1", - "source": { - "git": { - "repository": "github.com/buildpacks/lifecycle", - "commit": "75df86c" - } - } - }, - "processes": [ - { - "type": "web", - "command": "java", - "args": ["-jar", "/workspace/target/sample-0.0.1-SNAPSHOT.jar"], - "direct": true, - "buildpackID": "google.java.entrypoint" - } - ], - "buildpack-default-process-type": "web" + "sha": "sha256:abcd1234defg5678" } ```