CycloneDX 소프트웨어 자재명세서(SBOM)를 사용한 의존성 스캔은 애플리케이션의 의존성에서 알려진 취약점을 분석합니다. 전이적 의존성을 포함한 모든 의존성이 스캔됩니다.

의존성 스캔은 소프트웨어 컴포지션 분석(SCA)의 일부로 간주되는 경우가 많습니다. SCA는 코드가 사용하는 항목을 검사하는 측면을 포함할 수 있습니다. 이러한 항목에는 일반적으로 애플리케이션 및 시스템 의존성이 포함되며, 이는 거의 항상 외부 소스에서 가져오고 직접 작성한 항목이 아닙니다.

의존성 스캔은 애플리케이션 라이프사이클의 개발 단계에서 실행할 수 있습니다. CI/CD 파이프라인에서 새로운 의존성 스캔 분석기를 사용하면, 프로젝트 의존성이 감지되어 CycloneDX SBOM 보고서에 보고됩니다. 보안 결과가 식별되고 소스 및 대상 브랜치 간에 비교됩니다. 결과와 심각도는 머지 리퀘스트에 나열되어, 코드 변경이 커밋되기 전에 애플리케이션에 대한 위험을 사전에 해결할 수 있습니다. 보고된 SBOM 컴포넌트에 대한 보안 결과는 CI/CD 파이프라인과 독립적으로 새 보안 어드바이저리가 게시될 때 지속적 취약점 스캔에 의해서도 식별됩니다.

GitLab은 이러한 모든 의존성 유형을 포괄하기 위해 의존성 스캔과 컨테이너 스캔을 모두 제공합니다. 위험 영역을 최대한 포괄하려면 모든 보안 스캐너를 사용하는 것을 권장합니다. 이러한 기능의 비교를 위해서는 의존성 스캔과 컨테이너 스캔 비교를 참조하세요.

새로운 의존성 스캔 분석기에 대한 피드백은 피드백 이슈에서 공유하세요.

의존성 스캔 활성화#

프로젝트에 대한 의존성 스캔을 활성화합니다.

전제 조건#

모든 GitLab 인스턴스의 전제 조건:

• 프로젝트에 대한 Developer, Maintainer 또는 Owner 권한.

• 지원되는 잠금 파일 또는 의존성 그래프 내보내기가 리포지터리에 커밋되어 있거나 CI/CD 파이프라인에서 생성되어 dependency-scanning job에 아티팩트로 전달됩니다. 또는 의존성 해결이 지원되는 에코시스템에서 필요한 파일을 생성할 수 있으며, 매니페스트 파일을 폴백 옵션으로 사용할 수도 있습니다.

• 셀프 매니지드 러너의 경우, docker 또는 kubernetes executor가 있는 GitLab Runner.

• GitLab.com의 호스팅된 러너의 경우, 이 구성은 기본적으로 활성화됩니다.

GitLab Self-Managed 전용으로, 스캔할 모든 PURL 유형에 대한 패키지 메타데이터가 GitLab 인스턴스에서 동기화되어야 합니다. 이 데이터를 GitLab 인스턴스에서 사용할 수 없으면 의존성 스캔이 취약점을 식별할 수 없습니다.

프로젝트 파이프라인 구성 업데이트#

의존성 스캔을 활성화하려면 프로젝트 파이프라인 구성에 의존성 스캔 템플릿을 추가해야 합니다.

기본적으로 Dependency-Scanning.v2.gitlab-ci.yml 템플릿은 머지 리퀘스트 파이프라인에서 의존성 스캔 job을 실행합니다. 프로젝트가 다른 job에 머지 리퀘스트 파이프라인을 사용하지 않는 경우, 의존성 스캔 job만 머지 리퀘스트 파이프라인에 나타나고 다른 모든 job은 별도의 브랜치 파이프라인에서 실행됩니다. 이 동작을 비활성화하려면 의존성 스캔의 MR 파이프라인 비활성화를 참조하세요.

GitLab UI를 통해 의존성 스캔을 활성화하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.

