입력 시나리오별 처리 가이드¶

개요¶

여러 팀에서 산출물을 소스, ZIP, 기존 SBOM, 펌웨어 등 서로 다른 형태로 받습니다. 이 가이드는 6가지 입력 형태마다 동일한 3종 산출물을 발행하는 방법을 정리합니다. (AI 모델은 약간 다릅니다. ML-BOM이고 보안 보고서가 없습니다. 시나리오 6 참고.)

3종 산출물

산출물	파일	의미
오픈소스 고지문	`{Project}_{Version}_NOTICE.{txt,html}`	라이선스 의무 이행을 위한 고지문
SBOM	`{Project}_{Version}_bom.json`	CycloneDX 1.6 구성요소 명세
오픈소스위험분석보고서	`{Project}_{Version}_risk-report.{md,html}`	라이선스+취약점 위험 집계(대응 기한 포함)

어떤 입력 형태든 --all --generate-only를 붙이면 위 3종이 한 번에 생성됩니다(위험분석보고서는 기본 생성이며 --no-report로만 끕니다).

공통 준비¶

Windows 사용자: 아래 명령은 macOS/Linux 기준입니다. 다음 중 하나를 고르세요. 설치는 시작하기를 참고하세요.

./scripts/scan-sbom.sh를 scripts\scan-sbom.bat로 바꿔 실행합니다 (Git Bash 필요).

WSL2에서는 명령을 그대로 실행합니다.

CLI 없이 쓰려면 scripts\sbom-ui.bat을 더블클릭합니다.

# Docker 20.10+ 필요. 스캐너 이미지 1회 받기(또는 직접 빌드).
docker pull ghcr.io/sktelecom/bomlens:latest   # 이전 이름 sbom-scanner 도 같은 이미지

# 편의를 위해 스크립트 경로를 변수로 둡니다.
SBOM=/path/to/sbom-tools/scripts/scan-sbom.sh

한눈에 보기¶

아래 모든 명령의 $SBOM은 공통 준비에서 정의한 스크립트 경로 변수입니다. 그 단계를 건너뛰었다면 $SBOM 자리에 scan-sbom.sh의 전체 경로를 그대로 넣으면 됩니다.

입력 형태	모드	핵심 명령(요약)	산출물
GitHub URL	SOURCE	`$SBOM --git <url> --all --generate-only`	고지문, SBOM, 위험분석보고서
소스 ZIP	SOURCE	`$SBOM --target app.zip --all --generate-only`	〃
로컬 디렉터리(C/C++)	SOURCE	`cd dir && $SBOM --all --generate-only`	〃
기존 SBOM JSON	ANALYZE	`$SBOM --analyze sbom.json --generate-only`	〃 + 적합성 보고서
펌웨어 `.bin`	FIRMWARE	`$SBOM --target dev.bin --firmware --all --generate-only`	〃
AI 모델(HuggingFace)	AIBOM	`$SBOM --model owner/name --generate-only`	고지문, ML-BOM(1.7), 위험분석보고서(보안 없음)

모든 명령에 --project <이름> --version <버전>이 필요합니다(아래 예시 참고).

패키지 매니저(Conan/vcpkg)가 없는 C/C++ 소스라면 --identify-vendored를 추가하세요. 소스 트리에 통째로 복사된 오픈소스를 이름 있는 구성요소로 탐지합니다. 이 경우 강력히 권장하며, 자세한 내용은 시나리오 3을 참고하세요.

시나리오 1 — GitHub URL¶

개발1팀이 GitHub 저장소 정보를 전달한 경우. 수동 git clone 없이 URL을 그대로 전달합니다. ($SBOM은 공통 준비에서 정의했습니다.)

$SBOM --project team1-app --version 1.0.0 \
  --git "https://github.com/sktelecom/sbom-tools" \
  --all --generate-only

특정 브랜치/태그: --branch v1.2.3
비공개 저장소: GIT_TOKEN=ghp_xxx $SBOM ... --git https://github.com/org/private ... (토큰은 로그에 남지 않음)
얕은 클론(--depth 1)으로 임시 디렉터리에 받은 뒤 분석하고, 산출물만 현재 디렉터리 아래 {Project}_{Version}/ 하위 폴더에 남깁니다.

산출물: team1-app_1.0.0_NOTICE.{txt,html}, team1-app_1.0.0_bom.json, team1-app_1.0.0_risk-report.{md,html}

시나리오 2 — 소스 ZIP¶

개발2팀이 소스 코드를 ZIP으로 전달한 경우. 수동 해제 없이 아카이브를 그대로 전달합니다.

$SBOM --project team2-app --version 1.0.0 \
  --target "./team2-app.zip" \
  --all --generate-only

