From 2e609231b43d9bbb68dffef991e16c3968d441a2 Mon Sep 17 00:00:00 2001 From: Devashish Date: Fri, 1 Nov 2024 12:34:55 -0400 Subject: [PATCH] website: add docs for the hcp-sbom provisioner --- provisioner/hcp-sbom/provisioner.go | 34 ++--- website/content/community-plugins.mdx | 1 + .../content/docs/provisioners/hcp-sbom.mdx | 137 ++++++++++++++++++ website/content/docs/provisioners/index.mdx | 2 + .../hcp-sbom/Config-not-required.mdx | 27 ++-- .../provisioner/hcp-sbom/Config-required.mdx | 5 +- website/data/docs-nav-data.json | 4 + 7 files changed, 168 insertions(+), 42 deletions(-) create mode 100644 website/content/docs/provisioners/hcp-sbom.mdx diff --git a/provisioner/hcp-sbom/provisioner.go b/provisioner/hcp-sbom/provisioner.go index cf03e5670..437139086 100644 --- a/provisioner/hcp-sbom/provisioner.go +++ b/provisioner/hcp-sbom/provisioner.go @@ -30,29 +30,21 @@ import ( type Config struct { common.PackerConfig `mapstructure:",squash"` - // Source is a required field that specifies the path to the SBOM file that - // needs to be downloaded. - // It can be a file path or a URL. + // The file path or URL to the SBOM file in the Packer artifact. + // This file must either be in the SPDX or CycloneDX format. Source string `mapstructure:"source" required:"true"` - // Destination is an optional field that specifies the path where the SBOM - // file will be downloaded to for the user. - // The 'Destination' must be a writable location. If the destination is a file, - // the SBOM will be saved or overwritten at that path. If the destination is - // a directory, a file will be created within the directory to store the SBOM. - // Any parent directories for the destination must already exist and be - // writable by the provisioning user (generally not root), otherwise, - // a "Permission Denied" error will occur. If the source path is a file, - // it is recommended that the destination path be a file as well. + + // The path on the local machine to store a copy of the SBOM file. + // You can specify an absolute or a path relative to the working directory + // when you execute the Packer build. If the file already exists on the + // local machine, Packer overwrites the file. If the destination is a + // directory, the directory must already exist. Destination string `mapstructure:"destination"` - // The name to give the SBOM when uploaded on HCP Packer - // - // By default this will be generated, but if you prefer to have a name - // of your choosing, you can enter it here. - // The name must match the following regexp: `[a-zA-Z0-9_-]{3,36}` - // - // Note: it must be unique for a single build, otherwise the build will - // fail when uploading the SBOMs to HCP Packer, and so will the Packer - // build command. + + // The name of the SBOM file stored in HCP Packer. + // If omitted, HCP Packer uses the build fingerprint as the file name. + // This value must be between three and 36 characters from the following set: `[A-Za-z0-9_-]`. + // You must specify a unique name for each build in an artifact version. SbomName string `mapstructure:"sbom_name"` ctx interpolate.Context } diff --git a/website/content/community-plugins.mdx b/website/content/community-plugins.mdx index fa245b73d..43a427c3f 100644 --- a/website/content/community-plugins.mdx +++ b/website/content/community-plugins.mdx @@ -24,6 +24,7 @@ HashiCorp maintainers for advice on how to get started contributing. ## Provisioners - File +- HCP SBOM - InSpec - PowerShell - Shell diff --git a/website/content/docs/provisioners/hcp-sbom.mdx b/website/content/docs/provisioners/hcp-sbom.mdx new file mode 100644 index 000000000..f0bd15cca --- /dev/null +++ b/website/content/docs/provisioners/hcp-sbom.mdx @@ -0,0 +1,137 @@ +--- +description: | + The hcp-sbom Packer provisioner uploads a CycloneDX or SPDX JSON-formatted software bill of materials record to HCP Packer. +page_title: HCP SBOM - Provisioners +--- + + + + + +# HCP SBOM Provisioner + +Type: `hcp-sbom` + +The `hcp-sbom` provisioner uploads software bill of materials (SBOM) files from artifacts built by Packer to HCP Packer. You must format SBOM files you want to upload as JSON and follow either the [SPDX](https://spdx.github.io/spdx-spec/latest) or [CycloneDX](https://cyclonedx.org/) specification. HCP Packer ties these SBOM files to the version of the artifact that Packer builds. + +## Example + +The following example uploads an SBOM from the local `/tmp` directory and stores a copy at `./sbom/sbom_cyclonedx.json` on the local machine. + + + + +```hcl +provisioner "hcp-sbom" { + source = "/tmp/sbom_cyclonedx.json" + destination = "./sbom/sbom_cyclonedx.json" + sbom_name = "sbom-cyclonedx" +} +``` + + + + +```json +{ + "type": "hcp-sbom", + "source": "/tmp/sbom_cyclonedx.json", + "destination": "./sbom/sbom_cyclonedx.json", + "sbom_name": "sbom-cyclonedx" +} +``` + + + + +## Configuration reference + +You can specify the following configuration options. + +Required parameters: + +@include 'provisioner/hcp-sbom/Config-required.mdx' + +Optional parameters: + +@include '/provisioner/hcp-sbom/Config-not-required.mdx' + +## Example usage + + + + +```hcl +packer { + required_plugins { + docker = { + version = ">= 1.0.0" + source = "github.com/hashicorp/docker" + } + } +} + +source "docker" "ubuntu" { + image = "ubuntu:20.04" + commit = true +} + +build { + sources = ["source.docker.ubuntu"] + + hcp_packer_registry { + bucket_name = "test-bucket" + } + + + provisioner "shell" { + inline = [ + "apt-get update -y", + "apt-get install -y curl gpg", + "bash -c \"$(curl -sSL https://install.mondoo.com/sh)\"", + "cnquery sbom --output cyclonedx-json --output-target /tmp/sbom_cyclonedx.json", + ] + } + + provisioner "hcp-sbom" { + source = "/tmp/sbom_cyclonedx.json" + destination = "./sbom" + sbom_name = "sbom-cyclonedx" + } +} +``` + + + + +```json +{ + "builders": [ + { + "type": "docker", + "image": "ubuntu:20.04", + "commit": true + } + ], + "provisioners": [ + { + "type": "shell", + "inline": [ + "apt-get update -y", + "apt-get install -y curl", + "bash -c \"$(curl -sSL https://install.mondoo.com/sh)\"", + "cnquery sbom --output cyclonedx-json --output-target /tmp/sbom_cyclonedx.json" + ] + }, + { + "type": "hcp-sbom", + "source": "/tmp/sbom_cyclonedx.json", + "destination": "./sbom", + "sbom_name": "sbom-cyclonedx" + } + ] +} +``` + + + \ No newline at end of file diff --git a/website/content/docs/provisioners/index.mdx b/website/content/docs/provisioners/index.mdx index e6144beae..da2603e80 100644 --- a/website/content/docs/provisioners/index.mdx +++ b/website/content/docs/provisioners/index.mdx @@ -20,6 +20,8 @@ The following provisioners are included with Packer: - [Breakpoint](/packer/docs/provisioners/breakpoint) - pause until the user presses `Enter` to resume a build. - [File](/packer/docs/provisioners/file) - upload files to machines image during a build. +- [HCP SBOM](/packer/docs/provisioners/hcp-sbom) - upload an SBOM and associate it with an artifact + version in the HCP Packer registry. - [Shell](/packer/docs/provisioners/shell) - run shell scripts on the machines image during a build. - [Local Shell](/packer/docs/provisioners/shell-local) - run shell scripts on the host running Packer during a build. diff --git a/website/content/partials/provisioner/hcp-sbom/Config-not-required.mdx b/website/content/partials/provisioner/hcp-sbom/Config-not-required.mdx index 871e7a5ad..fbba4f3c8 100644 --- a/website/content/partials/provisioner/hcp-sbom/Config-not-required.mdx +++ b/website/content/partials/provisioner/hcp-sbom/Config-not-required.mdx @@ -1,23 +1,14 @@ -- `destination` (string) - Destination is an optional field that specifies the path where the SBOM - file will be downloaded to for the user. - The 'Destination' must be a writable location. If the destination is a file, - the SBOM will be saved or overwritten at that path. If the destination is - a directory, a file will be created within the directory to store the SBOM. - Any parent directories for the destination must already exist and be - writable by the provisioning user (generally not root), otherwise, - a "Permission Denied" error will occur. If the source path is a file, - it is recommended that the destination path be a file as well. +- `destination` (string) - The path on the local machine to store a copy of the SBOM file. + You can specify an absolute or a path relative to the working directory + when you execute the Packer build. If the file already exists on the + local machine, Packer overwrites the file. If the destination is a + directory, the directory must already exist. -- `sbom_name` (string) - The name to give the SBOM when uploaded on HCP Packer - - By default this will be generated, but if you prefer to have a name - of your choosing, you can enter it here. - The name must match the following regexp: `[a-zA-Z0-9_-]{3,36}` - - Note: it must be unique for a single build, otherwise the build will - fail when uploading the SBOMs to HCP Packer, and so will the Packer - build command. +- `sbom_name` (string) - The name of the SBOM file stored in HCP Packer. + If omitted, HCP Packer uses the build fingerprint as the file name. + This value must be between three and 36 characters from the following set: `[A-Za-z0-9_-]`. + You must specify a unique name for each build in an artifact version. diff --git a/website/content/partials/provisioner/hcp-sbom/Config-required.mdx b/website/content/partials/provisioner/hcp-sbom/Config-required.mdx index 2f227c2b0..4df8744eb 100644 --- a/website/content/partials/provisioner/hcp-sbom/Config-required.mdx +++ b/website/content/partials/provisioner/hcp-sbom/Config-required.mdx @@ -1,7 +1,6 @@ -- `source` (string) - Source is a required field that specifies the path to the SBOM file that - needs to be downloaded. - It can be a file path or a URL. +- `source` (string) - The file path or URL to the SBOM file in the Packer artifact. + This file must either be in the SPDX or CycloneDX format. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 51b173740..65ed0cb2d 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -792,6 +792,10 @@ "title": "File", "path": "provisioners/file" }, + { + "title": "HCP SBOM", + "path": "provisioners/hcp-sbom" + }, { "title": "PowerShell", "path": "provisioners/powershell"