2. 왼쪽 사이드바에서 Code > Repository를 선택합니다.

3. .gitlab-ci.yml 파일을 선택합니다.

4. Edit > Edit single file을 선택합니다.

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

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

6. Commit changes를 선택합니다.

사용 가능한 컨테이너 이미지#

이 기능은 CI job을 실행하기 위해 컨테이너 이미지를 사용합니다. 기본 CI job 정의는 메이저 버전 태그(예: dependency-scanning:2)로 이미지를 참조하므로, CI/CD 구성을 변경하지 않아도 패치 및 마이너 업데이트를 자동으로 받을 수 있습니다.

유지 관리 정책#

GitLab은 릴리스 및 유지 관리 정책에 따라 현재 안정 릴리스에 대한 버그 수정과 이전 두 월별 릴리스에 대한 보안 수정을 제공합니다.

CI/CD job은 메이저 버전 태그(예: dependency-scanning:2)로 이미지를 참조하므로, 수정 사항은 해당 메이저 이미지 버전과 호환되는 모든 GitLab 버전에 자동으로 제공됩니다.

이 정책은 아래 나열된 이미지에 적용됩니다. 이전 이미지는 이 정책에 포함되지 않습니다.

현재 이미지#

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

이전 이미지#

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

FIPS 준수#

의존성 스캔 분석기 이미지와 모든 의존성 해결 이미지는 FIPS 140 검증 암호화 모듈을 사용하는 Red Hat UBI를 기반으로 합니다. FIPS 활성화 환경에서는 추가 구성이 필요하지 않습니다.

Go#

프로젝트가 go.mod 파일만 제공하는 경우, 의존성 스캔 분석기는 여전히 컴포넌트 목록을 추출할 수 있습니다. 그러나 의존성 경로 정보는 사용할 수 없습니다. 또한 동일한 모듈의 여러 버전이 있는 경우 거짓 양성이 발생할 수 있습니다.

향상된 컴포넌트 감지 및 기능 커버리지의 이점을 얻으려면 Go 도구 체인의 go mod graph 명령을 사용하여 생성된 go.graph 파일을 제공해야 합니다.

다음 예제 .gitlab-ci.yml은 Go 프로젝트에서 의존성 경로 지원으로 분석기를 활성화하는 방법을 보여줍니다. 의존성 그래프는 의존성 스캔이 실행되기 전에 build 스테이지에서 job 아티팩트로 출력됩니다.

stages:
  - build
  - test

include:
  - template: Jobs/Dependency-Scanning.v2.gitlab-ci.yml
go:build:
  stage: build
  image: "golang:latest"
  script:
    - "go mod tidy"
    - "go build ./..."
    - "go mod graph > go.graph"
  artifacts:
    when: on_success
    access: developer
    paths: ["**/go.graph"]

Gradle#

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

• Nebula Gradle Dependency Lock Plugin
• Gradle의 HtmlDependencyReportTask

의존성 잠금 플러그인#

이 방법은 직접 의존성에 대한 정보를 제공합니다.

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

1. build.gradle 또는 build.gradle.kts를 편집하여 gradle-dependency-lock-plugin을 사용하거나 init 스크립트를 사용합니다.
2. .gitlab-ci.yml 파일이 dependencies.lock 및 dependencies.direct.lock 아티팩트를 생성하고 dependency-scanning job에 전달하도록 구성합니다.

다음 예제는 Gradle 프로젝트에 대해 분석기를 구성하는 방법을 보여줍니다.

stages:
  - build
  - test

image: gradle:8.0-jdk11

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

generate nebula lockfile:
  # build 스테이지에서 실행하면 dependency-scanning job이
  # 스캔 가능한 아티팩트를 받을 수 있습니다.
  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은 잠금 파일을 프로젝트의 build/ 디렉토리에 저장하고
      # saveLock은 프로젝트 루트에 복사합니다. 중복을 방지하고
      # 의존성의 정확한 위치를 얻으려면 find를 사용하여
      # build/ 디렉토리의 잠금 파일만 제거합니다.
  after_script:
    - find . -path '*/build/dependencies*.lock' -print -delete
  # 생성된 모든 아티팩트를 수집하여 순차적 스테이지의 job에 전달합니다.
  artifacts:
    paths:
      - '**/dependencies*.lock'