지원 형식: .zip, .tar.gz, .tgz, .tar.bz2, .tar.xz, .tar
zip-slip(경로 탈출) 검사 후 임시 디렉터리에 해제하며, 최상위 폴더가 하나면 자동으로 그 안으로 진입합니다.

산출물: 고지문, SBOM, 위험분석보고서 (3종)

시나리오 3 — 로컬 C/C++ 소스 디렉터리¶

개발3팀이 공유 폴더로 전달해 로컬(~/project/c-dev)에 복사한 경우. 디렉터리 안에서 실행합니다.

cd ~/project/c-dev
$SBOM --project team3-dev --version 1.0.0 --all --deep-license --generate-only

C/C++ 안내

패키지 매니저가 있으면(Conan conanfile.txt / vcpkg vcpkg.json) 의존성이 해석되어 SBOM에 반영됩니다.
순수 CMake/Make 소스는 매니저 메타데이터가 없어 SBOM이 희소할 수 있습니다. 이때는 --deep-license로 1st-party 소스의 라이선스 헤더를 보강하고, 빌드 산출물(설치된 라이브러리가 있는 staging/rootfs)은 별도로 $SBOM --target <build-dir> --all --generate-only(syft)로 분석합니다. OS rootfs와 애플리케이션, 정적 링크 의존성을 층별로 나눠 만드는 서버 SBOM 전체 흐름은 서버 SBOM 작성 가이드를 참고하세요. 웹 UI에서는 --deep-license가 고급 스캔 옵션의 라이선스 스캔 (ScanCode) 토글에 대응합니다. 선언된 의존성이 아니라 내 소스 파일(/src)을 스캔하며 느리므로, 파일 단위 라이선스 탐지가 필요할 때만 켜세요.
패키지 매니저 없이(순수 Make/CMake) 오픈소스를 소스 트리에 통째로 복사(vendored)해 쓰는 경우 — 임베디드와 펌웨어 소스에서 흔합니다 — --identify-vendored를 강력히 권장합니다. 이 옵션이 없으면 SBOM이 희소해 내장 라이브러리를 놓치고, 켜면 이들을 CPE가 붙은 이름 있는 구성요소로 탐지해 위험분석보고서가 CVE를 연결할 수 있습니다. 내장 오픈소스 식별을 참고하세요. BomLens는 이 상황을 감지하면 자동으로 이 옵션을 안내하기도 합니다.
패키지 매니저가 없어도 위험분석보고서는 생성되며, 탐지된 구성요소의 라이선스와 취약점을 집계합니다.

산출물: 고지문, SBOM, 위험분석보고서 (3종)

시나리오 4 — 기존 SBOM JSON¶

개발4팀이 SBOM(JSON)을 전달한 경우. 소스가 없어도 검증하고 분석합니다.

$SBOM --project team4-proj --version 2.0.0 \
  --analyze "./team4-sbom.json" \
  --generate-only

CycloneDX와 SPDX(JSON/Tag-Value) 모두 입력 가능하며 내부에서 CycloneDX로 변환합니다.
--analyze는 고지문과 보안을 자동으로 켜므로 --all을 따로 붙일 필요가 없습니다.
추가로 포맷 적합성 보고서(_conformance.{json,md,html})가 생성됩니다. 받은 SBOM이 필수 항목(이름, 버전, 식별자 등)을 갖췄는지 점검한 결과이며, 위험분석보고서 1절에도 요약이 들어갑니다. 받은 SBOM을 검증하고 공급사에 보완을 요청하는 흐름은 공급사 SBOM 검증을 참고하세요.

산출물: 고지문, SBOM(변환본), 위험분석보고서, 적합성 보고서

시나리오 5 — 펌웨어 바이너리¶

개발5팀이 빌드된 펌웨어(dev.bin)를 전달한 경우. 언패킹 후 구성요소를 식별합니다.

$SBOM --project team5-fw --version 1.0.0 \
  --target "./dev.bin" --firmware \
  --all --generate-only

펌웨어 분석은 GPL 도구(unblob/cve-bin-tool 등)를 포함하는 opt-in 펌웨어 이미지가 필요합니다. 환경변수 SBOM_FIRMWARE_IMAGE로 지정하거나, 기본값(ghcr.io/sktelecom/bomlens-firmware:latest)을 받습니다.
인식 가능한 확장자(.bin/.img/.squashfs/.ubi/...)는 --firmware 없이도 자동 감지되지만, 명시를 권장합니다.
자세한 동작과 한계는 펌웨어 분석을 참고하세요.

산출물: 고지문, SBOM, 위험분석보고서 (3종)

시나리오 6 — AI 모델(HuggingFace)¶

개발팀이 코드 대신 HuggingFace 모델을 가리킨 경우. 모델 id만으로 ML-BOM을 생성합니다. 소스 코드도, 모델 가중치 다운로드도 필요 없습니다.

$SBOM --project bert-base --version 1.0.0 \
  --model "google-bert/bert-base-uncased" \
  --generate-only

