| --- | --- | | dependency-scanning | registry.gitlab.com/security-products/dependency-scanning:2 | 19.x | | dependency-scanning:maven-resolution | registry.gitlab.com/security-products/dependency-resolution/ubi9/openjdk-21:1 | 18.x, 19.x | | dependency-scanning:gradle-resolution | registry.gitlab.com/security-products/dependency-resolution/ubi9/openjdk-17-with-gradle-8:1 | 19.x | | dependency-scanning:python-resolution | registry.gitlab.com/security-products/dependency-resolution/ubi9/python-312-minimal-with-piptools-7:9 | 18.x,19.x |

현재 이미지는 베이스 이미지 공급업체의 업스트림 패치를 반영하기 위해 정기적으로 재빌드됩니다.

이전 이미지#

이 이미지들은 더 이상 사용되지 않으며(deprecated) 버그 수정이나 새 기능이 제공되지 않습니다. 컨테이너 레지스트리에서 계속 사용할 수 있으며, 해당 GitLab 버전과 함께 계속 작동합니다. 더 이상 사용되지 않는 이미지를 최신 GitLab 버전과 함께 사용하는 것은 지원되지 않으며 예상치 못한 결과가 발생할 수 있습니다.

FIPS 준수#

종속성 스캐닝 분석기 이미지와 모든 종속성 해석 이미지는 FIPS 140 인증 암호화 모듈을 사용하는 Red Hat UBI를 기반으로 합니다. FIPS가 활성화된 환경에서 추가 구성은 필요하지 않습니다.

결과 이해하기#

종속성 스캐닝 분석기의 출력:

• 감지된 지원 잠금 파일(lockfile) 또는 의존성 그래프 내보내기(dependency graph export)마다 CycloneDX SBOM을 생성합니다.

• 스캔된 모든 SBOM 문서에 대한 단일 종속성 스캐닝 보고서(GitLab.com 및 GitLab Self-Managed 전용).

  분석기가 지원되는 파일을 찾지 못하면 종속성 스캐닝 job이 성공적으로 완료되고 CI/CD job 로그에 경고가 출력됩니다. 이 경우 CycloneDX SBOM이나 종속성 스캐닝 보고서는 생성되지 않습니다.

CycloneDX 소프트웨어 자재 명세서#

종속성 스캐닝 분석기는 지원되는 잠금 파일, 의존성 그래프, 또는 매니페스트 파일이 감지된 각 디렉터리에 대해 CycloneDX Software Bill of Materials(SBOM)를 출력합니다. CycloneDX SBOM은 job 아티팩트로 생성됩니다.

CycloneDX SBOM은 다음과 같습니다:

• gl-sbom-<package-type>-<package-manager>.cdx.json으로 이름이 지정됩니다.

• 종속성 스캐닝 job의 job 아티팩트로 제공됩니다.

• cyclonedx 보고서로 업로드됩니다.

• 감지된 잠금 파일 또는 의존성 그래프 파일과 동일한 디렉터리에 저장됩니다.

예를 들어, 프로젝트 구조가 다음과 같은 경우:

.
├── ruby-project/
│   └── Gemfile.lock
├── ruby-project-2/
│   └── Gemfile.lock
└── php-project/
    └── composer.lock

다음 CycloneDX SBOM이 job 아티팩트로 생성됩니다:

.
├── ruby-project/
│   ├── Gemfile.lock
│   └── gl-sbom-gem-bundler.cdx.json
├── ruby-project-2/
│   ├── Gemfile.lock
│   └── gl-sbom-gem-bundler.cdx.json
└── php-project/
    ├── composer.lock
    └── gl-sbom-packagist-composer.cdx.json

종속성 스캐닝 보고서#

• Offering: GitLab.com, GitLab Self-Managed
  

종속성 스캐닝 분석기는 CycloneDX SBOM 파일에서 식별된 의존성에서 발견된 모든 취약점을 문서화하는 종속성 스캐닝 보고서를 생성합니다.

종속성 스캐닝 보고서는:

• gl-dependency-scanning-report.json으로 이름이 지정됩니다.

• 종속성 스캐닝 job의 job 아티팩트로 제공됩니다.

• dependency_scanning 보고서로 업로드됩니다.

• 프로젝트의 루트 디렉터리에 저장됩니다.

스캔 성능 향상#

종속성 스캐닝 성능의 주요 요인은 스캔할 의존성 수입니다. 기본적으로 종속성 스캐닝은 다음 범위로 동작합니다:

• 지원되는 모든 언어와 파일이 포함됩니다.

• 루트 디렉터리와 직속 하위 디렉터리가 포함됩니다.

• 숨겨진 디렉터리는 제외됩니다.

성능을 향상시키려면 특정 경로를 제외하거나, 스캔 디렉터리 깊이를 제한하거나, 개발 및 테스트 의존성을 제외할 수 있습니다.

스캔에서 경로 제외#

스캔 성능을 향상시키기 위해 경로를 제외합니다. 예를 들어 문서가 포함된 경로를 제외할 수 있습니다. 경로를 제외할 때는 취약점이 숨겨지지 않도록 선택적으로 지정하세요.

제외할 경로는 .gitlab-ci.yml 파일에 나열합니다:

• 종속성 스캐닝 템플릿의 경우 DS_EXCLUDED_PATHS CI/CD 변수를 사용합니다.

• 종속성 스캐닝 CI/CD 컴포넌트의 경우 excluded_paths spec 입력을 사용합니다.

제외 패턴은 다음 규칙을 따릅니다:

• 슬래시가 없는 패턴은 프로젝트의 모든 깊이에서 파일 또는 디렉터리 이름과 일치합니다. 예를 들어 test는 ./test 및 src/test와 일치합니다.

• 슬래시가 있는 패턴은 해당 패턴으로 시작하는 경로와 일치합니다. 예를 들어 a/b는 a/b 및 a/b/c와 일치하지만 c/a/b와는 일치하지 않습니다.

• 표준 glob 와일드카드가 지원됩니다. 예를 들어 a/**/b는 a/b, a/x/b, a/x/y/b와 일치합니다.

• 선행 및 후행 슬래시는 무시됩니다. 예를 들어 /build와 build/는 build와 동일한 결과와 일치합니다.

스캔 디렉터리 깊이 제한#

기본적으로 스캔은 리포지터리의 루트 디렉터리와 직속 하위 디렉터리만 패키지 매니저 파일을 검색합니다. 스캔 성능을 향상시키려면 최대 디렉터리 깊이를 1로 설정하여 검색을 리포지터리의 루트 디렉터리로만 제한하세요. 리포지터리의 모든 관련 패키지 매니저 파일이 포함되도록 주의하세요.

.gitlab-ci.yml 파일에서 최대 스캔 디렉터리 깊이를 지정하려면:

• 종속성 스캐닝 템플릿의 경우 DS_MAX_DEPTH CI/CD 변수를 사용합니다.

• 종속성 스캐닝 CI/CD 컴포넌트의 경우 max_scan_depth spec 입력을 사용합니다.

다음 예에서 DS_MAX_DEPTH를 1로 설정하면 종속성 스캐닝은 timer 디렉터리만 패키지 매니저 파일을 검색합니다. 하위 디렉터리는 스캔하지 않습니다.

timer
├── integration
└── source

개발 및 테스트 의존성 제외#

기본적으로 개발 및 테스트 의존성이 스캔에 포함됩니다. 스캔 성능을 향상시키려면 다음 중 하나를 설정하여 제외합니다:

