SBOMを使用した依存関係スキャン

CycloneDXソフトウェア部品表（SBOM）を使用した依存関係スキャンでは、既知の脆弱性についてアプリケーションの依存関係が分析されます。すべての依存関係（推移的な依存関係を含む）がスキャンされます。

依存関係スキャンは、多くの場合、ソフトウェアコンポジション解析（SCA）の一部と見なされます。SCAには、コードで使用するアイテムの検査の側面が含まれる場合があります。これらのアイテムには通常、アプリケーションやシステムの依存関係が含まれており、ほとんどの場合、これらはユーザーが記述したアイテムからではなく外部ソースからインポートされます。

依存関係スキャンは、アプリケーションのライフサイクルの開発フェーズで実行できます。新しい依存関係スキャンアナライザーをCI/CDパイプラインで使用すると、プロジェクトの依存関係が検出され、CycloneDX SBOMレポートとして報告されます。セキュリティの検出結果は、ソースブランチとターゲットブランチの間で特定され、比較されます。コードの変更がコミットされる前に、アプリケーションに対するリスクにプロアクティブに対処できるように、検出結果とその重大度がマージリクエストにリストされます。報告されたSBOMコンポーネントのセキュリティアドバイザリーは、新しいセキュリティアドバイザリーが公開されると、CI/CDパイプラインとは無関係に、継続的脆弱性スキャンによっても識別されます。

GitLabは、これらのすべての依存関係タイプを確実に網羅するために、依存関係スキャンとコンテナスキャンの両方を提供しています。リスク領域をできるだけ広くカバーするために、すべてのセキュリティスキャナーを使用することをおすすめします。これらの機能の比較については、依存関係スキャンとコンテナスキャンの比較を参照してください。

このフィードバックイシューで、新しい依存関係スキャンアナライザーに関するご意見をお聞かせください。

依存関係スキャンを有効にする

プロジェクトの依存関係スキャンを有効にします。

前提条件

すべてのGitLabインスタンスの前提条件:

• プロジェクトのデベロッパー、メンテナー、またはオーナーロール。
• サポートされているロックファイルまたは依存関係グラフのエクスポートが、リポジトリにコミットされるか、CI/CDパイプラインで作成されてアーティファクトとしてdependency-scanningジョブに渡される必要があります。あるいは、依存関係の解決によって、サポートされているエコシステムに必要なファイルを生成できるか、マニフェストファイルをフォールバックオプションとして使用できます。
• セルフマネージドGitLab Runnerの場合は、dockerまたはkubernetes executorを使用するGitLab Runner。
• GitLab.comでホストされているRunnerの場合、この設定はデフォルトで有効になっています。

GitLab Self-Managedの場合のみ、スキャンされるすべてのPURLタイプのパッケージメタデータをGitLabインスタンスで同期する必要があります。このデータがGitLabインスタンスで使用できない場合、依存関係スキャンは脆弱性を特定できません。

プロジェクトのパイプライン構成を更新

依存関係スキャンを有効にするには、依存関係スキャンテンプレートをプロジェクトのパイプライン構成に追加する必要があります。

デフォルトでは、Dependency-Scanning.v2.gitlab-ci.ymlテンプレートはマージリクエストパイプラインで依存関係スキャンジョブを実行します。プロジェクトが他のジョブにマージリクエストパイプラインを使用しない場合、マージリクエストパイプラインには依存関係スキャンジョブのみが表示され、他のすべてのジョブは個別のブランチパイプラインで実行されます。この動作を無効にするには、マージリクエストパイプラインの依存関係スキャンを無効にするを参照してください。

GitLab UIを介して依存関係スキャンを有効にするには:

1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。

2. 左側のサイドバーで、コード > リポジトリを選択します。

3. .gitlab-ci.ymlファイルを選択します。

4. 編集 > 単一のファイルを編集を選択します。

5. Dependency-Scanning.v2 CI/CDテンプレートを追加します:

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

6. 変更をコミットするを選択します。

利用可能なコンテナイメージ

この機能は、CIジョブを実行するためにコンテナイメージに依存しています。デフォルトのCIジョブ定義は、これらのイメージをメジャーバージョンタグ (dependency-scanning:2など) で参照するため、CI/CD設定を変更することなく、パッチおよびマイナーアップデートが自動的に適用されます。

メンテナンスポリシー

GitLabは、現在の安定リリースのバグ修正と、過去2か月のリリースのセキュリティ修正を提供するために、リリースおよびメンテナンスポリシーに従います。

CI/CDジョブはメジャーバージョンタグ (dependency-scanning:2など) でイメージを参照するため、そのメジャーイメージバージョンと互換性のあるすべてのGitLabバージョンで修正が自動的に利用可能です。

これは、以下にリストされているイメージに適用されます。以前のイメージはこのポリシーの対象ではありません。

現在のイメージ

現在のイメージは、ベースイメージベンダーからのアップストリームパッチを組み込むために定期的に再構築されます。

以前のイメージ

これらのイメージは非推奨であり、バグ修正や新機能は今後提供されません。これらはコンテナレジストリで引き続き利用可能であり、対応するGitLabバージョンで動作し続けます。非推奨のイメージを新しいGitLabバージョンで使用することはサポートされておらず、予期せぬ結果を生じる可能性があります。

FIPSコンプライアンス

依存関係スキャンアナライザーイメージおよびすべての依存関係解決イメージは、FIPS 140で検証された暗号学的モジュールを使用するRed Hat UBIに基づいています。FIPS対応環境では追加の設定は必要ありません。

結果について理解する

依存関係スキャンアナライザーの出力内容:

• 検出されたサポート対象のロックファイルまたは依存関係グラフエクスポートごとに、CycloneDX SBOMが作成されます。
• スキャンされたすべてのSBOMドキュメントに対する単一の依存関係スキャンレポート（GitLab.comおよびGitLab Self-Managedのみ）。

CycloneDXソフトウェア部品表

The依存関係スキャンアナライザーは、サポートされているロックファイル、依存関係グラフ、またはマニフェストファイルが検出されたディレクトリごとに、CycloneDXソフトウェア部品表 (SBOM) を出力します。CycloneDX SBOMは、ジョブアーティファクトとして作成されます。

CycloneDX SBOMの仕様は次のとおりです:

• gl-sbom-<package-type>-<package-manager>.cdx.jsonという名前が付けられます。
• 依存関係スキャンジョブのジョブアーティファクトとして利用できます。
• cyclonedxレポートとしてアップロードされます。
• 検出されたロックファイルまたは依存関係グラフファイルと同じディレクトリに保存されます。

たとえば、プロジェクトに次の構造がある場合:

.
├── ruby-project/
│   └── Gemfile.lock
├── ruby-project-2/
│   └── Gemfile.lock
└── php-project/
    └── composer.lock

次のCycloneDX SBOMは、ジョブアーティファクトとして作成されます:

