Skip to content

Update API docs for required_fields #5190

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 17, 2024
Merged

Update API docs for required_fields #5190

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2a7245b
Update docs for `required_fields`
nikitaindik May 9, 2024
da6bc49
Update docs/detections/api/rules/rules-api-create.asciidoc
nikitaindik May 9, 2024
41c7478
Update docs/detections/api/rules/rules-api-update.asciidoc
nikitaindik May 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/detections/api/rules/rules-api-bulk-actions.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -584,7 +584,7 @@ A rule can only be `skipped` when the bulk action to be performed on it results
],
"immutable":false,
"related_integrations": [], <1>
"required_fields": [], <1>
"required_fields": [],
"setup": "",
"type":"machine_learning",
"anomaly_threshold":50,
Expand Down Expand Up @@ -752,7 +752,7 @@ If processing of any rule fails, a partial error outputs the ID and/or name of t
"exceptions_list": [],
"immutable": false,
"related_integrations": [], <1>
"required_fields": [], <1>
"required_fields": [],
"setup": "",
"type": "query",
"language": "kuery",
Expand Down Expand Up @@ -797,7 +797,7 @@ If processing of any rule fails, a partial error outputs the ID and/or name of t
}
--------------------------------------------------

<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, `required_fields`, and `execution_summary`.
<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations` and `execution_summary`.

*Example 3, Dry run*

Expand Down
88 changes: 71 additions & 17 deletions docs/detections/api/rules/rules-api-create.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -342,6 +342,14 @@ single execution. Defaults to `100`.
|references |String[] |Array containing notes about or references to
relevant information about the rule. Defaults to an empty array.

|required_fields |Object[] a| {es} fields and their types that need to be present for the rule to function. The object has these fields:

* `name` (string, required): The field's name.
* `type` (string, required): The field's data type.
* `ecs` (Boolean, optional): Indicates whether the field is {ecs-ref}[ECS-compliant]. This property is only present in responses. Its value is computed based on field's name and type.

*NOTE*: The value of `required_fields` does not affect the rule's behavior, and specifying it incorrectly won't cause the rule to fail. Use `required_fields` as an informational property to document the fields that the rule expects to be present in the data.

|rule_id |String |Unique ID used to identify rules. For example, when a rule
is converted from a third-party security solution. Automatically created when
it is not provided.
Expand Down Expand Up @@ -815,6 +823,9 @@ POST api/detection_engine/rules
}
}
],
"required_fields": [
{ name: "process.parent.name", "type": "keyword" }
],
"enabled": false
}
--------------------------------------------------
Expand Down Expand Up @@ -852,6 +863,9 @@ POST api/detection_engine/rules
"interval": "2m",
"name": "Windows server prml-19",
"query": "host.name:prml-19 and event.category:authentication and event.outcome:failure",
"required_fields": [
{ "name": "source.ip", "type": "ip" }
],
"risk_score": 30,
"rule_id": "liv-win-ser-logins",
"severity": "low",
Expand Down Expand Up @@ -960,7 +974,15 @@ POST api/detection_engine/rules
],
"type": "eql",
"language": "eql",
"query": "sequence by process.entity_id with maxspan=2h [process where event.type in (\"start\", \"process_started\") and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\") and ((process.args == \"rundll32.exe\" and process.args_count == 1) or (process.args != \"rundll32.exe\" and process.args_count == 0))] [network where event.type == \"connection\" and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\")]"
"query": "sequence by process.entity_id with maxspan=2h [process where event.type in (\"start\", \"process_started\") and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\") and ((process.args == \"rundll32.exe\" and process.args_count == 1) or (process.args != \"rundll32.exe\" and process.args_count == 0))] [network where event.type == \"connection\" and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\")]",
"required_fields": [
{ "name": "event.type", "type": "keyword" },
{ "name": "process.args", "type": "keyword" },
{ "name": "process.args_count", "type": "long" },
{ "name": "process.entity_id", "type": "keyword" },
{ "name": "process.name", "type": "keyword" },
{ "name": "process.pe.original_file_name", "type": "keyword" }
]
}
--------------------------------------------------
// KIBANA
Expand Down Expand Up @@ -1014,6 +1036,11 @@ POST api/detection_engine/rules
]
}
],
"required_fields": [
{ "name": "destination.ip", "type": "ip" },
{ "name": "destination.port", "type": "long" },
{ "name": "host.ip", "type": "ip" }
],
"risk_score": 50,
"severity": "medium",
"name": "Bad IP threat match",
Expand Down Expand Up @@ -1049,7 +1076,11 @@ POST api/detection_engine/rules
"query": "*",
"new_terms_fields": ["user.id", "source.ip"],
"history_window_start": "now-30d",
"index": ["auditbeat*"]
"index": ["auditbeat*"],
"required_fields": [
{ "name": "user.id", "type": "keyword" },
{ "name": "source.ip", "type": "ip" }
]
}
--------------------------------------------------
// KIBANA
Expand All @@ -1073,7 +1104,10 @@ POST api/detection_engine/rules
"to": "now",
"enabled": false,
"risk_score": 21,
"severity": "low"
"severity": "low",
"required_fields": [
{ "name": "process.parent.name", "type": "keyword" }
]
}
--------------------------------------------------

Expand Down Expand Up @@ -1180,11 +1214,13 @@ Example response for a query rule:
"query": "process.parent.name:EXCEL.EXE or process.parent.name:MSPUB.EXE or process.parent.name:OUTLOOK.EXE or process.parent.name:POWERPNT.EXE or process.parent.name:VISIO.EXE or process.parent.name:WINWORD.EXE",
"language": "kuery",
"related_integrations": [], <1>
"required_fields": [], <1>
"required_fields": [
{ "name": "process.parent.name", "type": "keyword", "ecs": true }
],
"setup": ""
}
--------------------------------------------------
<1> dev:[] These fields are under development and their usage may change: `related_integrations` and `required_fields`.
<1> dev:[] These fields are under development and their usage may change: `related_integrations`.


Example response for a {ml} job rule:
Expand Down Expand Up @@ -1238,11 +1274,11 @@ Example response for a {ml} job rule:
"anomaly_threshold": 70,
"machine_learning_job_id": "linux_anomalous_network_activity_ecs",
"related_integrations": [], <1>
"required_fields": [], <1>
"required_fields": [],
"setup": ""
}
--------------------------------------------------
<1> dev:[] These fields are under development and their usage may change: `related_integrations` and `required_fields`.
<1> dev:[] These fields are under development and their usage may change: `related_integrations`.

Example response for a threshold rule:

Expand Down Expand Up @@ -1319,11 +1355,13 @@ Example response for a threshold rule:
"value": 20
},
"related_integrations": [], <1>
"required_fields": [], <1>
"required_fields": [
{ "name": "source.ip", "type": "ip", "ecs": true }
],
"setup": ""
}
--------------------------------------------------
<1> dev:[] These fields are under development and their usage may change: `related_integrations` and `required_fields`.
<1> dev:[] These fields are under development and their usage may change: `related_integrations`.

Example response for an EQL rule:

Expand Down Expand Up @@ -1364,11 +1402,18 @@ Example response for an EQL rule:
"query": "sequence by process.entity_id with maxspan=2h [process where event.type in (\"start\", \"process_started\") and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\") and ((process.args == \"rundll32.exe\" and process.args_count == 1) or (process.args != \"rundll32.exe\" and process.args_count == 0))] [network where event.type == \"connection\" and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\")]",
"language": "eql",
"related_integrations": [], <1>
"required_fields": [], <1>
"required_fields": [
{ "name": "event.type", "type": "keyword", "ecs": true },
{ "name": "process.args", "type": "keyword", "ecs": true },
{ "name": "process.args_count", "type": "long", "ecs": true },
{ "name": "process.entity_id", "type": "keyword", "ecs": true },
{ "name": "process.name", "type": "keyword", "ecs": true },
{ "name": "process.pe.original_file_name", "type": "keyword", "ecs": true }
],
"setup": ""
}
--------------------------------------------------
<1> dev:[] These fields are under development and their usage may change: `related_integrations` and `required_fields`.
<1> dev:[] These fields are under development and their usage may change: `related_integrations`.

Example response for an indicator match rule:

Expand Down Expand Up @@ -1436,11 +1481,15 @@ Example response for an indicator match rule:
}
],
"related_integrations": [], <1>
"required_fields": [], <1>
"required_fields": [
{ "name": "destination.ip", "type": "ip", "ecs": true },
{ "name": "destination.port", "type": "long", "ecs": true },
{ "name": "host.ip", "type": "ip", "ecs": true }
],
"setup": ""
}
--------------------------------------------------
<1> dev:[] These fields are under development and their usage may change: `related_integrations` and `required_fields`.
<1> dev:[] These fields are under development and their usage may change: `related_integrations`.

Example response for a new terms rule:

Expand Down Expand Up @@ -1481,11 +1530,14 @@ Example response for a new terms rule:
"new_terms_fields": ["user.id", "source.ip"],
"history_window_start": "now-30d",
"related_integrations": [], <1>
"required_fields": [], <1>
"required_fields": [
{ "name": "user.id", "type": "keyword", "ecs": true },
{ "name": "source.ip", "type": "ip", "ecs": true }
],
"setup": ""
}
--------------------------------------------------
<1> dev:[] These fields are under development and their usage may change: `related_integrations` and `required_fields`.
<1> dev:[] These fields are under development and their usage may change: `related_integrations`.

Example response for an {esql} rule:

Expand Down Expand Up @@ -1521,11 +1573,13 @@ Example response for an {esql} rule:
"rule_id": "e4b53a89-debd-4a0d-a3e3-20606952e589",
"immutable": false,
"related_integrations": [], <1>
"required_fields": [], <1>
"required_fields": [
{ "name": "process.parent.name", "type": "keyword", "ecs": true }
],
"setup": "",
"type": "esql",
"language": "esql",
"query": "from auditbeat-8.10.2 [metadata _id] | where process.parent.name == \"EXCEL.EXE\""
}
--------------------------------------------------
<1> dev:[] These fields are under development and their usage may change: `related_integrations` and `required_fields`.
<1> dev:[] These fields are under development and their usage may change: `related_integrations`.
8 changes: 6 additions & 2 deletions docs/detections/api/rules/rules-api-find.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,11 @@ Example response:
],
"to": "now",
"related_integrations": [], <1>
"required_fields": [], <1>
"required_fields": [
{ "name": "event.action", "type": "keyword", "ecs": true },
{ "name": "process.name", "type": "keyword", "ecs": true },
{ "name": "process.parent.name", "type": "keyword", "ecs": true }
],
"setup": "",
"type": "query",
"threat": [
Expand Down Expand Up @@ -138,4 +142,4 @@ Example response:

--------------------------------------------------

<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, `required_fields`, and `execution_summary`.
<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations` and `execution_summary`.
7 changes: 5 additions & 2 deletions docs/detections/api/rules/rules-api-get.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,10 @@ Example response:
"interval": "1h",
"rule_id": "process_started_by_ms_office_user_folder",
"related_integrations": [], <1>
"required_fields": [], <1>
"required_fields": [
{ "name": "process.name", "type": "keyword", "ecs": true },
{ "name": "process.parent.name", "type": "keyword", "ecs": true }
],
"setup": "",
"language": "kuery",
"max_signals": 100,
Expand Down Expand Up @@ -113,4 +116,4 @@ Example response:

