Gemini でカスタム パーサーとパーサー拡張機能を作成する
このガイドは、セキュリティ アナリストと検出エンジニアが Google Security Operations の AI 解析を使用して、カスタム パーサーをゼロから構築したり、既存のパーサーを拡張するパーサー拡張機能を作成したりする際に役立ちます。自然言語プロンプトとベンダーのドキュメントを使用すると、複雑なパーサー構文や正規表現を記述することなく、未加工のログを統合データモデル（UDM）にマッピングできます。
AI カスタム パーサーと AI パーサー拡張機能のどちらかを選択する
次の表は、AI 解析の「AI を使用してパーサーを作成する」機能と「AI を使用して拡張機能を記述する」機能を比較したものです。
| 機能の側面 | AI を使用してパーサーを作成する | AI を使用して拡張機能を記述 |
|---|---|---|
| 出力 | 完全なスタンドアロン カスタム パーサー | 既存のパーサーにレイヤ化された拡張機能 |
| 主なユースケース | 新しいログソース、サポートされていないログソース、またはパーサーの完全な書き換え | 動作しているパーサーの特定のフィールドを追加または修正する |
| 入力 | ログタイプ、取り込まれた未加工ログ、オプションのドキュメント リンク | ログタイプ、未加工ログのサンプル、マッピングするフィールドを記述するプロンプト |
主な用語
- AI 解析: Google SecOps の AI 支援解析機能のスイート。AI カスタム パーサー生成（AI でパーサーを作成する）や AI パーサー拡張機能（AI で拡張機能を記述する）などがあります。
- 統合データモデル（UDM）: ログデータの保存と分析に使用される Google SecOps の標準データ構造。
始める前に
AI 解析を使用する前に、次の前提条件を満たしていることを確認してください。
- Google SecOps インスタンスで AI 解析機能が有効になっていることを確認します。[AI でパーサーを作成する] オプションまたは [AI で拡張機能を作成する] オプションが表示されない場合は、Google SecOps の担当者にお問い合わせください。
- AI パーサー拡張機能の場合は、ターゲット ログタイプにアクティブな事前構築済みパーサーまたはカスタム パーサーがすでに存在することを確認し、抽出をテストするためのサンプル未加工ログを準備します。
- AI カスタム パーサーの生成では、開始する前にログソースの代表サンプルを取り込みます。パーサー エージェントは、選択したログタイプですでに取り込まれているログから学習します。ログタイプにログが見つからない場合、生成を開始できません。起動に失敗した試行は割り当てにカウントされません。
- AI カスタム パーサーの生成用に、ベンダーのログ形式リファレンス（フィールド辞書、イベント スキーマ、ログサンプル ページなど）への一般公開リンクを 1 ～ 5 個用意します（推奨）。包括的なドキュメントは、パーサーの品質を左右する最大の要因です。
AI を使用してカスタム パーサーを作成する
AI でパーサーを作成すると、ログソースの完全なカスタム パーサーをゼロから作成できます。ログタイプを選択し、必要に応じてベンダーのログ ドキュメントへのリンクを指定します。パーサー エージェントは、取り込まれたログをサンプリングし、ログスキーマを調査して、未加工フィールドから UDM へのマッピングを計画し、JavaScript でパーサーコードを記述します。次に、結果を確認し、未加工のフィールド名と UDM フィールドを参照する平易な英語の指示を使用して、結果を絞り込みます。出力の準備ができたら、他のカスタム パーサーと同様にパーサーを送信します。
AI カスタム パーサー生成を使用すると、次のことができます。
- 事前構築済みパーサーがないログソース、または事前構築済みパーサーがログ形式に適合しないログソースをオンボーディングする。
- 単一のサンプルだけでなく、取り込まれたデータで見つかった個別のログ形式をすべてカバーする完全なパーサーを生成します。
- パーサーコードを自分で記述することなく、フォローアップ プロンプトを使用して生成されたパーサーを改良します。
AI 生成のカスタム パーサーを開始する
- Google SecOps で、[SIEM 設定] > [パーサー] に移動します。
- [Add New Parser] をクリックします。
- [新しいカスタム パーサーを作成] ダイアログで、解析するログソース（
GCP DNSなど）を選択します。 - [パーサーを作成するには、どうすればよいですか？] で、[AI を使用してパーサーを作成する] を選択します。
- [作成] をクリックします。
プロダクト ドキュメントを追加して生成を開始する
- 省略可: [パーサー エージェント] ペインの [プロダクト リンクを追加] フィールドに、ベンダーのログ ドキュメントへのリンクを貼り付けて、[追加] をクリックします。リンクは 5 つまで追加できます。[ドキュメント] カウンタには、追加したリンクの数が表示されます。
- [パーサーを生成] をクリックします。
ドキュメント リンクのガイドライン
生成されたパーサーのフィールド カバレッジを改善するには、ドキュメント リンクを選択する際に次のガイドラインに沿ってください。
- ベンダーのドキュメントへの公開リンクのみを提供します。リンクが非公開またはアクセスできない場合、パーサー エージェントはリンクを無視し、生成を失敗させることなくウェブを検索します。
- ログスキーマ、フィールド辞書、イベント リファレンスなど、ログフィールドとイベントタイプを説明するページへのリンク。マーケティング ページやプロダクトの概要は避けてください。
- 取り込むログ形式に一致するページを選択します。たとえば、JSON 監査ログを取り込む場合は、syslog リファレンスではなく、JSON 監査ログ リファレンスにリンクします。
- ベンダーが異なるイベント カテゴリを別々のページに記載している場合は、イベント カテゴリごとにリンクを追加します（例: DNS クエリ、ファイアウォール イベント、管理者アクティビティ）。
生成の進行状況を追跡する
カスタム パーサーの生成が開始されると、ステータスが [生成中] に変わります。生成プロセスは、次のステージで構成されます。
| ステージ | エージェントの対応 | 次のステージに渡された出力 |
|---|---|---|
| 未加工ログの取得 | エージェントは、ログタイプごとに取り込まれたログをサンプリングします。ログをクラスタ化して、すべての異なるログ形式とイベント形状をカバーする一連のサンプルログを選択します。 | 代表的なログの例 |
| リサーチ ドキュメント | エージェントは、指定されたドキュメント リンクを読み取ります。リンクが指定されていない場合は、ウェブを検索します。この情報とサンプルログを組み合わせて、ログスキーマとフィールド辞書を構築します。 | ログスキーマとフィールド ディクショナリ |
| マッピング計画を作成する | エージェントは、ログ内の各イベントタイプを識別し、各未加工ログフィールドを対応する UDM フィールドにマッピングする方法を計画します。 | 各イベントタイプの未加工フィールドから UDM フィールドへのマッピング計画 |
| パーサーコードを生成する | エージェントは、マッピング プランを JavaScript パーサーコードに変換します。サンプルログに対してコードをテストし、パーサーが正常に実行されるまでエラーを解決します。 | 審査待ちのパーサー |
選択したログタイプのログが見つからないためにパーサーの生成が失敗した場合は、生成を再度開始する前に、そのログタイプの未加工ログを取り込みます。その他の生成エラーについては、手動トリアージ オプションは利用できません。新しい生成セッションをトリガーします。エラーが解決しない場合は、サポートにお問い合わせのうえ、サポートケースを登録してください。
カスタム パーサーを確認して改良する
カスタム パーサーの生成が完了すると、ステータスが [AI GENERATED] に変わり、ページに次のペインが表示されます。
- パーサー エージェント: [AI でパーサーを改良する] プロンプト フィールドが表示されます。ここにフォローアップ指示を入力できます。
- パーサーコード: 生成された JavaScript パーサーコードが表示されます。生成されたコードは、送信前は読み取り専用です。ロジックを変更するには、[Refine Parser with AI] フィールドにプロンプトを入力します。
- 未加工ログ: ログタイプの未加工ログのサンプルが表示されます。 [編集] をクリックして独自のログ行を貼り付けるか、 [更新] をクリックして他のサンプルを読み込むことができます。
- UDM 出力を表示: 未加工のログに対して現在のパーサーコードを実行し、結果の UDM イベントを表示して、各マッピングを確認できるようにします。
生成された出力を確認する
パーサーを有効にする前に、サンプルログ全体で生成されたマッピングを確認します。
- 解析する各イベントタイプを含む複数の未加工ログを読み込み、各ログの [UDM 出力を表示] をクリックします。
- パーサーが未加工ログフィールドを適切な UDM フィールドにマッピングし、その値を正確に入力していることを確認します（例: イベント メタデータ、
principalやtargetなどのエンティティ フィールド、セキュリティ結果フィールド）。 - マッピングされていない重要な未加工フィールドがないか確認します。
AI を使用してカスタム パーサーを改良する
マッピングが正しくないか、マッピングがない場合は、[Refine Parser with AI] フィールドに指示を入力し、[Confirm] をクリックします。パーサー エージェントは、最初からやり直すのではなく、既存のパーサーを更新し、言及されていないすべてのマッピングを保持します。絞り込みを行うたびに、確認可能な新しいバージョンのパーサーコードが作成されます。
効果的な絞り込みプロンプトを作成するには、次のガイドラインに沿って対応してください。
- 未加工のソース フィールド（またはログのサンプル値）と、ターゲット UDM フィールドの正確なパスの両方を指定します。
- 関連する変更をグループ化し、関連のない修正を 1 つの長いプロンプトに混在させないようにします。
- 未加工ログの正確な文字列を単一引用符で囲みます（例:
'NXDOMAIN'、'allow'）。 - マッピングがフィールド値に依存する場合は、
if ... then ... otherwise ...構造を使用して条件付きマッピングを明示的に指定します。 - 一致する UDM フィールドがないベンダー固有の属性を、明確なキー名で
additional.fieldsにマッピングするようエージェントに指示します。
次の表に、GCP DNS ログの絞り込みプロンプトの例を示します。
| 目標 | サンプル プロンプト |
|---|---|
| 不正確なマッピングを修正する | "Map jsonPayload.sourceIP to principal.ip instead of target.ip." |
| 不足しているフィールドを追加する | "Map jsonPayload.vmInstanceName to principal.hostname." |
| ネストされた値または繰り返し値をマッピングする | "Map jsonPayload.queryName to network.dns.questions.name and jsonPayload.queryType to network.dns.questions.type." |
| 条件付きロジックを適用する | "If jsonPayload.responseCode is 'NXDOMAIN', set security_result.summary to 'Domain does not exist'. Otherwise, leave it empty." |
| イベントタイプを設定する | "Set metadata.event_type to NETWORK_DNS for all DNS query logs." |
| ベンダー固有のフィールドをマッピングする | "Map jsonPayload.alias_query_response_code to additional.fields with key 'alias_query_response_code'." |
| マッピングを削除する | "Stop mapping jsonPayload.protocol to network.application_protocol." |
カスタム パーサーを送信して有効にする
UDM 出力が正確な場合は、[送信] をクリックして、生成されたカスタム パーサーを保存して有効にします。
下書きパーサーを破棄するには、[破棄] をクリックします。保存した AI 生成のカスタム パーサーを後で削除するには、パーサーを開き、[カスタム パーサーを削除] の [削除] をクリックします。
AI カスタム パーサーの生成に関するトラブルシューティング
次の表に、AI を使用してカスタム パーサーを生成する際に発生する可能性のある一般的な問題とその解決方法を示します。
| 問題または現象 | 解決策 |
|---|---|
| [AI を使用してパーサーを作成する] オプションが表示されない。 | この機能はインスタンスで有効になっていません。Google SecOps の担当者にお問い合わせください。 |
| ログタイプにログが見つからないため、生成に失敗します。 | パーサー エージェントには、選択したログタイプに対して取り込まれた未加工ログが必要です。生成を再度開始する前に、ログタイプの未加工ログを取り込みます。 |
| 別の理由で生成が失敗する。 | 生成に失敗した場合、手動トリアージ オプションは使用できません。生成を再度トリガーします。エラーが解決しない場合は、サポートにお問い合わせのうえ、サポートケースを登録してください。 |
| 生成が完了するまでに時間がかかる。 | 通常、生成には 30 ～ 90 分かかります。多数の異なる形式や大きなスキーマを持つ複雑なログソースは、より時間がかかります。ページを閉じて、後で [SIEM 設定] > [パーサー] に戻ることができます。 |
| 多くのフィールドがマッピングされていないままです。 | ログフィールドを説明するドキュメント リンクを追加して新しいセッションを開始するか、調整プロンプトを使用して不足しているフィールドをマッピングします。 |
| 絞り込みプロンプトによって、無関係なマッピングが変更された。 | フォローアップ プロンプト（"Revert the change to principal.ip and map jsonPayload.sourceIP to it again." など）で修正内容を記述します。または、パーサーを送信して有効にし、コードを手動で編集します。 |
| 一部のログが [Show UDM Output] で解析されない。 | 失敗したログを [Raw Log] ペインに貼り付け、ログの解析されていない部分を引用した改良プロンプトを送信します。 |
AI を使用してパーサー拡張機能を作成する
Google SecOps のデフォルトのログパーサーがログソースを解析するときに、お客様固有のカスタム属性、オプション フィールド、特殊なテレメトリーが省略されることがあります。AI パーサー拡張機能（AI で続きを生成）を使用すると、次のことができます。
- 未加工ログから追加のフィールドを抽出し、標準の UDM フィールドまたはカスタム
additional.fieldsにマッピングします。 - 条件付きロジックと値の変換を適用します。たとえば、文字列アクションを UDM 列挙型にマッピングします。
- 生成された拡張機能を、ゼロからではなく、マルチターン チャット セッションでインタラクティブに調整します。
プロンプトを作成するためのベスト プラクティス
正確なパーサー拡張機能を取得するには、次のプロンプト ガイドラインに従ってください。
- 未加工ログのどの部分を抽出し、どの UDM フィールドパス（
principal.ip、target.user.email_addresses、security_result.actionなど）に入力するかを明確に指定します。 - 非構造化ログのリテラル文字列、区切り文字、サンプル値は、
'198.51.100.0'や'allow'のように一重引用符で囲みます。 - 専用の UDM フィールドがない独自属性またはベンダー固有の属性を、明確なキー名（
additional.fields["application"]など）を使用してadditional.fieldsにマッピングするように AI に指示します。
パーサー拡張機能を生成する
パーサー拡張機能のワークフローは、Google SecOps の次のいずれかの場所から開始できます。
- [SIEM の設定] > [パーサー] に移動して、既存のログパーサーを選択して拡張します。
- [検索] ページでログを調査するときに、未解析のフィールドを含むイベントから拡張機能の作成フローを直接開きます。
[パーサー] ページからパーサー拡張機能を生成する手順は次のとおりです。
- Google SecOps で、[SIEM 設定] > [パーサー] に移動します。
- [パーサー] テーブルで、拡張するログタイプを検索します。
- パーサーの行で、 [メニュー] をクリックし、[パーサーを拡張 > 拡張機能を作成] を選択します。
- [未加工ログ] ペインで、サンプルの未加工ログを確認するか、 [編集] をクリックして、解析するログのサンプルを貼り付けます。
- Extension ペインの Extension Method で、Write Extension with AI を選択します。
- プロンプト フィールドに、抽出するフィールドの簡単な説明を入力します。
[確認] をクリックします。
システムが拡張機能コードを生成し、[UDM Output] ペインを更新します。
パーサー拡張機能を改良する
マルチターン チャット セッションで、パーサー拡張機能を繰り返し構築して改良できます。フォローアップ プロンプトを送信すると、AI は以前に生成された広告表示オプションに新しい指示を適用します。以前のターンで作成された既存のマッピングと条件付きロジックは、明示的にオーバーライドまたは削除をリクエストしない限り、自動的に保持されます。
- プロンプト フィールドに、生成されたコードを調整するためのフォローアップ指示を入力します。
- [確認] をクリックします。
- 各プロンプトの後、生成された拡張機能コードをプレビューし、サンプルの UDM 出力を確認して、ロジックを確認または調整します。
次のワークフローの例は、反復的な改良によって複数のターンにわたってパーサー拡張機能を構築する方法を示しています。
- ターン 1（最初の抽出）:
- ユーザー プロンプト:
"Extract source IP '198.51.100.0' to principal.ip and destination IP '198.51.100.1' to target.ip." - 結果: AI が拡張機能マッピング
principal.ipとtarget.ipを生成します。
- ユーザー プロンプト:
- ターン 2（追加マッピング）:
- ユーザー プロンプト:
"Also map virtual system string 'vsys1' to observer.administrative_domain." - 結果: AI は、ターン 1 の IP マッピングを維持しながら、
observer.administrative_domainをマッピングするように拡張機能を更新します。
- ユーザー プロンプト:
- ターン 3（条件付きの絞り込み）:
- ユーザー プロンプト:
"In addition, map action string 'allow' to security_result[0].action as ALLOW." - 結果: AI は、以前のすべての抽出に加えて、条件付きアクションの列挙型マッピングを組み込みます。
- ユーザー プロンプト:
パーサー拡張機能を検証する
- [検証] をクリックします。
- プロセスが完了したら、検証指標を確認します。
参照情報にアクセスする
次の例を使用して、パーサー拡張機能の正確なプロンプトを作成します。
構造化ログのプロンプト
データが名前付きキー、属性、XML タグに整理されている構造化ログの場合は、プロンプトでフィールド名またはパスを指定します。
構造化ログのサンプル - JSON 形式
{
"insertId": "u0mlpdesys",
"logName": "projects/sample-project-id/logs/cloudaudit.googleapis.com%2Fdata_access",
"protoPayload": {
"authenticationInfo": {
"principalEmail": "analyst@example-domain.com"
},
"methodName": "GenerateAccessToken",
"requestMetadata": {
"callerIp": "203.0.113.195",
"callerSuppliedUserAgent": "google-cloud-sdk gcloud/392.0.0"
},
"resourceName": "projects/-/serviceAccounts/110649196922301550006",
"serviceName": "iamcredentials.googleapis.com"
}
}
構造化ログのプロンプトの例
| プロンプトの指示 | ソース フィールドまたはキー | ターゲット UDM フィールド |
|---|---|---|
"Map principalEmail to principal.user.email_addresses." |
principalEmail |
principal.user.email_addresses |
"Extract callerIp to principal.ip and methodName to metadata.product_event_type." |
callerIp、methodName |
principal.ip、metadata.product_event_type |
"Map resourceName to target.resource.name and serviceName to target.application." |
resourceName、serviceName |
target.resource.name、target.application |
"From XML tags, map /Event/System/Hostname to principal.hostname." |
/Event/System/Hostname |
principal.hostname |
非構造化ログのプロンプト
非構造化ログの場合は、サンプルログ、位置参照、または説明ラベルからリテラル値を直接指定します。
非構造化 syslog メッセージの例
<14>Nov 9 18:52:45 198.51.100.1 1,2021/11/09 18:52:45,007051000184334,TRAFFIC,start,2561,2021/11/09 18:52:45,198.51.100.0,198.51.100.1,0.0.0.0,0.0.0.0,any allow,,,ping,vsys1,LAN,LAN,ethernet1/2,ethernet1/2,LFPpan,2021/11/09 18:52:45,9729,6,0,0,2048,0,0x100000,icmp,allow,444,444,0,6
非構造化ログのプロンプトの例
| プロンプトの指示 | リテラル値または説明の例 | ターゲット UDM フィールド |
|---|---|---|
"Extract source IP '198.51.100.0' to principal.ip and destination IP '198.51.100.1' to target.ip." |
'198.51.100.0'、'198.51.100.1' |
principal.ip、target.ip |
"Extract the application string 'ping' from the log and map it to additional.fields['application']." |
'ping' |
additional.fields["application"] |
"Map rule name 'any allow' to security_result.rule_id." |
'any allow' |
security_result[0].rule_id |
"Extract sent bytes and received bytes into network.sent_bytes and network.received_bytes." |
ログ内の数値バイトカウンタ | network.sent_bytes、network.received_bytes |
条件付きロジックのプロンプト
未加工のログ値を特定の UDM 列挙型に正規化する条件付きロジックについて説明します。
- 列挙型の正規化:
"If the firewall action in the log is 'allow', set security_result.action to ALLOW; otherwise set security_result.action to BLOCK." - 条件付きフィールド マッピング:
"If the protocol is 'icmp', map the ICMP type and code into network.icmp.type and network.icmp.code." - ステータスのマッピング:
"When the log status contains 'success' or '0', set security_result.severity to INFO; if it contains 'error', set it to ERROR."
使用量上限
最適なパフォーマンスとリソースの可用性を維持するため、AI Parsing 機能には次のデフォルトの使用割り当てが適用されます。
- 24 時間のローリング ウィンドウで、インスタンスごとに最大 10 個の AI カスタム パーサー生成セッションまたは AI パーサー拡張セッションを開始できます。カスタム パーサーの場合、新しいパーサーの [パーサーを生成] をクリックするたびにセッションが開始されます。
- 各セッションには、次のインタラクションの上限が適用されます。
- AI カスタム パーサーの生成では、各セッションで合計 6 ターンまでサポートされます。これには、最初の生成と最大 5 つの絞り込みプロンプトが含まれます。
- AI パーサー拡張機能の場合、各セッションでサポートされるメッセージは、最初のプロンプトと後続の絞り込みターンを含めて合計 5 件までです。
セッションのターン数またはメッセージ数の上限に達した場合は、現在の作業を送信または保存するか、新しいセッションを開始できます（1 日のセッション割り当てが適用されます）。カスタム パーサーの場合、パーサーを送信して有効にすると、他のカスタム パーサーと同様にコードを手動で編集できます。
次のステップ
- カスタム パーサーの作成と管理の詳細については、カスタム パーサーを構成するをご覧ください。
- その他のパーサー拡張メソッドの詳細については、パーサー拡張機能を開発するをご覧ください。
- 拡張機能のスニペットとシナリオの例については、パーサー拡張機能の例をご覧ください。
- 未加工ログを UDM に解析する方法の概要については、ログ解析の概要をご覧ください。
さらにサポートが必要な場合 コミュニティ メンバーや Google SecOps のプロフェッショナルから回答を得ることができます。