依存関係スキャンのトラブルシューティング
- プラン: 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の組み合わせに置き換えることができます。
特定の言語またはパッケージマネージャーのサポート不足を回避する
Supported languagesに記載されているように、一部の依存関係定義ファイルはまだサポートされていません。ただし、言語、パッケージマネージャー、またはサードパーティツールが定義ファイルをサポートされている形式に変換できれば、依存関係スキャンを実現できます。
一般的なアプローチは次のとおりです:
.gitlab-ci.ymlファイルで専用のコンバータージョブを定義します。変換を容易にするために、適切なDockerイメージ、スクリプト、またはその両方を使用します。- そのジョブに変換されたサポートファイルをアーティファクトとしてアップロードさせます。
- 変換された定義ファイルを使用するために、
dependencies: [<your-converter-job>]をdependency_scanningジョブに追加します。
例えば、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 lockfile to be analyzed.依存関係スキャンジョブが予期せず実行されている
The dependency scanning CI templateは、rules:exists構文を使用します。このディレクティブは10000回のチェックに制限されており、この数に達すると常にtrueを返します。このため、リポジトリ内のファイルの数によっては、スキャナーがプロジェクトをサポートしていなくても、依存関係スキャンジョブがトリガーされる場合があります。この制限の詳細については、rules:exists documentationを参照してください。
エラー: dependency_scanning is used for configuration only, and its script should not be executed
詳細については、application security testing troubleshootingを参照してください。
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を、dependency scanning templateで参照されているバージョンと一致するように設定します。DS_ANALYZER_IMAGE変数を直接ハードコードする場合は、dependency scanning templateにある最新の行と一致するように変更します。行番号は、編集したスキャンジョブによって異なります。例えば、
gemnasium-maven-dependency_scanningジョブはDS_ANALYZER_IMAGEが"$SECURE_ANALYZERS_PREFIX/gemnasium-maven:$DS_MAJOR_VERSION"に設定されているため、最新のgemnasium-mavenDockerイメージをプルします。
setuptoolsプロジェクトの依存関係スキャンがuse_2to3 is invalidエラーで失敗する
setuptoolsバージョンv58.0.0で、2to3のサポートが削除されました。依存関係スキャン（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.0psycopg2を使用するプロジェクトの依存関係スキャンがpg_config executable not foundエラーで失敗する
psycopg2に依存するPythonプロジェクトのスキャンは、次のメッセージで失敗する可能性があります:
Error: pg_config executable not found.psycopg2はlibpq-dev Debianパッケージに依存しますが、これはgemnasium-python Dockerイメージにはインストールされていません。このエラーを回避するには、libpq-devパッケージをbefore_scriptにインストールします:
gemnasium-python-dependency_scanning:
before_script:
- apt-get update && apt-get install -y libpq-devpoetry config http-basicをCI_JOB_TOKENとともに使用するときのNoSuchOptionException
このエラーは、自動生成されたCI_JOB_TOKENがハイフン（-）で始まる場合に発生する可能性があります。このエラーを回避するには、Poetry’s configuration adviceに従ってください。
エラー: プロジェクトに未解決の依存関係があります
次のエラーメッセージは、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 dependency resolution documentationを参照してください。詳細については、issue 482650を参照してください。
さらに、Kotlin 2.0.0には依存関係解決に影響する既知のイシューがあり、Kotlin 2.0.20で修正される予定です。詳細については、this issueを参照してください。
Goプロジェクトをスキャンする際のビルド制約を設定する
依存関係スキャンは、linux/amd64コンテナ内で実行されます。結果として、Goプロジェクト用に生成されたビルドリストには、この環境と互換性のある依存関係が含まれています。デプロイ環境がlinux/amd64でない場合、最終的な依存関係リストには、追加の互換性のないモジュールが含まれる可能性があります。依存関係リストは、デプロイ環境と互換性のあるモジュールのみを省略する場合もあります。この問題を防止するには、.gitlab-ci.ymlファイルのGOOSおよびGOARCH environment variablesを設定することで、ビルドプロセスがデプロイ環境のオペレーティングシステムとアーキテクチャをターゲットにするように設定できます。
例:
variables:
GOOS: "darwin"
GOARCH: "arm64"GOFLAGS変数を使用して、ビルドタグ制約を供給することもできます:
variables:
GOFLAGS: "-tags=test_feature"Goプロジェクトの依存関係スキャンが誤検出を返す
go.sumファイルには、プロジェクトのbuild listを生成する際に考慮されたすべてのモジュールのエントリが含まれています。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に設定したため、セットアップ中に~を使用してユーザーディレクトリを表すと発生する可能性があります。このイシューは、Cloning project over SSH fails when using gemnasium-python imageで説明されています。openssh-clientは/root/.ssh/known_hostsを見つけることを期待しますが、このパスは存在せず、代わりに/tmp/.ssh/known_hostsが存在します。
これは、openssh-clientがプリインストールされているgemnasium-pythonで解決済みですが、他のイメージにopenssh-clientをゼロからインストールする場合にイシューが発生する可能性があります。これを解決するには、次のいずれかの方法があります:
- キーとホストを設定する際に、絶対パス（
~/.ssh/known_hostsの代わりに/root/.ssh/known_hosts）を使用します。 - 関連する
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 ==
このエラーは、要件ファイルがRunnerが使用するプラットフォームとは異なるプラットフォームで生成された場合に発生します。他のプラットフォームをターゲットにするためのサポートは、issue 416376で追跡されています。
編集可能なフラグがPythonの依存関係スキャンをハングさせる可能性がある
requirements.txtファイルで-e/--editableフラグを使用して現在のディレクトリをターゲットにすると、Gemnasium Python依存関係スキャナーがpip3 downloadを実行するときにハングするイシューが発生する可能性があります。このコマンドは、ターゲットプロジェクトをビルドするために必要です。
このイシューを解決するには、Pythonの依存関係スキャンを実行するときに-e/--editableフラグを使用しないでください。
SBTでのメモリ不足エラーの処理
Scalaプロジェクトで依存関係スキャンを使用中にSBTでメモリ不足エラーが発生した場合は、SBT_CLI_OPTS環境変数を設定することで対処できます。設定例は次のとおりです:
variables:
SBT_CLI_OPTS: "-J-Xmx8192m -J-Xms4192m -J-Xss2M"Kubernetes executorを使用している場合、デフォルトのKubernetesリソース設定を上書きする必要がある場合があります。メモリイシューを防止するためのコンテナリソースの調整方法の詳細については、Kubernetes executor documentationを参照してください。
NPMプロジェクトにpackage-lock.jsonファイルがない
デフォルトでは、依存関係スキャンジョブは、リポジトリにpackage-lock.jsonファイルがある場合にのみ実行されます。しかし、一部のNPMプロジェクトは、Gitリポジトリに格納する代わりに、ビルドプロセス中にpackage-lock.jsonファイルを生成します。
これらのプロジェクトで依存関係をスキャンするには:
- ビルドジョブで
package-lock.jsonファイルを生成します。 - 生成されたファイルをアーティファクトとして保存します。
- アーティファクトを使用し、そのルールを調整するように依存関係スキャンジョブを変更します。
例えば、設定は次のようになります:
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/"パイプラインに依存関係スキャンジョブが追加されない
依存関係スキャンジョブは、依存関係のあるロックファイルまたはビルドツール関連ファイルが存在するかどうかを確認するルールを使用します。これらのファイルが検出されない場合、パイプライン内の別のジョブによってロックファイルが生成されていても、そのジョブはパイプラインに追加されません。
この状況が発生した場合は、リポジトリにsupported file、またはサポートされているファイルがランタイムで生成されることを示すファイルが含まれていることを確認してください。そのようなファイルをリポジトリに追加して、依存関係スキャンジョブをトリガーできるかどうかを検討してください。
リポジトリにそのようなファイルが含まれており、ジョブがまだトリガーされないと思われる場合は、次の情報とともにopen an issueしてください:
- 使用している言語とビルドツール。
- 提供するロックファイルの種類と、それがどこで生成されるか。
dependency scanning templateに直接コントリビュートすることもできます。
依存関係スキャンが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 deniedchmod +ux gradlewをローカルで実行し、Gitリポジトリにプッシュして、ファイルを実行可能にします。
サポートされていないGradleバージョンのため、依存関係スキャンのnebulaロック作成が失敗する
サポートされていないGradleバージョン（9.0以上）でdependency.lockfilesを作成しようとすると、次のエラーが発生します:
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/NameMatchergradleビルドをGradle 8.10.2にダウングレードしてみてください。
依存関係スキャンスキャナーがGemnasiumではなくなった
過去には、依存関係スキャンで使用されるスキャナーはGemnasiumであり、これはユーザーがvulnerability pageで見ることができるものです。
SBOMを使用した依存関係スキャンの展開により、Gemnasiumスキャナーは組み込みのGitLab SBoM Vulnerability Scannerに置き換えられます。この新しいスキャナーは、CI/CDジョブではなく、GitLabプラットフォーム内で実行されます。2つのスキャナーは同じ結果を提供すると予想されますが、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 executorを使用している場合は、RunnerがグループID（GID）0を使用して実行するように設定されていることを確認してください。
[[runners]]
[runners.kubernetes]
[runners.kubernetes.pod_security_context]
run_as_non_root = true
run_as_group = 0カスタムまたはマージされたCycloneDX SBOMに対して脆弱性スキャンが結果を生成しない
依存関係スキャンCI/CDジョブは成功し、SBOMコンポーネントは依存関係リストに表示されますが、パイプラインのセキュリティータブには脆弱性は報告されません。
GitLab 18.10以降では、セキュリティータブに次のメッセージが表示されます: 「SBOMレポートには、脆弱性スキャンに必要なGitLabメタデータプロパティが不足しています。」
このイシューは、SBOMに必要なGitLab CycloneDX propertiesが不足している場合に発生します。これらのプロパティがないと、脆弱性スキャナーはSBOMのコンポーネントの検出結果を構築できません。依存関係リストはまだ入力された状態ですが、脆弱性は報告されません。
これは通常、次の場合に発生します:
- 複数のSBOMが
cyclonedx mergeを使用してマージされ、メタデータプロパティが削除される場合。 - サードパーティのSBOMジェネレーターがGitLab固有のプロパティを含んでいない場合。
metadata.propertiesからgitlab:meta:schema_versionプロパティ（1である必要があります）が不足している場合。
脆弱性スキャンに必要なプロパティ
| プロパティ | 場所 | 説明 |
|---|---|---|
gitlab:meta:schema_version | metadata.properties | 1に設定する必要があります。 |
gitlab:dependency_scanning:input_file:path | metadata.propertiesまたは各コンポーネントのproperties | 依存関係を生成するために分析されたロックファイルへのパス。どちらも存在しない場合、これらのコンポーネントに対して脆弱性の検出結果は生成されません。GitLab 18.10以降では、パイプラインのセキュリティータブにエラーが表示されます。 |
この問題を解決するには、次のいずれかのアプローチを選択してください:
各SBOMを個別にアップロードします。
マージする代わりに、各SBOMを個別の
artifacts: reports: cyclonedx:エントリとしてアップロードします。これにより、各ファイル内のGitLab固有のプロパティが保持されます。サードパーティのSBOMにプロパティを追加します。
サードパーティツールによって生成されたSBOMには、通常、GitLab固有のプロパティは含まれていません。脆弱性スキャンを有効にするには、SBOMに
metadata.propertiesに次のものが含まれていることを確認してください:gitlab:meta:schema_versionが1に設定されていることgitlab:dependency_scanning:input_file:pathがロックファイルのリポジトリ相対パスに設定されていること（例:package-lock.jsonまたはsrc/Gemfile.lock）
SBOMに複数のロックファイルからのコンポーネントが含まれている場合は、各コンポーネントが正しいソースファイルを指すように、メタデータ内ではなく、各コンポーネントの
properties配列に個別にinput_file:pathを設定します。サポートされているプロパティの完全なリストについては、GitLab CycloneDX property taxonomyを参照してください。
詳細については、イシュー542813とマージリクエスト221549を参照してください。
脆弱性スキャンがすべての依存関係に対して誤った入力ファイルを表示する
脆弱性レポートまたは依存関係リスト内のすべての依存関係は、異なるロックファイルから発生しているにもかかわらず、同じ入力ファイルパスを示しています。
このイシューは、gitlab:dependency_scanning:input_file:pathプロパティがコンポーネントごとではなくmetadata.propertiesに設定されている場合に発生します。property taxonomyによると、メタデータレベルのプロパティはドキュメント内のすべてのオブジェクトに適用されるため、単一の値がすべてのコンポーネントを上書きします。
このイシューを解決するには、トップレベルのメタデータ内ではなく、各コンポーネントのproperties配列に個別にinput_file:pathを設定します。input_file:pathプロパティは、異なるロックファイルからのコンポーネントを含むマージされたSBOMにとって特に重要です。
エラー: 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で現在のイメージバージョンを確認してください。