InfoGrab DocsInfoGrab Docs

의존성 스캔 자동 수정

요약

의존성 스캔 자동 수정은 취약한 의존성을 올릴 수 있는 취약하지 않은 버전이 있으면, 해당 버전으로 올리는 머지 리퀘스트를 엽니다. 베타에서 의존성 스캔 자동 수정은 독립적으로 구성할 수 있는 두 가지 기능을 지원합니다.

히스토리
  • GitLab 19.0에서 dependency_management_auto_remediation이라는 기능 플래그와 함께
  • GitLab 19.2에서 실험에서
  • GitLab 19.2에서 enable_dependency_bump_breaking_changes라는
  • GitLab 19.3에서 Go 모듈 지원이 도입되었습니다.
  • GitLab 19.3에서 Cargo(Rust) 지원이 도입되었습니다.
  • GitLab 19.3에서 기능 플래그 dependency_management_auto_remediation이
  • GitLab 19.4에서 NuGet(.NET) 지원이 도입되었습니다.
  • GitLab 19.5에서 Pub(Dart와 Flutter) 지원이 도입되었습니다.
  • GitLab 19.4에서 triage_and_remediation_profile이라는 기능 플래그와 함께 분류 및 수정 프로필 지원이 도입되었습니다. 기본적으로 활성화되어 있습니다.
  • GitLab 19.4에서 기능 플래그 enable_dependency_bump_breaking_changes가
  • GitLab 19.6에서 자동 수정 job용 러너 태그가 도입되었습니다.
  • GitLab 19.6에서 Swift Package Manager 지원이 도입되었습니다.
  • GitLab 19.6에서 머지 리퀘스트 제목과 커밋 메시지의 Conventional Commits 형식이
  • GitLab 19.6에서 dependency_management_scheduler_rate_limit이라는

의존성 스캔 자동 수정은 취약한 의존성을 올릴 수 있는 취약하지 않은 버전이 있으면, 해당 버전으로 올리는 머지 리퀘스트를 엽니다. 서비스 계정이 사람의 입력 없이 머지 리퀘스트를 생성하며, 이후 이 머지 리퀘스트는 표준 검토 및 승인 절차를 거칩니다.

베타에서 의존성 스캔 자동 수정은 독립적으로 구성할 수 있는 두 가지 기능을 지원합니다.

  • 의존성 버전 상향: GitLab이 취약한 의존성을 업데이트하는 머지 리퀘스트를 엽니다.
  • 에이전트 방식 브레이킹 체인지 해결: 버전 상향이 브레이킹 체인지 때문에 파이프라인 실패를 일으키면 GitLab Duo가 이를 해결하려고 시도합니다. 자세한 내용은 에이전트 방식 브레이킹 체인지 해결 활성화를 참고합니다.

일반 공급 로드맵은 에픽 19244를 참고합니다.

보안 구성 프로필도 이 플로를 지원합니다. 여러 프로젝트와 그룹에서 플로를 한 번에 켜고 구성하려면 자동화된 분류 및 수정 프로필을 사용합니다.

의존성 스캔 자동 수정 켜기#

사전 요구 사항:

  • 의존성 스캔이 활성화되어 있고 결과를 생성해야 합니다. 스캔이 실행되어야 하고, 결과가 기본 브랜치에 보고되어야 합니다.
  • 프로젝트가 지원되는 패키지 관리자를 사용해야 합니다.
  • 의존성 스캔 자동 수정 프로필이 프로젝트에 연결되어 있어야 합니다. 설명은 의존성 스캔 자동 수정 프로필을 참고합니다.
  • 프로필에 러너 태그를 설정하지 않았다면, 러너가 태그가 없는 job을 수락해야 합니다. GitLab은 자동 수정 job을 직접 생성하며 이 job에 프로젝트의 .gitlab-ci.yml 구성을 사용하지 않으므로 default:tags가 적용되지 않습니다.
  • 러너가 권한 있는(privileged) 모드를 허용해야 합니다. 자동 수정 job은 docker:28-dind 서비스를 사용합니다. 자세한 내용은 Docker를 사용해 Docker 이미지 빌드를 참고합니다.
  • 러너가 registry.gitlab.com에서 자동 수정 오케스트레이터 이미지를, 그리고 docker:28-dind 이미지를 가져올 수 있어야 합니다.

취약점 탐지와 자동 수정을 트리거하려면 파이프라인을 실행합니다. GitLab이 수정 가능한 버전이 있는 취약점을 탐지하면 의존성 스캔 자동 수정이 자동으로 트리거됩니다.

의존성 버전 상향 작동 방식#

이 동작은 의존성 스캔 자동 수정 프로필이 제어합니다. 기본 프로필에서는 다음과 같이 동작합니다.

  • 심각도 임계값: GitLab은 심각도가 high 이상인 취약점을 수정합니다.
  • 쿨다운 기간: GitLab은 최근 7일 이내에 릴리스된 수정 버전을 제외합니다.
  • 업그레이드 정책: 에이전트 방식 브레이킹 체인지 해결을 활성화하지 않으면 GitLab은 패치와 마이너 버전 상향만 제안합니다.
  • 열린 머지 리퀘스트 한도: 프로젝트당 자동 수정 머지 리퀘스트는 한 번에 최대 30개까지 열 수 있습니다. 기존 머지 리퀘스트가 머지되거나 닫힐 때까지 GitLab은 새 머지 리퀘스트를 생성하지 않습니다.

각 파이프라인이 끝나면 GitLab은 이 값을 기준으로 의존성 스캔 결과를 확인합니다. 대상이 되는 각 취약점에 대해 다음을 수행합니다.

  1. GitLab이 브레이킹 체인지가 없는 가장 가까운 업그레이드 경로를 결정합니다.
  2. 서비스 계정이 관련 매니페스트 파일을 업데이트하는 머지 리퀘스트를 엽니다.
  3. GitLab은 리뷰어를 지정하지 않습니다. 업데이트된 파일의 Code Owners가 리뷰어로 요청되도록 하려면 자동 리뷰어 지정을 켭니다.
  4. 머지 리퀘스트는 프로젝트의 표준 승인 워크플로를 거칩니다.