• CI/CD 변수 DS_INCLUDE_DEV_DEPENDENCIES를 "false"로 설정

• CI/CD 컴포넌트 입력 include_dev_dependencies를 false로 설정

다음 패키지 매니저를 사용하는 프로젝트만 지원됩니다: Composer, Conda, Gradle, Maven, npm, pnpm, Pipenv, Poetry, uv.

롤아웃#

단일 프로젝트에서 SBOM을 활용한 종속성 스캐닝 결과에 확신이 생기면, 여러 프로젝트와 그룹으로 구현 범위를 확장할 수 있습니다. 자세한 내용은 여러 프로젝트에서 스캔 적용을 참조하세요.

고유한 요구 사항이 있는 경우 SBOM을 활용한 종속성 스캐닝은 오프라인 환경에서도 실행할 수 있습니다.

지원되는 패키지 유형#

보안 분석이 효과적이려면 SBOM 보고서에 나열된 컴포넌트가 GitLab advisory database에 해당하는 항목이 있어야 합니다.

GitLab SBOM Vulnerability Scanner는 다음 PURL 유형을 가진 컴포넌트에 대한 종속성 스캐닝 취약점을 보고할 수 있습니다:

• cargo

• composer

• conan

• gem

• golang

• maven

• npm

• nuget

• pypi

• swift

지원되는 언어 및 파일#

각주:

• 잠금 파일에 동일한 패키지에 대해 서로 다른 환경 마커를 가진 여러 항목이 포함된 경우(예: Python <3.11에 대한 numpy==2.2.6, Python ≥3.11에 대한 numpy==2.4.1), 첫 번째 항목만 파싱되고 보고됩니다.

패키지 해시 정보#

종속성 스캐닝 SBOM에는 가능한 경우 패키지 해시 정보가 포함됩니다. 이 정보는 현재 NuGet 패키지에 대해서만 제공됩니다. 패키지 해시는 SBOM 내 다음 위치에 나타나며, 패키지 무결성 및 신뢰성을 검증하는 데 사용할 수 있습니다:

• 전용 hashes 필드

• PURL qualifier

예시:

{
  "name": "Iesi.Collections",
  "version": "4.0.4",
  "purl": "pkg:nuget/Iesi.Collections@4.0.4?sha512=8e579b4a3bf66bb6a661f297114b0f0d27f6622f6bd3f164bef4fa0f2ede865ef3f1dbbe7531aa283bbe7d86e713e5ae233fefde9ad89b58e90658ccad8d69f9",
  "hashes": [
    {
      "alg": "SHA-512",
      "content": "8e579b4a3bf66bb6a661f297114b0f0d27f6622f6bd3f164bef4fa0f2ede865ef3f1dbbe7531aa283bbe7d86e713e5ae233fefde9ad89b58e90658ccad8d69f9"
    }
  ],
  "type": "library",
  "bom-ref": "pkg:nuget/Iesi.Collections@4.0.4?sha512=8e579b4a3bf66bb6a661f297114b0f0d27f6622f6bd3f164bef4fa0f2ede865ef3f1dbbe7531aa283bbe7d86e713e5ae233fefde9ad89b58e90658ccad8d69f9"
}

분석기 동작 사용자 정의#

분석기를 사용자 정의하는 방법은 활성화 솔루션에 따라 다릅니다.

GitLab 분석기의 모든 사용자 정의를 기본 브랜치에 병합하기 전에 머지 리퀘스트에서 테스트하세요.

그렇지 않으면 다수의 false positive를 포함한 예상치 못한 결과가 발생할 수 있습니다.

CI/CD 템플릿으로 동작 사용자 정의#

사용 가능한 spec 입력#

다음 spec 입력은 Dependency-Scanning.v2.gitlab-ci.yml 템플릿과 함께 사용할 수 있습니다.

사용 가능한 CI/CD 변수#

이 변수들은 spec 입력을 대체할 수 있으며 베타 latest 템플릿과도 호환됩니다.

종속성 스캐닝에 대한 머지 리퀘스트 파이프라인 비활성화#

기본적으로 Dependency-Scanning.v2.gitlab-ci.yml 템플릿은 머지 리퀘스트 파이프라인에서 종속성 스캐닝 job을 실행합니다. 프로젝트에서 다른 job에 대해 머지 리퀘스트 파이프라인을 사용하지 않는 경우, 각 머지 리퀘스트에 대해 두 개의 파이프라인이 실행될 수 있으며 다른 job은 별도의 브랜치 파이프라인에서 실행될 수 있습니다. 이 동작을 비활성화하려면 spec 입력 enable_mr_pipelines: false 또는 CI/CD 변수 AST_ENABLE_MR_PIPELINES: "false"를 설정하세요.

지원 파일이 없을 때 job 건너뛰기#

기본적으로 종속성 스캐닝 job은 프로젝트에 지원되는 파일이 없어도 템플릿이 포함된 모든 파이프라인에서 실행됩니다. 지원되는 파일이 감지되지 않을 때 job을 건너뛰려면 DS_SKIP_IF_NO_SUPPORTED_FILES를 "true"로 설정하세요:

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

variables:
  DS_SKIP_IF_NO_SUPPORTED_FILES: "true"

변수가 설정되면 프로젝트에 지원 파일 목록에 있는 파일이 하나 이상 포함되거나 DS_PIPCOMPILE_LOCKFILE_FILE_NAME_PATTERN, DS_PIP_MANIFEST_FILE_NAME_PATTERN, 또는 PIP_REQUIREMENTS_FILE(더 이상 사용되지 않음)로 사용자 정의 패턴이 설정된 경우에만 종속성 스캐닝 job이 실행됩니다.

사용자 정의 TLS 인증 기관#

종속성 스캐닝은 분석기 컨테이너 이미지에 기본으로 포함된 인증서 대신 SSL/TLS 연결에 사용자 정의 TLS 인증서를 사용할 수 있습니다.

사용자 정의 TLS 인증 기관 사용#

사용자 정의 TLS 인증 기관을 사용하려면 X.509 PEM 공개 키 인증서의 텍스트 표현을 CI/CD 변수 ADDITIONAL_CA_CERT_BUNDLE에 할당하세요.

예를 들어 .gitlab-ci.yml 파일에서 인증서를 구성하려면:

variables:
  ADDITIONAL_CA_CERT_BUNDLE: |
      -----BEGIN CERTIFICATE-----
      MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
      ...
      jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
      -----END CERTIFICATE-----

종속성 해석#

History

• Maven과 Python에 대해 GitLab 18.11에서 도입됨, 기본적으로 비활성화됨.

• GitLab 19.0에서 Gradle 지원 추가됨. 지원되는 모든 프로젝트에 대해 기본적으로 활성화됨.

프로젝트에 지원되는 잠금 파일 또는 의존성 그래프 내보내기가 리포지터리에 커밋되어 있지 않은 경우, 종속성 해석이 스캔 실행 전에 필요한 파일을 자동으로 생성할 수 있습니다.

종속성 해석은 프로젝트에서 지원되는 매니페스트 파일이 감지되면 자동으로 트리거됩니다. 해석 job은 최소한의 에코시스템 이미지(예: ubi9/openjdk-21)를 사용하여 .pre Stage에서 실행되며 잠금 파일 또는 의존성 그래프 내보내기를 네이티브로 생성합니다. 이 job들은 기존 잠금 파일이나 그래프 내보내기를 보존하고 없는 경우에만 생성합니다. 생성된 아티팩트는 test Stage의 dependency-scanning job에서 사용됩니다. 기본 이미지를 동등한 대안(예: eclipse-temurin:jdk-21)이나 필요한 빌드 도구가 포함된 사용자 정의 이미지로 대체할 수 있습니다.

