概要

新しい検出ルールを作成したり、既存のルールを変更したりする場合]1、テンプレート変数 (属性やシグナルタグなど) と条件変数を使用して、ルールの通知メッセージをカスタマイズします。ルールからシグナルが生成されると、そのシグナルに関連する値が変数に入力されます。

テンプレート変数

テンプレート変数を使用して、トリガーされたログやトレースから動的なコンテキストをセキュリティシグナルと関連する通知に直接注入することができます。

以下の変数が利用可能です。

大量のログがルールにマッチする場合、そのルールのタイトルやメッセージは新たに到着するすべてのログに対してレンダリングされません。このような場合、{{events_matched}} および {{events_matched_per_query.<name_of_the_query>}} の表示値は、シグナルのサイドパネルの Overview タブに表示される値よりも小さくなる可能性があります。

ダイナミックリンク

テンプレート変数を使用して、調査のための関連リソースに動的にリンクします。

例えば、シグナルが疑わしいユーザーのログインを検出した場合、{{@user.id}} を使って別のリソースへのダイナミックリンクを作成します。

* [Investigate user in the authentication dashboard](https://app.datadoghq.com/example/integration/security-monitoring---authentication-events?tpl_var_username={{@usr.id}})

また、シグナルが特定のサービスとタグ付けされている場合、{{@service}} 変数を使用して動的なリンクを作成します。

* [Investigate service in the services dashboard](https://app.datadoghq.com/example/integration/application-security---service-events?tpl_var_service={{@service}})

数値の評価

数値を返すテンプレート変数では、数学的な演算を行ったり、値の形式を変更したりするために eval を使用します。より詳細な情報は、テンプレート変数の評価を参照してください。

Epoch

Epoch テンプレート変数は、通知内で人間が読みやすい文字列や数学に適した数値を作成します。例えば、関数の中で first_seen、last_seen、timestamp (ミリ秒単位) などの値を使用すると、通知内で読みやすい文字列を受け取ることができます。例:

{{eval "first_seen_epoch-15*60*1000"}}

eval 関数の詳細については、テンプレート変数の評価を参照してください。

ローカルタイム

local_time 関数を使うと、通知の中に好きなタイムゾーンで別の日付を追加することができます。この関数は、日付をローカルタイムに変換します: {{local_time "time_variable" "timezone"}}

例えば、東京のタイムゾーンで最後にトリガーされたシグナルの時刻を通知に追加するには、通知メッセージに次のように記述します。

{{local_time "last_triggered_at" "Asia/Tokyo"}}

結果は、ISO 8601 形式 yyyy-MM-dd HH:mm:ss±HH:mm で表示されます。例: 2021-05-31 23:43:27+09:00。 利用可能なタイムゾーンの値については、tz データベースのタイムゾーンリスト、特に TZ database name の列をご参照ください。

属性変数

属性変数を使用して、トリガーされたシグナルに関する特定の情報を使用してシグナル通知をカスタマイズします。

シグナルのイベント属性のリストを表示するには、シグナルのサイドパネルの Overview タブの下部にある JSON をクリックします。ルール通知にこれらのイベント属性を追加するには、構文 {{@attribute}} を使用します。イベント属性の内部キーにアクセスするには、JSON のドット表記を使用します (例: {{@attribute.inner_key}}))。

もしシグナルの JSON に、関連するログの JSON に含まれる属性がない場合は、先述の構文をログの JSON 内の属性名と併せて使用してください。すると、この属性はシグナルの JSON とシグナル通知の両方に含まれるようになります。

以下は、セキュリティシグナルに関連するイベント属性を持つ JSON オブジェクトの例です。

{
  "network": {
    "client": {
      "ip": "1.2.3.4"
    }
  },
  "usr": {
    "id": "user@domain.com"
  },
  "evt": {
    "category": "authentication",
    "outcome": "success"
  },
  "used_mfa": "false"
}

{{@usr.id}} just logged in without MFA from {{@network.client.ip}}.

user@domain.com just logged in without MFA from 1.2.3.4.

{
  "attributes":{
    "title":"Security scanner detected",
    "http":{
      "url":"http://www.example.com"
    },
    "rule":{
      "detectionMethod":"threshold",
      "name":"Your rule name"
    },
    "events_matched":2,
    "first_seen":"2022-01-26T13:23:33.000Z",
    "last_seen":"2022-01-27T04:01:57.000Z"
  },
  "groupByPaths":[
    "service"
  ]
}

Real routes targeted for {{@service}}.

Real routes targeted for your_service_name.

その他の例

シグナルに関連する IP アドレスを表示するには、{{@network.client.ip}} を使用します。

もしセキュリティルールが悪意のある IP アドレスからログインしたユーザーを検出したら、テンプレート変数 {{@usr.id}} と {{@network.client.ip}} を使って、どのユーザーと IP アドレスがシグナルを発生させたかを確認します。例:

The user {{@usr.id}} just successfully authenticated from {{@network.client.ip}} which is a known malicious IP address.

タグ変数

ルールの通知メッセージにタグ変数を追加するには、構文 {{tag_name}} を使用します。

key:value の構文に従うタグには、変数 {{key.name}} を使用します。これは、キーに関連付けられた値を通知でレンダリングします。例えば、シグナルが region というタグキーを持っている場合、通知メッセージの中で {{region.name}} という変数を使用します。

タグの値にアクセスするために @ を使用する必要はありません。

タグのキーにピリオドが含まれている場合、タグ変数を使用する際には完全なキーを括弧で囲んでください。例えば、タグが dot.key.test:five の場合、{{[dot.key.test].name}} を使用します。

ダイナミックハンドル

タグ変数を使用して、通知ハンドルを動的に構築し、生成されたセキュリティシグナルに基づいて、通知を特定のチームまたはサービスにルーティングします。 例えば、シグナルに service タグがある場合、失敗したサービスに基づいて、通知を異なる Slack チャンネルにルーティングさせることができます。

@slack-{{service.name}} There is a security issue with {{service.name}}.

例えば、シグナルに service:ad-server が指定されている場合、#ad-server Slack チャンネルに以下の内容で通知が送信されます。

@slack-ad-server There is an ongoing issue with ad-server.

条件付き変数

条件変数は、if-else ロジックを使用して、シグナルがトリガーされた詳細に基づいてメッセージを表示します。これらの変数は、タイトルや通知メッセージで使用することができます。

以下の条件付き変数を使用できます。

条件付き変数には、テキストと @通知の間に開始と終了のペアが必要です。例:

{{#is_match "<tag_variable>.name" "<comparison_string>"}}
  This displays if <comparison_string> is included in <tag_variable>.
{{/is_match}}

例

if-else ロジックで属性が存在するかどうかを確認します。

{{#if @network.client.ip}}The attribute IP attribute exists.{{/if}}

if-else ロジックで属性が値と一致するかどうかを確認します。

{{#is_exact_match "@network.client.ip" "1.2.3.4"}}The ip matched.{{/is_exact_match}}

追加情報

未加工の形式

シグナル通知が二重中括弧、例えば {{ <TEXT> }} を送る必要がある場合は {{{{raw}}}} フォーマットを使用してください。例えば、以下の構文:

{{{{raw}}}}
{{ <TEXT_1> }} {{ <TEXT_2> }}
{{{{/raw}}}}

出力:

{{ <TEXT_1> }} {{ <TEXT_2> }}

条件付き変数で使用されている ^|# ヘルパーは、{{{{raw}}}} 形式と共に使用できず、削除する必要があります。たとえば、{{is_match}} 条件付き変数を使用してテキストをそのまま出力するには、次のテンプレートを使用します。

{{{{is_match "host.name" "<HOST_NAME>"}}}}
{{ .matched }} ホスト名
{{{{/is_match}}}}

host.name が <HOST_NAME> と一致する場合、テンプレートは次を出力します。

{{ .matched }} ホスト名

URL エンコード

シグナル通知に URL でエンコードする必要がある情報が含まれている場合 (例えば、リダイレクトの場合)、{{ urlencode "<variable>"}} 構文を使います。

例: シグナルメッセージに特定のサービスにフィルタリングされたソフトウェアカタログへの URL が含まれている場合、service タグ変数を使い、URL に {{ urlencode "<variable>"}} 構文を追加します。

https://app.datadoghq.com/services/{{urlencode "service.name"}}

参考資料

お役に立つドキュメント、リンクや記事:

セキュリティ検出ルールについてドキュメント セキュリティ通知についてドキュメント