hcp-sbom 프로비저너

hcp-sbom 프로비저너

공식 (Official)

hcp-sbom provisioner는 Packer가 빌드한 아티팩트의 소프트웨어 자재 명세(SBOM, software bill of materials) 파일을 HCP Packer에 업로드하고 개별 아티팩트 버전과 연결해요. 업로드하려는 SBOM 파일은 JSON 형식이어야 하며 SPDX 또는 CycloneDX 명세를 따라야 해요.

이 provisioner는 다음 운영 방식을 지원해요.

  • 수동 SBOM 업로드(source): 원격 호스트에서 자체 생성한 SBOM 파일을 업로드해요.
  • 자동 SBOM 생성(auto_generate): Packer가 내장 스캐닝 도구를 사용해 SBOM을 생성해요. 자세한 내용은 Automatic SBOM generation을 참고하세요.

출처: Packer 공식 문서

본문

예시 (Examples)

다음 예시는 로컬 /tmp 디렉터리에서 SBOM을 업로드하고 로컬 머신의 ./sbom/sbom_cyclonedx.json에 복사본을 저장해요.

provisioner "hcp-sbom" {
source      = "/tmp/sbom_cyclonedx.json"
destination = "./sbom/sbom_cyclonedx.json"
sbom_name   = "sbom-cyclonedx"
}

{
"type": "hcp-sbom",
"source": "/tmp/sbom_cyclonedx.json",
"destination": "./sbom/sbom_cyclonedx.json",
"sbom_name": "sbom-cyclonedx"
}

자동 SBOM 생성 (Automatic SBOM generation)

원격 호스트에서 SBOM을 생성하도록 Packer를 자동으로 다운로드해 실행하도록 provisioner를 구성할 수 있어요.

다음 예시는 원격 호스트에서 Packer를 실행해 SBOM을 생성하고, HCP Packer 아티팩트 버전과 연결한 뒤 로컬 머신의 ./sbom/sbom_cyclonedx.json에 복사본을 저장해요.

provisioner "hcp-sbom" {
auto_generate = true
destination = "./sbom/sbom_cyclonedx.json"
sbom_name     = "auto-generated-sbom"
}

{
"type": "hcp-sbom",
"auto_generate": true,
"destination": "./sbom/sbom_cyclonedx.json",
"sbom_name": "auto-generated-sbom"
}

auto_generate를 true로 설정하면 Packer는 원격 호스트의 OS와 아키텍처를 자동으로 감지하고 적절한 Packer 바이너리를 다운로드해요. 그런 다음 Packer가 SBOM을 생성하고, SBOM을 다운로드한 뒤 HCP Packer에 업로드해요.

Packer가 빌드를 완료하면 SBOM 생성 도구를 다운로드하기 위해 만들었던 모든 임시 파일을 정리해요.

참고: Packer는 원격 호스트에 연결할 때 런타임에 OS와 아키텍처를 검증해요. 감지된 플랫폼이 지원되지 않으면 provisioner는 지원되지 않는 플랫폼을 알리는 오류 메시지와 함께 실패해요.

승격된 실행 (Elevated execution)

원격 시스템에서 스캔을 수행하고 SBOM을 생성하는 데 다른 권한이 필요하면 provisioner를 커스터마이즈할 수 있어요.

참고: sudo나 관리자(administrator) 접근 같은 승격된 권한으로 SBOM 생성 도구를 실행하면 더 완전한 스캔 결과를 얻을 수 있어요. 승격된 권한이 없으면 도구가 시스템의 모든 파일과 디렉터리에 접근하지 못할 수 있고, 결과적으로 불완전한 SBOM이 생길 수 있어요.

기본적으로 Packer는 SBOM 생성 도구를 실행하기 위해 다음 명령을 실행해요.

chmod +x {{.Path}} && sudo {{.Path}} sbom-generate {{.Args}} {{.ScanPath}} > {{.Output}}

{{.Path}} sbom-generate {{.Args}} {{.ScanPath}} > {{.Output}}