다음 에코시스템이 종속성 해석을 지원합니다:

종속성 해석 사용자 정의#

사용 가능한 모든 옵션은 사용 가능한 spec 입력과 사용 가능한 CI/CD 변수를 참조하세요.

사용자 정의 종속성 해석 이미지 사용#

직접 이미지를 사용하려면 다음 입력을 설정할 수 있습니다:

• maven_resolution_image

• gradle_resolution_image

• python_resolution_image

예를 들어 maven 해석에 사용자 정의 이미지를 사용하려면:

include:
  - template: Jobs/Dependency-Scanning.v2.gitlab-ci.yml
    inputs:
      maven_resolution_image: "registry.gitlab.mycorp.com/eclipse-temurin:jdk-21"

또는 다음 CI/CD 변수를 설정할 수 있습니다:

• DS_MAVEN_RESOLUTION_IMAGE

• DS_GRADLE_RESOLUTION_IMAGE

• DS_PYTHON_RESOLUTION_IMAGE

종속성 해석 비활성화#

특정 에코시스템의 종속성 해석을 비활성화하려면 DS_DISABLED_RESOLUTION_JOBS CI/CD 변수 또는 disabled_resolution_jobs 입력을 사용합니다. 가능한 값: maven, gradle, python.

예를 들어 maven의 종속성 해석을 비활성화하려면:

variables:
  DS_DISABLED_RESOLUTION_JOBS: "maven"

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

종속성 해석의 보안 고려 사항#

종속성 해석 job은 CI/CD job 컨테이너에서 에코시스템 네이티브 빌드 도구(mvn, gradle, pip-compile)를 실행합니다. 이 도구들은 시작 시 확장 프로그램을 로드하거나 임의의 코드를 실행할 수 있는 환경 변수 및 구성 파일을 네이티브로 지원합니다. 여기에는 다음이 포함됩니다:

• Maven: MAVEN_ARGS, MAVEN_CLI_OPTS(레거시), MAVEN_OPTS, JAVA_TOOL_OPTIONS, -s 또는 --settings를 통해 참조된 모든 settings.xml, 그리고 pom.xml 또는 settings.xml에 선언된 <extensions>.

• Gradle: GRADLE_OPTS, JAVA_TOOL_OPTIONS, --init-script, 그리고 build.gradle 또는 build.gradle.kts의 최상위 Groovy 또는 Kotlin 코드.

• Python: PIP_INDEX_URL, PIP_EXTRA_INDEX_URL, setup.py, 잠금 파일 설치 훅.

이러한 CI/CD 변수를 설정하거나 프로젝트의 빌드 파일을 수정할 수 있는 사람은 해석 job에서 임의의 코드를 실행시킬 수 있습니다. 해석 job은 CI_JOB_TOKEN으로 실행되며, 범위 내의 마스킹된 CI/CD 변수에 접근하고, job이 진행되는 동안 프로젝트 리포지터리에 읽기 또는 쓰기가 가능합니다.

이 속성은 에코시스템 네이티브 빌드 도구에 고유한 것이며, 종속성 스캐닝에만 해당하는 것이 아닙니다. 해석 job을 민감한 실행 컨텍스트로 취급하세요.

권장 제어 방법:

• 앞서 나열된 변수를 정의하거나 재정의할 수 있는 사람을 제한하세요. 보호된 브랜치와 태그로 범위를 지정한 보호된 CI/CD 변수를 사용하세요. 개발자가 편집할 수 있는 .gitlab-ci.yml variables: 블록에는 설정하지 마세요.

• 표준 코드 리뷰 프로세스의 일환으로 MAVEN_ARGS, MAVEN_CLI_OPTS, GRADLE_OPTS, --init-script, 사용자 정의 settings.xml, pom.xml의 <extensions> 사용을 감사하세요.

• 스캔 실행 정책을 사용하여 종속성 스캐닝을 적용할 때 대상 프로젝트의 개발자 작성 variables:가 주입된 해석 job으로 흘러들어갑니다. 정책 프레임워크가 전달하는 변수를 검토하고 정책에서 빌드 도구 변수를 설정 해제하거나 재정의하세요.

• 프로젝트의 빌드가 직접 제어하고 신뢰하는 CI/CD job(예: mvn package를 실행하는 build Stage)에서 실행되는 경우, 동일한 job에서 잠금 파일 또는 의존성 그래프 내보내기를 생성하고 DS_DISABLED_RESOLUTION_JOBS로 GitLab 제공 해석 job을 비활성화하세요. 이 방법은 빌드 도구 실행의 위험을 줄이지는 않지만 민감한 job 컨텍스트를 하나로 제한합니다.

• 알려진 툴체인을 보장해야 하는 경우 다이제스트로 고정된 사용자 정의 해석 이미지를 사용하세요.

종속성 해석 제한 사항#

종속성 해석은 에코시스템당 단일한 고정 런타임 버전 및 빌드 도구를 사용하는 바닐라 또는 사용자 정의 이미지에서 에코시스템 네이티브 빌드 도구를 실행합니다.

해석 성공 여부는 프로젝트와 이 환경의 호환성, 패키지 레지스트리에 대한 접근 가능 여부, 그리고 의존성 수집을 넘어서는 빌드 시간 요구 사항의 부재에 따라 달라집니다.

기본 환경에서 실패하는 프로젝트는 필요한 빌드 환경이 모두 포함된 호환 환경을 제공하기 위해 관련 해석 job 이미지를 재정의할 수 있습니다.

호환 가능하더라도 해석 환경이 프로젝트가 빌드된 정확한 런타임 버전이나 다른 요구 사항과 일치하지 않을 수 있습니다. 따라서 생성된 의존성 그래프가 프로젝트의 실제 빌드 환경에서 해석될 정확한 의존성 집합을 반영하지 않을 수 있습니다. 고정된 런타임 버전, 해석되지 않은 환경 마커, 플랫폼별 의존성, 또는 해석 job에서 사용할 수 없는 빌드 시간 컨텍스트에 의존하는 조건부 의존성 그룹으로 인해 차이가 발생할 수 있습니다.

가장 정확한 결과를 얻으려면 자체 빌드 환경에서 생성된 잠금 파일 또는 의존성 그래프 내보내기를 제공하세요. 종속성 해석 워크플로로 적절하게 지원되지 않는 고도로 사용자 정의된 빌드를 가진 프로젝트의 경우 잠금 파일 또는 의존성 그래프 내보내기 수동 생성에 설명된 대로 자체 빌드 환경에서 생성된 잠금 파일 또는 의존성 그래프 내보내기를 제공해야 합니다.

Maven 해석 알려진 문제#

기본 환경: Java 21, Maven 3.9

Maven 프로젝트에는 다음 제한 사항이 적용됩니다:

• Maven enforcer 플러그인: Maven Enforcer Plugin에서 엄격한 Java 버전 규칙을 사용하는 프로젝트는 실패할 수 있습니다. 해석 명령은 이를 완화하기 위해 -Denforcer.skip=true를 전달하지만 모든 enforcer 규칙이 건너뛰어지는 것은 아닙니다.