opt-in aibom 이미지(ghcr.io/sktelecom/bomlens-aibom:latest)가 필요하며 자동으로 받습니다. 다른 태그는 SBOM_AIBOM_IMAGE로 지정합니다.
--model은 --target/--analyze/--git/--merge와 함께 쓸 수 없습니다.
CycloneDX 1.7 ML-BOM(1.6 아님), 고지문, 위험분석보고서와 G7 최소 요소 적합성 검사를 만듭니다. 보안 보고서는 없습니다. 모델에는 패키지 CVE가 없습니다.
모델 카드, 데이터셋, G7 세부는 AI 모델 가이드를 참고하세요.

산출물: 고지문, ML-BOM(CycloneDX 1.7), 위험분석보고서, G7 적합성

산출물 3종 해석¶

고지문(NOTICE): 라이선스별로 구성요소를 묶어 표기합니다. 배포할 때 동봉하거나 고지하는 의무를 이행하는 데 씁니다.
SBOM: CycloneDX 1.6. 취약점 관리 시스템에 올릴 때 기준이 되는 산출물입니다.
오픈소스위험분석보고서: 취약점을 심각도별로 집계하고 권고 대응 기한(Critical 7일, High 30일)을 명시합니다. 라이선스 요약도 담고 있으며, 공급사 SBOM을 분석한 경우에는 포맷 적합성 결과가 더해집니다.

웹 UI로 한 번에¶

CLI에 익숙하지 않다면 웹 UI를 사용합니다.

$SBOM --ui   # 브라우저에서 http://localhost:8080

UI 상단에서 스캔 대상을 고르고 각 형태에 맞게 입력합니다.

스캔 대상	입력 방법
현재 폴더	UI를 실행한 폴더의 소스를 스캔
GitHub URL	URL 입력
ZIP 업로드	`.zip`/tar 파일 업로드
SBOM 업로드	기존 SBOM(JSON) 업로드, 분석(ANALYZE) 모드
펌웨어 업로드	`.bin` 등 업로드(펌웨어 이미지에서 UI 실행 필요)
Docker 이미지	이미지명 입력
AI 모델	HuggingFace 모델 id 입력(aibom 이미지에서 UI 실행 필요)

소스 코드 스캔(현재 폴더, GitHub URL, ZIP 업로드)에서는 고급 스캔 옵션 섹션에서 어떤 파일을 만들지가 아니라 소스를 어떻게 분석할지를 바꾸는 토글을 제공합니다.

라이선스 스캔 (ScanCode) — CLI --deep-license에 대응합니다. 내 소스 파일을 훑어 파일 단위 라이선스 텍스트·헤더(1st-party)를 탐지합니다. 선언된 의존성을 내려받거나 스캔하지는 않습니다.
파일 단위 식별 (SCANOSS) — 소스 트리에 통째로 복사된 제3자 오픈소스(주로 C/C++)를 찾습니다. 내장 오픈소스 식별을 참고하세요.

둘 다 느리고 기본은 꺼져 있으니 필요할 때만 켜세요. ScanCode는 --build-arg SBOM_DEEP_LICENSE=true로 빌드한 이미지에서만 쓸 수 있습니다. 토글 전체 목록과 스캔 대상별 제공 여부는 웹 UI 레퍼런스를 참고하세요.

실행하면 진행 로그가 실시간으로 표시되고, 완료 후에는 고지문과 SBOM, 위험분석보고서(필요하면 적합성 보고서까지)를 화면에서 보거나 내려받을 수 있습니다. 적합성 결과(적합/부적합)는 상단 카드로 표시됩니다.

펌웨어 업로드 탭은 펌웨어 도구가 포함된 이미지에서 UI를 실행할 때만 활성화됩니다: SBOM_SCANNER_IMAGE=ghcr.io/sktelecom/bomlens-firmware:latest $SBOM --ui

트러블슈팅 / 한계¶

GitHub URL: 비공개 저장소는 GIT_TOKEN이 필요합니다. 허용되지 않은 URL 형식(셸 메타문자, .., 공백)은 보안상 거부됩니다.
ZIP/tar: 경로 탈출(zip-slip)이 포함된 아카이브는 거부됩니다. Windows Git Bash에 unzip이 없으면 tar로 처리됩니다.
C/C++: 패키지 매니저가 없는 순수 소스는 SBOM이 희소합니다(시나리오 3 참고).
펌웨어: 정적 링크 라이브러리와 벤더 변형 squashfs는 탐지율이 제한적입니다(펌웨어 분석 §한계).
SBOM 분석: SPDX를 CycloneDX로 변환할 때 일부 라이선스 표현이 단순화될 수 있습니다.

관련 문서: 시작하기 | CLI 레퍼런스 | 고지문·보안 보고서 가이드