SBOM

포털은 가장 최근 성공 스캔으로부터 Software Bill of Materials(SBOM) 산출물을 생성합니다. 4가지 교환 포맷과 attribution NOTICE 파일을 지원합니다.

내보내기 vs 업로드

이 페이지는 TRUSCA가 스캔으로부터 생성한 SBOM을 내보내는(export) 방법을 다룹니다. 반대로 고객 도구가 이미 만든 SBOM(CycloneDX 또는 SPDX)을 업로드해 TRUSCA가 CVE를 매칭하고 적합성을 채점하게 하려면 SBOM 업로드와 스캔 → SBOM 업로드을 참고하세요.

대상 독자

릴리스를 출고하는 엔지니어, 산출물을 제출하는 컴플라이언스 리드, EO 14028에 따라 SBOM 요청을 처리하는 고객. 팀 멤버십 기반 읽기 권한.

지원 포맷

포맷	쿼리 값 (format=)	MIME	사용 사례
CycloneDX 1.6 (JSON)	cyclonedx-json	application/vnd.cyclonedx+json	SCA 도구의 사실상 표준. VEX 포함.
CycloneDX 1.6 (XML)	cyclonedx-xml	application/vnd.cyclonedx+xml	동일 데이터; 레거시 도구를 위한 XML.
SPDX 2.3 (JSON)	spdx-json	application/spdx+json	규제 산업에서 폭넓게 수용.
SPDX 2.3 (Tag-Value)	spdx-tv	text/spdx	원래의 SPDX 라인 기반 포맷.

두 포맷 모두 동일한 내부 모델에서 생성되므로 컴포넌트 목록은 (포맷별 필드 제외) 동일합니다.

컴포넌트별 포함 내용

각 컴포넌트는 이름, 버전, 패키지 URL(PURL), 그리고 탐지된 라이선스를 담습니다.

• 라이선스 — 스캔의 라이선스 finding에서 채웁니다. CycloneDX는 컴포넌트 licenses 배열을 사용하고(concluded → declared → detected 우선순위), SPDX는 licenseDeclared·licenseConcluded를 SPDX license expression으로 채웁니다. 탐지된 라이선스가 없거나 SPDX 식별자가 없는 라이선스(ORT LicenseRef-*)는 SPDX에서 스펙 sentinel NOASSERTION으로 출력됩니다 (CycloneDX는 라이선스 이름을 그대로 담음). copyrightText는 현재 항상 NOASSERTION입니다.

• 최상위 버전 — metadata.component.version은 스캔된 릴리스를 반영합니다. 스캔 제출 시 release 라벨(예: v1.2.3)이 지정됐으면 그 값을, 없으면 스캔 id를 안정적 fallback으로 사용합니다.

• 문서 메타데이터 — 스캔이 만드는 SBOM(서명해서 내려받는 그 문서)과 이 페이지가 내보내는 SBOM 모두 2026 SBOM 최소 요소가 요구하는 자기 기술을 기록합니다. 생성 시점(metadata.lifecycles — 소스 스캔은 pre-build, 컨테이너 스캔은 post-build. 인제스트한 공급자 문서를 다시 내보낼 때는 단계를 적지 않습니다. 남의 문서를 변환한다고 우리가 작성자가 되지는 않기 때문입니다), 생성 도구와 그 버전, SBOM_AUTHOR로 선언한 작성자, 그리고 비어 있는 필드는 숨긴 것이 아니라 이번 스캔이 확인하지 못한 것이라는 문서 단위 선언입니다. 버전을 확인하지 못한 컴포넌트는 버전 문자열 대신 그 표시를 달고 나갑니다. 확인하지 못한 값을 답처럼 보여 주지 않기 위해서입니다.

의존성 그래프와 완전성

CycloneDX 내보내기(JSON, XML)에는 스캔의 의존성 그래프를 담은 dependencies 절이 들어 있습니다. 프로젝트가 맨 앞에 오고, 목록에 있는 컴포넌트마다 항목이 하나씩 있으며, 의존하는 것이 없으면 dependsOn이 빈 배열입니다. SPDX 내보내기에는 이 절이 없습니다.

문서가 얼마나 완전한지도 CycloneDX compositions로 밝힙니다. 컴포넌트 목록(assemblies)과 그래프(dependencies)에 대해 각각 complete, incomplete, unknown 중 하나를 씁니다. complete는 스캔이 기록한 실패 가운데 컴포넌트나 간선을 빠뜨릴 수 있는 것이 없었다는 뜻입니다. 소프트웨어에 들어 있는 모든 것이 SBOM에 있다는 뜻은 아닙니다. 잠금 파일 없이 매니페스트만 있으면 직접 의존성만 나오는데, 기록으로는 그것을 볼 수 없습니다. 문서 속성 trusca:composition-basis가 판정의 이유를 알려 줍니다.