execute_command 인자를 설정해 이 기본 동작을 덮어쓸 수 있어요. Packer는 SBOM 생성 도구의 경로, 도구 인자, 스캔할 경로 같은 정보를 런타임에 채워 넣는 템플릿 변수를 제공해요. 지원되는 변수의 전체 목록은 execute_command의 Template variables를 참고하세요.

다음 예시는 기본 execute_command 값을 덮어써서 sudo 명령에 비밀번호를 제공해요.

provisioner "hcp-sbom" {
auto_generate   = true
execute_command = "chmod +x {{.Path}} && echo 'mypassword' | sudo -S {{.Path}} sbom-generate {{.Args}} {{.ScanPath}} > {{.Output}}"
destination     = "./sbom"
sbom_name       = "sbom-sudo-password"
}

다음 예시는 승격된 권한이 필요하지 않은 경우 명령에서 sudo를 제거해요.

provisioner "hcp-sbom" {
auto_generate   = true
execute_command = "chmod +x {{.Path}} && {{.Path}} sbom-generate {{.Args}} {{.ScanPath}} > {{.Output}}"
destination     = "./sbom"
sbom_name       = "sbom-no-sudo"
}
커스텀 사용자를 사용하는 Windows (Windows with a custom user)

관리자 권한이 필요한 Windows 호스트의 경우, elevated_user와 elevated_password 파라미터를 설정해 특정 사용자로 SBOM 생성을 실행하도록 Packer에 지시할 수 있어요.

provisioner "hcp-sbom" {
auto_generate      = true
elevated_user      = "Administrator"
elevated_password  = "MySecurePassword123!"
destination        = "./sbom"
sbom_name          = "windows-elevated-sbom"
}

설정 참조 (Configuration reference)

다음 구성 옵션을 지정할 수 있어요.

요구되는 파라미터: 다음 중 정확히 하나가 필요해요.

  • source (string) — Packer 아티팩트 안의 SBOM 파일 경로 또는 URL이에요. 이 파일은 SPDX 또는 CycloneDX 형식이어야 해요. auto_generate와 상호 배타적이에요.
  • auto_generate (bool) — 원격 호스트에서 packer sbom-generate를 실행해 자동 SBOM 생성을 활성화해요. 활성화하면 provisioner가 실행 중인 Packer 바이너리(Syft SDK가 내장된)를 원격 VM에 업로드하고 거기서 실행해 SBOM을 생성해요. source와 상호 배타적이에요.

