正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

依存関係スキャンのトラブルシューティング

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

依存関係スキャンを使用していると、次の問題が発生することがあります。

デバッグレベルのログを生成する

デバッグレベルでログを生成しておくと、トラブルシューティングに役立ちます。詳細については、デバッグレベルのログを生成するを参照してください。

ローカル環境でアナライザーを実行する

パイプラインを実行せずに問題をデバッグしたり、動作を確認したりするために、ローカルで依存関係スキャンアナライザーを実行できます。

たとえば、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構文を使用します。このディレクティブは10000件のチェックに制限されており、この数に達すると常にtrueを返します。このため、リポジトリ内のファイルの数によっては、スキャナーがプロジェクトをサポートしていなくても、依存関係スキャンジョブがトリガーされる可能性があります。この制限の詳細については、rules:existsドキュメントを参照してください。

エラー: dependency_scanning is used for configuration only, and its script should not be executed

詳細については、アプリケーションセキュリティテストのトラブルシューティングを参照してください。

Javaベースのプロジェクトの複数の証明書をインポートする

gemnasium-mavenアナライザーは、ADDITIONAL_CA_CERT_BUNDLE変数のコンテンツをkeytoolを使用して読み取ります。これにより、単一の証明書または証明書チェーンのいずれかがインポートされます。関連のない複数の証明書は無視され、最初の証明書のみが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を無効にします。個々の<analyzer-name>-dependency_scanningジョブは、CI/CDパイプラインで実行される各アナライザーに対して作成されます。

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-mavenDockerイメージをプルします。

use_2to3 is invalidエラーでsetuptoolsプロジェクトの依存関係スキャンが失敗する

2to3のサポートは、setuptoolsバージョンv58.0.0で削除されました。依存関係スキャン（python 3.9を実行）は、setuptoolsバージョン58.1.0+を使用しますが、これは2to3をサポートしていません。したがって、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

pg_config executable not foundエラーでpsycopg2を使用するプロジェクトの依存関係スキャンが失敗する

psycopg2に依存するPythonプロジェクトをスキャンすると、このメッセージで失敗する可能性があります:

Error: pg_config executable not found.

psycopg2は、libpq-devDebianパッケージに依存しており、これはgemnasium-pythonDockerイメージにインストールされていません。このエラーを回避するには、libpq-devパッケージをbefore_scriptにインストールします:

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

NoSuchOptionException（poetry config http-basicとCI_JOB_TOKENを使用する場合）

このエラーは、自動的に生成された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依存関係解決ドキュメントを参照してください。詳細については、issue 482650を参照してください。

さらに、Kotlin 2.0.0には依存関係の解決に影響を与える既知の問題があり、Kotlin 2.0.20で修正される予定です。詳細については、このイシューを参照してください。

Goプロジェクトをスキャンするときにビルド制約を設定する

依存関係スキャンは、linux/amd64コンテナで実行されます。その結果、Go言語プロジェクト用に生成されたビルドリストには、この環境と互換性のある依存関係が含まれています。デプロイ環境がlinux/amd64でない場合、依存関係の最終リストには、互換性のない追加のモジュールが含まれている可能性があります。依存関係リストには、デプロイ環境とのみ互換性のあるモジュールが除外されている場合もあります。この問題を回避するには、GOOSおよびGOARCH .gitlab-ci.ymlファイルの環境変数を設定して、デプロイ環境のオペレーティングシステムとアーキテクチャをターゲットとするようにビルドプロセスを設定できます。

例:

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

GOFLAGS変数を使用して、ビルドタグの制約を指定することもできます:

variables:
  GOFLAGS: "-tags=test_feature"

Go言語プロジェクトの依存関係スキャンが誤検出を返す

go.sumファイルには、プロジェクトのビルドリストの生成中に検討されたすべてのモジュールのエントリが含まれています。モジュールの複数のバージョンがgo.sumファイルに含まれていますが、go buildが使用するMVSアルゴリズムは1つしか選択しません。その結果、依存関係スキャンが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. キーとホストをセットアップするときは、絶対パス（/root/.ssh/known_hostsの代わりに~/.ssh/known_hosts）を使用します。
  2. 関連するknown_hostsファイルを指定するssh設定にUserKnownHostsFileを追加します。例：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の依存関係スキャンをハングさせる可能性がある

現在のディレクトリをターゲットとするためにrequirements.txtファイルで-e/--editableフラグを使用すると、pip3 downloadを実行したときにGemnasium Python依存関係スキャナーがハングする問題が発生する可能性があります。このコマンドは、ターゲットプロジェクトをビルドするために必要です。

この問題を解決するには、Pythonの依存関係スキャンを実行するときに-e/--editableフラグを使用しないでください。

SBTでのメモリ不足エラーの処理

Scalaプロジェクトで依存関係スキャンを使用中にSBTでメモリ不足エラーが発生した場合は、SBT_CLI_OPTS環境変数を設定することで、これに対処できます。設定例を以下に示します:

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

Kubernetesexecutorを使用している場合は、デフォルトのKubernetesリソース設定をオーバーライドする必要がある場合があります。メモリの問題を防ぐためにコンテナリソースを調整する方法の詳細については、Kubernetesexecutorドキュメントを参照してください。

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バージョンが原因で、依存関係スキャンのネビュラロック作成が失敗する

サポートされていないGradleバージョン（9.0以降）で依存関係.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プラットフォーム内で実行されるようになります。2つのスキャナーは同じ結果を提供することが期待されますが、SBOMスキャンは既存の依存関係スキャンCI/CDジョブの後に発生するため、既存の脆弱性は、GitLab SBoM Vulnerability Scannerでスキャナー値が更新されます。

ロールアウトを進め、最終的に既存のGemnasiumアナライザーを置き換えるにつれて、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を使用して実行するようにRunnerを設定していることを確認してください。

[[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で、現在のイメージバージョンを確認してください。