Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

GitGuardian Enterprise のログを収集する

パーサーのバージョン: 1.0

以下でサポートされています。

Google SecOps SIEM

このドキュメントでは、Webhook を使用してログを Google Security Operations に push するように GitGuardian Enterprise を構成する方法について説明します。

GitGuardian Enterprise は、ソースコードリポジトリ、CI/CD パイプライン、デベロッパーワークステーションをモニタリングして、公開された認証情報や機密データを検出して修正するプラットフォームです。シークレットが検出されるとリアルタイムでアラートが送信され、セキュリティチームがインシデントの修復ワークフローを管理するのに役立ちます。

始める前に

次の前提条件を満たしていることを確認してください。

Google SecOps インスタンス
GitGuardian Enterprise ワークスペース（管理者アクセスレベル）
Google Cloud コンソールへのアクセス（API キーの作成用）
GitGuardian Business プラン以上（カスタム Webhook のサポート）

Google SecOps で Webhook フィードを作成する

フィードを作成する

[SIEM 設定] > [フィード] に移動します。
[Add New Feed] をクリックします。
次のページで、[単一のフィードを構成する] をクリックします。
[フィード名] フィールドに、フィードの名前を入力します（例: GitGuardian Enterprise Incidents）。
[Source type] として [Webhook] を選択します。
[ログタイプ] として [GitGuardian Enterprise] を選択します。
[次へ] をクリックします。
次の入力パラメータの値を指定します。
- Split delimiter（省略可）: 空白のままにします（各 Webhook リクエストには 1 つのイベントが含まれます）。
- Asset namespace: アセットの名前空間。
- Ingestion labels: このフィードのイベントに適用されるラベル
[次へ] をクリックします。
[Finalize] 画面で新しいフィードの設定を確認し、[送信] をクリックします。

秘密鍵を生成して保存する

フィードを作成したら、認証用のシークレットキーを生成する必要があります。

フィードの詳細ページで、[秘密鍵を生成] をクリックします。
ダイアログに秘密鍵が表示されます。
秘密鍵をコピーして安全に保存します。

重要: 秘密鍵は一度しか表示されず、後で取得することはできません。秘密鍵を紛失した場合は、新しい秘密鍵を生成する必要があります。

フィードエンドポイントの URL を取得する

フィードの [詳細] タブに移動します。
[エンドポイント情報] セクションで、[フィードエンドポイント URL] をコピーします。
URL の形式は次のとおりです。
```
https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import
```
ここで、{region} は Google SecOps インスタンスのリージョン（us、europe、asia-southeast1 など）で、{parent} は projects/<PROJECT_ID>/locations/<LOCATION>/instances/<INSTANCE_ID>/logTypes/<LOG_TYPE> 形式のリソースパスです。
次の手順で使用するために、この URL を保存します。
[完了] をクリックします。

Google Cloud API キーを作成する

Google SecOps では、認証に API キーが必要です。 Google Cloud コンソールで制限付き API キーを作成します。

API キーを作成する

Google Cloud コンソールの [認証情報] ページに移動します。
プロジェクト（Google SecOps インスタンスに関連付けられているプロジェクト）を選択します。
[認証情報を作成] > [API キー] をクリックします。
API キーが作成され、ダイアログに表示されます。
[API キーを編集] をクリックしてキーを制限します。

API キーを制限する

[API キー] 設定ページで、次の操作を行います。
- 名前: わかりやすい名前を入力します（例: Google SecOps GitGuardian Webhook API Key）。
[API の制限] で次の操作を行います。
1. [キーを制限] を選択します。
2. [API を選択] プルダウンで、[Google SecOps API]（または [Chronicle API]）を検索して選択します。
[保存] をクリックします。
ページ上部の [API キー] フィールドから API キーの値をコピーします。
API キーを安全に保存します。

注: API キーを制限すると、Chronicle API でのみ使用できるようになり、キーが不正使用された場合のセキュリティリスクが軽減されます。

GitGuardian Enterprise Webhook を構成する

Webhook URL を作成する

Google SecOps エンドポイント URL と API キーを組み合わせます。

<ENDPOINT_URL>?key=<API_KEY>

例:

https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import?key=AIzaSyD...

GitGuardian でカスタム Webhook を作成する

