Manage artifact software bill of materials

This topic describes how to upload software bill of materials (SBOM) files and associate them with an artifact version in the HCP Packer registry.

Overview

A software bill of materials stores a reference of an artifact's package metadata, and is useful to help with security and compliance audits. You can upload existing SBOM files to HCP Packer and associate them with an artifact version with the hcp-sbom provisioner or the HCP Packer registry API.

Create a software bill of materials

Packer does not generate SBOM files, so you must use a third-party tool to create them. HCP Packer requires SBOM files to be in either SPDX or CycloneDX format. For an example Packer template that uses the provisioner, refer to the Track Packer artifact package bill of materials tutorial.

Upload the software bill of materials

You can upload SBOM files to the HCP Packer registry using either the hcp-sbom provisioner or by using the HCP Packer API.

Upload using the provisioner

You can use the hcp-sbom provisioner in your Packer template to upload an SBOM from your artifact to the HCP Packer registry.

1. Add the hcp-sbom provisioner to your Packer template, for example:

   provisioner "hcp-sbom" {
     source = "/tmp/sbom-cyclonedx-0.3.json"
   }
   

   Copy

   Refer to the hcp-sbom provisioner reference for more information.

2. Run the packer init command to install the provisioner.

3. Run packer build to upload the SBOM file.

Upload using the API

You can upload SBOM files using the HCP Packer registry API. You must upload the file during the Packer build. You cannot associate SBOM files with an artifact version after Packer completes the build. To upload an SBOM:

1. Compress the SBOM using zstd, then encode it as base64.

   The following example compresses and encodes a CycloneDX SBOM stored at /tmp/sbom.json, assigns it to the SBOM variable:

   $ SBOM=`zstd -c /tmp/sbom.json --stdout | base64 -w 0` 
   

   Copy

2. Send a PUT request to the /sboms HCP Packer API endpoint. The following example uses curl to send the API request to upload the SBOM:

   $ curl -XPUT \
   https://api.cloud.hashicorp.com/packer/2023-01-01/organizations/$ORG_ID/projects/$PROJ_ID/buckets/$BUCKET/versions/$FINGERPRINT/builds/$BUILD_ID/sboms \
   --header "authorization: Bearer $HCP_ACCESS_TOKEN" \
   -d "{\"compressed_sbom\": \"$SBOM\", \"format\": \"CYCLONEDX\", \"name\": \"api-test\"}"
   

   Copy

Refer to the UploadSboms API reference for more information.

Download artifact software bill of materials

You can download SBOM files from the HCP Packer registry using the UI or the API.

Download from the UI

1. Open the artifact version overview page.
2. Click the Download SBOM drop-down and choose the SBOM you want to download.

Download using the API

Send a GET request to the /GetSbom HCP Packer API endpoint to download SBOM files using the HCP Packer registry API.