의존성 스캐닝 SBOM 분석기를 사용할 때 다음과 같은 문제가 발생할 수 있습니다.

사용자 지정 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: "Dependency scanning running" 컴플라이언스 제어는 SBOM 기반 의존성 스캐닝과 올바르게 동작합니다.
• GitLab Self-Managed 18.4 이상: SBOM 기반 의존성 스캐닝(DS_ENFORCE_NEW_ANALYZER: 'true')을 사용하면 기존 gl-dependency-scanning-report.json 아티팩트가 생성되지 않기 때문에 "Dependency scanning running" 컴플라이언스 제어가 실패할 수 있습니다.

Self-Managed 인스턴스의 해결 방법: "Dependency scanning running" 제어가 필요한 컴플라이언스 프레임워크 검사를 통과해야 한다면, SBOM 보고서와 의존성 스캐닝 보고서를 모두 생성하는 v2 템플릿(Jobs/Dependency-Scanning.v2.gitlab-ci.yml)을 사용할 수 있습니다.

컴플라이언스 제어에 대한 자세한 내용은 GitLab 컴플라이언스 제어를 참고합니다.

해결 job이 실패해도 의존성 스캐닝은 계속 실행됨#

해결 job은 자동으로 실행되므로 allow_failure: true로 설정됩니다. 해결 job이 실패해도 dependency-scanning job은 계속 실행됩니다. 리포지터리에 잠금 파일이 커밋되어 있는지에 따라, 스캔은 커밋된 파일을 사용하거나, 활성화된 경우 매니페스트 폴백으로 대체됩니다.

사용 사례가 지원되는지 확인하려면 알려진 제한 사항을 확인합니다.

해결 실패를 조사하려면 실패한 해결 job의 CI/CD job 로그를 확인합니다. 로그에는 DS 분석기 서비스 컨테이너 실행 출력과 빌드 도구 명령 출력이 포함됩니다. 서비스 로그가 보이지 않으면 CI_DEBUG_SERVICES를 "true"로 설정하여 서비스 컨테이너 로그를 캡처할 수 있습니다.

필요하다면 의존성 해결을 비활성화하고 수동으로 생성한 잠금 파일을 대신 사용할 수 있습니다.

의존성 스캐닝 job은 성공했지만 보고서가 생성되지 않음#

의존성 스캐닝 job이 성공적으로 완료되었는데도 SBOM 또는 의존성 스캐닝 보고서 아티팩트가 생성되지 않았다면, 프로젝트에 지원되는 파일이 없을 가능성이 높습니다.

CI/CD job 로그에서 다음과 유사한 경고 메시지를 확인합니다:

No compatible file found in <directory>.

이 문제를 해결하려면 지원되는 잠금 파일 또는 의존성 그래프 내보내기를 프로젝트에 추가합니다. 자세한 지침은 잠금 파일 또는 의존성 그래프 내보내기 수동 생성을 참고합니다.

DS_SKIP_IF_NO_SUPPORTED_FILES가 설정된 경우 의존성 스캐닝 job이 실행되지 않음#

DS_SKIP_IF_NO_SUPPORTED_FILES가 "true"로 설정되어 있고 dependency-scanning job이 파이프라인에 나타나지 않는다면, 프로젝트에서 지원되는 파일이 탐지되지 않은 것입니다.

의존성 해결 job을 트리거하는 일부 파일은 지원되지 않기 때문에 의존성 스캐닝 job을 트리거하지 않을 수 있습니다. 예를 들어 settings.gradle, setup.cfg, pyproject.toml, requirements.in은 직접 지원되지 않습니다.

이 문제를 해결하려면 다음 중 하나를 수행합니다:

• DS_SKIP_IF_NO_SUPPORTED_FILES를 "false"로 설정하거나 설정하지 않은 상태로 두어 의존성 스캐닝 job이 무조건 실행되도록 합니다.
• 지원되는 파일을 리포지터리에 커밋합니다. 예를 들어 생성된 잠금 파일이나 의존성 그래프 내보내기가 해당합니다.

오류: 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"

머지 리퀘스트 파이프라인에서 의존성 스캐닝만 실행되고 다른 job은 건너뛴 것으로 표시됨#

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

파이프라인 실행 정책으로 템플릿이 주입되는 경우에는, 프로젝트나 그룹 변수가 AST_ENABLE_MR_PIPELINES: "false"를 설정해도 이 문제가 발생합니다. 파이프라인 실행 정책은 기본적으로 격리되어 실행되므로 정책 job이 그 값을 전달받지 못합니다. 설정되지 않은 변수는 "true"가 기본값이므로, 프로젝트나 그룹 설정과 관계없이 job이 머지 리퀘스트 파이프라인에서 실행됩니다.

해결 방법은 정책 CI/CD 구성에 AST_ENABLE_MR_PIPELINES: "false"를 직접 설정하는 것입니다. 프로젝트나 그룹 값을 대신 사용하는 방법을 포함한 자세한 내용은 CI/CD 변수를 참고합니다.