의존성 스캔 작업 시 다음과 같은 문제가 발생할 수 있습니다.

디버그 수준 로깅#

디버그 수준 로깅은 트러블슈팅 시 도움이 될 수 있습니다. 자세한 내용은 디버그 수준 로깅을 참조하세요.

로컬 환경에서 분석기 실행#

파이프라인을 실행하지 않고 문제를 디버그하거나 동작을 확인하기 위해 의존성 스캔 분석기를 로컬에서 실행할 수 있습니다.

예를 들어 Python 분석기를 실행하려면:

cd project-git-repository

docker run \
   --interactive --tty --rm \
   --volume "$PWD":/tmp/app \
   --env CI_PROJECT_DIR=/tmp/app \
   --env SECURE_LOG_LEVEL=debug \
   -w /tmp/app \
   registry.gitlab.com/security-products/gemnasium-python:5 /analyzer run

이 명령은 디버그 수준 로깅으로 분석기를 실행하고 분석할 로컬 저장소를 마운트합니다. registry.gitlab.com/security-products/gemnasium-python:5를 프로젝트의 언어 및 의존성 관리자에 적합한 스캐너 image:tag 조합으로 교체할 수 있습니다.

특정 언어 또는 패키지 관리자 지원 부재 우회#

지원되는 언어에 언급된 바와 같이 일부 의존성 정의 파일은 아직 지원되지 않습니다. 그러나 언어, 패키지 관리자 또는 서드파티 도구가 정의 파일을 지원되는 형식으로 변환할 수 있는 경우 의존성 스캔을 수행할 수 있습니다.

일반적인 접근 방식은 다음과 같습니다:

1. .gitlab-ci.yml 파일에 전용 변환기 작업을 정의합니다. 변환을 용이하게 하기 위해 적합한 Docker 이미지, 스크립트 또는 둘 다를 사용합니다.
2. 해당 작업이 변환된 지원 파일을 아티팩트로 업로드하도록 합니다.
3. 변환된 정의 파일을 사용하기 위해 dependency_scanning 작업에 dependencies: [<your-converter-job>]를 추가합니다.

예를 들어 pyproject.toml 파일만 있는 Poetry 프로젝트는 다음과 같이 poetry.lock 파일을 생성할 수 있습니다.

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

stages:
  - test

gemnasium-python-dependency_scanning:
  # Work around https://gitlab.com/gitlab-org/gitlab/-/issues/32774
  before_script:
    - pip install "poetry>=1,<2"  # Or via another method: https://python-poetry.org/docs/#installation
    - poetry update --lock # Generates the lock file to be analyzed.

의존성 스캔 작업이 예기치 않게 실행됨#

의존성 스캔 CI 템플릿은 rules:exists 구문을 사용합니다. 이 지시문은 10,000번의 검사로 제한되며 이 숫자에 도달하면 항상 true를 반환합니다. 이로 인해 저장소의 파일 수에 따라 스캐너가 프로젝트를 지원하지 않더라도 의존성 스캔 작업이 트리거될 수 있습니다. 이 제한에 대한 자세한 내용은 rules:exists 문서를 참조하세요.

오류: dependency_scanning is used for configuration only, and its script should not be executed#

자세한 내용은 애플리케이션 보안 테스트 트러블슈팅을 참조하세요.

Java 기반 프로젝트에 여러 인증서 가져오기#

gemnasium-maven 분석기는 keytool을 사용하여 ADDITIONAL_CA_CERT_BUNDLE 변수의 내용을 읽어 단일 인증서 또는 인증서 체인을 가져옵니다. 관련 없는 여러 인증서는 무시되고 keytool에 의해 첫 번째 인증서만 가져옵니다.

분석기에 관련 없는 여러 인증서를 추가하려면 gemnasium-maven-dependency_scanning 작업 정의에서 다음과 같은 before_script를 선언할 수 있습니다:

