히스토리

• 레거시 라이선스 컴플라이언스 분석기(License-Scanning.gitlab-ci.yml)가 GitLab 17.0에서 제거되었습니다.
• GitLab 17.5에서 CycloneDX 보고서 아티팩트를 라이선스 정보의 데이터 소스로 사용하는
• GitLab 17.6에서 CycloneDX 보고서 아티팩트를 라이선스 정보의 데이터 소스로 사용하는 기능이 기본적으로 활성화되었습니다. 필요하면 기능을 비활성화할 수 있도록 license_scanning_with_sbom_licenses 기능 플래그는 그대로 남아 있었습니다.
• GitLab 17.8에서 license_scanning_with_sbom_licenses 기능 플래그가 제거되었습니다.

사용 중인 라이선스를 탐지하기 위해 라이선스 컴플라이언스는 의존성 스캔 job을 실행하고, 그 job이 생성한 CycloneDX 소프트웨어 자재 명세서(SBOM)를 분석합니다. 이 스캔 방식은 SPDX 목록에 정의된 600가지가 넘는 라이선스 유형을 파싱하고 식별할 수 있습니다. 지원되는 언어에 대해 CycloneDX 보고서 아티팩트를 생성하고 GitLab CycloneDX 속성 분류 체계를 따른다면, 서드파티 스캐너로 의존성 목록을 생성할 수도 있습니다. 그 밖의 라이선스를 제공하는 기능은 에픽 10861에서 추적하고 있습니다.

구성#

CycloneDX 파일의 라이선스 스캐닝을 활성화하려면 다음 방법을 사용합니다.

• 의존성 스캔 템플릿 사용
  • 의존성 스캔을 켜고 사전 요구 사항이 충족되었는지 확인합니다.
  • GitLab Self-Managed에서는 GitLab 인스턴스의 Admin 영역에서 동기화할 패키지 레지스트리 메타데이터를 선택할 수 있습니다. 이 데이터 동기화가 동작하려면 GitLab 인스턴스에서 storage.googleapis.com과 pmdb-dist-svc.runway.gitlab.net 도메인으로 나가는 네트워크 트래픽을 허용해야 합니다. 네트워크 연결이 제한되거나 없는 경우에는 오프라인 환경에서 실행 절을 참고합니다.
• 또는 해당 패키지 레지스트리에 대해 CI/CD 컴포넌트를 사용합니다.

지원되는 언어 및 패키지 관리자#

히스토리

• GitLab 17.9에서 Swift 지원이 도입되었습니다.
• GitLab 18.10에서 Dart 지원이 도입되었습니다.

다음 언어와 패키지 관리자에서 라이선스 스캐닝을 지원합니다.

각주:

1. stdlib 같은 Go 표준 라이브러리는 지원되지 않으며 unknown 라이선스로 표시됩니다. 이에 대한 지원은 이슈 480305에서 추적하고 있습니다.

지원되는 파일과 버전은 의존성 스캔에서 지원하는 것과 동일합니다.

데이터 소스#

지원되는 패키지의 라이선스 정보는 아래 소스에서 가져옵니다. GitLab은 원본 데이터에 추가 처리를 수행하며, 여기에는 표기 변형을 표준 라이선스 이름으로 매핑하는 작업이 포함됩니다.

라이선스 표현식#

히스토리

• GitLab 19.3에서 CycloneDX SBOM의 SPDX 라이선스 표현식 지원이 도입되었습니다.
• GitLab 19.4에서 PMDB의 SPDX 라이선스 표현식 지원이 도입되었습니다.

GitLab은 CycloneDX SBOM의 expression 필드에서 SPDX 라이선스 표현식을 읽으며, 여기에는 SPDX 표준이 아닌 사용자 지정 라이선스를 위한 LicenseRef-[NAME] 구문도 포함됩니다. 컴포넌트의 SBOM 항목에 expression 이 있으면 GitLab은 표현식 전체를 저장하고 평가합니다. CycloneDX SBOM에 라이선스 정보가 없으면 GitLab은 라이선스 표현식을 지원하는 PMDB 라이선스 데이터와 컴포넌트를 대조합니다.

