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の場合、この設定はデフォルトで有効になっています。
• Self-ManagedインスタンスのGitLabのみの追加前提条件:

  • スキャンされるすべてのPURLタイプのパッケージメタデータは、GitLabインスタンスで同期されている必要があります。

    GitLabインスタンスでこのデータが利用できない場合、依存関係スキャンで脆弱性を特定できません。

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

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

2. コード > リポジトリを選択します。

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

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

5. v2依存関係スキャンCI/CDテンプレートを追加します:

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

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

ロックファイルまたは依存関係グラフを作成する

プロジェクトにサポートされているロックファイルまたはリポジトリにコミットされた依存関係グラフがない場合は、1つ指定する必要があります。

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

Go

プロジェクトがgo.modファイルのみを提供する場合でも、依存関係スキャンアナライザーはコンポーネントのリストを抽出できます。ただし、依存関係パス情報は利用できません。さらに、同じモジュールの複数のバージョンがある場合は、誤検出が発生する可能性があります。

コンポーネントの検出と機能のカバレッジを向上させるには、Goツールチェーンからgo mod graphコマンドを使用して生成されたgo.graphファイルを提供する必要があります。

以下の例.gitlab-ci.ymlは、Goプロジェクトで依存関係パスのサポートを使用してアナライザーを有効にする方法を示しています。依存関係グラフは、依存関係スキャンの実行前に、buildステージでジョブアーティファクトとして出力されます。

stages:
  - build
  - test

include:
  - template: Jobs/Dependency-Scanning.v2.gitlab-ci.yml
go:build:
  stage: build
  image: "golang:latest"
  script:
    - "go mod tidy"
    - "go build ./..."
    - "go mod graph > go.graph"
  artifacts:
    when: on_success
    access: developer
    paths: ["**/go.graph"]

Gradle

Gradleプロジェクトの場合は、次のいずれかの方法を使用して依存関係グラフを作成します。

• Nebula Gradle Dependency Lockプラグイン
• GradleのHtmlDependencyReportTask

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

この方法では、直接的な依存関係に関する情報が提供されます。

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

1. build.gradleまたはbuild.gradle.ktsを編集して、gradle-dependency-lock-pluginを使用するか、初期化スクリプトを使用します。
2. .gitlab-ci.ymlファイルを構成してdependencies.lockおよびdependencies.direct.lockアーティファクトを生成し、それらをdependency-scanningジョブに渡します。

次の例は、Gradleプロジェクトのアナライザーを構成する方法を示しています。

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 lock file 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
      # lock files in the build/ directory only.
  after_script:
    - find . -path '*/build/dependencies*.lock' -print -delete
  # Collect all generated artifacts and pass them onto jobs in sequential stages.
  artifacts:
    paths:
      - '**/dependencies*.lock'

HtmlDependencyReportTask

この方法では、推移的および直接的な依存関係に関する情報が提供されます。

HtmlDependencyReportTaskは、Gradleプロジェクトの依存関係のリストを取得する別の方法です（gradleバージョン4～8でテスト済み）。依存関係スキャンでこの方法を使用できるようにするには、gradle htmlDependencyReportタスクの実行からのアーティファクトを使用可能にする必要があります。

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)
  # Pass html report artifact to subsequent dependency scanning stage.
  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

次の例.gitlab-ci.ymlは、Mavenプロジェクトでアナライザーを有効にする方法を示しています。依存関係グラフは、依存関係スキャンの実行前に、buildステージでジョブアーティファクトとして出力されます。

要件: maven-dependency-pluginは、少なくともバージョン3.7.0以上を使用してください。

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:
    - mvn install
    - mvn org.apache.maven.plugins:maven-dependency-plugin:3.8.1:tree -DoutputType=json -DoutputFile=maven.graph.json
  # Collect all maven.graph.json artifacts and pass them onto jobs
  # in sequential stages.
  artifacts:
    paths:
      - "**/*.jar"
      - "**/maven.graph.json"

pip

プロジェクトがpip-compileコマンドラインツールによって生成されたrequirements.txtロックファイルを提供する場合、依存関係スキャンアナライザーは、コンポーネントのリストと依存関係グラフ情報を抽出でき、依存関係パス機能をサポートします。

または、プロジェクトは、pipdeptree --jsonコマンドラインユーティリティによって生成されたpipdeptree.json依存関係グラフエクスポートを提供できます。

以下の例.gitlab-ci.ymlは、pipプロジェクトで依存関係パスのサポートを使用してアナライザーを有効にする方法を示しています。buildステージは、依存関係スキャンの実行前に、ジョブアーティファクトとして依存関係グラフを出力します。

stages:
  - build
  - test

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

build:
  stage: build
  image: "python:latest"
  script:
    - "pip install -r requirements.txt"
    - "pip install pipdeptree"
    # Run pipdeptree to get project's dependencies and exclude pipdeptree itself to avoid false positives
    - "pipdeptree -e pipdeptree --json > pipdeptree.json"
  artifacts:
    when: on_success
    access: developer
    paths: ["**/pipdeptree.json"]

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