.
├── ruby-project/
│   ├── Gemfile.lock
│   └── gl-sbom-gem-bundler.cdx.json
├── ruby-project-2/
│   ├── Gemfile.lock
│   └── gl-sbom-gem-bundler.cdx.json
└── php-project/
    ├── composer.lock
    └── gl-sbom-packagist-composer.cdx.json

依存関係スキャンレポート

依存関係スキャンアナライザーは、CycloneDX SBOMファイルで特定された依存関係で特定されたすべての脆弱性をドキュメント化する依存関係スキャンレポートを生成します。

依存関係スキャンレポート:

• gl-dependency-scanning-report.jsonという名前が付けられます。
• 依存関係スキャンジョブのジョブアーティファクトとして使用できます。
• dependency_scanningレポートとしてアップロードされます。
• プロジェクトのルートディレクトリに保存されます。

最適化

SBOMを使用した依存関係スキャンを最適化するには、次のいずれかの方法を使用します:

• パスを除外する
• スキャンを最大のディレクトリ深度に制限する

パスを除外する

スキャンパフォーマンスを最適化し、関連するリポジトリコンテンツに焦点を当てるには、パスを除外します。

.gitlab-ci.ymlファイルに、除外されたパスを一覧表示します:

• 依存関係スキャンテンプレートを使用している場合は、DS_EXCLUDED_PATHS CI/CD変数を使用します。
• 依存関係スキャンCI/CDコンポーネントを使用している場合は、excluded_paths仕様入力を使用します。

除外パターン

除外パターンは、次のルールに従います:

• スラッシュのないパターンは、プロジェクト内の任意の深度でファイル名またはディレクトリ名と一致します（例: testは./test、src/testと一致します）。
• スラッシュ（/）を含むパターンは、親ディレクトリ単位でのマッチングが行われます。つまり、そのパターンで始まるパスに一致します（例: a/bはa/bとa/b/cには一致しますが、c/a/bには一致しません）。
• 標準のglobワイルドカードがサポートされています（例: a/**/bはa/b、a/x/b、a/x/y/bと一致します）。
• 先頭と末尾のスラッシュは無視されます（例: /buildとbuild/はbuildと同じように動作します）。

スキャンを最大のディレクトリ深度に制限する

スキャンパフォーマンスを最適化し、分析するファイルの数を減らすために、スキャンを最大のディレクトリ深度に制限します。

ルートディレクトリは深度1としてカウントされ、各サブディレクトリは深度を1ずつ増やします。デフォルトの深度は2です。値が-1の場合、深さに関係なくすべてのディレクトリをスキャンします。

.gitlab-ci.ymlファイルで最大の深度を指定するには、以下を行います:

• 依存関係スキャンテンプレートを使用している場合は、DS_MAX_DEPTH CI/CD変数を使用します。
• 依存関係スキャンCI/CDコンポーネントを使用している場合は、max_scan_depth仕様入力を使用します。

次の例では、DS_MAX_DEPTHが3に設定されている場合、commonディレクトリのサブディレクトリはスキャンされません。

timer
├── integration
│   ├── doc
│   └── modules
└── source
    ├── common
    │   ├── cplusplus
    │   └── go
    ├── linux
    ├── macos
    └── windows

ロールアウトする

単一のプロジェクトでSBOMの結果を使用した依存関係スキャンに自信がある場合は、その実装を複数のプロジェクトとグループに拡張できます。詳細については、複数のプロジェクトでスキャンを強制するを参照してください。

固有の要件がある場合、SBOMを使用した依存関係スキャンはオフライン環境で実行できます。

サポートされているパッケージタイプ

セキュリティポリシー分析を効果的にするには、SBOMレポートにリストされているコンポーネントに、GitLab Advisory Databaseに対応するエントリが含まれている必要があります。

GitLab SBOM脆弱性スキャナーは、次のPURLタイプのコンポーネントについて、依存関係スキャンの脆弱性を報告できます:

• cargo
• composer
• conan
• gem
• golang
• maven
• npm
• nuget
• pypi
• swift

サポートされている言語とファイル

脚注:

1. ロックファイルに、異なる環境マーカーを持つ同じパッケージの複数のエントリ（例: Python <3.11の場合はnumpy==2.2.6、Python ≥3.11の場合はnumpy==2.4.1）が含まれている場合、最初のエントリのみが解析され、レポートされます。

パッケージハッシュ情報

依存関係スキャンSBOMには、利用可能な場合にパッケージハッシュ情報が含まれます。この情報は、NuGetパッケージにのみ提供されます。パッケージの整合性と信頼性を検証できるように、SBOM内の次の場所にパッケージハッシュが表示されます:

• 専用ハッシュフィールド
• PURL修飾子

例:

{
  "name": "Iesi.Collections",
  "version": "4.0.4",
  "purl": "pkg:nuget/Iesi.Collections@4.0.4?sha512=8e579b4a3bf66bb6a661f297114b0f0d27f6622f6bd3f164bef4fa0f2ede865ef3f1dbbe7531aa283bbe7d86e713e5ae233fefde9ad89b58e90658ccad8d69f9",
  "hashes": [
    {
      "alg": "SHA-512",
      "content": "8e579b4a3bf66bb6a661f297114b0f0d27f6622f6bd3f164bef4fa0f2ede865ef3f1dbbe7531aa283bbe7d86e713e5ae233fefde9ad89b58e90658ccad8d69f9"
    }
  ],
  "type": "library",
  "bom-ref": "pkg:nuget/Iesi.Collections@4.0.4?sha512=8e579b4a3bf66bb6a661f297114b0f0d27f6622f6bd3f164bef4fa0f2ede865ef3f1dbbe7531aa283bbe7d86e713e5ae233fefde9ad89b58e90658ccad8d69f9"
}

アナライザーの動作をカスタマイズする

アナライザーの動作のカスタマイズ方法は、イネーブルメントソリューションによって異なります。

CI/CDテンプレートを使用した動作のカスタマイズ

利用可能なspec入力

次のspec入力は、Dependency-Scanning.v2.gitlab-ci.ymlテンプレートと組み合わせて使用できます。

利用可能なCI/CD変数

これらの変数はspec入力を置き換えることができ、ベータlatestテンプレートとも互換性があります。

マージリクエストパイプラインの依存関係スキャンを無効にする

デフォルトでは、Dependency-Scanning.v2.gitlab-ci.ymlテンプレートはマージリクエストパイプラインで依存関係スキャンジョブを実行します。プロジェクトが他のジョブにマージリクエストパイプラインを使用しない場合、各マージリクエストに対して2つのパイプラインが実行され、他のジョブは個別のブランチパイプラインで実行される可能性があります。この動作を無効にするには、仕様入力enable_mr_pipelines: falseまたはCI/CD変数AST_ENABLE_MR_PIPELINES: "false"を設定します。

サポートされているファイルが存在しない場合にジョブをスキップする

