パイプラインシークレット検出

パイプラインシークレット検出は、ファイルがGitリポジトリにコミットされ、GitLabにプッシュされた後、ファイルをスキャンします。

パイプラインシークレット検出を有効にすると、secret_detectionという名前のCI/CDジョブでスキャンが実行されます。スキャンを実行して、任意のGitLabプランでパイプラインシークレット検出のJSONレポートアーティファクトを表示できます。

GitLab Ultimateでは、パイプラインシークレット検出の結果も処理されるため、次のことが可能です:

• マージリクエストウィジェット 、パイプラインセキュリティレポート 、および脆弱性レポートで結果を確認する。
• 承認ワークフローで結果を使用する。
• セキュリティダッシュボードで結果を確認する。
• パブリックリポジトリ内のリークに自動的に対応する。
• セキュリティポリシーを使用して、プロジェクト全体で一貫したシークレット検出ルールを適用する。

このパイプラインシークレット検出ドキュメントのインタラクティブな読み取りおよびハウツーデモについては、以下をご覧ください:

• How to enable secret detection in GitLab Application Security Part 1/2（GitLabアプリケーションセキュリティでシークレット検出を有効にする方法: パート1/2）
• How to enable secret detection in GitLab Application Security Part 2/2（GitLabアプリケーションセキュリティでシークレット検出を有効にする方法: パート2/2）

その他のインタラクティブな読み取りおよびハウツーデモについては、Get Started With GitLab Application Security Playlist（GitLabアプリケーションセキュリティ入門プレイリスト）をご覧ください。

可用性

GitLabプランごとに、利用できる機能が異なります。

はじめに

パイプラインシークレット検出の使用を開始するには、パイロットプロジェクトを選択してアナライザーを有効にします。

前提要件:

• dockerまたはkubernetes executorを備えたLinuxベースのRunnerが必要です。GitLab.comのためにホスティングされたRunnerを使用している場合は、デフォルトで有効になっています。
  • Windows Runnerはサポートされていません。
  • amd64以外のCPUアーキテクチャはサポートされていません。
• testステージが含まれた.gitlab-ci.ymlファイルが必要です。

シークレット検出アナライザーを有効にするには、次のいずれかの方法を使用します:

• .gitlab-ci.ymlファイルを手動で編集します。CI/CDの設定が複雑な場合は、この方法を使用します。
• 自動的に設定されたマージリクエストを使用します。CI/CD設定がない場合、または設定が最小限である場合は、この方法を使用します。
• スキャン実行ポリシーでパイプラインシークレット検出を有効にします。

プロジェクトでシークレット検出スキャンを初めて実行する場合は、アナライザーを有効にした後、直ちに履歴スキャンを実行する必要があります。

パイプラインシークレット検出を有効にした後、アナライザーの設定をカスタマイズできます。

.gitlab-ci.ymlファイルを手動で編集する

この方法では、既存の.gitlab-ci.ymlファイルを手動で編集する必要があります。

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。

2. ビルド > パイプラインエディタを選択します。

3. 次の内容をコピーして、.gitlab-ci.ymlファイルの末尾に貼り付けます:

   include:
     - template: Jobs/Secret-Detection.gitlab-ci.yml

4. 検証タブを選択し、パイプラインの検証を選択します。メッセージシミュレーションが正常に完了しましたは、ファイルが有効であることを示しています。

5. 編集タブを選択します。

6. オプション。コミットメッセージテキストボックスで、コミットメッセージをカスタマイズします。

7. ブランチテキストボックスに、デフォルトブランチの名前を入力します。

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

これで、パイプラインにパイプラインシークレット検出ジョブが含まれるようになります。アナライザーを有効にした後で履歴スキャンを実行することを検討してください。

自動的に設定されたマージリクエストを使用する

このメソッドは、、マージリクエストを自動的に準備して、パイプラインシークレット検出テンプレートが含まれた.gitlab-ci.ymlファイルを追加します。マージリクエストをマージして、パイプラインシークレット検出を有効にします。

パイプラインシークレット検出を有効にするには、次の手順に従います:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. セキュリティ > セキュリティ設定を選択します。
3. パイプラインのシークレット検出行で、マージリクエスト経由で設定を選択します。
4. オプション。フィールドに入力します。
5. マージリクエストを作成を選択します。
6. マージリクエストをレビューしてマージします。

これで、パイプラインにパイプラインシークレット検出ジョブが含まれるようになります。

カバレッジ