gemnasium-maven-dependency_scanning:
  before_script:
    - . $HOME/.bashrc # make the java tools available to the script
    - OIFS="$IFS"; IFS=""; echo $ADDITIONAL_CA_CERT_BUNDLE > multi.pem; IFS="$OIFS" # write ADDITIONAL_CA_CERT_BUNDLE variable to a PEM file
    - csplit -z --digits=2 --prefix=cert multi.pem "/-----END CERTIFICATE-----/+1" "{*}" # split the file into individual certificates
    - for i in `ls cert*`; do keytool -v -importcert -alias "custom-cert-$i" -file $i -trustcacerts -noprompt -storepass changeit -keystore /opt/asdf/installs/java/adoptopenjdk-11.0.7+10.1/lib/security/cacerts 1>/dev/null 2>&1 || true; done # import each certificate using keytool (note the keystore location is related to the Java version being used and should be changed accordingly for other versions)
    - unset ADDITIONAL_CA_CERT_BUNDLE # unset the variable so that the analyzer doesn't duplicate the import

의존성 스캔 작업이 strconv.ParseUint: parsing "0.0": invalid syntax 메시지와 함께 실패#

Docker-in-Docker는 지원되지 않으며 이를 호출하려는 시도가 이 오류의 원인일 가능성이 높습니다.

이 오류를 수정하려면 의존성 스캔에 대해 Docker-in-Docker를 비활성화하세요. CI/CD 파이프라인에서 실행되는 각 분석기에 대해 개별 <analyzer-name>-dependency_scanning 작업이 생성됩니다.

include:
  - template: Dependency-Scanning.gitlab-ci.yml

variables:
  DS_DISABLE_DIND: "true"

<file> does not exist in <commit SHA> 메시지#

파일의 의존성 Location이 표시될 때 링크의 경로는 특정 Git SHA로 이동합니다.

그러나 의존성 스캔 도구가 검토한 락파일이 캐시된 경우 해당 링크를 선택하면 저장소 루트로 리디렉션되고 메시지가 표시됩니다: <file> does not exist in <commit SHA>.

락파일은 빌드 단계에서 캐시되어 스캔이 발생하기 전에 의존성 스캔 작업으로 전달됩니다. 캐시가 분석기 실행 전에 다운로드되기 때문에 CI_BUILDS_DIR 디렉토리에 락파일이 존재하면 의존성 스캔 작업이 트리거됩니다.

이 경고를 방지하려면 락파일을 커밋해야 합니다.

DS_MAJOR_VERSION 또는 DS_ANALYZER_IMAGE를 설정한 후 더 이상 최신 Docker 이미지를 가져오지 않음#

특정 이유로 DS_MAJOR_VERSION 또는 DS_ANALYZER_IMAGE를 수동으로 설정했고 이제 분석기의 최신 패치 버전을 다시 가져오도록 구성을 업데이트해야 하는 경우 .gitlab-ci.yml 파일을 편집하고 다음 중 하나를 수행하세요:

• DS_MAJOR_VERSION을 의존성 스캔 템플릿에서 참조된 버전과 일치하도록 설정합니다.

• DS_ANALYZER_IMAGE 변수를 직접 하드코딩한 경우 의존성 스캔 템플릿의 최신 줄과 일치하도록 변경합니다. 줄 번호는 어떤 스캔 작업을 편집했는지에 따라 다릅니다.

  예를 들어 gemnasium-maven-dependency_scanning 작업은 DS_ANALYZER_IMAGE가 "$SECURE_ANALYZERS_PREFIX/gemnasium-maven:$DS_MAJOR_VERSION"으로 설정되어 있기 때문에 최신 gemnasium-maven Docker 이미지를 가져옵니다.

setuptools 프로젝트의 의존성 스캔이 use_2to3 is invalid 오류와 함께 실패#

2to3에 대한 지원이 setuptools 버전 v58.0.0에서 제거 되었습니다. 의존성 스캔(python 3.9 실행)은 2to3를 지원하지 않는 setuptools 버전 58.1.0+를 사용합니다. 따라서 lib2to3에 의존하는 setuptools 의존성은 다음 메시지와 함께 실패합니다:

