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
+	// The file path or URL to the SBOM file in the Packer artifact.
-	// needs to be downloaded.
+	// This file must either be in the SPDX or CycloneDX format.
-	// It can be a file path or a URL.
 	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 path on the local machine to store a copy of the SBOM file.
-	// The 'Destination' must be a writable location. If the destination is a file,
+	// You can specify an absolute or a path relative to the working directory
-	// the SBOM will be saved or overwritten at that path. If the destination is
+	// when you execute the Packer build. If the file already exists on the
-	// a directory, a file will be created within the directory to store the SBOM.
+	// local machine, Packer overwrites the file. If the destination is a
-	// Any parent directories for the destination must already exist and be
+	// directory, the directory must already exist.
-	// 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 `mapstructure:"destination"`
-	// The name to give the SBOM when uploaded on HCP Packer
+
-	//
+	// The name of the SBOM file stored in HCP Packer.
-	// By default this will be generated, but if you prefer to have a name
+	// If omitted, HCP Packer uses the build fingerprint as the file name.
-	// of your choosing, you can enter it here.
+	// This value must be between three and 36 characters from the following set: `[A-Za-z0-9_-]`.
-	// The name must match the following regexp: `[a-zA-Z0-9_-]{3,36}`
+	// You must specify a unique name for each build in an artifact version.
-	//
-	// 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.
 	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
+- `destination` (string) - The path on the local machine to store a copy of the SBOM file.
-  file will be downloaded to for the user.
+  You can specify an absolute or a path relative to the working directory
-  The 'Destination' must be a writable location. If the destination is a file,
+  when you execute the Packer build. If the file already exists on the
-  the SBOM will be saved or overwritten at that path. If the destination is
+  local machine, Packer overwrites the file. If the destination is a
-  a directory, a file will be created within the directory to store the SBOM.
+  directory, the directory must already exist.
-  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.
 
-- `sbom_name` (string) - The name to give the SBOM when uploaded on HCP Packer
+- `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.
-  By default this will be generated, but if you prefer to have a name
+  This value must be between three and 36 characters from the following set: `[A-Za-z0-9_-]`.
-  of your choosing, you can enter it here.
+  You must specify a unique name for each build in an artifact version.
-  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.
 
 <!-- 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
+- `source` (string) - The file path or URL to the SBOM file in the Packer artifact.
-  needs to be downloaded.
+  This file must either be in the SPDX or CycloneDX format.
-  It can be a file path or a URL.
 
 <!-- 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"