パイプラインシークレット検出は、カバレッジと実行時間のバランスを取るように最適化されています。シークレットがないかスキャンされるのは、リポジトリの現在の状態と将来のコミットのみです。リポジトリの履歴にすでに存在するシークレットを特定するには、パイプラインシークレット検出を有効にした後、履歴スキャンを1回実行します。スキャン結果は、パイプラインが完了した後にのみ利用可能です。

シークレットについてスキャンされる内容は、パイプラインの種類と、設定が追加されているかどうかによって異なります。

デフォルトでは、パイプラインを実行すると、次のようになります:

• ブランチの場合:
  • デフォルトブランチでは、Gitワークツリーがスキャンされます。つまり、現在のリポジトリの状態が、通常のディレクトリであるかのようにスキャンされます。
  • new, non-default branch（新しいデフォルト以外のブランチ）では、親ブランチの直近のコミットから最新のコミットに至るまでのすべてのコミットの内容がスキャンされます。
  • existing, non-default branch（既存のデフォルト以外のブランチ）では、最後にプッシュされたコミットから最新のコミットに至るまでのすべてのコミットの内容がスキャンされます。
• マージリクエストでは、ブランチ上のすべてのコミットの内容がスキャンされます。アナライザーがすべてのコミットにアクセスできない場合、親から最新のコミットに至るまでのすべてのコミットの内容がスキャンされます。すべてのコミットをスキャンするには、マージリクエストパイプラインを有効にする必要があります。

デフォルトの動作をオーバーライドするには、利用可能なCI/CD変数を使用します。

アナライザーがコミットをフェッチする方法

デフォルトでは、GitLabが最初にリポジトリをクローンすると、最新のコミット（「シャロークローン」）のみをフェッチします。この初期クローンを超えて追加のコミットが必要な場合、アナライザーは最適化された戦略を使用して、それらを自動的にフェッチします:

• マージリクエストの場合、アナライザーはマージベースの後にコミットされた変更のみを取得ため、データ転送を最小限に抑えます。
• --sinceや--max-countなどのログオプションが指定されている場合、アナライザーは必要なコミットのみをフェッチします。
• 履歴スキャン中、アナライザーはリポジトリの完全な履歴をフェッチします。リポジトリがシャロークローンされた場合、アナライザーは--unshallowオプションを使用します。

アナライザーが必要なコミットをフェッチできない場合、利用可能なデータのスキャンにフォールバックします:

• 強制プッシュ後、アナライザーはリポジトリの現在の状態のみをスキャンします。
• ネットワーク障害が発生した場合、アナライザーは初期クローン後に利用可能なコミットをスキャンします。
• タイムアウトが発生した場合、アナライザーは部分的なコミットの履歴を使用してスキャンを続行します。

これらのフォールバックにより、制限された環境でもパイプラインが正常に完了します。

初期リポジトリクローン深度

RunnerのGIT_DEPTHは、最初にクローンされるコミット数を制御します。パイプラインシークレット検出は必要に応じて追加のコミットを自動的にフェッチするため、通常、この設定を調整する必要はありません。

制限されたネットワーク環境でコミットの欠落に関する問題が解決しない場合は、トラブルシューティングの回避策を参照してください。

履歴スキャンを実行する

デフォルトでは、パイプラインシークレット検出は、Gitリポジトリの現在の状態のみをスキャンします。リポジトリの履歴に含まれるシークレットは検出されません。Gitリポジトリで全コミットとブランチのシークレットをチェックするには、履歴スキャンを実行します。

履歴スキャンは、パイプラインシークレット検出を有効にした後、1回だけ実行する必要があります。履歴スキャンには、特に長いGit履歴がある大規模なリポジトリの場合、長時間がかかることがあります。最初の履歴スキャンが完了したら、パイプラインの一部として標準のパイプラインシークレット検出のみを使用します。

スキャン実行ポリシーでパイプラインシークレット検出を有効にすると、デフォルトでは、最初にスケジュールされるスキャンは履歴スキャンになります。

履歴スキャンを実行するには、次の手順に従います:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. ビルド > パイプラインを選択します。
3. 新しいパイプラインを選択します。
4. CI/CD変数を追加します:
   1. ドロップダウンリストから変数を選択します。
   2. 変数キーを入力ボックスに、SECRET_DETECTION_HISTORIC_SCANと入力します。
   3. 変数値を入力ボックスに、trueと入力します。
5. 新しいパイプラインを選択します。

重複する脆弱性の追跡

シークレット検出は、高度な脆弱性追跡アルゴリズムを使用して、ファイルがリファクタリングされたり、移動したりしたときに、発見と脆弱性が重複して作成されるのを防ぎます。

次の場合、新しい発見は作成されません:

• ファイル内でシークレットが移動した場合。
• ファイル内に重複するシークレットが表示される場合。