판정	조건	trusca:composition-basis
complete	스캔이 단계를 기록했고, 의존성을 잃을 수 있는 단계가 실패하지 않았으며, 컴포넌트와 함께 그래프가 나왔습니다.	no_known_gap
incomplete	SBOM 생성이 대체 방식으로 진행됐거나, 빌드 준비나 CocoaPods 보완이 열화됐거나, 매니페스트가 있는데 아무것도 찾지 못했거나, policy-filtered 프로파일이 컴포넌트를 제거했습니다.	stage_degraded:<단계>, empty_with_manifests, profile_filter
unknown	스캔이 단계 기록보다 먼저 만들어졌거나(다시 스캔하면 판정이 나옵니다), 소스에 매니페스트가 없거나, 생성이 아니라 업로드한 문서이거나, 컴포넌트만 있고 그래프가 없습니다(그래프 문장에 한함).	not_recorded, no_manifests, ingested_document, no_graph

incomplete의 근거가 되는 단계는 개요 탭의 스캔이 작업 일부를 건너뛰었을 때에 나오는 것들입니다.

Byte-stable 출력

4가지 내보내기 모두 byte-stable입니다 — 같은 스캔을 다시 내보내면 동일 바이트가 생성됩니다. diff·서명·캐싱이 단순해집니다.

byte-stability 달성 방법:

• 컴포넌트를 purl(사전식)로 정렬.
• 각 컴포넌트 내 라이선스 표현을 알파벳순 정렬.
• serialNumber(CycloneDX) / documentNamespace(SPDX)를 (project_id, scan_id) 기반 결정적 값으로 고정.
• 본문에서 타임스탬프를 제외(SBOM 메타데이터에는 스캔 종료 시각이 기록되며 스캔당 안정적).

UI에서 다운로드

1. 프로젝트 열기.
2. SBOM 탭 클릭.
3. 4개 포맷 버튼 중 하나(CycloneDX JSON, CycloneDX XML, SPDX JSON, SPDX Tag-Value)를 클릭하여 다운로드.

파일명은 sbom-<project-slug>.<ext>.

API에서 다운로드

API는 SBOM을 CycloneDX JSON으로 제공합니다:

…그리고 SPDX JSON으로도 제공합니다(같은 엔드포인트, format만 다름):

# CycloneDX JSON
curl -sS -L -OJ \
  -H "Authorization: Bearer ${TRUSTEDOSS_API_KEY}" \
  "https://trustedoss.example.com/v1/projects/${PROJECT_ID}/sbom?format=cyclonedx-json"

# SPDX JSON
curl -sS -L -OJ \
  -H "Authorization: Bearer ${TRUSTEDOSS_API_KEY}" \
  "https://trustedoss.example.com/v1/projects/${PROJECT_ID}/sbom?format=spdx-json"

format 허용값: cyclonedx-json, cyclonedx-xml, spdx-json, spdx-tv.

엔드포인트는 항상 **가장 최근에 성공한 스캔(latest succeeded)**의 SBOM을 내보냅니다. 특정 과거 스캔 ID로 고정하는 기능은 로드맵 항목입니다.

감사 증거 — 스캔을 외부에서 고정하세요

SBOM 내보내기는 항상 최신 성공 스캔을 반영합니다. 외부 감사관은 보통 특정 릴리스 시점의 SBOM을 요청합니다(예: "2026-01-15에 출고된 것은 무엇인가?"). 과거 스캔 고정()이 적용되기 전까지는 각 릴리스 경계에서 SBOM 산출물을 캡처하여 릴리스 아카이브에 보관하세요. 포털은 현재 SBOM으로 다루되 과거 SBOM의 출처로 보지 마세요.

정책 프로파일

기본 내보내기는 가공하지 않은 컴포넌트 목록입니다. 선택적 정책 프로파일은 팀의 라이선스 정책을 내보내기에 적용해, 배포용 SBOM이 조직의 기준을 반영하게 합니다.

