正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。
ドキュメントに関する現在のご利用体験についてお聞かせください。アンケートにご協力ください。

シークレットプッシュ保護

  • プラン: Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

シークレットプッシュ保護は、キーやAPIトークンなどのシークレットがGitLabにプッシュされるのをブロックします。

概要については、再生リストGet Started with Secret Push Protectionを参照してください。

パイプラインシークレット検出とシークレットプッシュ保護を併用して、セキュリティをさらに強化してください。

シークレットプッシュ保護のワークフロー

シークレットプッシュ保護は事前受信フックで行われます。GitLabにプッシュをプッシュすると、プッシュ保護は各ファイルまたはコミットでシークレットをチェックします。デフォルトでは、シークレットが検出された場合、プッシュはブロックされます。

シークレット保護がプッシュをブロックする方法を示すフローチャート

プッシュがブロックされると、GitLabは次の情報を含むメッセージを表示します:

  • コミットIDにシークレットが含まれています。
  • ファイル名とシークレットを含む行。
  • シークレットのタイプ。

例として、Git CLIを使用してプッシュがブロックされたときに返されるメッセージの抜粋を次に示します。GitLab Web IDEを含む他のクライアントを使用する場合、メッセージのフォーマットは異なりますが、内容は同じです。

remote: PUSH BLOCKED: Secrets detected in code changes
remote: Secret push protection found the following secrets in commit: 37e54de5e78c31d9e3c3821fd15f7069e3d375b6
remote:
remote: -- test.txt:2 GitLab Personal Access Token
remote:
remote: To push your changes you must remove the identified secrets.

シークレットプッシュ保護がコミットでシークレットを検出しない場合、メッセージは表示されません。

検出されたシークレット

シークレットプッシュ保護は、特定のパターンに対してファイルまたはコミットをスキャンします。各パターンは特定のタイプのシークレットに一致します。シークレットプッシュ保護によって検出されるシークレットを確認するには、検出されたシークレットを参照してください。シークレットプッシュ保護には、コミットのプッシュ時の遅延を最小限に抑えると、誤検出の数を最小限に抑えるために、信頼性の高いパターンのみが選択されました。例えば、カスタムプレフィックスを使用するパーソナルアクセストークンは、シークレットプッシュ保護では検出されません。シークレットプッシュ保護による検出から、選択したシークレットを除外することができます。

はじめに

GitLab DedicatedとGitLab Self-Managedのインスタンスでは、次の操作を行う必要があります:

  1. インスタンス全体でシークレットプッシュ保護を許可します。
  2. シークレットプッシュ保護を有効にします。次のいずれかの方法があります。
    • 特定のプロジェクトでシークレットプッシュ保護を有効にします。
    • APIを使用して、グループ内のすべてのプロジェクトでシークレットプッシュ保護を有効にします。

GitLabインスタンスでシークレットプッシュ保護の使用を許可する

GitLab DedicatedとGitLab Self-Managedのインスタンスでは、プロジェクトでシークレットプッシュ保護を有効にする前に、それを許可する必要があります。

前提条件:

  • GitLabインスタンスの管理者である必要があります。

GitLabインスタンスでシークレットプッシュ保護の使用を許可するには、次の手順を実行します:

  1. 管理者としてGitLabインスタンスにサインインします。
  2. 右上隅で、管理者を選択します。
  3. 左サイドバーで、設定 > セキュリティとコンプライアンスを選択します。
  4. シークレットの検出で、Allow secret push protectionを選択またはクリアします。

インスタンスでシークレットプッシュ保護が許可されます。この機能を使用するには、プロジェクトごとに有効にする必要があります。

プロジェクトでシークレットプッシュ保護を有効にする

前提条件:

  • プロジェクトのセキュリティマネージャー、メンテナー、またはオーナーロールが必要です。
  • GitLab DedicatedとGitLab Self-Managedでは、インスタンスでシークレットプッシュ保護を許可する必要があります。

プロジェクトでシークレットプッシュ保護を有効にするには:

  1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
  2. 左側のサイドバーで、セキュリティ > セキュリティ設定を選択します。
  3. シークレットプッシュ保護切替をオンにします。

グループ内のすべてのプロジェクトでAPIを使用してシークレットプッシュ保護を有効にすることもできます。

カバレッジ

シークレットプッシュ保護は、次の場合にはシークレットをブロックしません:

  • コミットをプッシュする際に、シークレットプッシュ保護をスキップするオプションを使用します。
  • シークレットがシークレットプッシュ保護から除外されています。
  • シークレットが除外として定義されたパスにあります。

シークレットプッシュ保護は、次の場合にはコミット内のファイルをチェックしません:

  • ファイルがバイナリファイルである。
  • ファイルまたは差分パッチが1 MiBより大きい。
  • ファイルが、コンテンツの変更なしに名前変更、削除、または移動された場合。
  • ファイルの内容が、コード内の別のファイルの内容と同一である。
  • ファイルがリポジトリを作成した最初のプッシュに含まれている。
  • プッシュに含まれる変更された行の合計が350,000行を超える。