重複する脆弱性の追跡は、ファイルごとに行われます。同じシークレットが2つの異なるファイルに表示される場合、2つの発見が作成されます。

詳細については、機密プロジェクトhttps://gitlab.com/gitlab-org/security-products/post-analyzers/tracking-calculatorを参照してください。このプロジェクトは、GitLabチームメンバーのみが利用できます。

サポートされていないワークフロー

重複した脆弱性の追跡は、以下の場合、ワークフローをサポートしません:

• 既存の発見に追跡署名がなく、新しい発見と同じ場所を共有していない。

• 特定のシークレットは、シークレット値全体ではなく、プレフィックスを検索することで検出されます。これらのシークレットタイプでは、同じファイル内にある同じタイプの検出すべてが、単一の発見としてレポートされます。

  たとえば、SSH秘密キーは、プレフィックス-----BEGIN OPENSSH PRIVATE KEY-----によって検出されます。同じファイルに複数のSSH秘密キーがある場合、パイプラインシークレット検出は1つの発見のみを作成します。

• 履歴スキャンを実行している場合、または既存のコミットでパイプラインシークレット検出を有効にしている場合、1つのコミットでシークレットが導入され、同じスキャン中に以降のコミットで変更された場合、最新のシークレット値のみが脆弱性レポートに表示されます。

検出されたシークレット

パイプラインシークレット検出は、リポジトリのコンテンツを特定のパターンでスキャンします。各パターンは特定のタイプのシークレットに一致し、TOML構文を使用してルールで指定されます。GitLabは、デフォルトのルールセットを管理しています。

GitLab Ultimateを使用すると、これらのルールをニーズに合わせて拡張できます。たとえば、カスタムプレフィックスを使用するパーソナルアクセストークンはデフォルトでは検出されませんが、ルールをカスタマイズして、これらのトークンを識別できます。詳細については、アナライザールールセットをカスタマイズするをご覧ください。

パイプラインシークレット検出によって検出されるシークレットを確認するには、検出されたシークレットをご覧ください。パイプラインシークレット検出は、信頼性の高い結果を提供するために、URLなどの特定のコンテキストで、パスワードやその他の非構造化シークレットのみを検索します。

シークレットが検出されると、そのシークレットに対して脆弱性が作成されます。スキャンされたファイルからシークレットが削除され、パイプラインシークレット検出が再度実行された場合でも、脆弱性は「検出されたまま」になります。これは、流出したシークレットは、失効するまでセキュリティ上のリスクであり続けるためです。削除されたシークレットもGit履歴に残り続けます。Gitリポジトリの履歴からシークレットを削除するには、リポジトリからテキストを削除するをご覧ください。

除外されたアイテム

パフォーマンスの向上のために、パイプラインシークレット検出は、シークレットが含まれる可能性が低い特定のファイルタイプとディレクトリを自動的に除外します。

次のアイテムは除外されます:

シークレット検出の結果

パイプラインシークレット検出は、ファイルgl-secret-detection-report.jsonをジョブアーティファクトとして出力します。ファイルには、検出されたシークレットが含まれています。ファイルをダウンロードして、GitLabの外部で処理できます。

詳細については、レポートファイルスキーマとレポートファイルの例を参照してください。

追加の出力

ジョブの結果は、以下でもレポートされます:

• マージリクエストウィジェット: マージリクエストに取り込まれた新しい発見を表示します。
• パイプラインセキュリティレポート: 最新のパイプライン実行から得られたすべての発見を表示します。
• 脆弱性レポート: すべてのセキュリティ検出の一元管理を提供します。
• セキュリティダッシュボード: プロジェクトとグループのすべての脆弱性を組織全体が把握できるようにします。

結果について理解する

パイプラインシークレット検出は、リポジトリで見つかった潜在的なシークレットに関する詳細情報を提供します。各シークレットには、流出したシークレットのタイプと修正のガイドラインが含まれています。

結果をレビューするときは、次の手順に従います:

1. 周囲のコードを調べて、検出されたパターンが実際にシークレットであるかどうかを判断します。
2. 検出された値が有効な認証情報であるかどうかをテストします。
3. リポジトリの表示レベルとシークレットのスコープについて検討します。
4. アクティブな権限の高いシークレットに最初に対処します。

一般的な検出カテゴリ

パイプラインシークレット検出による検出は、多くの場合、次の3つのカテゴリに分類されます:

• True positives（真陽性）: ローテーションして削除する必要がある正当なシークレット。例は次のとおりです:
  • アクティブなAPIキー、データベースパスワード、認証トークン
  • 秘密キーと証明書
  • サービスアカウントの認証情報
