website: add docs for the hcp-sbom provisioner

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
 }

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

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
+---
+
+<BadgesHeader>
+  <PluginBadge type="official"/>
+</BadgesHeader>
+
+# 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.
+
+<Tabs>
+<Tab heading="HCL2">
+
+```hcl
+provisioner "hcp-sbom" {
+  source      = "/tmp/sbom_cyclonedx.json"
+  destination = "./sbom/sbom_cyclonedx.json"
+  sbom_name   = "sbom-cyclonedx"
+}
+```
+
+</Tab>
+<Tab heading="JSON">
+
+```json
+{
+  "type": "hcp-sbom",
+  "source": "/tmp/sbom_cyclonedx.json",
+  "destination": "./sbom/sbom_cyclonedx.json",
+  "sbom_name": "sbom-cyclonedx"
+}
+```
+
+</Tab>
+</Tabs>
+
+## 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
+
+<Tabs>
+<Tab heading="HCL2">
+
+```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"
+  }
+}
+```
+
+</Tab>
+<Tab heading="JSON">
+
+```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"
+    }
+  ]
+}
+```
+
+</Tab>
+</Tabs>

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.

website/content/partials/provisioner/hcp-sbom/Config-not-required.mdx

@@ -1,23 +1,14 @@
 <!-- Code generated from the comments of the Config struct in provisioner/hcp-sbom/provisioner.go; DO NOT EDIT MANUALLY -->
 
-- `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.
 
 <!-- End of code generated from the comments of the Config struct in provisioner/hcp-sbom/provisioner.go; -->

website/content/partials/provisioner/hcp-sbom/Config-required.mdx

@@ -1,7 +1,6 @@
 <!-- Code generated from the comments of the Config struct in provisioner/hcp-sbom/provisioner.go; DO NOT EDIT MANUALLY -->
 
-- `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.
 
 <!-- End of code generated from the comments of the Config struct in provisioner/hcp-sbom/provisioner.go; -->

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"