-
Notifications
You must be signed in to change notification settings - Fork 147
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add SBOM pages and more SBOM info (#1688)
## Description Improve the SBOM information that we have in our documentation. ## Related Issue Fixes #1595 Fixes #1653 ## Type of change - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [X] Other (security config, docs update, etc) ## Checklist before merging - [X] Test, docs, adr added or updated as needed - [X] [Contributor Guide Steps](https://github.com/defenseunicorns/zarf/blob/main/CONTRIBUTING.md#developer-workflow) followed
- Loading branch information
Showing
18 changed files
with
119 additions
and
76 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| # Package SBOMs | ||
|
|
||
| Zarf builds [Software Bill of Materials (SBOM)](https://www.linuxfoundation.org/tools/the-state-of-software-bill-of-materials-sbom-and-cybersecurity-readiness/) into packages to help with the management of software being brought into the air gap. This page goes into detail of how these SBOMs are created and what within a package will get an associated SBOM. If you would like to see how to interact with SBOMs after they are built into a package, see the [View SBOMs page](../4-deploy-a-zarf-package/4-view-sboms.md) under Deploy a Zarf Package. | ||
|
|
||
| ## How SBOMs are Generated | ||
|
|
||
| Zarf uses [Syft](https://github.com/anchore/syft) under the hood to provide SBOMs for container `images`, as well as `files` and `dataInjections` included in components. This is run during the final step of package creation with the SBOM information for a package being placed within an `sboms` directory at the root of the Zarf Package tarball. Additionally, the SBOMs are created in the Syft `.json` format which is a superset of all of the information that Syft can discover and is used so that we can provide the most information possible even when performing [lossy conversions to formats like `spdx-json` or `cyclonedx-json`](../4-deploy-a-zarf-package/4-view-sboms.md#sboms-built-into-packages). | ||
|
|
||
| If you were using the Syft CLI to create these SBOM files manually this would be equivalent to the following commands: | ||
|
|
||
| ```bash | ||
| # For `images` contained within the package | ||
| $ syft packages oci-dir:path/to/yourimage -o json > my-sbom.json | ||
| ``` | ||
|
|
||
| ```bash | ||
| # For `files` or `dataInjections` contained within the package | ||
| $ syft packages file:path/to/yourproject/file -o json > my-sbom.json | ||
| ``` | ||
|
|
||
| :::note | ||
|
|
||
| Zarf uses the `file:` Syft SBOM scheme even if given a directory as the `files` or `dataInjection` source since this generally provides more information (at the cost of execution speed). | ||
|
|
||
| ::: | ||
|
|
||
| :::tip | ||
|
|
||
| Given the Syft CLI is vendored into Zarf you can run these commands with the Zarf binary as well: | ||
|
|
||
| ```bash | ||
| $ zarf tools sbom packages file:path/to/yourproject/file -o json > my-sbom.json | ||
| ``` | ||
|
|
||
| ::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
File renamed without changes.
2 changes: 1 addition & 1 deletion
2
docs/5-dashboard-ui/3-zarf-deployment-ui.md → ...-deploy-a-zarf-package/3-deployment-ui.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,61 @@ | ||
| # View SBOMs | ||
|
|
||
| A [Software Bill of Materials (SBOM)](https://www.linuxfoundation.org/tools/the-state-of-software-bill-of-materials-sbom-and-cybersecurity-readiness/) is a document that contains a detailed list of all the things a software application is using. SBOMs are important from a security standpoint because they allow you to better track what dependencies you have, and with that information, you can quickly check if any of your dependencies are out of date or have a known vulnerability that should be patched. Zarf makes SBOMs easier, if not painless, to deal with! | ||
|
|
||
| ## SBOMs Built Into Packages | ||
|
|
||
| Zarf treats security as a first-class concern and builds SBOM documents into packages by default! Unless explicitly skipped with the `--skip-sbom` flag, whenever a package is created, Zarf generates an SBOM for it and adds it to the package itself. This means that wherever you end up moving your package, you will always be able to take a peek inside to see what it contains. You can learn more about how Zarf does this on the [Package SBOMs page](../3-create-a-zarf-package/6-package-sboms.md). | ||
|
|
||
| You can quickly view these files in your browser by running `zarf package inspect` with the `-s` or `--sbom` flag. If there are any SBOMs included in the package, Zarf will open the SBOM viewer to the first SBOM in the list. | ||
|
|
||
| ``` bash | ||
| $ zarf package inspect zarf-package-example-amd64.tar.zst -s | ||
| ``` | ||
|
|
||
| :::tip | ||
|
|
||
| If you would like to get to the raw SBOM files inside of a package you can use the `--sbom-out` flag as shown below: | ||
|
|
||
| ``` bash | ||
| $ zarf package inspect zarf-package-example-amd64.tar.zst --sbom-out ./temp-sbom-dir | ||
| $ cd ./temp-sbom-dir/example | ||
| $ ls | ||
| ``` | ||
|
|
||
| This will output the raw SBOM viewer `.html` files as well as the Syft `.json` files contained in the package. Both of these files contain the same information, but the `.html` files are a lightweight representation of the `.json` SBOM files to be more human-readable. The `.json` files exist to be injected into other tools, such as [Grype](https://github.com/anchore/grype) for vulnerability checking. | ||
|
|
||
| The Syft `.json` files can also be converted to other formats with the Syft CLI (which is vendored into Zarf) including `spdx-json` and `cyclonedx-json`. | ||
|
|
||
| ``` | ||
| zarf tools sbom convert nginx_1.23.0.json -o cyclonedx-json > nginx_1.23.0.cyclonedx.json | ||
| ``` | ||
|
|
||
| To learn more about the formats Syft supports see `zarf tools sbom convert -h` | ||
|
|
||
| ::: | ||
|
|
||
| ## Viewing SBOMs When Deploying | ||
|
|
||
|
|
||
|
|
||
| When deploying a package, Zarf will output the yaml definition of the package, i.e. the `zarf.yaml` that defined the package that was created. If there are any artifacts included in the package, Zarf will also output a note saying how many artifacts are going to be deployed with a link to a lightweight [SBOM viewer](#the-sbom-viewer) that you can copy into your browser to get a visual overview of the artifacts and what they contain. | ||
|
|
||
|  | ||
|
|
||
| :::note | ||
|
|
||
| Zarf does not prompt you to view the SBOM if you are deploying a package with the `--confirm` flag | ||
|
|
||
| ::: | ||
|
|
||
| ## The SBOM Viewer | ||
|
|
||
| **Example SBOM Dashboard** | ||
|  | ||
|
|
||
| In each package that contains SBOM information, Zarf includes a simple dashboard that allows you to see the contents of each container image or set of component files within your package. You can toggle through the different images or components in the dropdown at the top right of the dashboard as well as export the table contents to a CSV. | ||
|
|
||
| **Example SBOM Comparer** | ||
|  | ||
|
|
||
| The SBOM viewer also has an SBOM comparison tool built in that you can access by clicking the "Compare Tool" button next to the image selector. This view allows you to take the SBOM `.json` data (extracted alongside the `.html` files with `--sbom-out`) and compare that across images or packages (if you extract multiple Zarf packages at a time). This is useful for seeing what has changed between different image or component versions. |
File renamed without changes.
Oops, something went wrong.