• False positives（誤検出）: 実際のシークレットではない、検出されたパターン。例は次のとおりです:
  • ドキュメント内のサンプル値
  • テストデータまたはモック認証情報
  • プレースホルダー値が含まれた設定テンプレート
• Historical findings（過去の発見）: 以前にコミット済みであるが、アクティブではない可能性のあるシークレット。これらの検出には、以下が必要です:
  • 調査して現在の状態を判定する必要があります
  • 念のため、ローテーションする必要があります

流出したシークレットを修正する

シークレットが検出された場合は、直ちにローテーションする必要があります。GitLabは、一部のタイプの流出したシークレットを自動的に失効しようとします。自動的に失効しないものについては、手動で失効させる必要があります。

リポジトリの履歴からシークレットをパージするだけでは、流出に完全に対応できません。元のシークレットは、リポジトリの既存のフォークまたは複製に残ります。

流出したシークレットに対応する方法の手順については、脆弱性レポートで脆弱性を選択してください。

最適化

組織全体にパイプラインシークレット検出をデプロイする前に、設定を最適化して誤検出を減らし、特定の環境の精度を向上させます。

誤検出は、アラート疲れを引き起こし、ツールに対する信頼を低下させる可能性があります。次のようなカスタムルールセット設定（Ultimateのみ）の使用を検討してください:

• コードベースに固有の既知の安全なパターンを除外します。
• シークレット以外で頻繁にトリガーされるルールの感度を調整します。
• 組織固有のシークレット形式のカスタムルールを追加します。

大規模なリポジトリ、または多数のプロジェクトがある組織でパフォーマンスを最適化するには、以下をレビューしてください:

• スキャンスコープの管理:
  • プロジェクトで履歴スキャンを実行した後、履歴スキャンをオフにします。
  • 使用率の低い期間中に履歴スキャンを行うようにスケジュールします。
• リソースの割り当て:
  • より大きなリポジトリに対して十分なRunnerリソースを割り当てます。
  • セキュリティスキャンのワークロードに対して専用のRunnerを使用することを検討してください。
  • スキャンの期間をモニタリングし、リポジトリのサイズに基づいて最適化します。

最適化の変更をテストする

組織全体に最適化を適用する前に、以下を実行します:

1. 最適化が正当なシークレットを見逃していないことを検証します。
2. 誤検出の削減とスキャンパフォーマンスの向上を追跡します。
3. 効果的な最適化パターンのレコードを維持します。

ロールアウトする

パイプラインシークレット検出を段階的に実装する必要があります。組織全体に機能をロールアウトする前に、小規模なパイロットから始めて、ツールの動作を理解してください。

パイプラインシークレット検出をロールアウトするときは、次のガイドラインに従ってください:

1. パイロットプロジェクトを選択します。適切なプロジェクトは、以下を備えています:
   • コミットが定期的に行われるアクティブな開発。
   • 管理可能なコードベースサイズ。
   • GitLab CI/CDに精通しているチーム。
   • 設定でイテレーションを行う意欲。
2. 簡単なことから始めます。パイロットプロジェクトのデフォルトの設定でパイプラインシークレット検出を有効にします。
3. 結果をモニタリングします。1～2週間アナライザーを実行して、一般的な発見について理解します。
4. 検出されたシークレットに対処します。見つかった正当なシークレットを修正します。
5. 設定を調整します。初期結果に基づいて設定を調整します。
6. 実装を文書化します。一般的な誤検出と修正パターンを記録します。

FIPS対応イメージ

デフォルトのスキャナーイメージは、サイズと保守性の観点からベースのAlpineイメージから構築されています。GitLabは、FIPS対応イメージのRed Hat UBIバージョンを提供しています。

FIPS対応イメージを使用するには、次のいずれかを実行します:

• SECRET_DETECTION_IMAGE_SUFFIX CI/CD変数を-fipsに設定します。
• デフォルトのイメージ名に-fips拡張子を追加します。

例は次のとおりです:

variables:
  SECRET_DETECTION_IMAGE_SUFFIX: '-fips'

include:
  - template: Jobs/Secret-Detection.gitlab-ci.yml

トラブルシューティング

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

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

警告: gl-secret-detection-report.json: no matching files

この警告に関する情報については、アプリケーションセキュリティの一般的なトラブルシューティングのセクションを参照してください。

エラー: Couldn't run the gitleaks command: exit status 2

このエラーは、アナライザーが必要なコミットにアクセスできないことを示しています。アナライザーはほとんどの場合、欠落しているコミットを自動的にフェッチしますが、制限された環境では問題が発生する可能性があります。

