From bae9605053cafff1cf3b18730742c2a7b8249a27 Mon Sep 17 00:00:00 2001 From: Haksung Jang Date: Sun, 14 Jun 2026 13:42:14 +0900 Subject: [PATCH] docs(user-guide): document received-SBOM ingest + conformance on Scans/SBOM pages (model 3) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The CI-integration how-to (ci-integration/sbom-upload.md) already covered the upload endpoint + conformance verdict, but the product user-guide did not: - user-guide/scans.md: add the 'sbom' scan kind to the kinds table, correct the 'Source/Container only' dialog note (three kinds now; sbom is uploaded, not picked), and add a 'Received SBOMs (uploaded)' section covering formats (CycloneDX/SPDX), the ingest endpoint, and the advisory pass/warn/fail conformance verdict + per-check meaning, cross-linking the CI guide. - user-guide/sbom.md: add an export-vs-upload note distinguishing this page (export from a scan) from uploading a supplier SBOM, linking both surfaces. - EN + KO mirrored; KO translation-style lint S1/S2 clean. (CHANGELOG is batched at release-prep here — #404–#412 will be captured then, matching how the concurrent ingest PRs were handled.) --- docs-site/docs/user-guide/sbom.md | 4 ++++ docs-site/docs/user-guide/scans.md | 14 +++++++++++++- .../current/user-guide/sbom.md | 4 ++++ .../current/user-guide/scans.md | 14 +++++++++++++- 4 files changed, 34 insertions(+), 2 deletions(-) diff --git a/docs-site/docs/user-guide/sbom.md b/docs-site/docs/user-guide/sbom.md index 20b2a680..08940b7c 100644 --- a/docs-site/docs/user-guide/sbom.md +++ b/docs-site/docs/user-guide/sbom.md @@ -10,6 +10,10 @@ sidebar_position: 5 The portal generates **Software Bill of Materials** (SBOM) artifacts from the latest successful scan. Four interchange formats are supported, plus an attribution `NOTICE` file. +:::note Export vs. upload +This page is about **exporting** an SBOM that TRUSCA generated from a scan. To go the other way — **upload** an SBOM your own tooling already produced (CycloneDX or SPDX) so TRUSCA matches CVEs and scores its conformance — see [Upload an SBOM](../ci-integration/sbom-upload.md) and [Scans → Received SBOMs](./scans.md#received-sboms-uploaded). +::: + ![Project detail — SBOM tab with format selector and last-scan summary](/img/screenshots/user-sbom-tab.png) :::note Audience diff --git a/docs-site/docs/user-guide/scans.md b/docs-site/docs/user-guide/scans.md index 4eafd787..c3863f44 100644 --- a/docs-site/docs/user-guide/scans.md +++ b/docs-site/docs/user-guide/scans.md @@ -20,8 +20,9 @@ Engineers with `developer` or higher on the project's team. Triggering scans aga |---|---|---| | **`source`** | `cdxgen` (CycloneDX generator) → scancode (first-party license detection) → Trivy (`trivy sbom`) | Components and their **declared** licenses (from dependency metadata) plus **detected** licenses (scancode reading your own first-party source), and CVEs (Common Vulnerabilities and Exposures) matched by the local Trivy DB against NVD + OSV + GHSA + EPSS + KEV. | | **`container`** | Trivy (Aqua Security container scanner) | OS-package vulnerabilities and (limited) language-package CVEs in a container image. | +| **`sbom`** | conformance scoring → component persistence → Trivy (`trivy sbom`) | An SBOM your own tooling already produced (CycloneDX-JSON or SPDX). TRUSCA does not clone or build your source — it scores the SBOM's quality, persists its components, and matches CVEs. See [Received SBOMs](#received-sboms-uploaded) below. | -Both kinds are selectable from the UI scan dialog in this release — pick **Source** or **Container** when you trigger a scan (see [Trigger a scan → From the UI](#from-the-ui)). The API accepts both kinds as well. +**Source** and **Container** are selectable from the UI scan dialog — pick one when you trigger a scan (see [Trigger a scan → From the UI](#from-the-ui)). An **`sbom`** scan is created differently: you upload an existing SBOM to the ingest endpoint rather than picking it in the dialog (see [Received SBOMs](#received-sboms-uploaded)). The API accepts all three kinds. ## Trigger a scan @@ -104,6 +105,17 @@ curl -sS -X POST \ The recommended path is the [GitHub Action](../ci-integration/github-actions.md), the [GitLab CI template](../ci-integration/gitlab-ci.md), or the [Jenkinsfile example](../ci-integration/jenkins.md). Each one wraps the API and adds the build gate. +## Received SBOMs (uploaded) {#received-sboms-uploaded} + +If your own build or CI already produces an SBOM, you can upload it instead of having TRUSCA clone and scan your source. This creates an **`sbom`** scan: TRUSCA persists the SBOM's components, matches CVEs with Trivy, and classifies declared licenses — the same component / vulnerability / license views you get from a source scan, and the build gate runs on it too. + +- **Formats**: CycloneDX-JSON, or SPDX (JSON or Tag-Value). Trivy auto-detects the format for matching; SPDX is mapped to CycloneDX internally for the component graph. +- **How to upload**: `POST /v1/projects/{project_id}/sbom-ingest` with an API key. The full how-to (fields, size limits, errors) is in [Upload an SBOM](../ci-integration/sbom-upload.md). + +### Conformance verdict + +Because a supplier-provided SBOM can be a "shell" with missing versions, PURLs, or no dependency graph, TRUSCA scores its **quality** on ingest and shows a **pass / warn / fail** badge plus a per-requirement table on the scan detail page. The verdict is **advisory** — a `fail` does not block ingest (CVE matching still runs); it tells you whether to accept the SBOM or send it back to the supplier. Mandatory checks include a timestamp, tool info, a top-level component, 100% component name+version, PURL coverage ≥ 90%, no `pkg:generic` placeholders, and a transitive dependency graph; license and hash coverage are recommended (warn-only). Read it via the UI panel or `GET /v1/projects/{project_id}/scans/{scan_id}/conformance` — see [Upload an SBOM → Read the conformance verdict](../ci-integration/sbom-upload.md#read-the-conformance-verdict). + ## Lifecycle ``` diff --git a/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/user-guide/sbom.md b/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/user-guide/sbom.md index 1909e42a..f5215e6b 100644 --- a/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/user-guide/sbom.md +++ b/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/user-guide/sbom.md @@ -10,6 +10,10 @@ sidebar_position: 5 포털은 가장 최근 성공 스캔으로부터 **Software Bill of Materials**(SBOM) 산출물을 생성합니다. 4가지 교환 포맷과 attribution `NOTICE` 파일을 지원합니다. +:::note 내보내기 vs 업로드 +이 페이지는 TRUSCA가 스캔으로부터 생성한 SBOM을 **내보내는(export)** 방법을 다룹니다. 반대로 고객 도구가 이미 만든 SBOM(CycloneDX 또는 SPDX)을 **업로드**해 TRUSCA가 CVE를 매칭하고 적합성을 채점하게 하려면 [SBOM 업로드](../ci-integration/sbom-upload.md)와 [스캔 → 받은 SBOM](./scans.md#받은-sbom-업로드)을 참고하세요. +::: + ![프로젝트 상세 — 포맷 선택기와 마지막 스캔 요약이 있는 SBOM 탭](/img/screenshots/user-sbom-tab.png) :::note 대상 독자 diff --git a/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/user-guide/scans.md b/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/user-guide/scans.md index 16799f85..8e8d8812 100644 --- a/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/user-guide/scans.md +++ b/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/user-guide/scans.md @@ -20,8 +20,9 @@ sidebar_position: 2 |---|---|---| | **`source`** | `cdxgen` → scancode(first-party 라이선스 탐지) → Trivy(`trivy sbom`) | 컴포넌트와 그 **declared** 라이선스(의존성 메타데이터에서), **detected** 라이선스(scancode 가 직접 스캔한 first-party 소스), 로컬 Trivy DB가 NVD + OSV + GHSA + EPSS + KEV로 매칭한 CVE(Common Vulnerabilities and Exposures). | | **`container`** | Trivy | 컨테이너 이미지의 OS 패키지 취약점(언어 패키지 CVE는 제한적). | +| **`sbom`** | 적합성 채점 → 컴포넌트 적재 → Trivy(`trivy sbom`) | 고객 도구가 이미 생성한 SBOM(CycloneDX-JSON 또는 SPDX). TRUSCA는 소스를 복제·빌드하지 않고 SBOM의 품질을 채점하고 컴포넌트를 적재하며 CVE를 매칭합니다. 아래 [받은 SBOM](#받은-sbom-업로드) 참고. | -현재 릴리스부터 두 종류 모두 UI 스캔 다이얼로그에서 선택할 수 있습니다 — 스캔을 트리거할 때 **Source** 또는 **Container** 를 고르세요([스캔 트리거 → UI에서](#ui에서) 참고). API도 두 종류를 모두 수용합니다. +**Source** 와 **Container** 는 UI 스캔 다이얼로그에서 선택합니다 — 스캔을 트리거할 때 하나를 고르세요([스캔 트리거 → UI에서](#ui에서) 참고). **`sbom`** 스캔은 방식이 다릅니다. 다이얼로그에서 고르는 대신 기존 SBOM을 인제스트 엔드포인트로 업로드합니다(아래 [받은 SBOM](#받은-sbom-업로드) 참고). API는 세 종류를 모두 수용합니다. ## 스캔 트리거 @@ -104,6 +105,17 @@ curl -sS -X POST \ 권장 경로는 [GitHub Action](../ci-integration/github-actions.md), [GitLab CI 템플릿](../ci-integration/gitlab-ci.md), [Jenkinsfile 예시](../ci-integration/jenkins.md)입니다. 모두 API를 감싸고 빌드 게이트를 추가합니다. +## 받은 SBOM(업로드) {#받은-sbom-업로드} + +빌드나 CI가 이미 SBOM을 생성한다면, TRUSCA가 소스를 복제·스캔하게 하는 대신 그 SBOM을 업로드할 수 있습니다. 이렇게 하면 **`sbom`** 스캔이 생성됩니다. TRUSCA는 SBOM의 컴포넌트를 적재하고, Trivy로 CVE를 매칭하고, 선언 라이선스를 분류합니다 — 소스 스캔에서 얻는 컴포넌트·취약점·라이선스 화면을 그대로 제공하며, 빌드 게이트도 동일하게 실행됩니다. + +- **포맷**: CycloneDX-JSON, 또는 SPDX(JSON·Tag-Value). 매칭에서는 Trivy가 포맷을 자동 감지하고, 컴포넌트 그래프를 위해 SPDX는 내부적으로 CycloneDX로 변환됩니다. +- **업로드 방법**: API Key로 `POST /v1/projects/{project_id}/sbom-ingest`. 필드·크기 제한·오류를 포함한 전체 안내는 [SBOM 업로드](../ci-integration/sbom-upload.md)에 있습니다. + +### 적합성(conformance) 결과 + +공급사가 제공한 SBOM은 버전·PURL·의존성 그래프가 빠진 "껍데기"일 수 있으므로, TRUSCA는 인제스트 시 SBOM의 **품질**을 채점하고 스캔 상세 페이지에 **pass / warn / fail** 배지와 요구사항별 표를 표시합니다. 이 결과는 **자문(advisory)**입니다 — `fail`이어도 인제스트를 막지 않으며(CVE 매칭은 계속 수행) SBOM을 받아들일지 공급사에 반려할지 판단하는 근거가 됩니다. 필수 검사에는 타임스탬프, 도구 정보, 최상위 컴포넌트, 컴포넌트 name+version 100%, PURL 커버리지 ≥ 90%, `pkg:generic` 자리표시자 없음, 전이 의존성 그래프가 포함되고, 라이선스·해시 커버리지는 권장(warn만)입니다. UI 패널이나 `GET /v1/projects/{project_id}/scans/{scan_id}/conformance`로 읽습니다 — [SBOM 업로드 → 적합성 결과 읽기](../ci-integration/sbom-upload.md#적합성conformance-결과-읽기) 참고. + ## 수명 주기 ```