個人用ワークスペースの場合:

GitGuardian ダッシュボードにログインします。
[Settings] > [Workspace] > [Integrations] > [Destinations] > [Custom webhook] に移動します。
[カスタム Webhook を追加] または [新しいカスタム Webhook を作成] をクリックします。
次の構成情報を提供してください。
- [名前]: わかりやすい名前を入力します（例: Google SecOps SIEM Integration）。
- URL: 上記の API キーを含む完全なエンドポイント URL を貼り付けます。
- 署名トークン: Google SecOps フィードの作成時に取得した秘密鍵を貼り付けます。
- カスタムヘッダー（省略可）: 環境タグまたはサービスタグを指定する必要がある場合を除き、空白のままにします。
[Event Subscription] セクションで、Google SecOps に送信するイベントを選択します。
- インシデント:
  - ☑ 新しいインシデントが検出されました
  - ☑ 新しい発生を検出しました
  - ☑ インシデントが解決した
  - ☑ インシデントが無視された
  - ☑ インシデントが再開された
  - ☑ インシデントの回帰
  - ☑ インシデントの割り当て
  - ☑ インシデントの再割り当て
  - ☑ インシデントが割り当てられていない
  - ☑ インシデントの重大度が変更された
  - ☑ インシデントの有効性が変更された
  - ☑ インシデントへのアクセス権が付与されました
  - ☑ インシデントへのアクセス権が取り消されました
  - ☑ インシデントが一般公開されている
  - ☑ インシデントが一般公開されていない
  - ☑ フィードバックを送信しました
  - ☑ インシデントに関する新しいコメント
[作成] または [保存] をクリックします。
GitGuardian は、Webhook が動作していることを確認するためにテストメッセージを送信します。

ビジネスワークスペースの場合:

GitGuardian ダッシュボードにログインします。
Webhook のスコープを決定します。
- ワークスペース内のすべてのインシデントの場合: [All-incidents team] に移動します。
- 特定のチームのインシデントの場合: 目的のチームに移動します。
[Settings] > [Workspace] > [Integrations] > [Destinations] > [Custom webhook] に移動します。
- または、チームページから [Integrations] > [Custom webhook] に移動します。
[カスタム Webhook を追加] または [新しいカスタム Webhook を作成] をクリックします。
次の構成情報を提供してください。
- [名前]: わかりやすい名前を入力します（例: Google SecOps SIEM Integration）。
- URL: 上記の API キーを含む完全なエンドポイント URL を貼り付けます。
- 署名トークン: Google SecOps フィードの作成時に取得した秘密鍵を貼り付けます。
- カスタムヘッダー（省略可）: 環境タグまたはサービスタグを指定する必要がある場合を除き、空白のままにします。
[Event Subscription] セクションで、Google SecOps に送信するイベントを選択します。
- インシデント:
  - ☑ 新しいインシデントが検出されました
  - ☑ 新しい発生を検出しました
  - ☑ インシデントが解決した
  - ☑ インシデントが無視された
  - ☑ インシデントが再開された
  - ☑ インシデントの回帰
  - ☑ インシデントの割り当て
  - ☑ インシデントの再割り当て
  - ☑ インシデントが割り当てられていない
  - ☑ インシデントの重大度が変更された
  - ☑ インシデントの有効性が変更された
  - ☑ インシデントへのアクセス権が付与されました
  - ☑ インシデントへのアクセス権が取り消されました
  - ☑ インシデントが一般公開されている
  - ☑ インシデントが一般公開されていない
  - ☑ フィードバックを送信しました
  - ☑ インシデントに関する新しいコメント
[作成] または [保存] をクリックします。
GitGuardian は、Webhook が動作していることを確認するためのテストメッセージを送信します。

Webhook の配信を確認する

GitGuardian ダッシュボードで、カスタム Webhook 構成に移動します。
[テストメッセージを送信] または [Webhook をテスト] をクリックします。
GitGuardian が Google SecOps にサンプルペイロードを送信します。
Google SecOps コンソールで、[SIEM 設定] > [フィード] に移動します。
GitGuardian フィードを見つけて、テストイベントが受信されたことを確認します。
[Feed Status] に [Active] と表示され、最近の取り込みのタイムスタンプが表示されていることを確認します。

