diff --git a/docs/concepts/architecture.ko.md b/docs/concepts/architecture.ko.md index 38c4a67d..e8061dfb 100644 --- a/docs/concepts/architecture.ko.md +++ b/docs/concepts/architecture.ko.md @@ -189,7 +189,7 @@ sequenceDiagram 이미지 안에서의 두 단계: -1. **`build-prep.sh`** (`docker/lib/build-prep.sh`) — cdxgen **직전** 의존성 보강. cdxgen이 자동 해석하지 못하는 생태계(특히 Rust·Go)의 lockfile을 만들어 전이 의존성까지 노출시킵니다. POSIX `sh`, best-effort(스캔을 절대 실패시키지 않음). +1. **`build-prep.sh`** (`docker/lib/build-prep.sh`) — cdxgen **직전** 의존성 보강. cdxgen이 자동 해석하지 못하는 생태계(특히 Rust·Go)의 lockfile을 만들어 전이 의존성까지 노출시킵니다. POSIX `sh`, 실패해도 스캔을 중단시키지 않습니다. | 생태계 | 동작 | 비고 | |--------|------|------| @@ -363,14 +363,14 @@ CLI 플래그가 어떤 환경변수로 변환되어 어느 단계를 켜는지 - **책임 분리** — 생성(Stage 1)과 후처리(Stage 2)를 분리해 후처리 이미지를 경량화. - **재현성** — 도구 버전을 `ARG`로 고정, `--byte-stable`로 바이트 동일 출력. - **표준 준수** — CycloneDX 1.6 스펙 준수. -- **견고성** — 후처리 단계는 best-effort로 전체 스캔을 쉽게 중단시키지 않음. +- **견고성** — 후처리 단계는 실패해도 전체 스캔을 중단시키지 않음. - **단일 인터페이스** — 모든 언어·모드를 `scan-sbom.sh` 하나로 호출. --- ## 역할 분담 (TRUSCA) -BomLens는 **생성(generation)** 전문 도구입니다. 전사(全社) 프로젝트 관리·취약점 triage·라이선스 정책 게이트 같은 **거버넌스**는 자매 프로젝트 [TRUSCA](https://github.com/trustedoss/trusca)(구 TrustedOSS Portal)에 위임합니다. 두 도구 모두 cdxgen/Trivy를 공유하므로 산출물(CycloneDX)이 그대로 호환됩니다. +BomLens는 **생성(generation)** 전문 도구입니다. 전사(全社) 프로젝트 관리, 취약점 분류, 라이선스 정책 게이트 같은 **거버넌스**는 자매 프로젝트 [TRUSCA](https://github.com/trustedoss/trusca)(구 TrustedOSS Portal)에 위임합니다. 두 도구 모두 cdxgen/Trivy를 공유하므로 산출물(CycloneDX)이 그대로 호환됩니다. ```mermaid flowchart TB diff --git a/docs/concepts/local-first.ko.md b/docs/concepts/local-first.ko.md index 63c62941..b18c2ddf 100644 --- a/docs/concepts/local-first.ko.md +++ b/docs/concepts/local-first.ko.md @@ -22,7 +22,7 @@ BomLens는 폐쇄망과 오프라인 환경에서 동작합니다. 외부 조회 ## 생성은 BomLens, 거버넌스는 TRUSCA -BomLens는 생성에 집중합니다. 전사 프로젝트 관리, 취약점 triage, 라이선스 정책 게이트 같은 거버넌스는 자매 프로젝트 TRUSCA(구 TrustedOSS Portal, )에 위임합니다. 두 도구는 CycloneDX 산출물을 그대로 주고받습니다. +BomLens는 생성에 집중합니다. 전사 프로젝트 관리, 취약점 분류, 라이선스 정책 게이트 같은 거버넌스는 자매 프로젝트 TRUSCA(구 TrustedOSS Portal, )에 위임합니다. 두 도구는 CycloneDX 산출물을 그대로 주고받습니다. ## 관련 문서 diff --git a/docs/concepts/pipeline-by-input.ko.md b/docs/concepts/pipeline-by-input.ko.md index 143a92b5..647bd33d 100644 --- a/docs/concepts/pipeline-by-input.ko.md +++ b/docs/concepts/pipeline-by-input.ko.md @@ -54,7 +54,7 @@ flowchart TD ## 펌웨어 -네트워크 장비 펌웨어 이미지(`.bin`, `.img.gz`, squashfs 등)이며, opt-in `bomlens-firmware` 이미지가 담당합니다. 펌웨어는 운영체제와 라이브러리 수십 개를 한 파일에 밀봉하므로, 먼저 압축을 풀고 두 가지로 구성요소를 식별합니다. 패키지 매니저 메타데이터는 syft로, strip된 정적 바이너리는 [cve-bin-tool](https://github.com/intel/cve-bin-tool)로 식별하며 cve-bin-tool은 CVE도 함께 매칭합니다. 두 결과를 병합한 뒤, 잘 알려진 OSS(busybox, dropbear, dnsmasq 등)에 대해 CPE/SPDX를 채우는 보강 단계를 거쳐 Trivy와 고지문이 이를 쓸 수 있게 합니다. +네트워크 장비 펌웨어 이미지(`.bin`, `.img.gz`, squashfs 등)이며, opt-in `bomlens-firmware` 이미지가 담당합니다. 펌웨어는 운영체제와 라이브러리 수십 개를 한 파일에 밀봉하므로, 먼저 압축을 풀고 두 가지로 구성요소를 식별합니다. 패키지 매니저 메타데이터는 syft로, strip된 정적 바이너리는 [cve-bin-tool](https://github.com/intel/cve-bin-tool)로 식별하며 cve-bin-tool은 CVE도 함께 매칭합니다. 두 결과를 병합한 뒤, 잘 알려진 OSS(busybox, dropbear, dnsmasq 등)의 CPE/SPDX를 채우는 보강 단계를 거치고, 그 결과를 Trivy와 고지문 생성이 이어받아 활용합니다. 언팩은 먼저 성공한 도구를 쓰는 순서로 시도합니다. [unblob](https://github.com/onekey-sec/unblob)(기본), [BANG](https://github.com/armijnhemel/binaryanalysis-ng), 표준 squashfs용 `unsquashfs`, 그다음 `binwalk`입니다. @@ -114,7 +114,7 @@ flowchart TD ## 공통 후처리 -어떤 입력이든 SBOM은 같은 순서의 단계를 거칩니다. 정규화는 이후 모든 단계의 입력을 안정시키므로 가장 먼저 돌고, 서명은 최종 SBOM을 대상으로 해야 하므로 마지막에 돕니다. 점선 단계는 선택이거나 입력별입니다. 각 단계는 best-effort라, 실패하면 전체 스캔을 중단하지 않고 경고와 함께 건너뜁니다(서명과 업로드는 예외). +어떤 입력이든 SBOM은 같은 순서의 단계를 거칩니다. 정규화는 이후 모든 단계의 입력을 안정시키므로 가장 먼저 돌고, 서명은 최종 SBOM을 대상으로 해야 하므로 마지막에 돕니다. 점선 단계는 선택이거나 입력별입니다. 각 단계는 실패하더라도 전체 스캔을 중단하지 않고 경고와 함께 건너뜁니다(서명과 업로드는 예외). ```mermaid flowchart TD diff --git a/docs/concepts/reports-explained.ko.md b/docs/concepts/reports-explained.ko.md index af711f34..626b315a 100644 --- a/docs/concepts/reports-explained.ko.md +++ b/docs/concepts/reports-explained.ko.md @@ -32,7 +32,7 @@ BomLens는 각 컴포넌트의 릴리스 주기가 상위(upstream) 지원 종 - 날짜는 스캐너 이미지에 번들한 endoflife.date 스냅샷에서 가져옵니다. 그래서 이 점검은 네트워크 호출 없이 오프라인으로 동작하며 폐쇄망에서도 쓸 수 있습니다. 출처와 스냅샷 날짜는 표시된 각 컴포넌트에 기록됩니다(`bomlens:eol:source`). - 커버리지는 endoflife.date를 따릅니다. endoflife.date는 런타임, 주요 프레임워크, 운영체제, 데이터베이스를 다룹니다(spring-boot, express, django, nodejs, python, php, nginx, openssl, ubuntu, debian 등). 규모가 작은 라이브러리 다수는 대상이 아니며, 매핑이 없는 컴포넌트는 추측하지 않고 미표기(unknown)로 둡니다. -- 웹 UI에서는 개요(Overview)에 "지원 종료" 개수 타일이 나오고, 그중 취약점도 있는 컴포넌트는 위험색으로 강조됩니다. 지원 종료 컴포넌트는 자신의 CVE에 대한 상위 패치가 없으므로 실제로 대응해야 할 대상입니다. 컴포넌트 표에는 "지원 종료" 뱃지(가능하면 종료 날짜 포함)와 "지원 종료" 필터가 더해집니다. +- 웹 UI에서는 개요(Overview)에 "지원 종료" 개수 타일이 나오고, 그중 취약점도 있는 컴포넌트는 위험색으로 강조됩니다. 지원 종료 컴포넌트는 자신의 CVE에 대한 상위 패치가 없으므로 실제로 대응해야 할 대상입니다. 컴포넌트 표에는 "지원 종료" 배지(가능하면 종료 날짜 포함)와 "지원 종료" 필터가 더해집니다. - 오프라인이라 지연이 없어 기본으로 켜져 있습니다. 끄려면 `ENRICH_EOL=false`로 설정합니다. AI/ML 모델 스캔은 런타임이나 프레임워크 컴포넌트가 없어 이 단계를 건너뜁니다. ## 버전 최신성 @@ -58,7 +58,7 @@ BomLens는 각 컴포넌트의 릴리스 주기가 상위(upstream) 지원 종 crit=$(jq '[.Results[]?.Vulnerabilities[]? | select(.Severity=="CRITICAL")] | length' *_security.json) [ "$crit" -gt 0 ] && { echo "Critical 취약점 ${crit}건"; exit 1; } ``` -- 오탐(실제 영향 없음) 판단, 예외 승인, 이력 관리 같은 triage는 BomLens의 범위를 넘습니다. 취약점 관리 시스템(Dependency-Track, TRUSCA 등)에 SBOM을 업로드해 처리하세요. +- 오탐(실제 영향 없음) 판단, 예외 승인, 이력 관리 같은 취약점 분류 업무는 BomLens의 범위를 넘습니다. 취약점 관리 시스템(Dependency-Track, TRUSCA 등)에 SBOM을 업로드해 처리하세요. ## 오픈소스위험분석보고서 diff --git a/docs/concepts/what-is-sbom.ko.md b/docs/concepts/what-is-sbom.ko.md index 13ef2862..f8afab13 100644 --- a/docs/concepts/what-is-sbom.ko.md +++ b/docs/concepts/what-is-sbom.ko.md @@ -4,7 +4,7 @@ description: SBOM(Software Bill of Materials)이 무엇인지, 오픈소스 고 # SBOM이란 -SBOM(Software Bill of Materials)은 소프트웨어 안에 든 구성요소의 목록입니다. 함께 배포되는 모든 오픈소스 라이브러리와 패키지를 이름, 버전, 라이선스와 함께 정리한 것입니다. 포장 식품의 성분표가 제품을 뜯지 않고도 안에 뭐가 들었는지 알려주듯, SBOM은 소프트웨어에 대해 같은 역할을 합니다. +SBOM(Software Bill of Materials)은 소프트웨어 안에 든 구성요소의 목록입니다. 함께 배포되는 모든 오픈소스 라이브러리와 패키지를 이름, 버전, 라이선스와 함께 정리한 것입니다. 포장 식품의 성분표가 제품을 뜯지 않고도 안에 뭐가 들었는지 알려주듯, SBOM이 소프트웨어에서 같은 역할을 합니다. 오늘날 소프트웨어 대부분은 오픈소스를 조립해 만들어집니다. 보통의 웹 애플리케이션이 직접 선언하는 패키지는 수십 개지만, 그것들이 다시 수백 개를 끌어옵니다. 이 목록을 사람이 외울 수는 없으므로 도구가 프로젝트에서 생성합니다. BomLens가 하는 일이 그것입니다. diff --git a/docs/contribute/package-managers.ko.md b/docs/contribute/package-managers.ko.md index f5814fb7..e990e6d7 100644 --- a/docs/contribute/package-managers.ko.md +++ b/docs/contribute/package-managers.ko.md @@ -28,11 +28,11 @@ newlang) echo "ghcr.io/cyclonedx/cdxgen-debian-newlang:$CDXGEN_TAG" ;; ### 2. 의존성 보강이 필요하면 build-prep.sh 수정 -cdxgen이 잠금 파일 없이 전이 의존성을 해석하지 못하는 생태계라면, cdxgen 실행 직전에 잠금 파일을 만들어 주는 `docker/lib/build-prep.sh`에 보강 로직을 추가합니다. Rust(`cargo generate-lockfile`)와 Go(`go mod download`)가 선례입니다. 보강은 best-effort로 작성해 스캔을 실패시키지 않아야 합니다. +cdxgen이 잠금 파일 없이 전이 의존성을 해석하지 못하는 생태계라면, cdxgen 실행 직전에 잠금 파일을 만들어 주는 `docker/lib/build-prep.sh`에 보강 로직을 추가합니다. Rust(`cargo generate-lockfile`)와 Go(`go mod download`)가 선례입니다. 보강은 실패하더라도 스캔을 중단시키지 않도록 작성해야 합니다. ### 3. 예제 프로젝트 추가 -`examples/` 디렉토리에 예제 프로젝트를 추가합니다. +`examples/` 디렉터리에 예제 프로젝트를 추가합니다. ``` examples/kotlin/ diff --git a/docs/contribute/testing.ko.md b/docs/contribute/testing.ko.md index ecc68334..06f9d381 100644 --- a/docs/contribute/testing.ko.md +++ b/docs/contribute/testing.ko.md @@ -184,7 +184,7 @@ DEBUG_MODE=true ./tests/cases/test-nodejs.sh ### 테스트 실패 시 대응 절차 1. `DEBUG_MODE=true` 로 재실행하여 상세 로그를 확인합니다. -2. 실패한 언어의 예제 디렉토리에서 `scan-sbom.sh`를 직접 실행합니다. +2. 실패한 언어의 예제 디렉터리에서 `scan-sbom.sh`를 직접 실행합니다. 3. Docker 이미지를 최신 버전으로 업데이트합니다: `docker pull ghcr.io/sktelecom/bomlens:latest` 4. 해결되지 않으면 [GitHub Issues](https://github.com/sktelecom/bomlens/issues)에 환경 정보와 로그를 첨부해 리포트해 주세요. diff --git a/docs/guides/ai-model.ko.md b/docs/guides/ai-model.ko.md index 8a9dc943..de532656 100644 --- a/docs/guides/ai-model.ko.md +++ b/docs/guides/ai-model.ko.md @@ -16,7 +16,7 @@ AI 모델의 "구성요소 명세"는 모델 카드입니다. 식별자, 아키 "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가 어느 쪽의 준수를 보증하는 것은 아닙니다. 적합성 리포트가 주는 것은 가시성입니다. 모델 문서가 이미 다루는 요소와 사람이 채워야 할 요소를 항목별로 보여주므로, 준수 판정이 아니라 준비를 돕는 구체적인 방법이 됩니다. +그래도 규제와 무관하지 않습니다. EU 인공지능법(AI Act)의 고위험·투명성 의무가 2026년 8월 2일부터 적용되고, Annex IV가 요구하는 기술 문서는 G7 클러스터와 상당 부분 겹칩니다. BomLens가 어느 쪽의 준수를 보증하는 것은 아닙니다. 적합성 보고서가 주는 것은 가시성입니다. 모델 문서가 이미 다루는 요소와 사람이 채워야 할 요소를 항목별로 보여주므로, 준수 판정이 아니라 준비를 돕는 구체적인 방법이 됩니다. BomLens는 50개 요소를 51개 검사로 보여줍니다. 모델 개방성(가중치, 아키텍처, 학습 데이터, 학습 과정의 공개 여부)은 G7 원문에서 Model license 요소의 한 측면이지만, 따로 볼 가치가 있어 별도 행으로 노출합니다. @@ -34,7 +34,7 @@ BomLens는 50개 요소를 51개 검사로 보여줍니다. 모델 개방성(가 ## 규제 크로스워크 -적합성 리포트는 규제와 대응되는 G7 요소마다 그 요소가 어느 문서화 의무와 닿는지를 연결해 줍니다. 검토자가 던지는 질문에 답하기 위한 것입니다. 어떤 요소가 비어 있을 때, 그 공백이 어느 규제 요구와 관련되는가? 현재 두 가지 규제를 매핑합니다. +적합성 보고서는 규제와 대응되는 G7 요소마다 그 요소가 어느 문서화 의무와 닿는지를 연결해 줍니다. 검토자가 던지는 질문에 답하기 위한 것입니다. 어떤 요소가 비어 있을 때, 그 공백이 어느 규제 요구와 관련되는가? 현재 두 가지 규제를 매핑합니다. - EU 인공지능법(AI Act) — Annex IV 기술문서 항목(Regulation (EU) 2024/1689, Article 11(1)). - AI 기본법(한국) — 투명성(제31조), 안전성과 위험관리(제32조), 고영향 인공지능(제33·34조), 영향평가(제35조) 조항. 이 법은 기본법 성격이라 매핑이 EU 쪽보다 성깁니다. @@ -95,7 +95,7 @@ SBOM_SCANNER_IMAGE=ghcr.io/sktelecom/bomlens-aibom:latest ./scripts/scan-sbom.sh 같은 데이터는 산출물에도 있습니다. ML-BOM(`_bom.json`, CycloneDX 1.7)과 적합성 보고서(`_conformance.*`)입니다. -## 적합성 리포트 읽는 법 +## 적합성 보고서 읽는 법 G7 블록의 머리에는 "N / 38 충족" 같은 수치가 옵니다. 분모는 자동 출처가 있는 검사만 셉니다. 51개 중 38개이므로, 이 숫자는 도구가 스스로 확인할 수 있었던 범위를 말합니다. 사람 검토 전용 13개는 그 옆에 "검토 필요" 건수로 따로 표시되고, 자동 검사 중 채워지지 않은 것은 권고 건수로 잡힙니다. @@ -113,7 +113,7 @@ G7 블록의 머리에는 "N / 38 충족" 같은 수치가 옵니다. 분모는 ## 한계 - 결과는 HuggingFace 모델 카드만큼만 충실합니다. 카드가 빈약하면 ML-BOM도 빈약하고, G7 검사도 카드에 문서화된 범위를 반영할 뿐 모델 자체를 감사하지는 않습니다. 리포트 생성은 도구의 몫이고, 해석과 검토 전용 13개 요소를 채우는 일은 사람의 몫입니다. -- 적합성 리포트는 EU 인공지능법을 비롯한 어떤 규제의 준수도 인증하지 않습니다. 문서화 공백을 드러내 사람이 메울 수 있게 할 뿐입니다. +- 적합성 보고서는 EU 인공지능법을 비롯한 어떤 규제의 준수도 인증하지 않습니다. 문서화 공백을 드러내 사람이 메울 수 있게 할 뿐입니다. - 메타데이터를 네트워크로 가져오므로, 비공개·게이트 모델은 접근 권한(환경의 HuggingFace 토큰)이 필요하며 오프라인 사용은 지원하지 않습니다. - 모델 id는 `org/model` 형식이어야 합니다. 컬렉션 이름이나 전체 URL은 해석되지 않습니다. diff --git a/docs/guides/firmware.ko.md b/docs/guides/firmware.ko.md index 9c498d39..98364595 100644 --- a/docs/guides/firmware.ko.md +++ b/docs/guides/firmware.ko.md @@ -78,7 +78,7 @@ OSV(Open Source Vulnerabilities) 권고는 재배포 이미지에 share-alike - 오픈소스 도구 스택의 검출률은 약 60~85%이며, 펌웨어 종류와 strip 정도, 언팩 성공 여부에 크게 좌우됩니다. - 함수 수준 바이너리 핑거프린팅이 없어서, 상용 도구와 달리 strip되거나 인라인된 컴포넌트, 버전 문자열이 제거된 바이너리는 놓칩니다. - 정적 링크 라이브러리와 벤더가 변형한 squashfs, 암호화·서명된 펌웨어, 사명을 바꾼 라이브러리는 검출하지 못하거나 부정확합니다. -- 결과 SBOM은 best-effort 추정이므로, 법적 라이선스 컴플라이언스의 단일 근거로 사용하지 마세요. +- 결과 SBOM은 완전하지 않은 근사 추정이므로, 법적 라이선스 컴플라이언스의 단일 근거로 사용하지 마세요. --- diff --git a/docs/guides/identify-vendored.ko.md b/docs/guides/identify-vendored.ko.md index 35d92ee7..9bd7716d 100644 --- a/docs/guides/identify-vendored.ko.md +++ b/docs/guides/identify-vendored.ko.md @@ -22,9 +22,9 @@ OSSKB 서비스로는 파일 **지문(해시)**만 전송됩니다. 소스 코 ## 패키지 매니저가 있는 프로젝트에서는 -이 옵션은 패키지 매니저가 없는 소스를 위한 것입니다. npm·Maven·pip·Go 등을 쓰는 프로젝트라면 일반 스캔이 이미 의존성을 해석하므로 필요하지 않습니다. 그래도 켜면 BomLens가 결과를 정합화합니다. 의존성·빌드 디렉터리(`node_modules`, `vendor`, `dist` 등)는 건너뛰고, 패키지 매니저 컴포넌트가 이미 가진 이름과 겹치는 매치는 그 권위 있는 식별을 우선해 제거합니다. 그래서 관리 프로젝트에서 켜도 알려진 의존성이 중복되거나 취약점 수가 부풀지 않으며, 기껏해야 패키지 매니저가 못 본 진짜 복사된 소스만 추가됩니다. +이 옵션은 패키지 매니저가 없는 소스를 위한 것입니다. npm, Maven, pip, Go 등을 쓰는 프로젝트라면 일반 스캔이 이미 의존성을 해석하므로 필요하지 않습니다. 그래도 켜면 BomLens가 결과를 정리해 중복을 없앱니다. 의존성·빌드 디렉터리(`node_modules`, `vendor`, `dist` 등)는 건너뛰고, 패키지 매니저 컴포넌트에 이미 있는 이름과 겹치는 매칭 결과는 더 정확한 패키지 매니저 쪽 식별을 우선해 제거합니다. 그래서 관리 프로젝트에서 켜도 알려진 의존성이 중복되거나 취약점 수가 부풀지 않으며, 기껏해야 패키지 매니저가 못 본 진짜 복사된 소스만 추가됩니다. -매치는 출처와 신뢰도가 태깅된 채 읽기 전용으로 기록됩니다. BomLens는 accept/reject 같은 audit 워크플로를 제공하지 않습니다. 매치를 확정하거나 triage해야 하면 SBOM을 취약점 관리 시스템(Dependency-Track, TRUSCA 등)에 올려 거기서 처리하세요. +각 매칭 결과는 출처와 신뢰도를 붙여 읽기 전용으로 기록합니다. BomLens는 승인/반려 같은 감사 절차를 제공하지 않습니다. 매칭 결과를 확정하거나 분류해야 하면 SBOM을 취약점 관리 시스템(Dependency-Track, TRUSCA 등)에 올려 거기서 처리하세요. ## 준비 @@ -41,7 +41,7 @@ scan-sbom.sh --project trelay --version 26.4.0 --target ./src \ --identify-vendored --all --generate-only ``` -웹 UI·데스크톱 앱에서는 **고급**을 펼쳐 **파일 단위 식별 (SCANOSS)** 토글을 켭니다. 화면 라벨은 "파일 단위 식별 (SCANOSS)"이지만 이 문서에서 말하는 내장 오픈소스 식별과 같은 기능입니다. 이 옵션은 소스 스캔(현재 디렉터리·git URL·ZIP 업로드)이면서 이미지가 지원할 때만 보입니다. +웹 UI·데스크톱 앱에서는 **고급**을 펼쳐 **파일 단위 식별 (SCANOSS)** 토글을 켭니다. 화면 라벨은 "파일 단위 식별 (SCANOSS)"이지만 이 문서에서 말하는 내장 오픈소스 식별과 같은 기능입니다. 이 옵션은 소스 스캔(현재 디렉터리, git URL, ZIP 업로드)이면서 이미지가 지원할 때만 보입니다. 명령어가 낯선 Windows 사용자는 [비개발자 빠른 시작](../start/no-cli.ko.md)의 데스크톱 앱 안내를 먼저 따라 하세요. @@ -71,8 +71,8 @@ scan-sbom.sh --project trelay --version 26.4.0 --target ./src --identify-vendore 엔드포인트 주소(`SCANOSS_API_URL`)와 보고 임계값(`SCANOSS_MIN_FILES`)은 CLI와 컨테이너 환경변수로만 설정하며, 웹 UI·데스크톱 앱에는 입력 화면이 없습니다. 특히 데스크톱 앱은 `SCANOSS_API_URL`을 컨테이너로 전달하지 않으므로, 현재 데스크톱 앱 화면에서는 상용·자체 호스팅 엔드포인트를 쓸 수 없습니다. 이 엔드포인트가 필요하면 CLI나 `sbom-ui.bat`로 실행하면서 환경변수를 지정하세요. -버전은 근사값입니다. 파일 매치는 그 파일 내용이 처음 등장한 릴리스를 버전으로 보고하므로, 같은 라이브러리라도 파일마다 버전이 조금씩 다르게 나오거나 실제보다 한 단계 어긋난 릴리스로 보고될 수 있습니다. 버전(과 그로부터 도출된 CVE)은 최종 판정이 아니라 검토의 출발점으로 삼으세요. +버전은 근사값입니다. 파일 매칭은 그 파일 내용이 처음 등장한 릴리스를 버전으로 보고하므로, 같은 라이브러리라도 파일마다 버전이 조금씩 다르게 나오거나 실제보다 한 단계 어긋난 릴리스로 보고될 수 있습니다. 버전(과 그로부터 도출된 CVE)은 최종 판정이 아니라 검토의 출발점으로 삼으세요. -귀속(어느 프로젝트인지)도 틀릴 수 있습니다. 여러 프로젝트가 흔히 복사하는 파일(예: zlib의 `deflate.c`)은 정식 upstream이 아니라 그것을 vendored한 다운스트림 프로젝트로 매치될 수 있습니다. 이 노이즈를 줄이기 위해 BomLens는 **최소 두 개 이상의 파일이 지지하는 라이브러리만 보고**하고(`SCANOSS_MIN_FILES`로 조정, `1`이면 모두 유지) 버전·PURL은 그 파일들의 **다수결**로 정합화합니다. 그래서 단발성 포크 매치는 떨어지고, 여러 포크로 흩어진 라이브러리는 하나의 컴포넌트로 합쳐집니다. 다만 완전한 해결은 아니며, 실제 사본이 여전히 다른 이름으로 보고되고 그 CVE를 놓칠 수 있습니다. 이는 지식 베이스의 랭킹·커버리지 한계이며 무료 OSSKB에서 더 두드러집니다. 더 정확한 귀속이 필요하면 `SCANOSS_API_URL`을 SCANOSS 상용·자체 호스팅 엔드포인트로 지정하세요. 또한 공개 저장소에 이미 게시된 소스를 스캔하면 그 저장소로 매치됩니다(자기 1st-party 파일이 자기 공개 프로젝트로 매치) — 의도한 용도인 비공개 공급사 소스에서는 발생하지 않습니다. +귀속(어느 프로젝트인지)도 틀릴 수 있습니다. 여러 프로젝트가 흔히 복사하는 파일(예: zlib의 `deflate.c`)은 정식 upstream이 아니라 그것을 vendored한 다운스트림 프로젝트로 매칭될 수 있습니다. 이 노이즈를 줄이기 위해 BomLens는 **최소 두 개 이상의 파일이 지지하는 라이브러리만 보고**하고(`SCANOSS_MIN_FILES`로 조정, `1`이면 모두 유지) 버전과 PURL은 그 파일들의 **다수결**로 정합니다. 그래서 단발성 포크 매칭은 걸러지고, 여러 포크로 흩어진 라이브러리는 하나의 컴포넌트로 합쳐집니다. 다만 완전한 해결은 아니며, 실제 사본이 여전히 다른 이름으로 보고되고 그 CVE를 놓칠 수 있습니다. 이는 지식 베이스의 랭킹과 커버리지 한계이며 무료 OSSKB에서 더 두드러집니다. 더 정확한 귀속이 필요하면 `SCANOSS_API_URL`을 SCANOSS 상용 또는 자체 호스팅 엔드포인트로 지정하세요. 또한 공개 저장소에 이미 게시된 소스를 스캔하면 그 저장소로 매칭됩니다(자기 1st-party 파일이 자기 공개 프로젝트로 매칭됨) — 의도한 용도인 비공개 공급사 소스에서는 발생하지 않습니다. -결과는 사람 검토가 도움이 되는 best-effort 추정입니다. OSSKB 약관과 라이선스 설명은 [THIRD_PARTY_LICENSES.md](https://github.com/sktelecom/bomlens/blob/main/THIRD_PARTY_LICENSES.md)를 참조하세요. +결과는 확정이 아니라 근사 추정이므로 사람이 한 번 검토하는 편이 좋습니다. OSSKB 약관과 라이선스 설명은 [THIRD_PARTY_LICENSES.md](https://github.com/sktelecom/bomlens/blob/main/THIRD_PARTY_LICENSES.md)를 참조하세요. diff --git a/docs/korean-style-guide.md b/docs/korean-style-guide.md index 8718615f..04af5db7 100644 --- a/docs/korean-style-guide.md +++ b/docs/korean-style-guide.md @@ -31,7 +31,7 @@ - 고친 뒤: `프로젝트 이름과 버전을 입력하고, 스캔 대상을 골라 실행을 누른다` - **화살표(→) 장식** — "실행 → 스캔 → 다운로드"처럼 흐름을 화살표로 잇는 표현은 문장으로 푼다. 다이어그램 안에서 쓰는 화살표는 그대로 둔다. -- **가운뎃점(·) 나열 남발** — "고지문·SBOM·보안 보고서·위험 보고서"처럼 길게 잇지 +- **가운뎃점(·) 나열 남발** — `고지문·SBOM·보안 보고서·위험 보고서`처럼 길게 잇지 말고, 자연스러운 문장이나 목록으로 바꾼다. ### 2. 구조적 AI 패턴 @@ -51,10 +51,29 @@ 우리 문서엔 많지 않지만, 눈에 띄면 고친다. -- "~를 통해" → "~로", "~으로" -- "~에 대해 논의할 필요가 있다" → "~를 논의해야 한다" -- "~에 의해 생성된" → "~가 만든" -- 이중 피동("~되어지다") → 능동 또는 단일 피동 +- `~를 통해` → `~로`, `~으로` +- `~에 대해 논의할 필요가 있다` → `~를 논의해야 한다` +- `~에 의해 생성된` → `~가 만든` +- 이중 피동(`~되어지다`) → 능동 또는 단일 피동 + +## 용어와 표기 + +같은 대상을 문서마다 다르게 적으면 검색이 깨지고 번역 티가 난다. 2026-07 교정에서 +정한 표준 표기다. 새 문서도 이를 따른다. + +- 외래어 표기: "디렉터리"(디렉토리 아님), "배지"(뱃지 아님) +- 산출물 문서는 "보고서"로 통일한다("리포트" 아님). 파일명(`_risk-report` 등)은 + 식별자이므로 그대로 둔다. +- 표의 세로줄은 "열"이라고 쓴다("컬럼" 아님) +- SCANOSS 등의 match는 "매칭"("매치" 아님), 그 결과물은 "매칭 결과" +- triage는 "(취약점) 분류"로 풀어 쓴다 +- best-effort는 음차하지 말고 뜻을 풀어 쓴다: "실패해도 스캔을 중단하지 않음", + "완전하지 않은 근사 추정" 등 문맥에 맞게 +- 영어 그대로 두는 것: opt-in, 폴백, PURL 같은 굳어진 기술 용어와 화면의 영문 라벨. + 다만 화면 요소를 지칭할 때는 웹 UI 한국어 라벨을 그대로 쓴다(예: "위험 · 컴플라이언스" + 그룹, "통합 검색") +- 새 용어를 만들지 않는다. "정합화", "AI 표면", "머리 수치"처럼 사전에 없는 조어가 + 필요해 보이면 통용 표현으로 푼다 ## 변경 강도 diff --git a/docs/reference/cli.ko.md b/docs/reference/cli.ko.md index 7886a229..2446d775 100644 --- a/docs/reference/cli.ko.md +++ b/docs/reference/cli.ko.md @@ -22,7 +22,7 @@ BomLens의 전체 옵션과 분석 모드, CI/CD 통합 방법, 트러블슈팅 |------|--------|------| | `--project <이름>` | — | **(필수)** 프로젝트 이름 | | `--version <버전>` | — | **(필수)** 프로젝트 버전 | -| `--target <대상>` | 현재 디렉토리 | 분석 대상: 디렉토리(소스 트리, 또는 OS rootfs·빌드 산출물 staging), Docker 이미지, 바이너리 파일, `.zip`/`.tar.gz` 아카이브 | +| `--target <대상>` | 현재 디렉터리 | 분석 대상: 디렉터리(소스 트리, 또는 OS rootfs·빌드 산출물 staging), Docker 이미지, 바이너리 파일, `.zip`/`.tar.gz` 아카이브 | | `--git ` | — | git/GitHub URL을 얕은 클론(shallow) 후 소스로 분석 (비공개 저장소: `GIT_TOKEN` 환경변수) | | `--branch ` | 기본 브랜치 | `--git` 대상의 브랜치, 태그, 커밋 (별칭 `--ref`) | | `--firmware` | false | `--target` 파일을 펌웨어 모드로 강제 (opt-in 펌웨어 이미지) | diff --git a/docs/reference/ecosystems.ko.md b/docs/reference/ecosystems.ko.md index fb8ae707..c28f98cc 100644 --- a/docs/reference/ecosystems.ko.md +++ b/docs/reference/ecosystems.ko.md @@ -4,9 +4,9 @@ description: Java, Python, Node.js 등 언어별 예제 프로젝트로 BomLens # 지원 생태계 -`examples/` 디렉토리의 언어별 예제 프로젝트로 직접 실습해 보는 가이드입니다. 각 예제를 실행하면 SBOM 출력 결과를 바로 확인할 수 있습니다. +`examples/` 디렉터리의 언어별 예제 프로젝트로 직접 실습해 보는 가이드입니다. 각 예제를 실행하면 SBOM 출력 결과를 바로 확인할 수 있습니다. -## 예제 디렉토리 구조 +## 예제 디렉터리 구조 ``` examples/ diff --git a/docs/reference/ui.ko.md b/docs/reference/ui.ko.md index 308485b8..38907422 100644 --- a/docs/reference/ui.ko.md +++ b/docs/reference/ui.ko.md @@ -23,11 +23,11 @@ cd ~/sbom-output # 출력 폴더(아무 곳이나 가능) 인터페이스는 폭 전체를 가로지르는 상단 바, 현재 스캔의 섹션을 담는 좌측 레일, 내용 영역으로 이뤄집니다. -- **상단 바** — 제품 표시(클릭하면 홈으로), 현재 프로젝트, 재스캔 버튼(설정을 그대로 담고 있는 스캔에서만 나타나며, 같은 대상을 토글을 채운 채 다시 실행합니다), 컴포넌트와 CVE를 아우르는 글로벌 검색, 스캔 관리 메뉴(시계 아이콘을 누르면 지난 스캔 목록과 삭제 버튼, 전체 목록 링크가 열립니다), 새 스캔 버튼, 언어(한국어 / EN)와 라이트·다크 전환. +- **상단 바** — 제품 표시(클릭하면 홈으로), 현재 프로젝트, 재스캔 버튼(설정이 그대로 남아 있는 스캔에서만 나타나며, 같은 대상을 토글을 채운 채 다시 실행합니다), 컴포넌트와 CVE를 아우르는 통합 검색, 스캔 관리 메뉴(시계 아이콘을 누르면 지난 스캔 목록과 삭제 버튼, 전체 목록 링크가 열립니다), 새 스캔 버튼, 언어(한국어 / EN)와 라이트·다크 전환. - **좌측 레일** — 현재 스캔의 섹션이 인벤토리, 위험·컴플라이언스, AI, 산출물로 묶여 있습니다. 레일은 스캔에 맞춰 바뀝니다. AI 섹션은 AI/ML SBOM에만 나타나고, 각 섹션은 해당 데이터가 있을 때만 보입니다. 화면 폭이 좁으면 아이콘만 남게 접힙니다. 스캔이 열려 있지 않은 홈 화면에는 레일이 없습니다. - **내용 영역** — 홈(스캔 관리) 화면, 새 스캔 폼, 진행 화면, 또는 선택한 결과 섹션. -전역 작업(새 스캔, 스캔 관리)은 상단 바에 있어 레일은 현재 스캔의 섹션만 담습니다. 로고, 새 스캔, 레일 섹션, 점프 카드, 지난 스캔 링크 같은 모든 내비게이션 요소는 URL 해시(`#/scan//
`)를 가진 실제 링크라, Cmd/Ctrl 클릭이나 가운데 클릭으로 새 탭에서 열 수 있습니다. +전역 작업(새 스캔, 스캔 관리)은 상단 바에 있어 레일은 현재 스캔의 섹션만 담습니다. 로고, 새 스캔, 레일 섹션, 바로가기 카드, 지난 스캔 링크 같은 모든 내비게이션 요소는 URL 해시(`#/scan//
`)가 붙은 실제 링크라, Cmd/Ctrl 클릭이나 가운데 클릭으로 새 탭에서 열 수 있습니다. ## 새 스캔 @@ -60,15 +60,15 @@ cd ~/sbom-output # 출력 폴더(아무 곳이나 가능) **개요**는 한눈에 보는 수치를 각 상세 섹션으로 이동하는 카드로 먼저 보여주고, 이어서 주의가 필요한 항목(형식 적합성 실패(공급사 SBOM 분석 시), 심각·높음 취약점, 라이선스 검토가 필요한 컴포넌트)을 둡니다. 스캔이 상위 지원 종료(EOL) 컴포넌트를 표시하면 "지원 종료" 개수 타일이 카드에 더해지고, 그중 취약점도 있는 컴포넌트는 위험색으로 강조됩니다([컴포넌트 지원 종료](../concepts/reports-explained.ko.md#컴포넌트-지원-종료eol) 참고). 최신 버전보다 뒤처진 컴포넌트 수를 세는 타일도 별도로 붙습니다([버전 최신성](../concepts/reports-explained.ko.md#버전-최신성) 참고). 그 아래에는 두 위험 축, 곧 보안 심각도 분포와 라이선스 분류를 좌우로 나란히 배치합니다. 둘 중 한 막대 영역을 클릭하면 해당 섹션(취약점 또는 라이선스)으로 필터가 걸린 채 이동합니다. 스캔이 분석을 줄여서 끝났을 때(예를 들어 cdxgen이 Docker 디스크 공간 부족으로 돌지 못해 SBOM이 직접 의존성만으로 대체된 경우) 사유와 조치를 알려주는 배너가 여기에 나타납니다. 스캔이 아직 진행 중이면 실시간 로그가 다른 섹션이 아니라 이 개요에 표시됩니다. -![개요 — 주의 필요, 수치, 심각도, 점프 카드](../images/app-results.png) +![개요 — 주의 필요, 수치, 심각도, 바로가기 카드](../images/app-results.png) -**컴포넌트**는 검출된 모든 항목을 나열합니다. 검색과 필터(취약점 있음, 직접 의존만, 검토 필요, 지원 종료, 최신 아님)가 있고, 범위(직접·이행)와 위험(최고 취약점 심각도와 개수) 컬럼을 둡니다. 상위 지원이 종료된 컴포넌트에는 "지원 종료" 뱃지가 붙고, 아는 경우 종료 날짜도 함께 표시합니다. 최신 버전이 아닌 컴포넌트는 최신 아님으로 표시하며, deps.dev 보강을 켜면(`STALENESS_ENRICH=true`) 상세에 몇 릴리스 뒤인지와 마지막 릴리스 날짜가 나옵니다([버전 최신성](../concepts/reports-explained.ko.md#버전-최신성) 참고). 대용량 SBOM은 나눠서 렌더합니다. 행을 클릭하면 그 자리에서 상세가 펼쳐집니다. PURL, 소스·다운로드 위치, 저작권, 라이선스, 취약점을 보여줍니다. +**컴포넌트**는 검출된 모든 항목을 나열합니다. 검색과 필터(취약점 있음, 직접 의존만, 검토 필요, 지원 종료, 최신 아님)가 있고, 범위(직접·이행)와 위험(최고 취약점 심각도와 개수) 열을 둡니다. 상위 지원이 종료된 컴포넌트에는 "지원 종료" 배지가 붙고, 아는 경우 종료 날짜도 함께 표시합니다. 최신 버전이 아닌 컴포넌트는 최신 아님으로 표시하며, deps.dev 보강을 켜면(`STALENESS_ENRICH=true`) 상세에 몇 릴리스 뒤인지와 마지막 릴리스 날짜가 나옵니다([버전 최신성](../concepts/reports-explained.ko.md#버전-최신성) 참고). 대용량 SBOM은 나눠서 표시합니다. 행을 클릭하면 그 자리에서 상세가 펼쳐집니다. PURL, 소스·다운로드 위치, 저작권, 라이선스, 취약점을 보여줍니다. -![컴포넌트 — 범위·위험 컬럼과 필터](../images/web-ui-components.png) +![컴포넌트 — 범위·위험 열과 필터](../images/web-ui-components.png) -**취약점**은 심각도에 이어 CVSS로 정렬하며, CVSS 컬럼과 수정 버전을 보여주고, 각 행을 펼치면 CVSS 벡터·설명·참조가 그 자리에서 나옵니다. 심각도 막대에서 한 구간을 클릭하면 그 심각도로 필터링되고, CVE나 패키지로 검색할 수 있습니다. +**취약점**은 심각도에 이어 CVSS로 정렬하며, CVSS 열과 수정 버전을 보여주고, 각 행을 펼치면 CVSS 벡터·설명·참조가 그 자리에서 나옵니다. 심각도 막대에서 한 구간을 클릭하면 그 심각도로 필터링되고, CVE나 패키지로 검색할 수 있습니다. -![취약점 — CVSS 컬럼과 펼침 행](../images/web-ui-vulns.png) +![취약점 — CVSS 열과 펼침 행](../images/web-ui-vulns.png) **의존성**은 SBOM에 기록된 관계를 그래프나 트리로 보여줍니다. 직접 의존성을 강조하고, 알려진 취약점이 있는 패키지는 심각도로 표시합니다. 트리로 전환하면 직접·이행 의존성을 계층으로 펼칠 수 있습니다. @@ -78,13 +78,13 @@ cd ~/sbom-output # 출력 폴더(아무 곳이나 가능) ![라이선스 — 검토 우선, 이어 전체 분포](../images/web-ui-licenses.png) -**적합성**은 기존 SBOM을 분석할 때(SBOM 업로드 / ANALYZE 모드) Risk & compliance 그룹에 나타납니다. 형식 판정(통과 또는 실패)과 기본 CycloneDX 검사(타임스탬프, 도구, 최상위 컴포넌트, 이름·버전 커버리지, PURL 커버리지, 이행 의존성)를 보여주고, 실패한 검사마다 누락 항목을 나열합니다. 분석한 SBOM에 머신러닝 모델 컴포넌트가 있으면 AI G7 최소 요소 검사(모두 권고)가 이 안에 하위 블록으로 나타납니다. G7 7개 클러스터별로 묶이고, 각 항목에는 데이터 출처 배지(자동 확인, 신호 추정, 선언 필요, 검토 필요)가 표시됩니다. 머리 수치와 배지가 뜻하는 바는 [AI 모델 SBOM 가이드](../guides/ai-model.ko.md#적합성-리포트-읽는-법)에서 설명합니다. +**적합성**은 기존 SBOM을 분석할 때(SBOM 업로드 / ANALYZE 모드) 위험 · 컴플라이언스 그룹에 나타납니다. 형식 판정(통과 또는 실패)과 기본 CycloneDX 검사(타임스탬프, 도구, 최상위 컴포넌트, 이름·버전 커버리지, PURL 커버리지, 이행 의존성)를 보여주고, 실패한 검사마다 누락 항목을 나열합니다. 분석한 SBOM에 머신러닝 모델 컴포넌트가 있으면 AI G7 최소 요소 검사(모두 권고)가 이 안에 하위 블록으로 나타납니다. G7 7개 클러스터별로 묶이고, 각 항목에는 데이터 출처 배지(자동 확인, 신호 추정, 선언 필요, 검토 필요)가 표시됩니다. 요약 수치와 배지가 뜻하는 바는 [AI 모델 SBOM 가이드](../guides/ai-model.ko.md#적합성-보고서-읽는-법)에서 설명합니다. ![적합성 — 형식 판정과 G7 권고 하위 블록](../images/web-ui-g7.png) **산출물**은 생성된 파일(SBOM, 고지문, 위험분석 보고서, 보안 보고서, 적합성)을 종류별로 묶어 나열하고, 포맷별로 또는 ZIP 하나로 내려받습니다. 소스 트리 섹션은 ScanCode 결과가 있을 때, 즉 **라이선스 스캔 (ScanCode)**을 켜고 소스를 스캔한 산출물이 있을 때 나타나며, 소스 파일을 파일별 탐지 라이선스와 함께 보여줍니다. -### AI 표면 +### AI 전용 섹션 AI/ML SBOM(머신러닝 모델 컴포넌트가 있는 CycloneDX SBOM)에서는 레일에 다음이 추가됩니다.