diff --git a/docs-site/docs/comparison.md b/docs-site/docs/comparison.md index 8423b02a..62425d8f 100644 --- a/docs-site/docs/comparison.md +++ b/docs-site/docs/comparison.md @@ -44,7 +44,7 @@ For term definitions (SCA, SBOM, VEX, EPSS, reachability), see the | Auto remediation / PRs | Planned | Yes | No | No | | EPSS prioritization | **Yes** | Yes | Partial | No | | VEX consumption | **Yes** | Yes | Partial | No | -| Reachability analysis | Planned | Yes (some) | No | No | +| Reachability analysis | Go only (govulncheck) | Yes (some) | No | No | | Signed SBOM / provenance | Planned | Partial | No | No | ## vs commercial SCA (Black Duck, Snyk) @@ -64,8 +64,8 @@ covering detection, licenses, SBOM, approvals, and CI gating meets your needs. dependency-graph depth but does not yet open upgrade pull requests — suggested upgrades are planned. - **Prioritization signals.** EPSS prioritization is first-class — column, - sort, filter, and a policy-gate threshold. Reachability analysis is - planned, not shipped. + sort, filter, and a policy-gate threshold. Reachability analysis ships + for Go (via `govulncheck`); reachability for other ecosystems is planned. **Where TRUSCA is competitive:** self-hosting with no seat cost, Apache-2.0 licensing, a single portal instead of several consoles, a built-in @@ -129,8 +129,12 @@ These are real and intentional gaps. Each is on the - **Vulnerability data depends on the Trivy DB.** Signals are limited to what NVD + OSV + GHSA + EPSS + KEV expose, augmented by first-class EPSS prioritization, KEV in-the-wild badges, and imported VEX. -- **No reachability prioritization.** Findings are listed in full rather than - ranked by whether vulnerable code is reachable (planned, best-effort). +- **Multi-language reachability is limited.** Reachability prioritization + ships for **Go** (via `govulncheck`) — a reachable / not-reachable badge, + the `?reachable=` filter, `sort=reachable`, and a gate signal. Findings in + other ecosystems (Java, JS/TS, Python, and so on) are not yet analysed and + are shown in full. Proprietary multi-language reachability is where the + commercial tools still lead. - **Static license policy.** Classification uses a fixed catalog; per-team / per-org editable policy is planned. - **No signed SBOMs / provenance.** SBOM signing and SLSA provenance are diff --git a/docs-site/docs/reference/analysis-types.md b/docs-site/docs/reference/analysis-types.md index 86541b16..e9fad863 100644 --- a/docs-site/docs/reference/analysis-types.md +++ b/docs-site/docs/reference/analysis-types.md @@ -25,9 +25,9 @@ This page lists the **analysis pipelines** — source scan, container scan, poli | **Source SBOM scan** | A Git repository (or an uploaded source archive) | `cdxgen` → scancode → `trivy sbom` | A CycloneDX SBOM, declared + detected licenses with legal-tier classification, and matched CVEs | The default. You want the full component inventory, licenses, and vulnerabilities for a project's dependency tree. | [Scans → Scan kinds](../user-guide/scans.md#scan-kinds), [SBOM](../user-guide/sbom.md) | | **Container image scan** | A built container image reference (`name:tag`) | Trivy | OS-package CVEs and a base-image OS end-of-life (EOSL) verdict | You ship a container and want to know about vulnerabilities in the OS layer, not just your application dependencies. | [Scans → Scan a container image](../user-guide/scans.md#scan-a-container-image), [Container OS end-of-life](../user-guide/scans.md#container-os-eol) | | **Policy gate** | The findings and licenses from a completed scan | Portal gate evaluator | A pass/fail build verdict (CI exit code `0` or `1`) | You want a build to fail automatically on a forbidden license or a vulnerability over threshold — the CI enforcement point. | [Approvals](../user-guide/approvals.md), [License policies](./license-policies.md), [GitHub Actions](../ci-integration/github-actions.md) | -| **Reachability analysis** | (Planned) analyser output for a finding's call graph | (Planned) `govulncheck` and peers | A per-finding reachability signal — reachable / not reachable / not analysed | You want to prioritise findings whose vulnerable code is actually called. **See the status note below before relying on this.** | [Comparison → reachability](../comparison.md) | +| **Reachability analysis** | Preserved Go source of a scanned module | `govulncheck` (Go) | A per-finding reachable / not-reachable / not-analysed signal (Go findings only) | You want to prioritise findings whose vulnerable code is actually called. **Go only today — see the status note below.** | [Comparison → reachability](../comparison.md) | -The first three are analysis pipelines that ship and run today. The fourth, reachability, is a planned capability with partial UI plumbing — read the note below so you do not overstate it in an evaluation. +All four ship and run today. Reachability ships **for Go** via `govulncheck` — read the note below for its scope: it covers Go modules only, and findings in every other ecosystem are not yet analysed. ## Source SBOM scan {#source-detail} @@ -51,27 +51,29 @@ See [Approvals](../user-guide/approvals.md) for the human workflow around condit ## Reachability analysis {#reachability-detail} -:::caution Planned — not a shipped analysis pipeline -Reachability is a **planned, best-effort** capability. The UI surfaces a reachability signal where source data provides it, but **no dedicated reachability scan pipeline ships today**. The backend and worker do not run `govulncheck` (or any call-graph analyser) as a first-class analysis type — there is UI plumbing (a reachability badge, a `?reachable=` filter, a `sort=reachable` ranking, and a `reachability_source` field) that displays a signal *when a finding carries one*, but in this release findings are shown in full rather than ranked by whether vulnerable code is reachable. Every matched CVE is presented as "potentially affected". +:::note Ships for Go; other ecosystems not yet analysed +Reachability ships today **for Go**. After every successful source scan, the worker runs `govulncheck` as a best-effort follow-up (`scan_reachability.py`, dispatched from `scan_source`; `govulncheck` is built into the worker image). It is on by default and can be turned off with `REACHABILITY_ENABLED=false` to shed worker load. It never fails the originating scan — if the source is not preserved, the project is not a Go module, or `govulncheck` is missing or times out, findings simply stay "not analysed". -This matches the honest characterization elsewhere in the docs: [Comparison](../comparison.md) lists reachability as **Planned** with *no reachability prioritization*, and [Data sources](./data-sources.md) states the portal does **not** consume reachability analysis. Do not represent TRUSCA as running `govulncheck` as a first-class analysis type. +For each **Go** finding (a `pkg:golang/` component whose CVE / GHSA / GO id `govulncheck` reported), the analyser stamps a verdict: `reachable = true` (the vulnerable symbol is reachable on the call graph), `reachable = false` (the analyser ran but the symbol is not reachable), or `reachable = null` (not analysed). The signal is surfaced by the reachability badge, the `?reachable=true|false|unknown` filter, and the `sort=reachable` ranking, and it can inform the policy/build gate. + +**Findings in other ecosystems (Java, JS/TS, Python, and so on) are not yet analysed** — they stay `reachable = null` and are shown as "potentially affected". Multi-language reachability is the current commercial gap: Black Duck and Snyk run proprietary multi-language reachability, whereas TRUSCA ships Go-only reachability via `govulncheck`. ::: -When reachability lands, it will layer over the existing finding list as a prioritisation signal — the UI affordances (badge, filter, sort) are already in place to receive it. Track the status on the [comparison page](../comparison.md) and the [roadmap](https://github.com/trustedoss/trusca/blob/main/ROADMAP.md). +Track the multi-language roadmap on the [comparison page](../comparison.md) and the [roadmap](https://github.com/trustedoss/trusca/blob/main/ROADMAP.md). ## Verify it worked 1. The three shipped analysis kinds on this page (source, container, policy gate) match the scan kinds and gate documented in [Scans → Scan kinds](../user-guide/scans.md#scan-kinds) and [License policies → Dynamic gate evaluation](./license-policies.md#dynamic-gate-evaluation) — no pipeline appears here that is not documented there. - -2. The reachability row and its status note describe a **planned, best-effort** signal, consistent with [Comparison](../comparison.md) ("Planned", "No reachability prioritization") and [Data sources](./data-sources.md) ("does not consume reachability analysis") — this page does not claim a shipped `govulncheck` pipeline. + +2. The reachability row and its status note describe a **Go-only, best-effort** signal that ships today: a Go finding can carry a `reachable = true / false / null` verdict from `govulncheck`, while non-Go findings stay "not analysed". This is consistent with [Comparison](../comparison.md) ("Go only", reachability prioritization ships for Go) and [Data sources](./data-sources.md) (reachability is not a Trivy-DB signal but a separate `govulncheck` pipeline for Go). ## Troubleshooting - **"Which analysis do I run for licenses and CVEs?"** A source scan — it produces both in one run. The policy gate then turns those results into a build verdict. - **"My container scan found no application-dependency CVEs."** Container scans cover OS packages only. Run a source scan for the application dependency tree; the two are complementary. -- **"The reachability badge is blank on every finding."** Expected in this release: no reachability pipeline runs, so findings carry no reachability signal and the compact list renders nothing for the "not analysed" state. See the [status note](#reachability-detail). +- **"The reachability badge is blank on every finding."** Expected on non-Go findings, and on Go findings when reachability could not run (source not preserved, `REACHABILITY_ENABLED=false`, or `govulncheck` missing or timed out): the finding stays "not analysed" and the compact list renders nothing for that state. Go findings that were analysed show a reachable / not-reachable badge. See the [status note](#reachability-detail). ## See also @@ -80,4 +82,4 @@ When reachability lands, it will layer over the existing finding list as a prior - [Architecture](./architecture.md) — services, scan pipeline stages, Trivy matching. - [Data sources](./data-sources.md) — the per-finding data signals (NVD · OSV · GHSA · EPSS · KEV) behind each vulnerability. - [License policies](./license-policies.md) — how the policy gate classifies and gates licenses. -- [Comparison](../comparison.md) — where reachability and other planned items stand. +- [Comparison](../comparison.md) — reachability scope (Go today) and where other planned items stand. diff --git a/docs-site/docs/reference/data-sources.md b/docs-site/docs/reference/data-sources.md index 35f9a5f2..d5327b93 100644 --- a/docs-site/docs/reference/data-sources.md +++ b/docs-site/docs/reference/data-sources.md @@ -90,7 +90,7 @@ The portal **does not** consume: - Curated vulnerability research from commercial feeds (Black Duck KnowledgeBase, Snyk DB) — by design, we ship the open feeds only. - Vendor-specific advisory feeds (Oracle CPU, Microsoft MSRC) beyond what flows into NVD. These can be added as additional Trivy data sources in a future release. -- Reachability analysis. The portal does not parse call graphs; every matched CVE is shown as "potentially affected". +- Reachability as a **Trivy-DB signal** — the Trivy DB does not carry reachability. TRUSCA does run reachability, but as a separate `govulncheck` analyser for **Go**, not from Trivy DB data (see [Analysis types → Reachability](./analysis-types.md#reachability-detail)). It marks Go findings reachable / not-reachable / not-analysed; findings in other ecosystems are not analysed and are shown as "potentially affected". ## What this means for triage diff --git a/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/comparison.md b/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/comparison.md index df992b9f..5df85253 100644 --- a/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/comparison.md +++ b/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/comparison.md @@ -44,7 +44,7 @@ UI로 묶는 것입니다. 아래 비교는 그 아이디어를 세 가지 대 | 자동 리메디에이션 / PR | 로드맵 | 지원 | 미지원 | 미지원 | | EPSS 우선순위화 | **지원** | 지원 | 부분 | 미지원 | | VEX 소비 | **지원** | 지원 | 부분 | 미지원 | -| Reachability 분석 | 로드맵 | 일부 지원 | 미지원 | 미지원 | +| Reachability 분석 | Go만 지원 (govulncheck) | 일부 지원 | 미지원 | 미지원 | | SBOM 서명 / provenance | 로드맵 | 부분 | 미지원 | 미지원 | ## 상용 SCA(Black Duck, Snyk)와 비교 @@ -62,7 +62,8 @@ UI로 묶는 것입니다. 아래 비교는 그 아이디어를 세 가지 대 finding별 `fixed_version`과 의존성 그래프 depth는 제공하지만 업그레이드 PR을 아직 생성하지 않습니다 — 추천 업그레이드는 계획 단계입니다. - **우선순위화 신호.** EPSS 우선순위화는 1급 신호로 제공됩니다 — 컬럼·정렬·필터· - 정책 게이트 임계값. Reachability 분석은 아직 계획 단계입니다. + 정책 게이트 임계값. Reachability 분석은 `govulncheck`로 Go에 대해 제공되며, + 다른 생태계의 reachability는 계획 단계입니다. **TRUSCA가 경쟁력 있는 지점:** 좌석 비용 없는 자체 호스팅, Apache-2.0 라이선스, 여러 콘솔 대신 하나의 포털, 내장 컴포넌트 승인 워크플로우, 빌드 차단 CI @@ -120,8 +121,11 @@ SBOM·컴포넌트가 공급되는 것을 전제하며 스캔보다 clearing을 업그레이드는 계획 단계입니다. - **취약점 데이터가 Trivy DB에 의존.** 신호는 NVD + OSV + GHSA + EPSS + KEV 노출분에 더해 1급 EPSS 우선순위화, KEV 실환경 배지, 임포트된 VEX로 보강됩니다. -- **Reachability 우선순위화 없음.** 취약 코드의 도달 가능성으로 순위를 매기는 대신 - 전체를 나열합니다(계획, 베스트에포트). +- **다중 언어 reachability는 제한적.** reachability 우선순위화는 **Go**에 대해 + `govulncheck`로 제공됩니다 — reachable / not-reachable 배지, `?reachable=` 필터, + `sort=reachable`, 게이트 신호. 다른 생태계(Java, JS/TS, Python 등)의 finding은 + 아직 분석되지 않고 전체가 나열됩니다. 독점 다중 언어 reachability는 상용 도구가 + 여전히 앞서는 지점입니다. - **정적 라이선스 정책.** 분류는 고정 카탈로그를 사용하며, per-team / per-org 편집 가능 정책은 계획 단계입니다. - **SBOM 서명 / provenance 없음.** SBOM 서명과 SLSA provenance는 계획 diff --git a/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/reference/analysis-types.md b/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/reference/analysis-types.md index d60b26d5..00642d96 100644 --- a/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/reference/analysis-types.md +++ b/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/reference/analysis-types.md @@ -25,9 +25,9 @@ TRUSCA는 코드와 그 의존성에 대해 서로 다른 여러 **종류**의 | **소스 SBOM 스캔** | Git 레포지토리 (또는 업로드한 소스 아카이브) | `cdxgen` → scancode → `trivy sbom` | CycloneDX SBOM, 법적 tier 분류가 붙은 declared + detected 라이선스, 매칭된 CVE | 기본값. 프로젝트 의존성 트리의 전체 컴포넌트 목록·라이선스·취약점이 필요할 때. | [스캔 → 스캔 종류](../user-guide/scans.md#스캔-종류), [SBOM](../user-guide/sbom.md) | | **컨테이너 이미지 스캔** | 빌드된 컨테이너 이미지 참조 (`name:tag`) | Trivy | OS 패키지 CVE와 베이스 이미지 OS 지원 종료(EOSL) 판정 | 컨테이너를 배포하며, 애플리케이션 의존성뿐 아니라 OS 계층의 취약점도 알고 싶을 때. | [스캔 → 컨테이너 이미지 스캔](../user-guide/scans.md#컨테이너-이미지-스캔), [컨테이너 OS 지원 종료](../user-guide/scans.md#container-os-eol) | | **정책 게이트** | 완료된 스캔의 finding과 라이선스 | 포털 게이트 평가기 | pass/fail 빌드 판정 (CI exit code `0` 또는 `1`) | 금지 라이선스나 임계값 초과 취약점에서 빌드를 자동으로 실패시키고 싶을 때 — CI 집행 지점. | [승인](../user-guide/approvals.md), [라이선스 정책](./license-policies.md), [GitHub Actions](../ci-integration/github-actions.md) | -| **Reachability 분석** | (계획) finding의 콜 그래프에 대한 분석기 출력 | (계획) `govulncheck` 등 | finding별 reachability 신호 — reachable / not reachable / not analysed | 취약 코드가 실제로 호출되는 finding에 우선순위를 매기고 싶을 때. **의존하기 전에 아래 상태 안내를 확인하세요.** | [비교 → reachability](../comparison.md) | +| **Reachability 분석** | 스캔한 모듈의 보존된 Go 소스 | `govulncheck` (Go) | finding별 reachable / not-reachable / not-analysed 신호 (Go finding에 한함) | 취약 코드가 실제로 호출되는 finding에 우선순위를 매기고 싶을 때. **현재 Go만 지원 — 아래 상태 안내를 확인하세요.** | [비교 → reachability](../comparison.md) | -앞의 세 가지는 현재 제공·실행되는 분석 파이프라인입니다. 네 번째 reachability는 UI 배선만 일부 있는 계획 단계 기능입니다 — 평가에서 과장하지 않도록 아래 안내를 읽으세요. +네 가지 모두 현재 제공·실행됩니다. reachability는 `govulncheck`로 **Go에 대해** 제공됩니다 — 범위는 아래 안내를 읽으세요. Go 모듈만 커버하며, 다른 모든 생태계의 finding은 아직 분석되지 않습니다. ## 소스 SBOM 스캔 {#source-detail} @@ -51,27 +51,29 @@ TRUSCA는 코드와 그 의존성에 대해 서로 다른 여러 **종류**의 ## Reachability 분석 {#reachability-detail} -:::caution 계획 단계 — 제공되는 분석 파이프라인이 아닙니다 -Reachability는 **계획 단계의 베스트에포트** 기능입니다. UI는 출처 데이터가 제공하는 곳에서 reachability 신호를 노출하지만, **전용 reachability 스캔 파이프라인은 현재 제공되지 않습니다**. 백엔드와 워커는 `govulncheck`(또는 어떤 콜 그래프 분석기도)를 1급 분석 유형으로 실행하지 않습니다 — finding이 신호를 담을 *때* 이를 표시하는 UI 배선(reachability 배지, `?reachable=` 필터, `sort=reachable` 순위, `reachability_source` 필드)은 있지만, 이번 릴리스에서 finding은 취약 코드의 도달 가능성으로 순위가 매겨지지 않고 전체가 표시됩니다. 매칭된 모든 CVE는 "영향 가능"으로 제시됩니다. +:::note Go는 제공, 다른 생태계는 아직 미분석 +Reachability는 현재 **Go에 대해** 제공됩니다. 성공한 소스 스캔마다 워커가 베스트에포트 후속 단계로 `govulncheck`를 실행합니다(`scan_reachability.py`, `scan_source`에서 디스패치. `govulncheck`는 워커 이미지에 내장). 기본으로 켜져 있으며, 워커 부하를 덜려면 `REACHABILITY_ENABLED=false`로 끌 수 있습니다. 원래 스캔을 실패시키지 않습니다 — 소스가 보존되지 않았거나 프로젝트가 Go 모듈이 아니거나 `govulncheck`가 없거나 시간이 초과되면 finding은 그대로 "not analysed"로 남습니다. -이는 문서의 다른 곳과 정직하게 일치합니다. [비교](../comparison.md)는 reachability를 **계획**으로, *reachability 우선순위화 없음*으로 표시하며, [데이터 출처](./data-sources.md)는 포털이 reachability 분석을 **소비하지 않는다**고 명시합니다. TRUSCA가 `govulncheck`를 1급 분석 유형으로 실행한다고 표현하지 마세요. +각 **Go** finding(`govulncheck`가 보고한 CVE / GHSA / GO id를 지닌 `pkg:golang/` 컴포넌트)에 분석기가 판정을 찍습니다: `reachable = true`(콜 그래프에서 취약 심볼에 도달 가능), `reachable = false`(분석기는 실행됐으나 심볼에 도달 불가), `reachable = null`(미분석). 이 신호는 reachability 배지, `?reachable=true|false|unknown` 필터, `sort=reachable` 순위로 노출되며, 정책·빌드 게이트에도 반영될 수 있습니다. + +**다른 생태계(Java, JS/TS, Python 등)의 finding은 아직 분석되지 않습니다** — `reachable = null`로 남으며 "영향 가능"으로 표시됩니다. 다중 언어 reachability가 현재의 상용 격차입니다: Black Duck와 Snyk는 독점 다중 언어 reachability를 실행하지만, TRUSCA는 `govulncheck`로 Go 전용 reachability를 제공합니다. ::: -reachability가 도착하면 기존 finding 목록 위에 우선순위 신호로 얹힐 것입니다 — 이를 받을 UI 요소(배지·필터·정렬)는 이미 자리 잡았습니다. 상태는 [비교 페이지](../comparison.md)와 [로드맵](https://github.com/trustedoss/trusca/blob/main/ROADMAP.md)에서 확인하세요. +다중 언어 로드맵은 [비교 페이지](../comparison.md)와 [로드맵](https://github.com/trustedoss/trusca/blob/main/ROADMAP.md)에서 확인하세요. ## 동작 확인 1. 본 페이지의 제공되는 세 분석 종류(소스, 컨테이너, 정책 게이트)는 [스캔 → 스캔 종류](../user-guide/scans.md#스캔-종류)와 [라이선스 정책 → 동적 게이트 평가](./license-policies.md#동적-게이트-평가)에 문서화된 스캔 종류·게이트와 일치합니다 — 그곳에 문서화되지 않은 파이프라인이 여기 등장하지 않습니다. - -2. reachability 행과 그 상태 안내는 **계획 단계의 베스트에포트** 신호를 기술하며, 이는 [비교](../comparison.md)("계획", "reachability 우선순위화 없음")·[데이터 출처](./data-sources.md)("reachability 분석을 소비하지 않음")와 일관됩니다 — 본 페이지는 제공되는 `govulncheck` 파이프라인을 주장하지 않습니다. + +2. reachability 행과 그 상태 안내는 현재 제공되는 **Go 전용 베스트에포트** 신호를 기술합니다: Go finding은 `govulncheck`의 `reachable = true / false / null` 판정을 담을 수 있고, non-Go finding은 "not analysed"로 남습니다. 이는 [비교](../comparison.md)("Go만 지원", reachability 우선순위화는 Go에 제공)·[데이터 출처](./data-sources.md)(reachability는 Trivy DB 신호가 아니라 Go를 위한 별도 `govulncheck` 파이프라인)와 일관됩니다. ## 트러블슈팅 - **"라이선스와 CVE는 어떤 분석으로 얻나요?"** 소스 스캔입니다 — 한 번의 실행으로 둘 다 냅니다. 이후 정책 게이트가 그 결과를 빌드 판정으로 바꿉니다. - **"컨테이너 스캔이 애플리케이션 의존성 CVE를 하나도 찾지 못했습니다."** 컨테이너 스캔은 OS 패키지만 다룹니다. 애플리케이션 의존성 트리는 소스 스캔으로 실행하세요. 둘은 상호 보완적입니다. -- **"모든 finding에서 reachability 배지가 비어 있습니다."** 이번 릴리스에서는 정상입니다. reachability 파이프라인이 실행되지 않으므로 finding은 reachability 신호를 담지 않고, compact 목록은 "not analysed" 상태에 아무것도 렌더링하지 않습니다. [상태 안내](#reachability-detail)를 참조하세요. +- **"모든 finding에서 reachability 배지가 비어 있습니다."** non-Go finding에서는 정상이며, Go finding도 reachability가 실행되지 못한 경우(소스 미보존, `REACHABILITY_ENABLED=false`, 또는 `govulncheck` 없음·시간 초과)에는 마찬가지입니다. finding은 "not analysed"로 남고 compact 목록은 그 상태에 아무것도 렌더링하지 않습니다. 분석된 Go finding은 reachable / not-reachable 배지를 표시합니다. [상태 안내](#reachability-detail)를 참조하세요. ## 참고 @@ -80,4 +82,4 @@ reachability가 도착하면 기존 finding 목록 위에 우선순위 신호로 - [아키텍처](./architecture.md) — 서비스, 스캔 파이프라인 단계, Trivy 매칭. - [데이터 출처](./data-sources.md) — 각 취약점 뒤의 finding별 데이터 신호(NVD · OSV · GHSA · EPSS · KEV). - [라이선스 정책](./license-policies.md) — 정책 게이트가 라이선스를 분류·게이트하는 방식. -- [비교](../comparison.md) — reachability 등 계획 항목의 현황. +- [비교](../comparison.md) — reachability 범위(현재 Go)와 다른 계획 항목의 현황. diff --git a/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/reference/data-sources.md b/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/reference/data-sources.md index a4979764..39826aa3 100644 --- a/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/reference/data-sources.md +++ b/docs-site/i18n/ko/docusaurus-plugin-content-docs/current/reference/data-sources.md @@ -90,7 +90,7 @@ Dependency-Track 급 도구와 비교해 Trivy DB는 finding별로 다음 신호 - 상용 피드의 큐레이션된 취약점 리서치(Black Duck KnowledgeBase, Snyk DB) — 설계상 공개 피드만 사용. - NVD로 흘러드는 것 외 벤더 어드바이저리(Oracle CPU, Microsoft MSRC). 향후 릴리스에서 추가 Trivy data source로 붙일 수 있음. -- Reachability 분석. 포털은 콜 그래프를 파싱하지 않으며, 매칭된 CVE는 모두 "영향 가능"으로 표시. +- **Trivy DB 신호로서의** reachability — Trivy DB는 reachability를 담지 않습니다. TRUSCA는 reachability를 실행하지만, Trivy DB 데이터가 아니라 **Go**를 위한 별도 `govulncheck` 분석기로 실행합니다([분석 유형 → Reachability](./analysis-types.md#reachability-detail) 참조). Go finding을 reachable / not-reachable / not-analysed로 표시하며, 다른 생태계의 finding은 분석되지 않고 "영향 가능"으로 표시됩니다. ## 트리아지에의 의미 diff --git a/docs/bomlens-parity-review.md b/docs/bomlens-parity-review.md index 014ce2e1..cb2c5fad 100644 --- a/docs/bomlens-parity-review.md +++ b/docs/bomlens-parity-review.md @@ -13,9 +13,9 @@ | 항목 | 값 | |---|---| -| BomLens 커밋 | `5a62094` | -| BomLens 태그 | v1.7.0 + 27커밋 (2026-07-10) | -| 리뷰 일자 | 2026-07-11 (7차 — Phase K·L·M 완료 후) | +| BomLens 커밋 | `6b2ca03` | +| BomLens 태그 | v1.8.2 + 25커밋 (2026-07-18, #429) | +| 리뷰 일자 | 2026-07-18 (8차 — C4 트랙 재평가) | ## 격차 표 @@ -39,6 +39,9 @@ | 14 | 데스크톱 앱, local-first, `--byte-stable`·cosign 서명 | — | 역할경계 | BomLens 정체성 영역 | | 15 | 런타임 스코프 필터(test/dev 의존성 SBOM 제외) | P1 | **closed (Phase K, 2026-07-11)** | BomLens #331/#335/#337/#341 미러. cdxgen 이 test/provided/dev 의존성까지 담아 CVE·의무 과대 집계 — TRUSCA 동일 결함 확인. `integrations/sbom_scope_filter.py`: Maven 은 cdxgen scope 태그(hasScopes 가드), Node 는 **BomLens 와 달리 npm 재해석 서브프로세스 없이** 기존 npm_lockfile 분류로(dev 만 제거, keep-if-unknown). persist·서명·Trivy 전에 copy-then-commit 으로 적용, 인제스트 경로는 의도적 무필터(업로드 SBOM = 공급자 선언 진실). 기본 켬(`SCAN_SCOPE_FILTER_*`, 정확한 falsy 토큰만 끔). FE 요약 밴드 "N건 제외" 표시. **Android(release runtime classpath)는 워커에 Android SDK 부재로 후속 백로그** — gradle 유래 컴포넌트는 scope 미탑재라 hasScopes 가드로 무회귀 | | 16 | EOL(endoflife.date) 컴포넌트 플래그 | P2 | **closed (Phase M, 2026-07-11)** | BomLens #368(enrich-eol.sh) 미러. purl 맵 **원본 그대로 벤더링**(바이트 동일 계약 테스트, %40 정규화는 매처에서 흡수) + 스냅숏은 빌드타임 베이크 대신 **저장소 벤더링**(scripts/refresh_eol_snapshot.py, 릴리즈마다) — Docker 빌드 무네트워크·air-gap 기본 동작. 판정은 component_versions 카탈로그 컬럼(0038, KEV 동형)에 저장, persist 훅에서 스탬프(소스+인제스트 공통). FE: EolBadge(KevBadge 미러)·컬럼·`?eol=true` 필터·드로어 행·Overview 칩. 운영(0039): 주간 재스탬프 beat(항상 로컬 실행) + opt-in 실시간 수집(`EOL_REFRESH_ENABLED` 기본 꺼짐, 위생 플로어) + admin/health 스냅숏 패널(180일 stale 경고) | +| 18 | 버전 currency/staleness (최신 패치 대비 낙후·releases-behind) | P2 | **open (8차 채택, 2026-07-18)** | BomLens v1.8.0(`enrich-eol.sh`·`enrich-staleness.py`, `bomlens:currency:*`/`bomlens:staleness:*`). EOL(수명 종료)과 **다른 축** — "최신 패치/버전 대비 낙후". 오프라인(같은 릴리스 라인 내 낙후)은 TRUSCA EOL 스냅샷 인프라 재사용, deps.dev 절대최신은 egress라 air-gap 게이트(LICENSE_FETCH/SCANOSS 패턴) 필요. W9-#53 업그레이드 클러스터와 시너지. **구현 착수** | +| 19 | 규제 크로스워크 (G7→EU AI Act Annex IV·한국 AI기본법) | P4 | **미채택 (8차, 2026-07-18)** | BomLens v1.8.1(`regulation-crosswalk.json`). G7 적합성은 이미 수집(#2). "결측 요소→규제 문서 의무" 매핑은 정보성 레이어, 실사용자 없어 값 낮음 → 보류 | +| 20 | copyleft 강도 분류 (network/strong/weak/permissive) | P4 | **미채택 (8차, 2026-07-18)** | BomLens Unreleased(#420, `bomlens:licenseClass`). 허용/조건부/금지 티어와 직교하는 세분화. 한계효용 작음 → 보류 | | 17 | iOS CocoaPods/SPM lockfile 스캔 | P2 | **closed (Phase L, 2026-07-11)** | BomLens #347 미러. Podfile 존재 + pod CLI 부재 시 cdxgen cocoapods 수집기가 TypeError 로 스캔 전체를 죽이던 크래시 → `--exclude-type cocoapods`(어댑터+사이드카, depth-3 제한 글롭) + `integrations/cocoapods_lockfile.py` 가 Podfile.lock PODS: 블록에서 컴포넌트·그래프 오프라인 복원(**syft 불요** — BomLens 와 분기, npm_lockfile 규율). Package.resolved 만 커밋한 저장소도 swift 감지, 사이드카는 커밋된 lockfile 존재 시 `swift package resolve` 스킵. cdxgen 12.3.3 의 Package.resolved 오프라인 파싱 실측 검증(채록 픽스처가 그 증거) | ## TRUSCA 우위 (참고) @@ -54,7 +57,7 @@ BomLens 내부 방향 문서(`bomlens-internal/identity-and-direction.md`)가 | 2026 9~10월 | 검출 모드 `DETECTION=build\|lightweight\|static` (설계: sbom-tools #300) | 빌드 없는 경량 스캔 — TRUSCA 스캔 파이프라인에도 유효한 옵션 | | 2026 11~12월 | 취약점 변화 추적(재스캔 diff, 로컬 파일 기반) | 격차 표 #6과 같은 영역 — 포털이 먼저 완성하면 역할 경계가 명확해짐 | | 2026 11~12월 | TRUSCA SBOM ingest 연계(업로드 편의) | TRUSCA 쪽 수용 준비 필요 — 특히 ML-BOM 1.7 수용(#2) | -| 협의 대기 | 다언어 도달성 분석(Java/JS 등 call-graph 산출) | 상용(Black Duck) 최대 격차. BomLens가 산출·TRUSCA가 소비하는 공동 후보 — [`commercial-parity-candidates.md`](./commercial-parity-candidates.md) C4. 공용 포맷·역할 경계 선협의 필요 | +| ~~협의 대기~~ **전제 폐기(8차, 2026-07-18)** | 다언어 도달성 분석(Java/JS 등 call-graph 산출) | C4 원 전제("BomLens 산출→TRUSCA 소비")는 **성립 안 함**. BomLens 내부 로드맵(`improvement-roadmap.md:75`)이 도달성 분석을 정책 게이트·triage·VEX와 함께 **"포털(TRUSCA)의 영역"으로 명시 분류**하고 무상태 로컬 도구 정체성은 불변 선언 → 산출 주체가 될 의사 없음. 한편 **TRUSCA는 Go 도달성(govulncheck)을 이미 탑재**(`tasks/scan_reachability.py`, v2.3 r1). 따라서 C4는 "TRUSCA 자체 다언어 확장"으로 재정의되며, 오프라인 OSS 콜그래프 도구 부재(상용 해자)로 보류. 상세: `commercial-parity-candidates.md` C4 | ## 리뷰 이력 @@ -67,4 +70,5 @@ BomLens 내부 방향 문서(`bomlens-internal/identity-and-direction.md`)가 | 2026-07-03 (5차) | `17d6e59` → `2591230` | Phase E 착수 전 리뷰. v1.6.0 태그 신설이나 기준점 이후 실질 변경은 릴리즈 chore 1건뿐(데스크톱·G7·스캐너 수정 묶음, 전부 기존 격차/역할경계 범위) — 새 격차 없음. #7 in-progress | | 2026-07-03 (완료 스윕) | (기준점 유지 `2591230`) | Phase E~I 연속 완료: #7 카탈로그 확장(#451)·#6 diff e2e(#452)·#8 Excel(#454)·#9 의존성 그래프(#455)·#10 전역 검색(#456)·#12 릴리즈 게이트(#457). 부수: jsonata CVE-2026-52746 .trivyignore 억제(#453, 저장소 전역 image-scan 언블록). **open 격차는 #11(SCANOSS, 조건부 Phase J)만 남음.** #12는 코드 머지 완료, v0.13.0 태그에서 게이트 실동작 최종 확인 예정 | | 2026-07-04 (6차) | `2591230` → `9cc37e0` | Phase J 종료 후 리뷰. 기준점 이후 신규는 #329(firmware CVE DB 게이팅)뿐 — 펌웨어는 역할경계(#13), 새 격차 없음. **#11 SCANOSS closed(#459) — 마지막 격차 마감. 격차 표 P1~P3 실질 전부 closed, open 없음(역할경계 2건 제외).** Phase J 부수로 워커 이미지 linux-libc-dev 커널헤더 제거(Trivy DB 갱신發 76 CVE 영구 해소, #453과 같은 클래스지만 억제 대신 durable 제거) | +| 2026-07-18 (8차) | `5a62094` → `6b2ca03` | v1.8.0~v1.8.2 + 25커밋 리뷰(C4 트랙 재평가 겸). **C4 전제 폐기**: BomLens는 도달성 분석을 "포털의 영역"으로 명시 분류하고 무상태 정체성 불변 선언 → "BomLens 산출→TRUSCA 소비" 구도 불가. TRUSCA는 Go 도달성(govulncheck)을 이미 탑재하므로 C4는 자체 다언어 확장으로 재정의·보류(OSS 콜그래프 도구 부재). **부수 발견·수정**: Wave 7 문서(analysis-types)와 기존 comparison·data-sources가 도달성을 "planned·미탑재"로 오기 → Go govulncheck 실탑재에 맞게 정정. **신규 격차**: 버전 currency/staleness(#18 채택→구현), 규제 크로스워크(#19 보류)·copyleft 강도(#20 보류). 역할경계: SPDX 2.3 생성, 공급사 SBOM 검증 규칙, 펌웨어 인덱스, 대용량 테이블 가상스크롤 | | 2026-07-11 (7차) | `9cc37e0` → `5a62094` | v1.7.0 릴리즈 + 후속 27커밋, 총 80커밋 리뷰. 스캔 정밀도 연작이 핵심: 런타임 스코프 필터(#331/#335/#337/#341)·EOL 플래그(#368)·iOS lockfile(#347) — 신규 격차 3건(#15~#17) 판정 즉시 Phase K·L·M 으로 전부 구현·closed. 격차 아님: 펌웨어 CPE 인덱스(#330, 역할경계 #13), Trivy 0.72 범프(TRUSCA 기보유), Windows/문서 인프라. 부수 확인: BomLens 웹 UI 에 **TRUSCA 업로드 기능**(#336) 탑재 — 격차가 아니라 연계 실동작 시작. 후속 백로그: Android release-classpath 스코프 필터(워커 Android SDK 탑재 시), 컨테이너 스캔의 Trivy `eosl`(이미지 OS 단위) 표면화 | diff --git a/docs/completeness-master-plan.md b/docs/completeness-master-plan.md index 8b34d261..81b312af 100644 --- a/docs/completeness-master-plan.md +++ b/docs/completeness-master-plan.md @@ -75,15 +75,13 @@ v0.13.1 기준 BomLens 격차 17건은 전부 해소됐고, 남은 완성도 과 **v0.17.0 종결**: C1b 드롭 + W9-#53 출하 + W9-#55/#56 미채택으로 v0.17.0 UX 확장 트랙 마감. 남은 로드맵은 조건부 트랙 C4(BomLens 협의 선행)와 §7 상시 부채뿐. -## 6. 조건부 트랙 C4 — 다언어 도달성 분석 (BomLens 협업) +## 6. 조건부 트랙 C4 — 다언어 도달성 분석 (전제 폐기 → 재정의·보류) -상용 대비 최대 격차이나 BomLens 스코프 합의가 선행 조건. 합의 준비물까지만 이 플랜에서 진행한다. +**2026-07-18 재평가**: C4의 원 전제("BomLens가 call-graph 산출 → TRUSCA가 ingest")는 폐기한다. BomLens 조사(파리티 8차) 결과 BomLens는 도달성 분석을 정책 게이트·triage·VEX와 함께 **"포털(TRUSCA)의 영역"으로 명시 분류**하고(`bomlens-internal/improvement-roadmap.md:75`) 무상태 로컬 도구 정체성을 불변 선언 → 산출 주체가 될 의사가 없다. 따라서 C4-1(인터페이스 설계)·C4-2(협의 제안)는 상류 전제가 사라져 무의미. -| # | 항목 | 상태 | -|---|------|------| -| C4-1 | 인터페이스 설계 문서 — BomLens call-graph 산출 포맷 + TRUSCA ingest 스키마 초안 (ADR) | ⏳ | -| C4-2 | 협의 제안서 — 대상 언어 우선순위(Java·JS), 산출물 경계, 검증 방법 | ⏳ | -| C4-3 | 합의 확정 시 별도 릴리즈 트랙으로 분리해 이 문서 갱신. 미확정 상태로 구현 착수 금지 | — | +**재정의**: C4 = "TRUSCA 자체 다언어 도달성". 이미 **Go 도달성은 탑재 완료**(`tasks/scan_reachability.py`, govulncheck, v2.3 r1 — 소스 스캔 후 best-effort, 기본 ON, 게이트 신호로도 사용). 남은 격차는 Java·JS·Python 등으로의 확장인데, **오프라인·OSS 콜그래프 도구가 사실상 부재**(상용 Black Duck·Snyk의 독점 해자)라 연구성 대형 투자가 필요. + +**결정**: 실사용자·수요 없는 현 단계에서 다언어 확장은 **보류**. 가용한 오프라인 OSS 도달성 분석기가 특정 생태계에 등장하면 그때 해당 언어부터 착수(Go 파이프라인이 어댑터 패턴 선례). C4-1/C4-2는 폐기, C4-3(미확정 구현 금지)는 유지. ## 7. 상시 트랙 — 부채 청산·유지 (우선순위 낮음, 관련 코드 작업에 편승) @@ -93,6 +91,7 @@ v0.13.1 기준 BomLens 격차 17건은 전부 해소됐고, 남은 완성도 과 - aiosmtplib 3→5 major 업그레이드 (별도 PR) - Android release-classpath 스코프 필터 — 워커 Android SDK 탑재 선행, 수요 확인 전 보류 - BomLens 예고 기능 감시 — `docs/bomlens-parity-review.md` 감시 목록을 BomLens 릴리즈 태그마다 재점검 +- **버전 currency/staleness (파리티 #18, 8차 채택 → 구현 착수)** — EOL과 별개 축("최신 패치 대비 낙후·releases-behind"). 오프라인(같은 릴리스 라인 내 낙후)은 EOL 스냅샷 인프라 재사용, deps.dev 절대최신은 egress라 air-gap 게이트 필요. W9-#53 업그레이드 클러스터와 시너지 - license_fetcher 하드닝 (W8-#49 리뷰 후속, 6개 fetcher 공통): ① `quote(name, safe="")` 백필(현재 crates/pypi/maven/pkggo는 `safe='/'` 상속 — in-registry 경로 traversal 방어, gem/nuget은 W8-#49에서 이미 적용), ② `base.request_with_retry`에 응답 본문 크기 상한(디컴프레션 밤 방어, 공유 코드라 전 fetcher 일괄) ## 8. 검증 기준 (릴리즈별)