EQL search API

検索結果をイベントクエリ言語 (EQL)クエリに対して返します。

EQLは、データストリームまたはインデックス内の各ドキュメントがイベントに対応していると仮定します。

Python

  1. resp = client.eql.search(
  2.    index="my-data-stream",
  3.    query="\n    process where process.name == \"regsvr32.exe\"\n  ",
  4. )
  5. print(resp)

Ruby

  1. response = client.eql.search(
  2.   index: 'my-data-stream',
  3.   body: {
  4.    query: "\n    process where process.name == \"regsvr32.exe\"\n  "
  5.   }
  6. )
  7. puts response

Js

  1. const response = await client.eql.search({
  2.   index: "my-data-stream",
  3.   query: '\n    process where process.name == "regsvr32.exe"\n  ',
  4. });
  5. console.log(response);

Console

  1. GET /my-data-stream/_eql/search
  2. {
  3.   "query": """
  4.    process where process.name == "regsvr32.exe"
  5.   """
  6. }

Request

GET /<target>/_eql/search

POST /<target>/_eql/search

Prerequisites

  • Elasticsearchのセキュリティ機能が有効になっている場合、ターゲットデータストリーム、インデックス、またはエイリアスに対してread インデックス権限を持っている必要があります。
  • 必須フィールドを参照してください。
  • [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elasticは問題を修正するために取り組みますが、技術プレビューの機能は公式GA機能のサポートSLAの対象ではありません。 クロスクラスタ検索の場合、ローカルおよびリモートクラスタは、7.17.7（含む）以前または8.5.1（含む）以前のバージョンを使用している場合、同じElasticsearchバージョンを使用する必要があります。セキュリティについては、リモートクラスタを参照してください。

Limitations

EQLの制限を参照してください。

Path parameters

  • <target>
  • (必須、文字列) リクエストを制限するために使用されるデータストリーム、インデックス、またはエイリアスのカンマ区切りリスト。 ワイルドカード(*)をサポートします。すべてのデータストリームとインデックスを検索するには、*または_allを使用します。
    [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elasticは問題を修正するために取り組みますが、技術プレビューの機能は公式GA機能のサポートSLAの対象ではありません。 リモートクラスタを検索するには、<cluster>:<target>構文を使用します。クラスタ間でEQL検索を実行するを参照してください。

Query parameters

  • allow_no_indices
  • (オプション、Boolean)
    このパラメータの動作は、他のmulti-target APIsで使用されるallow_no_indicesパラメータとは異なります。
    falseの場合、リクエストは、ワイルドカードパターン、エイリアス、または_all値が欠落または閉じたインデックスのみをターゲットにする場合にエラーを返します。この動作は、リクエストが他のオープンインデックスをターゲットにしている場合でも適用されます。たとえば、foo*,bar*をターゲットにするリクエストは、fooで始まるインデックスがあるが、barで始まるインデックスがない場合にエラーを返します。
    trueの場合、欠落または閉じたインデックスのみをターゲットにするリクエストがエラーを返します。たとえば、foo*,bar*をターゲットにするリクエストは、fooで始まるインデックスがあるが、barで始まるインデックスがない場合にエラーを返しません。ただし、bar*のみをターゲットにするリクエストは、依然としてエラーを返します。
    デフォルトはtrueです。
  • ccs_minimize_roundtrips
  • (オプション、Boolean) trueの場合、クロスクラスタ検索（CCS）リクエストを実行する際に、ローカルとリモートクラスタ間のネットワークラウンドトリップが最小限に抑えられます。
    このオプションは、1つのリモートクラスタに完全に含まれるデータをターゲットにするリクエストに対して有効です。データが複数のクラスタに分散している場合、この設定は無視されます。
    デフォルトはtrueです。
  • expand_wildcards
  • (オプション、文字列) ワイルドカードパターンが一致できるインデックスのタイプ。リクエストがデータストリームをターゲットにできる場合、この引数はワイルドカード式が隠しデータストリームに一致するかどうかを決定します。カンマ区切りの値をサポートします。open,hiddenのような。 有効な値は：
    • all
    • すべてのデータストリームまたはインデックスに一致します。隠しのものも含まれます。
    • open
    • オープンで非隠しのインデックスに一致します。非隠しデータストリームにも一致します。
    • closed
    • クローズドで非隠しのインデックスに一致します。非隠しデータストリームにも一致します。データストリームはクローズできません。
    • hidden
    • 隠しデータストリームと隠しインデックスに一致します。open、closed、またはその両方と組み合わせる必要があります。
    • none
    • ワイルドカードパターンは受け付けられません。
      デフォルトはopenです。
  • filter_path
  • (オプション、文字列) APIレスポンスのフィルタのカンマ区切りリスト。レスポンスフィルタリングを参照してください。
  • ignore_unavailable
  • (オプション、Boolean) falseの場合、リクエストが欠落または閉じたインデックスをターゲットにする場合、エラーを返します。デフォルトはtrueです。
  • keep_alive
  • (オプション、時間値) 検索とその結果がクラスタに保存される期間。デフォルトは5d（5日）です。
    この期間が終了すると、検索とその結果は削除されます。検索がまだ進行中であっても。
    keep_on_completionパラメータがfalseの場合、Elasticsearchは、非同期検索のうち、wait_for_completion_timeoutパラメータで設定された期間内に完了しないもののみを保存します。この値に関係なく。
    この値は、keep_aliveリクエストボディパラメータを使用して指定することもできます。両方のパラメータが指定されている場合、クエリパラメータのみが使用されます。
  • keep_on_completion
  • (オプション、Boolean) trueの場合、検索とその結果はクラスタに保存されます。
    falseの場合、リクエストがwait_for_completion_timeoutパラメータで設定された期間内に完了しない場合にのみ、検索とその結果がクラスタに保存されます。デフォルトはfalseです。
    この値は、keep_on_completionリクエストボディパラメータを使用して指定することもできます。両方のパラメータが指定されている場合、クエリパラメータのみが使用されます。
  • wait_for_completion_timeout
  • (オプション、時間値) リクエストが完了するまで待機するタイムアウトの期間。デフォルトはタイムアウトなし、つまりリクエストは完全な検索結果を待機します。
    このパラメータが指定され、リクエストがこの期間内に完了した場合、完全な検索結果が返されます。
    この期間内にリクエストが完了しない場合、検索は非同期検索になります。
    この値は、wait_for_completion_timeoutリクエストボディパラメータを使用して指定することもできます。両方のパラメータが指定されている場合、クエリパラメータのみが使用されます。

Request body

  • event_category_field
  • (必須*、文字列) イベント分類を含むフィールド、process、file、またはnetworkなど。
    デフォルトは、Elastic Common Schema (ECS)で定義されているevent.categoryです。データストリームまたはインデックスにevent.categoryフィールドが含まれていない場合、この値は必須です。
    イベントカテゴリフィールドは、keywordファミリーのフィールドタイプとしてマッピングされている必要があります。
  • fetch_size
  • (オプション、整数) シーケンスクエリのために一度に検索する最大イベント数。デフォルトは1000です。
    この値は2より大きくなければなりませんが、index.max_result_window設定の値を超えることはできません。デフォルトは10000です。
    内部的に、シーケンスクエリは、マッチを検索するためにイベントのセットを取得し、ページネートします。このパラメータは、それらのセットのサイズを制御します。このパラメータは、検索されるイベントの総数や返される一致イベントの数を制限するものではありません。
    大きなfetch_size値は、検索速度を向上させることが多いですが、より多くのメモリを使用します。
  • fields
  • (オプション、文字列とオブジェクトの配列) フィールドパターンの配列。リクエストは、レスポンスのhits.fieldsプロパティ内でこれらのパターンに一致するフィールド名の値を返します。
    配列内のアイテムは、文字列またはオブジェクトとして指定できます。fieldsオプションを参照してください。 
    1. -   `````field
    • (必須、文字列) 返すフィールド。ワイルドカード(*)をサポートします。
    • format
    • (オプション、文字列) 日付および地理空間フィールドのフォーマット。他のフィールドデータタイプはこのパラメータをサポートしていません。
      dateおよびdate_nanosフィールドは、日付フォーマットを受け入れます。geo_pointおよびgeo_shapeフィールドは次のものを受け入れます：
      • geojson (デフォルト)
      • GeoJSON
      • wkt
      • Well Known Text
      • mvt(<spec>)
      • バイナリMapboxベクタタイル。APIは、タイルをbase64エンコードされた文字列として返します。<spec>は、<zoom>/<x>/<y>の形式で、2つのオプションのサフィックス@<extent>および/または:<buffer>を持ちます。たとえば、2/0/1または2/0/1@4096:5。
        mvtパラメータ
      • <zoom>
      • (必須、整数) タイルのズームレベル。0-29を受け入れます。
      • <x>
      • (必須、整数) タイルのX座標。
      • <y>
      • (必須、整数) タイルのY座標。
      • <extent>
      • (オプション、整数) タイルの一辺のサイズ（ピクセル単位）。ベクタタイルは、等しい辺を持つ正方形です。デフォルトは4096です。
      • <buffer>
      • (オプション、整数) タイルの外側のクリッピングバッファのサイズ（ピクセル単位）。これにより、レンダラーはタイルの範囲を超えて拡張するジオメトリからのアウトラインアーティファクトを回避できます。デフォルトは5です。
  • filter
  • (オプション、Query DSLオブジェクト) EQLクエリが実行されるイベントをフィルタリングするために使用されるクエリ、Query DSLで記述されています。
  • keep_alive

  • (オプション、時間値) 検索とその結果がクラスタに保存される期間。デフォルトは5d（5日）です。
    この期間が終了すると、検索とその結果は削除されます。検索がまだ進行中であっても。
    keep_on_completionパラメータがfalseの場合、Elasticsearchは、非同期検索のうち、wait_for_completion_timeoutパラメータで設定された期間内に完了しないもののみを保存します。この値に関係なく。
    この値は、keep_aliveクエリパラメータを使用して指定することもできます。両方のパラメータが指定されている場合、クエリパラメータのみが使用されます。

  • keep_on_completion

  • (オプション、Boolean) trueの場合、検索とその結果はクラスタに保存されます。
    falseの場合、リクエストがwait_for_completion_timeoutパラメータで設定された期間内に完了しない場合にのみ、検索とその結果がクラスタに保存されます。デフォルトはfalseです。
    この値は、keep_on_completionクエリパラメータを使用して指定することもできます。両方のパラメータが指定されている場合、クエリパラメータのみが使用されます。

  • query
  • (必須、文字列) 実行したいEQLクエリ。
  • result_position
  • (オプション、列挙型) 返す一致イベントまたはシーケンスのセット。 
    1. -   `````tail
    • (デフォルト) 最も最近の一致を返します。Unix tailコマンドに似ています。
    • head
    • 最も古い一致を返します。Unix headコマンドに似ています。
      このパラメータは、返されるヒットのセットを変更する可能性があります。ただし、レスポンス内のヒットのソート順序は変更されません。
  • runtime_mappings
  • (オプション、オブジェクトのオブジェクト) 検索リクエスト内の1つ以上のランタイムフィールドを定義します。これらのフィールドは、同じ名前のマッピングされたフィールドよりも優先されます。 
    1. -   `````<field-name>
    • (必須、オブジェクト) ランタイムフィールドの設定。キーはフィールド名です。 
      1. -   `````type
      • (必須、文字列) フィールドタイプ、次のいずれかである必要があります：
      • boolean
      • composite
      • date
      • double
      • geo_point
      • ip
      • keyword
      • long
      • lookup
      • script
      • (オプション、文字列) クエリ時に実行されるPainlessスクリプト。スクリプトは、元の_sourceおよびマッピングされたフィールドとその値を含むドキュメントの全コンテキストにアクセスできます。
        このスクリプトは、計算された値を返すためにemitを含める必要があります。たとえば：

Js

  1. "script": "emit(doc['@timestamp'].value.dayOfWeekEnum.toString())"

  • size

  • (オプション、整数または浮動小数点) 基本クエリの場合、一致するイベントの最大数を返します。
    シーケンスクエリの場合、一致するシーケンスの最大数を返します。
    デフォルトは10です。この値は0より大きくなければなりません。
    パイプを使用して、この値を超えることはできません。headまたはtailのように。

  • tiebreaker_field

  • (オプション、文字列) 同じタイムスタンプを持つヒットを昇順にソートするために使用されるフィールド。ソートのタイブレイカーを指定するを参照してください。

  • timestamp_field

  • (必須*、文字列) イベントのタイムスタンプを含むフィールド。
    デフォルトは、Elastic Common Schema (ECS)で定義されている@timestampです。データストリームまたはインデックスに@timestampフィールドが含まれていない場合、この値は必須です。
    APIレスポンス内のイベントは、このフィールドの値に基づいて、Unix epochからのミリ秒に変換され、昇順にソートされます。
    タイムスタンプフィールドは、dateとしてマッピングされる必要があります。date_nanosフィールドタイプはサポートされていません。

  • wait_for_completion_timeout
  • (オプション、時間値) リクエストが完了するまで待機するタイムアウトの期間。デフォルトはタイムアウトなし、つまりリクエストは完全な検索結果を待機します。
    このパラメータが指定され、リクエストがこの期間内に完了した場合、完全な検索結果が返されます。
    この期間内にリクエストが完了しない場合、検索は非同期検索になります。
    この値は、wait_for_completion_timeoutクエリパラメータを使用して指定することもできます。両方のパラメータが指定されている場合、クエリパラメータのみが使用されます。

Response body

  • id
  • (文字列) 検索の識別子。
    この検索IDは、次のいずれかの条件が満たされた場合にのみ提供されます：
  • is_partial
  • (Boolean) trueの場合、レスポンスには完全な検索結果が含まれていません。
  • is_running
  • (Boolean) trueの場合、検索リクエストはまだ実行中です。
    このパラメータとis_partialパラメータがtrueの場合、検索は進行中の非同期検索です。keep_alive期間が経過しない場合、検索が完了すると完全な検索結果が利用可能になります。
    is_partialがtrueで、is_runningがfalseの場合、検索は失敗により部分的な結果を返しました。いくつかのシャードが結果を返すか、検索を調整するノードが失敗しました。
  • took
  • (整数) Elasticsearchがリクエストを実行するのにかかったミリ秒。
    この値は、リクエストが調整ノードで受信されてから、調整ノードがレスポンスを送信する準備ができるまでの経過時間を測定することによって計算されます。
    かかった時間には次が含まれます：
    • 調整ノードとデータノード間の通信時間
    • リクエストがsearch スレッドプールで実行待ちの時間
    • 実際の実行時間
      かかった時間には含まれません：
    • Elasticsearchにリクエストを送信するのに必要な時間
    • JSONレスポンスをシリアライズするのに必要な時間
    • クライアントにレスポンスを送信するのに必要な時間
  • timed_out
  • (Boolean) trueの場合、リクエストは完了前にタイムアウトしました。
  • hits
  • (オブジェクト) 一致するイベントとシーケンスを含みます。また、関連するメタデータも含まれます。 
    1. -   `````total
    • (オブジェクト) 一致するイベントまたはシーケンスの数に関するメタデータ。 
      1. -   `````value
      • (整数) 基本クエリの場合、一致するイベントの総数。
        シーケンスクエリの場合、一致するシーケンスの総数。
      • relation
      • (文字列) 返されたイベントまたはシーケンスの数が正確であるか、下限であるかを示します。
        返された値は：
      • eq
      • 正確
      • gte
      • 下限、返されたイベントまたはシーケンスを含む
    • sequences
    • (オブジェクトの配列) クエリに一致するイベントシーケンスを含みます。各オブジェクトは一致するシーケンスを表します。このパラメータは、シーケンスを含むEQLクエリに対してのみ返されます。 
      1. -   `````join_keys
      • (値の配列) シーケンス内の一致を制約するために使用される共有フィールド値。これらは、EQLクエリ構文内のbyキーワードを使用して定義されます。
      • events
      • (オブジェクトの配列) クエリに一致するイベントを含みます。各オブジェクトは一致するイベントを表します。
        eventsオブジェクトのプロパティ
      • _index
      • (文字列) イベントを含むインデックスの名前。
      • _id
      • (文字列) イベントの一意の識別子。このIDはインデックス内でのみ一意です。
      • _source
      • (オブジェクト) インデックス時にイベントに渡された元のJSONボディ。
    • events
    • (オブジェクトの配列) クエリに一致するイベントを含みます。各オブジェクトは一致するイベントを表します。 
      1. -   `````_index
      • (文字列) イベントを含むインデックスの名前。
      • _id
      • (文字列) イベントの一意の識別子。このIDはインデックス内でのみ一意です。
      • _source
      • (オブジェクト) インデックス時にイベントに渡された元のJSONボディ。

Examples

Basic query example

次のEQL検索リクエストは、次の条件を満たすprocessのevent.categoryを持つイベントを検索します：

  • cmd.exeのprocess.name
  • 2013以外のprocess.pid

Python

  1. resp = client.eql.search(
  2.    index="my-data-stream",
  3.    query="\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  ",
  4. )
  5. print(resp)

Ruby

  1. response = client.eql.search(
  2.   index: 'my-data-stream',
  3.   body: {
  4.    query: "\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  "
  5.   }
  6. )
  7. puts response

Js

  1. const response = await client.eql.search({
  2.   index: "my-data-stream",
  3.   query:
  4.    '\n    process where (process.name == "cmd.exe" and process.pid != 2013)\n  ',
  5. });
  6. console.log(response);

Console

  1. GET /my-data-stream/_eql/search
  2. {
  3.   "query": """
  4.    process where (process.name == "cmd.exe" and process.pid != 2013)
  5.   """
  6. }

APIは次のレスポンスを返します。hits.eventsプロパティ内の一致するイベントは、タイムスタンプに基づいて、Unix epochからのミリ秒に変換され、昇順にソートされます。

2つ以上のイベントが同じタイムスタンプを共有する場合、tiebreaker_fieldフィールドが使用されて、イベントが昇順にソートされます。

Console-Result

  1. {
  2.   "is_partial": false,
  3.   "is_running": false,
  4.   "took": 6,
  5.   "timed_out": false,
  6.   "hits": {
  7.    "total": {
  8.    "value": 2,
  9.    "relation": "eq"
  10.    },
  11.    "events": [
  12.    {
  13.    "_index": ".ds-my-data-stream-2099.12.07-000001",
  14.    "_id": "babI3XMBI9IjHuIqU0S_",
  15.    "_source": {
  16.    "@timestamp": "2099-12-06T11:04:05.000Z",
  17.    "event": {
  18.    "category": "process",
  19.    "id": "edwCRnyD",
  20.    "sequence": 1
  21.    },
  22.    "process": {
  23.    "pid": 2012,
  24.    "name": "cmd.exe",
  25.    "executable": "C:\\Windows\\System32\\cmd.exe"
  26.    }
  27.    }
  28.    },
  29.    {
  30.    "_index": ".ds-my-data-stream-2099.12.07-000001",
  31.    "_id": "b6bI3XMBI9IjHuIqU0S_",
  32.    "_source": {
  33.    "@timestamp": "2099-12-07T11:06:07.000Z",
  34.    "event": {
  35.    "category": "process",
  36.    "id": "cMyt5SZ2",
  37.    "sequence": 3
  38.    },
  39.    "process": {
  40.    "pid": 2012,
  41.    "name": "cmd.exe",
  42.    "executable": "C:\\Windows\\System32\\cmd.exe"
  43.    }
  44.    }
  45.    }
  46.    ]
  47.   }
  48. }

Sequence query example

次のEQL検索リクエストは、次の条件を満たすイベントのシーケンスに一致します：

  • 1. 次のイベントで開始します：
    • fileのevent.category
    • cmd.exeのfile.name
    • 2013以外のprocess.pid
  • 2. 次のイベントに続きます：
    • processのevent.category
    • regsvr32を含むprocess.executable

これらのイベントは、同じprocess.pid値を共有する必要があります。

Python

  1. resp = client.eql.search(
  2.    index="my-data-stream",
  3.    query="\n    sequence by process.pid\n      [ file where file.name == \"cmd.exe\" and process.pid != 2013 ]\n      [ process where stringContains(process.executable, \"regsvr32\") ]\n  ",
  4. )
  5. print(resp)

Ruby

  1. response = client.eql.search(
  2.   index: 'my-data-stream',
  3.   body: {
  4.    query: "\n    sequence by process.pid\n      [ file where file.name == \"cmd.exe\" and process.pid != 2013 ]\n      [ process where stringContains(process.executable, \"regsvr32\") ]\n  "
  5.   }
  6. )
  7. puts response

Js

  1. const response = await client.eql.search({
  2.   index: "my-data-stream",
  3.   query:
  4.    '\n    sequence by process.pid\n      [ file where file.name == "cmd.exe" and process.pid != 2013 ]\n      [ process where stringContains(process.executable, "regsvr32") ]\n  ',
  5. });
  6. console.log(response);

Console

  1. GET /my-data-stream/_eql/search
  2. {
  3.   "query": """
  4.    sequence by process.pid
  5.    [ file where file.name == "cmd.exe" and process.pid != 2013 ]
  6.    [ process where stringContains(process.executable, "regsvr32") ]
  7.   """
  8. }

APIは次のレスポンスを返します。一致するシーケンスはhits.sequencesプロパティに含まれています。hits.sequences.join_keysプロパティには、各一致イベントの共有process.pid値が含まれています。

Console-Result

  1. {
  2.   "is_partial": false,
  3.   "is_running": false,
  4.   "took": 6,
  5.   "timed_out": false,
  6.   "hits": {
  7.    "total": {
  8.    "value": 1,
  9.    "relation": "eq"
  10.    },
  11.    "sequences": [
  12.    {
  13.    "join_keys": [
  14.    2012
  15.    ],
  16.    "events": [
  17.    {
  18.    "_index": ".ds-my-data-stream-2099.12.07-000001",
  19.    "_id": "AtOJ4UjUBAAx3XR5kcCM",
  20.    "_source": {
  21.    "@timestamp": "2099-12-06T11:04:07.000Z",
  22.    "event": {
  23.    "category": "file",
  24.    "id": "dGCHwoeS",
  25.    "sequence": 2
  26.    },
  27.    "file": {
  28.    "accessed": "2099-12-07T11:07:08.000Z",
  29.    "name": "cmd.exe",
  30.    "path": "C:\\Windows\\System32\\cmd.exe",
  31.    "type": "file",
  32.    "size": 16384
  33.    },
  34.    "process": {
  35.    "pid": 2012,
  36.    "name": "cmd.exe",
  37.    "executable": "C:\\Windows\\System32\\cmd.exe"
  38.    }
  39.    }
  40.    },
  41.    {
  42.    "_index": ".ds-my-data-stream-2099.12.07-000001",
  43.    "_id": "OQmfCaduce8zoHT93o4H",
  44.    "_source": {
  45.    "@timestamp": "2099-12-07T11:07:09.000Z",
  46.    "event": {
  47.    "category": "process",
  48.    "id": "aR3NWVOs",
  49.    "sequence": 4
  50.    },
  51.    "process": {
  52.    "pid": 2012,
  53.    "name": "regsvr32.exe",
  54.    "command_line": "regsvr32.exe  /s /u /i:https://...RegSvr32.sct scrobj.dll",
  55.    "executable": "C:\\Windows\\System32\\regsvr32.exe"
  56.    }
  57.    }
  58.    }
  59.    ]
  60.    }
  61.    ]
  62.   }
  63. }