선택 파라미터:

  • destination (string) — SBOM 파일 복사본을 저장할 로컬 머신의 경로예요. Packer 빌드를 실행할 때 작업 디렉터리를 기준으로 절대 경로 또는 상대 경로를 지정할 수 있어요. 파일이 로컬 머신에 이미 있으면 Packer가 덮어써요. destination이 디렉터리면 그 디렉터리가 이미 존재해야 해요.
  • sbom_name (string) — HCP Packer에 저장되는 SBOM 파일의 이름이에요. 생략하면 HCP Packer가 빌드 지문(fingerprint)을 파일 이름으로 사용해요. 이 값은 [A-Za-z0-9_-] 문자 집합에서 3~36자 사이여야 해요. 아티팩트 버전의 각 빌드마다 고유한 이름을 지정해야 해요.
  • scanner_args ([]string) — packer sbom-generate에 전달할 인자예요. 기본값: ["-o", "cyclonedx-json"]이에요.
  • scanner_url (string) — DEPRECATED: 커스텀 스캐너 URL은 더 이상 지원되지 않아요. hcp-sbom provisioner는 이제 자동 SBOM 생성에 Syft SDK가 내장된 Packer 바이너리를 사용해요. 이 필드는 무시되며 향후 메이저 버전에서 제거될 거예요. 커스텀 SBOM 도구의 경우 auto_generate 대신 source 필드로 수동 생성을 사용하세요.
  • scanner_checksum (string) — DEPRECATED: 스캐너 체크섬 검증은 더 이상 지원되지 않아요. 이 필드는 무시되며 향후 메이저 버전에서 제거될 거예요.
  • scan_path (string) — 원격 호스트에서 스캔할 경로예요. 기본값은 /(루트 디렉터리)예요.
  • execute_command (string) — 원격 호스트에서 스캐너를 실행하는 데 사용되는 명령 템플릿이에요. 사용 가능한 템플릿 변수:
    • {{.Path}} — 원격 호스트의 스캐너 바이너리 경로
    • {{.Args}} — 스캐너 인자(scanner_args에서)
    • {{.ScanPath}} — 스캔할 경로(scan_path에서)
    • {{.Output}} — SBOM의 출력 파일 경로 Unix 기본값: chmod +x {{.Path}} && sudo {{.Path}} sbom-generate {{.Args}} {{.ScanPath}} > {{.Output}} Windows 기본값: {{.Path}} sbom-generate {{.Args}} {{.ScanPath}} > {{.Output}} 예시: sudo 없이:
    execute_command = "chmod +x {{.Path}} && {{.Path}} sbom-generate {{.Args}} {{.ScanPath}} > {{.Output}}"
    sudo 비밀번호와 함께: 
    execute_command = "chmod +x {{.Path}} && echo 'password' | sudo -S {{.Path}} sbom-generate {{.Args}} {{.ScanPath}} > {{.Output}}"
  • elevated_user (string) — Windows에서 Packer를 실행할 때 승격된 권한에 사용할 사용자 이름이에요. 승격된 권한이 필요한 Windows 호스트에서만 사용돼요. Unix 계열 시스템에서는 sudo와 함께 execute_command를 사용하세요.
  • elevated_password (string) — elevated_user의 비밀번호예요. elevated_user가 지정되면 필수예요. Windows 호스트에만 적용돼요.

운영체제와 아키텍처 감지 (Operating system and architecture detection)

auto_generate를 활성화하면 provisioner는 다음 명령을 실행해 원격 호스트의 운영체제와 아키텍처를 자동으로 감지해요.

  • SSH communicator: uname -s -m
  • WinRM communicator: echo %PROCESSOR_ARCHITECTURE%

provisioner는 이 정보를 사용해 원격 호스트에서 올바른 Packer 빌드를 다운로드·압축 해제하고, 플랫폼별 기본 실행 명령을 설정해요.

수동 SBOM 생성 전체 예시 (Complete example with manual SBOM generation)

다음 예시는 SBOM을 생성하기 위해 커스텀 스캐너를 다운로드·설치·실행하는 shell provisioner를 포함해요. 그런 다음 hcp-sbom provisioner의 source 인자를 커스텀 스캐닝 도구의 출력 파일로 설정해요.

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"
}
}

{
"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"
}
]
}

자동 SBOM 생성 전체 예시 (Complete example with automatic SBOM generation)

다음 예시는 Packer의 내장 자동 스캐너를 사용해 아티팩트의 SBOM을 생성하고 업로드해요.

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 "hcp-sbom" {
auto_generate = true
scan_path     = "/"
destination   = "./sbom"
sbom_name     = "auto-generated-sbom"
}
}

{
"builders": [
{
"type": "docker",
"image": "ubuntu:20.04",
"commit": true
}
],
"provisioners": [
{
"type": "hcp-sbom",
"auto_generate": true,
"scan_path": "/",
"destination": "./sbom",
"sbom_name": "auto-generated-sbom"
}
]
}

execute_command의 템플릿 변수 (Template variables in execute_command)

execute_command 구성 옵션은 다음 템플릿 변수를 지원해요.

  • {{.Path}} — 원격 호스트의 Packer 경로
  • {{.Args}} — 도구 인자(scanner_args에서)
  • {{.ScanPath}} — 스캔할 경로(scan_path에서)
  • {{.Output}} — SBOM의 출력 파일 경로

이 변수들은 다양한 환경과 보안 요구사항에서 유연성을 유지하면서 provisioner가 SBOM 생성 도구를 실행하는 방식을 커스터마이즈할 수 있게 해줘요.