HtmlDependencyReportTask#

이 방법은 전이적 의존성과 직접 의존성 모두에 대한 정보를 제공합니다.

HtmlDependencyReportTask는 Gradle 프로젝트의 의존성 목록을 가져오는 대안적인 방법입니다(gradle 버전 4에서 8로 테스트됨). 의존성 스캔과 함께 이 방법을 사용하려면 gradle htmlDependencyReport 작업을 실행한 아티팩트를 사용할 수 있어야 합니다.

stages:
  - build
  - test

# Java와 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
  # gradle 작업은 의존성 보고서를 build/reports/project/dependencies 아래에
  # 자바스크립트 파일로 작성합니다. 파일 이름이 표준화되지 않았기 때문에
  # after_script가 파일을 찾아 `build.gradle`과 동일한 디렉토리에
  # `gradle-html-dependency-report.js`로 이름을 바꾸어 복사합니다.
  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)
  # html 보고서 아티팩트를 후속 의존성 스캔 스테이지에 전달합니다.
  artifacts:
    paths:
      - "**/gradle-html-dependency-report.js"

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

allprojects {
    apply plugin: 'project-report'
}

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#

다음 예제 .gitlab-ci.yml은 Maven 프로젝트에서 분석기를 활성화하는 방법을 보여줍니다. 의존성 그래프는 의존성 스캔이 실행되기 전에 build 스테이지에서 job 아티팩트로 출력됩니다.

요구사항: maven-dependency-plugin의 최소 버전 3.7.0을 사용하세요.

stages:
  - build
  - test

image: maven:3.9.9-eclipse-temurin-21

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

build:
  # build 스테이지에서 실행하면 dependency-scanning job이
  # maven.graph.json 아티팩트를 받을 수 있습니다.
  stage: build
  script:
    - mvn install
    - mvn org.apache.maven.plugins:maven-dependency-plugin:3.8.1:tree -DoutputType=json -DoutputFile=maven.graph.json
  # 모든 maven.graph.json 아티팩트를 수집하여
  # 순차적 스테이지의 job에 전달합니다.
  artifacts:
    paths:
      - "**/*.jar"
      - "**/maven.graph.json"

pip#

프로젝트가 pip-compile 명령줄 도구로 생성된 requirements.txt 잠금 파일을 제공하는 경우, 의존성 스캔 분석기는 컴포넌트 목록과 의존성 그래프 정보를 추출할 수 있어, 의존성 경로 기능을 지원합니다.

또는 pipdeptree --json 명령줄 유틸리티로 생성된 pipdeptree.json 의존성 그래프 내보내기를 제공할 수 있습니다.

다음 예제 .gitlab-ci.yml은 pip 프로젝트에서 의존성 경로 지원으로 분석기를 활성화하는 방법을 보여줍니다. build 스테이지는 의존성 스캔이 실행되기 전에 의존성 그래프를 job 아티팩트로 출력합니다.

stages:
  - build
  - test

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

build:
  stage: build
  image: "python:latest"
  script:
    - "pip install -r requirements.txt"
    - "pip install pipdeptree"
    # pipdeptree를 실행하여 프로젝트의 의존성을 가져오고 거짓 양성을 방지하기 위해 pipdeptree 자체를 제외합니다.
    - "pipdeptree -e pipdeptree --json > pipdeptree.json"
  artifacts:
    when: on_success
    access: developer
    paths: ["**/pipdeptree.json"]

알려진 문제로 인해 pipdeptree는 선택적 의존성을 부모 패키지의 의존성으로 표시하지 않습니다. 결과적으로 의존성 스캔은 전이적 의존성이 아닌 프로젝트의 직접 의존성으로 표시합니다.

Pipenv#

프로젝트가 Pipfile.lock 파일만 제공하는 경우, 의존성 스캔 분석기는 여전히 컴포넌트 목록을 추출할 수 있습니다. 그러나 의존성 경로 정보는 사용할 수 없습니다.

