Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Introduce download-sbom docs #457

Closed
wants to merge 5 commits into from
Closed

Introduce download-sbom docs #457

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6ce0057
introduce download-sbom docs
Jan 5, 2022
2c9d6a4
Address PR comments
Jan 21, 2022
09fc0ee
Update content/docs/features/bill-of-materials.md
AidanDelaney Feb 23, 2022
b65cd29
Update content/docs/features/bill-of-materials.md
AidanDelaney Feb 23, 2022
69c77cf
Update content/docs/features/bill-of-materials.md
AidanDelaney Feb 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 24 additions & 64 deletions content/docs/features/bill-of-materials.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -18,76 +18,36 @@ Use the following tutorial to add a `Bill-of-Materials` using buildpacks. <br/>

## Viewing Bill of Materials

You can use this command to inspect your app for it's `Bill-of-Materials`.
You can use the `download-sbom` 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.
AidanDelaney marked this conversation as resolved.
Show resolved Hide resolved

```bash
pack inspect-image your-image-name --bom
pack download-sbom your-image-name
AidanDelaney marked this conversation as resolved.
Show resolved Hide resolved
```

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 download-sbom your-image-name --remote
AidanDelaney marked this conversation as resolved.
Show resolved Hide resolved
```

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"
}
```

Expand Down