diff --git a/docs/siem/detections/alerts-ui-manage.asciidoc b/docs/siem/detections/alerts-ui-manage.asciidoc new file mode 100644 index 0000000000..a94df74827 --- /dev/null +++ b/docs/siem/detections/alerts-ui-manage.asciidoc @@ -0,0 +1,106 @@ +[[alerts-ui-manage]] +[role="xpack"] +== Managing detection alerts + +The Detections page displays all <>. +From the Alerts table, you can change an alert's status, and start +investigating and analyzing alerts in Timeline. + +TIP: From Timeline, you can <> to track issues and +share information with colleagues. + +To view detection alerts created by a specific rule, you can: + +* Filter for a specific rule in the KQL bar (for example, +`signal.rule.name :"SSH (Secure Shell) from the Internet"`). +* View detection alerts in the *Rule details* page (click +*Manage detection rules* -> rule name in the *All rules* table). + +NOTE: KQL autocomplete for `.siem-signals-*` indices is available on the +*Detections* and *Rule details* pages, and in Timeline when either `All` or +`Detection alerts` is selected. + +TIP: Use the icons in the upper left corner of the Alerts table to customize +displayed columns and row renderers, and view the table in full screen mode. + +[float] +[[detection-alert-status]] +=== Change alert statuses + +You can set an alert's status to indicate whether it needs to be investigated +(`Open`), is under active investigation (`In progress`), or resolved +(`Closed`). By default, the Alerts table displays open alerts. To view alerts +with other statuses, click *In progress* or *Closed*. + +To change alert statuses, either: + +* In the alert's row, click the *more options* icon, and then select the +required status (*Mark in progress*, *Close alert*, or *Open alert*). +* In the Alerts table, select all the alerts you want to change, and then select +*Take action* -> *Close selected*, *Open selected*, or *Mark in progress*. + +[float] +[[signals-to-timelines]] +=== Send alerts to Timeline + +To view an alert in Timeline, click the *Investigate in timeline* icon. + +TIP: When you send an alert generated by a +<> to Timeline, all matching events are +listed in the Timeline, even ones that did not reach the threshold value. For +example, if you have an alert generated by a threshold rule that detects 10 +failed login attempts, when you send that alert to Timeline all failed login +attempts detected by the rule are listed. + +If the rule that generated the alert uses a Timeline template, when you +investigate the alert in Timeline, the dropzone query values defined in the +template are replaced with their corresponding alert values. + +// * `host.name` +// * `host.hostname` +// * `host.domain` +// * `host.id` +// * `host.ip` +// * `client.ip` +// * `destination.ip` +// * `server.ip` +// * `source.ip` +// * `network.community_id` +// * `user.name` +// * `process.name` + +*Example* + +This Timeline template uses the `host.name: "{host.name}"` dropzone filter in +the rule. When alerts generated by the rule are investigated in Timeline, the +`{host.name}` value is replaced with the alert's `host.name` value. If the +alerts's `host.name` value is `Windows-ArsenalFC`, the Timeline dropzone query +is `host.name: "Windows-ArsenalFC"`. + +NOTE: See <> for information on creating Timelines and Timeline +templates. For information on how to add Timeline templates to rules, see +<>. + +[float] +[[add-exception-from-alerts]] +=== Add rule exceptions + +You can add exceptions to the rule that generated the alert directly from the +Alerts table. Exceptions prevent a rule from generating alerts even when its +criteria are met. + +To add an exception, click the actions icon (three dots) and then select +_Add exception_. + +For information about exceptions and how to use them, see +<>. + +[float] +[[alerts-to-resolver]] +=== Visually analyze process relationships. + +For process events received from the Elastic Endpoint agent, you can open a +visual mapping of the relationships and hierarchy connecting related processes. + +To visualize process relationships, click the *Analyze event* icon. For more +information, see Ben xref. diff --git a/docs/siem/detections/api/rules-api-create.asciidoc b/docs/siem/detections/api/rules-api-create.asciidoc index 3ca370e77a..234abae0f3 100644 --- a/docs/siem/detections/api/rules-api-create.asciidoc +++ b/docs/siem/detections/api/rules-api-create.asciidoc @@ -377,7 +377,7 @@ used as an identifier across systems * `{{context.rule.saved_id}}`: Saved search ID * `{{context.rule.severity}}`: Rule severity * `{{context.rule.threat}}`: Rule threat framework -* `{{context.rule.threshold}}`: Rule threshold (threshold rules only) +* `{{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 diff --git a/docs/siem/detections/building-block-rule.asciidoc b/docs/siem/detections/building-block-rule.asciidoc new file mode 100644 index 0000000000..8e464abf64 --- /dev/null +++ b/docs/siem/detections/building-block-rule.asciidoc @@ -0,0 +1,31 @@ +[[building-block-rule]] +[role="xpack"] +== About building-block rules + +Create building-block rules when you do not want to see their generated alerts +in the UI. This is useful when you want: + +* A record of low-risk alerts without producing noise in the Alerts table. +* Rules that execute on the alert indices (`.siem-signals--*`). +You can then use building-block rules to create hidden alerts that act as a +basis for an 'ordinary' rule to generate visible alerts. + +[float] +=== Set up rules that run on alert indices + +To create a rule that searches alert indices, in the *Index patterns* field, +add the index pattern for alert indices: + +[role="screenshot"] +image::images/alert-indices-ui.png[] + +[float] + +=== View building-block alerts in the UI + +. Go to *Security* -> *Detections* +. In the Alert table, select _Additional filters_ -> +_Include building-block alerts_. + +NOTE: On a building-block Rule details page, the rule's alerts are displayed (by +default, _Include building-block alerts_ is selected). diff --git a/docs/siem/detections/detection-engine-intro.asciidoc b/docs/siem/detections/detection-engine-intro.asciidoc index 0ca484212a..8ff4446d1b 100644 --- a/docs/siem/detections/detection-engine-intro.asciidoc +++ b/docs/siem/detections/detection-engine-intro.asciidoc @@ -1,26 +1,60 @@ [[detection-engine-overview]] [role="xpack"] -= Detections (beta) += Detections and Alerts (beta) beta[] -The SIEM Detections feature automatically searches for threats and creates -signals when they are detected. Signal detection rules define the conditions -for creating signals. Additionally, you can use the {kib} -{kibana-ref}/alerting-getting-started.html[Alerting and Actions] -framework to send notifications via other systems, such as email and Slack, -when signals are generated. +Use the Detections feature to create and manage rules, and view the alerts +these rules create. Rules periodically search indices (such as `endgame-*` and +`filebeat-*`) for suspicious source events, and create alerts when a rule's +conditions are met. When an alert is created, its status is `Open`. To help +track investigations, an alert's status can be set as `Open`, `In progress`, or +`Closed` (see <>). -NOTE: To use {kib} Alerting for signal notifications, you need the +[role="screenshot"] +image::images/detections-ui.png[] + +In addition to creating <>, enable +<> to immediately start detecting +suspicious activity. For detailed information on all the prebuilt rules, see the +<> section. Once the prebuilt rules are loaded and +running, <> and <> explain +how to modify the rules to reduce false positives and get a better set of +actionable alerts. You can also use exceptions and value lists when creating or +modifying your own rules. + +There are two special prebuilt rules you need to know about: + +* <>: +Automatically creates an alert from all incoming Elastic Endpoint alerts. To +receive Elastic Endpoint alerts, you must install the Endpoint agent on your +hosts (BEN: see xref). ++ +When this rule is enabled, the following Endpoint events are displayed as +detection alerts: ++ +** Malware Prevention Alert +** Malware Detection Alert ++ +NOTE: When you load the prebuilt rules, this is the only rule that is enabled +by default. + +* <>: Automatically creates an alert for +all incoming third-party system alerts (for example, Suricata alerts). + +If you want to receive notifications via external systems, such as Slack or +email, when alerts are created, use the {kib} +{kibana-ref}/alerting-getting-started.html[Alerting and Actions] framework. + +NOTE: To use {kib} Alerting for detection alert notifications, you need the https://www.elastic.co/subscriptions[appropriate license]. -The {siem-app} comes with <> that search for -suspicious activity on your network and hosts. For information on how to -optimize the prebuilt rules, see <>. You can also -<>. +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 manage detection rules and signals via the UI or the +You can create and manage rules and alerts via the UI or the <>. [IMPORTANT] @@ -29,106 +63,45 @@ To make sure you can access Detections and manage rules, see <>. ============== -[role="screenshot"] -image::detections-ui.png[] - [float] [[det-engine-terminology]] == Terminology -Rules:: -Perform background tasks to detect suspicious activity. There are two types of -rules: - -* Query-based rules search indices for documents that match their queries at -scheduled intervals. When a document matches, a signal is created. -* {ml-cap} rules create a signal when a {ml} job discovers an anomaly score -above a rule's defined threshold. - -Signals:: -Always refer to {siem-soln} produced detections. Signals are never received -from external systems. When a rule's conditions are met, the {siem-app} -writes one or more signals to an Elasticsearch `signals` index. +Actions:: +Sends notifications via other systems when a detection alert is created, such +as email, Slack, PagerDuty, and Webhook. + +[[detection-alert-def]] +Detection alerts:: +{es-sec} produced alerts. Detection alerts are never received from external +systems. When a rule's conditions are met, {es-sec} writes a detection alert to +an Elasticsearch `.signals` index. + [NOTE] ============== -Signal indices are created for each {kib} space. The naming convention is: -`.siem-signals-`. For the default space, the signals index is named -`.siem-signals-default`. +Detection alert indices are created for each {kib} space. The naming convention +is: `.siem-signals-`. For the default space, the alerts index is +named `.siem-signals-default`. ============== -Alerts and events:: -Always refer to data the {siem-app} receives from external systems, such as -Elastic Endpoint and Suricata. +Detection rules:: +Background tasks that run periodically and produce alerts when suspicious +activity is detected. -Actions:: -Used to send notifications via other systems when a signal is created, such as -email, Slack, PagerDuty, and Webhook. - -[float] -== Signals and external alerts +Endpoint exceptions:: +<> added to both rules and Endpoint agents on +hosts. Endpoint exceptions can only be added when: -The Detections page displays all signals and alerts. To view signals created -by a rule, you can: +* Endpoint agents are installed on the hosts. +* The Elastic Endpoint Security rule is activated. -* Filter for a specific rule in the KQL bar (for example, -`signal.rule.name :"SSH (Secure Shell) from the Internet"`). -* View signals in the *Rule details* page (click -*Manage signal detection rules* -> rule name in the *All rules* table). +[[term-exceptions]] +Exceptions:: +Added to rules to prevent specific source event field values from generating +alerts. -NOTE: KQL autocomplete for `.siem-signals-*` indices is available on the -*Detections* and *Rule details* pages, and in Timeline when either `All events` -or `Signal events` is selected. - -To view alerts from external data shippers, click *External alerts*. - -[float] -=== Open and close signals - -You can close signals to indicate they do not need any further investigation. -By default, the All signals table displays open signals. To view closed -signals, click *Closed signals*. - -To open and close signals, either: - -* Click the *Close/Open signal* icon. -* Select the signals you want to open or close and then click -*Close/Open selected*. - -[float] -[[signals-to-timelines]] -=== Investigate signals in Timeline - -To investigate a signal in Timeline, click the *Investigate in timeline* -icon. - -If the rule that generated the signal uses a timeline template, when you -investigate the signal in Timeline, the following dropzone query values are -replaced with their corresponding signal values: - -* `host.name` -* `host.hostname` -* `host.domain` -* `host.id` -* `host.ip` -* `client.ip` -* `destination.ip` -* `server.ip` -* `source.ip` -* `network.community_id` -* `user.name` -* `process.name` - -*Example* - -The timeline template used in the rule has this dropzone query: -`host.name: "Linux-LiverpoolFC"`. When signals generated by the rule are -investigated in Timeline, the `host.name` value is replaced with the signal's -`host.name` value. If the signal's `host.name` value is `Windows-ArsenalFC`, -the timeline dropzone query is `host.name: "Windows-ArsenalFC"`. - -NOTE: For information on how to add timeline templates to rules, see -<>. +External alerts:: +Alerts {es-sec} receives from external systems, such as Suricata. [float] [[detections-permissions]] @@ -150,14 +123,14 @@ of at least 32 characters. For example: For *all* deployments (on-premises and hosted): -* To view signals and detection rules, you must have at least: +* To view detection rules and alerts, you must have at least: ** `read` permissions for the `.siem-signals-` index, where `` is the name of the {kib} space you are using to view Detections (see {ref}/security-privileges.html#privileges-list-indices[Indices privileges]). -** {kib} space `Read` privileges for the `SIEM` feature (see +** {kib} space `Read` privileges for the `Security` feature (see {kibana-ref}/xpack-spaces.html#spaces-control-user-access[Feature access based on user privileges]). * To create and modify detection rules, you must have: -** {kib} space `All` privileges for the `SIEM` feature (see +** {kib} space `All` privileges for the `Security` feature (see {kibana-ref}/xpack-spaces.html#spaces-control-user-access[Feature access based on user privileges]). ** Write permissions for the `.siem-signals-` index, such as `create` `create_doc`, `write`, `index`, and `all` @@ -173,11 +146,11 @@ when you try to open the *Detections* page. *`Let’s set up your detection engine`* If you see this message, a user with these privileges must visit the -*Detections* page before you can view signals and rules: +*Detections* page before you can view detection rules and alerts: * The `manage` cluster privilege (see {ref}/security-privileges.html[{es} security privileges]). * The `create_index` index privilege (see {ref}/security-privileges.html[{es} security privileges]). -* {kib} space `All` privileges for the `SIEM` feature (see +* {kib} space `All` privileges for the `Security` feature (see {kibana-ref}/xpack-spaces.html#spaces-control-user-access[Feature access based on user privileges]). NOTE: For *on-premises* {stack} deployments only, this message may be displayed diff --git a/docs/siem/detections/detections-index.asciidoc b/docs/siem/detections/detections-index.asciidoc index ea5c9ab197..3d494ef56e 100644 --- a/docs/siem/detections/detections-index.asciidoc +++ b/docs/siem/detections/detections-index.asciidoc @@ -2,10 +2,20 @@ include::detection-engine-intro.asciidoc[] include::rules-ui-create.asciidoc[] -include::prebuilt-rules/prebuilt-rules-reference.asciidoc[] +include::rules-ui-manage.asciidoc[] -include::prebuilt-rules/rule-desc-index.asciidoc[] +include::rules-ui-monitor.asciidoc[] + +include::detections-ui-exceptions.asciidoc[] + +include::building-block-rule.asciidoc[] + +include::alerts-ui-manage.asciidoc[] include::prebuilt-rules/tune-rule-signals.asciidoc[] -include::prebuilt-rules/prebuilt-rules-changelog.asciidoc[] \ No newline at end of file +include::prebuilt-rules/prebuilt-rules-changelog.asciidoc[] + +include::prebuilt-rules/prebuilt-rules-reference.asciidoc[] + +include::prebuilt-rules/rule-desc-index.asciidoc[] diff --git a/docs/siem/detections/detections-ui-exceptions.asciidoc b/docs/siem/detections/detections-ui-exceptions.asciidoc new file mode 100644 index 0000000000..7e1ebde02a --- /dev/null +++ b/docs/siem/detections/detections-ui-exceptions.asciidoc @@ -0,0 +1,237 @@ +[[detections-ui-exceptions]] +[role="xpack"] +== Rule exceptions and value lists + +To prevent the creation of unwanted alerts, you can add exceptions to detection +rules. Exceptions contain the source event conditions that determine when +alerts are not generated. They provide a convenient way of allowing trusted +processes and network activity to function without producing unnecessary noise. + +You can add multiple exceptions to one rule. + +IMPORTANT: When you add an exception to the +<> rule, you can select to +add the exception to the Endpoint. When selected, the exception is added to +both the detection rule *and* the Elastic Endpoint agent on your hosts. + +In addition to defining exception queries for source event values, rule +exceptions can be used with value lists. Value lists are lists of items with +the same {es} {ref}/mapping-types.html[data type]. You can create value lists +with these types: + +* `keyword` (many {ecs-ref}/ecs-field-reference.html[ECS fields] are keywords) +* `ip` +* `ip_range` +* `text` + +After creating value lists, you can use `is in list` and `is not in list` +operators to define exceptions. + +[float] +=== Manage value lists + +To create a value list for use with exceptions: + +. Prepare a `txt` or `csv` file with all the values you want to use for +determining exceptions from a single list. If you use a `txt` file, newlines +act as value delimiters. ++ +NOTE: All values in the file must be of the same {es} type. + +. Go to *Security* -> *Detections* -> *Manage detection rules*. +. Click *Upload value lists*. ++ +The *Upload value lists* window opens. + +[role="screenshot"] +image::images/upload-lists-ui.png[] + +. Select the list type (`Keywords`, `IP addresses`, `IP ranges`, or +`Text`) +. Drag or select the `csv` or `txt` file that contains the values. +. Click *Upload list*. + +NOTE: When the name of the file you are uploading already exists, the values in +the new file are appended to the previously uploaded values. + +To view, delete, or export existing lists: + +. Go to *Security* -> *Detections* -> *Manage detection rules*. +. In the *Value lists* pane, click the required action icon. + +[float] +[[detection-rule-exceptions]] +=== Add detection exceptions to a rule + +You can add exceptions to a rule via the Rule details page or the Alerts table. +When you add an exception, you can also close all alerts that meet the +exception's criteria. + +IMPORTANT: When you select to close all alerts that meet the exception's +criteria, all matching alerts are closed, *including* alerts generated by other +rules. + +. To add an exception via the Rule details page: +.. Go to the Rule details page of the rule to which you want to add the +exception (*Security* -> *Detections* -> *Manage detection rules* -> +). +.. Scroll down to the *Trend* histogram and select the *Exceptions* tab. +.. Click *Add new exception*. +. To add an exception via the Alerts table: +.. Go to Detections (*Security* -> *Detections*). +.. Scroll down to the Alerts table and click the more actions icon, and then +select *Add exception*. ++ +The *Add Exception* window opens (via Alerts table). ++ +[role="screenshot"] +image::images/add-exception-ui.png[] + +. Add conditions that define when the exception prevents alerts. You can define +multiple conditions with `OR` and `AND` relationships. In the example above, +the exception prevents the rule from generating alerts when the +`maintenance.exe` process runs on `win-server-1`, `win-server-2`, or +`win-server-3`. ++ +[IMPORTANT] +============ +You can use nested conditions. However, this is only required for +<>. For all other fields, nested conditions +should not be used. +============ ++ +If you have created value lists, you can use them to exclude or include all +values in a list with `is in list` and `is not in list` operators: ++ +[role="screenshot"] +image::images/exceptions-ui-list.png[] + +NOTE: When using a list, all exception statements must use `is in list` and +`is not in list` operators. + +. You can select any of the following: + +* _Close this alert_: Closes the alert when the exception is added. This option +is only available when adding exceptions via the Alerts table. +* _Close all alerts that match this exception, including alerts generated by other rules_: +Closes all alerts that match the exception's conditions. + +. Click *Add Exception*. + +[float] +[[endpoint-rule-exceptions]] +=== Add Elastic Endpoint Security exceptions + +Like detection rule exceptions, you can add Endpoint agent exceptions via both +the Elastic Endpoint Security rule and its generated alerts. Alerts generated +from the Elastic Endpoint Security rule have the following fields: + +* `signal.original_event.module determined:endpoint` +* `signal.original_event.kind:alert` + +Additionally, you can add Endpoint exceptions via rules that are associated +with Elastic endpoint rule exceptions. To associate rules, when creating or +editing a rule select the +<> option. + +[IMPORTANT] +============= +Exceptions added to the Elastic Endpoint Security rule affect all alerts sent +from the Endpoint agent. Be careful not to unintentionally prevent some Endpoint +alerts. +============= + +. To add an Endpoint exception via the Rule details page: +.. Go to the Rule details page and select the Elastic Security Endpoint rule +(*Security* -> *Detections* -> *Manage detection rules* -> +*Elastic Endpoint Security*). +.. Scroll down to the *Trend* histogram and select the *Exceptions* tab. +.. Click *Add Endpoint exception*. +. To add an exception via the Alerts table: +.. Go to Detections (*Security* -> *Detections*). +.. Scroll down to the Alerts table and, from an Elastic Security Endpoint +alert, click the more actions icon, and then select *Add Endpoint exception*. ++ +The *Add Endpoint Exception* window opens (via Alerts table). ++ +[role="screenshot"] +image::images/endpoint-add-exp.png[] + +. If required, modify the conditions. ++ +NOTE: <> describes when nested conditions are required. + +. You can select any of the following: + +* _Close this alert_: Closes the alert when the exception is added. This option +is only available when adding exceptions via the Alerts table. +* _Close all alerts that match this exception, including alerts generated by other rules_: +Closes all alerts that match the exception's conditions. + +. Click *Add Exception*. ++ +An exception is created for both the detection rule *and* the Elastic Endpoint +agent. + +[float] +[[ex-nested-conditions]] +=== Exceptions with nested conditions + +Some Endpoint objects contain nested fields, and the only way to ensure you are +excluding the correct fields is with nested conditions. One example is the +`process.Ext` object: + +[source, json] +-------------------------------------------------- +{ + "ancestry": [], + "code_signature": { + "trusted": true, + "subject_name": "LFC", + "exists": true, + "status": "trusted" + }, + "user": "WDAGUtilityAccount", + "token": { + "elevation": true, + "integrity_level_name": "high", + "domain": "27FB305D-3838-4", + "user": "WDAGUtilityAccount", + "elevation_type": "default", + "sid": "S-1-5-21-2047949552-857980807-821054962-504" + } +} +-------------------------------------------------- + + +TIP: `code_signature.subject_name` refers to the process signature not the +process name. + +[[nested-field-list]] +Only these objects require nested conditions to ensure the exception functions +correctly: + +* `Endpoint.policy.applied.artifacts.global.identifiers` +* `Endpoint.policy.applied.artifacts.user.identifiers` +* `Target.dll.Ext.code_signature` +* `Target.process.Ext.code_signature` +* `Target.process.Ext.token.privileges` +* `Target.process.parent.Ext.code_signature` +* `Target.process.thread.Ext.token.privileges` +* `dll.Ext.code_signature` +* `file.Ext.code_signature` +* `file.Ext.macro.errors` +* `file.Ext.macro.stream` +* `process.Ext.code_signature` +* `process.Ext.token.privileges` +* `process.parent.Ext.code_signature` +* `process.thread.Ext.token.privileges` + + +[discrete] +==== Nested condition example + +Creates an exception that excludes all LFC-signed trusted processes: + +[role="screenshot"] +image::images/nested-exp.png[] \ No newline at end of file diff --git a/docs/siem/detections/images/add-exception-ui.png b/docs/siem/detections/images/add-exception-ui.png new file mode 100644 index 0000000000..0e82de361c Binary files /dev/null and b/docs/siem/detections/images/add-exception-ui.png differ diff --git a/docs/siem/detections/images/alert-indices-ui.png b/docs/siem/detections/images/alert-indices-ui.png new file mode 100644 index 0000000000..ea5a80c48c Binary files /dev/null and b/docs/siem/detections/images/alert-indices-ui.png differ diff --git a/docs/siem/detections/images/detections-ui.png b/docs/siem/detections/images/detections-ui.png index 98ae536b42..f935d5c90e 100644 Binary files a/docs/siem/detections/images/detections-ui.png and b/docs/siem/detections/images/detections-ui.png differ diff --git a/docs/siem/detections/images/endpoint-add-exp.png b/docs/siem/detections/images/endpoint-add-exp.png new file mode 100644 index 0000000000..33e19c32de Binary files /dev/null and b/docs/siem/detections/images/endpoint-add-exp.png differ diff --git a/docs/siem/detections/images/exception-ui-query.png b/docs/siem/detections/images/exception-ui-query.png new file mode 100644 index 0000000000..fa57bf056a Binary files /dev/null and b/docs/siem/detections/images/exception-ui-query.png differ diff --git a/docs/siem/detections/images/exceptions-ui-list.png b/docs/siem/detections/images/exceptions-ui-list.png new file mode 100644 index 0000000000..b7b5dab18c Binary files /dev/null and b/docs/siem/detections/images/exceptions-ui-list.png differ diff --git a/docs/siem/detections/images/nested-exp.png b/docs/siem/detections/images/nested-exp.png new file mode 100644 index 0000000000..7ea05cf28b Binary files /dev/null and b/docs/siem/detections/images/nested-exp.png differ diff --git a/docs/siem/detections/images/risk-source-field-ui.png b/docs/siem/detections/images/risk-source-field-ui.png new file mode 100644 index 0000000000..3d83e00956 Binary files /dev/null and b/docs/siem/detections/images/risk-source-field-ui.png differ diff --git a/docs/siem/detections/images/severity-mapping-ui.png b/docs/siem/detections/images/severity-mapping-ui.png new file mode 100644 index 0000000000..9d65e46de2 Binary files /dev/null and b/docs/siem/detections/images/severity-mapping-ui.png differ diff --git a/docs/siem/detections/images/upload-lists-ui.png b/docs/siem/detections/images/upload-lists-ui.png new file mode 100644 index 0000000000..a68eeab8d4 Binary files /dev/null and b/docs/siem/detections/images/upload-lists-ui.png differ diff --git a/docs/siem/detections/prebuilt-rules/prebuilt-rules-reference.asciidoc b/docs/siem/detections/prebuilt-rules/prebuilt-rules-reference.asciidoc index ed5f19a940..a2e6c826dc 100644 --- a/docs/siem/detections/prebuilt-rules/prebuilt-rules-reference.asciidoc +++ b/docs/siem/detections/prebuilt-rules/prebuilt-rules-reference.asciidoc @@ -156,7 +156,7 @@ and their rule type is `machine_learning`. |<> |Identifies use of the `netsh.exe` to disable or weaken the local firewall. Attackers will use this command line tool to disable the firewall during troubleshooting or to enable network mobility. |[Elastic] [Windows] |7.6.0 |3 <> -|<> |Generates a detection alert each time an Elastic Endpoint alert is received. Enabling this rule allows you to immediately begin investigating your Elastic Endpoint alerts. |[Elastic] [Endpoint] |7.9.0 |1 +|<> |Generates a detection alert each time an Elastic Endpoint alert is received. Enabling this rule allows you to immediately begin investigating your Elastic Endpoint alerts. |[Elastic] [Endpoint] |7.9.0 |1 |<> |Identifies the use of `certutil.exe` to encode or decode data. CertUtil is a native Windows component which is part of Certificate Services. CertUtil is often abused by attackers to encode or decode base64 data for stealthier command and control or exfiltration. |[Elastic] [Windows] |7.6.0 |3 <> diff --git a/docs/siem/detections/prebuilt-rules/rule-details/elastic-endpoint.asciidoc b/docs/siem/detections/prebuilt-rules/rule-details/elastic-endpoint.asciidoc index 0a2cd47a15..c59478d326 100644 --- a/docs/siem/detections/prebuilt-rules/rule-details/elastic-endpoint.asciidoc +++ b/docs/siem/detections/prebuilt-rules/rule-details/elastic-endpoint.asciidoc @@ -1,5 +1,5 @@ [[elastic-endpoint-prebuilt-rule]] -=== Elastic Endpoint +=== Elastic Endpoint Security Generates a detection alert each time an Elastic Endpoint alert is received. Enabling this rule allows you to immediately begin investigating your Elastic diff --git a/docs/siem/detections/rules-ui-create.asciidoc b/docs/siem/detections/rules-ui-create.asciidoc index d627b1d703..86fc5604e7 100644 --- a/docs/siem/detections/rules-ui-create.asciidoc +++ b/docs/siem/detections/rules-ui-create.asciidoc @@ -1,95 +1,71 @@ [[rules-ui-create]] [role="xpack"] -== Managing signal detection rules +== Creating detection rules beta[] -Rules run periodically and search for documents or {ml} job anomaly scores -that meet their criteria. For both prebuilt and custom rules, you can use the -{kib} {kibana-ref}/alerting-getting-started.html[Alerting and Actions] feature -to send notifications when signals are created. Notifications can be sent via -Email, PagerDuty, Slack, and Webhook, and can be configured in the {siem-app} -when you create or edit a rule. +Rules run periodically and search for source events or {ml} job anomaly scores +that meet their criteria. When a rule's criteria are met, a detections alert is +created. -[IMPORTANT] -============== -After you activate a rule, periodically check the rule is running as expected -in the <> on the All rules page. If you see -values in the `Gap` column, you can <>. +You can create these types of rules: -When a rule fails to run, the {siem-app} tries to rerun it at its next -scheduled run time. -============== +* *Custom query*: Query-based rule, which searches the defined indices and creates an alert when a document matches the rule's query. +* *Machine learning*: {ml-cap} rule, which creates an alert when a {ml} job discovers an anomaly above the defined threshold (see <>). ++ +For {ml} rules, the associated {ml} job must be running. If the {ml} job is not +running, the rule will: -On the Rules page, you can: +** Run and create alerts if existing anomaly scores above the defined threshold +are discovered. +** Issue an error stating the {ml} job was not running when the rule executed. +* *Threshold rules*: Searches the defined indices and creates a detections alert +when the number of times the specified field's value meets the threshold during +a single execution. When multiple values 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. -* <> -* <> -* <> -* <> -* <> -* <> -* <> +When creating or modifying rules, you can add exceptions that prevent a rule +from generating an alert even when its criteria are met. This is useful for +reducing noise, such as preventing alerts from trusted processes and internal +IP addresses. <> describes how to add exceptions to a +rule. -[role="screenshot"] -image::all-rules.png[] - -[float] -[[load-prebuilt-rules]] -=== Load prebuilt Elastic rules +For both prebuilt and custom rules, you can use the +{kib} {kibana-ref}/alerting-getting-started.html[Alerting and Actions] feature +to send notifications when alerts are created. Notifications can be sent via +Email, PagerDuty, Slack, and Webhook, and can be configured when you create or +edit a rule. -To load the {siem-app}'s <>, click -*Load Elastic prebuilt rules* on the *Signal detection rules* page (*SIEM* -> -*Detections* -> *Manage signal detection rules*). +Creating a new rule is made up of a number of steps: -If you delete any of the prebuilt rules, a button appears that enables -reloading all the deleted prebuilt rules. +. <> +. <> +. <> +. <> +. <> -[NOTE] +[IMPORTANT] ============== -By default, prebuilt rules are not activated. If you want to modify a prebuilt -rule, you must first duplicate it and then make your changes to the duplicated -rule. <> provides a detailed example of duplicating and modifying a rule. +After you activate a rule, periodically check the rule is running as expected +in the <> on the All rules page. If you see +values in the `Gap` column, you can <>. -All Elastic prebuilt rules are tagged with the word `Elastic`. +When a rule fails to run, the {es-sec-app} tries to rerun it at its next +scheduled run time. ============== -[float] -[[select-all-prebuilt-rules]] -=== Select and duplicate all prebuilt rules - -. Select the *Elastic rules* tab. -. Scroll to the bottom of the page. -. Click the `Rows per page` menu, and then select _200 rows_. -. When the page reloads, select all the rules. -. Click _Bulk actions_ -> _Duplicate selected_. -. Select the *Custom rules* tab. - -You can then modify the duplicated rules and, if required, delete the prebuilt -ones. +[role="screenshot"] +image::all-rules.png[] [float] [[create-rule-ui]] -=== Create a new rule +=== Select rule type and scope -You can create two types of rules: - -* *Custom query*: Query-based rule, which searches the defined indices and creates a signal when a document matches the rule's query. -* *Machine learning*: {ml-cap} rule, which creates a signal when a {ml} job discovers an anomaly above the defined threshold (see <>). -+ -For {ml} rules, the associated {ml} job must be running. If the {ml} job is not -running, the rule will: - -** Run and create signals if existing anomaly scores above the defined threshold -are discovered. -** Issue an error stating the {ml} job was not running when the rule executed. - -IMPORTANT: To create or edit {ml} rules, you must have the -https://www.elastic.co/subscriptions[appropriate license] or use a -{ess-trial}[cloud deployment]. Additionally, you must have the -{ref}/built-in-roles.html[`machine_learning_admin`] user role. - -. Go to *SIEM* -> *Detections* -> *Manage signal detection rules*. +. Go to *Security* -> *Detections* -> *Manage detection rules*. . Click *Create new rule*. + The *Create new rule* page is displayed. @@ -99,16 +75,22 @@ image::images/create-new-rule.png[] * To create a rule based on a {ml} anomaly threshold, select _Machine Learning_ and then: .. The required {ml} job. -.. The anomaly score threshold above which signals are created. +.. The anomaly score threshold above which alerts are created. + -IMPORTANT: The selected {ml} job must be running for the rule to function -correctly. +[IMPORTANT] +============== +To create or edit {ml} rules, you must have the +https://www.elastic.co/subscriptions[appropriate license] or use a +{ess-trial}[cloud deployment]. Additionally, you must have the +{ref}/built-in-roles.html[`machine_learning_admin`] user role, and the selected +{ml} job must be running for the rule to function correctly. +============== * To create a rule based on a KQL or Lucene query, select _Custom query_ and then: -.. Define which {es} indices the rule analyzes for signals. +.. Define which {es} indices the rule searches for alerts. .. Use the filter and query fields to create the criteria used for detecting -signals. +alerts. + NOTE: You can use {kib} saved queries (save icon) and queries from saved timelines (`Import query from saved timeline`) as rule conditions. + @@ -125,58 +107,144 @@ the `delete` and `shadow` arguments, which are used to delete a volume's shadow copies. + [role="screenshot"] -image::rule-query-example.png[] +image::images/rule-query-example.png[] + TIP: This example is based on the <> prebuilt rule. -. Select the timeline template used when you investigate a signal created by +* To create a rule based on a source event field threshold, select _Threshold_ +and then: +.. Define which {es} indices the rule analyzes for alerts. +.. Use the filter and query fields to create the criteria used for detecting +alerts. +.. Use the _Field_ and _Threshold_ fields to determine which source event field +is used as a threshold and the threshold's value. ++ +For example, if the _Field_ is `source.ip` and its _Threshold_ is `10`, an +alert is generated for every source IP address that appears in at least 10 of +the rule's search results. ++ +You can also leave the _Field_ undefined. The rule then creates an alert when +the number of search results is equal to or greater than the _Threshold_ value. ++ +If you want an alert for 10 or more failed login attempts to a specific host +per rule execution: + +** _Custom query_: `host.name : liv-win-19 and event.category : "authentication" and event.outcome : "failure"` +** _Field_: Leave blank +** _Threshold_: `10` + +. Select the Timeline template used when you investigate an alert created by the rule in Timeline (optional). + -TIP: Before you create rules, create and save relevant -<> so they can be selected here. When signals generated -by the rule are investigated in Timeline, -<> are replaced with their -corresponding signal field values. +TIP: Before you create rules, create <> so +they can be selected here. When alerts generated by the rule are investigated +in Timeline, Timeline query values are replaced with their corresponding alert +field values. . Click *Continue*. + The *About rule* pane is displayed. [role="screenshot"] image::images/about-rule-pane.png[] + +. Continue with <>. + +[float] +[[rule-ui-basic-params]] +=== Configure basic rule settings + . Fill in the following fields: .. _Name_: The rule's name. .. _Description_: A description of what the rule does. -.. _Severity_: Select the severity levels of signals created by the rule: -* `Low`: Signals that are of interest but generally not considered to be +.. _Default severity_: Select the severity level of alerts created by the rule: +* `Low`: Alerts that are of interest but generally not considered to be security incidents. Sometimes, a combination of low severity events can indicate suspicious activity. -* `Medium`: Signals that require investigation. -* `High`: Signals that require an immediate investigation. -* `Critical`: Signals that indicate it is highly likely a security incident has - occurred. -.. _Risk score_: A numerical value between 0 and 100 that correlates with the _Severity_ level. General guidelines are: +* `Medium`: Alerts that require investigation. +* `High`: Alerts that require an immediate investigation. +* `Critical`: Alerts that indicate it is highly likely a security incident has +occurred. +.. _Severity override_ (optional): Select to use source event values to +override the _Default severity_ in generated alerts. When selected, a UI +component is displayed where you can map the source event field values to +severity levels. For example, if you want to map severity levels to `host.name` +values: ++ +[role="screenshot"] +image::images/severity-mapping-ui.png[] +.. _Default risk score_: A numerical value between 0 and 100 that correlates +with the _Severity_ level. General guidelines are: * `0` - `21` represents low severity. * `22` - `47` represents medium severity. * `48` - `73` represents high severity. * `74` - `100` represents critical severity. -.. For additional options, click *Advanced settings* and fill in any of -these fields: -... _Reference URLs_ (optional): References to information that is relevant to -the rule. For example, links to relevant background information. -... _False positives_ (optional): List of common scenarios that may produce -false-positive signals. -... _MITRE ATT&CK^TM^_ (optional): Relevant MITRE framework tactics and techniques. -... _Tags_ (optional): Words and phrases used to categorize, filter, and search +.. _Risk score override_ (optional): Select to use a source event value to +override the _Default risk score_ in generated alerts. When selected, a UI +component is displayed where you can select the source field used for the risk +score. For example, if you want to use the source event's risk score in +alerts: ++ +[role="screenshot"] +image::images/risk-source-field-ui.png[] + +. Continue with *one* of the following: + +* <> +* <> + +[float] +[[rule-ui-advanced-params]] +=== Configure advanced rule settings (optional) + + +. Click *Advanced settings* and fill in these fields: +.. _Reference URLs_ (optional): References to information that is relevant to +the rule. For example, links to background information. +.. _False positives_ (optional): List of common scenarios that may produce +false-positive alerts. +.. _MITRE ATT&CK^TM^_ (optional): Relevant MITRE framework tactics and techniques. +.. _Tags_ (optional): Words and phrases used to categorize, filter, and search the rule. -... _Investigation guide_ (optional): Information for analysts investigating -signals created by the rule. +.. _Investigation guide_ (optional): Information for analysts investigating +alerts created by the rule. +.. _Author_ (optional): The rule's authors. +.. _License_ (optional): The rule's license. +.. _Elastic endpoint exceptions_ (optional): Adds all Elastic Endpoint Security +rule exceptions to this rule (see <>). ++ +NOTE: If you select this option, you can add +<> on the Rule details page. +Additionally, all future exceptions added to the Elastic Endpoint Security rule +also affect this rule. + +.. _Building block_ (optional): Select to create a building-block rule. By +default, alerts generated from a building-block rule are not displayed in the +UI. See <> for more information. +.. _Rule name override_ (optional): Select a source event field to use as the +rule name in the UI (Alerts table). This is useful for exposing, at a glance, +more information about an alert. For example, if the rule generates alerts from +Suricata, selecting `event.action` lets you see what action (Suricata category) +caused the event directly in the Alerts table. +.. _Timestamp override_ (optional): Select a source event timestamp field. When selected, the rule's query uses the selected field, instead of the default `@timestamp` field, to search for alerts. This can help reduce missing alerts due to network or server outages. Specifically, if your ingest pipeline adds a timestamp when events are sent to {es}, this avoids missing alerts due to ingestion delays. ++ +TIP: These Filebeat modules have an `event.ingested` timestamp field that can +be used instead of the default `@timestamp` field: +{filebeat-ref}/filebeat-module-microsoft.html[Microsoft] and +{filebeat-ref}/filebeat-module-gsuite.html[GSuite]. + . Click *Continue*. + -[[rule-schedule]] -The *Schedule rule* pane is displayed. [role="screenshot"] image::images/schedule-rule.png[] +The *Schedule rule* pane is displayed. + +. Continue with <>. + +[float] +[[rule-schedule]] +=== Set the rule's schedule + . Select how often the rule runs. . Optionally, add `Additional look-back time` to the rule. When defined, the rule searches indices with the additional time. @@ -188,10 +256,10 @@ documents added to indices during the last 6 minutes. [IMPORTANT] ============== It is recommended to set the `Additional look-back time` to at -least 1 minute. This ensures there are no missing signals when a rule does not +least 1 minute. This ensures there are no missing alerts when a rule does not run exactly at its scheduled time. -The {siem-app} performs deduplication. Duplicate signals discovered during the +The {siem-app} performs deduplication. Duplicate alerts discovered during the `Additional look-back time` are *not* created. ============== . Click *Continue*. @@ -200,48 +268,54 @@ The {siem-app} performs deduplication. Duplicate signals discovered during the The *Rule actions* pane is displayed. [role="screenshot"] image::images/rule-actions.png[] -. Optionally, use {kib} Actions to set up notifications sent via other systems -when new signals are detected. -+ -NOTE: To use {kib} Actions for signal notifications, you need the + +. Do *one* of the following: + +* Continue with <>. +* Create the rule (with or without activation). + +[float] +[[rule-notifications]] +=== Set up alert notifications (optional) + +Use {kib} Actions to set up notifications sent via other systems when alerts +are generated. + +NOTE: To use {kib} Actions for alert notifications, you need the https://www.elastic.co/subscriptions[appropriate license]. -.. Set how often notifications are sent: +. Set when to send notifications: -* _On each rule execution_: Sends a notification every time new signals are -detected. +* _On each rule execution_: Sends a notification every time new alerts are +generated. * _Hourly_: Sends a notification every hour. * _Daily_: Sends a notification every day. * _Weekly_: Sends a notification every week. + -NOTE: Notifications are sent only when new signals are detected. - +NOTE: Notifications are sent only when new alerts are generated. + The available action types are displayed. [role="screenshot"] image::images/available-action-types.png[] -+ -.. Select the required action type, which determines how notifications are sent (Email, PagerDuty, Slack, Webhook). +. Select the required action type, which determines how notifications are sent (Email, PagerDuty, Slack, Webhook). + NOTE: Each action type requires a connector. Connectors store the information required to send the notification from the external system. You can configure connectors while creating the rule or on the {kib} Alerts and Actions page (*Management* -> *Alerts and Actions* -> *Connectors*). For more information, see {kibana-ref}/action-types.html[Action and connector types]. - + The selected action type fields are displayed (Slack example). [role="screenshot"] image::images/selected-action-type.png[] -+ .. Fill in the fields for the selected action types. For all action types, click the icon above the `Message` field to add -<> for rule and signal details to the +<> for rule and alert details to the notifications. -. Save the rule with or without activation. +. Create the rule with or without activation. + NOTE: When you activate a rule, it is queued and its schedule is determined by its initial run time. For example, if you activate a rule that runs every 5 @@ -249,27 +323,27 @@ minutes at 14:03 but it does not run until 14:04, it will run again at 14:09. [float] [[rule-action-variables]] -==== Notification placeholders +==== Alert notification placeholders -These placeholders can be added to <> fields: +These placeholders can be added to <> fields: -* `{{state.signals_count}}`: Number of signals detected -* `{{{context.results_link}}}`: URL to the signals in {kib} +* `{{state.signals_count}}`: Number of alerts detected +* `{{{context.results_link}}}`: URL to the alerts in {kib} * `{{context.rule.anomaly_threshold}}`: Anomaly threshold score above which -signals are generated ({ml} rules only) +alerts are generated ({ml} rules only) * `{{context.rule.description}}`: Rule description * `{{context.rule.false_positives}}`: Rule false positives -* `{{context.rule.filters}}`: Rule filters (query-based rules only) +* `{{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-based rules only) -* `{{context.rule.language}}`: Rule query language (query-based rules only) +* `{{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 signals per rule +* `{{context.rule.max_signals}}`: Maximum allowed number of alerts per rule execution * `{{context.rule.name}}`: Rule name -* `{{context.rule.output_index}}`: Index to which signals are written -* `{{context.rule.query}}`: Rule query (query-based rules only) +* `{{context.rule.output_index}}`: Index to which alerts are written +* `{{context.rule.query}}`: Rule query (query rules only) * `{{context.rule.references}}`: Rule references * `{{context.rule.risk_score}}`: Rule risk score * `{{context.rule.rule_id}}`: Generated or user-defined rule ID that can be @@ -277,71 +351,8 @@ used as an identifier across systems * `{{context.rule.saved_id}}`: Saved search ID * `{{context.rule.severity}}`: Rule severity * `{{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 - -[float] -[[manage-rules-ui]] -=== Modify existing rules - -You can clone, edit, activate, deactivate, and delete rules: - -. Go to *SIEM* -> *Detections* -> *Manage signal detection rules*. -. Do one of the following: -* Click the actions icon (three dots) and then select the required action. -* In the *Rule* column, select all the rules you want to modify, and then the -required action from the `Bulk actions` menu. -. To activate or deactivate a rule, click the Activate toggle button. - -NOTE: For prebuilt rules, you can only activate, deactivate, delete, and edit -<>. - -[float] -[[monitor-rule-exe]] -=== Monitor all rule executions - -To view a summary of all rule executions, such as failures and last execution -times, click the Monitoring tab in the *All rules* table (*SIEM* -> -*Detections* -> *Manage signal detection rules*). - -For detailed information on a rule, its produced signals, and errors, click on -a rule name in the *All rules* table. - -[float] -[[import-export-rules-ui]] -=== Import and export rules - -. Go to *SIEM* -> *Detections* -> *Manage signal detection rules*. -. To import rules: -.. Click *Import rule*. -.. Drag-and-drop files containing the signal detection rules. -+ -NOTE: Imported rules must be in an `ndjson` file. - -. To export rules: -.. In the *All rules* table, select the rules you want to export. -.. Select *Bulk actions* -> *Export selected*. -+ -NOTE: You cannot export prebuilt rules. - -[float] -[[troubleshoot-signals]] -=== Troubleshoot missing signals - -When a rule fails to run close to its scheduled time, some signals may be -missing. There are a number of steps you can perform to try and resolve this -issue. - -If you see `Gaps` in the All rules table or on the Rule details page -for a small number of rules, you can increase those rules' -`Additional look-back time` (*Signal detection rules* page -> the rule's -actions icon -> *Edit rule settings* -> *Schedule* -> _Additional look-back time_). - -If you see gaps for a lot of rules: - -* If you restarted {kib} when many rules were activated, try deactivating them -and then reactivating them in small batches at staggered intervals. This -ensures {kib} does not attempt to run all the rules at the same time. -* Consider adding another {kib} instance to your environment. \ No newline at end of file diff --git a/docs/siem/detections/rules-ui-manage.asciidoc b/docs/siem/detections/rules-ui-manage.asciidoc new file mode 100644 index 0000000000..ffc0fddc49 --- /dev/null +++ b/docs/siem/detections/rules-ui-manage.asciidoc @@ -0,0 +1,83 @@ +[[rules-ui-management]] +[role="xpack"] +== Managing detection rules + +On the Detection rules page, you can: + +* <> +* <> +* <> +* <> + +[float] +[[load-prebuilt-rules]] +=== Load and activate prebuilt Elastic rules + +To load the {es-sec-app}'s <>, click +*Load Elastic prebuilt rules* on the *Detection rules* page (*Security* -> +*Detections* -> *Manage detection rules* -> +*Load Elastic prebuilt rules and timeline templates*). + +You can then activate whichever rules you want. If you delete any of the +prebuilt rules, a button appears that enables reloading all the deleted +ones. + +[NOTE] +============== +Apart from the Elastic Endpoint rule, prebuilt rules are not activated by +default. If you want to modify a prebuilt rule, you must first duplicate it +and then make your changes to the duplicated rule. <> +provides a detailed example of duplicating and modifying a rule. + +All Elastic prebuilt rules are tagged with the word `Elastic`. +============== + +[float] +[[select-all-prebuilt-rules]] +=== Select and duplicate all prebuilt rules + +In the All rules table: + +. Select the *Elastic rules* tab. +. Scroll to the bottom of the page. +. Click the `Rows per page` menu, and then select _300 rows_. +. When the page reloads, select all the rules. +. Click _Bulk actions_ -> _Duplicate selected_. +. Select the *Custom rules* tab. + +You can then modify the duplicated rules and, if required, delete the prebuilt +ones. + +[float] +[[manage-rules-ui]] +=== Modify existing rules + +You can clone, edit, activate, deactivate, and delete rules: + +. Go to *Security* -> *Detections* -> *Manage detection rules*. +. Do one of the following: +* Click the actions icon (three dots) and then select the required action. +* In the *Rule* column, select all the rules you want to modify, and then the +required action from the `Bulk actions` menu. +. To activate or deactivate a rule, click the Activate toggle button. + +NOTE: For prebuilt rules, you can only activate, deactivate, delete, and edit +<>. + +[float] +[[import-export-rules-ui]] +=== Import and export rules + +. Go to *Security* -> *Detections* -> *Manage detection rules*. +. To import rules: +.. Click *Import rule*. +.. Drag-and-drop files containing the detection rules. ++ +NOTE: Imported rules must be in an `ndjson` file. + +. To export rules: +.. In the *All rules* table, select the rules you want to export. +.. Select *Bulk actions* -> *Export selected*. ++ +NOTE: You cannot export prebuilt rules. + diff --git a/docs/siem/detections/rules-ui-monitor.asciidoc b/docs/siem/detections/rules-ui-monitor.asciidoc new file mode 100644 index 0000000000..4f29b30dc7 --- /dev/null +++ b/docs/siem/detections/rules-ui-monitor.asciidoc @@ -0,0 +1,30 @@ +[[alerts-ui-monitor]] +[role="xpack"] +== Monitoring and troubleshooting rule executions + +To view a summary of all rule executions, such as failures and last execution +times, click the Monitoring tab in the *All rules* table (*Security* -> +*Detections* -> *Manage detection rules*). + +For detailed information on a rule, its generated alerts and errors, click on +a rule name in the *All rules* table. + +[float] +[[troubleshoot-signals]] +=== Troubleshoot missing alerts + +When a rule fails to run close to its scheduled time, some alerts may be +missing. There are a number of steps you can perform to try and resolve this +issue. + +If you see `Gaps` in the All rules table or on the Rule details page +for a small number of rules, you can increase those rules' +`Additional look-back time` (*Detection rules* page -> the rule's +actions icon -> *Edit rule settings* -> *Schedule* -> _Additional look-back time_). + +If you see gaps for a lot of rules: + +* If you restarted {kib} when many rules were activated, try deactivating them +and then reactivating them in small batches at staggered intervals. This +ensures {kib} does not attempt to run all the rules at the same time. +* Consider adding another {kib} instance to your environment. \ No newline at end of file diff --git a/docs/siem/images/detections-ui.png b/docs/siem/images/detections-ui.png index 98ae536b42..f935d5c90e 100644 Binary files a/docs/siem/images/detections-ui.png and b/docs/siem/images/detections-ui.png differ diff --git a/docs/siem/siem-ui.asciidoc b/docs/siem/siem-ui.asciidoc index a63ed8ff15..050c9ae5f6 100644 --- a/docs/siem/siem-ui.asciidoc +++ b/docs/siem/siem-ui.asciidoc @@ -70,7 +70,7 @@ The most recent timelines you've accessed appear in **Recent Timelines**. The signals histogram displays a count of all the Signals detected by the {siem-app} within a set time frame. In the **Stack by** dropdown, select specific parameters for which to visualize the signal count. For example, stack by `user.name` for the graph to visualize the number of signals attributed to a specific user. -To create signal detection rules, see <>. +To create signal detection rules, see <>. [discrete] [[external-alerts-count]]