zarf-dev · Racer159 · May 15, 2023 · May 10, 2023 · May 10, 2023 · May 10, 2023
@@ -17,24 +17,24 @@ Zarf eliminates the [complexity of air gap software delivery](https://www.itopst
 ## 📦 Out of the Box Features
 
 - Automate Kubernetes deployments in disconnected environments
-- Automate [Software Bill of Materials (SBOM)](https://www.linuxfoundation.org/tools/the-state-of-software-bill-of-materials-sbom-and-cybersecurity-readiness/) generation
-- Provide a [web dashboard](https://docs.zarf.dev/docs/dashboard-ui/sbom-dashboard) for viewing SBOM output
+- Automate [Software Bill of Materials (SBOM)](https://docs.zarf.dev/docs/deploy-a-zarf-package/package-sboms) generation
+- Provide a [web dashboard](https://docs.zarf.dev/docs/deploy-a-zarf-package/view-sboms) for viewing SBOM output
 - Create and verify package signatures with [cosign](https://github.com/sigstore/cosign)
-- [Publish](https://docs.zarf.dev/docs/user-guide/the-zarf-cli/cli-commands/zarf_package_publish), [pull](https://docs.zarf.dev/docs/user-guide/the-zarf-cli/cli-commands/zarf_package_pull), and [deploy](https://docs.zarf.dev/docs/user-guide/the-zarf-cli/cli-commands/zarf_package_deploy) packages from an [OCI registry](https://opencontainers.org/)
-- Powerful component lifecycle [actions](https://docs.zarf.dev/docs/user-guide/component-actions)
+- [Publish](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_package_publish), [pull](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_package_pull), and [deploy](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_package_deploy) packages from an [OCI registry](https://opencontainers.org/)
+- Powerful component lifecycle [actions](https://docs.zarf.dev/docs/create-a-zarf-package/component-actions)
 - Deploy a new cluster while fully disconnected with [K3s](https://k3s.io/) or into any existing cluster using a [kube config](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
 - Builtin logging stack with [Loki](https://grafana.com/oss/loki/)
 - Builtin Git server with [Gitea](https://gitea.com/)
 - Builtin Docker registry
 - Builtin [K9s Dashboard](https://k9scli.io/) for managing a cluster from the terminal
 - [Mutating Webhook](adr/0005-mutating-webhook.md) to automatically update Kubernetes pod's image path and pull secrets as well as [Flux Git Repository](https://fluxcd.io/docs/components/source/gitrepositories/) URLs and secret references
-- Builtin [command to find images](https://docs.zarf.dev/docs/user-guide/the-zarf-cli/cli-commands/zarf_prepare_find-images) and resources from a Helm chart
-- Tunneling capability to [connect to Kubernetes resources](https://docs.zarf.dev/docs/user-guide/the-zarf-cli/cli-commands/zarf_connect) without network routing, DNS, TLS or Ingress configuration required
+- Builtin [command to find images](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_prepare_find-images) and resources from a Helm chart
+- Tunneling capability to [connect to Kubernetes resources](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_connect) without network routing, DNS, TLS or Ingress configuration required
 
 ## 🛠️ Configurable Features
 
 - Customizable [variables and package templates](examples/variables/README.md) with defaults and user prompting
-- [Composable packages](https://docs.zarf.dev/docs/user-guide/zarf-packages/zarf-components#composing-package-components) to include multiple sub-packages/components
+- [Composable packages](https://docs.zarf.dev/docs/create-a-zarf-package/zarf-components#composing-package-components) to include multiple sub-packages/components
 - Component-level OS/architecture filtering
 
 ## Demo
@@ -47,7 +47,7 @@ _<https://www.youtube.com/watch?v=WnOYlFVVKDE>_
 
 To try Zarf out for yourself, visit the ["Try It Now"](https://zarf.dev/install) section on our website, and if you want to learn more about Zarf and its use cases visit [docs.zarf.dev](https://docs.zarf.dev/docs/zarf-overview).
 
-From the docs you can learn more about [installation](https://docs.zarf.dev/docs/getting-started/#installing-zarf), [using the CLI](https://docs.zarf.dev/docs/user-guide/the-zarf-cli/), [making packages](https://docs.zarf.dev/docs/user-guide/zarf-packages/), and the [Zarf package schema](https://docs.zarf.dev/docs/user-guide/zarf-schema).
+From the docs you can learn more about [installation](https://docs.zarf.dev/docs/getting-started/#installing-zarf), [using the CLI](https://docs.zarf.dev/docs/the-zarf-cli/), [making packages](https://docs.zarf.dev/docs/create-a-zarf-package/zarf-packages/), and the [Zarf package schema](https://docs.zarf.dev/docs/create-a-zarf-package/zarf-schema).
 
 Using Zarf in Github workflows? Check out the [setup-zarf](https://github.com/defenseunicorns/setup-zarf) action. Install any version of Zarf and its `init` package with zero added dependencies.
 

@@ -12,7 +12,7 @@ SBOM are required for software running on government hardware per EO14028.
 
 ## Decision
 
-Using Witness' Syft attestor functionality allows Zarf to continue to get more refined SBOM capabilities as Witness' capabilities expand over time. Syft is capable of finding installed packages and some binaries for statically compiled dependencies over each image within a Zarf package. This allows for SBOMs for each image to be generated and packaged along with the Zarf package.  Abilities to export the SBOM to SDPX and CycloneDX formatted documents as well as a browsable web page are in works.
+Using Witness' Syft attestor functionality allows Zarf to continue to get more refined SBOM capabilities as Witness' capabilities expand over time. Syft is capable of finding installed packages and some binaries for statically compiled dependencies over each image within a Zarf package. This allows for SBOMs for each image to be generated and packaged along with the Zarf package.  Abilities to export the SBOM to SDPX and CycloneDX formatted documents as well as a browse-able web page are in works.
 
 ## Consequences
 

@@ -18,9 +18,9 @@ The `scripts` section of the `zarf.yaml` will be replaced with a new `actions` s
 - `onDeploy` - Runs during `zarf package deploy`
 - `onRemove` - Runs during `zarf package remove`
 
-In addition to adding more lifecycle events, the `actions` section will also allow for more complex actions to be defined. New configurations include, setting the cmd directory, defining custom env variables, setting the number of retries, setting the max total seconds, muting the output, and [setting a variable](../docs/3-create-a-zarf-package/6-component-actions.md#creating-dynamic-variables-from-actions) to be used in other actions or components.
+In addition to adding more lifecycle events, the `actions` section will also allow for more complex actions to be defined. New configurations include, setting the cmd directory, defining custom env variables, setting the number of retries, setting the max total seconds, muting the output, and [setting a variable](../docs/3-create-a-zarf-package/7-component-actions.md#creating-dynamic-variables-from-actions) to be used in other actions or components.
 
-Further details can be found in the `component-actions` [component actions documentation](../docs/3-create-a-zarf-package/6-component-actions.md), [package create lifecycle documentation](../docs/3-create-a-zarf-package/5-package-create-lifecycle.md), [package deploy lifecycle documentation](../docs/4-deploy-a-zarf-package/1-package-deploy-lifecycle.md), and the [example package](../examples/component-actions/README.md).
+Further details can be found in the `component-actions` [component actions documentation](../docs/3-create-a-zarf-package/7-component-actions.md), [package create lifecycle documentation](../docs/3-create-a-zarf-package/5-package-create-lifecycle.md), [package deploy lifecycle documentation](../docs/4-deploy-a-zarf-package/1-package-deploy-lifecycle.md), and the [example package](../examples/component-actions/README.md).
 
 ## Consequences
 

@@ -65,7 +65,7 @@ Given Zarf's being a "K8s cluster to serve _other_ K8s clusters", the following
 - Container images: to serve images for the Zarf and downstream clusters to run containers from.
 - Repositories: to serve as the git-based "source of truth" for downstream "GitOps"ed K8s clusters to watch.
 - Pre-compiled binaries: to provide the software necessary to start and support the Zarf cluster.
-- [Component actions](3-create-a-zarf-package/6-component-actions.md): to support scripts and commands that run at various stages of the Zarf [package create lifecycle](./3-create-a-zarf-package/5-package-create-lifecycle.md), and [package deploy lifecycle](./4-deploy-a-zarf-package/1-package-deploy-lifecycle.md).
+- [Component actions](3-create-a-zarf-package/7-component-actions.md): to support scripts and commands that run at various stages of the Zarf [package create lifecycle](./3-create-a-zarf-package/5-package-create-lifecycle.md), and [package deploy lifecycle](./4-deploy-a-zarf-package/1-package-deploy-lifecycle.md).
 - Helm charts, kustomizations, and other K8s manifests: to apply in a Kubernetes cluster.
 - [Data injections](../examples/data-injection/README.md): to declaratively inject data into running containers in a Kubernetes cluster.
 
@@ -133,11 +133,11 @@ In the more complex use case, your package consists of updates for many apps/sys
 ### 📦 Out of the Box Features
 
 - Automate Kubernetes deployments in disconnected environments
-- Automate [Software Bill of Materials (SBOM)](https://www.linuxfoundation.org/tools/the-state-of-software-bill-of-materials-sbom-and-cybersecurity-readiness/) generation
-- Provide a [web dashboard](./5-dashboard-ui/1-sbom-dashboard.md) for viewing SBOM output
+- Automate [Software Bill of Materials (SBOM)](./3-create-a-zarf-package/6-package-sboms.md) generation
+- Provide a [web dashboard](./4-deploy-a-zarf-package/4-view-sboms.md) for viewing SBOM output
 - Create and verify package signatures with [cosign](https://github.com/sigstore/cosign)
 - [Publish](./2-the-zarf-cli/100-cli-commands/zarf_package_publish.md), [pull](./2-the-zarf-cli/100-cli-commands/zarf_package_pull.md), and [deploy](./2-the-zarf-cli/100-cli-commands/zarf_package_deploy.md) packages from an [OCI registry](https://opencontainers.org/)
-- Powerful component lifecycle [actions](./3-create-a-zarf-package/6-component-actions.md)
+- Powerful component lifecycle [actions](./3-create-a-zarf-package/7-component-actions.md)
 - Deploy a new cluster while fully disconnected with [K3s](https://k3s.io/) or into any existing cluster using a [kube config](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
 - Builtin logging stack with [Loki](https://grafana.com/oss/loki/)
 - Builtin Git server with [Gitea](https://gitea.com/)

@@ -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
+```
+
+:::
@@ -135,7 +135,7 @@ Within each of the `action` lists (`before`, `after`, `onSuccess`, and `onFailur
 - `wait` - (required if not a cmd action) the wait parameters.
   - `cluster` - perform a wait operation on a Kubernetes resource (kubectl wait).
     - `kind` - the kind of resource to wait for (required).
-    - `identifier` - the identifier of the resource to wait for (required), can be a name or label selector.
+    - `name` - the name of the resource to wait for (required), can be a name or label selector.
     - `namespace` - the namespace of the resource to wait for.
     - `condition` - the condition to wait for (default: `exists`).
   - `network` - perform a wait operation on a network resource (curl).

@@ -1,4 +1,4 @@
-# Zarf Deployment Web UI
+# Deployment Web UI
 
 Zarf has a Deployment Web UI built in that supports a number of Zarf features used during the package deployment process. For users who prefer not to use the command line tool, the Web UI creates a simple experience to deploy and manage Zarf clusters and packages. The Web UI can be used to connect to existing clusters (via a Kubeconfig), initialize a cluster, deploy packages into a cluster, update packages in the cluster, and remove packages from the cluster.
 

@@ -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.
+
+![SBOM Prompt](../.images/dashboard/SBOM_prompt_example.png)
+
+:::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**
+![SBOM Dashboard](../.images/dashboard/SBOM_dashboard.png)
+
+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**
+![SBOM Comparer](../.images/dashboard/SBOM_compare.png)
+
+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.