error in <dependency name> setup command: use_2to3 is invalid

이 오류를 해결하려면 분석기의 setuptools 버전을 다운그레이드하세요(예: v57.5.0):

gemnasium-python-dependency_scanning:
  before_script:
    - pip install setuptools==57.5.0

psycopg2를 사용하는 프로젝트의 의존성 스캔이 pg_config executable not found 오류와 함께 실패#

psycopg2에 의존하는 Python 프로젝트를 스캔하면 다음 메시지와 함께 실패할 수 있습니다:

Error: pg_config executable not found.

psycopg2는 gemnasium-python Docker 이미지에 설치되지 않은 libpq-dev Debian 패키지에 의존합니다. 이 오류를 해결하려면 before_script에서 libpq-dev 패키지를 설치하세요:

gemnasium-python-dependency_scanning:
  before_script:
    - apt-get update && apt-get install -y libpq-dev

CI_JOB_TOKEN과 함께 poetry config http-basic을 사용할 때 NoSuchOptionException#

자동 생성된 CI_JOB_TOKEN이 하이픈(-)으로 시작하는 경우 이 오류가 발생할 수 있습니다. 이 오류를 방지하려면 Poetry의 구성 조언을 따르세요.

오류: 프로젝트에 미해결 의존성이 있음#

다음 오류 메시지는 build.gradle 또는 build.gradle.kts 파일로 인한 Gradle 의존성 해결 문제를 나타냅니다:

• Project has <number> unresolved dependencies (GitLab 16.7 ~ 16.9)
• project has unresolved dependencies: ["dependency_name:version"] (GitLab 17.0 이상)

GitLab 16.7 ~ 16.9에서는 미해결 의존성을 만나면 gemnasium-maven이 처리를 계속할 수 없습니다.

GitLab 17.0 이상에서 gemnasium-maven은 미해결 의존성 처리 방법을 제어하는 데 사용할 수 있는 DS_GRADLE_RESOLUTION_POLICY 환경변수를 지원합니다. 기본적으로 미해결 의존성이 발생하면 스캔이 실패합니다. 그러나 환경변수 DS_GRADLE_RESOLUTION_POLICY를 "none"으로 설정하면 스캔이 계속 실행되고 부분적인 결과를 생성할 수 있습니다.

build.gradle 파일 수정 방법에 대한 지침은 Gradle 의존성 해결 문서를 참조하세요. 자세한 내용은 이슈 482650을 참조하세요.

또한 Kotlin 2.0.0에서 의존성 해결에 영향을 미치는 알려진 문제가 있으며, Kotlin 2.0.20에서 수정될 예정입니다. 자세한 내용은 이 이슈를 참조하세요.

Go 프로젝트 스캔 시 빌드 제약 조건 설정#

의존성 스캔은 linux/amd64 컨테이너에서 실행됩니다. 결과적으로 Go 프로젝트에 대해 생성된 빌드 목록에는 이 환경과 호환되는 의존성이 포함됩니다. 배포 환경이 linux/amd64가 아닌 경우 최종 의존성 목록에 추가 호환되지 않는 모듈이 포함될 수 있습니다. 의존성 목록에는 배포 환경에서만 호환되는 모듈이 누락될 수도 있습니다. 이 문제를 방지하려면 .gitlab-ci.yml 파일의 GOOS 및 GOARCH 환경변수를 설정하여 배포 환경의 운영 체제와 아키텍처를 대상으로 하도록 빌드 프로세스를 구성할 수 있습니다.

예를 들어:

variables:
  GOOS: "darwin"
  GOARCH: "arm64"

GOFLAGS 변수를 사용하여 빌드 태그 제약 조건을 지정할 수도 있습니다:

variables:
  GOFLAGS: "-tags=test_feature"

Go 프로젝트의 의존성 스캔에서 거짓 양성 반환#