베타 기간에는 GitLab이 가장 심각도가 높은 결과부터 시작해 한 번에 취약점 세 개를 처리합니다.

Feature flag

스케줄러 속도 제한의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 기록을 참고합니다.

스케줄러 속도 제한을 활성화하면 GitLab은 프로젝트마다 5분에 최대 한 번만 스케줄러 실행을 시작합니다. 무시된 업데이트로 비워진 슬롯을 채우는 실행에는 별도의 제한이 있으며, 5분에 한 번입니다. 자세한 내용은 구성할 수 없는 속도 제한을 참고합니다.

머지 리퀘스트 제목과 커밋 메시지#

기본적으로 자동 수정 머지 리퀘스트의 제목은 Security: Update rack from 2.0.9 to 2.2.0와 같은 형태입니다. 커밋 제목은 Update rack입니다.

기본 브랜치가 Conventional Commits를 따르면 GitLab은 머지 리퀘스트 제목과 커밋 제목 모두에 이 형식을 사용합니다. 예를 들면 다음과 같습니다.

build(deps): [security] update rack from 2.0.9 to 2.2.0

GitLab은 기본 브랜치에서 가장 최근의 머지 커밋이 아닌 커밋을 최대 20개 샘플링하며, 자동 수정 서비스 계정이 만든 커밋은 건너뜁니다. GitLab은 머지 커밋이 아닌 커밋을 최대 50개까지만 거슬러 올라가 검색합니다. 이 커밋의 30% 이상이 대소문자와 관계없이 다음 유형 중 하나로 시작하면 프로젝트가 Conventional Commits를 사용하는 것으로 간주합니다. build, chore, ci, docs, feat, fix, perf, refactor, style, test. 유형 뒤에는 선택적 스코프와 선택적 ! 브레이킹 체인지 표시가 올 수 있습니다.

그렇지 않으면 GitLab은 기본 형식을 사용합니다. 예를 들어 이모지나 deps: 같은 사용자 지정 접두사를 사용하는 프로젝트에는 기본 형식이 적용됩니다.

Conventional Commits를 사용하는 프로젝트에서는 GitLab이 일치하는 커밋의 스타일을 따라 합니다.

  • 일치하는 커밋이 chore를 사용하고 build는 사용하지 않으면 유형은 chore입니다. 그렇지 않으면 유형은 build입니다.
  • 일치하는 커밋 대부분이 유형을 대문자로 시작하면 Build(deps):처럼 유형을 대문자로 씁니다.
  • 스코프는 항상 deps입니다.
  • (deps): 뒤의 텍스트는 일치하는 커밋 대부분이 제목을 대문자로 시작하면 [Security] Update이고, 그렇지 않으면 [security] update입니다.

Conventional Commits 제목이 72자보다 길면 GitLab은 제목과 커밋 제목에서 이전 버전을 생략해 build(deps): [security] update rack to 2.2.0처럼 만듭니다.

GitLab이 열려 있는 머지 리퀘스트를 업데이트할 때는 기본 브랜치 기록이 바뀌더라도 머지 리퀘스트를 생성할 때 사용한 Conventional Commits 스타일을 유지합니다. 기본 형식을 사용하는 머지 리퀘스트는 이후 기본 브랜치가 해당 규칙을 따르는 경우 GitLab이 다음에 업데이트할 때 Conventional Commits로 전환됩니다.

에이전트 방식 브레이킹 체인지 해결 활성화#

버전 상향이 브레이킹 체인지 때문에 파이프라인 실패를 일으키면, GitLab Duo가 브레이킹 체인지를 자동으로 해결하려고 시도할 수 있습니다. 이 기능은 의존성 버전 상향 기능과 별개이며 자체 토글이 있습니다.

사전 요구 사항:

  • 프로젝트에서 GitLab Duo를 사용할 수 있어야 합니다.

에이전트 방식 브레이킹 체인지 해결을 활성화하려면 프로젝트 API를 사용해 프로젝트의 duo_dependency_bump_breaking_changes_enabled를 true로 설정합니다.

스케줄러 동시성 구성#

관리자는 Sidekiq 전체에서 동시에 실행되는 자동 수정 스케줄러 job의 수를 제한할 수 있습니다. security_update_scheduler_max_concurrency 애플리케이션 설정으로 상한을 설정합니다. 기본값은 30이며, 값의 상한은 200입니다. 스케줄링을 일시 중지하려면 값을 0으로 설정합니다.

자동 수정 job용 러너 태그 설정#

러너 플릿에서 태그를 사용한다면 자동 수정 job에 태그를 지정해, 일치하는 태그가 있는 러너만 해당 job을 가져가도록 할 수 있습니다. 기본적으로 job에는 태그가 없습니다. GitLab 권장 프로필은 편집할 수 없으므로 직접 프로필을 만들어야 합니다.

사전 요구 사항:

  • 그룹에 대한 Security Manager, Maintainer 또는 Owner 권한.

러너 태그를 설정하려면 다음을 수행합니다.

  1. securityScanProfileCreate 뮤테이션으로 의존성 스캔 자동 수정 프로필을 생성하고 runnerTags를 설정합니다.

    mutation {
      securityScanProfileCreate(input: {
        namespaceId: "gid://gitlab/Group/123",
        scanType: DEPENDENCY_SCANNING_POST_PROCESSING,
        name: "Auto-remediation on tagged runners",
        description: "Runs auto-remediation jobs on runners tagged docker and linux",
        triggers: [
          {
            triggerType: SBOM_INGESTED,
            configuration: {
              dependencyScanningPostProcessing: {
                autoRemediation: {
                  runnerTags: ["docker", "linux"]
                }
              }
            }
          }
        ]
      }) {
        scanProfile {
          id
          name
        }
        errors
      }
    }
    

    지정하지 않은 설정은 기본값을 유지합니다.

  2. 프로필을 프로젝트 또는 그룹에 연결합니다. 설명은 GraphQL API로 프로필 적용을 참고합니다.

나중에 태그를 변경하려면 securityScanProfileUpdate 뮤테이션으로 프로필을 업데이트합니다. 업데이트는 프로필의 트리거와 해당 설정을 대체하므로, runnerTags뿐 아니라 유지하려는 모든 트리거와 설정을 포함해야 합니다.