デフォルトでは、プロジェクトにサポートされているファイルが含まれていない場合でも、テンプレートを含むすべてのパイプラインで依存関係スキャンジョブが実行されます。サポートされているファイルが検出されない場合にジョブをスキップするには、DS_SKIP_IF_NO_SUPPORTED_FILESを"true"に設定します:

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

variables:
  DS_SKIP_IF_NO_SUPPORTED_FILES: "true"

変数が設定されている場合、依存関係スキャンジョブは、プロジェクトにサポートされているファイルリストのファイルが少なくとも1つ含まれている場合、またはDS_PIPCOMPILE_LOCKFILE_FILE_NAME_PATTERN、DS_PIP_MANIFEST_FILE_NAME_PATTERN、あるいはPIP_REQUIREMENTS_FILE（非推奨）でカスタムパターンが設定されている場合にのみ実行されます。

カスタムTLS認証局

依存関係スキャンでは、アナライザーコンテナイメージに付属するデフォルトの代わりに、カスタムTLS証明書をSSL/TLS接続に使用できます。

カスタムTLS認証局を使用する

カスタムTLS認証局を使用するには、CI/CD変数ADDITIONAL_CA_CERT_BUNDLEにX.509 PEM公開キー証明書のテキスト表現を割り当てます。

たとえば、.gitlab-ci.ymlファイルで証明書を設定するには、次のようにします:

variables:
  ADDITIONAL_CA_CERT_BUNDLE: |
      -----BEGIN CERTIFICATE-----
      MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
      ...
      jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
      -----END CERTIFICATE-----

依存関係の解決

リポジトリにコミットされたサポート対象のロックファイルまたは依存関係グラフエクスポートがないプロジェクトの場合、依存関係解決はスキャン実行前に必要なファイルを自動的に生成できます。

サポートされているマニフェストファイルがプロジェクトで検出されると、依存関係解決が自動的にトリガーされます。解決ジョブは、最小限のエコシステムイメージ（例: ubi9/openjdk-21）を使用して.preパイプラインステージで実行され、ロックファイルまたは依存関係グラフエクスポートをネイティブに生成します。これらのジョブは既存のロックファイルまたはグラフエクスポートを保持し、存在しない場合にのみ作成します。生成されたアーティファクトは、その後、testパイプラインステージのdependency-scanningジョブによって消費されます。デフォルトのイメージを同等の代替（例: eclipse-temurin:jdk-21）または必要なビルドツールを含むカスタムイメージに置き換えることができます。

以下のエコシステムが依存関係解決をサポートしています:

依存関係解決のカスタマイズ

利用可能なすべてのオプションについては、利用可能なspecインプットおよび利用可能なCI/CD変数を参照してください。

カスタムの依存関係解決イメージを使用する

独自のイメージを使用するには、以下の入力を設定できます:

• maven_resolution_image
• gradle_resolution_image
• python_resolution_image

たとえば、Mavenの解決にカスタムイメージを使用する場合:

include:
  - template: Jobs/Dependency-Scanning.v2.gitlab-ci.yml
    inputs:
      maven_resolution_image: "registry.gitlab.mycorp.com/eclipse-temurin:jdk-21"

あるいは、以下のCI/CD変数を設定できます:

• DS_MAVEN_RESOLUTION_IMAGE
• DS_GRADLE_RESOLUTION_IMAGE
• DS_PYTHON_RESOLUTION_IMAGE

依存関係解決を無効にする

特定のエコシステムにおける依存関係解決を無効にするには、CI/CD変数DS_DISABLED_RESOLUTION_JOBSまたは入力disabled_resolution_jobsを使用します。指定可能な値はmaven、gradle、pythonです。

たとえば、Mavenの依存関係解決を無効にする場合:

variables:
  DS_DISABLED_RESOLUTION_JOBS: "maven"

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

依存関係解決のセキュリティに関する考慮事項

依存関係解決ジョブは、CI/CDコンテナ内でエコシステムネイティブのビルドツール (mvn, gradle, pip-compile) を実行します。これらのツールは、環境変数や設定ファイルをネイティブに尊重し、起動時に拡張機能を読み込むか任意のコードを実行できます。これには以下が含まれます:

• Maven: MAVEN_ARGS, MAVEN_CLI_OPTS (レガシー), MAVEN_OPTS, JAVA_TOOL_OPTIONS, -sまたは--settingsを介して参照される任意のsettings.xml、およびpom.xmlまたはsettings.xmlで宣言された<extensions>。
• Gradle: GRADLE_OPTS, JAVA_TOOL_OPTIONS, --init-script、およびbuild.gradleまたはbuild.gradle.kts内のトップレベルのGroovyまたはKotlinコード。
• Python: PIP_INDEX_URL, PIP_EXTRA_INDEX_URL, setup.py、およびロックファイルインストールフック。

これらのCI/CD変数を設定したり、プロジェクトのビルドファイルを変更できるユーザーは、解決ジョブで任意のコードを実行させることができます。解決ジョブはCI_JOB_TOKENで実行され、スコープ内のマスクされたCI/CD変数にアクセスし、ジョブの期間中、プロジェクトリポジトリへの読み取りまたは書き込みを行います。

このプロパティはエコシステムネイティブのビルドツールに固有のものであり、依存関係スキャンに特有のものではありません。解決ジョブを機密性の高い実行コンテキストとして扱います。

推奨される制御:

• 以前にリストされた変数を定義またはオーバーライドできるユーザーを制限します。保護ブランチおよびタグにスコープ設定された保護CI/CD変数を使用します。開発者が編集できる.gitlab-ci.yml variables:ブロックには設定しないでください。
• MAVEN_ARGS, MAVEN_CLI_OPTS, GRADLE_OPTS, --init-script, カスタムsettings.xml, および<extensions>のpom.xmlにおける使用状況を、標準のコードレビュープロセスの一部として監査します。
• スキャン実行ポリシーを使用して依存関係スキャンを適用する場合、ターゲットプロジェクトからの開発者が作成したvariables:は、挿入された解決ジョブに流れます。ポリシーフレームワークが転送する変数を確認し、ポリシー内のビルドツール変数の設定を解除またはオーバーライドします。
• プロジェクトのビルドが管理および信頼できるCI/CDジョブ（buildステージでmvn packageを実行するようなジョブ）で実行される場合、その同じジョブでロックファイルまたは依存関係グラフエクスポートを生成し、GitLabが提供する解決ジョブをDS_DISABLED_RESOLUTION_JOBSで無効にします。このアプローチはビルドツールの実行リスクを軽減するものではありませんが、機密性の高いジョブのコンテキストを1つに限定します。
• 既知のツールチェーンを保証する必要がある場合は、ダイジェストで固定されたカスタム解決イメージを使用します。

依存関係解決の制限

依存関係解決は、エコシステムネイティブのビルドツールを、バニライメージまたはカスタムイメージ内で、エコシステムごとに単一の固定ランタイムバージョンとビルドツールで実行します。

解決の成功は、プロジェクトがこの環境と互換性があるか、パッケージレジストリに到達できるか、および依存関係収集を超えるビルド時の要件がないかに依存します。

