シークレットプッシュ保護
- プラン: Ultimate
- 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated
シークレットプッシュ保護は、キーやAPIトークンなどのシークレットがGitLabにプッシュされるのをブロックします。
概要については、プレイリスト「シークレットプッシュ保護の開始」を参照してください。
パイプラインシークレット検出をシークレットプッシュ保護と併用して、セキュリティをさらに強化してください。
シークレットプッシュ保護ワークフロー
シークレットプッシュ保護は事前受信フックで行われます。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およびSelf-Managedインスタンスでは、次のことを行う必要があります:
- シークレットプッシュ保護をインスタンス全体で許可します。
- シークレットプッシュ保護を有効にします。次のいずれかの方法があります。
- 特定のプロジェクトでシークレットプッシュ保護を有効にします。
- APIを使用して、グループ内のすべてのプロジェクトでシークレットプッシュ保護を有効にします。
GitLabインスタンスでシークレットプッシュ保護の使用を許可する
GitLab DedicatedおよびSelf-Managedインスタンスでは、プロジェクトでシークレットプッシュ保護を有効にする前に、シークレットプッシュ保護を許可する必要があります。
前提条件:
- GitLabインスタンスの管理者である必要があります。
GitLabインスタンスでシークレットプッシュ保護の使用を許可するには:
- 管理者としてGitLabインスタンスにサインインします。
- 右上隅で、管理者を選択します。
- 設定 > セキュリティとコンプライアンスを選択します。
- シークレットの検出の下にあるシークレットプッシュ保護を許可するを選択またはクリアします。
シークレットプッシュ保護はインスタンスで許可されています。この機能を使用するには、プロジェクトごとに有効にする必要があります。
プロジェクトでシークレットプッシュ保護を有効にする
前提条件:
- プロジェクトのメンテナーまたはオーナーロールが必要です。
- GitLab DedicatedおよびGitLab Self-Managedでは、インスタンスでシークレットプッシュ保護を許可する必要があります。
プロジェクトでシークレットプッシュ保護を有効にするには:
- 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
- 左サイドバーで、セキュリティ > セキュリティ設定を選択します。
- シークレットプッシュ保護切替をオンにします。
APIを使用して、グループ内のすべてのプロジェクトでシークレットプッシュ保護を有効にすることもできます。
カバレッジ
シークレットプッシュ保護は、次の場合にはシークレットをブロックしません:
- コミットをプッシュしたときに、スキップシークレットプッシュ保護オプションを使用しました。
- シークレットがシークレットプッシュ保護から除外されています。
- シークレットが除外として定義されたパスにあります。
シークレットプッシュ保護は、次の場合、コミット内のファイルをチェックしません:
- ファイルがバイナリファイルである場合。
- ファイルまたは差分パッチが1MiBより大きい場合。
- ファイルが名前変更、削除、またはコンテンツの変更なしで移動された場合。
- ファイルの内容が、ソースコード内の別のファイルの内容と同一である場合。
- ファイルがリポジトリを作成した最初のプッシュに含まれている場合。
- プッシュに合計で350,000行を超える変更された行が含まれている場合。
差分スキャン
シークレットプッシュ保護は、HTTP(S)およびSSH経由でプッシュされたコミットの差分のみをスキャンします。シークレットがファイルにすでに存在し、変更の一部ではない場合、それは検出されません。
プッシュサイズのしきい値
プッシュが3,150を超えるパスまたは350,000行を変更する場合、シークレットプッシュ保護はスキップされます。しきい値は、シークレットプッシュ保護がスキャンするファイルにのみ適用されます（除外で定義されたパスを除外した後）。これらのしきい値は、大量のチェンジセットをプッシュする際のプッシュタイムアウトを防ぎます。
結果について理解する
シークレットプッシュ保護は、さまざまなカテゴリのシークレットを識別できます:
- APIキーとトークン: サービス固有の認証認証情報
- データベース接続文字列: 埋め込み認証情報を含むURL
- プライベートキー: 認証または暗号化のための暗号学的キー
- 一般的な高エントロピー文字列: ランダムに生成されたシークレットのように見えるパターン
プッシュがブロックされた場合、シークレットプッシュ保護は、検出されたシークレットを見つけて対処するのに役立つ詳細情報を提供します:
- コミットID: シークレットを含む特定のコミット。Git履歴の変更を追跡するのに役立ちます。
- ファイルパスと行番号: 検出されたパターンの正確な位置で、素早い移動が可能です。
- シークレットタイプ: 検出されたパターンの分類。例:
GitLab Personal Access Token、AWS Access Key。
一般的な検出カテゴリ
すべての検出に即座の対応が必要なわけではありません。結果を評価する際には、次の点を考慮してください:
真陽性: ローテーションして削除する必要がある正当なシークレット。例:
- 有効なAPIキーまたはトークン
- 本番環境データベース認証情報
- プライベート暗号学的キー
- 不正なアクセスを許可する可能性のあるあらゆる認証情報
誤検出: 実際のシークレットではない、検出されたパターン。例:
- シークレットに似ていますが、実際の価値がないテストデータ
- 設定テンプレート内のプレースホルダー値
- ドキュメント内の認証情報の例
- ハッシュ値またはチェックサムがシークレットパターンと一致する場合
将来の評価を効率化するために、組織内の一般的な誤検出パターンをドキュメント化します。
最適化
シークレットプッシュ保護を広くデプロイする前に、設定を最適化して、誤検出を減らし、特定の環境での精度を向上させます。
誤検出を減らす
誤検出は、デベロッパーの生産性に大きな影響を与え、セキュリティ疲労につながる可能性があります。
誤検出を減らすには:
- 除外を設定する戦略:
- テストディレクトリ、ドキュメント、およびサードパーティの依存関係に対してパスベースの除外を作成します。
- コードベースに固有の既知の誤検出パターンに対して、パターンベースの除外を使用します。
- 除外ルールをドキュメント化し、定期的にレビューします。
- 除外ルールに一致するが、デフォルトルールセットには一致しないプレースホルダー値とテスト認証情報の標準を作成します。
- 誤検出率を監視し、それに応じて除外を調整し続けます。
パフォーマンスを最適化する
大規模なリポジトリまたは頻繁なプッシュは、パフォーマンスに影響を与える可能性があります。
シークレットプッシュ保護のパフォーマンスを最適化するには:
- プッシュ時間を監視し、デプロイ前にベースラインメトリクスを確立します。
- 大容量のバイナリアセットを持つリポジトリのファイルサイズ制限を考慮します。
- シークレットが含まれる可能性の低いディレクトリには除外を実装します。
既存のワークフローとの統合
シークレットプッシュ保護が既存の開発プラクティスを補完するようにします:
- 確実な多層防御を確保するために、パイプラインシークレット検出とシークレットプッシュ保護を設定します。
- デベロッパードキュメントを更新し、シークレットプッシュ保護手順を含めます。
- セキュリティトレーニングと連携して、デベロッパーに安全なコード作成プラクティスを教育し、流出したシークレットを最小限に抑えます。
ロールアウトする
大規模なシークレットプッシュ保護のデプロイを成功させるには、慎重な計画と段階的な実装が必要です:
- 積極的に開発されている重要ではないプロジェクトを2つまたは3つ選択し、機能をテストしてデベロッパーワークフローへの影響を理解します。
- 選択したテストプロジェクトでシークレットプッシュ保護を有効にし、デベロッパーのフィードバックを監視します。
- ブロックされたプッシュを処理するためのプロセスをドキュメント化し、開発チームに新しいワークフローについてトレーニングします。
- パイロットフェーズ中に、検出されたシークレットの数、誤検出率、およびDevExフィードバックを追跡します。
より広範なデプロイの前に、十分なデータを収集し、必要なワークフロー調整を特定するために、パイロットフェーズを2〜4週間実行する必要があります。
パイロットを完了した後、スケールされたロールアウトのために次のフェーズを検討してください:
- 初期採用者（3〜6週目）
- アクティブなプロジェクトの10〜20%で有効にし、セキュリティに敏感なリポジトリを優先します。
- 高いセキュリティ意識と賛同を持つチームに焦点を当てます。
- パフォーマンスへの影響とDevExを監視します。
- 実際の使用状況に基づいてプロセスを改善します。
- 広範なデプロイ（7〜12週目）
- 残りのプロジェクトをバッチで徐々に有効にします。
- 開発チームに継続的なサポートとトレーニングを提供します。
- システムパフォーマンスを監視し、必要に応じてインフラストラクチャをスケールします。
- 使用パターンに基づいて除外ルールの最適化を続けます。
- 完全なカバレッジ（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を使用しており、いくつかのコミットがシークレットを含んでいるためにプッシュがブロックされているとします。シークレットプッシュ保護をスキップするには、最新のコミットメッセージを編集して
[skip secret push protection]を追加し、コミットをプッシュします。
トラブルシューティング
シークレットプッシュ保護を使用しているときに、次のような状況に遭遇する可能性があります。
プッシュが予期せずブロックされました
GitLab 17.11以前は、シークレットプッシュ保護はすべての変更されたファイルの内容をスキャンしていました。これは、変更されたファイルにシークレットが含まれている場合、そのシークレットが差分の一部でなくても、プッシュが予期せずブロックされる原因となる可能性があります。
GitLab 17.10以前では、新しくコミットされた変更のみがスキャンされるように、spp_scan_diffs機能フラグを有効にします。シークレットを含むファイルにWeb IDEの変更をプッシュするには、さらにsecret_checks_for_web_requests機能フラグを有効にする必要があります。
ファイルがスキャンされませんでした
一部のファイルはスキャンから除外されます。詳細については、カバレッジを参照してください。