runnerTags 설정에는 다음 제한이 있습니다.

  • 태그는 최대 20개입니다.
  • 각 태그의 길이는 1~255자입니다.
  • 태그는 중복될 수 없습니다.
  • 태그에는 쉼표, 따옴표(" 또는 '), $를 사용할 수 없습니다.
  • 태그는 공백으로 시작하거나 끝날 수 없습니다.

자동화된 분류 및 수정 프로필은 같은 필드를 triageAndRemediation.sbomIngested.autoRemediation.runnerTags에서 받습니다.

지원되는 패키지 관리자#

의존성 스캔 자동 수정은 다음 패키지 관리자를 지원합니다.

언어 패키지 관리자 파일
Ruby Bundler Gemfile, Gemfile.lock
Java Maven pom.xml
Java Gradle build.gradle, build.gradle.kts
Python pip, pipenv, poetry, setuptools, uv requirements.txt, Pipfile, pyproject.toml, setup.py, uv.lock
JavaScript / TypeScript npm, yarn, pnpm, bun package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock
Go Go modules go.mod, go.sum
Rust Cargo Cargo.toml, Cargo.lock
.NET NuGet *.csproj, packages.lock.json
Dart and Flutter Pub pubspec.yaml, pubspec.lock
Swift Swift Package Manager Package.swift, Package.resolved

추가 에코시스템 지원은 에픽 19244에서 제안되었습니다.

.NET에서는 의존성 스캔이 커밋된 packages.lock.json에서만 NuGet 의존성을 탐지합니다. 이 파일이 없는 프로젝트는 NuGet 결과가 생성되지 않으므로 자동 수정이 처리할 대상이 없습니다. 잠금 파일을 생성하려면 프로젝트 파일에 RestorePackagesWithLockFile을 설정하고 결과를 커밋합니다.

Dart와 Flutter에서는 의존성 스캔이 커밋된 pubspec.lock에서만 Pub 의존성을 탐지합니다. 이 파일이 없는 프로젝트는 Pub 결과가 생성되지 않으므로 자동 수정이 처리할 대상이 없습니다. dart pub get 또는 flutter pub get을 실행해 잠금 파일을 생성하고 결과를 커밋합니다. 또한 순수 Dart 프로젝트라도 업데이터가 의존성을 해결하기 전에 Flutter SDK를 설정하므로, Pub 자동 수정 job은 다른 에코시스템보다 몇 분 더 걸립니다.

Swift에서는 의존성 스캔이 커밋된 Package.resolved에서만 의존성을 탐지합니다. 이 파일이 없는 프로젝트는 Swift 결과가 생성되지 않으므로 자동 수정이 처리할 대상이 없습니다. swift package resolve를 실행해 잠금 파일을 생성하고 결과를 커밋합니다. 브랜치나 커밋에 고정된 의존성은 Package.resolved에 버전이 기록되지 않으므로 자동 수정이 건너뜁니다.

서비스 계정 권한#

프로젝트에서 의존성 스캔 자동 수정이 처음 실행되면 GitLab은 GitLab Dependency Management라는 프로젝트용 서비스 계정을 생성합니다. GitLab은 이후 해당 프로젝트의 모든 자동 수정 머지 리퀘스트에 이 계정을 재사용하므로, 프로젝트마다 계정이 정확히 하나만 있습니다.

GitLab은 서비스 계정을 Guest 멤버로 프로젝트에 추가합니다. 이 멤버십은 계정을 프로젝트의 멤버로 만들 뿐 다른 권한은 부여하지 않습니다. 대신 전용 내부 역할이 계정에 다음 권한을 부여합니다.

  • 리포지터리 클론.
  • 브랜치 푸시.
  • 머지 리퀘스트 생성 및 업데이트.
  • 파이프라인 생성.

계정이 할 수 있는 일의 범위는 Guest 멤버십이 아니라 이 내부 역할이 정합니다. 더 넓은 권한은 계정에 부여하지 않습니다. 이 설계는 기능을 켠 모든 프로젝트에서 자동화된 계정에 Developer 권한을 주는 대신, 이러한 권한을 직접적이고 좁게 부여하기 때문입니다. 이 설계의 전체 근거는 ADR 003: Single service account model을 참고합니다.

내부 역할은 프로젝트가 머지 리퀘스트에 설정한 가시성을 재정의하지 않습니다. 프로젝트가 머지 리퀘스트를 프로젝트 멤버로 제한하면 Reporter 권한 이상의 사용자만 머지 리퀘스트를 생성할 수 있습니다. 이 경우 자동 수정은 해당 프로젝트에 머지 리퀘스트를 생성하지 않습니다. 해결 방법은 자동 수정이 머지 리퀘스트를 생성하지 않음을 참고합니다.

자동 수정 머지 리퀘스트의 파이프라인은 이 서비스 계정으로 실행됩니다. job에 해당 역할이 부여하는 권한을 넘어서는 권한이 필요하면, 같은 파이프라인을 Developer 권한이 있는 사용자가 실행할 때는 성공하더라도 job이 실패합니다. 예를 들면 다음과 같습니다.

  • 프로젝트 컨테이너 레지스트리에 컨테이너 이미지를 푸시하려면 Developer 권한이 필요합니다. 프로젝트 컨테이너 레지스트리에서 기존 이미지를 가져오는 것은 서비스 계정의 권한으로 가능합니다.
  • 프로젝트 패키지 레지스트리를 읽으려면 Reporter 권한이 필요합니다.

Auto DevOps 빌드 job은 이미지를 푸시하므로 Auto DevOps를 사용하는 프로젝트는 컨테이너 레지스트리 사례에 해당합니다.

이러한 job이 실행되도록 하려면 Maintainer 권한 이상의 사용자가 서비스 계정에 프로젝트의 Developer 권한을 부여할 수 있습니다. 설명은 자동 수정 파이프라인 job이 권한 오류로 실패함을 참고합니다.

알려진 문제#

베타 단계에서는 다음과 같은 제한이 있습니다.

  • 쿨다운 기간: 나중에 문제가 있거나 악성으로 밝혀질 수 있는 버전으로 수정하는 위험을 줄이기 위해, GitLab은 최근 7일 이내에 릴리스된 수정 버전을 제안하지 않습니다.
  • 버전 상향 범위: 패치와 마이너 버전 상향만 제안합니다. 브레이킹 체인지가 생길 가능성이 더 큰 메이저 버전 업그레이드는 에이전트 방식 브레이킹 체인지 해결을 활성화하지 않으면 시도하지 않습니다.
  • 파이프라인 실행당 취약점 하나: 파이프라인을 실행할 때마다 수정 버전이 있는 취약점 하나만 대상으로 합니다. 여러 수정을 머지 리퀘스트 하나로 묶는 기능은 에픽 19244에서 제안되었습니다.
  • 수정 버전 없음: 취약점에 브레이킹 체인지가 없는 수정 버전이 없으면 해당 결과에 대해서는 머지 리퀘스트를 생성하지 않습니다.
  • 머지 리퀘스트 생성은 파이프라인 성공 여부에 따라 달라집니다. GitLab은 자동 수정 파이프라인을 해당 브랜치에서 실행하기 전에 dependency-management/<dependency>-<major-version>.x 브랜치를 생성하고, 파이프라인이 성공한 후에야 머지 리퀘스트를 생성합니다. 머지 리퀘스트가 없고 매니페스트 파일을 변경하는 커밋도 없는 dependency-management/ 브랜치는 파이프라인이 성공하지 못했다는 뜻입니다. 해당 브랜치의 파이프라인 상태를 확인합니다.

문제 해결#

자동 수정 파이프라인 job이 권한 오류로 실패함#

자동 수정 머지 리퀘스트의 파이프라인 job은 GitLab Dependency Management 서비스 계정으로 실행됩니다. 이 계정은 함께 가진 Guest 권한이 아니라 내부 역할에서 권한을 얻습니다. 이 내부 역할은 프로젝트 파이프라인에 필요할 수 있는 모든 권한을 포함하지 않습니다. 자세한 내용은 서비스 계정 권한을 참고합니다. 해당 역할이 부여하는 권한을 넘어서는 권한이 필요한 job은, 같은 job을 Developer 권한이 있는 사용자가 실행할 때는 성공하더라도 실패합니다. 오류는 job마다 다릅니다. 예를 들어 프로젝트 컨테이너 레지스트리에 이미지를 푸시하는 job은 거부 응답을 받고, 프로젝트 패키지 레지스트리를 읽는 job은 403 오류를 받습니다.

이 문제를 우회하려면 Maintainer 권한 이상의 사용자가 서비스 계정에 프로젝트의 Developer 권한을 부여할 수 있습니다.

  1. 왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
  2. Manage > Members를 선택합니다.
  3. GitLab Dependency Management 멤버를 찾습니다.
  4. 해당 멤버의 권한을 Developer로 변경합니다.

이 작업은 서비스 계정에 프로젝트의 Developer 권한 전체를 부여합니다. 파이프라인에 필요한 경우에만 변경합니다. 이 변경은 해당 프로젝트에만 적용됩니다. 변경 사항은 유지되므로 이후 프로젝트의 자동 수정 머지 리퀘스트에서는 파이프라인이 정상적으로 작동합니다. 실패한 파이프라인을 다시 실행해 변경 사항을 반영합니다.

자동 수정이 머지 리퀘스트를 생성하지 않음#

의존성 스캔은 기본 브랜치에서 실행되지만, GitLab Dependency Management 서비스 계정이 프로젝트에서 머지 리퀘스트를 생성할 수 없으면 자동 수정은 머지 리퀘스트를 생성하지 않습니다. 해당 프로젝트에서는 다음과 같이 동작합니다.

  • GitLab이 dependency-management/ 브랜치를 생성하거나 업데이트하지 않습니다.
  • 열려 있는 자동 수정 머지 리퀘스트가 더 이상 갱신되지 않습니다.
  • 취약점 보고서에서 수정을 시작하면 보고서에 Service account cannot create merge requests in this project 오류가 표시됩니다.

같은 오류에도 원인이 여러 가지입니다. GitLab Self-Managed에서는 관리자가 application_json.log의 DependencyManagement: service account cannot create merge requests 항목에 있는 denial_reason 필드에서 원인을 찾을 수 있습니다.

원인 denial_reason 해결 방법
머지 리퀘스트가 로 설정되어 있습니다. merge_requests_private 서비스 계정에 Reporter 권한을 부여합니다.
프로젝트에서 머지 리퀘스트가 꺼져 있습니다. merge_requests_disabled 프로젝트에서 머지 리퀘스트를 켭니다.
프로젝트에서 리포지터리가 꺼져 있습니다. repository_disabled 프로젝트에서 리포지터리를 켭니다.
프로젝트가 보관되었거나 서비스 계정이 프로젝트에서 제거되었습니다. access_denied 프로젝트 보관을 해제하거나 서비스 계정을 멤버로 다시 추가합니다.
네임스페이스가 읽기 전용입니다. access_denied 네임스페이스의 읽기 전용 상태를 해제합니다.

서비스 계정은 프로젝트의 Guest 멤버입니다. 머지 리퀘스트가 로 설정되어 있으면 Reporter 권한 이상의 사용자만 머지 리퀘스트를 생성할 수 있습니다. 계정의 내부 역할은 이 요구 사항을 재정의하지 않습니다. 자세한 내용은 서비스 계정 권한을 참고합니다.

서비스 계정에 Reporter 권한을 부여하려면 Maintainer 권한 이상의 사용자가 다음을 수행할 수 있습니다.

  1. 상단 바에서 를 선택하고 프로젝트를 찾습니다.
  2. > 를 선택합니다.
  3. GitLab Dependency Management 멤버를 찾습니다.
  4. 해당 멤버의 권한을 Reporter로 변경합니다.

또는 머지 리퀘스트의 가시성을 로 설정합니다. 공개 프로젝트에서는 이 설정으로 프로젝트 멤버가 아닌 사용자도 머지 리퀘스트를 생성할 수 있습니다.

이러한 변경 사항은 다음에 기본 브랜치에서 의존성 스캔이 실행될 때 자동 수정에 반영됩니다.

의존성 스캔 자동 수정

GitLab v19.6
Tier: Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
원문 보기

요약

의존성 스캔 자동 수정은 취약한 의존성을 올릴 수 있는 취약하지 않은 버전이 있으면, 해당 버전으로 올리는 머지 리퀘스트를 엽니다. 베타에서 의존성 스캔 자동 수정은 독립적으로 구성할 수 있는 두 가지 기능을 지원합니다.

히스토리
  • GitLab 19.0에서 dependency_management_auto_remediation이라는 기능 플래그와 함께
  • GitLab 19.2에서 실험에서
  • GitLab 19.2에서 enable_dependency_bump_breaking_changes라는
  • GitLab 19.3에서 Go 모듈 지원이 도입되었습니다.
  • GitLab 19.3에서 Cargo(Rust) 지원이 도입되었습니다.
  • GitLab 19.3에서 기능 플래그 dependency_management_auto_remediation이
  • GitLab 19.4에서 NuGet(.NET) 지원이 도입되었습니다.
  • GitLab 19.5에서 Pub(Dart와 Flutter) 지원이 도입되었습니다.
  • GitLab 19.4에서 triage_and_remediation_profile이라는 기능 플래그와 함께 분류 및 수정 프로필 지원이 도입되었습니다. 기본적으로 활성화되어 있습니다.
  • GitLab 19.4에서 기능 플래그 enable_dependency_bump_breaking_changes가
  • GitLab 19.6에서 자동 수정 job용 러너 태그가 도입되었습니다.
  • GitLab 19.6에서 Swift Package Manager 지원이 도입되었습니다.
  • GitLab 19.6에서 머지 리퀘스트 제목과 커밋 메시지의 Conventional Commits 형식이
  • GitLab 19.6에서 dependency_management_scheduler_rate_limit이라는

의존성 스캔 자동 수정은 취약한 의존성을 올릴 수 있는 취약하지 않은 버전이 있으면, 해당 버전으로 올리는 머지 리퀘스트를 엽니다. 서비스 계정이 사람의 입력 없이 머지 리퀘스트를 생성하며, 이후 이 머지 리퀘스트는 표준 검토 및 승인 절차를 거칩니다.

베타에서 의존성 스캔 자동 수정은 독립적으로 구성할 수 있는 두 가지 기능을 지원합니다.

  • 의존성 버전 상향: GitLab이 취약한 의존성을 업데이트하는 머지 리퀘스트를 엽니다.
  • 에이전트 방식 브레이킹 체인지 해결: 버전 상향이 브레이킹 체인지 때문에 파이프라인 실패를 일으키면 GitLab Duo가 이를 해결하려고 시도합니다. 자세한 내용은 에이전트 방식 브레이킹 체인지 해결 활성화를 참고합니다.

일반 공급 로드맵은 에픽 19244를 참고합니다.

보안 구성 프로필도 이 플로를 지원합니다. 여러 프로젝트와 그룹에서 플로를 한 번에 켜고 구성하려면 자동화된 분류 및 수정 프로필을 사용합니다.

의존성 스캔 자동 수정 켜기#

사전 요구 사항:

  • 의존성 스캔이 활성화되어 있고 결과를 생성해야 합니다. 스캔이 실행되어야 하고, 결과가 기본 브랜치에 보고되어야 합니다.
  • 프로젝트가 지원되는 패키지 관리자를 사용해야 합니다.
  • 의존성 스캔 자동 수정 프로필이 프로젝트에 연결되어 있어야 합니다. 설명은 의존성 스캔 자동 수정 프로필을 참고합니다.
  • 프로필에 러너 태그를 설정하지 않았다면, 러너가 태그가 없는 job을 수락해야 합니다. GitLab은 자동 수정 job을 직접 생성하며 이 job에 프로젝트의 .gitlab-ci.yml 구성을 사용하지 않으므로 default:tags가 적용되지 않습니다.
  • 러너가 권한 있는(privileged) 모드를 허용해야 합니다. 자동 수정 job은 docker:28-dind 서비스를 사용합니다. 자세한 내용은 Docker를 사용해 Docker 이미지 빌드를 참고합니다.
  • 러너가 registry.gitlab.com에서 자동 수정 오케스트레이터 이미지를, 그리고 docker:28-dind 이미지를 가져올 수 있어야 합니다.

취약점 탐지와 자동 수정을 트리거하려면 파이프라인을 실행합니다. GitLab이 수정 가능한 버전이 있는 취약점을 탐지하면 의존성 스캔 자동 수정이 자동으로 트리거됩니다.

의존성 버전 상향 작동 방식#

이 동작은 의존성 스캔 자동 수정 프로필이 제어합니다. 기본 프로필에서는 다음과 같이 동작합니다.

  • 심각도 임계값: GitLab은 심각도가 high 이상인 취약점을 수정합니다.
  • 쿨다운 기간: GitLab은 최근 7일 이내에 릴리스된 수정 버전을 제외합니다.
  • 업그레이드 정책: 에이전트 방식 브레이킹 체인지 해결을 활성화하지 않으면 GitLab은 패치와 마이너 버전 상향만 제안합니다.
  • 열린 머지 리퀘스트 한도: 프로젝트당 자동 수정 머지 리퀘스트는 한 번에 최대 30개까지 열 수 있습니다. 기존 머지 리퀘스트가 머지되거나 닫힐 때까지 GitLab은 새 머지 리퀘스트를 생성하지 않습니다.

각 파이프라인이 끝나면 GitLab은 이 값을 기준으로 의존성 스캔 결과를 확인합니다. 대상이 되는 각 취약점에 대해 다음을 수행합니다.

  1. GitLab이 브레이킹 체인지가 없는 가장 가까운 업그레이드 경로를 결정합니다.
  2. 서비스 계정이 관련 매니페스트 파일을 업데이트하는 머지 리퀘스트를 엽니다.
  3. GitLab은 리뷰어를 지정하지 않습니다. 업데이트된 파일의 Code Owners가 리뷰어로 요청되도록 하려면 자동 리뷰어 지정을 켭니다.
  4. 머지 리퀘스트는 프로젝트의 표준 승인 워크플로를 거칩니다.

베타 기간에는 GitLab이 가장 심각도가 높은 결과부터 시작해 한 번에 취약점 세 개를 처리합니다.

Feature flag

스케줄러 속도 제한의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 기록을 참고합니다.

스케줄러 속도 제한을 활성화하면 GitLab은 프로젝트마다 5분에 최대 한 번만 스케줄러 실행을 시작합니다. 무시된 업데이트로 비워진 슬롯을 채우는 실행에는 별도의 제한이 있으며, 5분에 한 번입니다. 자세한 내용은 구성할 수 없는 속도 제한을 참고합니다.

머지 리퀘스트 제목과 커밋 메시지#

기본적으로 자동 수정 머지 리퀘스트의 제목은 Security: Update rack from 2.0.9 to 2.2.0와 같은 형태입니다. 커밋 제목은 Update rack입니다.

기본 브랜치가 Conventional Commits를 따르면 GitLab은 머지 리퀘스트 제목과 커밋 제목 모두에 이 형식을 사용합니다. 예를 들면 다음과 같습니다.

build(deps): [security] update rack from 2.0.9 to 2.2.0

GitLab은 기본 브랜치에서 가장 최근의 머지 커밋이 아닌 커밋을 최대 20개 샘플링하며, 자동 수정 서비스 계정이 만든 커밋은 건너뜁니다. GitLab은 머지 커밋이 아닌 커밋을 최대 50개까지만 거슬러 올라가 검색합니다. 이 커밋의 30% 이상이 대소문자와 관계없이 다음 유형 중 하나로 시작하면 프로젝트가 Conventional Commits를 사용하는 것으로 간주합니다. build, chore, ci, docs, feat, fix, perf, refactor, style, test. 유형 뒤에는 선택적 스코프와 선택적 ! 브레이킹 체인지 표시가 올 수 있습니다.

그렇지 않으면 GitLab은 기본 형식을 사용합니다. 예를 들어 이모지나 deps: 같은 사용자 지정 접두사를 사용하는 프로젝트에는 기본 형식이 적용됩니다.

Conventional Commits를 사용하는 프로젝트에서는 GitLab이 일치하는 커밋의 스타일을 따라 합니다.

  • 일치하는 커밋이 chore를 사용하고 build는 사용하지 않으면 유형은 chore입니다. 그렇지 않으면 유형은 build입니다.
  • 일치하는 커밋 대부분이 유형을 대문자로 시작하면 Build(deps):처럼 유형을 대문자로 씁니다.
  • 스코프는 항상 deps입니다.
  • (deps): 뒤의 텍스트는 일치하는 커밋 대부분이 제목을 대문자로 시작하면 [Security] Update이고, 그렇지 않으면 [security] update입니다.

Conventional Commits 제목이 72자보다 길면 GitLab은 제목과 커밋 제목에서 이전 버전을 생략해 build(deps): [security] update rack to 2.2.0처럼 만듭니다.

GitLab이 열려 있는 머지 리퀘스트를 업데이트할 때는 기본 브랜치 기록이 바뀌더라도 머지 리퀘스트를 생성할 때 사용한 Conventional Commits 스타일을 유지합니다. 기본 형식을 사용하는 머지 리퀘스트는 이후 기본 브랜치가 해당 규칙을 따르는 경우 GitLab이 다음에 업데이트할 때 Conventional Commits로 전환됩니다.

에이전트 방식 브레이킹 체인지 해결 활성화#

버전 상향이 브레이킹 체인지 때문에 파이프라인 실패를 일으키면, GitLab Duo가 브레이킹 체인지를 자동으로 해결하려고 시도할 수 있습니다. 이 기능은 의존성 버전 상향 기능과 별개이며 자체 토글이 있습니다.

사전 요구 사항:

  • 프로젝트에서 GitLab Duo를 사용할 수 있어야 합니다.

에이전트 방식 브레이킹 체인지 해결을 활성화하려면 프로젝트 API를 사용해 프로젝트의 duo_dependency_bump_breaking_changes_enabled를 true로 설정합니다.

스케줄러 동시성 구성#

관리자는 Sidekiq 전체에서 동시에 실행되는 자동 수정 스케줄러 job의 수를 제한할 수 있습니다. security_update_scheduler_max_concurrency 애플리케이션 설정으로 상한을 설정합니다. 기본값은 30이며, 값의 상한은 200입니다. 스케줄링을 일시 중지하려면 값을 0으로 설정합니다.

자동 수정 job용 러너 태그 설정#

러너 플릿에서 태그를 사용한다면 자동 수정 job에 태그를 지정해, 일치하는 태그가 있는 러너만 해당 job을 가져가도록 할 수 있습니다. 기본적으로 job에는 태그가 없습니다. GitLab 권장 프로필은 편집할 수 없으므로 직접 프로필을 만들어야 합니다.

사전 요구 사항:

  • 그룹에 대한 Security Manager, Maintainer 또는 Owner 권한.

러너 태그를 설정하려면 다음을 수행합니다.

  1. securityScanProfileCreate 뮤테이션으로 의존성 스캔 자동 수정 프로필을 생성하고 runnerTags를 설정합니다.

    mutation {
      securityScanProfileCreate(input: {
        namespaceId: "gid://gitlab/Group/123",
        scanType: DEPENDENCY_SCANNING_POST_PROCESSING,
        name: "Auto-remediation on tagged runners",
        description: "Runs auto-remediation jobs on runners tagged docker and linux",
        triggers: [
          {
            triggerType: SBOM_INGESTED,
            configuration: {
              dependencyScanningPostProcessing: {
                autoRemediation: {
                  runnerTags: ["docker", "linux"]
                }
              }
            }
          }
        ]
      }) {
        scanProfile {
          id
          name
        }
        errors
      }
    }
    

    지정하지 않은 설정은 기본값을 유지합니다.

  2. 프로필을 프로젝트 또는 그룹에 연결합니다. 설명은 GraphQL API로 프로필 적용을 참고합니다.

나중에 태그를 변경하려면 securityScanProfileUpdate 뮤테이션으로 프로필을 업데이트합니다. 업데이트는 프로필의 트리거와 해당 설정을 대체하므로, runnerTags뿐 아니라 유지하려는 모든 트리거와 설정을 포함해야 합니다.

runnerTags 설정에는 다음 제한이 있습니다.

  • 태그는 최대 20개입니다.
  • 각 태그의 길이는 1~255자입니다.
  • 태그는 중복될 수 없습니다.
  • 태그에는 쉼표, 따옴표(" 또는 '), $를 사용할 수 없습니다.
  • 태그는 공백으로 시작하거나 끝날 수 없습니다.

자동화된 분류 및 수정 프로필은 같은 필드를 triageAndRemediation.sbomIngested.autoRemediation.runnerTags에서 받습니다.

지원되는 패키지 관리자#

의존성 스캔 자동 수정은 다음 패키지 관리자를 지원합니다.

언어 패키지 관리자 파일
Ruby Bundler Gemfile, Gemfile.lock
Java Maven pom.xml
Java Gradle build.gradle, build.gradle.kts
Python pip, pipenv, poetry, setuptools, uv requirements.txt, Pipfile, pyproject.toml, setup.py, uv.lock
JavaScript / TypeScript npm, yarn, pnpm, bun package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock
Go Go modules go.mod, go.sum
Rust Cargo Cargo.toml, Cargo.lock
.NET NuGet *.csproj, packages.lock.json
Dart and Flutter Pub pubspec.yaml, pubspec.lock
Swift Swift Package Manager Package.swift, Package.resolved

추가 에코시스템 지원은 에픽 19244에서 제안되었습니다.

.NET에서는 의존성 스캔이 커밋된 packages.lock.json에서만 NuGet 의존성을 탐지합니다. 이 파일이 없는 프로젝트는 NuGet 결과가 생성되지 않으므로 자동 수정이 처리할 대상이 없습니다. 잠금 파일을 생성하려면 프로젝트 파일에 RestorePackagesWithLockFile을 설정하고 결과를 커밋합니다.

Dart와 Flutter에서는 의존성 스캔이 커밋된 pubspec.lock에서만 Pub 의존성을 탐지합니다. 이 파일이 없는 프로젝트는 Pub 결과가 생성되지 않으므로 자동 수정이 처리할 대상이 없습니다. dart pub get 또는 flutter pub get을 실행해 잠금 파일을 생성하고 결과를 커밋합니다. 또한 순수 Dart 프로젝트라도 업데이터가 의존성을 해결하기 전에 Flutter SDK를 설정하므로, Pub 자동 수정 job은 다른 에코시스템보다 몇 분 더 걸립니다.

Swift에서는 의존성 스캔이 커밋된 Package.resolved에서만 의존성을 탐지합니다. 이 파일이 없는 프로젝트는 Swift 결과가 생성되지 않으므로 자동 수정이 처리할 대상이 없습니다. swift package resolve를 실행해 잠금 파일을 생성하고 결과를 커밋합니다. 브랜치나 커밋에 고정된 의존성은 Package.resolved에 버전이 기록되지 않으므로 자동 수정이 건너뜁니다.

서비스 계정 권한#

프로젝트에서 의존성 스캔 자동 수정이 처음 실행되면 GitLab은 GitLab Dependency Management라는 프로젝트용 서비스 계정을 생성합니다. GitLab은 이후 해당 프로젝트의 모든 자동 수정 머지 리퀘스트에 이 계정을 재사용하므로, 프로젝트마다 계정이 정확히 하나만 있습니다.

GitLab은 서비스 계정을 Guest 멤버로 프로젝트에 추가합니다. 이 멤버십은 계정을 프로젝트의 멤버로 만들 뿐 다른 권한은 부여하지 않습니다. 대신 전용 내부 역할이 계정에 다음 권한을 부여합니다.

  • 리포지터리 클론.
  • 브랜치 푸시.
  • 머지 리퀘스트 생성 및 업데이트.
  • 파이프라인 생성.

계정이 할 수 있는 일의 범위는 Guest 멤버십이 아니라 이 내부 역할이 정합니다. 더 넓은 권한은 계정에 부여하지 않습니다. 이 설계는 기능을 켠 모든 프로젝트에서 자동화된 계정에 Developer 권한을 주는 대신, 이러한 권한을 직접적이고 좁게 부여하기 때문입니다. 이 설계의 전체 근거는 ADR 003: Single service account model을 참고합니다.

내부 역할은 프로젝트가 머지 리퀘스트에 설정한 가시성을 재정의하지 않습니다. 프로젝트가 머지 리퀘스트를 프로젝트 멤버로 제한하면 Reporter 권한 이상의 사용자만 머지 리퀘스트를 생성할 수 있습니다. 이 경우 자동 수정은 해당 프로젝트에 머지 리퀘스트를 생성하지 않습니다. 해결 방법은 자동 수정이 머지 리퀘스트를 생성하지 않음을 참고합니다.

자동 수정 머지 리퀘스트의 파이프라인은 이 서비스 계정으로 실행됩니다. job에 해당 역할이 부여하는 권한을 넘어서는 권한이 필요하면, 같은 파이프라인을 Developer 권한이 있는 사용자가 실행할 때는 성공하더라도 job이 실패합니다. 예를 들면 다음과 같습니다.

  • 프로젝트 컨테이너 레지스트리에 컨테이너 이미지를 푸시하려면 Developer 권한이 필요합니다. 프로젝트 컨테이너 레지스트리에서 기존 이미지를 가져오는 것은 서비스 계정의 권한으로 가능합니다.
  • 프로젝트 패키지 레지스트리를 읽으려면 Reporter 권한이 필요합니다.

Auto DevOps 빌드 job은 이미지를 푸시하므로 Auto DevOps를 사용하는 프로젝트는 컨테이너 레지스트리 사례에 해당합니다.

이러한 job이 실행되도록 하려면 Maintainer 권한 이상의 사용자가 서비스 계정에 프로젝트의 Developer 권한을 부여할 수 있습니다. 설명은 자동 수정 파이프라인 job이 권한 오류로 실패함을 참고합니다.

알려진 문제#

베타 단계에서는 다음과 같은 제한이 있습니다.

  • 쿨다운 기간: 나중에 문제가 있거나 악성으로 밝혀질 수 있는 버전으로 수정하는 위험을 줄이기 위해, GitLab은 최근 7일 이내에 릴리스된 수정 버전을 제안하지 않습니다.
  • 버전 상향 범위: 패치와 마이너 버전 상향만 제안합니다. 브레이킹 체인지가 생길 가능성이 더 큰 메이저 버전 업그레이드는 에이전트 방식 브레이킹 체인지 해결을 활성화하지 않으면 시도하지 않습니다.
  • 파이프라인 실행당 취약점 하나: 파이프라인을 실행할 때마다 수정 버전이 있는 취약점 하나만 대상으로 합니다. 여러 수정을 머지 리퀘스트 하나로 묶는 기능은 에픽 19244에서 제안되었습니다.
  • 수정 버전 없음: 취약점에 브레이킹 체인지가 없는 수정 버전이 없으면 해당 결과에 대해서는 머지 리퀘스트를 생성하지 않습니다.
  • 머지 리퀘스트 생성은 파이프라인 성공 여부에 따라 달라집니다. GitLab은 자동 수정 파이프라인을 해당 브랜치에서 실행하기 전에 dependency-management/<dependency>-<major-version>.x 브랜치를 생성하고, 파이프라인이 성공한 후에야 머지 리퀘스트를 생성합니다. 머지 리퀘스트가 없고 매니페스트 파일을 변경하는 커밋도 없는 dependency-management/ 브랜치는 파이프라인이 성공하지 못했다는 뜻입니다. 해당 브랜치의 파이프라인 상태를 확인합니다.

문제 해결#

자동 수정 파이프라인 job이 권한 오류로 실패함#

자동 수정 머지 리퀘스트의 파이프라인 job은 GitLab Dependency Management 서비스 계정으로 실행됩니다. 이 계정은 함께 가진 Guest 권한이 아니라 내부 역할에서 권한을 얻습니다. 이 내부 역할은 프로젝트 파이프라인에 필요할 수 있는 모든 권한을 포함하지 않습니다. 자세한 내용은 서비스 계정 권한을 참고합니다. 해당 역할이 부여하는 권한을 넘어서는 권한이 필요한 job은, 같은 job을 Developer 권한이 있는 사용자가 실행할 때는 성공하더라도 실패합니다. 오류는 job마다 다릅니다. 예를 들어 프로젝트 컨테이너 레지스트리에 이미지를 푸시하는 job은 거부 응답을 받고, 프로젝트 패키지 레지스트리를 읽는 job은 403 오류를 받습니다.

이 문제를 우회하려면 Maintainer 권한 이상의 사용자가 서비스 계정에 프로젝트의 Developer 권한을 부여할 수 있습니다.

  1. 왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
  2. Manage > Members를 선택합니다.
  3. GitLab Dependency Management 멤버를 찾습니다.
  4. 해당 멤버의 권한을 Developer로 변경합니다.

이 작업은 서비스 계정에 프로젝트의 Developer 권한 전체를 부여합니다. 파이프라인에 필요한 경우에만 변경합니다. 이 변경은 해당 프로젝트에만 적용됩니다. 변경 사항은 유지되므로 이후 프로젝트의 자동 수정 머지 리퀘스트에서는 파이프라인이 정상적으로 작동합니다. 실패한 파이프라인을 다시 실행해 변경 사항을 반영합니다.

자동 수정이 머지 리퀘스트를 생성하지 않음#

의존성 스캔은 기본 브랜치에서 실행되지만, GitLab Dependency Management 서비스 계정이 프로젝트에서 머지 리퀘스트를 생성할 수 없으면 자동 수정은 머지 리퀘스트를 생성하지 않습니다. 해당 프로젝트에서는 다음과 같이 동작합니다.

  • GitLab이 dependency-management/ 브랜치를 생성하거나 업데이트하지 않습니다.
  • 열려 있는 자동 수정 머지 리퀘스트가 더 이상 갱신되지 않습니다.
  • 취약점 보고서에서 수정을 시작하면 보고서에 Service account cannot create merge requests in this project 오류가 표시됩니다.

같은 오류에도 원인이 여러 가지입니다. GitLab Self-Managed에서는 관리자가 application_json.log의 DependencyManagement: service account cannot create merge requests 항목에 있는 denial_reason 필드에서 원인을 찾을 수 있습니다.

원인 denial_reason 해결 방법
머지 리퀘스트가 로 설정되어 있습니다. merge_requests_private 서비스 계정에 Reporter 권한을 부여합니다.
프로젝트에서 머지 리퀘스트가 꺼져 있습니다. merge_requests_disabled 프로젝트에서 머지 리퀘스트를 켭니다.
프로젝트에서 리포지터리가 꺼져 있습니다. repository_disabled 프로젝트에서 리포지터리를 켭니다.
프로젝트가 보관되었거나 서비스 계정이 프로젝트에서 제거되었습니다. access_denied 프로젝트 보관을 해제하거나 서비스 계정을 멤버로 다시 추가합니다.
네임스페이스가 읽기 전용입니다. access_denied 네임스페이스의 읽기 전용 상태를 해제합니다.

서비스 계정은 프로젝트의 Guest 멤버입니다. 머지 리퀘스트가 로 설정되어 있으면 Reporter 권한 이상의 사용자만 머지 리퀘스트를 생성할 수 있습니다. 계정의 내부 역할은 이 요구 사항을 재정의하지 않습니다. 자세한 내용은 서비스 계정 권한을 참고합니다.

서비스 계정에 Reporter 권한을 부여하려면 Maintainer 권한 이상의 사용자가 다음을 수행할 수 있습니다.

  1. 상단 바에서 를 선택하고 프로젝트를 찾습니다.
  2. > 를 선택합니다.
  3. GitLab Dependency Management 멤버를 찾습니다.
  4. 해당 멤버의 권한을 Reporter로 변경합니다.

또는 머지 리퀘스트의 가시성을 로 설정합니다. 공개 프로젝트에서는 이 설정으로 프로젝트 멤버가 아닌 사용자도 머지 리퀘스트를 생성할 수 있습니다.

이러한 변경 사항은 다음에 기본 브랜치에서 의존성 스캔이 실행될 때 자동 수정에 반영됩니다.