• 프로필 기반 활성화: JDK 버전으로 활성화되는 조건부 모듈을 사용하는 프로젝트(예: ZXing, Dubbo)는 원래 타깃 Java 버전으로 빌드할 때와 다른 의존성 그래프를 생성할 수 있습니다.

• 초기 수명 주기 단계의 플러그인: validate 또는 initialize 단계에 바인딩된 플러그인 중 해석 이미지의 Java 버전과 호환되지 않는 플러그인은 실패를 유발할 수 있습니다.

Gradle 해석 알려진 문제#

기본 환경: Java 17, Gradle 8

해석 job은 Gradle 래퍼가 있는 경우 ./gradlew dependencies를 실행하고, 그렇지 않으면 gradle dependencies를 실행합니다. 멀티 모듈 프로젝트의 경우 각 서브 프로젝트는 :<subproject>:dependencies를 사용하여 개별적으로 해석됩니다. job은 출력을 해당 프로젝트 디렉터리의 gradle.graph.txt에 씁니다.

Gradle 프로젝트에는 다음 제한 사항이 적용됩니다:

• 래퍼 요구 사항: Gradle 래퍼(gradlew)가 있는 경우 유효한 gradle-wrapper.jar를 참조해야 합니다. 래퍼가 없는 경우 job은 시스템 gradle을 사용합니다.

• 플러그인 및 버전 호환성: 특정 Gradle 플러그인, 사용자 정의 툴체인 또는 Java 17 이외의 Java 버전이 필요한 프로젝트는 실패할 수 있습니다. 필요한 빌드 환경이 포함된 해석 이미지(spec:inputs:gradle_resolution_image)를 재정의하세요.

Python 해석 알려진 문제#

기본 환경: Python 3.12, pip-tools 7

Python 프로젝트에는 다음 제한 사항이 적용됩니다:

• Pipfile 미지원: Pipfile 프로젝트(Pipfile.lock 파일 없이)는 지원되지 않습니다. 리포지터리에 Pipfile 파일이 있어도 Python 해석 job이 트리거되지 않습니다.