差分スキャン

シークレットプッシュ保護は、HTTP(S)およびSSH経由でプッシュされたコミットの差分のみをスキャンします。シークレットが既にファイル内に存在し、変更の一部ではない場合、それは検出されません。

監査イベント

監査イベントは次の場合にログに記録されます:

  • プッシュに変更されたパスが多すぎるため、シークレットプッシュ保護がスキップされる場合。
  • プッシュで変更された行が多すぎるため、シークレットプッシュ保護がスキップされる場合。
  • シークレットプッシュ保護スキャンがタイムアウトし、GitLabがプッシュを受け入れる場合。
  • シークレットプッシュ保護がルールセットの解析またはコンパイルエラーを検出する場合。
  • スキャンが無効な入力を受け取ったため、シークレットプッシュ保護がスキップされる場合。
  • シークレットプッシュ保護が予期しないスキャンエラーを検出する場合。

プッシュサイズのしきい値

プッシュが3,150を超えるパスまたは350,000行を変更した場合、シークレットプッシュ保護はスキップされます。しきい値は、シークレットプッシュ保護がスキャンするファイル（除外で定義されたパスを除外した後）にのみ適用されます。これらのしきい値は、大規模な変更セットをプッシュする際のプッシュタイムアウトを防ぎます。

結果について理解する

シークレットプッシュ保護は、さまざまなカテゴリのシークレットを識別できます:

  • APIキーとトークン: サービス固有の認証認証情報
  • データベース接続文字列: 認証情報が埋め込まれたURL
  • プライベートキー: 認証または暗号化のための暗号学的キー
  • 汎用高エントロピー文字列: ランダムに生成されたシークレットのように見えるパターン

プッシュがブロックされると、シークレットプッシュ保護は、検出されたシークレットを見つけて対処するのに役立つ詳細情報を提供します:

  • コミットID: シークレットを含む特定のコミット。Git履歴の変更を追跡するのに役立ちます。
  • ファイルパスと行番号: 迅速なナビゲーションのために、検出されたパターンの正確な場所。
  • シークレットタイプ: 検出されたパターンの分類。例: GitLab Personal Access Token、AWS Access Key。

一般的な検出カテゴリ

すべての検出が直ちに行動を必要とするわけではありません。結果を評価する際に、以下を考慮してください:

  • 真陽性: ローテーションして削除する必要がある正当なシークレット。例:
    • 有効なAPIキーまたはトークン
    • 本番環境データベース認証情報
    • プライベート暗号学的キー
    • 不正なアクセスを許可する可能性のあるあらゆる認証情報
  • 誤検出: 実際のシークレットではない、検出されたパターン。例:
    • シークレットに似ているが、実際の価値がないテストデータ
    • 設定テンプレートのプレースホルダー値
    • ドキュメント内の認証情報の例
    • シークレットパターンに一致するハッシュ値またはチェックサム

将来の評価を効率化するために、組織内の一般的な誤検出パターンをドキュメント化します。

最適化

シークレットプッシュ保護を広くデプロイする前に、設定を最適化して誤検出を削減し、特定の環境の精度を向上させます。

誤検出を削減する

誤検出は、デベロッパーエクスペリエンスに大きな影響を与え、セキュリティ疲労につながる可能性があります。

誤検出を削減するには:

  • 戦略的に除外を設定します:
    • テストディレクトリ、ドキュメント、およびサードパーティの依存関係に対して、パスベースの除外を戦略的に作成します。
    • コードベースに固有の既知の誤検出パターンに対して、パターンベースの除外を使用します。
    • 除外ルールセットをドキュメント化し、定期的にレビューします。
  • プレースホルダー値とテスト認証情報の標準を作成します。これらは除外ルールセットに一致する必要がありますが、デフォルトのルールセットには一致しないようにします。
  • 誤検出率を監視し、それに応じて除外を調整し続けます。

パフォーマンスを最適化する

大規模なリポジトリや頻繁なプッシュは、パフォーマンスに影響を与える可能性があります。

シークレットプッシュ保護のパフォーマンスを最適化するには:

  • デプロイの前に、プッシュ時間を監視し、ベースラインメトリクスを確立します。
  • 大規模なバイナリアセットを持つリポジトリのファイルサイズ制限を考慮します。
  • シークレットが含まれる可能性の低いディレクトリに対して、除外を実装します。

既存のワークフローとのインテグレーション

シークレットプッシュ保護が既存の開発プラクティスを補完するようにします:

  • パイプラインシークレット検出とシークレットプッシュ保護を設定して、多層防御を確保します。
  • デベロッパーエクスペリエンスドキュメントを更新し、シークレットプッシュ保護の手順を含めます。
  • セキュリティトレーニングと連携して、開発者に安全なコード作成プラクティスについて教育し、流出したシークレットを最小限に抑えるようにします。

ロールアウトする

