implementing-secrets-scanning-in-ci-cd

CI/CD でのシークレットスキャンの実装

概要

このスキルでは、gitleaks と trufflehog を使用して、CI/CD パイプラインに自動シークレットスキャンを実装する方法を説明します。セキュリティチームは、ソースコードリポジトリに誤ってコミットされた API キー、トークン、パスワード、その他の認証情報を検出できます。また、高重大度の検出結果を含むデプロイをブロックする CI ゲートを設けられます。

Gitleaks は、正規表現パターンとエントロピー分析を使用して、Git リポジトリとディレクトリ内のハードコードされたシークレットをスキャンします。TruffleHog は、ファイルシステムと Git の履歴をスキャンし、オプションで稼働中のサービスに対するシークレットの検証も行います。両方を組み合わせることで、シークレット検出を包括的にカバーできます。

使用する場面

• 環境でシークレットスキャン機能を導入、設定、または実装するとき
• コンプライアンス要件に沿ったセキュリティ制御を確立するとき
• この分野のセキュリティアーキテクチャを構築、または改善するとき
• この実装を必要とするセキュリティ評価を実施するとき

前提条件

• Python 3.9 以降
• gitleaks v8.x がインストールされ、PATH から利用可能であること
• trufflehog v3.x がインストールされ、PATH から利用可能であること
• スキャンする Git リポジトリまたはディレクトリ
• CI/CD プラットフォーム（GitHub Actions、GitLab CI、Jenkins）へのアクセス

手順

1. スキャンツールをインストールする：パッケージマネージャーまたはバイナリのダウンロードで gitleaks をインストールします。brew install trufflehog を実行するか、GitHub のリリースからダウンロードして trufflehog をインストールします。

2. gitleaks を設定する：カスタムルール、許可リスト、パスの除外を定義する .gitleaks.toml 設定ファイルをリポジトリのルートに作成します。カスタム設定ファイルを指定するには --config フラグを使用します。

3. gitleaks でディレクトリをスキャンする：gitleaks dir --source . --report-format json --report-path gitleaks-report.json を実行して、作業ディレクトリをスキャンし、JSON レポートを生成します。

4. trufflehog でファイルシステムをスキャンする：trufflehog filesystem /path/to/repo --json > trufflehog-report.json を実行してファイルをスキャンし、検出結果を JSON 形式でレポートファイルに出力します。

5. 検出結果を解析してフィルタリングする：エージェントスクリプトを使用して両方の JSON レポートを解析し、重大度（critical、high、medium、low）で検出結果をフィルタリングして、CI パイプラインを成功させるか失敗させるかを判定します。

6. CI パイプラインに統合する：スキャン手順を GitHub Actions のワークフロー、GitLab CI の設定、または Jenkins パイプラインに追加し、デプロイ前のゲートとして実行します。パイプラインの動作を制御するには、gitleaks の --exit-code フラグを使用します。

7. pre-commit フックを設定する：gitleaks protect --staged を使用して gitleaks を pre-commit フックとして設定し、シークレットがコミットされる前に検出します。

8. 検出結果を確認してトリアージする：JSON 出力を調べて誤検知を確認し、正当な項目を .gitleaksignore に追加します。漏えいが確認された認証情報は、直ちにローテーションします。

期待される出力

エージェントスクリプトは、次の情報を含む JSON レポートを生成します。

• 各スキャナーの検出総数
• 重大度別に分類された検出結果
• ファイルパス、行番号、ルール ID、マスキングされたシークレットなど、個々の検出結果の詳細
• 設定された重大度のしきい値に基づく CI ゲートの判定（成功／失敗）
• スキャン所要時間やツールのバージョンなどの実行メタデータ

{
  "scan_summary": {
    "tool": "both",
    "total_findings": 3,
    "critical": 1,
    "high": 1,
    "medium": 1,
    "low": 0,
    "ci_gate": "FAIL",
    "fail_reason": "Found 1 critical and 1 high severity findings"
  },
  "findings": [...]
}