• 정책 주석(policy annotated) — 위반 컴포넌트를 제거하지 않고 그 자리에 표시합니다. CycloneDX 컴포넌트에는 trusca:policy:category / trusca:policy:spdx properties가, SPDX 패키지에는 REVIEW annotation이 추가됩니다. 금지뿐 아니라 조건부 컴포넌트도 함께 표시되므로, 검토자가 SBOM 안에서 각 컴포넌트가 왜 문제인지 바로 볼 수 있습니다.
• 정책 필터(policy filtered) — 금지 컴포넌트를 내보내기에서 제외하고 (그 컴포넌트를 참조하던 취약점 항목도 함께 제거), 제외한 개수를 문서에 기록합니다(trusca:policy:excluded_count 또는 문서 annotation).

팀·조직 정책이 설정돼 있지 않으면 내장 분류 카탈로그로 대체 판정하므로, 금지 GPL은 그래도 표시됩니다.

SBOM 탭에서 프로파일을 선택하거나 API에 profile을 전달합니다.

curl -sS -L -OJ \
  -H "Authorization: Bearer ${TRUSTEDOSS_API_KEY}" \
  "https://trustedoss.example.com/v1/projects/${PROJECT_ID}/sbom?format=cyclonedx-json&profile=policy-annotated"

profile 허용값: policy-annotated, policy-filtered. 프로파일 내보내기는 파일명이 구분되게 지정되어(sbom-<project>-<profile>.<ext>) 표준 내보내기와 혼동되지 않습니다.

프로파일 내보내기에는 서명이 붙지 않습니다

cosign 서명은 기본 SBOM — 스캔 시점에 생성된 정확한 바이트 — 에만 적용됩니다. 정책 프로파일은 요청 시점에 생성되므로 서명이 없으며, 프로파일 내보내기에 대해 cosign verify-blob을 실행하면 실패합니다. 검증 가능한 서명 산출물이 필요하면 기본 내보내기를 쓰고, 프로파일 내보내기는 검토·배포용 편의로 취급하십시오.

NOTICE 파일

Apache-2.0 §4(d)와 유사한 attribution 의무 이행을 위해 포털은 프로젝트 최신 스캔으로부터 NOTICE attribution 본문을 자동 생성합니다.

파일 내용:

• 프로젝트 이름과 생성 타임스탬프 헤더.
• 검출된 라이선스별 섹션 하나씩 — 해당 라이선스의 컴포넌트(name @ version) 목록과 컴포넌트별 저작권 라인 포함. SBOM이 코드가 아니라 데이터로 기록한 컴포넌트에는 버전 뒤에 [dataset] 표시가 붙습니다. AI SBOM은 학습 데이터와 라이브러리를 한 목록에 함께 싣는데, 데이터셋의 라이선스는 데이터를 규율하므로 따져야 할 의무가 다릅니다.
• 각 라이선스 섹션의 attribution 의무(예: attribution, no-endorsement)와 짧은 설명, 정책 참조 링크.
• 문서 말미의 License Texts 섹션 — 프로젝트에 등장한 모든 라이선스의 전문 수록.
• 라이선스에 AI 특화 제약 플래그(행동 사용 또는 비상업)가 붙은 컴포넌트를 나열하는 License review needed 섹션 — AI 라이선스 검토 플래그 참고.

저작권 라인

각 컴포넌트 항목에는 스캔 SBOM에 기록된 저작권 문구가 표시됩니다(cdxgen이 패키지 메타데이터에서 읽어 옵니다). SBOM에 저작권자가 기록되지 않았으면 라인을 공란으로 두지 않고, 저작권자가 수록되지 않았다는 안내와 함께 컴포넌트의 레지스트리 URL을 대신 표시합니다 — 원 소스에서 저작권 문구를 확인할 수 있습니다. 컴포넌트 드로어의 수동 오버라이드는 로드맵에 있습니다.

라이선스 전문

문서는 프로젝트에 등장한 각 라이선스의 정식 전문을 담은 License Texts 섹션으로 끝납니다. 포털은 잘 알려진 56종 라이선스의 SPDX(Software Package Data Exchange) 전문을 번들로 포함합니다. MIT, Apache-2.0, BSD, GPL, LGPL, AGPL, MPL, EPL, CDDL 계열과 데이터셋·문서가 흔히 쓰는 Creative Commons 라이선스가 여기에 들어갑니다. 전문이 번들에 없는 라이선스는 조용히 누락되지 않고 정식 전문으로 연결되는 reference URL 링크로 대체됩니다. 이 섹션 덕분에 NOTICE 산출물 자체가 카탈로그의 license_text_inclusion_required 의무를 충족합니다 — 의무사항 카탈로그 참고.

지원 포맷

NOTICE 엔드포인트는 format 쿼리 값을 받습니다(기본 text).