Pipenv

プロジェクトがPipfile.lockファイルのみを提供する場合でも、依存関係スキャンアナライザーはコンポーネントのリストを抽出できます。ただし、依存関係パス情報は利用できません。

機能カバレッジを向上させるには、pipenv graphコマンドによって生成されたpipenv.graph.jsonファイルを提供する必要があります。

次の例.gitlab-ci.ymlは、Pipenvプロジェクトで依存関係パスのサポートを使用してアナライザーを有効にする方法を示しています。buildステージは、依存関係スキャンの実行前に、ジョブアーティファクトとして依存関係グラフを出力します。

stages:
  - build
  - test

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

build:
  stage: build
  image: "python:3.12"
  script:
    - "pip install pipenv"
    - "pipenv install"
    - "pipenv graph --json-tree > pipenv.graph.json"
  artifacts:
    when: on_success
    access: developer
    paths: ["**/pipenv.graph.json"]

sbt

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

• plugins.sbtを編集して、sbt-dependency-graphプラグインを使用します。

次の例.gitlab-ci.ymlは、sbtプロジェクトで依存関係パスのサポートを使用してアナライザーを有効にする方法を示しています。buildステージは、依存関係スキャンの実行前に、ジョブアーティファクトとして依存関係グラフを出力します。

stages:
  - build
  - test

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

build:
  stage: build
  image: "sbtscala/scala-sbt:eclipse-temurin-17.0.13_11_1.10.7_3.6.3"
  script:
    - "sbt dependencyDot"
  artifacts:
    when: on_success
    access: developer
    paths: ["**/dependencies-compile.dot"]

結果について理解する

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

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

CycloneDXソフトウェア部品表

依存関係スキャンアナライザーは、検出されたサポートされているロックファイルまたは依存関係グラフエクスポートごとに、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をマージする

CI/CDジョブを使用して、複数のCycloneDX SBOMを単一のSBOMにマージできます。

たとえば、次の.gitlab-ci.ymlの抜粋は、複数のCyclone SBOMファイルをマージし、結果として生成されるファイルを検証する方法を示しています。

stages:
  - test
  - merge-cyclonedx-sboms

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

merge cyclonedx sboms:
  stage: merge-cyclonedx-sboms
  image:
    name: cyclonedx/cyclonedx-cli:0.27.1
    entrypoint: [""]
  script:
    - find . -name "gl-sbom-*.cdx.json" -exec cyclonedx merge --output-file gl-sbom-all.cdx.json --input-files "{}" +
    # optional: validate the merged sbom
    - cyclonedx validate --input-version v1_6 --input-file gl-sbom-all.cdx.json
  artifacts:
    paths:
      - gl-sbom-all.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テンプレートとも互換性があります。

カスタム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-----

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

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

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

マニフェストフォールバックを有効にするには、DS_ENABLE_MANIFEST_FALLBACKCI/CD変数を"true"に設定します。

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

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

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

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

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コンテナレジストリにインポートします:

   registry.gitlab.com/security-products/dependency-scanning:1

   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アーティファクトレポートとしてアップロードされる。

トラブルシューティング

依存関係スキャンを使用する際に、次のイシューが発生する可能性があります。

カスタム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エンドポイントに対してきめ細かいジョブ権限をサポートしていませんが、イシュー578850でこの機能の追加が提案されています。

警告: grep: command not found

アナライザーイメージには、イメージのアタックサーフェスを小さくするために、最小限の依存関係が含まれています。その結果、grepのような他のイメージで一般的に見られるユーティリティがイメージから欠落しています。これにより、ジョブログに/usr/bin/bash: line 3: grep: command not foundのような警告が表示される場合があります。この警告は、アナライザーの結果には影響せず、無視できます。

コンプライアンスフレームワークの互換性

GitLab Self-ManagedインスタンスでSBOMベースの依存関係スキャンを使用する場合、コンプライアンスフレームワークとの互換性について考慮事項があります:

• GitLab.com（SaaS）: 「依存関係スキャンの実行」コンプライアンスコントロールは、SBOMベースの依存関係スキャンで正しく機能します。
• 18.4以降のGitLab Self-Managedインスタンス: 従来のgl-dependency-scanning-report.jsonアーティファクトが生成されないため、「依存関係スキャンの実行」コンプライアンスコントロールは、SBOMベースの依存関係スキャン（DS_ENFORCE_NEW_ANALYZER: 'true'）を使用すると失敗する可能性があります。

Self-Managedインスタンスの回避策: 「依存関係スキャンの実行」コントロールを必要とするコンプライアンスフレームワークチェックに合格する必要がある場合は、v2テンプレート（Jobs/Dependency-Scanning.v2.gitlab-ci.yml）を使用できます。これにより、SBOMと依存関係スキャンレポートの両方が生成されます。

コンプライアンスコントロールの詳細については、GitLabのコンプライアンスコントロールを参照してください。

エラー: 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"