go.sum 파일은 프로젝트의 빌드 목록을 생성하는 동안 고려된 모든 모듈의 항목을 포함합니다. go.sum 파일에 여러 버전의 모듈이 포함되어 있지만 go build에서 사용하는 MVS 알고리즘은 하나만 선택합니다. 결과적으로 의존성 스캔이 go.sum을 사용할 때 거짓 양성을 보고할 수 있습니다.

거짓 양성을 방지하기 위해 Gemnasium은 Go 프로젝트의 빌드 목록을 생성할 수 없는 경우에만 go.sum을 사용합니다. go.sum이 선택되면 경고가 발생합니다:

[WARN] [Gemnasium] [2022-09-14T20:59:38Z] ▶ Selecting "go.sum" parser for "/test-projects/gitlab-shell/go.sum". False positives may occur. See https://gitlab.com/gitlab-org/gitlab/-/issues/321081.

ssh를 사용하려 할 때 Host key verification failed#

모든 gemnasium 이미지에 openssh-client를 설치한 후 ssh를 사용하면 Host key verification failed 메시지가 발생할 수 있습니다. 이는 이미지를 빌드할 때 $HOME이 /tmp로 설정되어 설정 중에 사용자 디렉토리를 나타내기 위해 ~를 사용하는 경우 발생할 수 있습니다. 이 문제는 gemnasium-python 이미지를 사용할 때 SSH를 통한 프로젝트 클론 실패에서 설명됩니다. openssh-client는 /root/.ssh/known_hosts를 찾을 것으로 예상하지만 이 경로가 존재하지 않으며 대신 /tmp/.ssh/known_hosts가 존재합니다.

이 문제는 openssh-client가 미리 설치된 gemnasium-python에서는 해결되었지만 다른 이미지에서 처음부터 openssh-client를 설치할 때 문제가 발생할 수 있습니다. 이를 해결하려면 다음 중 하나를 수행하세요:

1. 키와 호스트를 설정할 때 절대 경로(~/.ssh/known_hosts 대신 /root/.ssh/known_hosts)를 사용합니다.
2. 관련 known_hosts 파일을 지정하는 UserKnownHostsFile을 ssh 구성에 추가합니다. 예: echo 'UserKnownHostsFile /tmp/.ssh/known_hosts' >> /etc/ssh/ssh_config.

ERROR: THESE PACKAGES DO NOT MATCH THE HASHES FROM THE REQUIREMENTS FILE#

이 오류는 requirements.txt 파일의 패키지 해시가 다운로드된 패키지의 해시와 일치하지 않을 때 발생합니다. 보안 조치로 pip는 패키지가 변조되었다고 가정하고 설치를 거부합니다. 이를 해결하려면 요구사항 파일에 포함된 해시가 올바른지 확인하세요. pip-compile로 생성된 요구사항 파일의 경우 pip-compile --generate-hashes를 실행하여 해시가 최신인지 확인하세요. pipenv로 생성된 Pipfile.lock을 사용하는 경우 pipenv verify를 실행하여 락파일에 최신 패키지 해시가 포함되어 있는지 확인하세요.

ERROR: In --require-hashes mode, all requirements must have their versions pinned with ==#

이 오류는 요구사항 파일이 GitLab Runner에서 사용하는 것과 다른 플랫폼에서 생성된 경우 발생합니다. 다른 플랫폼을 대상으로 하는 지원은 이슈 416376에서 추적됩니다.

Python에 대한 의존성 스캔에서 편집 가능한 플래그로 인해 중단#

Python의 의존성 스캔을 실행할 때 현재 디렉토리를 대상으로 하는 -e/--editable 플래그를 requirements.txt 파일에 사용하는 경우 Gemnasium Python 의존성 스캐너가 pip3 download를 실행할 때 중단되는 문제가 발생할 수 있습니다. 이 명령은 대상 프로젝트를 빌드하는 데 필요합니다.

이 문제를 해결하려면 Python의 의존성 스캔을 실행할 때 -e/--editable 플래그를 사용하지 마세요.

SBT의 메모리 부족 오류 처리#