라이선스 표현식은 라이선스 승인 정책에서 지원됩니다. 정책이 대상으로 삼은 라이선스가 컴포넌트 표현식의 한 항으로 포함되어 있으면, 정책은 표현식 전체를 기준으로 정확하게 평가됩니다.

감지된 라이선스를 기준으로 머지 리퀘스트 차단#

라이선스 승인 정책을 구성하면 감지된 라이선스를 기준으로 머지 리퀘스트에 승인을 요구할 수 있습니다.

오프라인 환경에서 실행#

인터넷을 통한 외부 리소스 접근이 제한적이거나 차단되어 있거나 간헐적인 환경의 인스턴스에서는 CycloneDX 보고서의 라이선스를 정상적으로 스캔하기 위해 몇 가지 조정이 필요합니다. 자세한 내용은 오프라인 인스턴스용 패키지 메타데이터 데이터베이스를 참고합니다.

CycloneDX 보고서를 라이선스 정보 소스로 사용#

히스토리

• GitLab 17.5에서 license_scanning_with_sbom_licenses라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 17.6에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에 활성화되었습니다.
• GitLab 17.8에서 일반 공급으로 전환되었습니다. license_scanning_with_sbom_licenses 기능 플래그가 제거되었습니다.
• GitLab 19.3에서 SPDX 라이선스 표현식 지원이 도입되었습니다.

라이선스 스캐닝은 사용할 수 있는 경우 CycloneDX JSON SBOM의 licenses 필드를 사용합니다. 라이선스 정보를 사용할 수 없으면 외부 라이선스 데이터베이스에서 가져온 라이선스 정보를 사용합니다. 라이선스 정보는 유효한 SPDX 식별자, 라이선스 이름 또는 SPDX 라이선스 표현식으로 제공할 수 있습니다. 라이선스 필드 형식에 대한 자세한 내용은 CycloneDX 사양에서 확인할 수 있습니다.

licenses 필드를 제공하는 호환 CycloneDX SBOM 생성기는 CycloneDX Tool Center에서 확인할 수 있습니다.

라이선스 정보 소스 구성#

히스토리

• GitLab 18.3에서 도입되었습니다.

두 소스를 모두 사용할 수 있을 때 어느 라이선스 정보 소스를 사용할지 선택합니다.

프로젝트에서 사용할 라이선스 정보 소스를 구성하려면 다음을 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Secure > Security configuration을 선택합니다.
3. License information source 섹션에서 다음 중 하나를 선택합니다.
   • SBOM(기본값) - CycloneDX 보고서의 라이선스 정보를 사용합니다.
     • 스캐너는 프로젝트의 /gl-sbom-*.cdx.json에 있는 보고서에서 라이선스 정보를 읽습니다.
     • 라이선스를 덮어쓰려면 이 파일의 라이선스 데이터를 직접 수정합니다.
   • PMDB - 외부 라이선스 데이터베이스의 라이선스 정보를 사용합니다.

CycloneDX 파일의 라이선스 스캐닝 활성화 또는 비활성화#

히스토리

• GitLab 19.0에서 license_scanning_for_cyclonedx_setting이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 19.2에서 일반 공급으로 전환되었습니다. license_scanning_for_cyclonedx_setting 기능 플래그가 제거되었습니다.

라이선스 스캐닝은 수집된 모든 CycloneDX SBOM 파일에서 기본적으로 실행됩니다. Security configuration 페이지에서 프로젝트별로 라이선스 스캐닝을 비활성화할 수 있습니다. 비활성화하면 SBOM 수집으로 얻은 라이선스가 의존성 목록에 unknown으로 표시됩니다.

사전 요구 사항:

• 프로젝트에 대한 Maintainer, Owner 또는 Security Manager 권한이 있어야 합니다.

CycloneDX 파일의 라이선스 스캐닝을 활성화하거나 비활성화하려면 다음을 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Secure > Security configuration을 선택합니다.
3. License Scanning for CycloneDX 섹션에서 토글을 켜거나 끕니다.

문제 해결#

CycloneDX 파일이 스캔되지 않고 결과가 표시되지 않는 경우#

CycloneDX 파일이 CycloneDX JSON 사양을 따르는지 확인합니다. 이 사양은 중복 항목을 허용하지 않습니다. SBOM 파일이 여러 개인 프로젝트는 각 SBOM 파일을 개별 CI 보고서 아티팩트로 보고하거나, CI 파이프라인에서 SBOM을 병합하는 경우 중복을 제거해야 합니다.