향상된 기능 커버리지의 이점을 얻으려면 pipenv graph 명령으로 생성된 pipenv.graph.json 파일을 제공해야 합니다.

다음 예제 .gitlab-ci.yml은 Pipenv 프로젝트에서 의존성 경로 지원으로 분석기를 활성화하는 방법을 보여줍니다. build 스테이지는 의존성 스캔이 실행되기 전에 의존성 그래프를 job 아티팩트로 출력합니다.

stages:
  - build
  - test

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

build:
  stage: build
  image: "python:3.12"
  script:
    - "pip install pipenv"
    - "pipenv install"
    - "pipenv graph --json-tree > pipenv.graph.json"
  artifacts:
    when: on_success
    access: developer
    paths: ["**/pipenv.graph.json"]

sbt#

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

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

다음 예제 .gitlab-ci.yml은 sbt 프로젝트에서 의존성 경로 지원으로 분석기를 활성화하는 방법을 보여줍니다. build 스테이지는 의존성 스캔이 실행되기 전에 의존성 그래프를 job 아티팩트로 출력합니다.

stages:
  - build
  - test

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

build:
  stage: build
  image: "sbtscala/scala-sbt:eclipse-temurin-17.0.13_11_1.10.7_3.6.3"
  script:
    - "sbt dependencyDot"
  artifacts:
    when: on_success
    access: developer
    paths: ["**/dependencies-compile.dot"]

결과 이해하기#

의존성 스캔 분석기 출력:

• 감지된 지원되는 잠금 파일 또는 의존성 그래프 내보내기마다 CycloneDX SBOM.
• 스캔된 모든 SBOM 문서에 대한 단일 의존성 스캔 보고서(GitLab.com 및 GitLab Self-Managed만 해당).

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

