Skip to content

Commit 2e60923

Browse files
devashish-patellbajolet-hashicorp
devashish-patel
authored and
lbajolet-hashicorp
committed
website: add docs for the hcp-sbom provisioner
1 parent 8dcd9fe commit 2e60923

File tree

7 files changed

+168
-42
lines changed

7 files changed

+168
-42
lines changed

‎provisioner/hcp-sbom/provisioner.go‎

Lines changed: 13 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -30,29 +30,21 @@ import (
3030
type Config struct {
3131
common.PackerConfig `mapstructure:",squash"`
3232

33-
// Source is a required field that specifies the path to the SBOM file that
34-
// needs to be downloaded.
35-
// It can be a file path or a URL.
33+
// The file path or URL to the SBOM file in the Packer artifact.
34+
// This file must either be in the SPDX or CycloneDX format.
3635
Source string `mapstructure:"source" required:"true"`
37-
// Destination is an optional field that specifies the path where the SBOM
38-
// file will be downloaded to for the user.
39-
// The 'Destination' must be a writable location. If the destination is a file,
40-
// the SBOM will be saved or overwritten at that path. If the destination is
41-
// a directory, a file will be created within the directory to store the SBOM.
42-
// Any parent directories for the destination must already exist and be
43-
// writable by the provisioning user (generally not root), otherwise,
44-
// a "Permission Denied" error will occur. If the source path is a file,
45-
// it is recommended that the destination path be a file as well.
36+
37+
// The path on the local machine to store a copy of the SBOM file.
38+
// You can specify an absolute or a path relative to the working directory
39+
// when you execute the Packer build. If the file already exists on the
40+
// local machine, Packer overwrites the file. If the destination is a
41+
// directory, the directory must already exist.
4642
Destination string `mapstructure:"destination"`
47-
// The name to give the SBOM when uploaded on HCP Packer
48-
//
49-
// By default this will be generated, but if you prefer to have a name
50-
// of your choosing, you can enter it here.
51-
// The name must match the following regexp: `[a-zA-Z0-9_-]{3,36}`
52-
//
53-
// Note: it must be unique for a single build, otherwise the build will
54-
// fail when uploading the SBOMs to HCP Packer, and so will the Packer
55-
// build command.
43+
44+
// The name of the SBOM file stored in HCP Packer.
45+
// If omitted, HCP Packer uses the build fingerprint as the file name.
46+
// This value must be between three and 36 characters from the following set: `[A-Za-z0-9_-]`.
47+
// You must specify a unique name for each build in an artifact version.
5648
SbomName string `mapstructure:"sbom_name"`
5749
ctx interpolate.Context
5850
}

‎website/content/community-plugins.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ HashiCorp maintainers for advice on how to get started contributing.
2424
## Provisioners
2525

2626
- File
27+
- HCP SBOM
2728
- InSpec
2829
- PowerShell
2930
- Shell

‎website/content/docs/provisioners/hcp-sbom.mdx‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
description: |
3+
The hcp-sbom Packer provisioner uploads a CycloneDX or SPDX JSON-formatted software bill of materials record to HCP Packer.
4+
page_title: HCP SBOM - Provisioners
5+
---
6+
7+
<BadgesHeader>
8+
<PluginBadge type="official"/>
9+
</BadgesHeader>
10+
11+
# HCP SBOM Provisioner
12+
13+
Type: `hcp-sbom`
14+
15+
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.
16+
17+
## Example
18+
19+
The following example uploads an SBOM from the local `/tmp` directory and stores a copy at `./sbom/sbom_cyclonedx.json` on the local machine.
20+
21+
<Tabs>
22+
<Tab heading="HCL2">
23+
24+
```hcl
25+
provisioner "hcp-sbom" {
26+
source = "/tmp/sbom_cyclonedx.json"
27+
destination = "./sbom/sbom_cyclonedx.json"
28+
sbom_name = "sbom-cyclonedx"
29+
}
30+
```
31+
32+
</Tab>
33+
<Tab heading="JSON">
34+
35+
```json
36+
{
37+
"type": "hcp-sbom",
38+
"source": "/tmp/sbom_cyclonedx.json",
39+
"destination": "./sbom/sbom_cyclonedx.json",
40+
"sbom_name": "sbom-cyclonedx"
41+
}
42+
```
43+
44+
</Tab>
45+
</Tabs>
46+
47+
## Configuration reference
48+
49+
You can specify the following configuration options.
50+
51+
Required parameters:
52+
53+
@include 'provisioner/hcp-sbom/Config-required.mdx'
54+
55+
Optional parameters:
56+
57+
@include '/provisioner/hcp-sbom/Config-not-required.mdx'
58+
59+
## Example usage
60+
61+
<Tabs>
62+
<Tab heading="HCL2">
63+
64+
```hcl
65+
packer {
66+
required_plugins {
67+
docker = {
68+
version = ">= 1.0.0"
69+
source = "github.com/hashicorp/docker"
70+
}
71+
}
72+
}
73+
74+
source "docker" "ubuntu" {
75+
image = "ubuntu:20.04"
76+
commit = true
77+
}
78+
79+
build {
80+
sources = ["source.docker.ubuntu"]
81+
82+
hcp_packer_registry {
83+
bucket_name = "test-bucket"
84+
}
85+
86+
87+
provisioner "shell" {
88+
inline = [
89+
"apt-get update -y",
90+
"apt-get install -y curl gpg",
91+
"bash -c \"$(curl -sSL https://install.mondoo.com/sh)\"",
92+
"cnquery sbom --output cyclonedx-json --output-target /tmp/sbom_cyclonedx.json",
93+
]
94+
}
95+
96+
provisioner "hcp-sbom" {
97+
source = "/tmp/sbom_cyclonedx.json"
98+
destination = "./sbom"
99+
sbom_name = "sbom-cyclonedx"
100+
}
101+
}
102+
```
103+
104+
</Tab>
105+
<Tab heading="JSON">
106+
107+
```json
108+
{
109+
"builders": [
110+
{
111+
"type": "docker",
112+
"image": "ubuntu:20.04",
113+
"commit": true
114+
}
115+
],
116+
"provisioners": [
117+
{
118+
"type": "shell",
119+
"inline": [
120+
"apt-get update -y",
121+
"apt-get install -y curl",
122+
"bash -c \"$(curl -sSL https://install.mondoo.com/sh)\"",
123+
"cnquery sbom --output cyclonedx-json --output-target /tmp/sbom_cyclonedx.json"
124+
]
125+
},
126+
{
127+
"type": "hcp-sbom",
128+
"source": "/tmp/sbom_cyclonedx.json",
129+
"destination": "./sbom",
130+
"sbom_name": "sbom-cyclonedx"
131+
}
132+
]
133+
}
134+
```
135+
136+
</Tab>
137+
</Tabs>

‎website/content/docs/provisioners/index.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ The following provisioners are included with Packer:
2020
- [Breakpoint](/packer/docs/provisioners/breakpoint) - pause until the user presses `Enter` to resume
2121
a build.
2222
- [File](/packer/docs/provisioners/file) - upload files to machines image during a build.
23+
- [HCP SBOM](/packer/docs/provisioners/hcp-sbom) - upload an SBOM and associate it with an artifact
24+
version in the HCP Packer registry.
2325
- [Shell](/packer/docs/provisioners/shell) - run shell scripts on the machines image during a build.
2426
- [Local Shell](/packer/docs/provisioners/shell-local) - run shell scripts on the host running Packer
2527
during a build.

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

Lines changed: 9 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,14 @@
11
<!-- Code generated from the comments of the Config struct in provisioner/hcp-sbom/provisioner.go; DO NOT EDIT MANUALLY -->
22

3-
- `destination` (string) - Destination is an optional field that specifies the path where the SBOM
4-
file will be downloaded to for the user.
5-
The 'Destination' must be a writable location. If the destination is a file,
6-
the SBOM will be saved or overwritten at that path. If the destination is
7-
a directory, a file will be created within the directory to store the SBOM.
8-
Any parent directories for the destination must already exist and be
9-
writable by the provisioning user (generally not root), otherwise,
10-
a "Permission Denied" error will occur. If the source path is a file,
11-
it is recommended that the destination path be a file as well.
3+
- `destination` (string) - The path on the local machine to store a copy of the SBOM file.
4+
You can specify an absolute or a path relative to the working directory
5+
when you execute the Packer build. If the file already exists on the
6+
local machine, Packer overwrites the file. If the destination is a
7+
directory, the directory must already exist.
128

13-
- `sbom_name` (string) - The name to give the SBOM when uploaded on HCP Packer
14-
15-
By default this will be generated, but if you prefer to have a name
16-
of your choosing, you can enter it here.
17-
The name must match the following regexp: `[a-zA-Z0-9_-]{3,36}`
18-
19-
Note: it must be unique for a single build, otherwise the build will
20-
fail when uploading the SBOMs to HCP Packer, and so will the Packer
21-
build command.
9+
- `sbom_name` (string) - The name of the SBOM file stored in HCP Packer.
10+
If omitted, HCP Packer uses the build fingerprint as the file name.
11+
This value must be between three and 36 characters from the following set: `[A-Za-z0-9_-]`.
12+
You must specify a unique name for each build in an artifact version.
2213

2314
<!-- 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‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
<!-- Code generated from the comments of the Config struct in provisioner/hcp-sbom/provisioner.go; DO NOT EDIT MANUALLY -->
22

3-
- `source` (string) - Source is a required field that specifies the path to the SBOM file that
4-
needs to be downloaded.
5-
It can be a file path or a URL.
3+
- `source` (string) - The file path or URL to the SBOM file in the Packer artifact.
4+
This file must either be in the SPDX or CycloneDX format.
65

76
<!-- End of code generated from the comments of the Config struct in provisioner/hcp-sbom/provisioner.go; -->

‎website/data/docs-nav-data.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -792,6 +792,10 @@
792792
"title": "File",
793793
"path": "provisioners/file"
794794
},
795+
{
796+
"title": "HCP SBOM",
797+
"path": "provisioners/hcp-sbom"
798+
},
795799
{
796800
"title": "PowerShell",
797801
"path": "provisioners/powershell"

0 commit comments

Comments
 (0)