AI 모델 SBOM 가이드¶
HuggingFace 모델의 CycloneDX ML-BOM(머신러닝 SBOM)을 생성하고 결과를 읽는 방법입니다. 모델 id만 주면 BomLens가 모델 카드 메타데이터를 네트워크로 가져옵니다. 소스 코드도, 모델 가중치 다운로드도 필요 없습니다.
동작 방식¶
AI 모델의 "구성요소 명세"는 모델 카드입니다. 식별자, 아키텍처, 태스크, 라이선스, 공급자, 데이터셋, 파일 무결성 등이 담깁니다. BomLens는 OWASP AIBOM Generator로 HuggingFace 모델 카드를 읽어 모델과 참조 데이터셋 중심의 CycloneDX 1.7 ML-BOM을 만들고, G7 최소 요소 적합성 검사(권고)를 더합니다. 모델에는 패키지 의존성이 없으므로 보안(CVE) 보고서는 생성하지 않습니다.
전체 도구 흐름은 입력 형태별 파이프라인에 있습니다.
G7 체크리스트란¶
"G7 Software Bill of Materials for AI — Minimum Elements"는 2026년 5월 G7 차원에서 발행된 지침으로, 독일 BSI와 이탈리아 ACN이 주도했습니다. AI 모델의 SBOM이 갖춰야 할 최소 요소 50개를 7개 클러스터로 정의합니다. 누가 만든 모델인지, 무엇인지, 어떤 데이터로 학습했는지, 어떻게 보호되는지, 성능은 어떤지를 다룹니다. 법적 구속력이 있는 규정이 아니라 권고입니다.
그래도 규제와 무관하지 않습니다. EU 인공지능법(AI Act)의 고위험·투명성 의무가 2026년 8월 2일부터 적용되고, Annex IV가 요구하는 기술 문서는 G7 클러스터와 상당 부분 겹칩니다. BomLens가 어느 쪽의 준수를 보증하는 것은 아닙니다. 적합성 리포트가 주는 것은 가시성입니다. 모델 문서가 이미 다루는 요소와 사람이 채워야 할 요소를 항목별로 보여주므로, 준수 판정이 아니라 준비를 돕는 구체적인 방법이 됩니다.
BomLens는 50개 요소를 51개 검사로 보여줍니다. 모델 개방성(가중치, 아키텍처, 학습 데이터, 학습 과정의 공개 여부)은 G7 원문에서 Model license 요소의 한 측면이지만, 따로 볼 가치가 있어 별도 행으로 노출합니다.
| 클러스터 | 검사 수 | 그중 사람 검토 |
|---|---|---|
| 메타데이터 | 10 | 0 |
| 시스템 속성 | 9 | 4 |
| 모델 | 14 | 0 |
| 데이터셋 속성 | 10 | 5 |
| 인프라 | 2 | 0 |
| 보안 속성 | 4 | 3 |
| 핵심 성과 지표 | 2 | 1 |
13개 요소는 자동으로 확인할 출처가 없습니다. 의도된 적용 분야나 데이터셋 민감도처럼 모델 카드의 어떤 필드로도 증명할 수 없는 것들입니다. BomLens는 이를 추측하는 대신 사람 검토가 필요하다고 표시합니다.
이미지 준비¶
AI 모델 SBOM 생성에는 OWASP AIBOM Generator가 들어 있는 별도 이미지가 필요합니다. opt-in이고 네트워크(HuggingFace)에 접근하므로 기본 이미지가 아니라 별도 이미지로 제공합니다.
이 이미지가 AI 모델 스캔의 기본값이므로 --model만 붙여도 받습니다. 다른 태그를 쓰려면 환경변수 SBOM_AIBOM_IMAGE로 지정합니다.
실행하기¶
웹 UI에서¶
aibom 이미지로 UI를 실행하면 AI 모델 타일이 활성화됩니다. 그 뒤 모델 id를 입력하고 스캔합니다.
SBOM_SCANNER_IMAGE=ghcr.io/sktelecom/bomlens-aibom:latest ./scripts/scan-sbom.sh --ui
# Windows: sbom-ui.bat 더블클릭 전에 SBOM_SCANNER_IMAGE를 지정
새 스캔의 소스 타일에서 AI 모델을 고르고, HuggingFace 모델 id를 org/model 형식으로 입력한 뒤(예: google-bert/bert-base-uncased, Qwen/Qwen2.5-0.5B — 컬렉션 이름이나 전체 URL이 아닌) 스캔을 실행합니다.
CLI에서¶
모델 id를 --model에 넘깁니다.
./scripts/scan-sbom.sh --project bert-base --version 1.0.0 \
--model "google-bert/bert-base-uncased" --generate-only
--model은 --target, --analyze, --git, --merge와 함께 쓸 수 없습니다. bomlens-aibom 이미지를 자동으로 받고, 고지문과 위험 보고서를 만들며, 보안 보고서는 건너뜁니다(모델에는 패키지 CVE가 없음).
결과 읽기¶
웹 UI에서 AI/ML SBOM은 좌측 레일에 두 섹션을 추가합니다.
모델·데이터셋 — 각 모델 카드의 식별자, 아키텍처, 태스크, 라이선스, 공급자, 무결성과 공개 4축 패널(가중치 / 아키텍처 / 학습 데이터 / 학습 과정 — 모델 카드에 문서화된 범위), 그리고 모델이 참조하는 데이터셋입니다.
적합성 — AI 모델 SBOM에서는 이 섹션에 G7 최소 요소 검사(모두 권고)가 기본 형식 적합성 검사와 함께 더해지고, G7 7개 클러스터별로 묶입니다. 각 항목은 무엇인지와 어떻게 충족하는지를 안내합니다. 숫자와 배지가 뜻하는 바는 다음 절에서 설명합니다.
같은 데이터는 산출물에도 있습니다. ML-BOM(_bom.json, CycloneDX 1.7)과 적합성 보고서(_conformance.*)입니다.
적합성 리포트 읽는 법¶
G7 블록의 머리에는 "N / 38 충족" 같은 수치가 옵니다. 분모는 자동 출처가 있는 검사만 셉니다. 51개 중 38개이므로, 이 숫자는 도구가 스스로 확인할 수 있었던 범위를 말합니다. 사람 검토 전용 13개는 그 옆에 "검토 필요" 건수로 따로 표시되고, 자동 검사 중 채워지지 않은 것은 권고 건수로 잡힙니다.
각 검사의 상태는 세 가지입니다. 충족(pass)은 해당 요소가 ML-BOM에 있다는 뜻입니다. 권고(warn)는 없거나 확인하지 못했다는 뜻이고, 검토 전용 13개 요소는 항상 이 상태로 사람 검토가 필요하다는 표시와 함께 나타납니다. 실패(fail)는 G7 검사에서는 사실상 나오지 않습니다. G7 요소는 전부 권고라서 하나가 비어도 SBOM 전체 판정을 실패로 만들지 않으며, 전체 실패 판정은 기본 형식 검사(필수 CycloneDX 검사)에서만 나옵니다.
각 행의 출처 배지는 충족된 값이 어디서 오는지를 말합니다.
- 자동 확인(20건) — ML-BOM 필드에서 직접 읽습니다.
- 신호 추정(14건) — 전용 필드 하나가 아니라 BOM 안의 신호로 도출합니다.
- 선언 필요(4건) — 사람이나 매니페스트가 값을 제공했을 때만 채워집니다.
- 검토 필요(13건) — 자동 출처가 없어 사람이 직접 확인해야 합니다.
같은 결과가 세 가지 형식으로 나옵니다. 기계용 {Project}_{Version}_conformance.json(CI 게이트, 비교용), 표 형태의 _conformance.md, 시각화한 _conformance.html입니다.
한계¶
- 결과는 HuggingFace 모델 카드만큼만 충실합니다. 카드가 빈약하면 ML-BOM도 빈약하고, G7 검사도 카드에 문서화된 범위를 반영할 뿐 모델 자체를 감사하지는 않습니다. 리포트 생성은 도구의 몫이고, 해석과 검토 전용 13개 요소를 채우는 일은 사람의 몫입니다.
- 적합성 리포트는 EU 인공지능법을 비롯한 어떤 규제의 준수도 인증하지 않습니다. 문서화 공백을 드러내 사람이 메울 수 있게 할 뿐입니다.
- 메타데이터를 네트워크로 가져오므로, 비공개·게이트 모델은 접근 권한(환경의 HuggingFace 토큰)이 필요하며 오프라인 사용은 지원하지 않습니다.
- 모델 id는
org/model형식이어야 합니다. 컬렉션 이름이나 전체 URL은 해석되지 않습니다.
관련 문서: 입력 형태별 파이프라인 | 웹 UI 레퍼런스 | CLI 레퍼런스