• Git/VCS 의존성: Git 또는 VCS URL(git+https://...)로 지정된 의존성은 해석할 수 없습니다. 이 특정 매니페스트 파일에 대한 해석 명령이 실패하지만 다른 파일이 있는 경우 계속 처리됩니다.

• 로컬/편집 가능 설치: -e ., file:, 또는 로컬 경로 참조를 사용하는 항목은 해석 전에 제거되고 경고가 발생합니다. 해당 패키지는 출력에 나타나지 않습니다.

• 동적 install_requires를 가진 setup.py: install_requires가 런타임에 파일을 읽는 경우 경고가 발생하고 pip-compile이 해석을 시도하지만 실패할 수 있습니다.

• [project] 테이블이 없는 pyproject.toml: 빌드 시스템 구성만 포함하는 pyproject.toml은 건너뛰고 경고가 발생합니다.

• DS_INCLUDE_DEV_DEPENDENCIES 범위: 개발 의존성 포함은 [dependency-groups]가 있는 pyproject.toml에 대해서만 구현됩니다.

잠금 파일 또는 의존성 그래프 내보내기 수동 생성#

프로젝트에 리포지터리에 커밋된 지원되는 잠금 파일 또는 의존성 그래프 내보내기가 없고 종속성 해석도 지원하지 않는 경우 직접 제공해야 합니다.

복잡한 빌드, 사용자 정의 빌드 단계, 비공개 레지스트리, 또는 특정 환경 요구 사항이 있는 프로젝트의 경우 잠금 파일 또는 의존성 그래프 내보내기를 수동으로 생성하는 것을 고려하세요. 기존 빌드 프로세스의 일부로 파일을 생성하는 것이 해당 환경을 복제하도록 종속성 해석을 구성하는 것보다 더 빠르고 간단한 경우가 많습니다. 수동 파일 생성도 더 정확한 결과를 생성합니다. 파일은 전이 의존성과 플랫폼별 해석을 포함하여 자체 빌드에서 정확한 의존성 버전을 반영합니다.

아래 예시는 인기 있는 언어 및 패키지 매니저에 대해 GitLab 분석기가 지원하는 파일을 생성하는 방법을 보여줍니다. 지원되는 언어 및 파일의 전체 목록도 참조하세요.

Go#

이 방법은 Go 툴체인의 go mod graph 명령을 사용하여 분석기에 필요한 모든 정보(직접 및 전이 의존성 포함)가 담긴 go.graph 파일을 생성합니다. 이 파일이 없으면 분석기는 go.mod에서만 컴포넌트를 추출하지만, 의존성 경로 정보를 사용할 수 없으며 동일한 모듈의 여러 버전이 존재하는 경우 false positive가 발생할 수 있습니다.

Go 프로젝트에서 분석기를 활성화하려면:

• Dependency-Scanning.v2 CI/CD 템플릿을 추가합니다.

• go mod graph 명령을 프로젝트의 기존 빌드 job에 추가하거나, 빌드 job이 없는 경우 전용 job을 만듭니다. 이 job은 스캔이 시작될 때 아티팩트를 사용할 수 있도록 dependency-scanning job 이전에 실행되어야 합니다.

• go.graph를 job 아티팩트로 선언합니다.

모듈 캐시를 빌드에서 재사용하므로 별도의 job에서 실행하는 것보다 기존 빌드 job에 명령을 추가하는 것이 더 빠릅니다.

예시:

stages:
  - build
  - test

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

build:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the go.graph artifact.
  stage: build
  image: "golang:latest"
  script:
    # Your regular build script
    - go mod tidy
    - go build ./...
    # New instruction to generate the dependency graph
    - go mod graph > go.graph
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/go.graph"

Gradle#

Gradle 프로젝트의 경우 다음 방법 중 하나를 사용하여 의존성 그래프 내보내기를 생성합니다.

• Gradle dependencies 태스크

• Nebula Gradle Dependency Lock Plugin

• Gradle HtmlDependencyReportTask

Gradle dependencies 태스크#

이 방법은 자동 종속성 해석을 지원하는 동일한 gradle dependencies 태스크를 사용합니다. 직접 및 전이 의존성과 의존성 경로를 활성화하기 위한 그래프 정보를 포함하여 분석기에 필요한 모든 정보가 담긴 단일 gradle.graph.txt 파일을 생성하므로 권장 방법입니다.

Gradle 프로젝트에서 분석기를 활성화하려면:

• Dependency-Scanning.v2 CI/CD 템플릿을 추가합니다.

• gradle dependencies 명령을 프로젝트의 기존 빌드 job에 추가하거나, 빌드 job이 없는 경우 전용 job을 만듭니다. 이 job은 스캔이 시작될 때 아티팩트를 사용할 수 있도록 dependency-scanning job 이전에 실행되어야 합니다.

• gradle.graph.txt를 job 아티팩트로 선언합니다.

• DS_DISABLED_RESOLUTION_JOBS CI/CD 변수 또는 disabled_resolution_jobs 입력 값에 gradle을 추가하여 자동 종속성 해석을 비활성화합니다.

Gradle 데몬, 캐시, 빌드의 해석된 구성을 재사용하므로 별도의 job에서 실행하는 것보다 기존 빌드 job에 명령을 추가하는 것이 더 빠릅니다.

예시:

stages:
  - build
  - test

image: gradle:8.0-jdk11

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

build:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the gradle.graph.txt artifact.
  stage: build
  script:
    # Your regular build script
    - ./gradlew build
    # New instruction to generate the dependency graph
    - ./gradlew dependencies > gradle.graph.txt
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/gradle.graph.txt"

의존성 잠금 플러그인#

이 방법은 gradle-dependency-lock-plugin을 사용하여 두 개의 잠금 파일 dependencies.lock(직접 및 전이 의존성)과 dependencies.direct.lock(직접 의존성만)을 생성합니다. 분석기는 두 파일을 사용하여 의존성 그래프에서 직접 의존성과 전이 의존성을 구분합니다.

Gradle 프로젝트에서 분석기를 활성화하려면:

• Dependency-Scanning.v2 CI/CD 템플릿을 추가합니다.

• build.gradle 또는 build.gradle.kts를 편집하거나 init 스크립트를 사용하여 gradle-dependency-lock-plugin을 프로젝트에 적용합니다.

• generateLock saveLock 명령을 프로젝트의 기존 빌드 job에 추가하거나, 빌드 job이 없는 경우 전용 job을 만듭니다. 이 job은 스캔이 시작될 때 아티팩트를 사용할 수 있도록 dependency-scanning job 이전에 실행되어야 합니다.

• dependencies.lock과 dependencies.direct.lock을 job 아티팩트로 선언합니다.

• DS_DISABLED_RESOLUTION_JOBS CI/CD 변수 또는 disabled_resolution_jobs 입력 값에 gradle을 추가하여 자동 종속성 해석을 비활성화합니다.

예시:

stages:
  - build
  - test

image: gradle:8.0-jdk11

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

generate nebula lockfile:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the scannable artifacts.
  stage: build
  script:
    - |
      cat << EOF > nebula.gradle
      initscript {
          repositories {
            mavenCentral()
          }
          dependencies {
              classpath 'com.netflix.nebula:gradle-dependency-lock-plugin:12.7.1'
          }
      }

      allprojects {
          apply plugin: nebula.plugin.dependencylock.DependencyLockPlugin
      }
      EOF
      ./gradlew --init-script nebula.gradle -PdependencyLock.includeTransitives=true -PdependencyLock.lockFile=dependencies.lock generateLock saveLock
      ./gradlew --init-script nebula.gradle -PdependencyLock.includeTransitives=false -PdependencyLock.lockFile=dependencies.direct.lock generateLock saveLock
      # generateLock saves the lockfile in the build/ directory of a project
      # and saveLock copies it into the root of a project. To avoid duplicates
      # and get an accurate location of the dependency, use find to remove the
      # lockfiles in the build/ directory only.
  after_script:
    - find . -path '*/build/dependencies*.lock' -print -delete
  # Make the artifacts available to the dependency-scanning job.
  artifacts:
    paths:
      - '**/dependencies*.lock'

HtmlDependencyReportTask#

이 방법은 HtmlDependencyReportTask를 사용하여 직접 및 전이 의존성이 포함된 gradle-html-dependency-report.js 파일을 생성합니다. gradle 버전 4부터 8까지 테스트되었습니다.

Gradle 프로젝트에서 분석기를 활성화하려면:

• Dependency-Scanning.v2 CI/CD 템플릿을 추가합니다.

• gradle htmlDependencyReport 명령을 프로젝트의 기존 빌드 job에 추가하거나, 빌드 job이 없는 경우 전용 job을 만듭니다. 이 job은 스캔이 시작될 때 아티팩트를 사용할 수 있도록 dependency-scanning job 이전에 실행되어야 합니다.

• gradle-html-dependency-report.js를 job 아티팩트로 선언합니다.

• DS_DISABLED_RESOLUTION_JOBS CI/CD 변수 또는 disabled_resolution_jobs 입력 값에 gradle을 추가하여 자동 종속성 해석을 비활성화합니다.

예시:

stages:
  - build
  - test

# Define the image that contains Java and Gradle
image: gradle:8.0-jdk11

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

build:
  stage: build
  script:
    - gradle --init-script report.gradle htmlDependencyReport
  # The gradle task writes the dependency report as a javascript file under
  # build/reports/project/dependencies. Because the file has an un-standardized
  # name, the after_script finds and renames the file to
  # `gradle-html-dependency-report.js` copying it to the  same directory as
  # `build.gradle`
  after_script:
    - |
      reports_dir=build/reports/project/dependencies
      while IFS= read -r -d '' src; do
        dest="${src%%/$reports_dir/*}/gradle-html-dependency-report.js"
        cp $src $dest
      done < <(find . -type f -path "*/${reports_dir}/*.js" -not -path "*/${reports_dir}/js/*" -print0)
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/gradle-html-dependency-report.js"

위 명령은 report.gradle 파일을 사용하며 --init-script를 통해 제공하거나 내용을 build.gradle에 직접 추가할 수 있습니다:

allprojects {
    apply plugin: 'project-report'
}

의존성 보고서에 일부 구성의 의존성이 `FAILED`로 해석되었다고 표시될 수 있습니다.

이 경우 종속성 스캐닝은 경고를 기록하지만 job을 실패시키지는 않습니다. 해석 실패가 보고될 때 파이프라인이 실패하도록 하려면 위의 build 예시에 다음 추가 단계를 추가하세요.

while IFS= read -r -d '' file; do
  grep --quiet -E '"resolvable":\s*"FAILED' $file && echo "Dependency report has dependencies with FAILED resolution status" && exit 1
done < <(find . -type f -path "*/gradle-html-dependency-report.js -print0)

Maven#

이 방법은 자동 종속성 해석을 지원하는 동일한 mvn dependency:tree 명령을 사용합니다. 분석기에 필요한 모든 정보(직접 및 전이 의존성과 의존성 경로를 활성화하기 위한 그래프 정보 포함)가 담긴 단일 maven.graph.json 파일을 생성합니다.

Maven 프로젝트에서 분석기를 활성화하려면:

• Dependency-Scanning.v2 CI/CD 템플릿을 추가합니다.

• mvn dependency:tree 명령(maven-dependency-plugin 버전 3.7.0 이상 사용)을 프로젝트의 기존 빌드 job에 추가하거나, 빌드 job이 없는 경우 전용 job을 만듭니다. 이 job은 스캔이 시작될 때 아티팩트를 사용할 수 있도록 dependency-scanning job 이전에 실행되어야 합니다.

• maven.graph.json을 job 아티팩트로 선언합니다.

• DS_DISABLED_RESOLUTION_JOBS CI/CD 변수 또는 disabled_resolution_jobs 입력 값에 maven을 추가하여 자동 종속성 해석을 비활성화합니다.

Maven 세션과 빌드의 해석된 구성을 재사용하므로 별도의 job에서 실행하는 것보다 기존 빌드 job에 명령을 추가하는 것이 더 빠릅니다.

예시:

stages:
  - build
  - test

image: maven:3.9.9-eclipse-temurin-21

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

build:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the maven.graph.json artifacts.
  stage: build
  script:
    # Your regular build script
    - mvn install
    # New instruction to generate the dependency graph
    - mvn org.apache.maven.plugins:maven-dependency-plugin:3.8.1:tree -DoutputType=json -DoutputFile=maven.graph.json
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/*.jar"
      - "**/maven.graph.json"

pip#

pip 프로젝트의 경우 다음 방법 중 하나를 사용하여 의존성 그래프 내보내기를 생성합니다:

• pip-compile

• pipdeptree

pip-compile#

이 방법은 자동 종속성 해석을 지원하는 pip-compile 명령을 사용합니다. 분석기에 필요한 모든 정보(직접 및 전이 의존성과 의존성 경로를 활성화하기 위한 그래프 정보 포함)가 담긴 requirements.txt 잠금 파일을 생성합니다.

pip 프로젝트에서 분석기를 활성화하려면:

• Dependency-Scanning.v2 CI/CD 템플릿을 추가합니다.

• pip-compile 명령을 프로젝트의 기존 빌드 job에 추가하거나, 빌드 job이 없는 경우 전용 job을 만듭니다. 이 job은 스캔이 시작될 때 아티팩트를 사용할 수 있도록 dependency-scanning job 이전에 실행되어야 합니다.

• requirements.txt를 job 아티팩트로 선언합니다.

• DS_DISABLED_RESOLUTION_JOBS CI/CD 변수 또는 disabled_resolution_jobs 입력 값에 python을 추가하여 자동 종속성 해석을 비활성화합니다.

빌드에서 설치된 의존성을 재사용하므로 별도의 job에서 실행하는 것보다 기존 빌드 job에 명령을 추가하는 것이 더 빠릅니다.

예시:

stages:
  - build
  - test

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

build:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the requirements.txt artifact.
  stage: build
  image: "python:latest"
  script:
    # Your regular build script
    - pip install pip-tools
    # New instruction to generate the dependency lockfile
    - pip-compile requirements.in
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/requirements.txt"

pipdeptree#

이 방법은 pipdeptree --json을 사용하여 분석기에 필요한 모든 정보(직접 및 전이 의존성과 의존성 경로를 활성화하기 위한 그래프 정보 포함)가 담긴 pipdeptree.json 파일을 생성합니다.

pip 프로젝트에서 분석기를 활성화하려면:

• Dependency-Scanning.v2 CI/CD 템플릿을 추가합니다.

• pipdeptree --json 명령을 프로젝트의 기존 빌드 job에 추가하거나, 빌드 job이 없는 경우 전용 job을 만듭니다. 이 job은 스캔이 시작될 때 아티팩트를 사용할 수 있도록 dependency-scanning job 이전에 실행되어야 합니다.

• pipdeptree.json을 job 아티팩트로 선언합니다.

• DS_DISABLED_RESOLUTION_JOBS CI/CD 변수 또는 disabled_resolution_jobs 입력 값에 python을 추가하여 자동 종속성 해석을 비활성화합니다.

빌드에서 설치된 의존성을 재사용하므로 별도의 job에서 실행하는 것보다 기존 빌드 job에 명령을 추가하는 것이 더 빠릅니다.

예시:

stages:
  - build
  - test

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

build:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the pipdeptree.json artifact.
  stage: build
  image: "python:latest"
  script:
    # Your regular build script
    - pip install -r requirements.txt
    # New instructions to generate the dependency graph.
    # Exclude pipdeptree itself to avoid false positives.
    - pip install pipdeptree
    - pipdeptree -e pipdeptree --json > pipdeptree.json
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/pipdeptree.json"

알려진 문제로 인해 pipdeptree는 선택적 의존성을 상위 패키지의 의존성으로 표시하지 않습니다. 결과적으로 종속성 스캐닝은 이를 전이 의존성 대신 프로젝트의 직접 의존성으로 표시합니다.

Pipenv#

이 방법은 pipenv graph 명령을 사용하여 분석기에 필요한 정보(직접 및 전이 의존성 포함)가 담긴 pipenv.graph.json 파일을 생성합니다. 이 파일이 없으면 분석기는 Pipfile.lock에서만 컴포넌트를 추출하지만, 의존성 경로 정보를 사용할 수 없습니다.

Pipenv 프로젝트에서 분석기를 활성화하려면:

• Dependency-Scanning.v2 CI/CD 템플릿을 추가합니다.

• pipenv graph --json-tree 명령을 프로젝트의 기존 빌드 job에 추가하거나, 빌드 job이 없는 경우 전용 job을 만듭니다. 이 job은 스캔이 시작될 때 아티팩트를 사용할 수 있도록 dependency-scanning job 이전에 실행되어야 합니다.

• pipenv.graph.json을 job 아티팩트로 선언합니다.

빌드에서 설치된 의존성을 재사용하므로 별도의 job에서 실행하는 것보다 기존 빌드 job에 명령을 추가하는 것이 더 빠릅니다.

예시:

stages:
  - build
  - test

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

build:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the pipenv.graph.json artifact.
  stage: build
  image: "python:3.12"
  script:
    # Your regular build script
    - pip install pipenv
    - pipenv install
    # New instruction to generate the dependency graph
    - pipenv graph --json-tree > pipenv.graph.json
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/pipenv.graph.json"

sbt#

이 방법은 sbt-dependency-graph 플러그인을 사용하여 분석기에 필요한 모든 정보(직접 및 전이 의존성 포함)가 담긴 dependencies-compile.dot 파일을 생성합니다.

sbt 프로젝트에서 분석기를 활성화하려면:

• Dependency-Scanning.v2 CI/CD 템플릿을 추가합니다.

• plugins.sbt를 편집하여 sbt-dependency-graph 플러그인을 추가합니다.

• sbt dependencyDot 명령을 프로젝트의 기존 빌드 job에 추가하거나, 빌드 job이 없는 경우 전용 job을 만듭니다. 이 job은 스캔이 시작될 때 아티팩트를 사용할 수 있도록 dependency-scanning job 이전에 실행되어야 합니다.

• dependencies-compile.dot을 job 아티팩트로 선언합니다.

sbt 세션과 빌드의 해석된 구성을 재사용하므로 별도의 job에서 실행하는 것보다 기존 빌드 job에 명령을 추가하는 것이 더 빠릅니다.

예시:

stages:
  - build
  - test

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

build:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the dependencies-compile.dot artifact.
  stage: build
  image: "sbtscala/scala-sbt:eclipse-temurin-17.0.13_11_1.10.7_3.6.3"
  script:
    # Your regular build script
    - sbt compile
    # New instruction to generate the dependency graph
    - sbt dependencyDot
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/dependencies-compile.dot"

매니페스트 폴백#

History

• GitLab 18.9에서 도입됨. Maven 매니페스트 파일만 지원, 기본적으로 비활성화됨.

• GitLab 18.9에서 업데이트됨. Python requirements 파일 지원 추가, 기본적으로 비활성화됨.

• GitLab 18.10에서 업데이트됨. Gradle 매니페스트 파일 지원 추가, 기본적으로 비활성화됨.

• GitLab 19.0에서 기본적으로 활성화됨.

지원되는 잠금 파일 또는 의존성 그래프 내보내기를 사용할 수 없는 경우, 종속성 스캐닝 분석기는 지원되는 매니페스트 파일에서 의존성을 추출하는 폴백으로 사용할 수 있습니다.

다음 매니페스트 파일이 지원됩니다:

매니페스트 폴백은 잠금 파일 스캔에 비해 정확도가 낮습니다:

• 전이 의존성 없음: 직접 의존성만 탐지됩니다.

• 정확한 해석된 버전을 항상 결정할 수 없습니다.

매니페스트 폴백 비활성화#

매니페스트 폴백을 비활성화하려면 DS_ENABLE_MANIFEST_FALLBACK CI/CD 변수 또는 enable_manifest_fallback 입력을 사용합니다.

variables:
  DS_ENABLE_MANIFEST_FALLBACK: "false"

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

애플리케이션 스캔 방법#

SBOM을 사용한 종속성 스캐닝 기능은 의존성 탐지를 정적 도달 가능성 또는 취약점 스캐닝과 같은 다른 분석에서 분리하는 분해된 의존성 분석 접근 방식을 사용합니다.

이러한 관심사의 분리와 아키텍처의 모듈성을 통해 언어 지원 확장, GitLab 플랫폼 내에서 더 긴밀한 통합 및 경험, 그리고 업계 표준 보고서 유형으로의 전환을 통해 고객을 더 잘 지원할 수 있습니다.

종속성 해석이 활성화된 경우 해석 job은 dependency-scanning job 이전 .pre Stage에서 실행됩니다. 이 job들은 잠금 파일 또는 의존성 그래프 내보내기를 아티팩트로 생성하며, dependency-scanning job이 이를 사용합니다.

종속성 스캐닝의 전체 흐름은 아래에 설명되어 있습니다

flowchart TD subgraph CI[CI Pipeline] START([CI Job Starts]) DETECT[Dependency Detection] SBOM_GEN[SBOM Reports Generation] SR[Static Reachability Analysis] UPLOAD[Upload SBOM Files] DL[Download Scan Results] REPORT[DS Security Report Generation] END([CI Job Complete]) end

subgraph GitLab[GitLab Instance]
    API[CI SBOM Scan API]
    SCANNER[GitLab SBOM Vulnerability Scanner]
    RESULTS[Scan Results]
end

START --> DETECT
DETECT --> SBOM_GEN
SBOM_GEN --> SR
SR --> UPLOAD
UPLOAD --> API
API --> SCANNER
SCANNER --> RESULTS
RESULTS --> DL
DL --> REPORT
REPORT --> END

의존성 탐지 단계에서 분석기는 사용 가능한 잠금 파일을 파싱하여 프로젝트의 의존성 및 그 관계(의존성 그래프)에 대한 포괄적인 인벤토리를 구축합니다. 이 인벤토리는 CycloneDX SBOM(Software Bill of Materials) 문서에 캡처됩니다.

정적 도달 가능성 단계에서 분석기는 소스 파일을 파싱하여 어떤 SBOM 컴포넌트가 활성으로 사용되는지 파악하고 SBOM 파일에 그에 맞게 표시합니다. 이를 통해 사용자는 취약한 컴포넌트에 실제로 도달 가능한지 여부를 기반으로 취약점의 우선순위를 정할 수 있습니다. 자세한 내용은 정적 도달 가능성 페이지를 참조하세요.

SBOM 문서는 종속성 스캐닝 SBOM API를 통해 GitLab 인스턴스에 임시로 업로드됩니다. GitLab SBOM 취약점 스캐너 엔진은 SBOM 컴포넌트를 advisory와 대조하여 결과 목록을 생성하고 이를 분석기에 반환하여 종속성 스캐닝 보고서에 포함시킵니다.

API는 인증을 위해 기본 CI_JOB_TOKEN을 사용합니다. CI_JOB_TOKEN 값을 다른 토큰으로 재정의하면 API에서 403 - forbidden 응답이 발생할 수 있습니다.

사용자는 다음을 사용하여 종속성 스캐닝 SBOM API와 통신하는 분석기 클라이언트를 구성할 수 있습니다:

• vulnerability_scan_api_timeout 또는 DS_API_TIMEOUT

• vulnerability_scan_api_download_delay 또는 DS_API_SCAN_DOWNLOAD_DELAY

자세한 내용은 사용 가능한 spec 입력과 사용 가능한 CI/CD 변수를 참조하세요.

생성된 보고서는 CI job이 완료될 때 GitLab 인스턴스에 업로드되며 일반적으로 파이프라인 완료 후 처리됩니다.

SBOM 보고서는 의존성 목록, 라이선스 스캐닝, 또는 지속적 취약점 스캐닝과 같은 다른 SBOM 기반 기능을 지원하는 데 사용됩니다.

종속성 스캐닝 보고서는 보안 스캐닝 결과의 일반적인 프로세스를 따릅니다.

• 종속성 스캐닝 보고서가 기본 브랜치의 CI/CD job에 의해 선언된 경우: 취약점이 생성되며 취약점 보고서에서 확인할 수 있습니다.

• 종속성 스캐닝 보고서가 기본 브랜치가 아닌 브랜치의 CI/CD job에 의해 선언된 경우: 보안 결과가 생성되며 파이프라인 뷰의 보안 탭과 머지 리퀘스트 보고서에서 확인할 수 있습니다.

오프라인 환경#

외부 리소스에 대한 인터넷 접근이 제한되거나, 제약되거나, 간헐적인 환경의 인스턴스에서는 종속성 스캐닝 job을 성공적으로 실행하기 위해 몇 가지 조정이 필요합니다. 자세한 내용은 오프라인 환경을 참조하세요.

요구 사항#

오프라인 환경에서 종속성 스캐닝을 실행하려면 다음이 필요합니다:

• docker 또는 kubernetes 실행기를 사용하는 GitLab Runner.

• 종속성 스캐닝 분석기 이미지의 로컬 복사본.

• 패키지 메타데이터 데이터베이스에 대한 접근. 의존성의 라이선스 및 advisory 데이터를 확보하기 위해 필요합니다.

분석기 이미지의 로컬 복사본#

종속성 스캐닝 분석기를 사용하려면:

registry.gitlab.com에서 현재 이미지를 로컬 Docker 컨테이너 레지스트리로 가져오세요. Docker 이미지를 로컬 오프라인 Docker 레지스트리로 가져오는 프로세스는 네트워크 보안 정책에 따라 다릅니다. IT 담당자에게 문의하여 외부 리소스를 가져오거나 일시적으로 접근할 수 있는 허용되고 승인된 프로세스를 찾으세요. 이 이미지는 새 기능, 버그 수정 및 패치로 정기적으로 업데이트되므로 정기적으로 다운로드하는 것이 좋습니다. 오프라인 인스턴스에서 GitLab 레지스트리에 접근할 수 있는 경우 Security-Binaries 템플릿을 사용하여 최신 종속성 스캐닝 분석기 이미지를 다운로드할 수 있습니다.

GitLab CI/CD를 로컬 분석기를 사용하도록 구성하세요.

CI/CD 변수 SECURE_ANALYZERS_PREFIX 또는 analyzer_image_prefix spec 입력 값을 로컬 Docker 레지스트리로 설정합니다 - 이 예에서는 docker-registry.example.com입니다.

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

variables:
  SECURE_ANALYZERS_PREFIX: "docker-registry.example.com/analyzers"

여러 프로젝트에서 스캔 적용#

보안 정책을 사용하여 여러 프로젝트에서 종속성 스캐닝을 적용합니다. 종속성 스캐닝은 잠금 파일 또는 의존성 그래프 내보내기 중 하나의 스캔 가능한 아티팩트가 필요합니다. 스캔 가능한 아티팩트가 프로젝트 리포지터리에 커밋되어 있는지 여부에 따라 정책 선택이 결정됩니다.

스캔 가능한 아티팩트가 리포지터리에 커밋되어 있는 경우 스캔 실행 정책을 사용하세요.

스캔 가능한 아티팩트가 리포지터리에 커밋되어 있거나 종속성 해석에 의해 지원되는 프로젝트의 경우, 스캔 실행 정책이 종속성 스캐닝을 적용하는 가장 직접적인 방법을 제공합니다.

스캔 가능한 아티팩트가 리포지터리에 커밋되어 있지 않고 종속성 해석에 의해 지원되지도 않는 경우 파이프라인 실행 정책을 사용하세요.

스캔 가능한 아티팩트가 리포지터리에 커밋되어 있지 않은 프로젝트의 경우 파이프라인 실행 정책을 사용해야 합니다. 정책은 종속성 스캐닝을 호출하기 전에 스캔 가능한 아티팩트를 생성하는 사용자 정의 CI/CD job을 정의해야 합니다.

파이프라인 실행 정책은 다음을 수행해야 합니다:

CI/CD 파이프라인의 일부로 잠금 파일 또는 의존성 그래프 내보내기를 생성합니다.

• 특정 프로젝트 요구 사항에 맞게 의존성 탐지 프로세스를 사용자 정의합니다.

• Gradle 및 Maven과 같은 빌드 도구에 대한 언어별 지침을 구현합니다.

다음 예시는 Gradle nebula 플러그인을 사용하여 잠금 파일을 생성합니다. 다른 언어는 잠금 파일 또는 의존성 그래프 내보내기 수동 생성을 참조하세요.

예시: Gradle 프로젝트를 위한 파이프라인 실행 정책#

리포지터리에 스캔 가능한 아티팩트가 커밋되지 않은 Gradle 프로젝트의 경우 파이프라인 실행 정책에서 아티팩트 생성 단계를 정의해야 합니다. 다음 예시는 nebula 플러그인을 사용합니다.

전용 보안 정책 프로젝트에서 기본 정책 파일(예: policy.yml)을 생성하거나 업데이트합니다:

pipeline_execution_policy:
- name: Enforce Gradle dependency scanning with SBOM
  description: Generate dependency artifact and run dependency scanning.
  enabled: true
  pipeline_config_strategy: inject_policy
  content:
    include:
      - project: $SECURITY_POLICIES_PROJECT
        file: "dependency-scanning.yml"

dependency-scanning.yml 정책 파일을 추가합니다:

stages:
  - build
  - test

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

generate nebula lockfile:
  image: openjdk:11-jdk
  stage: build
  script:
    - |
      cat << EOF > nebula.gradle
      initscript {
          repositories {
            mavenCentral()
          }
          dependencies {
              classpath 'com.netflix.nebula:gradle-dependency-lock-plugin:12.7.1'
          }
      }

      allprojects {
          apply plugin: nebula.plugin.dependencylock.DependencyLockPlugin
      }
      EOF
      ./gradlew --init-script nebula.gradle -PdependencyLock.includeTransitives=true -PdependencyLock.lockFile=dependencies.lock generateLock saveLock
      ./gradlew --init-script nebula.gradle -PdependencyLock.includeTransitives=false -PdependencyLock.lockFile=dependencies.direct.lock generateLock saveLock
  after_script:
    - find . -path '*/build/dependencies.lock' -print -delete
  artifacts:
    paths:
      - '**/dependencies.lock'
      - '**/dependencies.direct.lock'

이 접근 방식은 다음을 보장합니다:

• Gradle 프로젝트에서 파이프라인 실행 시 스캔 가능한 아티팩트가 생성됩니다.

• 종속성 스캐닝이 적용되고 스캔 가능한 아티팩트에 접근할 수 있습니다.

• 정책 범위의 모든 프로젝트가 동일한 종속성 스캐닝 접근 방식을 일관되게 따릅니다.

• 구성 변경을 중앙에서 관리하고 여러 프로젝트에 적용할 수 있습니다.

새 종속성 스캐닝 기능을 활성화하는 다른 방법#

v2 템플릿을 사용하여 종속성 스캐닝 기능을 활성화하는 것을 강력히 권장합니다. 이것이 불가능한 경우 다음 방법 중 하나를 선택할 수 있습니다:

최신 템플릿 사용#

`latest` 템플릿은 안정적이지 않으며 주요 변경 사항이 포함될 수 있습니다. [템플릿 에디션](/19.2/user/application_security/detect/security_configuration/#template-editions)을 참조하세요.

GitLab 제공 분석기를 활성화하려면 latest 종속성 스캐닝 CI/CD 템플릿 Dependency-Scanning.latest.gitlab-ci.yml을 사용하세요.

기본적으로 (더 이상 사용되지 않는) Gemnasium 분석기가 사용됩니다.

새 종속성 스캐닝 분석기를 활성화하려면 CI/CD 변수 DS_ENFORCE_NEW_ANALYZER를 true로 설정합니다.

dependency-scanning job을 파이프라인에 생성하려면 지원되는 잠금 파일, 수동으로 생성한 의존성 그래프 내보내기, 또는 트리거 파일이 리포지터리에 존재해야 합니다.

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

variables:
  DS_ENFORCE_NEW_ANALYZER: 'true'

또는 스캔 실행 정책과 latest 템플릿을 사용하여 기능을 활성화하고 CI/CD 변수 DS_ENFORCE_NEW_ANALYZER를 true로 설정하여 새 종속성 스캐닝 분석기를 적용할 수 있습니다.

분석기 동작을 사용자 정의하려면 사용 가능한 CI/CD 변수를 사용하세요.

최신 템플릿의 트리거 파일#

트리거 파일은 최신 종속성 스캐닝 CI/CD 템플릿을 사용할 때 dependency-scanning CI/CD job을 생성합니다. 분석기는 이 파일들을 스캔하지 않습니다. 트리거 파일을 사용하여 잠금 파일 또는 의존성 그래프 내보내기를 수동으로 생성하면 프로젝트를 지원할 수 있습니다.

종속성 스캐닝 CI/CD 컴포넌트 사용#

History

• GitLab 17.5에서 베타로 도입됨. 종속성 스캐닝 CI/CD 컴포넌트 버전 0.4.0.

• GitLab 18.8에서 일반적으로 사용 가능해짐. 종속성 스캐닝 CI/CD 컴포넌트 버전 1.0.0.

종속성 스캐닝 CI/CD 컴포넌트를 사용하여 새 종속성 스캐닝 분석기를 활성화합니다. 이 접근 방식을 선택하기 전에 GitLab Self-Managed에 대한 현재 제한 사항을 검토하세요.

include:
  - component: $CI_SERVER_FQDN/components/dependency-scanning/main@1

잠금 파일 또는 의존성 그래프 내보내기를 수동으로 생성해야 합니다.

종속성 스캐닝 CI/CD 컴포넌트를 사용하는 경우 입력을 구성하여 분석기를 사용자 정의할 수 있습니다.

SBOM 직접 가져오기#

서드파티 SBOM 지원은 기술적으로 가능하지만 이 [에픽](https://www.gitlab.com/groups/gitlab-org/-/epics/14760)으로 공식 지원을 완성하는 과정에서 크게 변경될 수 있습니다.

서드파티 CycloneDX SBOM 생성기 또는 사용자 정의 도구로 생성한 CycloneDX SBOM 문서를 사용자 정의 CI job의 CI/CD 아티팩트 보고서로 사용하세요.

SBOM을 사용한 종속성 스캐닝을 활성화하려면 제공된 CycloneDX SBOM 문서가 다음을 충족해야 합니다:

• CycloneDX 사양 버전 1.4, 1.5, 또는 1.6을 준수해야 합니다. 온라인 유효성 검사기는 CycloneDX Web Tool에서 사용할 수 있습니다.

• GitLab CycloneDX 속성 분류 체계를 준수해야 합니다.

• 성공한 CI job의 CI/CD 아티팩트 보고서로 업로드되어야 합니다.