GitHub Actions에서 SBOM을 생성하는 방법

네 가지 방법

1. 종속성 그래프 내보내기

GitHub는 리포지토리의 매니페스트와 잠금 파일로 종속성 그래프를 만들고, 이를 SPDX SBOM으로 내보낼 수 있습니다. 워크플로를 바꿀 필요가 없습니다. 리포지토리의 Insights 탭을 열고 Dependency graph를 선택한 뒤 Export SBOM을 클릭하면 됩니다. 이 SBOM은 특정 빌드가 아니라 기본 브랜치의 리포지토리를 설명하므로, 워크플로가 설치하는 도구와 패키지는 들어 있지 않습니다.

스크립트로 처리하려면 REST API를 사용하세요. GET /repos/{owner}/{repo}/dependency-graph/sbom은 한 번의 호출로 SPDX JSON을 반환하지만, GitHub는 2026년 11월 13일 이후 이 API를 종료합니다. 대체 API는 비동기 방식입니다. 보고서를 요청한 뒤 반환된 sbom_url을 가져옵니다. 이 URL은 SBOM이 생성되는 동안 202로 응답하고, 이후 SPDX JSON 파일로 리디렉션되며, GitHub는 이 파일을 최대 1주일 동안 보관합니다.

# Export the dependency graph as SPDX JSON (closing down after November 13, 2026)
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/repos/OWNER/REPO/dependency-graph/sbom

# The replacement: request a report; the response carries an sbom_url
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/repos/OWNER/REPO/dependency-graph/sbom/generate-report

2. 생성기 단계 추가하기

워크플로의 단계에서 작업 공간 또는 이미지를 대상으로 생성기를 실행합니다. anchore/sbom-action은 Syft를 실행합니다. 기본적으로 작업 공간 디렉터리를 스캔해 SPDX JSON을 출력하며, 대신 컨테이너 이미지를 스캔할 수도 있고, SBOM을 워크플로 아티팩트로 업로드해 릴리스에 첨부합니다. README는 contents: write 권한을 요구하며, SBOM을 릴리스에 첨부할 때는 actions: read도 필요합니다.

name: sbom
on:
  push:
    branches: [main]
  release:
    types: [published]

jobs:
  sbom:
    runs-on: ubuntu-latest
    permissions:
      contents: write # upload the SBOM
      actions: read # attach it to a release
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
      # Scan the workspace after the install step
      - uses: anchore/sbom-action@v0
        with:
          path: .
          format: cyclonedx-json

format에는 spdx, spdx-json, cyclonedx, cyclonedx-json을 지정할 수 있습니다. 이미지를 스캔하려면 path를 image로 바꾸세요(예: image: ghcr.io/OWNER/app:1.0). BuildKit 자체의 이미지 SBOM은 Docker SBOM을 참조하세요.

Trivy와 cdxgen도 일반 run 단계로 같은 방식으로 실행할 수 있습니다. cdxgen은 CycloneDX를 출력하며, 버전 13부터 npm 패키지 이름은 @cdxgen/cdxgen입니다.

    steps:
      - uses: actions/checkout@v7
      - run: npm ci
      - run: npm install -g @cdxgen/cdxgen --ignore-scripts
      - run: cdxgen -o bom.json .
      - uses: actions/upload-artifact@v7
        with:
          name: sbom
          path: bom.json

실행 시점이 중요합니다. 종속성이 설치된 뒤에 단계를 실행하지 않으면 종속성을 보지 못합니다. 그렇게 하더라도 생성기는 앞에 있는 파일만 봅니다. 스크립트가 내려받아 사용한 뒤 삭제한 패키지나, 패키지 관리자 밖에서 설치된 도구는 빠질 수 있습니다.

3. 증명으로 서명하기

GitHub의 아티팩트 증명은 SBOM을 그것이 설명하는 아티팩트에 연결하고 Sigstore로 서명합니다. actions/attest@v4는 sbom-path를 통해 최대 16 MB의 SPDX 또는 CycloneDX JSON을 받습니다. sbom-path가 없으면 대신 SLSA 빌드 출처 증명을 생성합니다. actions/attest-sbom은 지원 중단 예정이며 actions/attest로 대체되고 있고, 현재는 actions/attest를 감싸는 래퍼입니다. 작업에는 서명 인증서를 받기 위한 id-token: write와 결과를 저장하기 위한 attestations: write가 필요합니다.

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # sign with a Sigstore certificate
      contents: read
      attestations: write # store the attestation
    steps:
      - uses: actions/checkout@v7
      - run: make build # writes dist/my-app
      - uses: anchore/sbom-action@v0
        with:
          path: .
          format: spdx-json
          output-file: sbom.spdx.json
          upload-artifact: false
      - uses: actions/attest@v4
        with:
          subject-path: dist/my-app
          sbom-path: sbom.spdx.json

컨테이너 이미지의 경우 subject-name과 subject-digest를 subject-path 대신 전달하고, push-to-registry: true를 설정하며, packages: write를 추가합니다. 아티팩트 증명은 현재 모든 GitHub 플랜의 공개 리포지토리에서 작동하며, 비공개 및 내부 리포지토리에는 GitHub Enterprise Cloud가 필요합니다.

이후 GitHub CLI로 누가 어떤 아티팩트에 대해 SBOM을 생성했는지 확인합니다. SBOM 증명에는 --predicate-type이 필요하며, SBOM 자체를 보려면 --format json을 추가하세요. 이미지의 경우 파일 경로 대신 oci:// 뒤에 이미지 이름을 붙여 사용합니다.

