CycloneDX 라이선스 수집
GitLab v19.6요약
초점: CycloneDX SBOM에 선언된 라이선스가 sbom_occurrences.licenses jsonb 열이 되는 과정입니다. 모든 경로는 ee/ 아래에 있습니다. A["Parsers::Sbom::Cyclonedx#parse_components"] --> B["Parsers::Sbom::Component#licenses<br/>(reads component.licenses[])"] B --> C["License::C...
초점: CycloneDX SBOM에 선언된 라이선스가 sbom_occurrences.licenses jsonb 열이 되는 과정입니다.
CycloneDX 컴포넌트는 SPDX 식별자(license.id), 자유 형식 이름(license.name), SPDX 표현식(expression)의
세 가지 형식으로 라이선스를 선언할 수 있습니다. 세 형식은 구문 분석 시점에 갈라지고 수집 과정에서 다시 합쳐집니다.
수집에서는 SPDX 식별자가 Package Metadata DB(PMDB)의 이름 및 URL 조회를 이끌고,
표현식은 기능 플래그 뒤에서 제어됩니다.
모든 경로는 ee/ 아래에 있습니다. 구문 분석은 SPDX 해석 없이 Reports::Sbom::License 값 객체를 생성하고,
수집은 소스를 해석해 결과를 sbom_occurrences에 기록합니다. 별도의
읽기 경로(LicenseScanning::SbomScanner)는 같은 리졸버를 재사용해 머지 리퀘스트
라이선스 위젯, 파이프라인 Licenses 탭, 라이선스 컴플라이언스 보고서에 데이터를 제공합니다. 이 경로는 두 플래그가
제어하며 둘 다 기본적으로 비활성화되어 있습니다. cyclonedx_license_expression_ingestion(표현식이 저장되는 라이선스에
남을지 여부)과 license_expression_checker(수집 이후 단계에서 표현식을 인식하는 정책 검사기)입니다.
소스 코드 보기
flowchart TD
accTitle: CycloneDX license ingestion
accDescr: How a CycloneDX component license in id, name, or expression form is parsed, resolved through the license fetcher, and persisted to sbom_occurrences, plus the separate read path that feeds the license widgets.
A["Parsers::Sbom::Cyclonedx#parse_components"] --> B["Parsers::Sbom::Component#licenses<br/>(reads component.licenses[])"]
B --> C["License::Common.parse (fork point)"]
C --> C1{"expression present?<br/>(CycloneDX oneOf: expression XOR license)"}
C1 -->|"yes"| C2["Reports::Sbom::License(expression:)"]
C1 -->|"no"| C3["read license.id / name / url<br/>check_license_name!: SPDX-valid name → id (Trivy 0.65.0 fix)"]
C2 --> D["Reports::Sbom::License<br/>{ spdx_identifier, name, url, expression }"]
C3 --> D
subgraph ING["ingestion (Tasks::IngestOccurrences)"]
E["LicensesFetcher.fetch(component)<br/>gated by security_setting.license_scanning_for_cyclonedx_enabled"] --> G{"component has<br/>SBOM licenses?"}
G -->|"yes"| H["use SBOM licenses"]
G -->|"no"| I["PackageLicenses → PMDB pm_packages / pm_licenses<br/>(else UNKNOWN_LICENSE)"]
H --> J["PackageLicenses#licenses_for_component<br/>usable_licenses / include_expression?<br/>(FF cyclonedx_license_expression_ingestion)"]
I --> J
J --> K["map_from: keep {spdx_identifier, name, url, expression}<br/>name ||= expression (schema + non-null GraphQL name)"]
end
D --> E
K -->|"expression is persisted under the name attribute"| L[("sbom_occurrences.licenses (jsonb)<br/>schema sbom_occurrences-licenses.json<br/>anyOf: spdx_identifier OR name")]
D -.->|"separate READ path"| M["LicenseScanning::SbomScanner#report<br/>→ PackageLicenses → LicenseScanning::Report"]
M -.-> N["MR license widget /<br/>pipeline Licenses tab /<br/>license compliance report"]
L -.-> O["dependency list<br/>(GraphQL LicenseType, REST)"]
표현식은 전용 필드가 아니라 name 속성으로 저장됩니다. sbom_occurrences.licenses에는 spdx_identifier 또는
name이 필요하고(expression만으로는 안 됨) GraphQL LicenseType#name은 null일 수 없으므로,
map_from이 name ||= expression을 설정합니다. 표현식만 있을 때는 name과 expression이 같은 문자열을 가집니다.
단계#
- 컴포넌트에서 라이선스 읽기.
Parsers::Sbom::Cyclonedx#parse_components가 컴포넌트를 순회하고,Parsers::Sbom::Component#licenses가 각licenses[]항목을License::Common.parse로 매핑합니다. - 표현식과 ID/이름으로 분기.
License::Common#parse는 먼저expression을 확인합니다(CycloneDXoneOf: 항목은{expression}또는{license: {id, name}}중 하나). 표현식이면Reports::Sbom::License(expression:)를 만들고, 아니면license['id'],license['name'],url을 읽습니다.check_license_name!는name이 유효한 SPDX 식별자이면name을id로 옮기며, 이는 Trivy 0.65.0 버그에 대한 우회책입니다. - 보고서 값 객체. 두 분기 모두
spdx_identifier,name,url,expression을 일반 속성으로 가진Reports::Sbom::License를 생성합니다. 구문 분석 시점에는 SPDX 해석이 일어나지 않습니다. - 수집이 페처에 요청.
Tasks::IngestOccurrences는Sbom::Ingestion::LicensesFetcher#fetch로licenses:를 설정하며, 이는security_setting.license_scanning_for_cyclonedx_enabled로 제어됩니다. - 소스 해석. SBOM이 제공한 라이선스가 있는 컴포넌트는 그 라이선스를 사용합니다. 없는 컴포넌트는
Gitlab::LicenseScanning::PackageLicenses(pm_packages,pm_licenses)를 통해 PMDB로 대체하며, 사용할 수 있는 것이 없으면 단일UNKNOWN_LICENSE를 사용합니다. - 표현식 제어(기능 플래그).
PackageLicenses에서usable_licenses는 표현식만 있는 라이선스를 제외하고,include_expression?는 프로젝트에cyclonedx_license_expression_ingestion이 활성화된 경우에만expression키를 추가합니다. 플래그가 꺼져 있으면 동작은 이전의 ID와 이름만 사용하던 동작과 같습니다. - 이름 대체와 저장.
map_from은spdx_identifier,name,url,expression을 유지하고name ||= expression을 설정합니다. JSON 스키마와 null이 아닌 GraphQLLicenseType#name에 이름이 필요한데 표현식만 있는 행에는 이름이 없기 때문입니다. 결과는sbom_occurrences.licensesjsonb 열에 기록되며sbom_occurrences-licenses.json으로 검증됩니다 (anyOf는spdx_identifier또는name을 요구하고 표현식만으로는 안 됩니다). - 별도의 읽기 경로. 수집과 별개로
LicenseScanning::SbomScanner#report가 최신 SBOM 파이프라인에PackageLicenses를 실행해LicenseScanning::Report를 만들며, 이는 머지 리퀘스트 라이선스 위젯, 파이프라인 Licenses 탭, 라이선스 컴플라이언스 보고서가 사용합니다. 저장된sbom_occurrences.licenses는 의존성 목록(GraphQL과 REST)에 제공됩니다. - ID, 이름, 표현식 비교.
id는 기본 키이며 PMDB의 이름 및 URL 조회를 이끕니다.name은 표현식만 있을 때 표현식 문자열로 대체됩니다.expression은 플래그가 켜진 경우에만 저장되며, 수집 시점이 아니라 이후 정책 및 컴플라이언스 계층에서Gitlab::SPDX::ExpressionParser가 구문 분석하고 평가합니다.
관련 항목#
- CycloneDX에서 보안 결과로는 CycloneDX 파서를 공유하며 같은 SBOM 컴포넌트에 대한 취약점 결과를 생성합니다.
- 새로운 의존성 스캔, SBOM 스캔 API는 여기서 사용하는 CycloneDX SBOM을 생성하는 분석기 대상 API입니다.
- GitLab CycloneDX 속성 분류 체계는 파서가 검증하는 SBOM 형식입니다.