注: テストメッセージには、検閲されたシークレット値を含むサンプルデータが含まれています。本番環境の Webhook には、実際のインシデントデータが含まれます。

認証方法のリファレンス

Google SecOps の Webhook フィードは、複数の認証方法をサポートしています。ベンダーがサポートしている方法を選択してください。

方法 1: クエリパラメータ（GitGuardian に推奨）

GitGuardian のカスタム Webhook は、URL に認証情報を追加すると最適に機能します。

URL 形式:
```
<ENDPOINT_URL>?key=<API_KEY>
```
例:
```
https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import?key=AIzaSyD...
```
GitGuardian Webhook の構成:
- URL: API キーパラメータを含む完全なエンドポイント URL
- 署名トークン: Google SecOps 秘密鍵（HMAC 検証用）

リクエストの形式:

POST <ENDPOINT_URL>?key=<API_KEY> HTTP/1.1
Content-Type: application/json
Timestamp: 1234567890
Gitguardian-Signature: sha256=abc123...

{
    "source": "GitGuardian",
    "timestamp": "2025-01-15T10:30:00Z",
    "action": "incident_triggered",
    "incident": {...}
}

方法 2: カスタムヘッダー（代替）

認証情報を URL に含めないようにするには、カスタムヘッダーを使用します。

リクエストの形式:

POST <ENDPOINT_URL> HTTP/1.1
Content-Type: application/json
x-goog-chronicle-auth: <API_KEY>
Timestamp: 1234567890
Gitguardian-Signature: sha256=abc123...

{
    "source": "GitGuardian",
    "timestamp": "2025-01-15T10:30:00Z",
    "action": "incident_triggered",
    "incident": {...}
}

GitGuardian Webhook 署名の検証

GitGuardian は、HMAC-SHA256 を使用してすべての Webhook ペイロードに署名し、真正性を確保して改ざんを防止します。

署名ヘッダー

GitGuardian は、Webhook リクエストに次のヘッダーを含めます。

Gitguardian-Signature: sha256=<hex_digest> 形式の HMAC-SHA256 署名
Timestamp: リクエストが送信されたときの Unix タイムスタンプ
X-GitGuardian-Signature: 非推奨のヘッダー（下位互換性のために引き続きサポートされています）

署名アルゴリズム

署名は次のように計算されます。
```
HMAC-SHA256(key=timestamp + signature_token, message=payload)
```
ここで
- timestamp: Timestamp ヘッダーの値
- signature_token: GitGuardian Webhook 設定で構成されたシークレットキー
- payload: UTF-8 文字列としての未加工の JSON リクエスト本文

検証の例（Python）

import hmac
import hashlib

def verify_signature(signature: str, timestamp: str, signature_token: str, payload: str) -> bool:
    if not signature.startswith("sha256="):
        return False
    
    signature = signature.split("sha256=")[-1]
    
    hmac_digest = hmac.new(
        key=bytes(timestamp + signature_token, "utf-8"),
        msg=bytes(payload, "utf-8"),
        digestmod=hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, hmac_digest)

リプレイ攻撃保護

Timestamp ヘッダーはリプレイ攻撃を防ぎます。現在のタイムスタンプと Webhook のタイムスタンプの差が数秒（推奨: 300 秒）を超える場合は、リクエストを拒否します。

注: Google SecOps は、Webhook 認証を自動的に処理します。Google SecOps ウェブフックフィードを使用する場合、署名検証を実装する必要はありません。

イベントタイプとペイロード構造

GitGuardian は、インシデントのライフサイクルの変化に基づいて、さまざまなイベントタイプを送信します。

インシデントイベント