問題を診断するには、デバッグレベルのログを有効にして、以下を探します:

ERRO[2020-11-18T18:05:52Z] object not found
[ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Couldn't run the gitleaks command: exit status 2
[ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Gitleaks analysis failed: exit status 2

この問題を解決するには、以下を実行します:

• ほとんどの場合、アクションは必要ありません。アナライザーにフェッチを自動的に処理させます。

• 制限されたネットワークの場合は、初期クローン深度を大きくします:

  secret_detection:
    variables:
      GIT_DEPTH: 100  # or 0 to clone everything

• 大規模なリポジトリの場合は、スキャンのスコープを制限します:

  secret_detection:
    variables:
      SECRET_DETECTION_LOG_OPTIONS: "--max-count=50"

エラー: ERR fatal: ambiguous argument

リポジトリのデフォルトブランチが、ジョブがトリガーされた対象のブランチと無関係である場合、パイプラインシークレット検出がERR fatal: ambiguous argumentエラーで失敗する可能性があります。詳細については、イシュー!352014を参照してください。

問題を解決するには、リポジトリでデフォルトブランチを正しく設定してください。これは、secret-detectionジョブを実行するブランチと関連する履歴を持つブランチに設定する必要があります。

ジョブログのexec /bin/sh: exec format errorメッセージ

GitLabパイプラインシークレット検出アナライザーは、amd64 CPUアーキテクチャでの実行のみをサポートしています。このメッセージは、ジョブがarmなどの異なるアーキテクチャで実行されていることを示しています。

エラー: fatal: detected dubious ownership in repository at '/builds/<project dir>'

シークレット検出が終了ステータス128で失敗する場合があります。これは、Dockerイメージのユーザーへの変更が原因である可能性があります。

例は次のとおりです:

$ /analyzer run
[INFO] [secrets] [2024-06-06T07:28:13Z] ▶ GitLab secrets analyzer v6.0.1
[INFO] [secrets] [2024-06-06T07:28:13Z] ▶ Detecting project
[INFO] [secrets] [2024-06-06T07:28:13Z] ▶ Analyzer will attempt to analyze all projects in the repository
[INFO] [secrets] [2024-06-06T07:28:13Z] ▶ Loading ruleset for /builds....
[WARN] [secrets] [2024-06-06T07:28:13Z] ▶ /builds/....secret-detection-ruleset.toml not found, ruleset support will be disabled.
[INFO] [secrets] [2024-06-06T07:28:13Z] ▶ Running analyzer
[FATA] [secrets] [2024-06-06T07:28:13Z] ▶ get commit count: exit status 128

この問題を回避するには、次のようにbefore_scriptを追加します:

before_script:
    - git config --global --add safe.directory "$CI_PROJECT_DIR"

この問題の詳細については、イシュー465974をご覧ください。

GIT_DEPTHを調整しても、スキャンされる内容は変わりません

これは予期される動作です。GIT_DEPTHは、初期クローンのRunner変数です。アナライザーの動作は変わりません。

シークレット検出は、以下に基づいてスキャン対象を決定します:

• パイプラインの種類（プッシュ、マージリクエスト、スケジュール）
• ブランチのコンテキスト（デフォルト、新規、既存）
• 設定（SECRET_DETECTION_LOG_OPTIONS、SECRET_DETECTION_HISTORIC_SCAN）を調整します。

たとえば、30個のコミットのみをスキャンするには、次のようにします:

secret_detection:
  variables:
    # Scan the last 30 commits
    SECRET_DETECTION_LOG_OPTIONS: "--max-count=30"

過去2週間のコミットのみをスキャンするには、次のようにします:

secret_detection:
  variables:
    # Scan commits made in the last two weeks
    SECRET_DETECTION_LOG_OPTIONS: "--since=2.weeks"

HEAD~10からHEADまでのコミットのみをスキャンするには、次のようにします:

secret_detection:
  variables:
    # Scan commits from HEAD~10 to HEAD
    SECRET_DETECTION_LOG_OPTIONS: "HEAD~10..HEAD"

オプションの完全なリストについては、Gitログオプションのドキュメントを参照してください。

強制プッシュ検出

強制プッシュ後、次のように表示されることがあります:

Failed to retrieve all the commits from the last Git push event due to a force push

これは予期される動作です。スキャンは、現在のリポジトリの状態を使用して続行します。

リポジトリの信頼設定

次のようなメッセージが表示される場合があります:

Added project directory to Git safe.directory configuration

これは、コンテナ化された環境での一般的なシークレット設定を示します。アクションは必要ありません。