デフォルト環境で失敗するプロジェクトは、関連する解決ジョブイメージをオーバーライドして、必要なすべての依存関係と互換性のあるものを提供できます。

互換性がある場合でも、解決環境は、プロジェクトがビルドされた正確なランタイムバージョンやその他の要件と一致しない場合があります。したがって、生成された依存関係グラフは、プロジェクトの実際のビルド環境で解決されるであろう正確な依存関係のセットを反映しない場合があります。相違は、固定されたランタイムバージョン、未解決の環境マーカー、プラットフォーム固有の依存関係、または解決ジョブで利用できないビルド時のコンテキストに依存する条件付き依存関係グループから生じる可能性があります。

最も正確な結果を得るには、独自のビルド環境で生成されたロックファイルまたは依存関係グラフエクスポートを提供してください。依存関係解決ワークフローで適切にカバーされていない高度にカスタマイズされたビルドを持つプロジェクトの場合、手動でロックファイルまたは依存関係グラフエクスポートを作成するで説明されているように、独自のビルド環境で生成されたロックファイルまたは依存関係グラフエクスポートを提供する必要があります。

Maven解決の既知のイシュー

デフォルト環境: Java 21, Maven 3.9

Mavenプロジェクトには以下の制限が適用されます:

• Maven enforcerプラグイン: Maven Enforcerプラグインで厳格なJavaバージョンルールを使用するプロジェクトは、失敗する可能性があります。この問題を軽減するために解決コマンドは-Denforcer.skip=trueを渡しますが、すべてのenforcerルールがスキップされるわけではありません。
• プロファイルベースのアクティベーション: JDKバージョンによってアクティベートされる条件付きモジュールを使用するプロジェクト（例: ZXing、Dubbo）は、元々ターゲットとされたJavaバージョンでビルドされた場合とは異なる依存関係グラフを生成する可能性があります。
• 初期ライフサイクルフェーズのプラグイン: 解決イメージのJavaバージョンと互換性のない検証または初期化フェーズにバインドされたプラグインは、失敗を引き起こす可能性があります。

Gradle解決の既知のイシュー

デフォルト環境: Java 17, Gradle 8

ジョブは、Gradleラッパーが存在する場合は./gradlew dependenciesを、それ以外の場合はgradle dependenciesを実行します。マルチモジュールプロジェクトの場合、各サブプロジェクトは:<subproject>:dependenciesを使用して個別に解決されます。ジョブは、対応するプロジェクトディレクトリ内のgradle.graph.txtに出力を書き込みます。

Gradleプロジェクトには以下の制限が適用されます:

• ラッパーの要件: Gradleラッパー (gradlew) が存在する場合、有効なgradle-wrapper.jarを参照する必要があります。ラッパーが存在しない場合、ジョブはシステムgradleを使用します。
• プラグインとバージョンの互換性: 特定のGradleプラグイン、カスタムツールチェーン、またはJava 17以外のJavaバージョンを必要とするプロジェクトは失敗する可能性があります。解決イメージ (spec:inputs:gradle_resolution_image) を、必要なビルド環境を含むイメージでオーバーライドします。

Python解決の既知のイシュー

デフォルト環境: Python 3.12, pip-tools 7

Pythonプロジェクトには以下の制限が適用されます:

• Pipfileはサポートされていません: Pipfileプロジェクト（Pipfile.lockファイルなし）はサポートされていません。リポジトリにPipfileファイルが存在しても、Pythonの解決ジョブはトリガーされません。
• Git/VCS依存関係: GitまたはVCSのURL（git+https://...）として指定された依存関係は解決できません。この特定のマニフェストファイルに対しては解決コマンドは失敗しますが、他のファイルがあれば処理を続行します。
• ローカル/編集可能なインストール: -e .、file:、またはローカルパス参照を使用するエントリは、解決前に除去され、警告が発行されます。それらのパッケージは出力に表示されません。
• 動的install_requiresを持つsetup.py: install_requiresがランタイム時にファイルから読み取りを行うと、警告が発行され、pip-compileは解決を試みますが失敗する可能性があります。
• [project]テーブルのないpyproject.toml: ビルドシステム設定のみを含むpyproject.tomlはスキップされ、警告が発行されます。
• DS_INCLUDE_DEV_DEPENDENCIESスコープ: [dependency-groups]を持つpyproject.tomlに対してのみ、開発依存関係のインクルージョンが実装されています。

ロックファイルまたは依存関係グラフエクスポートを手動で作成する

お使いのプロジェクトが、リポジトリにコミットされたサポート対象のロックファイルまたは依存関係グラフエクスポートを持たず、かつ依存関係解決がそれをサポートしていない場合、いずれかを提供する必要があります。

複雑なビルド、カスタムビルドステップ、プライベートレジストリ、または特定の環境要件を持つプロジェクトでは、ロックファイルまたは依存関係グラフエクスポートを手動で作成することを検討してください。既存のビルドプロセスの一部としてファイルを生成することは、その環境を依存関係解決にレプリケートするよう設定するよりも、多くの場合高速で簡単です。手動でのファイル作成は、より正確な結果も生成します。このファイルは、推移的な依存関係やプラットフォーム固有の解決策を含め、独自のビルドからの正確な依存関係バージョンを反映しています。

以下の例は、一般的な言語およびパッケージマネージャーでGitLabアナライザーによってサポートされているファイルを作成する方法を示しています。サポートされている言語とファイルの完全なリストも参照してください。

Go

この方法は、Goツールチェーンのgo mod graphコマンドを使用して、アナライザーが必要とするすべての情報（直接の依存関係や推移的な依存関係を含む）を含むgo.graphファイルを生成します。このファイルがない場合、アナライザーはgo.modのみからコンポーネントを抽出しますが、依存関係パス情報は利用できず、同じモジュールの複数のバージョンが存在する場合に誤検出が発生する可能性があります。

Goプロジェクトでアナライザーを有効にするには:

1. Dependency-Scanning.v2 CI/CDテンプレートを追加します。
2. プロジェクトの既存のビルドジョブにgo mod graphコマンドを追加するか、ビルドジョブが存在しない場合は専用のジョブを作成します。このジョブは、スキャン開始時にアーティファクトが利用可能になるように、dependency-scanningジョブの前に実行する必要があります。
3. go.graphをジョブアーティファクトとして宣言します。

コマンドを既存のビルドジョブに追加することは、ビルドからのモジュールキャッシュを再利用するため、別のジョブで実行するよりも高速です。

例:

stages:
  - build
  - test

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

build:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the go.graph artifact.
  stage: build
  image: "golang:latest"
  script:
    # Your regular build script
    - go mod tidy
    - go build ./...
    # New instruction to generate the dependency graph
    - go mod graph > go.graph
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/go.graph"

Gradle

Gradleプロジェクトの場合、依存関係グラフエクスポートを作成するには以下のいずれかの方法を使用してください。