포맷	쿼리 값 (format=)	MIME	확장자	사용 사례
일반 텍스트	text	text/plain	.txt	릴리스 tarball의 NOTICE 파일로 그대로 사용. 기본값.
Markdown	markdown	text/markdown	.md	문서 사이트나 PR 설명에 렌더링.
HTML	html	text/html	.html	attribution 페이지용 self-contained 문서(인라인 <style>, 스크립트 없음).

출력은 동일 스캔·동일 포맷에 대해 내보내기 간 byte-stable이며 릴리스 간 diff가 가능합니다.

다운로드

• UI: 프로젝트 → Obligations 탭 → 포맷 선택(text 또는 HTML) → Download NOTICE. 브라우저가 NOTICE-<project>.<ext>로 저장합니다. markdown 변형은 API에서 제공됩니다.

• API:

  # 일반 텍스트(기본)
  curl -sS -L -OJ \
    -H "Authorization: Bearer ${TRUSTEDOSS_API_KEY}" \
    "https://trustedoss.example.com/v1/projects/${PROJECT_ID}/notice?format=text&download=true"
  
  # HTML
  curl -sS -L -OJ \
    -H "Authorization: Bearer ${TRUSTEDOSS_API_KEY}" \
    "https://trustedoss.example.com/v1/projects/${PROJECT_ID}/notice?format=html&download=true"

  format 허용값: text, markdown, html. download=true를 전달하면 응답에 Content-Disposition: attachment가 설정되고 -OJ가 서버 제공 파일명(NOTICE-<project>.<ext>)으로 저장합니다. 생략하면 본문을 인라인으로 스트리밍합니다.

VEX 내보내기

CycloneDX SBOM은 모든 결과의 프로젝트 VEX 상태를 포함합니다. SPDX는 native VEX 표현이 없으므로 SPDX 내보내기는 결과별 상태를 생략합니다. 다운스트림 소비자가 기대하면 SPDX 내보내기와 별도 CycloneDX VEX 문서를 함께 제공하세요.

SBOM의 vulnerabilities[] 배열 각 항목은 CVE id, 출처 데이터베이스, VEX 분석, 그리고 같은 문서 안에서 영향받는 컴포넌트의 bom-ref를 가리키는 affects[].ref를 담습니다(소비자가 PURL을 파싱하지 않고도 결과와 컴포넌트를 연결할 수 있습니다).

VEX 상태는 CycloneDX analysis.state로 매핑되고, 분석가의 자유 텍스트 노트(있는 경우)는 analysis.detail에 담깁니다:

포털 상태	CycloneDX VEX state	analysis.detail
New	in_triage	(없음)
Analyzing	in_triage	분석가 노트
Exploitable	exploitable	분석가 노트
Not affected	not_affected	분석가 노트
False positive	false_positive	분석가 노트
Suppressed	not_affected	분석가 노트
Fixed	resolved	분석가 노트

닫힌 CycloneDX analysis.justification enum(code_not_present 등)은 절대 내보내지 않습니다. 이 enum의 항목은 자유 형식의 분석가 서술로는 추론할 수 없는 정밀한 의미를 가지므로, 노트는 analysis.detail에 유지됩니다.

정상 동작 확인

1. 다운로드된 SBOM이 검증기를 통과 — CycloneDX는 cyclonedx validate 실행:

   cyclonedx validate --input-file checkout-service.sbom.json

2. SPDX는 spdx-tools로 검증:

   pyspdxtools -i checkout-service.sbom.json

3. 같은 스캔을 다시 다운로드하면 byte 동일 파일 생성:

   sha256sum checkout-service.sbom.json checkout-service.sbom.json.again
   # → 동일 해시

트러블슈팅

성공한 스캔이 아직 없을 때의 빈 SBOM

프로젝트에 아직 성공한 스캔이 없는 경우에도 내보내기는 빈 components/packages 리스트를 가진 유효한 SBOM 문서(HTTP 200)를 반환합니다. 다운스트림 도구가 그대로 파싱할 수 있습니다.

/sbom?format=… 호출 시 422

쿼리 문자열이 API가 받지 않는 값을 사용했습니다. 위 표의 4가지 정식 쿼리 값 중 하나를 사용하세요 — 특히 SPDX Tag-Value 포맷의 값은 spdx-tv(이며 spdx-tag-value가 아닙니다).

접근 권한이 없는 프로젝트에서 404