gh attestation verify dist/my-app \
  -R OWNER/REPO \
  --predicate-type https://spdx.dev/Document/v2.3

증명은 누가 어떤 아티팩트에 대해 SBOM을 생성했는지를 입증합니다. SBOM을 더 완전하게 만들지는 않습니다.

4. 빌드 중에 기록하기

CRACI는 작업이 실행되는 동안 SBOM을 기록합니다. runs-on을 craci로 바꾸면 됩니다.

jobs:
  build:
    runs-on: craci # was: ubuntu-latest

그러면 러너의 패키지를 인식하는 프록시가 작업이 가져온 모든 패키지를 기록합니다. CI 캐시에서 복원된 패키지와, 설치 스크립트가 내려받은 코드처럼 어떤 잠금 파일에도 나열되지 않는 숨은 종속성도 포함됩니다. 배치할 생성기 단계가 없으므로 실행 시점 문제가 사라집니다. CycloneDX 또는 SPDX 형식의 각 SBOM은 작업별 및 캐시별 완전성을 명시하며, API는 SBOM, 네트워크 추적, 출처 증명을 반환합니다. CRACI GitHub App과 네트워크 설정을 포함한 설정 방법은 CRACI 문서에 있으며, 각 완전성 상태의 의미는 작업 및 캐시 SBOM 완전성에 설명되어 있습니다.

어떤 방법을 사용해야 하는가

• 리포지토리의 빠른 인벤토리: 종속성 그래프 내보내기.
• 컨테이너 이미지의 SBOM: 이미지를 대상으로 하는 생성기 단계.
• 누가 어떤 아티팩트에 대해 SBOM을 생성했는지에 대한 증명: 둘 중 하나 위에 더하는 증명.
• 취약점 대응이나 Cyber Resilience Act를 위해 빌드가 실제로 사용한 것의 기록: 빌드 시점 기록. SBOM 도구 비교를 참조하세요.

GitHub Actions의 SBOM: 자주 묻는 질문

GitHub Actions에서 SBOM을 어떻게 생성합니까?

설치 단계 뒤에 생성기 단계를 추가하세요. 가장 간단한 방법은 anchore/sbom-action@v0이며, 작업 공간에서 Syft를 실행하고 SPDX JSON SBOM을 워크플로 아티팩트로 업로드합니다. 서명된 SBOM이 필요하면 파일을 actions/attest@v4에 sbom-path로 전달하세요.

GitHub가 SBOM을 자동으로 생성합니까?

GitHub는 Insights 탭이나 REST API에서 리포지토리의 종속성 그래프를 SPDX SBOM으로 내보낼 수 있습니다. 이 SBOM은 특정 빌드가 아니라 리포지토리의 매니페스트와 잠금 파일을 설명하므로, 워크플로가 내려받는 도구나 패키지는 표시되지 않습니다.

GitHub Actions에서 SBOM을 생성하는 액션은 무엇입니까?

anchore/sbom-action은 Syft를 실행합니다. 기본적으로 작업 공간 디렉터리를 스캔해 SPDX JSON을 출력하며, 대신 컨테이너 이미지를 스캔할 수도 있고, SBOM을 워크플로 아티팩트로 업로드해 릴리스에 첨부합니다.

SBOM 워크플로에는 어떤 권한이 필요합니까?

anchore/sbom-action은 contents: write를 요구하며, SBOM을 릴리스에 첨부하려면 actions: read도 필요합니다. actions/attest로 서명하려면 id-token: write와 attestations: write가 필요하고, 증명을 컨테이너 레지스트리에 푸시할 때는 packages: write도 필요합니다.

GitHub Actions에서 SBOM에 어떻게 서명합니까?

GitHub의 아티팩트 증명을 사용하세요. actions/attest는 SPDX 또는 CycloneDX JSON SBOM에 Sigstore로 서명하고 아티팩트에 연결합니다. 검증은 gh attestation verify로 합니다. actions/attest-sbom은 지원 중단 예정이며 actions/attest로 대체되고 있고, 현재는 actions/attest를 감싸는 래퍼입니다.

GitHub Actions에서 컨테이너 이미지의 SBOM을 어떻게 생성합니까?

image 입력(path 대신)으로 이미지를 anchore/sbom-action에 전달하세요. 서명하려면 actions/attest에 subject-name과 subject-digest로 이미지 이름과 다이제스트를 전달하고, push-to-registry: true를 설정한 뒤 gh attestation verify oci://IMAGE로 검증하세요.

워크플로는 SPDX와 CycloneDX 중 무엇을 생성해야 합니까?

SBOM을 읽는 도구가 기대하는 형식을 사용하세요. 종속성 그래프 내보내기는 SPDX만 지원하고 cdxgen은 CycloneDX를 출력합니다. anchore/sbom-action은 둘 다 출력할 수 있고, actions/attest는 둘 다 받습니다. CycloneDX vs SPDX를 참조하세요.

SBOM 단계는 빌드 전에 실행해야 합니까, 후에 실행해야 합니까?

종속성이 설치된 후에 실행해야 하며, 그렇지 않으면 종속성을 놓칩니다. 그렇게 하더라도 디스크에 있는 것만 보며, 작업이 내려받았다가 삭제한 것이나 스크립트가 가져온 것은 보지 못합니다. 빌드 중에 기록하면 실행 시점 문제를 피할 수 있습니다.