Scala 프로젝트의 의존성 스캔을 사용할 때 SBT에서 메모리 부족 오류가 발생하면 SBT_CLI_OPTS 환경변수를 설정하여 해결할 수 있습니다. 구성 예시:

variables:
  SBT_CLI_OPTS: "-J-Xmx8192m -J-Xms4192m -J-Xss2M"

Kubernetes 실행기를 사용하는 경우 기본 Kubernetes 리소스 설정을 재정의해야 할 수 있습니다. 메모리 문제를 방지하기 위해 컨테이너 리소스를 조정하는 방법에 대한 자세한 내용은 Kubernetes 실행기 문서를 참조하세요.

NPM 프로젝트에서 package-lock.json 파일 없음#

기본적으로 의존성 스캔 작업은 저장소에 package-lock.json 파일이 있을 때만 실행됩니다. 그러나 일부 NPM 프로젝트는 Git 저장소에 저장하는 대신 빌드 프로세스 중에 package-lock.json 파일을 생성합니다.

이러한 프로젝트의 의존성을 스캔하려면:

1. 빌드 작업에서 package-lock.json 파일을 생성합니다.
2. 생성된 파일을 아티팩트로 저장합니다.
3. 아티팩트를 사용하고 규칙을 조정하도록 의존성 스캔 작업을 수정합니다.

예를 들어 구성은 다음과 같을 수 있습니다:

include:
  - template: Dependency-Scanning.gitlab-ci.yml

build:
  script:
    - npm i
  artifacts:
    paths:
      - package-lock.json  # Store the generated package-lock.json as an artifact

gemnasium-dependency_scanning:
  needs: ["build"]
  rules:
    - if: "$DEPENDENCY_SCANNING_DISABLED == 'true' || $DEPENDENCY_SCANNING_DISABLED == '1'"
      when: never
    - if: "$DS_EXCLUDED_ANALYZERS =~ /gemnasium([^-]|$)/"
      when: never
    - if: $CI_COMMIT_BRANCH && $GITLAB_FEATURES =~ /\bdependency_scanning\b/ && $CI_GITLAB_FIPS_MODE == "true"
      variables:
        DS_IMAGE_SUFFIX: "-fips"
        DS_REMEDIATE: 'false'
    - if: "$CI_COMMIT_BRANCH && $GITLAB_FEATURES =~ /\\bdependency_scanning\\b/"

파이프라인에 의존성 스캔 작업이 추가되지 않음#

의존성 스캔 작업은 규칙을 사용하여 락파일이나 빌드 도구 관련 파일이 있는지 확인합니다. 이러한 파일이 감지되지 않으면 락파일이 파이프라인의 다른 작업에 의해 생성되더라도 작업이 파이프라인에 추가되지 않습니다.

이 상황이 발생하면 저장소에 지원되는 파일이 포함되어 있는지 또는 런타임에 지원 파일이 생성됨을 나타내는 파일이 있는지 확인하세요. 이러한 파일을 저장소에 추가하여 의존성 스캔 작업을 트리거할 수 있는지 고려하세요.

저장소에 이러한 파일이 포함되어 있다고 판단되지만 여전히 작업이 트리거되지 않는 경우 다음 정보를 포함하여 이슈를 열어주세요:

• 사용 중인 언어 및 빌드 도구.
• 제공하는 락파일의 종류와 생성 위치.

의존성 스캔 템플릿에 직접 기여할 수도 있습니다.

의존성 스캔이 gradlew: permission denied와 함께 실패#

gradlew의 permission denied 오류는 일반적으로 gradlew가 실행 비트 없이 저장소에 체크인된 것을 나타냅니다. 작업에서 다음 메시지와 함께 오류가 나타날 수 있습니다:

[FATA] [gemnasium-maven] [2024-11-14T21:55:59Z] [/go/src/app/cmd/gemnasium-maven/main.go:65] ▶ fork/exec /builds/path/to/gradlew: permission denied

로컬에서 chmod +ux gradlew를 실행하고 Git 저장소에 푸시하여 파일을 실행 가능하게 만드세요.