SBOM·NOTICE 엔드포인트는 존재를 은폐합니다 — 프로젝트 소속 팀의 멤버가 아닌 호출자는 존재하지 않는 프로젝트 id와 동일하게 403이 아니라 404를 받습니다. 이는 의도된 동작입니다 — 403을 반환하는 project-detail 엔드포인트와 달리 SBOM·NOTICE 본문은 구조적 세부(컴포넌트 이름·버전)를 노출하므로, 비멤버에게는 프로젝트의 존재 자체를 확인해 주지 않습니다. 접근하려면 소속 팀에 합류하세요.

저작권 라인에 저작권자 대신 레지스트리 링크가 표시됨

스캔 SBOM에 해당 컴포넌트의 저작권자가 기록되지 않은 경우입니다 — cdxgen이 패키지 메타데이터에서 저작권 문구를 찾지 못했습니다. NOTICE는 라인을 공란으로 두지 않고 저작권자 미수록 안내와 함께 컴포넌트의 레지스트리 URL을 표시하므로, 상위 소스에서 저작권 문구를 직접 확인해 이행하세요. 컴포넌트 드로어의 수동 오버라이드는 로드맵에 있습니다. SPDX 내보내기는 별도 표면이며 여전히 copyrightText: NOASSERTION을 출력합니다.

컴플라이언스 증거 체인

외부 감사관이 포털 운영자에게 묻는 전형적인 다섯 가지 질문입니다. 오늘 답할 수 있는 것과 우회가 필요한 것을 정리한 표입니다.

감사관 질문	v0.10.0 답변 소스	한계
"릴리스 X 시점의 SBOM을 보여달라"	수동 아카이브; 포털은 최신본만 보존	과거 스캔 고정은 로드맵
"지난 분기에 누가 SBOM / NOTICE를 다운로드했나?"	structlog(Loki / journald) — audit_logs 아님	감사 행 승격은 로드맵
"프로젝트 X에서 GPL이 처음 탐지된 시점은?"	scans.create의 audit_logs + 스캔별 vulnerability_findings.create	가능 — 전체 증거 체인 보유
"2026 Q1의 모든 승인 결정을 보여달라"	component_approvals.update의 audit_logs + decision_note	가능 — 전체 증거 체인 보유
"감사 행이 변조되지 않았음을 증명하라"	append-only 트리거(마이그레이션 0012)	super-admin 우회 잔존 — 감사 로그 강화 검토 필요

공급사 제출 호환성

이 내보내기는 일반적인 기업 공급사 SBOM 요구사항(예: SK텔레콤 공급사 가이드)을 충족합니다: 표준 포맷/버전(CycloneDX, SPDX 2.3), ISO-8601 타임스탬프, 도구 메타데이터, 컴포넌트별 이름·버전·PURL, 라이선스, 그리고 전이적 의존성(스캔 대상 소스에 lockfile이 포함되거나 생성 가능할 때).

제출 전 유의할 두 가지:

• pkg:generic/ PURL은 일부 프로그램에서 반려됩니다. generic PURL은 스캐너가 컴포넌트의 생태계를 분류하지 못했다는 뜻입니다. cdxgen이 생태계별 타입을 부여하도록 lockfile / 빌드 산출물을 함께 제공하세요.
• SPDX 식별자가 없는 라이선스는 SPDX expression에서 NOASSERTION으로 나타납니다(CycloneDX license.name에는 라벨이 남습니다).

로드맵

매뉴얼이 이전에 약속했으나 v0.10.0에 포함되지 않은 항목.

• 취약점 보고서는 _이미 구현_되어 있습니다 — PDF로, v0.13.0부터는 Excel(.xlsx) 로도 제공됩니다. 취약점 → 보고서 다운로드 (PDF 또는 Excel)(GET /v1/projects/{id}/vulnerability-report.pdf / .xlsx) 참고. 아직 구현되지 않은 것은 독립형 컴포넌트 Excel 내보내기와 컴플라이언스 PDF이며 향후 릴리스에서 제공됩니다. 컴포넌트 표가 즉시 필요한 이해관계자는 SBOM(CycloneDX JSON)을 선호 도구로 소비하십시오.
• NOTICE 조립을 위한 컴포넌트 드로어의 수동 저작권 오버라이드 — 예정.
• SBOM·NOTICE 내보내기의 과거 스캔 고정 — 예정.
• SBOM / NOTICE 다운로드를 structlog 이벤트에서 audit_logs 행으로 승격 — 예정.

함께 보기

• SBOM 서명 검증 (cosign) — SBOM이 온전하며 이 배포에서 서명되었음을 증명
• 컴포넌트·라이선스
• 취약점
• API 개요