diff --git a/solutions/images/security-gaps-table.png b/solutions/images/security-gaps-table.png new file mode 100644 index 0000000000..7caf0334bd Binary files /dev/null and b/solutions/images/security-gaps-table.png differ diff --git a/solutions/images/security-manual-rule-run-table.png b/solutions/images/security-manual-rule-run-table.png index ddacb233e2..12a8291632 100644 Binary files a/solutions/images/security-manual-rule-run-table.png and b/solutions/images/security-manual-rule-run-table.png differ diff --git a/solutions/images/security-monitor-table.png b/solutions/images/security-monitor-table.png index 05cb4c3aa2..081d748696 100644 Binary files a/solutions/images/security-monitor-table.png and b/solutions/images/security-monitor-table.png differ diff --git a/solutions/security/detect-and-alert/manage-detection-rules.md b/solutions/security/detect-and-alert/manage-detection-rules.md index ed904f738a..6a4e4a13e9 100644 --- a/solutions/security/detect-and-alert/manage-detection-rules.md +++ b/solutions/security/detect-and-alert/manage-detection-rules.md @@ -66,7 +66,7 @@ For {{ml}} rules, an indicator icon (![Error icon from rules table](/solutions/i ::::{admonition} Requirements * You can edit custom rules and bulk-modify them with any [{{stack}} subscription](https://www.elastic.co/pricing) or [{{serverless-short}} project tier](../../../deploy-manage/deploy/elastic-cloud/project-settings.md). * You can edit [rule notifications](/solutions/security/detect-and-alert/create-detection-rule.md#rule-notifications) (notifications and response actions) for prebuilt rules with any {{stack}} subscription or {{serverless-short}} project tier. -* You must have an [Enterprise subscription](https://www.elastic.co/pricing) {{stack}} or a [Complete project tier](../../../deploy-manage/deploy/elastic-cloud/project-settings.md) subscription on {{serverless-short}} to edit all prebuilt rule settings (except for the **Author** and **License** fields) and bulk-modify them. +* You must have an [Enterprise subscription](https://www.elastic.co/pricing) {{stack}} or a [Complete project tier](../../../deploy-manage/deploy/elastic-cloud/project-settings.md) subscription on {{serverless-short}} to edit all prebuilt rule settings (except for the **Author** and **License** fields) and bulk-modify them. :::: @@ -130,12 +130,7 @@ When duplicating a rule with exceptions, you can choose to duplicate the rule an ## Run rules manually [manually-run-rules] -::::{warning} -This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features. -:::: - - -Manually run enabled rules for a specified period of time for testing purposes or additional rule coverage. +Manually run enabled rules for a specified period of time to deliberately test them, provide additional rule coverage, or fill gaps in rule executions. ::::{important} Before manually running rules, make sure you properly understand and plan for rule dependencies. Incorrect scheduling can lead to inconsistent rule results. @@ -151,19 +146,16 @@ Before manually running rules, make sure you properly understand and plan for ru 3. Specify when the manual run starts and ends. The default selection is the current day starting three hours in the past. The rule will search for events during the selected time range. 4. Click **Run** to manually run the rule. - ::::{note} - Manual runs can produce multiple rule executions. This is determined by the manual run’s time range and the rule’s execution schedule. - :::: - +The rule will run over the time range that you selected. Note that all [rule actions](/solutions/security/detect-and-alert/create-detection-rule.md#rule-notifications) will also be activated, except for **Summary of alerts** actions that run at a custom frequency. -The manual run’s details are shown in the [Manual runs](/solutions/security/detect-and-alert/monitor-rule-executions.md#manual-runs-table) table on the **Execution results** tab. Changes you make to the manual run or rule settings will display in the Manual runs table after the current run completes. +Go to the [Manual runs table](/solutions/security/detect-and-alert/monitor-rule-executions.md#manual-runs-table) on the **Execution results** tab to track the manual rule executions. If you manually ran the rule over a gap, you can also monitor the gap fill's progress from the [Gaps table](/solutions/security/detect-and-alert/monitor-rule-executions.md#gaps-table). ::::{note} Be mindful of the following: -* Rule actions are not activated during manual runs. -* Except for threshold rules, duplicate alerts aren’t created if you manually run a rule during a time range that was already covered by a scheduled run. -* Manual runs are executed with low priority and limited concurrency, meaning they might take longer to complete. This can be especially apparent for rules requiring multiple executions. +* Any changes that you make to the manual run or rule settings will display in the Manual runs table after the current run completes. +* Except for threshold rules, duplicate alerts aren't created if you manually run a rule during a time range that was already covered by a scheduled run. +* Manually running a custom query rule with suppression may incorrectly inflate the number of suppressed alerts. :::: @@ -188,7 +180,7 @@ You can snooze rule notifications from the **Installed Rules** tab, the rule det ::::{admonition} Requirements * You can export and import custom rules and prebuilt rules (modified and unmodified) with any [{{stack}} subscription](https://www.elastic.co/pricing) or [{{serverless-short}} project tier](../../../deploy-manage/deploy/elastic-cloud/project-settings.md). -* At minimum, your role needs `Read` privileges for the **Action and Connectors** feature to import rules with actions. To overwrite or add new connectors, you need `All` privileges. Refer to [Enable and access detections](/solutions/security/detect-and-alert/detections-requirements.md#enable-detections-ui) to learn more about the required privileges for managing rules. +* At minimum, your role needs `Read` privileges for the **Action and Connectors** feature to import rules with actions. To overwrite or add new connectors, you need `All` privileges. Refer to [Enable and access detections](/solutions/security/detect-and-alert/detections-requirements.md#enable-detections-ui) to learn more about the required privileges for managing rules. :::: You can export custom detection rules to an `.ndjson` file, which you can then import into another {{elastic-sec}} environment. diff --git a/solutions/security/detect-and-alert/monitor-rule-executions.md b/solutions/security/detect-and-alert/monitor-rule-executions.md index 07f0cc4052..424e80f63d 100644 --- a/solutions/security/detect-and-alert/monitor-rule-executions.md +++ b/solutions/security/detect-and-alert/monitor-rule-executions.md @@ -21,7 +21,7 @@ Refer to the [Troubleshoot missing alerts](../../../troubleshoot/security/detect ## Rule Monitoring tab [rule-monitoring-tab] -To view a summary of all rule executions, including the most recent failures and execution times, select the **Rule Monitoring** tab on the **Rules** page. To access the tab, find **Detection rules (SIEM)** in the navigation menu or look for “Detection rules (SIEM)” using the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), then go to the **Rule Monitoring** tab. +To view a summary of all rule executions (including the most recent failures, execution times, and gaps in rule executions), select the **Rule Monitoring** tab on the **Rules** page. To access the tab, find **Detection rules (SIEM)** in the navigation menu or look for “Detection rules (SIEM)” using the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), then go to the **Rule Monitoring** tab. :::{image} /solutions/images/security-monitor-table.png :alt: monitor table @@ -37,19 +37,28 @@ To sort the rules list, click any column header. To sort in descending order, cl For detailed information on a rule, the alerts it generated, and associated errors, click on its name in the table. This also allows you to perform the same actions that are available on the [**Installed Rules** tab](manage-detection-rules.md), such as modifying or deleting rules, activating or deactivating rules, exporting or importing rules, and duplicating prebuilt rules. +For information about rule execution gaps (which are periods of time when a rule didn't run), use the panel above the table. The time filter on the left allows you to select a time range for viewing gap data. The **Total rules with gaps:** field tells you how many rules have unfilled or partially filled gaps within the selected time range. The **Only rules with gaps** filter on the right lets you only display rules with unfilled or partially filled gaps. -## Execution results [rule-execution-logs] +Within the table, the **Last Gap (if any)** column conveys how long the most recent gap for a rule lasted. The **Unfilled gaps duration** column shows whether a rule still has gaps and provides a total sum of the remaining unfilled or partially filled gaps. The total sum can change based on the time range that you select in the panel above the table. If a rule has no gaps, the columns display a dash (`––`). -Each detection rule execution is logged, including the execution type, the execution’s success or failure, any warning or error messages, how long it took to search for data, create alerts, and complete. This can help you troubleshoot a particular rule if it isn’t behaving as expected (for example, if it isn’t creating alerts or takes a long time to run). +::::{tip} +For a detailed view of a rule's gaps, go to the **Execution results** tab and check the [Gaps table](/solutions/security/detect-and-alert/monitor-rule-executions.md#gaps-table). +:::: + +## Execution results tab [rule-execution-logs] + +From the **Execution results** tab, you can access the rule’s execution log, monitor and address gaps in a rule's execution schedule, and check manual runs for the rule. To find the tab, click the rule's name to open its details, then scroll down. -To access a rule’s execution log, click the rule’s name to open its details, then scroll down and select the **Execution results** tab. Within the Execution log table, you can click the arrow at the end of a row to expand a long warning or error message. +### Execution log table [execution-log-table] + +Each detection rule execution is logged, including the execution type, the execution’s success or failure, any warning or error messages, how long it took to search for data, create alerts, and complete. This can help you troubleshoot a particular rule if it isn’t behaving as expected (for example, if it isn’t creating alerts or takes a long time to run). :::{image} /solutions/images/security-rule-execution-logs.png :alt: Execution log table on the rule execution results tab :screenshot: ::: -You can hover over each column heading to display a tooltip about that column’s data. Click a column heading to sort the table by that column. +You can hover over each column heading to display a tooltip about that column’s data. Click a column heading to sort the table by that column. Within the Execution log table, you can click the arrow at the end of a row to expand a long warning or error message. Use these controls to filter what’s included in the logs table: @@ -70,32 +79,67 @@ Use these controls to filter what’s included in the logs table: * The **Actions** column allows you to show alerts generated from a given rule execution. Click the filter icon (![Filter icon](/solutions/images/security-filter-icon.png "title =20x20")) to create a global search filter based on the rule execution’s ID value. This replaces any previously applied filters, changes the global date and time range to 24 hours before and after the rule execution, and displays a confirmation notification. You can revert this action by clicking **Restore previous filters** in the notification. -### Manual runs table [manual-runs-table] +### Gaps table [gaps-table] ::::{warning} This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features. :::: +Gaps in rule executions are periods of time where a rule didn’t run. They can be caused by various disruptions, including system updates, rule failures, or simply turning off a rule. Addressing gaps is essential for maintaining consistent coverage and avoiding missed alerts. -Each manual run can produce multiple rule executions, depending on the time range of the run and the rule’s execution schedule. These details are shown in the Manual runs table. - -To access the table, navigate to the detection rules page, click the rule’s name to open its details, then scroll down and select the **Execution results** tab. Scroll down again to find the Manual runs table. +::::{tip} +Refer to the [Troubleshoot gaps](../../../troubleshoot/security/detection-rules.md#troubleshoot-gaps) section for strategies for avoiding gaps. +:::: -To stop an active run, go to the appropriate row and click **Stop run** in the **Actions** column. Completed rule executions for each manual run are logged in the Execution log table. +Use the information in the Gaps table to assess the scope and severity of rule execution gaps. To control what's shown in the table, you can filter the table by gap status, select a time range for viewing gap data, and sort multiple columns. -:::{image} /solutions/images/security-manual-rule-run-table.png -:alt: Manual rule runs table on the rule execution results tab +:::{image} /solutions/images/security-gaps-table.png +:alt: Gaps table on the rule execution results tab :screenshot: ::: -The Manual runs table displays important details such as: +The Gaps table has the following columns: + +* **Status**: The current state of the gap. It can be `Filled`, `Partially filled`, or `Unfilled`. +* **Detected at**: The date and time the gap was first discovered. +* **Manual fill tasks**: The status of the manual run that’s filling the gap. For more details about the manual run, refer to its entry in the [Manual runs table](/solutions/security/detect-and-alert/monitor-rule-executions.md#manual-runs-table). +* **Event time covered**: How much progress the manual run has made filling the gap. + + ::::{note} + If you stop a manual run that's hasn't finished filling a gap, the gap’s status will be set to `Partially filled`. To fill the remaining gap, you can select the **Fill remaining gap** action or [manually run](/solutions/security/detect-and-alert/manage-detection-rules.md#manually-run-rules) the rule over the gap's time frame. + :::: + +* **Range**: When the gap started and ended. +* **Total gap duration**: How long the gap lasted. +* **Actions**: The actions that you can take for the gap. They can be **Fill gap** (starts a manual run to fill the gap) or **Fill remaining gap** (starts a manual run that fills the leftover portion of the gap). + + +### Manual runs table [manual-runs-table] + +You can [manually run](/solutions/security/detect-and-alert/manage-detection-rules.md#manually-run-rules) enabled rules for a specified period of time to deliberately test them, provide additional rule coverage, or fill gaps in rule executions. Each manual run can produce multiple rule executions, depending on the time range of the run and the rule's execution schedule. + +::::{note} +Manual runs are executed with low priority and limited concurrency, meaning they might take longer to complete. This can be especially apparent for rules requiring multiple executions. +:::: + +The Manual runs table tracks manual rule executions and provides important details such as: + +* The total number of rule executions that the manual run will produce and how many are failing, pending, running, and completed. +* When the manual run started and the time range that it will cover. + + ::::{note} + To stop an active run, go to the appropriate row in the table and click **Stop run** in the **Actions** column. Completed rule executions for each manual run are logged in the Execution log table. + :::: * The status of each manual run: - * **Pending**: The rule is not yet running. - * **Running**: The rule is executing during the time range you specified. Some rules, such as indicator match rules, can take longer to run. - * **Error**: The rule’s configuration is preventing it from running correctly. For example, the rule’s conditions cannot be validated. + * `Pending`: The rule is not yet running. + * `Running`: The rule is executing during the time range you specified. Some rule types, such as indicator match rules, can take longer to run. + * `Error`: The rule's configuration is preventing it from running correctly. For example, the rule's conditions cannot be validated. + +:::{image} /solutions/images/security-manual-rule-run-table.png +:alt: Manual rule runs table on the rule execution results tab +:screenshot: +::: + -* When a manual run started and the time in which it will run -* The number of rule executions that are failing, pending, running, and completed for a manual run -* The total number of rule executions that are occurring for a manual run