지원되지 않는 Gradle 버전으로 인해 nebula 락 생성 실패#

지원되지 않는 Gradle 버전(9.0 이상)으로 dependency.lock 파일을 생성하려 할 때 다음 오류가 발생합니다:

FAILURE: Build failed with an exception.
* Where:
Initialization script '/builds/gitlab-org/app/app/nebula.gradle' line: 11
* What went wrong:
Failed to notify build listener.
> org/gradle/util/NameMatcher

Gradle 빌드를 Gradle 8.10.2로 다운그레이드해 보세요.

의존성 스캔 스캐너가 더 이상 Gemnasium이 아님#

역사적으로 의존성 스캔에 사용되는 스캐너는 Gemnasium이었으며 취약성 페이지에서 확인할 수 있었습니다.

SBOM을 사용한 의존성 스캔이 도입되면서 Gemnasium 스캐너는 내장된 GitLab SBoM Vulnerability Scanner로 대체됩니다. 이 새로운 스캐너는 더 이상 CI/CD 작업에서 실행되지 않고 GitLab 플랫폼 내에서 실행됩니다. 두 스캐너가 동일한 결과를 제공할 것으로 예상되지만 SBOM 스캔이 기존 의존성 스캔 CI/CD 작업 이후에 발생하기 때문에 기존 취약성은 새로운 GitLab SBoM Vulnerability Scanner로 스캐너 값이 업데이트됩니다.

GitLab SBoM Vulnerability Scanner는 GitLab 내장 의존성 스캔 기능의 유일한 예상 값입니다.

최신 SBOM을 기반으로 프로젝트 의존성 목록이 업데이트되지 않음#

SBOM을 생성하는 파이프라인에서 실패한 작업이 있는 경우 DeleteNotPresentOccurrencesService가 실행되지 않아 의존성 목록이 변경되거나 업데이트되지 않습니다. SBOM을 업로드하는 다른 성공한 작업이 있고 파이프라인이 전반적으로 성공하더라도 이 문제가 발생할 수 있습니다. 이는 관련 보안 스캔 작업이 실패할 때 의존성 목록에서 의존성을 실수로 제거하는 것을 방지하기 위해 설계되었습니다. 프로젝트 의존성 목록이 예상대로 업데이트되지 않는 경우 파이프라인에서 실패했을 수 있는 SBOM 관련 작업을 확인하고 수정하거나 제거하세요.

의존성 스캔이 open /etc/ssl/certs/ca-certificates.crt: permission denied와 함께 실패#

이 오류는 일반적으로 컨테이너를 실행하는 사용자가 root 그룹에 속하지 않음을 나타냅니다. id를 실행하여 사용자가 그룹에 속해 있는지 확인하세요.

$ id
uid=1000(node) gid=0(root) groups=0(root),1000(node)

OpenShift를 실행 중이거나 Kubernetes 실행기를 사용하는 경우 그룹 ID(GID) 0을 사용하여 실행하도록 실행기를 구성해야 합니다.

[[runners]]
[runners.kubernetes]
    [runners.kubernetes.pod_security_context]
    run_as_non_root = true
    run_as_group = 0

오류: node with package name <package_name> does not exist#

이 문제는 패키지 관리자(보통 nuget)가 패키지를 찾을 수 없을 때 발생합니다. 이는 애플리케이션을 빌드하는 데 사용된 이미지가 의존성 스캔을 실행하는 데 사용된 이미지와 다를 때 발생할 수 있습니다.

이 문제를 해결하려면 의존성 스캐너가 애플리케이션을 빌드하는 데 사용하는 것과 동일한 .NET SDK 이미지를 사용하세요. 다음을 실행하여 정확한 이미지를 찾을 수 있습니다:

curl --silent "https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/raw/master/build/gemnasium/alpine/Dockerfile" | grep "vrange-nuget-build" | grep "FROM"

현재 이미지 버전은 위에 링크된 Dockerfile을 확인하세요.