• Gradle dependenciesタスク
• Nebula Gradle Dependency Lockプラグイン
• Gradle HtmlDependencyReportTask

Gradle依存関係タスク

この方法は、自動依存関係解決を駆動する同じgradle dependenciesタスクを使用します。これは、アナライザーが必要とするすべての情報（直接の依存関係や推移的な依存関係、依存関係パスを有効にするためのグラフ情報を含む）を含む単一のgradle.graph.txtファイルを生成するため、推奨されるアプローチです。

Gradleプロジェクトでアナライザーを有効にするには、以下の手順に従います:

1. Dependency-Scanning.v2 CI/CDテンプレートを追加します。
2. プロジェクトの既存のビルドジョブにgradle dependenciesコマンドを追加するか、ビルドジョブが存在しない場合は専用のジョブを作成します。このジョブは、スキャン開始時にアーティファクトが利用可能になるように、dependency-scanningジョブの前に実行する必要があります。
3. gradle.graph.txtをジョブアーティファクトとして宣言します。
4. 自動依存関係解決を無効にするには、gradleをDS_DISABLED_RESOLUTION_JOBS CI/CD変数またはdisabled_resolution_jobs入力値に追加します。

コマンドを既存のビルドジョブに追加することは、ビルドからのGradleデーモン、キャッシュ、および解決済み設定を再利用するため、別のジョブで実行するよりも高速です。

例:

stages:
  - build
  - test

image: gradle:8.0-jdk11

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

build:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the gradle.graph.txt artifact.
  stage: build
  script:
    # Your regular build script
    - ./gradlew build
    # New instruction to generate the dependency graph
    - ./gradlew dependencies > gradle.graph.txt
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/gradle.graph.txt"

依存関係ロックプラグイン

この方法は、gradle-dependency-lock-pluginを使用して2つのロックファイルを生成します: dependencies.lock（直接の依存関係と推移的な依存関係）とdependencies.direct.lock（直接の依存関係のみ）。アナライザーは両方のファイルを使用して、依存関係グラフ内で直接の依存関係と推移的な依存関係を区別します。

Gradleプロジェクトでアナライザーを有効にするには、以下の手順に従います:

1. Dependency-Scanning.v2 CI/CDテンプレートを追加します。
2. gradle-dependency-lock-pluginをプロジェクトに適用します。これは、build.gradleまたはbuild.gradle.ktsを編集するか、initスクリプトを使用することで行えます。
3. プロジェクトの既存のビルドジョブにgenerateLock saveLockコマンドを追加するか、ビルドジョブが存在しない場合は専用のジョブを作成します。このジョブは、スキャン開始時にアーティファクトが利用可能になるように、dependency-scanningジョブの前に実行する必要があります。
4. dependencies.lockとdependencies.direct.lockをジョブアーティファクトとして宣言します。
5. 自動依存関係解決を無効にするには、gradleをDS_DISABLED_RESOLUTION_JOBS CI/CD変数またはdisabled_resolution_jobs入力値に追加します。

例:

stages:
  - build
  - test

image: gradle:8.0-jdk11

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

generate nebula lockfile:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the scannable artifacts.
  stage: build
  script:
    - |
      cat << EOF > nebula.gradle
      initscript {
          repositories {
            mavenCentral()
          }
          dependencies {
              classpath 'com.netflix.nebula:gradle-dependency-lock-plugin:12.7.1'
          }
      }

      allprojects {
          apply plugin: nebula.plugin.dependencylock.DependencyLockPlugin
      }
      EOF
      ./gradlew --init-script nebula.gradle -PdependencyLock.includeTransitives=true -PdependencyLock.lockFile=dependencies.lock generateLock saveLock
      ./gradlew --init-script nebula.gradle -PdependencyLock.includeTransitives=false -PdependencyLock.lockFile=dependencies.direct.lock generateLock saveLock
      # generateLock saves the lockfile in the build/ directory of a project
      # and saveLock copies it into the root of a project. To avoid duplicates
      # and get an accurate location of the dependency, use find to remove the
      # lockfiles in the build/ directory only.
  after_script:
    - find . -path '*/build/dependencies*.lock' -print -delete
  # Make the artifacts available to the dependency-scanning job.
  artifacts:
    paths:
      - '**/dependencies*.lock'

HtmlDependencyReportTask

この方法は、HtmlDependencyReportTaskを使用して、直接の依存関係と推移的な依存関係を含むgradle-html-dependency-report.jsファイルを生成します。gradleバージョン4から8でテストされています。

Gradleプロジェクトでアナライザーを有効にするには、以下の手順に従います:

1. Dependency-Scanning.v2 CI/CDテンプレートを追加します。
2. プロジェクトの既存のビルドジョブにgradle htmlDependencyReportコマンドを追加するか、ビルドジョブが存在しない場合は専用のジョブを作成します。このジョブは、スキャン開始時にアーティファクトが利用可能になるように、dependency-scanningジョブの前に実行する必要があります。
3. gradle-html-dependency-report.jsをジョブアーティファクトとして宣言します。
4. 自動依存関係解決を無効にするには、gradleをDS_DISABLED_RESOLUTION_JOBS CI/CD変数またはdisabled_resolution_jobs入力値に追加します。

例:

stages:
  - build
  - test

# Define the image that contains Java and Gradle
image: gradle:8.0-jdk11

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

build:
  stage: build
  script:
    - gradle --init-script report.gradle htmlDependencyReport
  # The gradle task writes the dependency report as a javascript file under
  # build/reports/project/dependencies. Because the file has an un-standardized
  # name, the after_script finds and renames the file to
  # `gradle-html-dependency-report.js` copying it to the  same directory as
  # `build.gradle`
  after_script:
    - |
      reports_dir=build/reports/project/dependencies
      while IFS= read -r -d '' src; do
        dest="${src%%/$reports_dir/*}/gradle-html-dependency-report.js"
        cp $src $dest
      done < <(find . -type f -path "*/${reports_dir}/*.js" -not -path "*/${reports_dir}/js/*" -print0)
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/gradle-html-dependency-report.js"

上記のコマンドはreport.gradleファイルを使用し、--init-scriptを介して提供するか、そのコンテンツをbuild.gradleに直接追加できます:

allprojects {
    apply plugin: 'project-report'
}

while IFS= read -r -d '' file; do
  grep --quiet -E '"resolvable":\s*"FAILED' $file && echo "Dependency report has dependencies with FAILED resolution status" && exit 1