다음과 같이 CycloneDX SBOM 파일을 CycloneDX JSON specification 기준으로 검증할 수 있습니다.

$ docker run -it --rm -v "$PWD:/my-cyclonedx-sboms" -w /my-cyclonedx-sboms cyclonedx/cyclonedx-cli:latest cyclonedx validate --input-version v1_4 --input-file gl-sbom-all.cdx.json

Validating JSON BOM...
BOM validated successfully.

예를 들어 중복 컴포넌트가 있어 JSON BOM 검증에 실패하면 다음과 같이 출력됩니다.

Validation failed: Found duplicates at the following index pairs: "(A, B), (C, D)"
#/properties/components/uniqueItems

이 문제는 중복 컴포넌트를 만드는 job 정의를 재정의해 jq로 gl-sbom-*.cdx.json 보고서에서 중복 컴포넌트를 제거하도록 CI 템플릿을 수정하면 해결할 수 있습니다. 예를 들어 다음 설정은 gemnasium-dependency_scanning job이 생성한 gl-sbom-gem-bundler.cdx.json 보고서 파일에서 중복 컴포넌트를 제거합니다.

include:
  - template: Jobs/Dependency-Scanning.gitlab-ci.yml

gemnasium-dependency_scanning:
  after_script:
    - apk update && apk add jq
    - jq '.components |= unique' gl-sbom-gem-bundler.cdx.json > tmp.json && mv tmp.json gl-sbom-gem-bundler.cdx.json

사용하지 않는 라이선스 데이터 제거#

GitLab 15.9에서 릴리스된 라이선스 스캐닝 변경 사항은 인스턴스에 상당한 추가 디스크 공간을 요구했습니다. 이 문제는 GitLab 16.3에서 패키지 메타데이터 테이블의 디스크 사용량 축소 에픽으로 해결되었습니다. 다만 GitLab 15.9와 16.3 사이에 인스턴스에서 라이선스 스캐닝을 실행했다면 불필요한 데이터를 제거하는 편이 좋습니다.

불필요한 데이터를 제거하려면 다음을 수행합니다.

1. package_metadata_synchronization 기능 플래그가 현재 활성화되어 있거나 이전에 활성화된 적이 있는지 확인하고, 그렇다면 비활성화합니다. Rails 콘솔에서 다음 명령을 실행합니다.

   Feature.enabled?(:package_metadata_synchronization) && Feature.disable(:package_metadata_synchronization)
   

2. 데이터베이스에 더 이상 사용하지 않는 데이터가 있는지 확인합니다.

   PackageMetadata::PackageVersionLicense.count
   PackageMetadata::PackageVersion.count
   

3. 데이터베이스에 더 이상 사용하지 않는 데이터가 있으면 다음 명령을 순서대로 실행해 제거합니다.

   ActiveRecord::Base.connection.execute('SET statement_timeout TO 0')
   PackageMetadata::PackageVersionLicense.delete_all
   PackageMetadata::PackageVersion.delete_all
   

CycloneDX SBOM에 대한 취약점 스캔 결과가 없는 경우#

CycloneDX 파일의 라이선스는 스캔되는데 취약점 스캔 결과가 없다면 사용자 지정 또는 병합된 CycloneDX SBOM에 대한 취약점 스캔 결과가 없는 경우를 참고합니다.

의존성 라이선스가 unknown으로 표시되는 경우#

오픈 소스 라이선스 정보는 데이터베이스에 저장되며 프로젝트 의존성의 라이선스를 확인하는 데 사용됩니다. 라이선스 정보가 없거나 아직 데이터베이스에 반영되지 않았다면 의존성의 라이선스가 unknown으로 표시될 수 있습니다.

의존성 라이선스 조회는 파이프라인이 끝날 때 수행되므로, 그 시점에 데이터를 사용할 수 없었다면 unknown 라이선스가 기록됩니다. 이 라이선스는 다음 파이프라인이 실행되어 라이선스를 다시 조회할 때까지 그대로 표시됩니다. 조회 결과 의존성의 라이선스가 변경된 것으로 확인되면 그때 새 라이선스가 표시됩니다.