bom command documentation

This commit adds the raw documentation for bom and its only subcommand: generate. The format mimics previous docs for our tools (like krel). Signed-off-by: Adolfo García Veytia (Puerco) <[email protected]>
kubernetes · Jun 7, 2021 · 0c2bc36 · 0c2bc36
1 parent 684c7de
commit 0c2bc36
Show file tree

Hide file tree

Showing 5 changed files with 112 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -24,6 +24,7 @@ Individual tools can be installed via `go install k8s.io/release/cmd/$TOOL@lates
   - [`gh2gcs`](#gh2gcs)
   - [`vulndash`](#vulndash)
 - [End User](#end-user)
+  - [`bom`](#bom)
   - [`release-notes`](#release-notes)
   - [`gcbuilder`](#gcbuilder)
   - [`publish-release`](#publish-release)
@@ -109,6 +110,13 @@ Details: [Documentation](/docs/vuln-dashboard.md)
 
 ## End User
 
+### [`bom`](/cmd/bom)
+
+Generate SPDX-compliant Bills of Materials for a software
+project. Supports reading directories, images, files and more.
+
+Details: [Documentation](cmd/bom/README.md) | [SBOM HOWTO](docs/bom/create-a-bill-of-materials.md)
+
 ### [`release-notes`](/cmd/release-notes)
 
 Scrape GitHub pull requests for release notes.

diff --git a/cmd/bom/README.md b/cmd/bom/README.md
@@ -1,14 +1,15 @@
 # bom (Bill of Materials)
 ## A utility to generate SPDX compliant Bill of Materials manifests.
 
-bom is a tiny utility that leverages the code written for the Kubernetes
+`bom` is a tiny utility that leverages the code written for the Kubernetes
 Bill of Materials project. It enables software authors to generate an 
 SBOM for their projects in a simple, yet powerful way.
 
-[![asciicast](https://asciinema.org/a/418528.svg)](https://asciinema.org/a/418528)
+![terminal demo](../../docs/bom/418528.png "Terminal demo")
+
 
 `bom` is a general-purpose tool that can generate SPDX packages from
-directories, docker images, single files, and other sources. The utility
+directories, container images, single files, and other sources. The utility
 has a built-in license classifier that recognizes the 400+ licenses in 
 the SPDX catalog.
 
@@ -46,14 +47,14 @@ describing different packages.
 
 ### Generate an SBOM from the Current Directory:
 
-To process a directory as a source for your SBOM, use the -d flag or simply pass
+To process a directory as a source for your SBOM, use the `-d` flag or simply pass
 the path as the first argument to `bom`:
 
 ```bash
 bom generate -n http://example.com/ .
 ```
 
-### Process a Docker Image
+### Process a Container Image
 
 This example pulls the kube-apiserver image, analyzes it, and describes in the
 SBOM. Each of its layers are then expressed as a subpackage in the resulting

diff --git a/docs/bom/418528.png b/docs/bom/418528.png
diff --git a/docs/bom/README.md b/docs/bom/README.md
@@ -0,0 +1,51 @@
+# bom (Bill of Materials)
+
+Create SPDX compliant Bill of Materials 
+
+- [Summary](#summary)
+- [Installation](#installation)
+- [Usage](#usage)
+
+## Summary 
+
+bom is a little utility that lets software authors generate
+SPDX manifests to describe the contents of a release. The
+SPDX manifests provide a way to list and verify all items
+contained in packages, images, and individual files while
+packing the data along with licensing information.
+
+bom is still in its early stages and it is an effort to open
+the libraries developed for the Kubernetes SBOM for other 
+projects to use.
+
+For a more in depth instructions on how to create an SBOM see
+[Generating a Bill of Materials for Your Project](create-a-bill-of-materials.md)
+
+## Installation
+
+To use bom generate, compile the release engineering tools:
+
+```
+git clone [email protected]:kubernetes/release.git
+cd release
+./compile-release-tools bom
+```
+
+## Usage
+```
+  bom [subcommand]
+```
+
+### Available Commands
+```
+  generate    bom generate → Create SPDX manifests
+  help        Help about any command
+```
+
+### Command line flags
+
+```
+Flags:
+  -h, --help               help for bom
+      --log-level string   the logging verbosity, either 'panic', 'fatal', 'error', 'warning', 'info', 'debug', 'trace' (default "info")
+```
diff --git a/docs/bom/generate.md b/docs/bom/generate.md
@@ -0,0 +1,47 @@
+# bom generate
+
+Create SPDX compliant Bill of Materials 
+
+- [Summary](#summary)
+- [Installation](#installation)
+- [Usage](#usage)
+
+## Summary 
+
+`bom generate` is the subcommand to generate SPDX manifests.
+Currently supports creating SBOM for files, images, and docker
+archives (images in tarballs). Supports pulling images from
+registries.
+
+bom can take a deeper look into images using a growing number
+of analyzers designed to add more sense to common base images.
+
+## Installation
+
+Simply [install bom](README.md).
+
+##  Usage:
+
+```
+  bom generate [flags]
+```
+
+### Command Line Flags
+
+```
+Flags:
+  -a, --analyze-images     go deeper into images using the available analyzers
+  -c, --config string      path to yaml SBOM configuration file
+  -d, --dirs strings       list of directories to include in the manifest as packages
+  -f, --file strings       list of files to include
+  -h, --help               help for generate
+      --ignore strings     list of regexp patterns to ignore when scanning directories
+  -i, --image strings      list of images
+  -n, --namespace string   an URI that servers as namespace for the SPDX doc
+      --no-gitignore       don't use exclusions from .gitignore files
+      --no-gomod           don't perform go.mod analysis, sbom will not include data about go packages
+      --no-transient       don't include transient go dependencies, only direct deps from go.mod
+  -o, --output string      path to the file where the document will be written (defaults to STDOUT)
+  -t, --tarball strings    list of docker archive tarballs to include in the manifest
+
+```