done < <(find . -type f -path "*/gradle-html-dependency-report.js -print0)

Maven

この方法は、自動依存関係解決を駆動する同じmvn dependency:treeコマンドを使用します。これは、アナライザーが必要とするすべての情報（直接の依存関係や推移的な依存関係、依存関係パスを有効にするためのグラフ情報を含む）を含む単一のmaven.graph.jsonファイルを生成します。

Mavenプロジェクトでアナライザーを有効にするには:

1. Dependency-Scanning.v2 CI/CDテンプレートを追加します。
2. プロジェクトの既存のビルドジョブにmvn dependency:treeコマンド（maven-dependency-pluginバージョン3.7.0以降を使用）を追加するか、ビルドジョブが存在しない場合は専用のジョブを作成します。このジョブは、スキャン開始時にアーティファクトが利用可能になるように、dependency-scanningジョブの前に実行する必要があります。
3. maven.graph.jsonをジョブアーティファクトとして宣言します。
4. 自動依存関係解決を無効にするには、mavenをDS_DISABLED_RESOLUTION_JOBS CI/CD変数またはdisabled_resolution_jobs入力値に追加します。

コマンドを既存のビルドジョブに追加することは、ビルドからのMavenセッションおよび解決済み設定を再利用するため、別のジョブで実行するよりも高速です。

例:

stages:
  - build
  - test

image: maven:3.9.9-eclipse-temurin-21

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

build:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the maven.graph.json artifacts.
  stage: build
  script:
    # Your regular build script
    - mvn install
    # New instruction to generate the dependency graph
    - mvn org.apache.maven.plugins:maven-dependency-plugin:3.8.1:tree -DoutputType=json -DoutputFile=maven.graph.json
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/*.jar"
      - "**/maven.graph.json"

pip

pipプロジェクトの場合、依存関係グラフエクスポートを作成するには、以下のいずれかの方法を使用します:

• pip-compile
• pipdeptree

pip-compile

この方法は、自動依存関係解決を駆動するpip-compileコマンドを使用します。これは、アナライザーが必要とするすべての情報（直接の依存関係や推移的な依存関係、依存関係パスを有効にするためのグラフ情報を含む）を含むrequirements.txtロックファイルを生成します。

pipプロジェクトでアナライザーを有効にするには:

1. Dependency-Scanning.v2 CI/CDテンプレートを追加します。
2. プロジェクトの既存のビルドジョブにpip-compileコマンドを追加するか、ビルドジョブが存在しない場合は専用のジョブを作成します。このジョブは、スキャン開始時にアーティファクトが利用可能になるように、dependency-scanningジョブの前に実行する必要があります。
3. requirements.txtをジョブアーティファクトとして宣言します。
4. 自動依存関係解決を無効にするには、pythonをDS_DISABLED_RESOLUTION_JOBS CI/CD変数またはdisabled_resolution_jobs入力値に追加します。

コマンドを既存のビルドジョブに追加することは、ビルドからのインストール済み依存関係を再利用するため、別のジョブで実行するよりも高速です。

例:

stages:
  - build
  - test

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

build:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the requirements.txt artifact.
  stage: build
  image: "python:latest"
  script:
    # Your regular build script
    - pip install pip-tools
    # New instruction to generate the dependency lockfile
    - pip-compile requirements.in
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/requirements.txt"

pipdeptree

この方法は、pipdeptree --jsonを使用して、アナライザーが必要とするすべての情報（直接の依存関係や推移的な依存関係、依存関係パスを有効にするためのグラフ情報を含む）を含むpipdeptree.jsonファイルを生成します。

pipプロジェクトでアナライザーを有効にするには:

1. Dependency-Scanning.v2 CI/CDテンプレートを追加します。
2. プロジェクトの既存のビルドジョブにpipdeptree --jsonコマンドを追加するか、ビルドジョブが存在しない場合は専用のジョブを作成します。このジョブは、スキャン開始時にアーティファクトが利用可能になるように、dependency-scanningジョブの前に実行する必要があります。
3. pipdeptree.jsonをジョブアーティファクトとして宣言します。
4. 自動依存関係解決を無効にするには、pythonをDS_DISABLED_RESOLUTION_JOBS CI/CD変数またはdisabled_resolution_jobs入力値に追加します。

コマンドを既存のビルドジョブに追加することは、ビルドからのインストール済み依存関係を再利用するため、別のジョブで実行するよりも高速です。

例:

stages:
  - build
  - test

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

build:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the pipdeptree.json artifact.
  stage: build
  image: "python:latest"
  script:
    # Your regular build script
    - pip install -r requirements.txt
    # New instructions to generate the dependency graph.
    # Exclude pipdeptree itself to avoid false positives.
    - pip install pipdeptree
    - pipdeptree -e pipdeptree --json > pipdeptree.json
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/pipdeptree.json"

既知の問題により、pipdeptreeはオプションの依存関係を親パッケージの依存関係としてマークしません。その結果、依存関係スキャンは、それらを推移的な依存関係としてではなく、プロジェクトの直接的な依存関係としてマークします。

Pipenv

この方法は、pipenv graphコマンドを使用して、アナライザーが必要とする情報（直接の依存関係や推移的な依存関係を含む）を含むpipenv.graph.jsonファイルを生成します。このファイルがない場合、アナライザーはPipfile.lockのみからコンポーネントを抽出しますが、依存関係パス情報は利用できません。

Pipenvプロジェクトでアナライザーを有効にするには:

1. Dependency-Scanning.v2 CI/CDテンプレートを追加します。
2. プロジェクトの既存のビルドジョブにpipenv graph --json-treeコマンドを追加するか、ビルドジョブが存在しない場合は専用のジョブを作成します。このジョブは、スキャン開始時にアーティファクトが利用可能になるように、dependency-scanningジョブの前に実行する必要があります。
3. pipenv.graph.jsonをジョブアーティファクトとして宣言します。

コマンドを既存のビルドジョブに追加することは、ビルドからのインストール済み依存関係を再利用するため、別のジョブで実行するよりも高速です。

例:

stages:
  - build
  - test

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

build:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the pipenv.graph.json artifact.
  stage: build
  image: "python:3.12"
  script:
    # Your regular build script
    - pip install pipenv
    - pipenv install
    # New instruction to generate the dependency graph
    - pipenv graph --json-tree > pipenv.graph.json
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/pipenv.graph.json"

sbt

この方法は、sbt-dependency-graphプラグインを使用して、アナライザーが必要とするすべての情報（直接の依存関係や推移的な依存関係を含む）を含むdependencies-compile.dotファイルを生成します。

sbtプロジェクトでアナライザーを有効にするには:

1. Dependency-Scanning.v2 CI/CDテンプレートを追加します。
2. sbt-dependency-graphプラグインを追加するためにplugins.sbtを編集します。
3. プロジェクトの既存のビルドジョブにsbt dependencyDotコマンドを追加するか、ビルドジョブが存在しない場合は専用のジョブを作成します。このジョブは、スキャン開始時にアーティファクトが利用可能になるように、dependency-scanningジョブの前に実行する必要があります。
4. dependencies-compile.dotをジョブアーティファクトとして宣言します。

コマンドを既存のビルドジョブに追加することは、ビルドからのsbtセッションおよび解決済み設定を再利用するため、別のジョブで実行するよりも高速です。

例:

stages:
  - build
  - test

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

build:
  # Running in the build stage ensures that the dependency-scanning job
  # receives the dependencies-compile.dot artifact.
  stage: build
  image: "sbtscala/scala-sbt:eclipse-temurin-17.0.13_11_1.10.7_3.6.3"
  script:
    # Your regular build script
    - sbt compile
    # New instruction to generate the dependency graph
    - sbt dependencyDot
  # Make the artifact available to the dependency-scanning job.
  artifacts:
    paths:
      - "**/dependencies-compile.dot"

マニフェストフォールバック

サポートされているロックファイルまたは依存関係グラフエクスポートが利用できない場合、依存関係スキャンアナライザーは、サポートされているマニフェストファイルから依存関係をフォールバックとして抽出できます。

次のマニフェストファイルがサポートされています:

マニフェストフォールバックを無効にする

マニフェストフォールバックを無効にするには、DS_ENABLE_MANIFEST_FALLBACK CI/CD変数またはenable_manifest_fallback入力を使用します。

variables:
  DS_ENABLE_MANIFEST_FALLBACK: "false"

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

アプリケーションのスキャン方法

SBOMを使用した依存関係スキャン機能は、静的到達可能性や脆弱性スキャンなどの他の分析から依存関係検出を分離する、分解された依存関係分析アプローチに依存しています。

この関心の分離とアーキテクチャのモジュール化により、対応言語の拡充、GitLabプラットフォーム内でのより緊密なインテグレーションとユーザー体験の向上、そして業界標準のレポート形式への移行を通じて、お客様へのサポートをより強化できます。

When 依存関係解決が有効になっている場合、解決ジョブはdependency-scanningジョブの前に.preパイプラインステージで実行されます。これらのジョブは、ロックファイルまたは依存関係グラフエクスポートをアーティファクトとして生成し、それをdependency-scanningジョブが消費します。

依存関係スキャンの全体的なフローを以下に示します。

flowchart TD
    subgraph CI[CI Pipeline]
        START([CI Job Starts])
        DETECT[Dependency Detection]
        SBOM_GEN[SBOM Reports Generation]
        SR[Static Reachability Analysis]
        UPLOAD[Upload SBOM Files]
        DL[Download Scan Results]
        REPORT[DS Security Report Generation]
        END([CI Job Complete])
    end

    subgraph GitLab[GitLab Instance]
        API[CI SBOM Scan API]
        SCANNER[GitLab SBOM Vulnerability Scanner]
        RESULTS[Scan Results]
    end

    START --> DETECT
    DETECT --> SBOM_GEN
    SBOM_GEN --> SR
    SR --> UPLOAD
    UPLOAD --> API
    API --> SCANNER
    SCANNER --> RESULTS
    RESULTS --> DL
    DL --> REPORT
    REPORT --> END

依存関係検出フェーズでは、アナライザーが利用可能なロックファイルを解析し、プロジェクトの依存関係とそれらの関係（依存関係グラフ）の包括的なインベントリをビルドします。このインベントリは、CycloneDX SBOM（ソフトウェア部品表）ドキュメントにキャプチャされます。

静的到達可能性フェーズでは、アナライザーはソースファイルを解析して、アクティブに使用されているSBOMコンポーネントを特定し、それに応じてSBOMファイルでマークします。これにより、ユーザーは、脆弱なコンポーネントが到達可能かどうかに基づいて、脆弱性の優先順位を付けることができます。詳細については、静的到達可能性ページを参照してください。

SBOMドキュメントは、依存関係スキャンSBOM APIを介してGitLabインスタンスに一時的にアップロードされます。GitLab SBOM脆弱性スキャナーエンジンは、SBOMコンポーネントをアドバイザリと照合して、依存関係スキャンレポートに含めるためにアナライザーに返される所見のリストを生成します。

APIは、認証にデフォルトのCI_JOB_TOKENを使用します。CI_JOB_TOKENの値を別のトークンで上書きすると、APIから403（Forbidden）エラーが返される可能性があります。

ユーザーは、次を使用して依存関係スキャンSBOM APIと通信するアナライザークライアントを構成できます:

• vulnerability_scan_api_timeoutまたはDS_API_TIMEOUT
• vulnerability_scan_api_download_delayまたはDS_API_SCAN_DOWNLOAD_DELAY

詳細については、利用可能なspec入力および利用可能なCI/CD変数を参照してください。

生成されたレポートは、 CIジョブの完了時、通常はパイプライン完了後にGitLabインスタンスにアップロードされ、処理されます。

SBOMレポートは、依存関係リスト 、ライセンススキャン 、継続的な脆弱性スキャンなど、他のSBOMベースの機能をサポートするために使用されます。

依存関係スキャンレポートは、セキュリティスキャン結果の一般的なプロセスに従います。

• 依存関係スキャンレポートがデフォルトブランチのCI/CDジョブによって宣言されている場合: 脆弱性が作成され、脆弱性レポートに表示されます。
• 依存関係スキャンレポートがデフォルト以外のブランチのCI/CDジョブによって宣言されている場合: セキュリティ所見が作成され、パイプラインビューのセキュリティタブとMRセキュリティウィジェットに表示されます。

オフライン環境

インターネット経由での外部リソースへのアクセスが制限、制限、または断続的な環境のインスタンスでは、依存関係スキャンジョブを正常に実行するためにいくつかの調整を行う必要があります。詳細については、オフライン環境を参照してください。

要件

オフライン環境で依存関係スキャンを実行するには、以下が必要です:

• dockerまたはkubernetesのexecutorを備えたGitLab Runner
• 依存関係スキャンアナライザーイメージのローカルコピー
• パッケージメタデータデータベースへのアクセス依存関係のライセンスとアドバイザリデータを取得する必要があります。

アナライザーイメージのローカルコピー

依存関係スキャンアナライザーを使用するには、以下の手順に従います:

1. registry.gitlab.comから現在のイメージをローカルDockerコンテナレジストリにインポートします。DockerイメージをローカルのオフラインDockerレジストリにインポートするプロセスは、ネットワークのセキュリティポリシーによって異なります。IT部門に相談して、外部リソースをインポートまたは一時的にアクセスするための承認済みプロセスを確認してください。これらのイメージは新機能、バグ修正、パッチで定期的に更新されるため、定期的にダウンロードすることをお勧めします。オフラインインスタンスがGitLabレジストリにアクセスできる場合は、Security-Binariesテンプレートを使用して、最新の依存関係スキャンアナライザーイメージをダウンロードできます。

2. ローカルアナライザーを使用するようにGitLab CI/CDを設定します。

   CI/CD変数SECURE_ANALYZERS_PREFIXまたはanalyzer_image_prefix spec入力の値をローカルDockerレジストリに設定します（この例では、docker-registry.example.com）。

   include:
     - template: Jobs/Dependency-Scanning.v2.gitlab-ci.yml
   
   variables:
     SECURE_ANALYZERS_PREFIX: "docker-registry.example.com/analyzers"

複数のプロジェクトでのスキャンの強制

セキュリティポリシーを使用して、複数のプロジェクトで依存関係スキャンを強制します。依存関係スキャンには、ロックファイルまたは依存関係グラフエクスポートのいずれかのスキャン可能なアーティファクトが必要です。スキャン可能なアーティファクトがプロジェクトのリポジトリにコミットされているかどうかによって、ポリシーの選択が決まります。

• スキャン可能なアーティファクトがリポジトリにコミットされている場合は、スキャン実行ポリシーを使用します。

  リポジトリにコミットされたスキャン可能なアーティファクトがあるプロジェクト、または依存関係解決によってサポートされているプロジェクトの場合、スキャン実行ポリシーは依存関係スキャンを強制する最も直接的な方法を提供します。

• スキャン可能なアーティファクトがリポジトリにコミットされておらず、依存関係解決によってサポートされていない場合は、パイプライン実行ポリシーを使用してください。

  スキャン可能なアーティファクトがリポジトリにコミットされていないプロジェクトの場合は、パイプライン実行ポリシーを使用する必要があります。このポリシーでは、依存関係スキャンを呼び出す前に、スキャン可能なアーティファクトを生成するためのカスタムCI/CDジョブを定義する必要があります。

  パイプライン実行ポリシーは、次のことを行う必要があります:

  • CI/CDパイプラインの一部としてロックファイルまたは依存関係グラフエクスポートを生成します。
  • 特定のプロジェクト要件に合わせて依存関係検出プロセスをカスタマイズします。
  • GradleやMavenなどのビルドツールに関する言語固有の指示を実装します。

次の例では、Gradle nebulaプラグインを使用してロックファイルを生成します。その他の言語については、ロックファイルまたは依存関係グラフエクスポートを手動で作成するを参照してください。

例: Gradleプロジェクトのパイプライン実行ポリシー

リポジトリにコミットされたスキャン可能なアーティファクトがないGradleプロジェクトの場合は、パイプライン実行ポリシーでアーティファクト生成ステップを定義する必要があります。次の例では、nebulaプラグインを使用しています。

1. 専用のセキュリティポリシープロジェクトで、メインポリシーファイル（例: policy.yml）を作成または更新します:

   pipeline_execution_policy:
   - name: Enforce Gradle dependency scanning with SBOM
     description: Generate dependency artifact and run dependency scanning.
     enabled: true
     pipeline_config_strategy: inject_policy
     content:
       include:
         - project: $SECURITY_POLICIES_PROJECT
           file: "dependency-scanning.yml"

2. dependency-scanning.ymlポリシーファイルを追加します:

   stages:
     - build
     - test
   
   include:
     - template: Jobs/Dependency-Scanning.v2.gitlab-ci.yml
   
   generate nebula lockfile:
     image: openjdk:11-jdk
     stage: build
     script:
       - |
         cat << EOF > nebula.gradle
         initscript {
             repositories {
               mavenCentral()
             }
             dependencies {
                 classpath 'com.netflix.nebula:gradle-dependency-lock-plugin:12.7.1'
             }
         }
   
         allprojects {
             apply plugin: nebula.plugin.dependencylock.DependencyLockPlugin
         }
         EOF
         ./gradlew --init-script nebula.gradle -PdependencyLock.includeTransitives=true -PdependencyLock.lockFile=dependencies.lock generateLock saveLock
         ./gradlew --init-script nebula.gradle -PdependencyLock.includeTransitives=false -PdependencyLock.lockFile=dependencies.direct.lock generateLock saveLock
     after_script:
       - find . -path '*/build/dependencies.lock' -print -delete
     artifacts:
       paths:
         - '**/dependencies.lock'
         - '**/dependencies.direct.lock'

このアプローチにより、次のことが保証されます:

1. Gradleプロジェクトで実行されるパイプラインによって、スキャン可能なアーティファクトが生成されること
2. 依存関係スキャンが確実に適用され、スキャン可能なアーティファクトへアクセスできること
3. ポリシーの適用範囲内にあるすべてのプロジェクトで、同一の依存関係スキャン方式が一貫して使用されること
4. 設定変更を一元管理し、複数のプロジェクトに横断的に適用できること

新しい依存関係スキャン機能を有効にするその他の方法

v2テンプレートを使用して、依存関係スキャン機能を有効にすることを強くお勧めします。これが不可能な場合は、次のいずれかの方法を選択できます:

latestテンプレートの使用

latest依存関係スキャンCI/CDテンプレートDependency-Scanning.latest.gitlab-ci.ymlを使用して、GitLab提供のアナライザーを有効にします。

• （非推奨の）Gemnasiumアナライザーがデフォルトで使用されます。

• 新しい依存関係スキャンアナライザーを有効にするには、CI/CD変数DS_ENFORCE_NEW_ANALYZERをtrueに設定します。

• サポートされているロックファイル、手動での依存関係グラフエクスポート 、またはトリガーファイルがリポジトリに存在して、パイプラインでdependency-scanningジョブを作成する必要があります。

  include:
    - template: Jobs/Dependency-Scanning.latest.gitlab-ci.yml
  
  variables:
    DS_ENFORCE_NEW_ANALYZER: 'true'

または、latestテンプレートでスキャン実行ポリシーを使用して機能を有効にし、CI/CD変数DS_ENFORCE_NEW_ANALYZERをtrueに設定して、新しい依存関係スキャンアナライザーを適用できます。

アナライザーの動作をカスタマイズする場合は、使用可能なCI/CD変数を使用してください。

latestテンプレートのトリガーファイル

トリガーファイルは、最新の依存関係スキャンCI/CDテンプレートを使用するときに、dependency-scanning CI/CDジョブを作成します。アナライザーはこれらのファイルをスキャンしません。トリガーファイルを使用して手動でロックファイルまたは依存関係グラフエクスポートを作成する場合、お使いのプロジェクトはサポートされます。

依存関係スキャンCI/CDコンポーネントの使用

依存関係スキャンCI/CDコンポーネントを使用して、新しい依存関係スキャンアナライザーを有効にします。このアプローチを選択する前に、GitLab Self-Managedインスタンスの現在の制限事項を確認してください。

include:
  - component: $CI_SERVER_FQDN/components/dependency-scanning/main@1

また、手動でロックファイルまたは依存関係グラフエクスポートを作成する必要があります。

依存関係スキャンCI/CDコンポーネントを使用する場合、アナライザーは入力を構成することでカスタマイズできます。

独自のSBOMの持ち込み

カスタムCIジョブで、サードパーティ製のCycloneDX SBOMジェネレーターまたはカスタムツールで生成された独自のCycloneDX SBOMドキュメントをCI/CDアーティファクトレポートとして使用します。

依存関係スキャンをSBOMを使用してアクティブ化するには、提供されているCycloneDX SBOMドキュメントが以下を満たしている必要があります:

• CycloneDX仕様バージョン1.4、1.5、または1.6に準拠している。CycloneDX Web Toolでオンラインバリデーターを利用できます。
• GitLab CycloneDXプロパティ分類に準拠している。
• 成功したCIジョブからCI/CDアーティファクトレポートとしてアップロードされる。