イベントタイプ	アクション値	説明
新しいインシデントが検出されました	`incident_triggered`	新しいシークレットインシデントが検出されました
新しい発生が検出されました	`new_occurrence`	既存のインシデントの新しい発生が見つかりました
インシデントが解決しました	`incident_resolved`	インシデントが解決済みとしてマークされました
インシデントが無視されました	`incident_ignored`	インシデントが無視としてマークされました
インシデントが再開されました	`incident_reopened`	以前にクローズされたインシデントが再開されました
インシデント回帰	`incident_regression`	このインシデントについて新しい回帰が見つかりました
Incident assigned	`incident_assigned`	インシデントがユーザーに割り当てられました
インシデントが再割り当てされました	`incident_reassigned`	インシデントが別のユーザーに再割り当てされました
インシデントの割り当て解除	`incident_unassigned`	ユーザーがこのインシデントから割り当て解除されました
重大度が変更されました	`incident_severity_changed`	重大度レベルが更新されました
有効期間の変更	`incident_validity_changed`	有効性ステータスが更新されました
アクセスが許可される	`incident_access_granted`	ユーザーにこのインシデントへのアクセス権が付与されました
アクセス権が取り消されました	`incident_access_revoked`	ユーザーのこのインシデントへのアクセス権が取り消された
一般公開で共有	`incident_shared_publicly`	公開共有リンクが生成されました
一般公開の共有を解除	`incident_unshared_publicly`	公開共有リンクが無効になりました
フィードバックを送信しました	`issue_feedback_received`	このインシデントに関するフィードバックが送信されました
新しいコメント	`incident_note_created`	このインシデントに関する新しいメモが作成されました

ペイロード構造の例

すべての Webhook ペイロードは次の構造に従います。

{
    "source": "GitGuardian",
    "timestamp": "2025-01-15T10:30:00.123456Z",
    "action": "incident_triggered",
    "message": "A new incident has been detected.",
    "target_user": "john.doe@example.com",
    "target_team": "Security Team",
    "custom_webhook_name": "Google SecOps SIEM Integration",
    "incident": {
        "id": 12345,
        "date": "2025-01-15T10:29:58.123456Z",
        "detector": {
            "name": "aws_iam",
            "display_name": "AWS Keys",
            "nature": "specific",
            "family": "credentials"
        },
        "secret_hash": "abc123...",
        "secret_revoked": false,
        "validity": "valid",
        "occurrence_count": 1,
        "status": "triggered",
        "assignee_email": null,
        "severity": "high",
        "gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/12345"
    }
}

Webhook の制限とベストプラクティス

リクエストに関する上限

上限	値
最大リクエストサイズ	4 MB
最大 QPS（秒間クエリ数）	15,000
リクエストのタイムアウト	30 秒
再試行の動作	指数バックオフによる自動再試行

ベストプラクティス

イベントの選択: セキュリティ運用に関連するイベントのみをサブスクライブして、ノイズを低減します。
チームスコープ: ビジネスワークスペースの場合、チームレベルで Webhook を作成して、チームの所有権でインシデントをフィルタします。
署名の検証: 署名トークンを安全に保存し、ソースコードにコミットしないようにします。
モニタリング: GitGuardian ダッシュボードで webhook の配信ステータスを定期的に確認します。
テスト: テストメッセージ機能を使用して、本番環境で使用する前に Webhook 構成を検証します。

配信の保証

重要: Webhook の配信はベストエフォートであり、保証されません。Google SecOps エンドポイントにアクセスできない場合や、ネットワークの問題がある場合、Webhook イベントが受信されないことがあります。一般的に、Webhook は信頼性が高いですが、配信は保証されません。

重要なユースケースでは、ウェブフックに加えて定期的な API ポーリングを行い、インシデントを見逃さないようにすることを検討してください。

UDM マッピングテーブル

ログフィールド	UDM マッピング	ロジック
日付	metadata.event_timestamp	ISO8601 形式を使用して変換
has_user	metadata.event_type	has_user が true の場合は「USER_UNCATEGORIZED」に設定し、それ以外の場合は「GENERIC_EVENT」に設定します。
event_name	metadata.product_event_type	値を直接コピーする
id	metadata.product_log_id	値を直接コピーする
	metadata.product_name	「GitGuardian Enterprise」に設定します。
	metadata.vendor_name	「GitGuardian」に設定します。
member_email	principal.user.email_addresses	member_email から統合
member_name	principal.user.user_display_name	値を直接コピーする
member_id	principal.user.userid	文字列に変換しました
action_type	security_result.action_details	値が直接コピーされる
target_ids	target.resource.product_object_id	target_ids の最初の要素からの値

変更ログ

このパーサーの変更ログを表示する

さらにサポートが必要な場合 コミュニティメンバーや Google SecOps のプロフェッショナルから回答を得ることができます。