シークレットプッシュ保護を大規模にデプロイするには、慎重な計画と段階的な実装が必要です:

  1. アクティブな開発を行っている重要度の低いプロジェクトを2つか3つ選択し、その機能をテストして、開発者のワークフローへの影響を理解します。
  2. 選択したテストプロジェクトでシークレットプッシュ保護をオンにし、開発者のフィードバックを監視します。
  3. ブロックされたプッシュを処理するためのプロセスをドキュメント化し、新しいワークフローについて開発チームをトレーニングします。
  4. パイロットフェーズ中に、検出されたシークレットの数、誤検出率、およびデベロッパーエクスペリエンスのフィードバックを追跡します。

より広範なデプロイの前に、十分なデータを収集し、必要なワークフローの調整を特定するために、パイロットフェーズを2〜4週間実施する必要があります。

パイロットを完了した後、大規模なロールアウトのための次のフェーズを検討してください:

  1. 早期導入者（3〜6週間）
    • アクティブなプロジェクトの10〜20%で有効にし、セキュリティに敏感なリポジトリを優先します。
    • セキュリティ意識が高く、協力的なチームに焦点を当てます。
    • パフォーマンスへの影響とデベロッパーエクスペリエンスを監視します。
    • 実際の使用状況に基づいてプロセスを改善します。
  2. 広範なデプロイ（7〜12週間）
    • 残りのプロジェクトで段階的にバッチで有効にします。
    • 開発チームに継続的なサポートとトレーニングを提供します。
    • システムパフォーマンスを監視し、必要に応じてインフラストラクチャをスケールします。
    • 使用パターンに基づいて除外ルールセットの最適化を続けます。
  3. 完全なカバレッジ（13〜16週間）
    • 残りのすべてのプロジェクトでシークレットプッシュ保護を有効にします。
    • 継続的なメンテナンスとレビュープロセスを確立します。
    • 除外ルールセットと検出されたパターンの定期的な監査イベントを実装します。

ブロックされたプッシュを解決する

シークレットプッシュ保護がプッシュをブロックした場合、次のいずれかの操作を実行できます:

シークレットプッシュ保護をスキップする

場合によっては、シークレットプッシュ保護をスキップする必要があるかもしれません。例えば、デベロッパーがテストのためにプレースホルダーシークレットをコミットする必要がある場合や、ユーザーがGit操作のタイムアウトのためにシークレットプッシュ保護をスキップしたい場合があります。

シークレットプッシュ保護がスキップされたときに監査イベントがログに記録されます。監査イベントの詳細には以下が含まれます:

  • 使用されたスキップ方法。
  • GitLabアカウント名。
  • シークレットプッシュ保護がスキップされた日時。
  • シークレットがプッシュされたプロジェクトの名前。
  • ターゲットブランチ。（GitLab 17.4で導入）
  • シークレットプッシュ保護をスキップしたコミット。（GitLab 17.9で導入）

パイプラインシークレット検出が有効になっている場合、すべてのコミットのコンテンツは、リポジトリにプッシュされた後にスキャンされます。

プッシュ内のすべてのコミットに対してシークレットプッシュ保護をスキップするには、次のいずれかを実行します:

  • Git CLIクライアントを使用している場合は、Gitにシークレットプッシュ保護をスキップするように指示します。
  • 他のクライアントを使用している場合は、いずれかのコミットメッセージに[skip secret push protection]を追加します。

Git CLIクライアントの場合

コマンドラインからシークレットプッシュ保護をスキップするには:

  • secret_push_protection.skip_allプッシュオプションを使用します。

    例えば、いくつかのコミットのうちの1つにシークレットが含まれているため、それらがプッシュされるのをブロックされているとします。シークレットプッシュ保護をスキップするには、Gitコマンドにプッシュオプションを追加します。

    git push -o secret_push_protection.skip_all

任意のGitクライアントの場合

シークレットプッシュ保護をスキップするには:

  • 既存の行または新しい行のいずれかで、いずれかのコミットメッセージに[skip secret push protection]を追加し、コミットをプッシュします。

    例えば、GitLab Web IDEを使用しており、いくつかのコミットのうちの1つにシークレットが含まれているため、それらがプッシュされるのをブロックされているとします。シークレットプッシュ保護をスキップするには、最新のコミットメッセージを編集して[skip secret push protection]を追加し、コミットをプッシュします。

トラブルシューティング

シークレットプッシュ保護を使用する際に、以下の状況に遭遇する可能性があります。

予期せずプッシュがブロックされた

GitLab 17.11以前は、シークレットプッシュ保護は変更されたすべてのファイルの内容をスキャンしていました。これは、変更されたファイルにシークレットが含まれている場合、そのシークレットが差分の一部でなくても、プッシュが予期せずブロックされる原因となる可能性があります。

GitLab 17.10以前では、新たにコミットされた変更のみがスキャンされるように、spp_scan_diffs機能フラグを有効にします。Web IDEの変更をシークレットを含むファイルにプッシュするには、さらにsecret_checks_for_web_requests機能フラグを有効にする必要があります。

ファイルがスキャンされませんでした

一部のファイルはスキャンから除外されます。詳細については、カバレッジを参照してください。