--------------------------------------------------

<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, `required_fields`, and `execution_summary`.
<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, and `execution_summary`.
14 changes: 12 additions & 2 deletions docs/detections/api/rules/rules-api-update.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -244,6 +244,14 @@ single execution. Defaults to `100`.
|references |String[] |Array containing notes about or references to
relevant information about the rule. Defaults to an empty array.

|required_fields |Object[] a| {es} fields and their types that need to be present for the rule to function. The object has these fields:

* `name` (string, required): The field's name.
* `type` (string, required): The field's data type.
* `ecs` (Boolean, optional): Indicates whether the field is {ecs-ref}[ECS-compliant]. This property is only present in responses. Its value is computed based on field's name and type.

*NOTE*: The value of `required_fields` does not affect the rule's behavior, and specifying it incorrectly won't cause the rule to fail. Use `required_fields` as an informational property to document the fields that the rule expects to be present in the data.

|setup |String |Populates the rule's setup guide with instructions on rule
prerequisites such as required integrations, configuration steps, and anything
else needed for the rule to work correctly.
Expand Down Expand Up @@ -632,7 +640,9 @@ Example response:
"ms office"
],
"related_integrations": [], <1>
"required_fields": [], <1>
"required_fields": [
{ "name": "process.parent.name", "type": "keyword", "ecs": true }
],
"setup": "",
"type": "query",
"threat": [
Expand Down Expand Up @@ -669,4 +679,4 @@ Example response:
}
--------------------------------------------------

<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, `required_fields`, and `execution_summary`.
<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, and `execution_summary`.