의존성 스캔 분석기는 감지하는 지원되는 각 잠금 또는 의존성 그래프 내보내기에 대해 CycloneDX 소프트웨어 자재명세서(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

여러 CycloneDX SBOM 병합#

CI/CD job을 사용하여 여러 CycloneDX SBOM을 단일 SBOM으로 병합할 수 있습니다.

예를 들어, 다음 .gitlab-ci.yml 추출본은 Cyclone SBOM 파일을 병합하고 결과 파일을 검증하는 방법을 보여줍니다.

stages:
  - test
  - merge-cyclonedx-sboms

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

merge cyclonedx sboms:
  stage: merge-cyclonedx-sboms
  image:
    name: cyclonedx/cyclonedx-cli:0.27.1
    entrypoint: [""]
  script:
    - find . -name "gl-sbom-*.cdx.json" -exec cyclonedx merge --output-file gl-sbom-all.cdx.json --input-files "{}" +
    # 선택 사항: 병합된 sbom 검증
    - cyclonedx validate --input-version v1_6 --input-file gl-sbom-all.cdx.json
  artifacts:
    paths:
      - gl-sbom-all.cdx.json

의존성 스캔 보고서#

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

의존성 스캔 보고서는:

• gl-dependency-scanning-report.json으로 이름이 지정됩니다.
• 의존성 스캔 job의 job 아티팩트로 사용 가능합니다.
• dependency_scanning 보고서로 업로드됩니다.
• 프로젝트의 루트 디렉토리에 저장됩니다.

최적화#

SBOM을 사용한 의존성 스캔을 최적화하려면 다음 방법 중 하나를 사용합니다:

• 경로 제외
• 최대 디렉토리 깊이로 스캔 제한

경로 제외#

스캔 성능을 최적화하고 관련 리포지터리 내용에 집중하려면 경로를 제외합니다.

.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로 계산되며, 각 하위 디렉토리는 깊이를 1씩 증가시킵니다. 기본 깊이는 2입니다. 값 -1은 깊이에 관계없이 모든 디렉토리를 스캔합니다.

.gitlab-ci.yml 파일에서 최대 깊이를 지정하려면:

• 의존성 스캔 템플릿을 사용하는 경우 DS_MAX_DEPTH CI/CD 변수를 사용합니다.
• 의존성 스캔 CI/CD 컴포넌트를 사용하는 경우 max_scan_depth spec 입력을 사용합니다.

다음 예제에서 DS_MAX_DEPTH가 3으로 설정되면 common 디렉토리의 하위 디렉토리는 스캔되지 않습니다.

timer
├── integration
│   ├── doc
│   └── modules
└── source
    ├── common
    │   ├── cplusplus
    │   └── go
    ├── linux
    ├── macos
    └── windows

롤아웃#

단일 프로젝트에 대한 SBOM을 사용한 의존성 스캔 결과에 확신이 생긴 후, 여러 프로젝트와 그룹으로 구현을 확장할 수 있습니다. 자세한 내용은 여러 프로젝트에 스캔 적용을 참조하세요.

고유한 요구사항이 있는 경우 SBOM을 사용한 의존성 스캔을 오프라인 환경에서 실행할 수 있습니다.

지원되는 패키지 유형#

보안 분석이 효과적이려면 SBOM 보고서에 나열된 컴포넌트가 GitLab 어드바이저리 데이터베이스에 해당 항목이 있어야 합니다.

GitLab SBOM 취약점 스캐너는 다음 PURL 유형을 가진 컴포넌트에 대한 의존성 스캔 취약점을 보고할 수 있습니다:

• cargo
• composer
• conan
• gem
• golang
• maven
• npm
• nuget
• pypi
• swift

지원되는 언어 및 파일#

각주:

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

패키지 해시 정보#

의존성 스캔 SBOM에는 사용 가능한 경우 패키지 해시 정보가 포함됩니다. 이 정보는 NuGet 패키지에만 제공됩니다. 패키지 해시는 SBOM 내의 다음 위치에 나타나며, 패키지 무결성 및 신뢰성을 검증할 수 있습니다:

• 전용 해시 필드
• PURL 한정자

예를 들어:

{
  "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"
}

분석기 동작 커스터마이즈#

분석기를 커스터마이즈하는 방법은 활성화 솔루션에 따라 다릅니다.

CI/CD 템플릿으로 동작 커스터마이즈#

사용 가능한 spec 입력#

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

사용 가능한 CI/CD 변수#

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

커스텀 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-----

매니페스트 폴백#

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

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

매니페스트 폴백을 활성화하려면 DS_ENABLE_MANIFEST_FALLBACK CI/CD 변수를 "true"로 설정합니다.

애플리케이션 스캔 방법#

SBOM을 사용한 의존성 스캔 기능은 의존성 감지를 정적 도달 가능성이나 취약점 스캔과 같은 다른 분석과 분리하는 분해된 의존성 분석 접근 방식에 의존합니다.

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

의존성 스캔의 전체 흐름은 아래에 설명되어 있습니다.

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 --&gt; END</code></pre></details></div>

의존성 감지 단계에서 분석기는 사용 가능한 잠금 파일을 파싱하여 프로젝트 의존성 및 그 관계(의존성
그래프)의 포괄적인 인벤토리를 빌드합니다. 이 인벤토리는 CycloneDX SBOM(소프트웨어 자재명세서)
문서에 캡처됩니다.
정적 도달 가능성 단계에서 분석기는 소스 파일을 파싱하여 어떤 SBOM 컴포넌트가 적극적으로
사용되는지 식별하고 SBOM 파일에 적절히 표시합니다.
이를 통해 사용자는 취약한 컴포넌트가 도달 가능한지 여부에 따라 취약점의 우선순위를 정할 수 있습니다.
자세한 내용은 정적 도달 가능성 페이지를 참조하세요.
SBOM 문서는 의존성 스캔 SBOM API를 통해 GitLab 인스턴스에 임시로 업로드됩니다.
GitLab SBOM 취약점 스캐너 엔진은 SBOM 컴포넌트를 어드바이저리와 대조하여 결과 목록을 생성하고,
이는 의존성 스캔 보고서에 포함하기 위해 분석기에 반환됩니다.
API는 인증을 위해 기본 CI_JOB_TOKEN을 사용합니다. CI_JOB_TOKEN 값을 다른 토큰으로
재정의하면 API에서 403 - 금지됨 응답이 발생할 수 있습니다.
사용자는 의존성 스캔 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에 의해 선언된 경우: 보안 결과가 생성되어
파이프라인 보기의 security 탭 및 MR 보안 위젯에서 볼 수 있습니다.

오프라인 지원#
인터넷을 통해 외부 리소스에 대한 제한적이거나 제한되거나 간헐적인 접근이 있는 환경의 인스턴스의 경우,
의존성 스캔 job을 성공적으로 실행하려면 몇 가지 조정이 필요합니다.
자세한 내용은 오프라인 환경을 참조하세요.
요구사항#
오프라인 환경에서 의존성 스캔을 실행하려면 다음이 필요합니다:

docker 또는 kubernetes executor가 있는 GitLab Runner.
의존성 스캔 분석기 이미지의 로컬 복사본.
패키지 메타데이터 데이터베이스 접근. 의존성에 대한 라이선스 및 어드바이저리 데이터가 필요합니다.

분석기 이미지의 로컬 복사본#
의존성 스캔 분석기를 사용하려면:


registry.gitlab.com에서 로컬 Docker 컨테이너 레지스트리로
다음 기본 의존성 스캔 분석기 이미지를 가져옵니다:
registry.gitlab.com/security-products/dependency-scanning:1

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 템플릿 사용#
Warning
latest 템플릿은 안정적으로 간주되지 않으며 호환성을 깨는 변경 사항이 포함될 수 있습니다. 템플릿 에디션을 참조하세요.

latest 의존성 스캔 CI/CD 템플릿 Dependency-Scanning.latest.gitlab-ci.yml을 사용하여
GitLab에서 제공하는 분석기를 활성화합니다.


(더 이상 사용되지 않는) 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 변수를 사용합니다.
latest 템플릿의 트리거 파일#
트리거 파일은 최신 의존성 스캔 CI/CD 템플릿을 사용할 때
dependency-scanning CI/CD job을 생성합니다.
분석기는 이 파일을 스캔하지 않습니다.
잠금 파일 또는 의존성 그래프를 생성하기 위한 트리거 파일을 사용하는 경우 프로젝트가 지원될 수 있습니다.



언어
파일




C#/Visual Basic
*.csproj, *.vbproj


Java
pom.xml


Java/Kotlin
build.gradle, build.gradle.kts


Python
requirements.pip, Pipfile, requires.txt, setup.py


Scala
build.sbt



의존성 스캔 CI/CD 컴포넌트 사용#
히스토리
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 가져오기#
Warning
서드파티 SBOM 지원은 기술적으로 가능하지만 이 에픽으로 공식 지원을 완료함에 따라 크게 변경될 수 있습니다.

서드파티 CycloneDX SBOM 생성기 또는 커스텀 도구로 생성된 자체 CycloneDX SBOM 문서를 커스텀 CI job에서
CI/CD 아티팩트 보고서로 사용합니다.
SBOM을 사용한 의존성 스캔을 활성화하려면 제공된 CycloneDX SBOM 문서가 다음을 충족해야 합니다:

버전 1.4, 1.5 또는 1.6의 CycloneDX 사양을 준수합니다. CycloneDX Web Tool에서 온라인 검증기를 사용할 수 있습니다.
GitLab CycloneDX 속성 분류체계를 준수합니다.
성공적인 CI job에서 CI/CD 아티팩트 보고서로 업로드됩니다.

문제 해결#
의존성 스캔 작업 시 다음 문제가 발생할 수 있습니다.
커스텀 CI_JOB_TOKEN 사용 시 403 Forbidden 오류#
스캔 업로드 또는 다운로드 단계에서 의존성 스캔 SBOM API가 403 Forbidden 오류를 반환할 수 있습니다.
이는 의존성 스캔 SBOM API가 인증을 위해 기본 CI_JOB_TOKEN을 필요로 하기 때문입니다.
커스텀 토큰(예: 프로젝트 접근 토큰 또는 개인 접근 토큰)으로 CI_JOB_TOKEN 변수를 재정의하면,
커스텀 토큰이 api 범위를 가지더라도 API가 요청을 제대로 인증할 수 없습니다.
이 문제를 해결하려면 다음 중 하나를 수행합니다:

권장. CI_JOB_TOKEN 재정의를 제거합니다. 미리 정의된 변수를 재정의하면 예상치 못한 동작이 발생할 수 있습니다.
자세한 내용은 CI/CD 변수를 참조하세요.
다른 변수 이름을 사용합니다. 파이프라인의 다른 목적으로 커스텀 토큰을 사용해야 하는 경우
CI_JOB_TOKEN을 재정의하는 대신 CUSTOM_ACCESS_TOKEN과 같이 다른 CI/CD 변수에 저장합니다.

GitLab은 의존성 스캔 API 엔드포인트에 대한 세분화된 job 권한을
지원하지 않지만, 이슈 578850에서 이 기능을 추가하도록 제안됩니다.
경고: grep: command not found#
분석기 이미지에는 이미지의 공격 표면을 줄이기 위한 최소한의 의존성만 포함됩니다.
결과적으로 다른 이미지에서 흔히 발견되는 grep과 같은 유틸리티가 이미지에 없습니다.
이로 인해 job 로그에 /usr/bin/bash: line 3: grep: command not found와 같은 경고가 나타날 수 있습니다.
이 경고는 분석기 결과에 영향을 미치지 않으며 무시할 수 있습니다.
컴플라이언스 프레임워크 호환성#
GitLab Self-Managed 인스턴스에서 SBOM 기반 의존성 스캔을 사용하는 경우 컴플라이언스 프레임워크와의 호환성을 고려해야 합니다:

GitLab.com(SaaS): "의존성 스캔 실행 중" 컴플라이언스 제어는 SBOM 기반 의존성 스캔과 올바르게 작동합니다.
GitLab Self-Managed 18.4 이상: SBOM 기반 의존성 스캔(DS_ENFORCE_NEW_ANALYZER: 'true')을 사용할 때 기존 gl-dependency-scanning-report.json 아티팩트가 생성되지 않기 때문에 "의존성 스캔 실행 중" 컴플라이언스 제어가 실패할 수 있습니다.

Self-Managed 인스턴스의 해결 방법: "의존성 스캔 실행 중" 제어를 필요로 하는 컴플라이언스 프레임워크 검사를 통과해야 하는 경우, SBOM 및 의존성 스캔 보고서를 모두 생성하는 v2 템플릿(Jobs/Dependency-Scanning.v2.gitlab-ci.yml)을 사용할 수 있습니다.
컴플라이언스 제어에 대한 자세한 내용은 GitLab 컴플라이언스 제어를 참조하세요.
오류: failed to verify certificate: x509: certificate signed by unknown authority#
의존성 스캔 분석기가 호스트에 연결할 때 다음 오류가 발생할 수 있습니다. 이 오류의 원인은
의존성 스캔 분석기에서 사용하는 인증서를 호스트가 신뢰하지 않는다는 것입니다.
failed to verify certificate: x509: certificate signed by unknown authority

이 문제를 해결하려면 ADDITIONAL_CA_CERT_BUNDLE CI/CD 변수에 자체 서명 인증서를 제공합니다.
그러면 이 인증서가 호스트에 연결할 때 의존성 스캔 분석기에서 사용됩니다.
ADDITIONAL_CA_CERT_BUNDLE 환경 변수의 값은 인증서 자체여야 합니다:
include:
  - template: Jobs/Dependency-Scanning.v2.gitlab-ci.yml

dependency-scanning:
  variables:
    ADDITIONAL_CA_CERT_BUNDLE: |
      -----BEGIN CERTIFICATE-----
      <...>
      -----END CERTIFICATE-----
  before_script:
    - echo "$ADDITIONAL_CA_CERT_BUNDLE" > /tmp/cacert.pem
    - export SSL_CERT_FILE="/tmp/cacert.pem"