종속성 스캐닝 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 이상: DS_ENFORCE_NEW_ANALYZER: 'true'를 사용하는 SBOM 기반 종속성 스캐닝을 사용할 때 기존의 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 파이프라인 비활성화를 참조하세요.