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

SBOMを使用する依存関係スキャンは、アプリケーションの依存関係を分析し、既知の脆弱性を検出します。すべての依存関係（推移的依存関係を含む）がスキャンされます。

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

依存関係スキャンは、アプリケーションのライフサイクルの開発フェーズで実行できます。パイプラインがSBOMレポートを生成するたびに、セキュリティ上のセキュリティアドバイザリーが識別され、ソースブランチとターゲットブランチ間で比較されます。調査結果とその重大度はマージリクエストにリスト表示されるため、コード変更がコミットされる前に、アプリケーションに対するリスクに事前に対処できます。レポートされたSBOMコンポーネントのセキュリティ上の調査結果は、新しいセキュリティアドバイザリーがリリースされたときに、CI/CDパイプラインとは独立して継続的な脆弱性スキャンによっても識別されます。

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

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

はじめに

前提要件:

• サポートされているロックファイルまたは依存関係グラフがリポジトリに存在するか、アーティファクトとしてdependency-scanningジョブに渡される必要があります。
• Self-Managed Runnerを使用する場合、dockerまたはkubernetes executorを備えたGitLab Runnerが必要です。
  • GitLab.comでSaaS Runnerを使用している場合、これはデフォルトで有効になっています。
• スキャン対象とするすべてのPURLタイプのパッケージメタデータを、GitLabインスタンスで同期する必要があります。GitLab.comおよびGitLab Dedicatedの場合、これは自動的に処理されます。

アナライザーを有効にする

アナライザーを有効にするには、次のいずれかのオプションを使用します:

• v2依存関係スキャンCI/CDテンプレートDependency-Scanning.v2.gitlab-ci.yml

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

• v2テンプレートを使用したセキュリティポリシー

言語固有の手順

プロジェクトに、サポートされているロックファイル依存関係グラフがコミットされていない場合は、いずれか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 Plugin
• GradleのHtmlDependencyReportTask

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

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

Gradleプロジェクトでアナライザーを有効にするには、次のようにします:

1. gradle-依存関係-lock-プラグインを使用するか、initスクリプトを使用するようにbuild.gradleまたはbuild.gradle.ktsを編集します。
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-依存関係-プラグインのバージョン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プロジェクトでアナライザーを有効にするには、次のようにします:

• sbt-依存関係-graphプラグインを使用するようにplugins.sbtを編集します。

次の例.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ドキュメントに対して、単一の依存関係スキャンレポートを生成します。

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@0

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

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

依存関係スキャンアナライザーは、スキャンされたすべてのロックファイルの脆弱性を含む単一の依存関係スキャンレポートを出力します。

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

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

最適化

要件に応じてSBOMを使用した依存関係スキャンを最適化するには、次のようにします:

• ファイルとディレクトリをスキャンから除外します。
• ファイルを検索する最大深度を定義します。

スキャンからファイルとディレクトリを除外する

スキャンのターゲットからファイルまたはディレクトリを除外するには、excluded_paths仕様入力またはコンマ区切りのパターンのリストを含むDS_EXCLUDED_PATHSを.gitlab-ci.ymlで使用します。

ファイルを検索する最大深度を定義する

アナライザーの動作を最適化するには、最大深度値を設定します。値が-1の場合、深さに関係なくすべてのディレクトリをスキャンします。デフォルトは2です。これを行うには、max_scan_depth仕様入力またはDS_MAX_DEPTHCI/CD変数を.gitlab-ci.ymlで使用します。

ロールアウトする

単一のプロジェクトでSBOMを使用する依存関係スキャンの結果に確信が持てたら、その実装を他のプロジェクトに拡張できます:

• スキャン実行の強制を使用して、グループ全体にSBOM設定で依存関係スキャンを適用します。
• 固有の要件がある場合、SBOMを使用する依存関係スキャンはオフライン環境で実行できます。

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

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

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

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

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

パッケージハッシュ情報

依存関係スキャン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テンプレートを使用した動作のカスタマイズ

利用可能な仕様入力

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

利用可能なCI/CD変数

これらの変数は、仕様入力をオーバーライドでき、ベータ版のlatestテンプレートとも互換性があります。

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

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（禁止）応答が発生する可能性があります。

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

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

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

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

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

依存関係スキャンレポートは、security scanning resultsの一般的なプロセスに従います

• 依存関係スキャンレポートがデフォルトブランチのCI/CDジョブによって宣言されている場合、脆弱性が作成され、vulnerability reportに表示されます。
• 依存関係スキャンレポートがデフォルト以外のブランチのCI/CDジョブによって宣言されている場合、セキュリティ調査結果が作成され、pipeline viewおよびMRセキュリティウィジェットのセキュリティタブに表示されます。

オフラインサポート

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

要件

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

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

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

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

1. registry.gitlab.comから、次のデフォルトの依存関係スキャンアナライザーイメージをローカルのDockerコンテナレジストリにインポートします:

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

   DockerイメージをローカルのオフラインDockerレジストリにインポートするプロセスは、your network security policy（ネットワークのセキュリティポリシー）によって異なります。IT部門に相談して、外部リソースをインポートまたは一時的にアクセスするための承認済みプロセスを確認してください。これらのスキャナーは新しい定義で定期的に更新されるため、定期的にダウンロードすることをおすすめします。オフラインインスタンスがGitLabレジストリにアクセスできる場合は、セキュリティバイナリテンプレートを使用して、最新の依存関係スキャンアナライザーイメージをダウンロードできます。

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

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

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

セキュリティポリシー

セキュリティポリシーを使用して、複数のプロジェクトにわたって依存関係スキャンを適用します。適切なポリシータイプは、プロジェクトにスキャン可能なアーティファクトがリポジトリにコミットされているかどうかによって異なります。

スキャン実行ポリシー

スキャン実行ポリシーは、スキャン可能なアーティファクトがリポジトリにコミットされているすべてのプロジェクトでサポートされています。これらのアーティファクトには、ロックファイル、依存関係グラフファイル、および依存関係を識別するために直接分析できるその他のファイルが含まれます。

これらのアーティファクトを使用するプロジェクトの場合、スキャン実行ポリシーは、依存関係スキャンを適用するための最も高速で簡単な方法を提供します。

パイプライン実行ポリシー

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

パイプライン実行ポリシー:

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

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

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

専用のセキュリティポリシープロジェクトで、メインポリシーファイルを作成または更新します（例：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"

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テンプレートでScan Execution Policiesを使用して機能を有効にし、CI/CD変数DS_ENFORCE_NEW_ANALYZERをtrueに設定して、新しい依存関係スキャンアナライザーを適用できます。

必ず言語固有の手順に従ってください。アナライザーの動作をカスタマイズする場合は、使用可能なCI/CD変数を使用してください

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

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

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

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

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

必ず言語固有の手順に従ってください。

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

独自のSBOMを持ち込む

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

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

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

トラブルシューティング

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

警告: grep: command not found

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

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

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

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

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

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