From 6d3f12b7bc613f178747c9579f78f0d68dd6518f Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com> Date: Tue, 17 Jun 2025 17:07:07 +0100 Subject: [PATCH] Deletes Detections APIs (#6872) * Deletes Detections APIs * update references * update reference * revert 8.8 URLs * Adds chapter tag (cherry picked from commit f273f0ccf9d63f1235e049ba8324af781d33704f) --- docs/detections/api/det-api-index.asciidoc | 31 - .../api/rules/index-api-overview.asciidoc | 138 -- .../rules/privileges-api-overview.asciidoc | 111 -- .../api/rules/rules-api-bulk-actions.asciidoc | 909 ---------- ...reate-rule-default-exception-list.asciidoc | 104 -- ...create-single-rule-exception-item.asciidoc | 193 -- .../api/rules/rules-api-create.asciidoc | 1604 ----------------- .../api/rules/rules-api-delete.asciidoc | 36 - .../api/rules/rules-api-export.asciidoc | 101 -- .../api/rules/rules-api-find.asciidoc | 153 -- .../api/rules/rules-api-get.asciidoc | 127 -- .../api/rules/rules-api-import.asciidoc | 98 - .../api/rules/rules-api-overview.asciidoc | 72 - .../api/rules/rules-api-prebuilt.asciidoc | 86 - .../api/rules/rules-api-update.asciidoc | 698 ------- .../api/rules/signals-api-overview.asciidoc | 444 ----- .../api/rules/tags-api-overview.asciidoc | 50 - .../api/signals-migration-api.asciidoc | 241 --- .../detection-engine-intro.asciidoc | 3 +- docs/detections/rules-ui-create.asciidoc | 2 +- .../post-upgrade-req-cti-alerts.asciidoc | 2 +- docs/post-upgrade/post-upgrade-req.asciidoc | 2 +- docs/release-notes/8.0.asciidoc | 4 +- docs/release-notes/8.12.asciidoc | 2 +- docs/release-notes/8.2.asciidoc | 8 +- docs/release-notes/8.5.asciidoc | 8 +- docs/siem-apis.asciidoc | 9 +- docs/upgrade/upgrade-7.17-8.x.asciidoc | 4 +- docs/upgrade/upgrade-security.asciidoc | 2 +- 29 files changed, 20 insertions(+), 5222 deletions(-) delete mode 100644 docs/detections/api/det-api-index.asciidoc delete mode 100644 docs/detections/api/rules/index-api-overview.asciidoc delete mode 100644 docs/detections/api/rules/privileges-api-overview.asciidoc delete mode 100644 docs/detections/api/rules/rules-api-bulk-actions.asciidoc delete mode 100644 docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc delete mode 100644 docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc delete mode 100644 docs/detections/api/rules/rules-api-create.asciidoc delete mode 100644 docs/detections/api/rules/rules-api-delete.asciidoc delete mode 100644 docs/detections/api/rules/rules-api-export.asciidoc delete mode 100644 docs/detections/api/rules/rules-api-find.asciidoc delete mode 100644 docs/detections/api/rules/rules-api-get.asciidoc delete mode 100644 docs/detections/api/rules/rules-api-import.asciidoc delete mode 100644 docs/detections/api/rules/rules-api-overview.asciidoc delete mode 100644 docs/detections/api/rules/rules-api-prebuilt.asciidoc delete mode 100644 docs/detections/api/rules/rules-api-update.asciidoc delete mode 100644 docs/detections/api/rules/signals-api-overview.asciidoc delete mode 100644 docs/detections/api/rules/tags-api-overview.asciidoc delete mode 100644 docs/detections/api/signals-migration-api.asciidoc diff --git a/docs/detections/api/det-api-index.asciidoc b/docs/detections/api/det-api-index.asciidoc deleted file mode 100644 index aea3c3b548..0000000000 --- a/docs/detections/api/det-api-index.asciidoc +++ /dev/null @@ -1,31 +0,0 @@ -include::rules/rules-api-overview.asciidoc[] - -include::rules/rules-api-create.asciidoc[] - -include::rules/rules-api-get.asciidoc[] - -include::rules/rules-api-find.asciidoc[] - -include::rules/rules-api-update.asciidoc[] - -include::rules/rules-api-delete.asciidoc[] - -include::rules/rules-api-bulk-actions.asciidoc[] - -include::rules/rules-api-create-rule-default-exception-list.asciidoc[] - -include::rules/rules-api-create-single-rule-exception-item.asciidoc[] - -include::rules/index-api-overview.asciidoc[] - -include::rules/tags-api-overview.asciidoc[] - -include::rules/rules-api-import.asciidoc[] - -include::rules/rules-api-export.asciidoc[] - -include::rules/privileges-api-overview.asciidoc[] - -include::rules/signals-api-overview.asciidoc[] - -include::rules/rules-api-prebuilt.asciidoc[] diff --git a/docs/detections/api/rules/index-api-overview.asciidoc b/docs/detections/api/rules/index-api-overview.asciidoc deleted file mode 100644 index 912ce99c6f..0000000000 --- a/docs/detections/api/rules/index-api-overview.asciidoc +++ /dev/null @@ -1,138 +0,0 @@ -[[index-api-overview]] -=== Index endpoint - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-detections-api[detections APIs]. --- - -You use the index endpoint to create, get, and delete -`.siem-signals-` system indices in a {kib} space. - -NOTE: Signal indices store detection alerts. - -For information about the permissions and privileges required to create -`.siem-signals-` indices, see <>. - -When you create a signal index, the following -{ref}/getting-started-index-lifecycle-management.html[{ilm} ({ilm-init})] -policy is created for the signal index: -[source,js] --------------------------------------------------- -{ - "policy": { - "phases": { - "hot": { - "min_age": "0ms", - "actions": { - "rollover": { - "max_size": "50gb", - "max_age": "30d" - } - } - } - } - } -} --------------------------------------------------- - -The `policy` and `rollover_alias` use the same name as the signal index. - -NOTE: To reduce clutter on your hot tier, we highly recommend adding a {ref}/ilm-delete.html[delete action] to this {ilm-init} policy. Otherwise, the signal indices will remain on your hot tier indefinitely. - -==== Create index - -Creates a signal index. The naming convention for the index is -`.siem-signals-`. - -===== Request URL - -`POST :/api/detection_engine/index` - -====== Example request - -Creates a signal index in the {kib} `siem` space. - -[source,console] --------------------------------------------------- -POST s/siem/api/detection_engine/index --------------------------------------------------- -// KIBANA - -===== Response code - -`200`:: - Indicates a successful call. - -==== Get index - -Gets the signal index name if it exists. - -===== Request URL - -`GET :/api/detection_engine/index` - -====== Example request - -Gets the signal index for the {kib} `siem` space: - -[source,console] --------------------------------------------------- -GET s/siem/api/detection_engine/index --------------------------------------------------- -// KIBANA - -===== Response code - -`200`:: - Indicates a successful call. -`404`:: - Indicates no index exists. - -====== Example responses - -Example response when index exists: - -[source,json] --------------------------------------------------- -{ - "name": ".siem-signals-siem" -} --------------------------------------------------- - -Example response when no index exists: - -[source,json] --------------------------------------------------- -{ - "statusCode": 404, - "error": "Not Found", - "message": "index for this space does not exist" -} --------------------------------------------------- - -==== Delete index - -Deletes the signal index. - -NOTE: This deletes {elastic-sec} 7.x signals indices (`.siem-signals-`) only. It _does not_ delete 8.x alert indices (`.alerts-security.alerts-`). - -===== Request URL - -`DELETE :/api/detection_engine/index` - -====== Example request - -Deletes the signal index for the {kib} `siem` space: - -[source, js] --------------------------------------------------- -DELETE s/siem/api/detection_engine/index --------------------------------------------------- -// KIBANA - -===== Response code - -`200`:: - Indicates a successful call. diff --git a/docs/detections/api/rules/privileges-api-overview.asciidoc b/docs/detections/api/rules/privileges-api-overview.asciidoc deleted file mode 100644 index cb5bb87df7..0000000000 --- a/docs/detections/api/rules/privileges-api-overview.asciidoc +++ /dev/null @@ -1,111 +0,0 @@ -[[privileges-api-overview]] -[role="xpack"] -=== Privileges endpoint - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-detections-api[detections APIs]. --- - -Retrieves whether or not the user is authenticated, and the user's {kib} space -and index privileges, which determine if the user can create an index -(`.siem-signals-*`) for the {elastic-sec} alerts generated by detection engine rules. - -For information about the permissions and privileges required to create -`.siem-signals-` indices, see <>. - -==== Get privileges - -Returns user privileges for the {kib} space. - -===== Request URL - -`GET :/api/detection_engine/privileges` - -====== Example requests - -Gets user privileges for the {kib} default space: - -[source,console] --------------------------------------------------- -GET api/detection_engine/privileges --------------------------------------------------- -// KIBANA - -Gets user privileges for the {kib} `siem` space: - -[source,console] --------------------------------------------------- -GET s/siem/api/detection_engine/privileges --------------------------------------------------- -// KIBANA - -===== Response code - -`200`:: - Indicates a successful call. - -====== Example response - -[source,js] --------------------------------------------------- -{ - "username": "detection-engine-admin", - "has_all_requested": false, - "cluster": { - "monitor_ml": true, - "manage_ccr": false, - "manage_index_templates": true, - "monitor_watcher": true, - "monitor_transform": true, - "read_ilm": true, - "manage_api_key": false, - "manage_security": false, - "manage_own_api_key": false, - "manage_saml": false, - "all": false, - "manage_ilm": true, - "manage_ingest_pipelines": true, - "read_ccr": false, - "manage_rollup": true, - "monitor": true, - "manage_watcher": true, - "manage": true, - "manage_transform": true, - "manage_token": false, - "manage_ml": true, - "manage_pipeline": true, - "monitor_rollup": true, - "transport_client": true, - "create_snapshot": true - }, - "index": { - ".siem-signals-detection-engine": { - "all": false, - "manage_ilm": true, - "read": false, - "create_index": true, - "read_cross_cluster": false, - "index": false, - "monitor": true, - "delete": false, - "manage": true, - "delete_index": true, - "create_doc": false, - "view_index_metadata": true, - "create": false, - "manage_follow_index": true, - "manage_leader_index": true, - "write": false - } - }, - "application": {} - "is_authenticated": true <1> - "has_encryption_key": true <2> -} --------------------------------------------------- -<1> Indicates whether the user can log in to the {es} deployment. -<2> Indicates whether the -<> is -set. diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc deleted file mode 100644 index 82fc698721..0000000000 --- a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc +++ /dev/null @@ -1,909 +0,0 @@ -:api-call: create-rule -[[bulk-actions-rules-api]] -=== Bulk rule actions - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-detections-api[detections APIs]. --- - -You can bulk create, update, and delete rules. - -''' - -[discrete] -[[bulk-actions-rules-api-create]] -==== Bulk create - -IMPORTANT: This API has been deprecated since version 8.2, and is scheduled for end of life in 2024. Please use the <> instead. - -[WARNING] -==== -When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running. - -If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change. -==== - -Creates new rules. - -[discrete] -===== Request URL - -`POST :/api/detection_engine/rules/_bulk_create` - -[discrete] -===== Request body - -A JSON array of rules, where each rule contains the -<>. - -[discrete] -===== Example request - -[source,console] --------------------------------------------------- -POST api/detection_engine/rules/_bulk_create -[ - { - "rule_id": "process_started_by_ms_office_program_possible_payload", - "risk_score": 50, - "description": "Process started by MS Office program - possible payload", - "interval": "5m", - "name": "MS Office child process", - "severity": "low", - "tags": [ - "child process", - "ms office" - ], - "type": "query", - "from": "now-6m", - "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", - "filters": [ - { - "query": { - "match": { - "event.action": { - "query": "Process Create (rule: ProcessCreate)", - "type": "phrase" - } - } - } - } - ], - "enabled": false - }, - { - "name": "Second bulk rule", - "description": "Query with a rule_id for referencing an external id", - "rule_id": "query-rule-id-2", - "risk_score": 2, - "severity": "low", - "type": "query", - "from": "now-6m", - "query": "user.name: root or user.name: admin" - } -] --------------------------------------------------- -// KIBANA - -[discrete] -===== Response code - -`200`:: - Indicates a successful call. - -[discrete] -===== Response payload - -A JSON array that includes a unique ID for each rule. A unique rule ID is -generated for all rules that did not include a `rule_id` field. - -''' - -[discrete] -[[bulk-actions-rules-api-delete]] -==== Bulk delete - -IMPORTANT: This API has been deprecated since version 8.2, and is scheduled for end of life in 2024. Please use the <> instead. - -Deletes multiple rules. - -[discrete] -===== Request URL - -`DELETE :/api/detection_engine/rules/_bulk_delete` - -[discrete] -===== Request body - -A JSON array of `id` or `rule_id` fields of the rules you want to delete. - -[discrete] -===== Example request - -[source,console] --------------------------------------------------- -DELETE api/detection_engine/rules/_bulk_delete -[ - { - "rule_id": "process_started_by_ms_office_program_possible_payload" - }, - { - "id": "51658332-a15e-4c9e-912a-67214e2e2359" - } -] --------------------------------------------------- -// KIBANA - -[discrete] -===== Response code - -`200`:: - Indicates a successful call. - -[discrete] -===== Response payload - -A JSON array containing the deleted rules. - -''' - -[discrete] -[[bulk-actions-rules-api-update]] -==== Bulk update - -IMPORTANT: This API has been deprecated since version 8.2, and is scheduled for end of life in 2024. Please use the <> instead. - -[WARNING] -==== -When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running. - -If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change. -==== - -Updates multiple rules. - -You can use `PUT` or `PATCH` methods to bulk update rules, where: - -* `PUT` replaces the original rule and deletes fields that are not specified. -* `PATCH` updates the specified fields. - -[discrete] -===== Request URL - -`PUT :/api/detection_engine/rules/_bulk_update` - -`PATCH :/api/detection_engine/rules/_bulk_update` - -[discrete] -===== Request body - -A JSON array where each element includes: - -* The `id` or `rule_id` field of the rule you want to update. -* The <> you want to modify. - -IMPORTANT: If you call `PUT` to update rules, all unspecified fields are -deleted. You cannot modify the `id` or `rule_id` values. - -For `PATCH` calls, any of the fields can be modified. For `PUT` calls, -some fields are required (see <> for a list of required -fields). - -[discrete] -===== Example request - -[source,console] --------------------------------------------------- -PATCH api/detection_engine/rules/_bulk_update -[ - { - "threat": [ - { - "framework": "MITRE ATT&CK", - "tactic": { - "id": "TA0001", - "reference": "https://attack.mitre.org/tactics/TA0001", - "name": "Initial Access" - }, - "technique": [ - { - "id": "T1193", - "name": "Spearphishing Attachment", - "reference": "https://attack.mitre.org/techniques/T1193" - } - ] - } - ], - "rule_id": "process_started_by_ms_office_program_possible_payload" - }, - { - "name": "New name", - "id": "56b22b65-173e-4a5b-b27a-82599cb1433e" - } -] --------------------------------------------------- -// KIBANA - -[discrete] -===== Response code - -`200`:: - Indicates a successful call. - -[discrete] -===== Response payload - -A JSON array containing the updated rules. - -''' - -[discrete] -[[bulk-actions-rules-api-action]] -==== Bulk action - -[WARNING] -==== -When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running. - -If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change. -==== - -Applies a bulk action to multiple rules. The bulk action is applied to all rules that match the filter or to the list of rules by their IDs. - -[discrete] -===== Request URL - -`POST :/api/detection_engine/rules/_bulk_action` - -[discrete] -===== URL query parameters - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`dry_run` |Boolean | Enables <> for the request call. -|No -|============================================== - -[discrete] -===== Request body - -A JSON object with the following properties: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required -| `query` | String | A KQL search query to match the rules. | No -| `ids` | String[] | Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. | No -| `action` | Enum a| A bulk action -to apply. - -.Possible values: -* `enable` -* `disable` -* `delete` -* `duplicate` -* `export` -* `edit` -* `run` - -| Yes - -| `run` | <> -| Object that describes applying a manual rule run action. -|No. - -Yes, if action is `run`. - -| `edit` | <> -| Edit object that describes applying an update action. - -|No. - -Yes, if action is `edit`. - - -| `duplicate` | <> -| Duplicate object that describes applying an update action. - -|No. - -|============================================== - -[[bulk-actions-rules-api-dry-run]] -[discrete] -==== Dry run mode -Enable dry run mode to verify that bulk actions can be applied to specified rules. Certain rules, such as prebuilt Elastic rules, can't be edited and will return errors in the request response. Error details will contain an explanation, the rule name and/or ID, and additional troubleshooting information. - -To enable dry run mode on a request, add the query parameter `dry_run=true` to the end of the request URL. Rules specified in the request will be temporarily updated. These updates won't be written to {es}. - - -IMPORTANT: Dry run mode is not supported for the `export` bulk action. A `400` error will be returned in the request response. - -[[bulk-manual-rule-run]] -[discrete] -==== BulkManualRuleRun object - -* `start_date` field: (String, Required) Defines the start date of the manual run. -* `end_date` field: (String, Optional) Defines the end date of the manual run. - -[[bulk-duplicate-object-schema]] -[discrete] -==== BulkDuplicateAction object - -* `include_exceptions` field: Boolean. Defines whether to include exceptions in a duplicated rule. - -[[bulk-edit-object-schema]] -[discrete] -==== BulkEditAction object - -* `type` field: enum. Defines what will be updated in rules. -* `value` field: any. value which will be applied in edit action. - -[discrete] -===== Possible `BulkEditAction` object values - -[width="100%",options="header"] -|============================================== -| `type` field | `value` field | Description -| `add_tags` | String[] | Add tags to rules -| `delete_tags` | String[] | Delete rules' tags -| `set_tags` | String[] | Overwrite rules' tags -| `add_investigation_fields` | { field_names: String[] } | Add custom highlighted fields to rules -| `delete_investigation_fields` | { field_names: String[] } | Delete rules' custom highlighted fields -| `set_investigation_fields` | { field_names: String[] } | Overwrite rules' custom highlighted fields -| `add_index_patterns` | String[] | Add index patterns to rules -| `delete_index_patterns` | String[] | Delete rules' index patterns -| `set_index_patterns` | String[] | Overwrite rules' index patterns -| `set_timeline` | { `timeline_id`: String; `timeline_title`: String } | Overwrite rules' Timeline template -| `set_schedule` - -| { `interval`: String; `lookback`: String } -| Overwrite rules' schedule - -`interval`: Frequency of rule execution. For example, `"1h"` means the rule runs every hour. - -`lookback`: Additional look-back time that the rule analyzes. For example, `"10m"` means the rule analyzes the last 10 minutes of data in addition to the frequency interval. - -If `interval` is set to `"10m"` and `lookback` to `"1m"`, then the rule runs every 5 minutes but analyzes the documents added to indices during the last 11 minutes. - -Both `interval` and `lookback` have a format of `"{integer}{time_unit}"`, where accepted time units are `s` for seconds, `m` for minutes, and `h` for hours. The integer must be positive and larger than 0. Examples: `"45s"`, `"30m"`, `"6h"` - -| `add_rule_actions` | { - `actions`: <> , - `throttle`: <> - } | Add actions to rules -| `set_rule_actions` | { - `actions`: <> , - `throttle`: <> - } | Overwrite rules' existing actions - - -|============================================== - -<> are shown in order of oldest to newest in the `edit` array payload's property. - - -[discrete] -[[actions-object-schema-bulk]] -===== `actions` schema - -These fields are required when calling `PUT` to modify the `actions` object: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|action_type_id |String a|The action type used for sending notifications, can -be: - -* `.slack` -* `.slack_api` -* `.email` -* `.index` -* `.pagerduty` -* `.swimlane` -* `.webhook` -* `.servicenow` -* `.servicenow-itom` -* `.servicenow-sir` -* `.jira` -* `.resilient` -* `.opsgenie` -* `.teams` -* `.torq` -* `.tines` -* `.d3security` - -|group |String |Optionally groups actions by use cases. Use `default` for alert -notifications. - -|id |String |The connector ID. - -|params |Object a|Object containing the allowed connector fields, which varies according to the connector type: - -* For Slack: -** `message` (string, required): The notification message. -* For email: -** `to`, `cc`, `bcc` (string): Email addresses to which the notifications are -sent. At least one field must have a value. -** `subject` (string, optional): Email subject line. -** `message` (string, required): Email body text. -* For Webhook: -** `body` (string, required): JSON payload. -* For PagerDuty: -** `severity` (string, required): Severity of on the alert notification, can -be: `Critical`, `Error`, `Warning` or `Info`. -** `eventAction` (string, required): Event https://v2.developer.pagerduty.com/docs/events-api-v2#event-action[action type], which can be `trigger`, -`resolve`, or `acknowledge`. -** `dedupKey` (string, optional): Groups alert notifications with the same -PagerDuty alert. -** `timestamp` (DateTime, optional): https://v2.developer.pagerduty.com/v2/docs/types#datetime[ISO-8601 format timestamp]. -** `component` (string, optional): Source machine component responsible for the -event, for example `security-solution`. -** `group` (string, optional): Enables logical grouping of service components. -** `source` (string, optional): The affected system. Defaults to the {kib} -saved object ID of the action. -** `summary` (string, options): Summary of the event. Defaults to -`No summary provided`. Maximum length is 1024 characters. -** `class` (string, optional): Value indicating the class/type of the event. - -|============================================== - -[discrete] -[[optional-actions-fields-bulk-update]] -===== Optional `action` fields - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|frequency |String a|Object containing an action’s frequency: - -* `summary` (Boolean, required): Defines whether to send notifications alert summaries or for individual alerts. - -* `notifyWhen` (String, required`): Defines how often rules run actions. Valid values are: - -** `onActiveAlert`: Actions run when an alert is generated. -** `onThrottleInterval`: Actions run on the specified throttle interval and summarize new alerts generated during that interval. - -* `throttle` (String, optional): Defines the minimum time that must elapse before a rule's actions can repeat, in seconds, minutes, hours, or days. For example, `10m` or `1h`. This property is used only if `notifyWhen` is `onThrottleInterval`. - -|alerts_filter |Object a|Object containing an action’s conditional filters: - -* `timeframe` (Object, optional): Defines the time frame when this action can run. - -** `days` (Array of integers, required): Days of the week when this action will run, expressed as numbers between `1-7`, where `1` is Monday and `7` is Sunday. To select all days of the week, enter an empty array. -** `hours` (Object, required): The hours of the day during which this action can run. Hours of the day are expressed as two strings in the format `hh:mm` and in 24-hour time. A start of `00:00` and an end of `24:00` means the action can run all day. -+ -NOTE: To set an overnight time range, specify an `end` time that is earlier than the `start` time or equal to it. For example: `16:00` -> `15:00` or `21:33` -> `21:33`. - -*** `start` (String, required) -*** `end` (String, required) - -** `timezone` (String, required): An IANA timezone name, such as `Europe/Madrid` or `America/New_York`. Specific offsets such as `UTC` or `UTC+1` will also work, but lack built-in DST. - -* `query` (Object, optional): Object containing a query filter that gets applied to an action to determine whether the action should run. -** `kql` (String, required): A KQL string. -** `filters` (Array of objects, required): A filter object, as defined in the `kbn-es-query` package. - -|============================================== - -[discrete] -[[throttle-schema-bulk]] -===== `throttle` schema - -`throttle` defines the maximum interval in which a rule's actions are executed. It accepts the following values: - -[NOTE] - -========= - -The rule-level `throttle` field is deprecated in {elastic-sec} 8.8 and is scheduled for end of life in Q4 of 2024. - -In {elastic-sec} 8.8 and later, you can use the (<>) field to define frequencies for individual actions. Actions without frequencies will acquire a converted version of the rule's `throttle` field. In the response, the converted `throttle` setting appears in the individual actions' `frequency` field. - -========= - -- `"rule"`: Execute actions on each rule execution - -- `"1h"`: Execute actions once per hour - -- `"1d"`: Execute actions once per day - -- `"7d"`: Execute actions once per week - -[discrete] -===== Example requests - -*Example 1* - -The following request activates all rules with the `test` tag: - -[source,console] --------------------------------------------------- -POST api/detection_engine/rules/_bulk_action -{ - "query": "alert.attributes.tags: \"test\"", - "action": "enable" -} --------------------------------------------------- - -[discrete] -===== Response code - -`200`:: - Indicates a successful call. - -[discrete] -===== Response payload - -For `enable`, `disable`, `delete`, `edit`, `duplicate`, and `run` actions, a JSON object containing the action's outcome: - -- `attributes.summary.total`: Total number of rules matching the bulk action -- `attributes.summary.succeeded`: Number of successful outcomes (number of rules that were enabled, deleted, or updated) -- `attributes.summary.failed`: Number of failed outcomes -- `attributes.summary.skipped`: Number of rules that were skipped due to various reasons (explained below) -- `attributes.results.created`: Rule objects that were created during the action's execution -- `attributes.results.updated`: Rule objects that were updated during the action's execution. If the action execution is `run`, it returns rule objects that were scheduled for manual runs. -- `attributes.results.deleted`: Rule objects that were deleted during the action's execution -- `attributes.results.skipped`: Rules that were skipped during the action's execution - -A rule can only be `skipped` when the bulk action to be performed on it results in nothing being done. For example, if the `edit` action is used to add a tag to a rule that already has that tag, or to delete an index pattern that is not specified in a rule. Objects returned in `attributes.results.skipped` will only include rules' `id`, `name`, and `skip_reason`. - -[source,json] --------------------------------------------------- -{ - "success":true, - "rules_count": 1, - "attributes":{ - "results":{ - "updated":[ - { - "id":"8bc7dad0-9320-11ec-9265-8b772383a08d", - "updated_at":"2022-02-21T17:05:50.883Z", - "updated_by":"elastic", - "created_at":"2022-02-21T14:14:13.801Z", - "created_by":"elastic", - "name":"DNS Tunneling [Duplicate]", - "tags":[ - "Elastic", - "Network", - "Threat Detection", - "ML" - ], - "interval":"15m", - "enabled":true, - "description":"A machine learning job detected unusually large numbers of DNS queries for a single top-level DNS domain, which is often used for DNS tunneling. DNS tunneling can be used for command-and-control, persistence, or data exfiltration activity. For example, dnscat tends to generate many DNS questions for a top-level domain as it uses the DNS protocol to tunnel data.", - "risk_score":21, - "severity":"low", - "license":"Elastic License v2", - "author":[ - "Elastic" - ], - "false_positives":[ - "DNS domains that use large numbers of child domains, such as software or content distribution networks, can trigger this alert and such parent domains can be excluded." - ], - "from":"now-45m", - "rule_id":"7289bf08-4e91-4c70-bf01-e04c4c5d7756", - "max_signals":100, - "risk_score_mapping":[ - - ], - "severity_mapping":[ - - ], - "threat":[ - - ], - "to":"now", - "references":[ - "https://www.elastic.co/guide/en/security/current/prebuilt-ml-jobs.html" - ], - "version":6, - "exceptions_list":[ - - ], - "immutable":false, - "related_integrations": [], - "required_fields": [], - "setup": "", - "type":"machine_learning", - "anomaly_threshold":50, - "machine_learning_job_id":[ - "packetbeat_dns_tunneling" - ], - "execution_summary": { <1> - "last_execution": { - "date": "2022-03-23T16:06:12.787Z", - "status": "partial failure", - "status_order": 20, - "message": "This rule attempted to query data from Elasticsearch indices listed in the \"Index pattern\" section of the rule definition, but no matching index was found.", - "metrics": { - "total_search_duration_ms": 135, - "total_indexing_duration_ms": 15, - "execution_gap_duration_s": 0, - } - } - } - } - ], - "created":[ - - ], - "deleted":[ - - ], - "skipped":[ - { "id": "51658332-a15e-4c9e-912a-67214e2e2359", "name": "Skipped rule", "skip_reason": "RULE_NOT_MODIFIED" } - ] - }, - "summary":{ - "failed": 0, - "skipped": 1, - "succeeded": 1, - "total": 2 - } - } -} --------------------------------------------------- - -<1> dev:[] These fields are under development and their usage or schema may change: `execution_summary`. - - -For an `export` action, an `.ndjson` file containing exported rules. - - -*Example 2, Partial failure* - -The following request adds tags `tag-1` and `tag-2` to the rules that have the IDs sent in the payload: -[source,console] --------------------------------------------------- -POST api/detection_engine/rules/_bulk_action -{ - "ids":[ - "8bc7dad0-9320-11ec-9265-8b772383a08d", - "8e5c1a40-9320-11ec-9265-8b772383a08d" - ], - "action": "edit", - "edit": [{ "type": "add_tags", "value":["tag-1", "tag-2"] }] -} --------------------------------------------------- - -[discrete] -===== Response code - -`500`:: - Indicates partial bulk action failure. - -[discrete] -===== Response payload - -If processing of any rule fails, a partial error outputs the ID and/or name of the affected rule and the corresponding error, as well as successfully processed rules (in the same format as a successful 200 request). - -[discrete] -==== Example payload - -[source,json] --------------------------------------------------- -{ - "message": "Bulk edit partially failed", - "status_code": 500, - "attributes": { - "errors": [ - { - "message": "Index patterns can't be added. Machine learning rule doesn't have index patterns property", - "status_code": 500, - "rules": [ - { - "id": "8bc7dad0-9320-11ec-9265-8b772383a08d", - "name": "DNS Tunneling [Duplicate]" - } - ] - } - ], - "results": { - "updated": [ - { - "id": "8e5c1a40-9320-11ec-9265-8b772383a08d", - "updated_at": "2022-02-21T16:56:22.818Z", - "updated_by": "elastic", - "created_at": "2022-02-21T14:14:17.883Z", - "created_by": "elastic", - "name": "External Alerts [Duplicate]", - "tags": [ - "Elastic", - "Network", - "Windows", - "APM", - "macOS", - "Linux" - ], - "interval": "5m", - "enabled": true, - "description": "Generates a detection alert for each external alert written to the configured indices. Enabling this rule allows you to immediately begin investigating external alerts in the app.", - "risk_score": 47, - "severity": "medium", - "license": "Elastic License v2", - "rule_name_override": "message", - "timestamp_override": "event.ingested", - "author": [ - "Elastic" - ], - "false_positives": [], - "from": "now-6m", - "rule_id": "941faf98-0cdc-4569-b16d-4af962914d61", - "max_signals": 10000, - "risk_score_mapping": [ - { - "field": "event.risk_score", - "value": "", - "operator": "equals" - } - ], - "severity_mapping": [ - { - "severity": "low", - "field": "event.severity", - "value": "21", - "operator": "equals" - }, - { - "severity": "medium", - "field": "event.severity", - "value": "47", - "operator": "equals" - }, - { - "severity": "high", - "field": "event.severity", - "value": "73", - "operator": "equals" - }, - { - "severity": "critical", - "field": "event.severity", - "value": "99", - "operator": "equals" - } - ], - "threat": [], - "to": "now", - "references": [], - "version": 5, - "exceptions_list": [], - "immutable": false, - "related_integrations": [], - "required_fields": [], - "setup": "", - "type": "query", - "language": "kuery", - "index": [ - "apm-*-transaction*", - "traces-apm*", - "auditbeat-*", - "filebeat-*", - "logs-*", - "packetbeat-*", - "winlogbeat-*", - "added-by-id-*" - ], - "query": "event.kind:alert and not event.module:(endgame or endpoint)\n", - "actions": [], - "execution_summary": { <1> - "last_execution": { - "date": "2022-03-23T16:06:12.787Z", - "status": "partial failure", - "status_order": 20, - "message": "This rule attempted to query data from Elasticsearch indices listed in the \"Index pattern\" section of the rule definition, but no matching index was found.", - "metrics": { - "total_search_duration_ms": 135, - "total_indexing_duration_ms": 15, - "execution_gap_duration_s": 0, - } - } - } - } - ], - "created": [], - "deleted": [], - "skipped": [], - }, - "summary": { - "failed": 1, - "succeeded": 1, - "skipped": 0, - "total": 2 - } - } -} --------------------------------------------------- - -<1> dev:[] These fields are under development and their usage or schema may change: `execution_summary`. - -*Example 3, Dry run* - -The following request will validate that the `add_index_patterns` bulk action can be successfully applied to three rules. Each rule (specified by its rule ID) is different: one is a prebuilt Elastic rule, another is a custom machine learning rule, and another is a custom query rule. Because dry run mode is enabled, changes to these rules will not be permanent or saved to {es}. - - -[source,console] --------------------------------------------------- -POST api/detection_engine/rules/_bulk_action?dry_run=true -{ - "action": "edit", - "edit": [ - { - "value": [ - "test-*" - ], - "type": "add_index_patterns" - } - ], - "ids": ["81aa0480-06af-11ed-94fb-dd1a0597d8d2", "dc015d10-0831-11ed-ac8b-05a222bd8d4a", "de8f5af0-0831-11ed-ac8b-05a222bd8d4a"] -} --------------------------------------------------- - -[discrete] -===== Response code - -`500`:: - Indicates a partial bulk action failure. - -[discrete] -===== Response payload - -The `attributes.errors` section of the response shows that two rules failed to update and one succeeded. The same results would be returned if you ran the request without dry run mode enabled. -Notice that there are no arrays in `attributes.results`. In dry run mode, rule updates are not applied and saved to {es}, so the endpoint wouldn't return results for rules that have been `updated`, `created`, or `deleted`. - -[discrete] -===== Response body - -[source,json] --------------------------------------------------- -{ - "message": "Bulk edit partially failed", - "status_code": 500, - "attributes": { - "errors": [ - { - "message": "Elastic rule can't be edited", - "status_code": 500, - "err_code": "IMMUTABLE", - "rules": [ - { - "id": "81aa0480-06af-11ed-94fb-dd1a0597d8d2", - "name": "Unusual AWS Command for a User" - } - ] - }, - { - "message": "Machine learning rule doesn't have index patterns", - "status_code": 500, - "err_code": "MACHINE_LEARNING_INDEX_PATTERN", - "rules": [ - { - "id": "dc015d10-0831-11ed-ac8b-05a222bd8d4a", - "name": "Suspicious Powershell Script [Duplicate]" - } - ] - } - ], - "results": { - "updated": [], - "created": [], - "deleted": [], - "skipped": [], - }, - "summary": { - "failed": 2, - "succeeded": 1, - "skipped": 0, - "total": 3 - } - } -} --------------------------------------------------- diff --git a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc deleted file mode 100644 index 334a233557..0000000000 --- a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc +++ /dev/null @@ -1,104 +0,0 @@ -[[exceptions-api-create-rule-default-exception-list]] -=== Create default exception list for a rule - -Creates a default exception list for the rule you specify. - -To add exception items to a default exception list, pass in exceptions items that you want applied to the rule. Refer to <> for more information. - -When an exception item’s query evaluates to `true`, the associated rule does not issue alerts even when its other criteria are met. - -NOTE: Default exception lists do not display on the **Shared Exception Lists** page in the {security-app} UI; they only appear in the Rule exceptions on the rule details page. This is because default exception lists can only be associated with a single rule. Refer to <> to learn more. - -==== Request URL - -`POST :/api/detection_engine//exceptions` - -==== Request body - -A JSON object with these fields: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`description` |String |Describes the exception list. |Yes -|`list_id` |String |Unique identifier. |No, automatically created when it is not -provided. -|`meta` |Object |Placeholder for metadata about the exception list. |No -|`name` |String |The exception list's name. |Yes -|`namespace_type` |String a|Determines whether the exception list is available in all {kib} spaces or just the space in which it is created, where: - -* `single`: Only available in the {kib} space in which it is created. -* `agnostic`: Available in all {kib} spaces. - -|No, defaults to `single`. -|`tags` |String[] |String array containing words and phrases to help categorize -exception lists. |No -|`type` |String a|The type of exception, which must be: - -* `rule_default`: Exception list that belongs to a single rule. - -|Yes - -|============================================== - -===== Example requests - -Creates an exception list for holding trusted Linux process exception -items: - -[source,console] --------------------------------------------------- -POST api/detection_engine//exceptions -{ - "description": "Excludes Linux trusted processes", - "name": "Linux process exceptions", - "list_id": "trusted-linux-processes", - "type": "detection", - "namespace_type": "single", - "tags": [ - "linux", - "processes" - ] -} --------------------------------------------------- -// KIBANA - -==== Response code - -`200`:: - Indicates a successful call. - - -==== Response payload - -The exception list object with a unique ID. - -[source,json] --------------------------------------------------- -{ - "_tags": [], - "created_at": "2020-07-13T09:33:46.187Z", - "created_by": "elastic", - "description": "Excludes Linux trusted processes", - "id": "f320c070-c4eb-11ea-80bb-11861bae2798", <1> - "list_id": "trusted-linux-processes", <2> - "name": "Linux process exceptions", - "namespace_type": "single", <3> - "tags": [ - "linux", - "processes" - ], - "tie_breaker_id": "2c08d5a5-2ecc-4d5a-acfb-0a367f25b3f3", - "type": "detection", <4> - "updated_at": "2020-07-13T09:33:46.359Z", - "updated_by": "elastic" -} --------------------------------------------------- - -The highlighted values can help you identify detection rules associated with the exception list: - -<1> `id` -<2> `list_id` -<3> `namespace_type` -<4> `type` diff --git a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc deleted file mode 100644 index 577509167e..0000000000 --- a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc +++ /dev/null @@ -1,193 +0,0 @@ -[[exceptions-api-create-rule-default-exception-item]] -=== Create exceptions for a rule - -Adds specified exception items to a rule's default exception list. -A default exception list contains exceptions that are associated with a single rule, as opposed to a shared exception list, which contains exceptions that are associated with multiple rules. - -If a default exception list doesn't exist for a rule, one is automatically created when you try to add an exception to it. - -TIP: For more information about creating exceptions that are used by multiple rules, refer to {api-kibana}/operation/operation-createexceptionlistitem[Create an exception list item]. For more information about creating exception items from a list, such as a list of IP addresses or hosts names, refer to {api-kibana}/group/endpoint-security-lists-api[Lists API]. - -==== Request URL - -`POST :/api/detection_engine/rules//exceptions` - -Allows you to create exception items that are associated with a specified rule `id`. - -===== URL query parameters - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`id` |String |Specify the rule ID. |Yes. - -|============================================== - -==== Request body - -A JSON object with an array of exception items, where each exception item has the {api-kibana}/operation/operation-createexceptionlistitem[required fields]. - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`items` |String[] | Specify an array of exception list items to create. |Yes -|`comments` |Object[] a|Array of `comment` fields. Default value is [] (empty): - -* `comment` (string): Comments about the exception item. - -|No - -|`description` |String |Describes the exception item. |Yes -|`entries` |<> |Array containing the -exception queries. Boolean `AND` logic is used to evaluate the relationship -between array elements. If you want to use `OR` logic, create a separate -exception item. |Yes -|`expire_time` |String |The exception item's expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions. |No -|`list_id` |String |ID of the associated {api-kibana}/operation/operation/operation-createexceptionlist[exception container]. |Yes -|`item_id` |String |Unique identifier of the exception item. |No, automatically -created when it is not provided. -|`meta` |Object |Placeholder for metadata about the exception item. |No -|`name` |String |The exception item's name. |Yes -|`namespace_type` |String a|Determines whether the exception item is available -in all {kib} spaces or just the space in which it is created, where: - -* `single`: Only available in the {kib} space in which it is created. -* `agnostic`: Available in all {kib} spaces. - -Must be the same value as its associated exception container. Default value is `single`. - -|No -|`os_types` |String[] a|Defines the OS on which the -exception is implemented. Valid values are: - -* `os:windows`: Windows OS -* `os:linux`: Linux OS -* `os:macos`: Mac OS - -Default value is `[]` (empty). - -|No -|`tags` |String[] |String array containing words and phrases to help categorize -exception items. |No -|`type` |String a|Exception query type, must be `simple`. |Yes - -|============================================== - - -[[entries-object-schema-single-rule-exceptions]] -===== `entries` schema - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`field` |String |The source event field used to define the exception. Cannot -be an empty string. |Yes -|`operator` |String a|The operator used to determine when the exception is used. -Can be: - -* `included`: The `field` has the specified value or values. -* `excluded`: The `field` does not have specified value or values. - -|Yes - -|`type` |String a|The `type` of query: - -* `match`: Must be an exact match of the defined value. -* `match_any`: Matches any of the defined values. -* `exists`: The field exists. -* `list`: The field matches values in a list container. -* `wildcard`: Matches `value` using wildcards, such as `C:\path\*\app.exe`. Use `?` to match one character and `*` to match zero or more characters. The `field` data type must be {ref}/keyword.html#keyword-field-type[keyword], {ref}/text.html#text-field-type[text], or {ref}/keyword.html#wildcard-field-type[wildcard]. -* `nested`: Array of `entries` objects. Nested conditions are required for -excluding some Endpoint fields. - -|Yes - -|`value` -a|String - -String[] - -a|Field value or values: - -* String: When the `type` is `match` or `wildcard`. -* String[]: When the `type` is `match_any`. - -|Yes, except when `type` is `exists` or `list`. - -|============================================== - -IMPORTANT: When you use {api-kibana}/operation/operation-createlist[list containers] (`"type": "list"`), you cannot use other types in the `entries` array (`match`, -`match_any`, `exists`, or `nested`). - -For endpoint exceptions, you cannot create exception items based on excluded -values (`"operator": "excluded"`). - -===== Example requests - -[source,console] --------------------------------------------------- -POST api/detection_engine/rules//exceptions -{ - "items": [ - { - "description": "Excludes the weekly maintenance job", - "entries": [ - { - "field": "process.name", - "operator": "included", - "type": "match", - "value": "maintenance-job" - } - ], - "name": "Linux maintenance job", - "tags": [ - "in-house processes", - "linux" - ], - "type": "simple" - } - ] -} --------------------------------------------------- - -==== Response code - -`200`:: - Indicates a successful call. - -==== Response payload - -The returned exception item. - -Example response: - -[source,json] --------------------------------------------------- -{ - "body": [ - { - "comments": [], - "created_by": "elastic", - "description": "Exception item for rule default exception list", - "entries": [ - { - "field": "host.name", - "operator": "included", - "type": "match", - "value": "foo", - }, - ], - "name": "Sample exception item", - "list_id": "e6c44050-c661-11ea-bab5-9d6ae015701b", - "namespace_type": "single", - "os_types": [], - "tags": [], - "type": "simple", - "updated_by": "elastic" - } - ] -} --------------------------------------------------- diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc deleted file mode 100644 index c9ef8636a3..0000000000 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ /dev/null @@ -1,1604 +0,0 @@ -[[rules-api-create]] -=== Create rule - -:frontmatter-description: Create a new detection rule. -:frontmatter-tags-products: [security, alerting] -:frontmatter-tags-content-type: [reference] -:frontmatter-tags-user-goals: [manage] - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-detections-api[detections APIs]. --- - -[WARNING] -==== -When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running. - -If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change. -==== - -Creates a new detection rule. - -You can create the following types of rules: - -* *Custom query*: Searches the defined indices and creates an alert when -a document matches the rule's KQL query. -* *Event correlation*: Searches the defined indices and creates an alert when results match an -{ref}/eql.html[Event Query Language (EQL)] query. -* *Threshold*: Searches the defined indices and creates an alert when the -number of times the specified field's value meets the threshold during a single -execution. When there are multiple values that meet the threshold, an alert is -generated for each value. -+ -For example, if the threshold `field` is `source.ip` and its `value` is `10`, an -alert is generated for every source IP address that appears in at least 10 of -the rule's search results. If you're interested, see -{ref}/search-aggregations-bucket-terms-aggregation.html[Terms Aggregation] for -more information. -* *Indicator match*: Creates an alert when fields match values defined in the -specified {ref}/indices-create-index.html[{es} index]. For example, you can -create an index for IP addresses and use this index to create an alert whenever -an event's `destination.ip` equals a value in the index. The index's field -mappings should be {ecs-ref}[ECS-compliant]. -* *New terms*: Generates an alert for each new term detected in source documents within a specified time range. -* *{esql}*: Uses {ref}/esql.html[Elasticsearch Query Language ({esql})] to find events and aggregate search results. -* *{ml-cap} rules*: Creates an alert when a {ml} job discovers an anomaly above -the defined threshold (see <>). - -IMPORTANT: To create {ml} rules, you must have the -https://www.elastic.co/subscriptions[appropriate license] or use a -{ess-trial}[cloud deployment]. Additionally, for the {ml} rule to function -correctly, the associated {ml} job must be running. - -To retrieve {ml} job IDs, which are required to create {ml} jobs, call the -{ref}/ml-get-job.html[{es} Get jobs API]. {ml-cap} jobs that contain `siem` in -the `groups` field can be used to create rules: - -[source,json] --------------------------------------------------- -... -"job_id": "linux_anomalous_network_activity_ecs", -"job_type": "anomaly_detector", -"job_version": "7.7.0", -"groups": [ - "auditbeat", - "process", - "siem" -], -... --------------------------------------------------- - -Additionally, you can set up notifications for when rules create alerts. The -notifications use the {kib} {kibana-ref}/alerting-getting-started.html[Alerting and Actions framework]. -Each action type requires a connector. Connectors store the information -required to send notifications via external systems. The following connector types are -supported for rule notifications: - -* Slack -* Email -* PagerDuty -* Webhook -* Microsoft Teams -* {ibm-r} -* {jira} -* {sn} ITSM - -NOTE: For more information on PagerDuty fields, see -https://developer.pagerduty.com/docs/events-api-v2/trigger-events/[Send a v2 Event]. - -To retrieve connector IDs, which are required to configure rule notifications, -call the {kib} {kibana-ref}/saved-objects-api-find.html[Find objects API] with -`"type": "action"` in the request payload. - -For detailed information on {kib} actions and alerting, and additional API -calls, see: - -* https://github.com/elastic/kibana/tree/main/x-pack/plugins/alerting -* https://github.com/elastic/kibana/tree/main/x-pack/plugins/actions - -==== Request URL - -`POST :/api/detection_engine/rules` - -==== Request body - -A JSON object that defines the rule's values: - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - -[[ref-fields-all]] -===== Required fields for all rule types - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|description |String |The rule's description. - -|name |String |The rule's name. - -|risk_score |Integer a|A numerical representation of the alert's severity from -0 to 100, where: - -* `0` - `21` represents low severity -* `22` - `47` represents medium severity -* `48` - `73` represents high severity -* `74` - `100` represents critical severity - -|severity |String a|Severity level of alerts produced by the rule, which must -be one of the following: - -* `low`: Alerts that are of interest but generally not considered to be -security incidents -* `medium`: Alerts that require investigation -* `high`: Alerts that require immediate investigation -* `critical`: Alerts that indicate it is highly likely a security incident has -occurred - -|type |String a|Data type on which the rule is based: - -* `eql`: EQL query (see {ref}/eql.html[Event Query Language]). -* `esql`: ES\|QL query (see {ref}/esql.html[Elasticsearch Query Language]). -* `query`: query with or without additional filters. -* `saved_query`: saved search, identified in the `saved_id` field. -* `machine_learning`: rule based on a {ml} job's anomaly scores. -* `threat_match`: rule that matches event values with values in the specified -{es} index. -* `threshold`: rule based on the number of times a `query` matches the -specified field. -* `new_terms`: rule that alerts on values that have not been seen before - -|============================================== - -[[req-fields-query-threshold]] -===== Required fields for query, indicator match, threshold, new terms, event correlation, and {esql} rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|query |String a|{kibana-ref}/search.html[Query] used by the rule to create -alerts. - -[NOTE] -====== -* For indicator match rules, only the query's results are used to determine -whether an alert is generated. -* ES\|QL rules have additional query requirements. Refer to <> for more information. -====== - -|============================================== - -[[req-fields-threshold]] -===== Required field for threshold rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|threshold |Object a|Defines the field and threshold value for when alerts -are generated, where: - -* `cardinality` (Array of length 1): The field on which the cardinality is applied. -* `cardinality.field` (string, required): The field on which to calculate and compare the -cardinality. -* `cardinality.value` (integer, required): The threshold value from which an alert is -generated based on unique number of values of `cardinality.field`. -* `field` (string or string[], required): The field on which the threshold is applied. If -you specify an empty array (`[]`), alerts are generated when the query returns -at least the number of results specified in the `value` field. -* `value` (integer, required): The threshold value from which an alert is -generated. - -|============================================== - -[[req-fields-saved-query]] -===== Required field for saved query rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|saved_id |String |Kibana saved search used by the rule to create alerts. - -|============================================== - -[[req-fields-eql]] -===== Required field for event correlation rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|language |String |Must be `eql`. - -|============================================== - -[[req-fields-esql]] -===== Required field for {esql} rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|language |String |Must be `esql`. - -|============================================== - -[[req-fields-ml]] -===== Required fields for machine learning rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|anomaly_threshold |Integer |Anomaly score threshold above which the rule -creates an alert. Valid values are from `0` to `100`. - -|machine_learning_job_id |String[] |{ml-cap} job ID(s) the rule monitors for -anomaly scores. - -|============================================== - -[[req-fields-threat-match]] -===== Required fields for indicator match rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|threat_index |String[] |{es} indices used to check which field values generate -alerts. - -|threat_query |String |Query used to determine which fields in the {es} index -are used for generating alerts. - -|threat_mapping |Object[] a|Array of `entries` objects that define mappings -between the source event fields and the values in the {es} threat index. Each -`entries` object must contain these fields: - -* `field`: field from the event indices on which the rule runs -* `type`: must be `mapping` -* `value`: field from the {es} threat index - -You can use Boolean `and` and `or` logic to define the conditions for when -matching fields and values generate alerts. Sibling `entries` objects -are evaluated using `or` logic, whereas multiple entries in a single `entries` -object use `and` logic. See <> for an example that -uses both `and` and `or` logic. - -|============================================== - -[[req-fields-new-terms]] -===== Required fields for new terms rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|new_terms_fields |String[] |Fields to monitor for new values. Must contain 1–3 field names. - -|history_window_start |String |Start date to use when checking if a term has been seen before. -Supports relative dates – for example, `now-30d` will search the last 30 days of data when checking if a term -is new. We do not recommend using absolute dates, which can cause issues with rule performance -due to querying increasing amounts of data over time. - -|============================================== - -[[opt-fields-all]] -===== Optional fields for all rule types - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|actions |<> |Array defining the automated -actions (notifications) taken when alerts are generated. - -|author |String[] |The rule's author. - -|building_block_type |String |Determines if the rule acts as a building block. -By default, building-block alerts are not displayed in the UI. These rules are -used as a foundation for other rules that do generate alerts. Its value must be -`default`. For more information, refer to <>. - -|enabled |Boolean |Determines whether the rule is enabled. Defaults to `true`. - -|false_positives |String[] |String array used to describe common reasons why -the rule may issue false-positive alerts. Defaults to an empty array. - -[[detection-rules-from]] -|from |String |Time from which data is analyzed each time the rule executes, -using a {ref}/common-options.html#date-math[date math range]. For example, -`now-4200s` means the rule analyzes data from 70 minutes before its start -time. Defaults to `now-6m` (analyzes data from 6 minutes before the start -time). - -|interval |String |Frequency of rule execution, using a -{ref}/common-options.html#date-math[date math range]. For example, `"1h"` -means the rule runs every hour. Defaults to `5m` (5 minutes). - -|license |String |The rule's license. - -|max_signals |Integer a|Maximum number of alerts the rule can create during a -single run (the rule's **Max alerts per run** <> value). Defaults to `100`. - -NOTE: This setting can be superseded by the {kibana-ref}/alert-action-settings-kb.html#alert-settings[{kib} configuration setting] `xpack.alerting.rules.run.alerts.max`, which determines the maximum alerts generated by _any_ rule in the {kib} alerting framework. For example, if `xpack.alerting.rules.run.alerts.max` is set to `1000`, the rule can generate no more than 1000 alerts even if `max_signals` is set higher. - -|meta |Object a|Placeholder for metadata about the rule. - -*NOTE*: This field is overwritten when you save changes to the rule's settings. - -|note |String |Notes to help investigate alerts produced by the rule. - -|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. - -|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. - -|tags |String[] |String array containing words and phrases to help categorize, -filter, and search rules. Defaults to an empty array. - -|threat |<> |Object containing attack -information about the type of threat the rule monitors, see -{ecs-ref}/ecs-threat.html[ECS threat fields]. Defaults to an empty array. - -|throttle |String a|Determines how often actions are taken: - -[NOTE] -===== -The rule level `throttle` field is deprecated in {elastic-sec} 8.8 and will remain active for at least the next 12 months. - -In {elastic-sec} 8.8 and later, you can use the (<>) field to define frequencies for individual actions. Actions without frequencies will acquire a converted version of the rule's `throttle` field. In the response, the converted `throttle` setting appears in the individual actions' `frequency` field. -===== - -* `no_actions`: Never -* `rule`: Every time new alerts are detected -* `1h`: Every hour -* `1d`: Every day -* `7d`: Every week - -Required when `actions` are used to send notifications. - -|version |Integer |The rule's version number. Defaults to `1`. - -|investigation_fields |Object a| Specify highlighted fields for personalized alert investigation flows: - -* `field_names`: String[] , required - -|related_integrations |Object[] a| {integrations-docs}[Elastic integrations] the rule depends on. The object has these fields: - -* `package` (String, required): The integration package's name, as used by the https://github.com/elastic/package-registry[Elastic Package Registry]. -* `integration` (String, optional): The integration's name. This field is optional for packages with only one integration whose name matches the package name, but it's required for packages with multiple integrations. -* `version`: (String, required): Integration (package containing the integration) version constraint in https://semver.org/[semantic versioning] format. For version ranges, you must use tilde or caret syntax. For example, `~1.2.3` is from 1.2.3 to any patch version less than `1.3.0`, and `^1.2.3` is from `1.2.3`` to any minor and patch version less than `2.0.0`. - -|============================================== - -[[opt-fields-threat-match]] -===== Optional fields for indicator match rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|threat_filters |Object[] -|{ref}/query-filter-context.html[Query and filter context] array used to filter -documents from the {es} index containing the threat values. - -|threat_indicator_path |String -|Much like an ingest processor, users can use this field to define where their threat indicator can be found on their indicator documents. Defaults to `threatintel.indicator`. -|============================================== - -[[opt-fields-query-threshold]] -===== Optional fields for query, indicator match, threshold, and new terms rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|language |String |Determines the query language, which must be -`kuery` or `lucene`. Defaults to `kuery`. -|============================================== - -[[opt-fields-eql-query-threshold]] -===== Optional fields for event correlation, query, threshold, indicator match, new terms, and {esql} rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|filters |Object[] a|The {ref}/query-filter-context.html[query and filter -context] array used to define the conditions for when alerts are created from -events. Defaults to an empty array. - -NOTE: This field is not supported for ES\|QL rules. - -|index |String[] a|Indices on which the rule functions. Defaults to the -Security Solution indices defined on the {kib} Advanced Settings page -(*Kibana* → *Stack Management* → *Advanced Settings* → -`securitySolution:defaultIndex`). - -NOTE: This field is not supported for ES\|QL rules. - -|risk_score_mapping |Object[] a|Overrides generated alerts' `risk_score` with -a value from the source event: - -* `field` (string, required): Source event field used to override the default -`risk_score`. This field must be an integer. -* `operator` (string, required): Must be `equals`. -* `value`(string, required): Must be an empty string (`""`). - -|rule_name_override |String |Sets which field in the source event is used to -populate the alert's `signal.rule.name` value (in the UI, this value is -displayed on the *Rules* page in the *Rule* column). When unspecified, the -rule's `name` value is used. The source field must be a string data type. - -|severity_mapping |Object[] a|Overrides generated alerts' `severity` with -values from the source event: - -* `field` (string, required): Source event field used to override the default -`severity`. -* `operator` (string, required): Must be `equals`. -* `severity` (string, required): Mapped severity value, must be `low`, -`medium`, `high`, or `critical`. -* `value`(string, required): Field value used to determine the `severity`. - -|timestamp_override |String |Sets the time field used to query indices. -When unspecified, rules query the `@timestamp` field. The source field -must be an {es} date data type. - -|exceptions_list |Object[] a|Array of {api-kibana}/operation/group/endpoint-security-exceptions-api[exception containers], which define -exceptions that prevent the rule from generating alerts even when its other -criteria are met. The object has these fields: - -* `id` (string, required): ID of the exception container. -* `list_id` (string, required): List ID of the exception container. -* `namespace_type` (string required): Determines whether the exceptions are -valid in only the rule's {kib} space (`single`) or in all {kib} spaces -(`agnostic`). -* `type` (string, required): The exception type, which must be either -a detection rule exception (`detection`) or an endpoint exception (`endpoint`). - -|============================================== - -[[opt-fields-eql-create]] -===== Optional fields for event correlation rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|event_category_field |String -|Contains the event classification, such as `process`, `file`, or `network`. This field is typically mapped as a field type in the {ref}/keyword.html[keyword family]. Defaults to the `event.category` ECS field. - -|tiebreaker_field |String -|Sets a secondary field for sorting events (in ascending, lexicographic order) if they have the same timestamp. - -|timestamp_field |String -|Contains the event timestamp used for sorting a sequence of events. This is different from `timestamp_override`, which is used for querying events within a range. Defaults to the `@timestamp` ECS field. - -|============================================== - -[[opt-fields-alert-suppression-create]] -===== Optional alert suppression fields for query, indicator match, threshold, event correlation (non-sequence queries only), new terms, {esql}, and {ml} rules - -preview::["Alert suppression is in technical preview for event correlation rules. The functionality may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features."] - -====== Query, indicator match, event correlation (non-sequence queries only), new terms, {esql}, and {ml} rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|alert_suppression |Object a|Defines alert suppression configuration. Available fields: - -* `group_by` (string[], required): An array of 1-3 field names to use for suppressing alerts. - -* `duration` (<>, optional): The time period in which alerts will be suppressed, beginning when the rule first meets its criteria and creates the alert. If not specified, alerts will be suppressed on rule execution only. - -* `missing_fields_strategy` (string, optional): Defines how to handle events with missing suppression fields. Possible values: - - - `doNotSuppress`: Create a separate alert for each matching event. - - - `suppress`: Create one alert for each group of events with missing fields. - -|============================================== - -====== Threshold rule - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|alert_suppression |Object a|Defines alert suppression configuration. Available fields: - -* `duration` (<>, required): The time period in which alerts will be suppressed, beginning when the rule first meets its criteria and creates the alert. - -|============================================== - -[[actions-object-schema]] -===== `actions` schema - -All fields are required: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|action_type_id |String a|The connector type used for sending notifications, can -be: - -* `.slack` -* `.slack_api` -* `.email` -* `.index` -* `.pagerduty` -* `.swimlane` -* `.webhook` -* `.servicenow` -* `.servicenow-itom` -* `.servicenow-sir` -* `.jira` -* `.resilient` -* `.opsgenie` -* `.teams` -* `.torq` -* `.tines` -* `.d3security` - -|group |String |Optionally groups actions by use cases. Use `default` for alert -notifications. - -|id |String |The connector ID. - -|params |Object a|Object containing the allowed connector fields, which varies according to the connector type: - -* For Slack: -** `message` (string, required): The notification message. -* For email: -** `to`, `cc`, `bcc` (string): Email addresses to which the notifications are -sent. At least one field must have a value. -** `subject` (string, optional): Email subject line. -** `message` (string, required): Email body text. -* For Webhook: -** `body` (string, required): JSON payload. -* For PagerDuty: -** `severity` (string, required): Severity of on the alert notification, can -be: `Critical`, `Error`, `Warning` or `Info`. -** `eventAction` (string, required): Event https://v2.developer.pagerduty.com/docs/events-api-v2#event-action[action type], which can be `trigger`, -`resolve`, or `acknowledge`. -** `dedupKey` (string, optional): Groups alert notifications with the same -PagerDuty alert. -** `timestamp` (DateTime, optional): https://v2.developer.pagerduty.com/v2/docs/types#datetime[ISO-8601 format timestamp]. -** `component` (string, optional): Source machine component responsible for the -event, for example `security-solution`. -** `group` (string, optional): Enables logical grouping of service components. -** `source` (string, optional): The affected system. Defaults to the {kib} -saved object ID of the action. -** `summary` (string, options): Summary of the event. Defaults to -`No summary provided`. Maximum length is 1024 characters. -** `class` (string, optional): Value indicating the class/type of the event. - -|============================================== - -[discrete] -[[optional-actions-fields-rule-create]] -===== Optional `action` fields - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|frequency |String a|Object containing an action’s frequency: - -* `summary` (Boolean, required): Defines whether to send notifications as a summary of alerts or for each generated alert. - -* `notifyWhen` (String, required`): Defines how often alerts generate actions. Valid values are: - -** `onActiveAlert`: Actions run when the alert is generated. -** `onThrottleInterval`: Actions run on the specified throttle interval and summarize new alerts generated during that interval. - -* `throttle` (String, optional): Defines how often an alert generates repeated actions. This custom action interval must be specified in seconds, minutes, hours, or days. For example, `10m` or `1h`. This property is used only if `notifyWhen` is `onThrottleInterval`. - -|alerts_filter |Object a|Object containing an action’s conditional filters: - -* `timeframe` (Object, optional): Object containing the time frame for when this action can be run. - -** `days` (Array of integers, required): List of days of the week on which this action can be run. Days of the week are expressed as numbers between `1-7`, where `1` is Monday and `7` is Sunday. To select all days of the week, enter an empty array. -** `hours` (Object, required): The hours of the day during which this action can run. Hours of the day are expressed as two strings in the format `hh:mm` in `24` hour time. A start of `00:00` and an end of `24:00` means the action can run all day. -*** `start` (String, required) -*** `end` (String, required) - -** `timezone` (String, required): An ISO timezone name, such as `Europe/Madrid` or `America/New_York`. Specific offsets such as UTC or UTC+1 will also work, but lack built-in DST. - -* `query` (Object, optional): Object containing a query filter which gets applied to an action and determines whether the action should run. -** `kql` (String, required): A KQL string. -** `filters` (Array of objects, required): A filter object, as defined in the `kbn-es-query` package. - -|============================================== - -[discrete] -[[action-variables-rule-create]] -===== Alert notification placeholders - -You can use http://mustache.github.io/[mustache syntax] to add variables to notification messages. The action frequency you choose determines the variables you can select from. - -The following variables can be passed for all rules: - -NOTE: Refer to {kibana-ref}/rule-action-variables.html#alert-summary-action-variables[Action frequency: Summary of alerts] to learn about additional variables that can be passed if the rule's action frequency is **Summary of alerts**. - -* `{{context.alerts}}`: Array of detected alerts -* `{{{context.results_link}}}`: URL to the alerts in {kib} -* `{{context.rule.anomaly_threshold}}`: Anomaly threshold score above which -alerts are generated ({ml} rules only) -* `{{context.rule.description}}`: Rule description -* `{{context.rule.false_positives}}`: Rule false positives -* `{{context.rule.filters}}`: Rule filters (query rules only) -* `{{context.rule.id}}`: Unique rule ID returned after creating the rule -* `{{context.rule.index}}`: Indices rule runs on (query rules only) -* `{{context.rule.language}}`: Rule query language (query rules only) -* `{{context.rule.machine_learning_job_id}}`: ID of associated {ml} job ({ml} -rules only) -* `{{context.rule.max_signals}}`: Maximum allowed number of alerts per rule -execution -* `{{context.rule.name}}`: Rule name -* `{{context.rule.query}}`: Rule query (query rules only) -* `{{context.rule.references}}`: Rule references -* `{{context.rule.risk_score}}`: Default rule risk score -+ -NOTE: This placeholder contains the rule's default values even when the *Risk score override* option is used. -* `{{context.rule.rule_id}}`: Generated or user-defined rule ID that can be -used as an identifier across systems -* `{{context.rule.saved_id}}`: Saved search ID -* `{{context.rule.severity}}`: Default rule severity -+ -NOTE: This placeholder contains the rule's default values even when the *Severity override* option is used. -* `{{context.rule.threat}}`: Rule threat framework -* `{{context.rule.threshold}}`: Rule threshold values (threshold rules only) -* `{{context.rule.timeline_id}}`: Associated Timeline ID -* `{{context.rule.timeline_title}}`: Associated Timeline name -* `{{context.rule.type}}`: Rule type -* `{{context.rule.version}}`: Rule version -* `{{date}}``: Date the rule scheduled the action -* `{{kibanaBaseUrl}}`: Configured `server.publicBaseUrl` value, or empty string if not configured -* `{{rule.id}}`: ID of the rule -* `{{rule.name}}`: Name of the rule -* `{{rule.spaceId}}`: Space ID of the rule -* `{{rule.tags}}`: Tags of the rule -* `{{rule.type}}`: Type of rule -* `{{state.signals_count}}`: Number of alerts detected - -The following variables can only be passed if the rule’s action frequency is for each alert: - -* `{{alert.actionGroup}}`: Action group of the alert that scheduled actions for the rule -* `{{alert.actionGroupName}}`: Human-readable name of the action group of the alert that scheduled actions for the rule -* `{{alert.actionSubgroup}}`: Action subgroup of the alert that scheduled actions for the rule -* `{{alert.id}}`: ID of the alert that scheduled actions for the rule -* `{{alert.flapping}}`: A flag on the alert that indicates whether the alert status is changing repeatedly - -[[response-actions-object-schema]] -===== `response actions` schema - -All fields are required: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|action_type_id |String a|The response action you want to add to a rule. - -* `.osquery` -* `.endpoint` -+ -NOTE: To learn more about the requirements for using the isolate endpoint response action, refer to <>. -+ -IMPORTANT: Host isolation involves quarantining a host from the network to prevent further spread of threats and limit potential damage. Be aware that automatic host isolation can cause unintended consequences, such as disrupting legitimate user activities or blocking critical business processes. - -|params |Object a|Object containing the allowed response action fields, which varies according to the response action. - -*Osquery* - -For Osquery (`.osquery`), use a single query, a saved query, or a query pack: - -* `query` (string, optional): To run a single query, use the `query` field and enter a SQL query. Example: `"query": "SELECT * FROM processes;"` -* `saved_query_id` (string, optional): To run a saved query, use the `saved_query_id` field and specify the saved query ID. Example: `"saved_query_id": "processes_elastic"` -* `packId` (string, optional): To specify a query pack, use the `packId` field. Example: `"packId": "processes_elastic"` -* `ecs_mapping` (object, required): Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: `"ecs_mapping": {"process.pid": {"field": "pid"}}` -* `timeout` (number, optional): A timeout period, in seconds, after which the query will stop running. Overwriting the default timeout allows you to support queries that require more time to complete. The default and minimum supported value is `60`. The maximum supported value is `86400` (24 hours). Example: `"timeout": 120`. - -NOTE: Refer to {api-kibana}/operation/operation-osquerycreatelivequery[Create live query API] for more information about running Osquery queries and packs. - -*Endpoint Security* - -For Endpoint Security (`.endpoint`), specify an endpoint response action command and provide an optional comment: - -* `command` (string, optional): To run an endpoint response action, specify a value for the `command` field. Example: `"command": "isolate"` -+ -NOTE: The only action that's available is the isolate host response action (`isolate`). -* `comment` (string, optional): Add a note that explains or describes the action. You can find your comment in the <>. Example: `"comment": "Check processes"` - - -|============================================== - - -[[threats-object-create]] -===== `threat` schema - -All fields are required: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|framework |String |Relevant attack framework. - -|tactic |Object a|Object containing information on the attack type: - -* `id` - string, required -* `name` - string, required -* `reference` - string, required - -|technique |Array a|Array containing information on the attack techniques (optional): - -* `id` - string, required -* `name` - string, required -* `reference` - string, required -* `subtechnique` - Array, optional - -|subtechnique |Array a|Array containing more specific information on the attack technique: - -* `id` - string, required -* `name` - string, required -* `reference` - string, required - -|============================================== - -NOTE: Only threats described using the MITRE ATT&CK^TM^ framework are displayed -in the UI (*Rules* -> *Detection rules (SIEM)* -> *_Rule name_*). - -[[alert-suppression-duration-schema]] -===== `alert_suppression.duration` schema - -All fields are required: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|unit |string | Time unit. Possible values are: `s`(seconds), `m`(minutes), or `h`(hours). -|value |number | Positive number. - -|============================================== - -===== Example requests - -*Example 1* - -Query rule that searches for processes started by MS Office: - -[source,console] --------------------------------------------------- -POST api/detection_engine/rules -{ - "rule_id": "process_started_by_ms_office_program", - "risk_score": 50, - "description": "Process started by MS Office program - possible payload", - "interval": "1h", <1> - "name": "MS Office child process", - "severity": "low", - "tags": [ - "child process", - "ms office" - ], - "type": "query", - "from": "now-70m", <2> - "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", - "filters": [ - { - "query": { - "match": { - "event.action": { - "query": "Process Create (rule: ProcessCreate)", - "type": "phrase" - } - } - } - } - ], - "required_fields": [ - { name: "process.parent.name", "type": "keyword" } - ], - "related_integrations": [ - { "package": "o365", "version": "^2.3.2"} - ], - "enabled": false -} --------------------------------------------------- -// KIBANA - -<1> The rule runs every hour. -<2> When the rule runs it analyzes data from 70 minutes before its start time. - -If the rule starts to run at 15:00, it analyzes data from 13:50 until 15:00. -When it runs next, at 16:00, it will analyze data from 14:50 until 16:00. - -*Example 2* - -Threshold rule that detects multiple failed login attempts to a Windows host -from the same external source IP address, and maps the `severity` value to -custom source event fields: - -[source,console] --------------------------------------------------- -POST api/detection_engine/rules -{ - "description": "Detects when there are 20 or more failed login attempts from the same IP address with a 2 minute time frame.", - "enabled": true, - "exceptions_list": [ <1> - { - "id": "int-ips", - "namespace_type": "single", - "type": "detection" - } - ], - "from": "now-180s", - "index": [ - "winlogbeat-*" - ], - "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", - "severity_mapping": [ <2> - { - "field": "source.geo.city_name", - "operator": "equals", - "severity": "low", - "value": "Manchester" - }, - { - "field": "source.geo.city_name", - "operator": "equals", - "severity": "medium", - "value": "London" - }, - { - "field": "source.geo.city_name", - "operator": "equals", - "severity": "high", - "value": "Birmingham" - }, - { - "field": "source.geo.city_name", - "operator": "equals", - "severity": "critical", - "value": "Wallingford" - } - ], - "tags": [ - "Brute force" - ], - "threshold": { <3> - "field": "source.ip", - "value": 20 - }, - "type": "threshold" -} --------------------------------------------------- -// KIBANA - -<1> Exception list container used to exclude internal IP addresses. -<2> Alert severity levels are mapped according to the defined field values. -<3> Alerts are generated when the same source IP address is discovered in at -least 20 results. - -*Example 3* - -{ml-cap} rule that creates alerts, and sends Slack notifications, when the -`linux_anomalous_network_activity_ecs` {ml} job discovers anomalies with a -threshold of 70 or above: - -[source,console] --------------------------------------------------- -POST api/detection_engine/rules -{ - "anomaly_threshold": 70, - "rule_id": "ml_linux_network_high_threshold", - "risk_score": 70, - "machine_learning_job_id": "linux_anomalous_network_activity_ecs", - "description": "Generates alerts when the job discovers anomalies over 70", - "interval": "5m", - "name": "Anomalous Linux network activity", - "note": "Shut down the internet.", - "setup": "This rule requires data coming in from Elastic Defend." - "severity": "high", - "tags": [ - "machine learning", - "Linux" - ], - "type": "machine_learning", - "from": "now-6m", - "enabled": true, - "actions": [ - { - "action_type_id": ".slack", - "group": "default", - "id": "5ad22cd5-5e6e-4c6c-a81a-54b626a4cec5", - "params": { - "message": "Urgent: {{context.rule.description}}" - } - } - ] -} --------------------------------------------------- -// KIBANA - -*Example 4* - -Event correlation rule that creates alerts when the Windows `rundll32.exe` process makes -unusual network connections: - -[source,console] --------------------------------------------------- -POST api/detection_engine/rules -{ - "rule_id": "eql-outbound-rundll32-connections", - "risk_score": 21, - "description": "Unusual rundll32.exe network connection", - "name": "rundll32.exe network connection", - "severity": "low", - "tags": [ - "EQL", - "Windows", - "rundll32.exe" - ], - "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\")]", - "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 - -[[threat-match-example]] -*Example 5* - -Indicator match rule that creates an alert when one of the following is true: - -* The event's destination IP address *and* port number matches destination IP -*and* port values in the `threat_index` index. -* The event's source IP address matches a host IP address value in the -`threat_index` index. - -[source,console] --------------------------------------------------- -POST api/detection_engine/rules -{ - "type": "threat_match", - "actions": [], - "index": [ - "packetbeat-*" - ], - "query": "destination.ip:* or host.ip:*", - "threat_index": [ - "ip-threat-list" <1> - ], - "threat_query": "*:*", <2> - "threat_mapping": [ - { - "entries": [ <3> - { - "field": "destination.ip", - "type": "mapping", - "value": "destination.ip" - }, - { - "field": "destination.port", - "type": "mapping", - "value": "destination.port" - } - ] - }, - { - "entries": [ <4> - { - "field": "source.ip", - "type": "mapping", - "value": "host.ip" - } - ] - } - ], - "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", - "description": "Checks for bad IP addresses listed in the ip-threat-list index" -} --------------------------------------------------- -// KIBANA - -<1> The {es} index used for matching threat values. -<2> Query defining which threat index fields are used for matching values. In -this example, all values from the `ip-threat-list` index are used. -<3> Multiple objects in a single `entries` element are evaluated using `and` -logic. In this example, both the event's `destination.ip` and -`destination.port` values must match the corresponding field values in the -`ip-threat-list`. -<4> Sibling `entries` are evaluated using `or` logic. An alert is generated when -at least one `entries` object evaluates to `true`. - -*Example 6* - -New terms rule that creates alerts a new IP address is detected for a user: - -[source,console] --------------------------------------------------- -POST api/detection_engine/rules -{ - "risk_score": 21, - "description": "Detects a user associated with a new IP address", - "name": "New User IP Detected", - "severity": "medium", - "type": "new_terms", - "language": "kuery", - "query": "*", - "new_terms_fields": ["user.id", "source.ip"], - "history_window_start": "now-30d", - "index": ["auditbeat*"], - "required_fields": [ - { "name": "user.id", "type": "keyword" }, - { "name": "source.ip", "type": "ip" } - ] -} --------------------------------------------------- -// KIBANA - -*Example 7* - -{esql} rule that creates alerts from events that match an Excel parent process: - -[source,json] --------------------------------------------------- -POST api/detection_engine/rules -{ - "type": "esql", - "language": "esql", - "query": "from auditbeat-8.10.2 METADATA _id, _version, _index | where process.parent.name == \"EXCEL.EXE\"", - "name": "Find Excel events", - "description": "Find Excel events", - "tags": [], - "interval": "5m", - "from": "now-360s", - "to": "now", - "enabled": false, - "risk_score": 21, - "severity": "low", - "required_fields": [ - { "name": "process.parent.name", "type": "keyword" } - ] -} --------------------------------------------------- - - -*Example 8* - -Query rule that searches for processes started by MS Office and suppresses alerts by the `process.parent.name` field within a 5-hour time period: - -[source,console] --------------------------------------------------- -POST api/detection_engine/rules -{ - "rule_id": "process_started_by_ms_office_program", - "risk_score": 50, - "description": "Process started by MS Office program - possible payload", - "interval": "1h", - "name": "MS Office child process", - "severity": "low", - "tags": [ - "child process", - "ms office" - ], - "type": "query", - "from": "now-70m", - "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", - "filters": [ - { - "query": { - "match": { - "event.action": { - "query": "Process Create (rule: ProcessCreate)", - "type": "phrase" - } - } - } - } - ], - "enabled": false, - "alert_suppression": { - "duration": { "unit": "h", "value": 5 }, - "group_by": [ - "process.parent.name" - ], - "missing_fields_strategy": "suppress" - } -} --------------------------------------------------- - -==== Response code - -`200`:: - Indicates a successful call. - -==== Response payload - -A JSON object that includes a unique ID, the time the rule was created, and its -version number. If the request payload did not include a `rule_id` field, a -unique rule ID is also generated. - -Example response for a query rule: - -[source,json] --------------------------------------------------- -{ - "created_at": "2020-04-07T14:51:09.755Z", - "updated_at": "2020-04-07T14:51:09.970Z", - "created_by": "elastic", - "description": "Process started by MS Office program - possible payload", - "enabled": false, - "false_positives": [], - "from": "now-70m", - "id": "6541b99a-dee9-4f6d-a86d-dbd1869d73b1", - "immutable": false, - "interval": "1h", - "rule_id": "process_started_by_ms_office_program", - "max_signals": 100, - "risk_score": 50, - "name": "MS Office child process", - "references": [], - "severity": "low", - "updated_by": "elastic", - "tags": [ - "child process", - "ms office" - ], - "to": "now", - "type": "query", - "threat": [], - "version": 1, - "actions": [], - "filters": [ - { - "query": { - "match": { - "event.action": { - "query": "Process Create (rule: ProcessCreate)", - "type": "phrase" - } - } - } - } - ], - "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": [ - { "package": "o365", "version": "^2.3.2" }, - { "package": "azure", "version": "^1.11.4", "integration": "graphactivitylogs" } - ], - "required_fields": [ - { "name": "process.parent.name", "type": "keyword", "ecs": true } - ], - "setup": "" -} --------------------------------------------------- - -Example response for a {ml} job rule: - -[source,json] --------------------------------------------------- -{ - "created_at": "2020-04-07T14:45:15.679Z", - "updated_at": "2020-04-07T14:45:15.892Z", - "created_by": "elastic", - "description": "Generates alerts when the job discovers anomalies over 70", - "enabled": true, - "false_positives": [], - "from": "now-6m", - "id": "83876f66-3a57-4a99-bf37-416494c80f3b", - "immutable": false, - "interval": "5m", - "rule_id": "ml_linux_network_high_threshold", - "max_signals": 100, - "risk_score": 70, - "name": "Anomalous Linux network activity", - "references": [], - "severity": "high", - "updated_by": "elastic", - "tags": [ - "machine learning", - "Linux" - ], - "to": "now", - "type": "machine_learning", - "threat": [], - "version": 1, - "actions": [ - { - "action_type_id": ".slack", - "group": "default", - "id": "5ad22cd5-5e6e-4c6c-a81a-54b626a4cec5", - "params": { - "message": "Urgent: {{context.rule.description}}" - }, - "frequency": { - "summary": true, - "notifyWhen": "onActiveAlert", - "throttle": null - } - } - ], - "note": "Shut down the internet.", - "status": "going to run", - "status_date": "2020-04-07T14:45:21.685Z", - "anomaly_threshold": 70, - "machine_learning_job_id": "linux_anomalous_network_activity_ecs", - "related_integrations": [], - "required_fields": [], - "setup": "" -} --------------------------------------------------- - -Example response for a threshold rule: - -[source,json] --------------------------------------------------- -{ - "author": [], - "created_at": "2020-07-22T10:27:23.486Z", - "updated_at": "2020-07-22T10:27:23.673Z", - "created_by": "elastic", - "description": "Detects when there are 20 or more failed login attempts from the same IP address with a 2 minute time frame.", - "enabled": true, - "false_positives": [], - "from": "now-180s", - "id": "15dbde26-b627-4d74-bb1f-a5e0ed9e4993", - "immutable": false, - "interval": "2m", - "rule_id": "liv-win-ser-logins", - "max_signals": 100, - "risk_score": 30, - "risk_score_mapping": [], - "name": "Windows server prml-19", - "references": [], - "severity": "low", - "severity_mapping": [ - { - "field": "source.geo.city_name", - "operator": "equals", - "severity": "low", - "value": "Manchester" - }, - { - "field": "source.geo.city_name", - "operator": "equals", - "severity": "medium", - "value": "London" - }, - { - "field": "source.geo.city_name", - "operator": "equals", - "severity": "high", - "value": "Birmingham" - }, - { - "field": "source.geo.city_name", - "operator": "equals", - "severity": "critical", - "value": "Wallingford" - } - ], - "updated_by": "elastic", - "tags": [ - "Brute force" - ], - "to": "now", - "type": "threshold", - "threat": [], - "version": 1, - "exceptions_list": [ - { - "id": "int-ips", - "namespace_type": "single", - "type": "detection" - } - ], - "actions": [], - "index": [ - "winlogbeat-*" - ], - "query": "host.name:prml-19 and event.category:authentication and event.outcome:failure", - "language": "kuery", - "threshold": { - "field": "source.ip", - "value": 20 - }, - "related_integrations": [ - { "package": "o365", "version": "^2.3.2" } - ], - "required_fields": [ - { "name": "source.ip", "type": "ip", "ecs": true } - ], - "setup": "" -} --------------------------------------------------- - -Example response for an EQL rule: - -[source,json] --------------------------------------------------- -{ - "author": [], - "created_at": "2020-10-05T09:06:16.392Z", - "updated_at": "2020-10-05T09:06:16.403Z", - "created_by": "elastic", - "description": "Unusual rundll32.exe network connection", - "enabled": true, - "false_positives": [], - "from": "now-6m", - "id": "93808cae-b05b-4dc9-8479-73574b50f8b1", - "immutable": false, - "interval": "5m", - "rule_id": "eql-outbound-rundll32-connections", - "max_signals": 100, - "risk_score": 21, - "risk_score_mapping": [], - "name": "rundll32.exe network connection", - "references": [], - "severity": "low", - "severity_mapping": [], - "updated_by": "elastic", - "tags": [ - "EQL", - "Windows", - "rundll32.exe" - ], - "to": "now", - "type": "eql", - "threat": [], - "version": 1, - "exceptions_list": [], - "throttle": "no_actions", - "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": [ - { "package": "o365", "version": "^2.3.2" } - ], - "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": "" -} --------------------------------------------------- - -Example response for an indicator match rule: - -[source,json] --------------------------------------------------- -{ - "author": [], - "created_at": "2020-10-06T07:07:58.227Z", - "updated_at": "2020-10-06T07:07:58.237Z", - "created_by": "elastic", - "description": "Checks for bad IP addresses listed in the ip-threat-list index", - "enabled": true, - "false_positives": [], - "from": "now-6m", - "id": "d5daa13f-81fb-4b13-be2f-31011e1d9ae1", - "immutable": false, - "interval": "5m", - "rule_id": "608501e4-c768-4f64-9326-cec55b5d439b", - "max_signals": 100, - "risk_score": 50, - "risk_score_mapping": [], - "name": "Bad IP threat match", - "references": [], - "severity": "medium", - "severity_mapping": [], - "updated_by": "elastic", - "tags": [], - "to": "now", - "type": "threat_match", - "threat": [], - "version": 1, - "exceptions_list": [], - "index": [ - "packetbeat-*" - ], - "query": "destination.ip:* or host.ip:*", - "language": "kuery", - "threat_query": "*:*", - "threat_index": [ - "ip-threat-list" - ], - "threat_mapping": [ - { - "entries": [ - { - "field": "destination.ip", - "type": "mapping", - "value": "destination.ip" - }, - { - "field": "destination.port", - "type": "mapping", - "value": "destination.port" - } - ] - }, - { - "entries": [ - { - "field": "source.ip", - "type": "mapping", - "value": "host.ip" - } - ] - } - ], - "related_integrations": [ - { "package": "o365", "version": "^2.3.2" } - ], - "required_fields": [ - { "name": "destination.ip", "type": "ip", "ecs": true }, - { "name": "destination.port", "type": "long", "ecs": true }, - { "name": "host.ip", "type": "ip", "ecs": true } - ], - "setup": "" -} --------------------------------------------------- - -Example response for a new terms rule: - -[source,json] --------------------------------------------------- -{ - "author": [], - "created_at": "2020-10-06T07:07:58.227Z", - "updated_at": "2020-10-06T07:07:58.237Z", - "created_by": "elastic", - "description": "Detects a user associated with a new IP address", - "enabled": true, - "false_positives": [], - "from": "now-6m", - "id": "eb7225c0-566b-11ee-8b4f-bbf3afdeb9f4", - "immutable": false, - "interval": "5m", - "rule_id": "c6f5d0bc-7be9-47d4-b2f3-073d22641e30", - "max_signals": 100, - "risk_score": 21, - "risk_score_mapping": [], - "name": "New User IP Detected", - "references": [], - "severity": "medium", - "severity_mapping": [], - "updated_by": "elastic", - "tags": [], - "to": "now", - "type": "new_terms", - "threat": [], - "version": 1, - "exceptions_list": [], - "index": [ - "auditbeat*" - ], - "query": "*", - "language": "kuery", - "new_terms_fields": ["user.id", "source.ip"], - "history_window_start": "now-30d", - "related_integrations": [ - { "package": "o365", "version": "^2.3.2" } - ], - "required_fields": [ - { "name": "user.id", "type": "keyword", "ecs": true }, - { "name": "source.ip", "type": "ip", "ecs": true } - ], - "setup": "" -} --------------------------------------------------- - -Example response for an {esql} rule: - -[source,json] --------------------------------------------------- -{ - "name": "Find Excel events", - "description": "Find Excel events", - "risk_score": 21, - "severity": "low", - "output_index": "", - "tags": [], - "interval": "5m", - "enabled": false, - "author": [], - "false_positives": [], - "from": "now-360s", - "max_signals": 100, - "risk_score_mapping": [], - "severity_mapping": [], - "threat": [], - "to": "now", - "references": [], - "version": 1, - "exceptions_list": [], - "actions": [], - "id": "d0f20490-6da4-11ee-b85e-09e9b661f2e2", - "updated_at": "2023-10-18T10:55:14.269Z", - "updated_by": "elastic", - "created_at": "2023-10-18T10:55:14.269Z", - "created_by": "elastic", - "revision": 0, - "rule_id": "e4b53a89-debd-4a0d-a3e3-20606952e589", - "immutable": false, - "related_integrations": [ - { "package": "o365", "version": "^2.3.2" } - ], - "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\"" -} --------------------------------------------------- diff --git a/docs/detections/api/rules/rules-api-delete.asciidoc b/docs/detections/api/rules/rules-api-delete.asciidoc deleted file mode 100644 index b9984f3ac0..0000000000 --- a/docs/detections/api/rules/rules-api-delete.asciidoc +++ /dev/null @@ -1,36 +0,0 @@ -[[rules-api-delete]] -=== Delete rule - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-detections-api[detections APIs]. --- - -Deletes a single rule using the `rule_id` or `id` field. - -==== Request URL - -`DELETE :/api/detection_engine/rules` - -===== URL query parameters - -The URL query must include one of the following: - -* `id` - `DELETE /api/detection_engine/rules?id=` -* `rule_id`- `DELETE /api/detection_engine/rules?rule_id=` - -===== Example request - -Deletes the rule with an `id` value of `16947168-5405-453d-a8b5-aadad357af42`: - -[source,console] --------------------------------------------------- -DELETE api/detection_engine/rules?id=16947168-5405-453d-a8b5-aadad357af42 --------------------------------------------------- -// KIBANA - -==== Response code - -`200`:: - Indicates a successful call. diff --git a/docs/detections/api/rules/rules-api-export.asciidoc b/docs/detections/api/rules/rules-api-export.asciidoc deleted file mode 100644 index b63830e9cc..0000000000 --- a/docs/detections/api/rules/rules-api-export.asciidoc +++ /dev/null @@ -1,101 +0,0 @@ -[[rules-api-export]] -=== Export rules - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-detections-api[detections APIs]. --- - -Exports rules to an `.ndjson` file. The following configuration items are also included in the `.ndjson` file: - -* Actions -* Exception lists - -You cannot export prebuilt rules, but they are available at https://github.com/elastic/detection-rules/tree/main/rules/. - -[IMPORTANT] -================= -Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) _is not_ included. You must re-add missing connector details after importing detection rules. - -You can use {kib}'s {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI (*Stack Management* -> *Kibana* -> *Saved Objects*) or the Saved Objects APIs (experimental) to {kibana-ref}/saved-objects-api-export.html[export] and {kibana-ref}/saved-objects-api-import.html[import] any necessary connectors before importing detection rules. - -Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the <> UI (*Rules* -> *Detection rules (SIEM)* -> *Manage value lists*) to export and import value lists separately. -================= - -==== Request URL - -`POST :/api/detection_engine/rules/_export` - - -===== URL query parameters - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`exclude_export_details` |Boolean |Determines whether a summary of the -exported rules is returned.|No, defaults to `false`. -|`file_name` |String |File name for saving the exported rules. |No, defaults to -`export.ndjson` -|============================================== - -TIP: When using cURL to export rules to a file, use the `-O` and `-J` options -to save the rules to the file name specified in the URL. - -==== Request body - -An optional JSON `objects` array containing the `rule_id` fields of the rules -you want to export: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`objects` |String[] |Array of `rule_id` fields. |No, exports all rules when -unspecified. -|============================================== - - -===== Example request - -Exports two rules without details and saves them to the `exported_rules.ndjson` -file: - -[source,console] --------------------------------------------------- -POST api/detection_engine/rules/_export?exclude_export_details=true&file_name=exported_rules.ndjson -{ - "objects": [ - { - "rule_id":"343580b5-c811-447c-8d2d-2ccf052c6900" - }, - { - "rule_id":"2938c9fa-53eb-4c04-b79c-33cbf041b18d" - } - ] -} --------------------------------------------------- -// KIBANA - - -==== Response code - -`200`:: - Indicates a successful call. - -===== Response payload - -An `.ndjson` file containing the returned rules. - -Each line in the file represents an object (a rule, exception list parent container, or exception list item), and the last line includes a summary of what was exported. - -Example response payload: - -[source,json] --------------------------------------------------- -{"id":"d4db8800-30df-11ec-88a5-fb21b48c9b4e","rule_id":"query-with-single-exception-list"[....]} // Rule -{"id":"cd62f410-30de-11ec-88a5-fb21b48c9b4e","list_id":"simple_list"[...]} // Exception list parent container -{"id":"e54ffbe0-30de-11ec-88a5-fb21b48c9b4e","item_id":"my-exception-item","list_id":"simple_list"[...]} // Exception list item -{"exported_rules_count":1,"missing_rules":[],"missing_rules_count":0,"exported_exception_list_count":1,"exported_exception_list_item_count":1,"missing_exception_list_item_count":0,"missing_exception_list_items":[],"missing_exception_lists":[],"missing_exception_lists_count":0} // Export summary --------------------------------------------------- diff --git a/docs/detections/api/rules/rules-api-find.asciidoc b/docs/detections/api/rules/rules-api-find.asciidoc deleted file mode 100644 index c9a4306a83..0000000000 --- a/docs/detections/api/rules/rules-api-find.asciidoc +++ /dev/null @@ -1,153 +0,0 @@ -[[rules-api-find]] -=== Find rules - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-detections-api[detections APIs]. --- - -Retrieves a paginated subset of detection rules. By default, the first -page is returned with 20 results per page. - -==== Request URL - -`GET :/api/detection_engine/rules/_find` - -===== URL query parameters - -All parameters are optional: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|`page` |Integer |The page number to return. - -|`per_page` |Integer |The number of rules to return per page. - -|`sort_field` |String |Determines which field is used to sort the results. - -|`sort_order` |String |Determines the sort order, which can be `desc` or `asc`. - -|`filter` |String a|Filters the returned results according to the value of the -specified field, using the `alert.attributes.:` -syntax, where `` can be: - -* `name` -* `enabled` -* `tags` -* `createdBy` -* `interval` -* `updatedBy` - -NOTE: Even though the JSON rule object uses `created_by` and `updated_by` -fields, you must use `createdBy` and `updatedBy` fields in the filter. -|============================================== - -===== Example request - -Retrieves the first five rules with the word `windows` in their names, sorted -in ascending order: - -[source,console] --------------------------------------------------- -GET api/detection_engine/rules/_find?page=1&per_page=5&sort_field=enabled&sort_order=asc&filter=alert.attributes.name:windows --------------------------------------------------- -// KIBANA - -==== Response code - -`200`:: - Indicates a successful call. - -==== Response payload - -A JSON object containing a summary and the returned rules. - -Example response: - -[source,json] --------------------------------------------------- -{ - "page": 1, - "perPage": 5, - "total": 4, - "data": [ - { - "created_at": "2020-02-02T10:05:19.613Z", - "updated_at": "2020-02-02T10:05:19.830Z", - "created_by": "elastic", - "description": "Identifies a PowerShell process launched by either cscript.exe or wscript.exe. Observing Windows scripting processes executing a PowerShell script, may be indicative of malicious activity.", - "enabled": false, - "false_positives": [], - "from": "now-6m", - "id": "89761517-fdb0-4223-b67b-7621acc48f9e", - "immutable": true, - "index": [ - "winlogbeat-*" - ], - "interval": "5m", - "rule_id": "f545ff26-3c94-4fd0-bd33-3c7f95a3a0fc", - "language": "kuery", - "max_signals": 33, - "risk_score": 21, - "name": "Windows Script Executing PowerShell", - "query": "event.action:\"Process Create (rule: ProcessCreate)\" and process.parent.name:(\"wscript.exe\" or \"cscript.exe\") and process.name:\"powershell.exe\"", - "references": [], - "severity": "low", - "updated_by": "elastic", - "tags": [ - "Elastic", - "Windows" - ], - "to": "now", - "related_integrations": [ - { "package": "o365", "version": "^2.3.2"} - ], - "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": [ - { - "framework": "MITRE ATT&CK", - "tactic": { - "id": "TA0002", - "name": "Execution", - "reference": "https://attack.mitre.org/tactics/TA0002/" - }, - "technique": [ - { - "id": "T1193", - "name": "Spearphishing Attachment", - "reference": "https://attack.mitre.org/techniques/T1193/" - } - ] - } - ], - "execution_summary": { <1> - "last_execution": { - "date": "2022-03-23T16:06:12.787Z", - "status": "partial failure", - "status_order": 20, - "message": "This rule attempted to query data from Elasticsearch indices listed in the \"Index pattern\" section of the rule definition, but no matching index was found.", - "metrics": { - "total_search_duration_ms": 135, - "total_indexing_duration_ms": 15, - "execution_gap_duration_s": 0, - } - } - }, - "version": 1 - }, - ... - ] -} - --------------------------------------------------- - -<1> dev:[] These fields are under development and their usage or schema may change: `execution_summary`. diff --git a/docs/detections/api/rules/rules-api-get.asciidoc b/docs/detections/api/rules/rules-api-get.asciidoc deleted file mode 100644 index 443d800104..0000000000 --- a/docs/detections/api/rules/rules-api-get.asciidoc +++ /dev/null @@ -1,127 +0,0 @@ -[[rules-api-get]] -=== Get rule - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-detections-api[detections APIs]. --- - -Retrieves a single rule using the `rule_id` or `id` field. - -==== Request URL - -`GET :/api/detection_engine/rules` - -===== URL query parameters - -The URL query must include one of the following: - -* `id` - `GET /api/detection_engine/rules?id=` -* `rule_id` - `GET /api/detection_engine/rules?rule_id=` - -===== Example request - -Retrieves the rule with an `id` value of `c41d170b-8ba6-4de6-b8ec-76440a35ace3`: - -[source,console] --------------------------------------------------- -GET api/detection_engine/rules?id=c41d170b-8ba6-4de6-b8ec-76440a35ace3 --------------------------------------------------- -// KIBANA - -==== Response code - -`200`:: - Indicates a successful call. - -==== Response payload - -The returned rule's JSON object. - -Example response: - -[source,json] --------------------------------------------------- -{ - "created_at": "2020-02-03T11:19:04.259Z", - "updated_at": "2020-02-03T11:19:04.462Z", - "created_by": "elastic", - "description": "Process started by MS Office program in user folder", - "enabled": false, - "false_positives": [], - "filters": [ - { - "query": { - "match": { - "event.action": { - "query": "Process Create (rule: ProcessCreate)", - "type": "phrase" - } - } - } - } - ], - "from": "now-4200s", - "id": "c41d170b-8ba6-4de6-b8ec-76440a35ace3", - "immutable": false, - "interval": "1h", - "rule_id": "process_started_by_ms_office_user_folder", - "related_integrations": [ - { "package": "o365", "version": "^2.3.2"} - ], - "required_fields": [ - { "name": "process.name", "type": "keyword", "ecs": true }, - { "name": "process.parent.name", "type": "keyword", "ecs": true } - ], - "setup": "", - "language": "kuery", - "max_signals": 100, - "risk_score": 21, - "name": "MS Office child process", - "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", - "references": [], - "severity": "low", - "updated_by": "elastic", - "tags": [ - "child process", - "ms office" - ], - "to": "now-300s", - "type": "query", - "threat": [ - { - "framework": "MITRE ATT&CK", - "tactic": { - "id": "TA0001", - "reference": "https://attack.mitre.org/tactics/TA0001", - "name": "Initial Access" - }, - "technique": [ - { - "id": "T1193", - "name": "Spearphishing Attachment", - "reference": "https://attack.mitre.org/techniques/T1193" - } - ] - } - ], - "execution_summary": { <1> - "last_execution": { - "date": "2022-03-23T16:06:12.787Z", - "status": "partial failure", - "status_order": 20, - "message": "This rule attempted to query data from Elasticsearch indices listed in the \"Index pattern\" section of the rule definition, but no matching index was found.", - "metrics": { - "total_search_duration_ms": 135, - "total_indexing_duration_ms": 15, - "execution_gap_duration_s": 0, - } - } - }, - "version": 1 -} - --------------------------------------------------- - -<1> dev:[] These fields are under development and their usage or schema may change: `execution_summary`. diff --git a/docs/detections/api/rules/rules-api-import.asciidoc b/docs/detections/api/rules/rules-api-import.asciidoc deleted file mode 100644 index 6c554ccb86..0000000000 --- a/docs/detections/api/rules/rules-api-import.asciidoc +++ /dev/null @@ -1,98 +0,0 @@ -[[rules-api-import]] -=== Import rules - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-detections-api[detections APIs]. --- - -Imports rules from an `.ndjson` file. The following configuration items are also included in the `.ndjson` file: - -* Actions -* Exception lists - -[WARNING] -==== -When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running. - -If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change. -==== - -NOTE: To import rules with actions, you need at least `Read` privileges for the `Action and Connectors` feature. To overwrite or add new connectors, you need `All` privileges for the `Actions and Connectors` feature. To import rules without actions, you don't need `Actions and Connectors` privileges. Refer to <> for more information. - -[IMPORTANT] -================= -Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) _is not_ included. You must re-add missing connector details after importing detection rules. - -You can use {kib}'s {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI (*Stack Management* -> *Kibana* -> *Saved Objects*) or the Saved Objects APIs (experimental) to {kibana-ref}/saved-objects-api-export.html[export] and {kibana-ref}/saved-objects-api-import.html[import] any necessary connectors before importing detection rules. - -Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the <> UI (*Rules* -> *Detection rules (SIEM)* -> *Manage value lists*) to export and import value lists separately. -================= - -==== Request URL - -`POST :/api/detection_engine/rules/_import` - -The request must include: - -* The `Content-Type: multipart/form-data` HTTP header. -* A link to the `.ndjson` file containing the rules. - -For example, using cURL: - -[source,console] --------------------------------------------------- -curl -X POST "/api/detection_engine/rules/_import" --u : -H 'kbn-xsrf: true' --H 'Content-Type: multipart/form-data' ---form "file=@" <1> --------------------------------------------------- -<1> The relative link to the `.ndjson` file containing the rules. - -===== URL query parameters - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`overwrite` |Boolean |Determines whether existing rules with the same -`rule_id` are overwritten. |No, defaults to `false`. -|`overwrite_exceptions` |Boolean |Determines whether existing exception lists -with the same `list_id` are overwritten. Both the exception list container and -its items are overwritten. |No, defaults to `false`. -|`overwrite_action_connectors` |Boolean |Determines whether existing actions with the same -`kibana.alert.rule.actions.id` are overwritten. |No, defaults to `false`. -|============================================== - -===== Example request - -Imports the rules in the `detection_rules.ndjson` file and overwrites -existing rules with the same `rule_id` values: - -[source,console] --------------------------------------------------- -curl -X POST "api/detection_engine/rules/_import?overwrite=true" --H 'kbn-xsrf: true' -H 'Content-Type: multipart/form-data' ---form "file=@detection_rules.ndjson" --------------------------------------------------- - -==== Response code - -`200`:: - Indicates a successful call. - -===== Example response - -[source,json] --------------------------------------------------- -{ - "success": true, - "success_count": 1, - "rules_count": 1, - "errors": [], - "exceptions_errors": [], - "exceptions_success": true, - "exceptions_success_count": 0 -} --------------------------------------------------- diff --git a/docs/detections/api/rules/rules-api-overview.asciidoc b/docs/detections/api/rules/rules-api-overview.asciidoc deleted file mode 100644 index 14ec399be2..0000000000 --- a/docs/detections/api/rules/rules-api-overview.asciidoc +++ /dev/null @@ -1,72 +0,0 @@ -[[rule-api-overview]] -[role="xpack"] -== Detections API - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-detections-api[detections APIs]. --- - -You can create rules that automatically turn events and external alerts sent to -{elastic-sec} into detection alerts. These alerts are displayed on the Detections -page. - -For more information about the differences between events, -external alerts, and detection alerts, see the -{glossary}/terms.html[Elastic Glossary]. - -The API has these endpoints: - -* `:/api/detection_engine/rules` - Detection rules CRUD functions -* `:/api/detection_engine/index` - Signal index operations -(used to store detection alerts) -* `:/api/detection_engine/tags` - Aggregates and returns rule -tags -* `:/api/detection_engine/rules/_import` - Imports rules from an -`.ndjson` file -* `:/api/detection_engine/rules/_export` - Exports rules to an -`.ndjson` file -* `:/api/detection_engine/privileges` - Returns the user's -{kib} space and signal index permissions, and whether the user is authenticated -* `:/api/detection_engine/signals` - Aggregates, queries, and -returns alerts, and updates their statuses -* `:/api/detection_engine/rules/prepackaged` - Loads and retrieves -the status of Elastic <> -* `:/api/detection_engine//exceptions` - Creates a default exception list for the rule you specify -* `:/api/detection_engine/rules//exceptions` - Creates exception items for a rule's default exception list. - -TIP: You can view and download a Detections API Postman collection -https://github.com/elastic/examples/tree/master/Security%20Analytics/SIEM-examples/Detections-API[here]. - -[float] -=== Authentication -This API supports both key- and token-based authentication. - -To use key-based authentication, create an {kibana-ref}/api-keys.html[API key], then specify the key in the header of your API calls. - -To use token-based authentication, provide a username and password; this automatically creates an API key that matches the current user's privileges. - -In both cases, the API key is subsequently used for authorization when the rule runs. - -[WARNING] -==== -If the API key has different privileges than the key that created or most recently updated the rule, the rule behavior might change. - -If the key that created the rule gets deleted, or the user that created the rule becomes inactive, the rule will stop running. -==== - -[float] -=== Kibana role requirements - -To create and run rules, the user role for the {kib} space must have: - -* {kib} space `All` privileges for the `Security` and `Saved Objects Management` -features (see -{kibana-ref}/xpack-spaces.html#spaces-control-user-access[Feature access based on user privileges]). -* `read` and `write` privileges for the `.siem-signals-*` index (the system index -used for storing detection alerts created from rules). - - - -See <> for a complete list of requirements. diff --git a/docs/detections/api/rules/rules-api-prebuilt.asciidoc b/docs/detections/api/rules/rules-api-prebuilt.asciidoc deleted file mode 100644 index 009a3c3b3c..0000000000 --- a/docs/detections/api/rules/rules-api-prebuilt.asciidoc +++ /dev/null @@ -1,86 +0,0 @@ -[[prebuilt-rules-api]] -[role="xpack"] -=== Prebuilt rules - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-detections-api[detections APIs]. --- - -The prepackaged endpoint is for retrieving rule statuses and loading Elastic -prebuilt detection rules. - -==== Load prebuilt rules - -Loads and updates Elastic prebuilt rules. - -NOTE: By default, all loaded prebuilt rules are disabled. - -===== Request URL - -`PUT :/api/detection_engine/rules/prepackaged` - -====== Example request - -[source,console] --------------------------------------------------- -PUT api/detection_engine/rules/prepackaged --------------------------------------------------- -// KIBANA - -===== Response code - -`200`:: - Indicates a successful call. - -====== Response payload - -A JSON object listing the number of loaded and updated prebuilt rules. - -Example response: - -[source,json] --------------------------------------------------- -{ - "rules_installed": 112, - "rules_updated": 0 -} --------------------------------------------------- - -==== Get rule status - -Returns rule statuses. - -===== Request URL - -`GET :/api/detection_engine/rules/prepackaged/_status` - -====== Example request - -[source,console] --------------------------------------------------- -GET api/detection_engine/rules/prepackaged/_status --------------------------------------------------- -// KIBANA - -===== Response code - -`200`:: - Indicates a successful call. - -====== Response payload - -A JSON object listing rule statuses. - -Example response: - -[source,json] --------------------------------------------------- -{ - "rules_custom_installed": 0, - "rules_installed": 0, - "rules_not_installed": 112, - "rules_not_updated": 0 -} --------------------------------------------------- diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc deleted file mode 100644 index 5857693fe0..0000000000 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ /dev/null @@ -1,698 +0,0 @@ -[[rules-api-update]] -=== Update rule - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-detections-api[detections APIs]. --- - -[WARNING] -==== -When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running. - -If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change. -==== - -Updates an existing detection rule. - -You can use `PUT` or `PATCH` methods to update rules, where: - -* `PUT` replaces the original rule and deletes fields that are not specified. -* `PATCH` updates the specified fields. - -==== Request URL - -`PUT :/api/detection_engine/rules` - -`PATCH :/api/detection_engine/rules` - -==== Request body - -A JSON object with: - -* The `id` or `rule_id` field of the rule you want to update. -* The fields you want to modify. - -IMPORTANT: If you call `PUT` to update a rule, all unspecified fields are -deleted. You cannot modify the `id` or `rule_id` values. - -For `PATCH` calls any of the fields can be modified, whereas for `PUT` calls -some fields are required. - -===== Fields required for `PUT` calls - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|description |String |The rule's description. - -|name |String |The rule's name. - -|risk_score |Integer a|A numerical representation of the alert's severity from -0 to 100, where: - -* `0` - `21` represents low severity -* `22` - `47` represents medium severity -* `48` - `73` represents high severity -* `74` - `100` represents critical severity - -|severity |String a|Severity level of alerts produced by the rule, which must -be one of the following: - -* `low`: Alerts that are of interest but generally not considered to be -security incidents -* `medium`: Alerts that require investigation -* `high`: Alerts that require immediate investigation -* `critical`: Alerts that indicate it is highly likely a security incident has -occurred - -|type |String a|Data type on which the rule is based: - -* `eql`: EQL query (see {ref}/eql.html[Event Query Language]). -* `esql`: ES\|QL query (refer to {ref}/esql.html[Elasticsearch Query Language]). -* `query`: query with or without additional filters. -* `saved_query`: saved search, identified in the `saved_id` field. -* `machine_learning`: rule based on a {ml} job's anomaly scores. -* `threat_match`: rule that matches event values with values in the specified -{es} index. -* `threshold`: rule based on the number of times a `query` matches the -specified field. -* `new_terms`: rule that alerts on values that have not been seen before - -|============================================== - -===== Field required for query, threat-match, threshold, and new terms rules `PUT` calls - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|query |String a|{kibana-ref}/search.html[Query] used by the rule to create -alerts. For threat-match rules, only the query's results are used to determine -whether an alert is generated. - -|============================================== - -===== Field required for threshold rules `PUT` calls - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|threshold |Object a|Defines the field and threshold value for when alerts -are generated, where: - -* `cardinality` (Array of length 1): The field on which the cardinality is applied. -* `cardinality.field` (string, required): The field on which to calculate and compare the -cardinality. -* `cardinality.value` (integer, required): The threshold value from which an alert is -generated based on unique number of values of `cardinality.field`. -* `field` (string or string[], required): The field on which the threshold is applied. If -you specify an empty array (`[]`), alerts are generated when the query returns -at least the number of results specified in the `value` field. -* `value` (integer, required): The threshold value from which an alert is -generated. - -|============================================== - -===== Field required for saved-query rules `PUT` calls - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|saved_id |String |Kibana saved search used by the rule to create alerts. - -|============================================== - -===== Field required for EQL rules `PUT` calls - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|language |String |Must be `eql`. - -|============================================== - -===== Field required for {esql} rules `PUT` calls - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|language |String |Must be `esql`. - -|============================================== - -===== Fields required for machine-learning rules `PUT` calls - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|anomaly_threshold |Integer |Anomaly score threshold above which the rule -creates an alert. Valid values are from `0` to `100`. - -|machine_learning_job_id |String |{ml-cap} job ID the rule monitors for -anomaly scores. - -|============================================== - -===== Fields required for threat-match rules `PUT` calls - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|threat_index |String[] |{es} indices used to check which field values generate -alerts. - -|threat_query |String |Query used to determine which fields in the {es} index -are used for generating alerts. - -|threat_mapping |Object[] a|Array of `entries` objects that define mappings -between the source event fields and the values in the {es} threat index. Each -`entries` object must contain these fields: - -* `field`: field from the event indices on which the rule runs -* `type`: must be `mapping` -* `value`: field from the {es} threat index - -You can use Boolean `and` and `or` logic to define the conditions for when -matching fields and values generate alerts. Sibling `entries` objects -are evaluated using `or` logic, whereas multiple entries in a single `entries` -object use `and` logic. See <> for an example that -uses both `and` and `or` logic. - -|============================================== - -===== Fields required for new terms rules `PUT` calls - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|new_terms_fields |String[] |Fields to monitor for new values. Must contain 1–3 field names. - -|history_window_start |String |Start date to use when checking if a term has been seen before. -Supports relative dates – for example, `now-30d` will search the last 30 days of data when checking if a term -is new. We do not recommend using absolute dates, which can cause issues with rule performance -due to querying increasing amounts of data over time. - -|============================================== - -===== Optional fields for all rule types - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|actions |<> |Array defining the automated -actions (notifications) taken when alerts are generated. - -|author |String[] |The rule's author. - -|building_block_type |String |Determines if the rule acts as a building block. -By default, building-block alerts are not displayed in the UI. These rules are -used as a foundation for other rules that do generate alerts. Its value must be -`default`. For more information, refer to <>. - -|enabled |Boolean |Determines whether the rule is enabled. Defaults to `true`. - -|false_positives |String[] |String array used to describe common reasons why -the rule may issue false-positive alerts. Defaults to an empty array. - -[[detection-rules-from]] -|from |String |Time from which data is analyzed each time the rule executes, -using a {ref}/common-options.html#date-math[date math range]. For example, -`now-4200s` means the rule analyzes data from 70 minutes before its start -time. Defaults to `now-6m` (analyzes data from 6 minutes before the start -time). - -|interval |String |Frequency of rule execution, using a -{ref}/common-options.html#date-math[date math range]. For example, `"1h"` -means the rule runs every hour. Defaults to `5m` (5 minutes). - -|license |String |The rule's license. - -|max_signals |Integer a|Maximum number of alerts the rule can create during a -single run (the rule's **Max alerts per run** <> value). Defaults to `100`. - -NOTE: This setting can be superseded by the {kibana-ref}/alert-action-settings-kb.html#alert-settings[{kib} configuration setting] `xpack.alerting.rules.run.alerts.max`, which determines the maximum alerts generated by _any_ rule in the {kib} alerting framework. For example, if `xpack.alerting.rules.run.alerts.max` is set to `1000`, the rule can generate no more than 1000 alerts even if `max_signals` is set higher. - -|meta |Object a|Placeholder for metadata about the rule. - -*NOTE*: This field is overwritten when you save changes to the rule's settings. - -|note |String |Notes to help investigate alerts produced by the rule. - -|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. - -|tags |String[] |String array containing words and phrases to help categorize, -filter, and search rules. Defaults to an empty array. - -|threat |<> |Object containing attack -information about the type of threat the rule monitors, see -{ecs-ref}/ecs-threat.html[ECS threat fields]. Defaults to an empty array. - -|throttle |String a|Determines how often actions are taken: - -[NOTE] -===== -The rule level `throttle` field is deprecated in {elastic-sec} 8.8 and will remain active for at least the next 12 months. - -In {elastic-sec} 8.8 and later, you can use the (<>) field to define frequencies for individual actions. Actions without frequencies will acquire a converted version of the rule's `throttle` field. In the response, the converted `throttle` setting appears in the individual actions' `frequency` field. -===== - -* `no_actions`: Never -* `rule`: Every time new alerts are detected -* `1h`: Every hour -* `1d`: Every day -* `7d`: Every week - -Required when `actions` are used to send notifications. - -|version |Integer a|The rule's version number. If this is not provided, the -rule's version number is incremented by 1. - -`PATCH` calls enabling and disabling the rule do not increment its version -number. - -|related_integrations |Object[] a| {integrations-docs}[Elastic integrations] the rule depends on. The object has these fields: - -* `package` (String, required): The integration package's name, as used by the https://github.com/elastic/package-registry[Elastic Package Registry]. -* `integration` (String, optional): The integration's name. This field is optional for packages with only one integration whose name matches the package name, but it's required for packages with multiple integrations. -* `version`: (String, required): Integration (package containing the integration) version constraint in https://semver.org/[semantic versioning] format. For version ranges, you must use tilde or caret syntax. For example, `~1.2.3` is from 1.2.3 to any patch version less than `1.3.0`, and `^1.2.3` is from `1.2.3`` to any minor and patch version less than `2.0.0`. - -|============================================== - -===== Optional fields for threat-match rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|threat_filters |Object[] -|{ref}/query-filter-context.html[Query and filter context] array used to filter -documents from the {es} index containing the threat values. - -|threat_indicator_path |String -|Much like an ingest processor, users can use this field to define where their threat indicator can be found on their indicator documents. Defaults to `threatintel.indicator`. -|============================================== - -===== Optional fields for query, threat-match, threshold, and new terms rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|language |String |Determines the query language, which must be -`kuery` or `lucene`. Defaults to `kuery`. -|============================================== - -===== Optional fields for EQL, query, threshold, indicator match, new terms rules, and {esql} rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|filters |Object[] a|The {ref}/query-filter-context.html[query and filter -context] array used to define the conditions for when alerts are created from -events. Defaults to an empty array. - -NOTE: This field is not supported for ES\|QL rules. - -|index |String[] a|Indices on which the rule functions. Defaults to the -Security Solution indices defined on the {kib} Advanced Settings page -(*Kibana* → *Stack Management* → *Advanced Settings* → -`securitySolution:defaultIndex`). - -NOTE: This field is not supported for ES\|QL rules. - -|risk_score_mapping |Object[] a|Overrides generated alerts' `risk_score` with -a value from the source event: - -* `field` (string, required): Source event field used to override the default -`risk_score`. This field must be an integer. -* `operator` (string, required): Must be `equals`. -* `value`(string, required): Must be an empty string (`""`). - -|rule_name_override |String |Sets which field in the source event is used to -populate the alert's `signal.rule.name` value (in the UI, this value is -displayed on the *Rules* page in the *Rule* column). When unspecified, the -rule's `name` value is used. The source field must be a string data type. - -|severity_mapping |Object[] a|Overrides generated alerts' `severity` with -values from the source event: - -* `field` (string, required): Source event field used to override the default -`severity`. -* `operator` (string, required): Must be `equals`. -* `severity` (string, required): Mapped severity value, must be `low`, -`medium`, `high`, or `critical`. -* `value`(string, required): Field value used to determine the `severity`. - -|timestamp_override |String |Sets the time field used to query indices. -When unspecified, rules query the `@timestamp` field. The source field -must be an {es} date data type. - -|exceptions_list |Object[] a|Array of -{api-kibana}/operation/group/endpoint-security-exceptions-api[exception containers], which define -exceptions that prevent the rule from generating alerts even when its other -criteria are met. The object has these fields: - -* `id` (string, required): ID of the exception container. -* `list_id` (string, required): List ID of the exception container. -* `namespace_type` (string required): Determines whether the exceptions are -valid in only the rule's {kib} space (`single`) or in all {kib} spaces -(`agnostic`). -* `type` (string, required): The exception type, which must be either -a detection rule exception (`detection`) or an endpoint exception (`endpoint`). - -|============================================== - -[[opt-fields-eql-update]] -===== Optional fields for EQL rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|event_category_field |String -|Contains the event classification, such as `process`, `file`, or `network`. This field is typically mapped as a field type in the {ref}/keyword.html[keyword family]. Defaults to the `event.category` ECS field. - -|tiebreaker_field |String -|Sets a secondary field for sorting events (in ascending, lexicographic order) if they have the same timestamp. - -|timestamp_field |String -|Contains the event timestamp used for sorting a sequence of events. This is different from `timestamp_override`, which is used for querying events within a range. Defaults to the `@timestamp` ECS field. - -|============================================== - -[[actions-object-schema-update]] -===== `actions` schema - -These fields are required when calling `PUT` to modify the `actions` object: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|action_type_id |String a|The action type used for sending notifications, can -be: - -* `.slack` -* `.slack_api` -* `.email` -* `.index` -* `.pagerduty` -* `.swimlane` -* `.webhook` -* `.servicenow` -* `.servicenow-itom` -* `.servicenow-sir` -* `.jira` -* `.resilient` -* `.opsgenie` -* `.teams` -* `.torq` -* `.tines` -* `.d3security` - -|group |String |Optionally groups actions by use cases. Use `default` for alert -notifications. - -|id |String |The connector ID. - -|params |Object a|Object containing the allowed connector fields, which varies according to the connector type: - -* For Slack: -** `message` (string, required): The notification message. -* For email: -** `to`, `cc`, `bcc` (string): Email addresses to which the notifications are -sent. At least one field must have a value. -** `subject` (string, optional): Email subject line. -** `message` (string, required): Email body text. -* For Webhook: -** `body` (string, required): JSON payload. -* For PagerDuty: -** `severity` (string, required): Severity of on the alert notification, can -be: `Critical`, `Error`, `Warning` or `Info`. -** `eventAction` (string, required): Event https://v2.developer.pagerduty.com/docs/events-api-v2#event-action[action type], which can be `trigger`, -`resolve`, or `acknowledge`. -** `dedupKey` (string, optional): Groups alert notifications with the same -PagerDuty alert. -** `timestamp` (DateTime, optional): https://v2.developer.pagerduty.com/v2/docs/types#datetime[ISO-8601 format timestamp]. -** `component` (string, optional): Source machine component responsible for the -event, for example `security-solution`. -** `group` (string, optional): Enables logical grouping of service components. -** `source` (string, optional): The affected system. Defaults to the {kib} -saved object ID of the action. -** `summary` (string, options): Summary of the event. Defaults to -`No summary provided`. Maximum length is 1024 characters. -** `class` (string, optional): Value indicating the class/type of the event. - -|============================================== - -[discrete] -[[optional-actions-fields-rule-update]] -===== Optional `action` fields - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|frequency |String a|Object containing an action’s frequency: - -* `summary` (Boolean, required): Defines whether to send notifications as a summary of alerts or for each generated alert. - -* `notifyWhen` (String, required`): Defines how often alerts generate actions. Valid values are: - -** `onActiveAlert`: Actions run when the alert is generated. -** `onThrottleInterval`: Actions run on the specified throttle interval and summarize new alerts generated during that interval. - -* `throttle` (String, optional): Defines how often an alert generates repeated actions. This custom action interval must be specified in seconds, minutes, hours, or days. For example, `10m` or `1h`. This property is used only if `notifyWhen` is `onThrottleInterval`. - -|alerts_filter |Object a|Object containing an action’s conditional filters: - -* `timeframe` (Object, optional): Object containing the time frame for when this action can be run. - -** `days` (Array of integers, required): List of days of the week on which this action can be run. Days of the week are expressed as numbers between `1-7`, where `1` is Monday and `7` is Sunday. To select all days of the week, enter an empty array. -** `hours` (Object, required): The hours of the day during which this action can run. Hours of the day are expressed as two strings in the format `hh:mm` in `24` hour time. A start of `00:00` and an end of `24:00` means the action can run all day. -*** `start` (String, required) -*** `end` (String, required) - -** `timezone` (String, required): An ISO timezone name, such as `Europe/Madrid` or `America/New_York`. Specific offsets such as UTC or UTC+1 will also work, but lack built-in DST. - -* `query` (Object, optional): Object containing a query filter which gets applied to an action and determines whether the action should run. -** `kql` (String, required): A KQL string. -** `filters` (Array of objects, required): A filter object, as defined in the `kbn-es-query` package. - -|============================================== - - -[[threats-object-update]] -===== `threat` schema - -These fields are required when calling `PUT` to modify the `threat` object: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|framework |String |Relevant attack framework. - -|tactic |Object a|Object containing information on the attack type: - -* `id` - string, required -* `name` - string, required -* `reference` - string, required - -|technique |Object a|Object containing information on the attack -technique: - -* `id` - string, required -* `name` - string, required -* `reference` - string, required - -|============================================== - -NOTE: Only threats described using the MITRE ATT&CK^TM^ framework are displayed -in the UI (*Rules* -> *Detection rules (SIEM)* -> *_Rule name_*). - - -[[opt-fields-alert-suppression-update]] -===== Optional alert suppression fields for query, indicator match, threshold, event correlation (non-sequence queries only), new terms, {esql}, and {ml} rules - -preview::["Alert suppression is in technical preview for event correlation rules. The functionality may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features."] - -====== Query, indicator match, event correlation (non-sequence queries only), new terms, {esql}, and {ml} rules - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|alert_suppression |Object a|Defines alert suppression configuration. Available fields: - -* `group_by` (string[], required): An array of 1-3 field names to use for suppressing alerts. - -* `duration` (<>, optional): The time period in which alerts will be suppressed, beginning when the rule first meets its criteria and creates the alert. If not specified, alerts will be suppressed on rule execution only. - -* `missing_fields_strategy` (string, optional): Defines how to handle events with missing suppression fields. Possible values: - - - `doNotSuppress`: Create a separate alert for each matching event. - - - `suppress`: Create one alert for each group of events with missing fields. - -|============================================== - -====== Threshold rule - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|alert_suppression a|Object |Defines alert suppression configuration. Available fields: - -* `duration` (<>, required): The time period in which alerts will be suppressed, beginning when the rule first meets its criteria and creates the alert. - -|============================================== - -===== Example request - -Updates the `threat` object: - -[source,console] --------------------------------------------------- -PATCH api/detection_engine/rules -{ - "rule_id": "process_started_by_ms_office_program_possible_payload", - "threat": [ - { - "framework": "MITRE ATT&CK", - "tactic": { - "id": "TA0001", - "reference": "https://attack.mitre.org/tactics/TA0001", - "name": "Initial Access" - }, - "technique": [ - { - "id": "T1193", - "name": "Spearphishing Attachment", - "reference": "https://attack.mitre.org/techniques/T1193" - } - ] - } - ] -} --------------------------------------------------- -// KIBANA - -==== Response code - -`200`:: - Indicates a successful call. - -==== Response payload - -The rule's updated JSON object, including the time the rule was updated and an -incremented version number. - -Example response: - -[source,json] --------------------------------------------------- -{ - "created_at": "2020-01-05T09:56:11.805Z", - "updated_at": "2020-01-05T09:59:59.129Z", - "created_by": "elastic", - "description": "Process started by MS Office program - possible payload", - "enabled": false, - "false_positives": [], - "filters": [ - { - "query": { - "match": { - "event.action": { - "query": "Process Create (rule: ProcessCreate)", - "type": "phrase" - } - } - } - } - ], - "from": "now-6m", - "id": "4f228868-9928-47e4-9785-9a1a9b520c7f", - "interval": "5m", - "rule_id": "process_started_by_ms_office_program_possible_payload", - "language": "kuery", - "max_signals": 100, - "risk_score": 50, - "name": "MS Office child process", - "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", - "references": [], - "severity": "low", - "updated_by": "elastic", - "tags": [ - "child process", - "ms office" - ], - "related_integrations": [ - { "package": "o365", "version": "^2.3.2"} - ], - "required_fields": [ - { "name": "process.parent.name", "type": "keyword", "ecs": true } - ], - "setup": "", - "type": "query", - "threat": [ - { - "framework": "MITRE ATT&CK", - "tactic": { - "id": "TA0001", - "reference": "https://attack.mitre.org/tactics/TA0001", - "name": "Initial Access" - }, - "technique": [ - { - "id": "T1193", - "name": "Spearphishing Attachment", - "reference": "https://attack.mitre.org/techniques/T1193" - } - ] - } - ], - "execution_summary": { <1> - "last_execution": { - "date": "2022-03-23T16:06:12.787Z", - "status": "partial failure", - "status_order": 20, - "message": "This rule attempted to query data from Elasticsearch indices listed in the \"Index pattern\" section of the rule definition, but no matching index was found.", - "metrics": { - "total_search_duration_ms": 135, - "total_indexing_duration_ms": 15, - "execution_gap_duration_s": 0, - } - } - }, - "version": 2 -} --------------------------------------------------- - -<1> dev:[] These fields are under development and their usage or schema may change: `execution_summary`. diff --git a/docs/detections/api/rules/signals-api-overview.asciidoc b/docs/detections/api/rules/signals-api-overview.asciidoc deleted file mode 100644 index 2936722c83..0000000000 --- a/docs/detections/api/rules/signals-api-overview.asciidoc +++ /dev/null @@ -1,444 +0,0 @@ -[[signals-api-overview]] -[role="xpack"] -=== Signals endpoint - -:frontmatter-description: Use the signals endpoint to retrieve, aggregate, and update alerts. -:frontmatter-tags-products: [security, alerting] -:frontmatter-tags-content-type: [reference] -:frontmatter-tags-user-goals: [manage] - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-detections-api[detections APIs]. --- - -The signals endpoint is for retrieving, aggregating, and updating detection -alerts. For detailed information on how to retrieve and aggregate results from -the indices, see: - -* {ref}/getting-started-search.html[Start searching indices] -* {ref}/search-aggregations.html[Aggregations] -* {ref}/query-dsl.html[Query DSL] - -==== Get alerts - -Aggregates and returns alerts. - -===== Request URL - -`POST :/api/detection_engine/signals/search` - -===== Request body - -A query DSL that determines which results are returned. - -====== Example request - -Gets aggregated results of all open alerts with a risk score equal to or -greater than 70. It also returns the timestamps of the oldest and -newest alerts that meet the query's criteria. - -[source,console] --------------------------------------------------- -POST api/detection_engine/signals/search -{ - "aggs": { - "latest": { - "max": { - "field": "@timestamp" - } - }, - "oldest": { - "min": { - "field": "@timestamp" - } - } - }, - "query": { - "bool": { - "filter": [ - { - "match": { - "signal.status": "open" - } - }, - { - "range": { - "signal.rule.risk_score": { - "gte": 70 - } - } - } - ] - } - } -} --------------------------------------------------- - -Gets all in-progress alerts with a risk score equal to or -greater than 70. - -[source,console] --------------------------------------------------- -POST api/detection_engine/signals/search -{ - "query": { - "bool": { - "filter": [ - { - "match": { - "signal.status": "in-progress" - } - }, - { - "range": { - "signal.rule.risk_score": { - "gte": 70 - } - } - } - ] - } - } -} --------------------------------------------------- -// KIBANA - -===== Response code - -`200`:: - Indicates a successful call. - -====== Response payload - -A JSON object with the aggregated values and requested alerts. - -Example response: - -[source,json] --------------------------------------------------- -{ - "took": 3, - "timed_out": false, - "_shards": { - "total": 1, - "successful": 1, - "skipped": 0, - "failed": 0 - }, - "hits": { - "total": { - "value": 8794, - "relation": "eq" - }, - "max_score": null, - "hits": [] - }, - "aggregations": { - "oldest": { - "value": 1576601119930, - "value_as_string": "2019-12-17T16:45:19.930Z" - }, - "latest": { - "value": 1576634706400, - "value_as_string": "2019-12-18T02:05:06.400Z" - } - } -} --------------------------------------------------- - -==== Set alert status - -Sets the status of one or more alert. - -===== Request URL - -`POST :/api/detection_engine/signals/status` - -===== Request body - -A JSON object with either a `query` or `signals_id` field: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`signal_ids` |String[] |Array of alert IDs. |Yes, when the `query` field is -not used. - -|`query` |Query DSL |Query that determines which alerts are updated. |Yes, when -the `signal_ids` field is not used. - -|`status` |String |The new status, which can be `open`, `acknowledged`, or -`closed`. |Yes. - -|============================================== - -====== Example requests - -Closes alerts with `signal_ids`: - -[source,console] --------------------------------------------------- -POST api/detection_engine/signals/status -{ - "signal_ids": [ - "694156bbe6a487e06d049bd6019bd49fec4172cfb33f5d81c3b4a977f0026fba", - "f4d1c62c4e8946c835cb497329127803c09b955de49a8fa186be3899522667b0" - ], - "status": "closed" -} --------------------------------------------------- -// KIBANA - -Closes alerts that are over a month old and have a risk score less than or -equal to 20: - -[source,json] --------------------------------------------------- -POST api/detection_engine/signals/status -{ - "query": { - "bool": { - "filter": [ - { - "range": { - "signal.rule.risk_score": { - "lte": 20 - } - } - }, - { - "range": { - "@timestamp": { - "lte": "now-M" - } - } - } - ] - } - }, - "status": "closed" -} --------------------------------------------------- -// KIBANA - -===== Response code - -`200`:: - Indicates a successful call. - -====== Response payload - -A JSON object containing the number of updated alerts. - -Example response: - -[source,json] --------------------------------------------------- -{ - "took": 9594, - "timed_out": false, - "total": 8794, - "updated": 8794, - "deleted": 0, - "batches": 9, - "version_conflicts": 0, - "noops": 0, - "retries": { - "bulk": 0, - "search": 0 - }, - "throttled_millis": 0, - "requests_per_second": -1, - "throttled_until_millis": 0, - "failures": [] -} --------------------------------------------------- - - -==== Apply alert tags - -Add and remove alert tags. - -===== Request URL - -`POST :/api/detection_engine/signals/tags` - -===== Request body - -A JSON object with the `tags` and `ids` fields: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`tags` |Object a|Object containing alert tags. Alert tags are the words and phrases that help categorize alerts. - -Properties of the `tags` object: - -* `tags_to_add`: (Required, string[]) Array of tags you want to add. -* `tags_to_remove`: (Required, string[]) Array of tags you want to remove. - -NOTE: You cannot add and remove the same alert tag. - -|No - -|`ids` |String[] |Array of alert IDs.|Yes - -|============================================== - -====== Example requests - -Adds and remove tags to alerts: - -[source,console] --------------------------------------------------- -POST api/detection_engine/signals/tags -{ - "tags": { - "tags_to_add": ["False Positive"], - "tags_to_remove": ["Further Investigation Required"] - }, - "ids": [ - "694156bbe6a487e06d049bd6019bd49fec4172cfb33f5d81c3b4a977f0026fba", - "f4d1c62c4e8946c835cb497329127803c09b955de49a8fa186be3899522667b0" - ] -} --------------------------------------------------- - -===== Response code - -`200`:: - Indicates a successful call. - -====== Response payload - -A JSON object containing alerts with newly added or removed alert tags. - -Example response: - -[source,json] --------------------------------------------------- -{ - "took": 699, - "errors": false, - "items": [ - { - "update": { - "_index": ".internal.alerts-security.alerts-default-000001", - "_id": "694156bbe6a487e06d049bd6019bd49fec4172cfb33f5d81c3b4a977f0026fba", - "_version": 2, - "result": "updated", - "_shards": { - "total": 1, - "successful": 1, - "failed": 0 - }, - "_seq_no": 137, - "_primary_term": 1, - "status": 200 - } - }, - { - "update": { - "_index": ".internal.alerts-security.alerts-default-000001", - "_id": "f4d1c62c4e8946c835cb497329127803c09b955de49a8fa186be3899522667b0", - "_version": 2, - "result": "updated", - "_shards": { - "total": 1, - "successful": 1, - "failed": 0 - }, - "_seq_no": 138, - "_primary_term": 1, - "status": 200 - } - } - ] -} --------------------------------------------------- - -==== Assign or unassign users from alerts - -Allows you to assign and unassign users from alerts. - -===== Request URL - -`POST :/api/detection_engine/signals/assignees` - -===== Request body - -A JSON object with the `assignees` and `ids` fields: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`assignees` |Object[] a|An array of unique identifiers (UIDs) for user profiles. Properties of the `assignees` object: - -* `add`: (Required, string[]) An array of assignees you want to add. -* `remove`: (Required, string[]) An array of assignees you want to unassign. - -NOTE: You cannot add and remove the same assignee. -|Yes - -|`ids` |String[] |An array of alert IDs. |Yes - -|============================================== - -====== Example request - -Assigns and unassigns users to alerts: - -[source,console] --------------------------------------------------- -POST api/detection_engine/signals/assignees - -{ - "assignees": { - "add": ["u_o4kzon2tUP0u189YjKVT0rTR_HBOED3JmyLLE6MrulY_0"], - "remove": ["u_P4HW8xg4_xRVI7Oa-i6Ys1Gxe7k3jqZteAeZe6ZctEc_0"] - }, - "ids": [ - "854f5eceeec1b4cd5495ad18c4259d6e5631a6677bc10c033edb318397d45459", - "00968e97805854d0aa356968cad971d5184cdf91ebd458720c5b4099f4a5229a" - ] -} --------------------------------------------------- -// KIBANA - -===== Response code - -`200`:: - Indicates a successful call. - -====== Response payload - -A JSON object containing the number of updated alerts. - -Example response: - -[source,json] --------------------------------------------------- -{ - "took": 67, - "timed_out": false, - "total": 2, - "updated": 2, - "deleted": 0, - "batches": 1, - "version_conflicts": 0, - "noops": 0, - "retries": { - "bulk": 0, - "search": 0 - }, - "throttled_millis": 0, - "requests_per_second": -1, - "throttled_until_millis": 0, - "failures": [] -} --------------------------------------------------- diff --git a/docs/detections/api/rules/tags-api-overview.asciidoc b/docs/detections/api/rules/tags-api-overview.asciidoc deleted file mode 100644 index 5ecde95f95..0000000000 --- a/docs/detections/api/rules/tags-api-overview.asciidoc +++ /dev/null @@ -1,50 +0,0 @@ -[[tags-api-overview]] -[role="xpack"] -=== Tags endpoint - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-detections-api[detections APIs]. --- - -Aggregates and returns all rule tags. - -==== Get tags - -Aggregates and returns all unique tags from all rules. - -===== Request URL - -`GET :/api/detection_engine/tags` - -====== Example request - -Gets tags for all rules in the {kib} default space: - -[source,console] --------------------------------------------------- -GET api/detection_engine/tags --------------------------------------------------- -// KIBANA - -===== Response code - -`200`:: - Indicates a successful call. - -====== Example response - -[source,json] --------------------------------------------------- -[ - "zeek", - "suricata", - "windows", - "linux", - "network", - "initial access", - "remote access", - "phishing" -] --------------------------------------------------- diff --git a/docs/detections/api/signals-migration-api.asciidoc b/docs/detections/api/signals-migration-api.asciidoc deleted file mode 100644 index 52111fa4e1..0000000000 --- a/docs/detections/api/signals-migration-api.asciidoc +++ /dev/null @@ -1,241 +0,0 @@ -[[signals-migration-api]] -[role="xpack"] -== Detection Alerts Migration API - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-detections-api[detections APIs]. --- - -After upgrading {kib}, the latest {elastic-sec} features will be available for any newly generated detection alerts. However, in order to enable new features for existing detection alerts, migration may be necessary. See {security-guide}/upgrade-intro.html[Upgrade {elastic-sec}] for instructions specific to your upgrade. - -Migrating detection alerts is performed at the index level and requires the following steps: - -1. <> -2. <> -3. <> -4. <> (optional) - -[[migration-1]] -[float] -=== Determine which indices to migrate -You can use the Migration Status API to determine which indices contain detection alerts of a particular age, along with migration info for each of those indices. - -[float] -==== Request - -`GET :/api/detection_engine/signals/migration_status?from=now-30d` - -[float] -==== Request query parameters - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|`from` |datemath|Maximum age of qualifying detection alerts -|============================================== - -[float] -==== Response example - -[source,json] --------------------------------------------------- -{ - "indices": [ - { - "index": ".siem-signals-default-000002", - "version": 15, - "signal_versions": [ - { - "version": 15, - "count": 100 - }, - { - "version": 16, - "count": 87 - } - ], - "migrations": [ - { - "id": "924f7c50-505f-11eb-ae0a-3fa2e626a51d", - "status": "pending", - "version": 16, - "updated": "2021-01-06T20:41:37.173Z" - } - ], - "is_outdated": true - }, - { - "index": ".siem-signals-default-000003", - "version": 16, - "signal_versions": [ - { - "version": 16, - "count": 54 - } - ], - "migrations": [], - "is_outdated": false - } - ] -} --------------------------------------------------- -The above response shows two indices: `.siem-signals-default-000002` is outdated, with multiple versions of detection alerts and a pending migration, and `.siem-signals-default-000003`, which is up to date as the current write index. - -NOTE: Indices that do not contain detection alerts in the specified range will be filtered from the response. - -With the above info, we can compile a list of indices that we wish to migrate. - -*Find outdated detection alerts with threat intelligence data* - -After upgrading to {stack} version 7.15.x from release versions 7.12.0 through 7.14.2, you need to migrate detection alerts enriched with threat intelligence data to ensure threat intelligence properly displays in {elastic-sec}. Run this query to find outdated detection alerts with threat intelligence data: - -[source,json] --------------------------------------------------- -GET .siem-signals-{KIBANA SPACE ID}/_search -{ - "query": { - "nested": { - "path": "threat.indicator", - "query": { - "exists": { - "field": "threat.indicator.matched.*" - } - } - } - } -} --------------------------------------------------- - - -[[migration-2]] -[float] -=== Initiate migrations - -Migrations are initiated per index. While the process is neither destructive nor interferes with existing data, it may be resource-intensive. As such, it is recommended that you plan your migrations accordingly. - -[float] -==== Request - -`POST :/api/detection_engine/signals/migration` - -[float] -==== Request body - -[width="100%",options="header"] -|============================================== -|Name |Type |Description | Required - -|`index` |String[]|Array of index names to migrate|Yes -|`size`|Integer|Number of alerts to migrate per batch. Corresponds to the `source.size` option on the {ref}/docs-reindex.html[Reindex API]|No -|`requests_per_second`|Integer|The throttle for the migration task in sub-requests per second. Corresponds to `requests_per_second` on the {ref}/docs-reindex.html[Reindex API]| No -|`slices`|Integer|The number of subtasks for the migration task. Corresponds to `slices` on the {ref}/docs-reindex.html[Reindex API]|No -|============================================== - -[float] -==== Response example - -[source,json] --------------------------------------------------- -{ - "indices": [ - { - "index": ".siem-signals-default-000001", - "migration_id": "923f7c50-505f-11eb-ae0a-3fa2e626a51d", - "migration_index": ".siem-signals-default-000001-r000016" - } - ] -} --------------------------------------------------- -The response will include, for each index specified, an ID and destination index for the migration, and an error if unsuccessful. - -[[migration-3]] -[float] -=== Finalize migrations - -The finalization endpoint replaces the original index's alias with the successfully migrated index's alias. The endpoint is idempotent; therefore, it can safely be used to poll a given migration and, upon completion, finalize it. - -NOTE: The original indices are not removed as part of this step. After verifying the integrity of the migrated index, you can use the <> endpoint to apply a 30-day deletion policy to the original, outdated index. - -NOTE: If an unsuccessful migration is finalized, a deletion policy will be applied to its index, causing it to be deleted after 30 days. - -[float] -==== Request - -`POST :/api/detection_engine/signals/finalize_migration` - -[float] -==== Request body - -[width="100%",options="header"] -|============================================== -|Name |Type |Description | Required - -|`migration_ids` |String[]|Array of `migration_id`s to finalize|Yes -|============================================== - -[float] -==== Response example - -[source,json] --------------------------------------------------- -{ - "migrations": [ - { - "id": "924f7c50-505f-11eb-ae0a-3fa2e626a51d", - "completed": true, - "destinationIndex": ".siem-signals-default-000002-r000016", - "status": "success", - "sourceIndex": ".siem-signals-default-000002", - "version": 16, - "updated": "2021-01-06T22:05:56.859Z" - } - ] -} --------------------------------------------------- -Finalized migrations will show a response of `completed: true`, with a corresponding `status`. If the migration is still running when you attempt to finalize it, its response will show as `completed: false`. - -[float] -[[migration-4]] -=== Migration cleanup - -Migrations favor data integrity over shard size. Consequently, unused or orphaned indices are artifacts of the migration process. A successful migration will result in both the old and new indices being present. As such, the old, orphaned index can (and likely should) be deleted. - -While you can delete these indices manually, the endpoint accomplishes this task by applying a deletion policy to the relevant index, causing it to be deleted after 30 days. It also deletes other artifacts specific to the migration implementation. - -[float] -==== Request - -`DELETE :/api/detection_engine/signals/migration` - -[float] -==== Request body - -[width="100%",options="header"] -|============================================== -|Name |Type |Description | Required - -|`migration_ids` |String[]|Array of `migration_id`s to finalize|Yes -|============================================== - -[float] -==== Response example - -[source,json] --------------------------------------------------- - { - "migrations": [ - { - "id": "924f7c50-505f-11eb-ae0a-3fa2e626a51d", - "destinationIndex": ".siem-signals-default-000002-r000016", - "status": "success", - "sourceIndex": ".siem-signals-default-000002", - "version": 16, - "updated": "2021-01-06T22:05:56.859Z" - } - ] -} --------------------------------------------------- -The response will include all migrations that were successfully deleted. diff --git a/docs/detections/detection-engine-intro.asciidoc b/docs/detections/detection-engine-intro.asciidoc index eb341fdebf..8badb056cf 100644 --- a/docs/detections/detection-engine-intro.asciidoc +++ b/docs/detections/detection-engine-intro.asciidoc @@ -40,8 +40,7 @@ After rules have started running, you can monitor their executions to verify they are functioning correctly, as well as view, manage, and troubleshoot alerts (see <> and <>). -You can create and manage rules and alerts via the UI or the -<>. +You can create and manage rules and alerts via the UI or the {api-kibana}/group/endpoint-security-detections-api[Detections API]. [IMPORTANT] ============== diff --git a/docs/detections/rules-ui-create.asciidoc b/docs/detections/rules-ui-create.asciidoc index 27ef2c5878..db55a69a5d 100644 --- a/docs/detections/rules-ui-create.asciidoc +++ b/docs/detections/rules-ui-create.asciidoc @@ -754,7 +754,7 @@ The following variables can only be passed if the rule’s action frequency is f [[placeholder-examples]] ===== Alert placeholder examples -To understand which fields to parse, see the <> to view the JSON representation of rules. +To understand which fields to parse, see the {api-kibana}/group/endpoint-security-detections-api[Detections API] to view the JSON representation of rules. Example using `{{context.rule.filters}}` to output a list of filters: diff --git a/docs/post-upgrade/post-upgrade-req-cti-alerts.asciidoc b/docs/post-upgrade/post-upgrade-req-cti-alerts.asciidoc index d0440c807e..438d585af0 100644 --- a/docs/post-upgrade/post-upgrade-req-cti-alerts.asciidoc +++ b/docs/post-upgrade/post-upgrade-req-cti-alerts.asciidoc @@ -9,7 +9,7 @@ To migrate detection alerts: . Ensure that all <> prior to upgrading your {stack}. . Upgrade Kibana. See {kibana-ref}/upgrade.html[Upgrade {kib}] for more information. . Visit the Overview or Alerts page in {elastic-sec} to update the detection alert indices. -. Migrate old alerts using the <>. +. Migrate old alerts using the {api-kibana}/operation/operation-createalertsmigration[detection alert migration API]. . <>. [float] diff --git a/docs/post-upgrade/post-upgrade-req.asciidoc b/docs/post-upgrade/post-upgrade-req.asciidoc index 4fe8e7565c..a4dd07cff0 100644 --- a/docs/post-upgrade/post-upgrade-req.asciidoc +++ b/docs/post-upgrade/post-upgrade-req.asciidoc @@ -4,7 +4,7 @@ After upgrading from {stack} version 7.9.x from a previous minor release (7.8.x, etc.), you need to update `.siem-signals*` system index mappings to enable the <>, which shows graphical representations of process relationships. -NOTE: If you are upgrading from a minor release to {stack} version >= 7.11.0, there is now a <> that you can use instead of the manual process described below. +NOTE: If you are upgrading from a minor release to {stack} version >= 7.11.0, there is now a {api-kibana}/operation/operation-createalertsmigration[detection alert migration API] that you can use instead of the manual process described below. To update the `.siem-signals*` index: diff --git a/docs/release-notes/8.0.asciidoc b/docs/release-notes/8.0.asciidoc index ef1c459e4a..c6a0b1642e 100644 --- a/docs/release-notes/8.0.asciidoc +++ b/docs/release-notes/8.0.asciidoc @@ -177,7 +177,7 @@ NOTE: If new alerts are generated in an upgraded environment without legacy aler Rules are automatically disabled during the upgrade process and must be manually re-enabled after the process completes. Failure to do so could cause a gap in rule coverage ({kibana-pull}120906[#120906]). -Before upgrading, use the <> API to retrieve a list of enabled detection rules in your environment. You can reference this list when re-enabling rules after you upgrade. +Before upgrading, use the {api-kibana}/operation/operation-readrule[Find rules] API to retrieve a list of enabled detection rules in your environment. You can reference this list when re-enabling rules after you upgrade. We recommend using curl or another HTTP tool to securely run {elastic-sec} APIs. Below is an example curl command that retrieves a list of your enabled rules: @@ -192,7 +192,7 @@ After upgrading, follow these steps to re-enable your rules from the Rules page: . Select the rules that you want to enable. . Click *Bulk actions -> Enable* to re-enable the rules. -Alternatively, you can use the <> API to re-enable rules. +Alternatively, you can use the {api-kibana}/operation/operation-performrulesbulkaction[bulk rule actions API] to re-enable rules. *Lucene 9 validation change may affect event correlation rules* diff --git a/docs/release-notes/8.12.asciidoc b/docs/release-notes/8.12.asciidoc index 0320441d59..af491c7c40 100644 --- a/docs/release-notes/8.12.asciidoc +++ b/docs/release-notes/8.12.asciidoc @@ -103,7 +103,7 @@ Select the **Edit the query filter using DSL** option. Configuration options for rule action frequency are unavailable when creating and editing rules. Rules with action frequencies that are already configured still run correctly. *Workaround* + -Use the <> API to change a rule's action frequency settings. Alternatively, export a rule, update its action frequency settings, and then re-import the rule. +Use the {api-kibana}/operation/operation-updaterule[update rule API] to change a rule's action frequency settings. Alternatively, export a rule, update its action frequency settings, and then re-import the rule. ==== // end::known-issue-175043[] diff --git a/docs/release-notes/8.2.asciidoc b/docs/release-notes/8.2.asciidoc index 303d004aea..aa293a6642 100644 --- a/docs/release-notes/8.2.asciidoc +++ b/docs/release-notes/8.2.asciidoc @@ -64,11 +64,11 @@ ==== Deprecations The following endpoints are deprecated ({kibana-pull}129448[#129448]) and will be removed in a future release. They will remain active for at least the next 18 months: -* <> -* <> -* <> +* `/api/detection_engine/rules/_bulk_create` +* `/api/detection_engine/rules/_bulk_delete` +* `/api/detection_engine/rules/_bulk_update` -To avoid breakage, we recommend using the <> API instead for similar bulk actions. You can also use the <>, <>, and <> rule APIs to manage rules individually. +To avoid breakage, we recommend using the {api-kibana}/operation/operation-performrulesbulkaction[bulk rule actions API] instead for similar bulk actions. You can also use the {api-kibana}/operation/operation-createrule[create], {api-kibana}/operation/operation-updaterule[update], and {api-kibana}/operation/operation-deleterule[delete] rule APIs to manage rules individually. [discrete] [[breaking-changes-8.2.0]] diff --git a/docs/release-notes/8.5.asciidoc b/docs/release-notes/8.5.asciidoc index a33ffc41a2..83dfb8da17 100644 --- a/docs/release-notes/8.5.asciidoc +++ b/docs/release-notes/8.5.asciidoc @@ -10,7 +10,7 @@ ==== Known issues * The rule details page and **Edit rule settings** page load indefinitely if you edit a rule that has the `saved_id` property configured. All rule types, except for the custom query rule, are affected. + -Upgrading to 8.6 or higher resolves this issue. If you’d prefer to stay on 8.5, use the <> to remove the `saved_id` field from the non-functioning `query`, `eql`, `machine_learning`, `threat_match`, `threshold`, or `new_terms` rule. +Upgrading to 8.6 or higher resolves this issue. If you’d prefer to stay on 8.5, use the {api-kibana}/operation/operation-updaterule[update rule API] to remove the `saved_id` field from the non-functioning `query`, `eql`, `machine_learning`, `threat_match`, `threshold`, or `new_terms` rule. [discrete] [[bug-fixes-8.5.3]] @@ -28,7 +28,7 @@ Upgrading to 8.6 or higher resolves this issue. If you’d prefer to stay on 8.5 ==== Known issues * The rule details page and **Edit rule settings** page load indefinitely if you edit a rule that has the `saved_id` property configured. All rule types, except for the custom query rule, are affected. + -Upgrading to 8.6 or higher resolves this issue. If you’d prefer to stay on 8.5, use the <> to remove the `saved_id` field from the non-functioning `query`, `eql`, `machine_learning`, `threat_match`, `threshold`, or `new_terms` rule. +Upgrading to 8.6 or higher resolves this issue. If you’d prefer to stay on 8.5, use the {api-kibana}/operation/operation-updaterule[update rule API] to remove the `saved_id` field from the non-functioning `query`, `eql`, `machine_learning`, `threat_match`, `threshold`, or `new_terms` rule. [discrete] [[bug-fixes-8.5.2]] @@ -44,7 +44,7 @@ There are no user-facing changes in 8.5.2. ==== Known issues * The rule details page and **Edit rule settings** page load indefinitely if you edit a rule that has the `saved_id` property configured. All rule types, except for the custom query rule, are affected. + -Upgrading to 8.6 or higher resolves this issue. If you’d prefer to stay on 8.5, use the <> to remove the `saved_id` field from the non-functioning `query`, `eql`, `machine_learning`, `threat_match`, `threshold`, or `new_terms` rule. +Upgrading to 8.6 or higher resolves this issue. If you’d prefer to stay on 8.5, use the {api-kibana}/operation/operation-updaterule[update rule API] to remove the `saved_id` field from the non-functioning `query`, `eql`, `machine_learning`, `threat_match`, `threshold`, or `new_terms` rule. [discrete] [[bug-fixes-8.5.1]] @@ -69,7 +69,7 @@ Upgrading to 8.6 or higher resolves this issue. If you’d prefer to stay on 8.5 * Version 8.5.0 {elastic-endpoint}s running on Linux systems with many CPUs may become unhealthy. For a workaround refer to https://github.com/elastic/endpoint/issues/34[issue #34]. * The rule details page and **Edit rule settings** page load indefinitely if you edit a rule that has the `saved_id` property configured. All rule types, except for the custom query rule, are affected. + -Upgrading to 8.6 or higher resolves this issue. If you’d prefer to stay on 8.5, use the <> to remove the `saved_id` field from the non-functioning `query`, `eql`, `machine_learning`, `threat_match`, `threshold`, or `new_terms` rule. +Upgrading to 8.6 or higher resolves this issue. If you’d prefer to stay on 8.5, use the {api-kibana}/operation/operation-updaterule[update rule API] to remove the `saved_id` field from the non-functioning `query`, `eql`, `machine_learning`, `threat_match`, `threshold`, or `new_terms` rule. [discrete] [[breaking-changes-8.5.0]] diff --git a/docs/siem-apis.asciidoc b/docs/siem-apis.asciidoc index 624aaa45ea..9838444829 100644 --- a/docs/siem-apis.asciidoc +++ b/docs/siem-apis.asciidoc @@ -1,4 +1,4 @@ -[role="xpack"] +[chapter, role="xpack"] [[security-apis]] = Elastic Security APIs @@ -13,7 +13,7 @@ You can use these APIs to interface with {elastic-sec} features: NOTE: Console supports sending requests to {kib} APIs. Prepend any {kib} API endpoint with `kbn:` and send the request via Console. For example: `GET kbn:/api/index_management/indices` -* <>: Manage detection rules, rule exceptions for individual rules, and alerts +* {api-kibana}/group/endpoint-security-detections-api[Detections API]: Manage detection rules, rule exceptions for individual rules, and alerts * {api-kibana}/group/endpoint-security-exceptions-api[Exceptions API]: Create and manage rule exceptions * {api-kibana}/group/endpoint-security-lists-api[Lists API]: Create source event value lists for use with rule exceptions * {api-kibana}/group/endpoint-security-timeline-api[Timeline API]: Import and export timelines @@ -93,10 +93,5 @@ path component to its URL. {kibana-ref}/development-basepath.html[Considerations for basePath] describes how to work with and disable the random path component. -include::detections/api/det-api-index.asciidoc[] - -include::detections/api/signals-migration-api.asciidoc[] - - NOTE: For the {fleet} APIs, see the {fleet-guide}/fleet-api-docs.html[Fleet API Documentation]. diff --git a/docs/upgrade/upgrade-7.17-8.x.asciidoc b/docs/upgrade/upgrade-7.17-8.x.asciidoc index ef8bc58a0e..5c5d5ffb6d 100644 --- a/docs/upgrade/upgrade-7.17-8.x.asciidoc +++ b/docs/upgrade/upgrade-7.17-8.x.asciidoc @@ -57,7 +57,7 @@ IMPORTANT: We strongly recommend performing the following steps on a non-product . If you haven't already done so, back up your cluster data to a {ref}/snapshots-take-snapshot.html[snapshot]. -. We recommend you <> in case there are issues with the detection engine after the upgrade. +. We recommend you {api-kibana}/operation/operation-exportrules[export all your custom detection rules] in case there are issues with the detection engine after the upgrade. . Upgrade {es}. ** If you're using {ecloud}, we recommend upgrades with no downtime. Refer to {cloud}/ec-upgrade-deployment.html[these instructions]. @@ -119,7 +119,7 @@ Any active rules when you upgrade from 7.17 to 8.0.1 or newer are automatically . Click *Select all _x_ rules*, or individually select the rules you want to re-enable. . Click *Bulk actions -> Enable* to re-enable the rules. -Alternatively, you can use the <> API to re-enable rules. +Alternatively, you can use the {api-kibana}/operation/operation-performrulesbulkaction[bulk rule actions API] to re-enable rules. [float] [[fda-upgrade]] diff --git a/docs/upgrade/upgrade-security.asciidoc b/docs/upgrade/upgrade-security.asciidoc index 8cab48dd6a..a4f9e35d1c 100644 --- a/docs/upgrade/upgrade-security.asciidoc +++ b/docs/upgrade/upgrade-security.asciidoc @@ -86,7 +86,7 @@ IMPORTANT: We strongly recommend performing the following steps on a non-product . If you haven't already done so, back up your cluster data to a {ref}/snapshots-take-snapshot.html[snapshot]. -. We recommend you <> in case there are issues with the detection engine after the upgrade. +. We recommend you {api-kibana}/operation/operation-exportrules[export all your custom detection rules] in case there are issues with the detection engine after the upgrade. . Upgrade {es}. ** If you're using {ecloud}, we recommend upgrades with no downtime. Refer to {cloud}/ec-upgrade-deployment.html[these instructions].