Alerts in correlations feature documentation (#7410)

* alerts in correlations feature documentation Signed-off-by: Riya Saxena <[email protected]> * Update correlation-eng.md Signed-off-by: Melissa Vagi <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update alerts.md Signed-off-by: Melissa Vagi <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Copy edit Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/api-tools/correlation-eng.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Signed-off-by: Melissa Vagi <[email protected]> * Update _security-analytics/usage/alerts.md Signed-off-by: Melissa Vagi <[email protected]> --------- Signed-off-by: Riya Saxena <[email protected]> Signed-off-by: Melissa Vagi <[email protected]> Co-authored-by: Melissa Vagi <[email protected]> Co-authored-by: Nathan Bower <[email protected]>
opensearch-project · Jun 20, 2024 · cdb346e · cdb346e
1 parent 14b8afc
commit cdb346e
Show file tree

Hide file tree

Showing 2 changed files with 177 additions and 25 deletions.
diff --git a/_security-analytics/api-tools/correlation-eng.md b/_security-analytics/api-tools/correlation-eng.md
@@ -5,19 +5,20 @@ parent: API tools
 nav_order: 55
 ---
 
-
 # Correlation engine APIs
 
 Correlation engine APIs allow you to create new correlation rules, view findings and correlations within a certain time window, and perform other tasks.
 
 ---
+
 ## Create correlation rules between log types
 
-This API is used to create correlation rules:
+You can use the following API to create correlation rules:
 
 ```json
 POST /_plugins/_security_analytics/correlation/rules
 ```
+{% include copy-curl.html %}
 
 ### Request fields
 
@@ -91,6 +92,7 @@ POST /_plugins/_security_analytics/correlation/rules
   }
 }
 ```
+{% include copy-curl.html %}
 
 ### Response fields
 
@@ -99,13 +101,15 @@ POST /_plugins/_security_analytics/correlation/rules
 | `_id` | String | The Id for the new rule. |
 
 ---
-## List all findings and their correlations within a time window
 
-This API provides a list of all findings and their correlations within a specified time window:
+## List all findings and correlations within a certain time window
+
+You can use the following API to list all findings and their correlations within a certain time window:
 
 ```json
 GET /_plugins/_security_analytics/correlations?start_timestamp=<start time in milliseconds>&end_timestamp=<end time in milliseconds>
 ```
+{% include copy-curl.html %}
 
 ### Query parameters
 
@@ -138,6 +142,7 @@ GET /_plugins/_security_analytics/correlations?start_timestamp=1689289210000&end
   ]
 }
 ```
+{% include copy-curl.html %}
 
 ### Response fields
 
@@ -150,13 +155,15 @@ GET /_plugins/_security_analytics/correlations?start_timestamp=1689289210000&end
 | `rules` | Array | A list of correlation rule IDs associated with the correlated findings. |
 
 ---
+
 ## List correlations for a finding belonging to a log type
 
-This API is used to list correlations for specific findings and the log types associated with them:
+You can use the following API to list correlations for certain findings and associated log types:
 
 ```json
 GET /_plugins/_security_analytics/findings/correlate?finding=425dce0b-f5ee-4889-b0c0-7d15669f0871&detector_type=ad_ldap&nearby_findings=20&time_window=10m
 ```
+{% include copy-curl.html %}
 
 ### Query parameters
 
@@ -167,7 +174,6 @@ GET /_plugins/_security_analytics/findings/correlate?finding=425dce0b-f5ee-4889-
 | `nearby_findings` | Number | The number of nearby findings with respect to the given finding Id. |
 | `time_window` | String | Sets a time window in which all of the correlations must have occurred together. |
 
-
 #### Example request
 
 ```json
@@ -213,6 +219,7 @@ GET /_plugins/_security_analytics/findings/correlate?finding=425dce0b-f5ee-4889-
   ]
 }
 ```
+{% include copy-curl.html %}
 
 ### Response fields
 
@@ -222,3 +229,136 @@ GET /_plugins/_security_analytics/findings/correlate?finding=425dce0b-f5ee-4889-
 | `detector_type` | String | The log type associated with the finding. |
 | `score` | Number | The correlation score for the correlated finding. The score is based on the proximity of relevant findings in the threat scenario defined by the correlation rule. |
 
+## List correlation alerts
+
+You can use the following API to list correlation alerts:
+
+```json
+GET /_plugins/_security_analytics/correlationAlerts
+```
+{% include copy-curl.html %}
+
+### Query parameters
+
+| Parameter | Type | Description |
+| :--- | :--- |:--- |
+| `correlation_rule_id` | String | The correlation rule ID. | Optional
+
+#### Example request
+
+```json
+GET /_plugins/_security_analytics/correlations?correlation_rule_id=VjY0MpABPzR_pcEveVRq
+```
+{% include copy-curl.html %}
+
+#### Example response
+
+```json
+{
+    "correlationAlerts": [
+        {
+            "correlated_finding_ids": [
+                "4f867df9-c9cb-4dc1-84bb-6c8b575f1a54"
+            ],
+            "correlation_rule_id": "VjY0MpABPzR_pcEveVRq",
+            "correlation_rule_name": "rule-corr",
+            "user": null,
+            "id": "8532c08b-3ab5-4e95-a1c2-5884c4cd41a5",
+            "version": 1,
+            "schema_version": 1,
+            "trigger_name": "trigger1",
+            "state": "ACTIVE",
+            "error_message": null,
+            "severity": "1",
+            "action_execution_results": [],
+            "start_time": "2024-06-19T20:37:08.257Z",
+            "end_time": "2024-06-19T20:42:08.257Z",
+            "acknowledged_time": null
+        },
+        {
+            "correlated_finding_ids": [
+                "30d2109f-76bb-44ad-8f68-6daa905e018d"
+            ],
+            "correlation_rule_id": "VjY0MpABPzR_pcEveVRq",
+            "correlation_rule_name": "rule-corr",
+            "user": null,
+            "id": "8bba85d9-a7fc-4c87-b35e-a7236b87159f",
+            "version": 1,
+            "schema_version": 1,
+            "trigger_name": "trigger1",
+            "state": "ACTIVE",
+            "error_message": null,
+            "severity": "1",
+            "action_execution_results": [],
+            "start_time": "2024-06-19T20:43:08.208Z",
+            "end_time": "2024-06-19T20:48:08.208Z",
+            "acknowledged_time": null
+        }
+    ],
+    "total_alerts": 2
+}
+```
+{% include copy-curl.html %}
+
+## Acknowledge correlation alerts
+
+You can use the following API to acknowledge the correlation alerts.
+
+### Example request
+
+```json
+POST /_plugins/_security_analytics/_acknowledge/correlationAlerts
+{
+   "alertIds": ["8532c08b-3ab5-4e95-a1c2-5884c4cd41a5", "8bba85d9-a7fc-4c87-b35e-a7236b87159f"]
+}
+```
+{% include copy-curl.html %}
+
+#### Example response
+
+```json
+{
+    "acknowledged": [
+        {
+            "correlated_finding_ids": [
+                "4f867df9-c9cb-4dc1-84bb-6c8b575f1a54"
+            ],
+            "correlation_rule_id": "VjY0MpABPzR_pcEveVRq",
+            "correlation_rule_name": "rule-corr",
+            "user": null,
+            "id": "8532c08b-3ab5-4e95-a1c2-5884c4cd41a5",
+            "version": 1,
+            "schema_version": 1,
+            "trigger_name": "trigger1",
+            "state": "ACTIVE",
+            "error_message": null,
+            "severity": "1",
+            "action_execution_results": [],
+            "start_time": "2024-06-19T20:37:08.257Z",
+            "end_time": "2024-06-19T20:42:08.257Z",
+            "acknowledged_time": null
+        },
+        {
+            "correlated_finding_ids": [
+                "30d2109f-76bb-44ad-8f68-6daa905e018d"
+            ],
+            "correlation_rule_id": "VjY0MpABPzR_pcEveVRq",
+            "correlation_rule_name": "rule-corr",
+            "user": null,
+            "id": "8bba85d9-a7fc-4c87-b35e-a7236b87159f",
+            "version": 1,
+            "schema_version": 1,
+            "trigger_name": "trigger1",
+            "state": "ACTIVE",
+            "error_message": null,
+            "severity": "1",
+            "action_execution_results": [],
+            "start_time": "2024-06-19T20:43:08.208Z",
+            "end_time": "2024-06-19T20:48:08.208Z",
+            "acknowledged_time": null
+        }
+    ],
+    "failed": []
+}
+```
+{% include copy-curl.html %}
diff --git a/_security-analytics/usage/alerts.md b/_security-analytics/usage/alerts.md
@@ -7,41 +7,53 @@ nav_order: 46
 
 # Working with alerts
 
-The Alerts window includes features for viewing and working with alerts. The two main features are:
-* The bar graph with alert information arranged by count, date, and alert status or alert severity.
-* The Alerts list arranged by time of the alert, the alert's trigger name, which detector triggered it, and other details.
+The **Alerts** window provides features for viewing and managing alerts. It consists of:
 
-You can select the **Refresh** button at any time to refresh information on the Alerts page.
+- A bar graph displaying alert counts, dates, and statuses or severities.
+- Two tabs:
+  - **Findings**: Lists detector-generated alerts, showing details such as alert time, trigger name, and the detector that triggered the alert.
+  - **Correlations**: Lists correlation-rule-generated alerts, showing details such as alert time, trigger name, and the correlation rule that triggered the alert.
+
+You can select the **Refresh** button to refresh information on the **Alerts** page.
 
 ---
-## The Alerts graph
 
-The Alerts graph can display alerts by their status or severity. Use the **Group by** dropdown list to specify either Alert status or Alert severity.
+## Alerts graph
+
+The **Alerts** graph displays alerts by their status or severity. Use the **Group by** dropdown menu to specify either **Alert status** or **Alert severity**.
 
-To specify the date range you would like the graph to display, first select the calendar dropdown arrow. The date selector window opens.
+To specify a date range, select the calendar icon to activate the dropdown menu. The date selector window opens. An example window is shown in the following image.
 <br><img src="{{site.url}}{{site.baseurl}}/images/Security/find-date-pick.png" alt="Date selector for findings graph" width="55%">
 
-You can use the **Quick select** settings to specify an exact window of time.
-* Select either **Last** or **Next** in the first dropdown list to set the window of time behind the current setting or ahead of the current setting.
-* Select a number in the second dropdown list to define a value for the range.
-* Select a unit of time in the third dropdown list. Available options are seconds, minutes, hours, days, weeks, months, and years.
-Select the **Apply** button to apply the range of dates to the graph. Information on the graph changes accordingly.
+You can use the **Quick select** settings to specify a date range:
+* Select either **Last** or **Next** from the first dropdown menu to set the date range to either behind the current setting or ahead of the current setting.
+* Select a number from the second dropdown menu to define a value for the range.
+* Select a unit of time from the third dropdown menu. Available options are seconds, minutes, hours, days, weeks, months, and years.
+* Select the **Apply** button to apply the time range to the graph. The graph is immediately updated.
+
+An example window is shown in the following image.
 
 <img src="{{site.url}}{{site.baseurl}}/images/Security/quickset.png" alt="Quick select settings example" width="40%">
 
-You can use the left and right arrows to move the window of time behind the current range of dates or ahead of the current range of dates. When you use these arrows, the start date and end date appear in the date range field. You can then select each one to set an absolute, relative, or current date and time. For absolute and relative changes, select the **Update** button to apply the changes.
+You can use the left and right arrows in the upper-left corner to shift the time range backward or forward, respectively. When you use these arrows, the start date and end date appear in the date range field. You can then select each one to set an absolute, relative, or current date and time. For absolute and relative changes, select the **Update** button to apply the changes. 
+
+An example window is shown in the following image.
 
 <img src="{{site.url}}{{site.baseurl}}/images/Security/date-pick.png" alt="Altering date range" width="55%">
 
-As an alternative, you can select an option in the **Commonly used** section (see the preceding image of the calendar dropdown list) to conveniently set a window of time. Options include date ranges such as **Today**, **Yesterday**, **this week**, and **week to date**. 
+As an alternative, you can select an option in the **Commonly used** section (see the preceding image of the calendar dropdown menu) to conveniently set a date range. Options include **Today**, **Yesterday**, **this week**, and **week to date**. 
 
-When one of the commonly used windows of time is selected, you can select the **Show dates** label in the date range field to populate the range of dates. Following that, you can select either the start date or end date to specify by an absolute, relative, or current date and time setting. For absolute and relative changes, select the **Update** button to apply the changes.
+When a commonly used date range is selected, you can select the **Show dates** label in the date range field to populate the ranges. You can then select either the start date or end date to specify an absolute, relative, or current date and time setting. For absolute and relative changes, select the **Update** button to apply the changes.
 
-As one more alternative, you can select an option from the **Recently used date ranges** section to go back to a previous setting.
+You can also select an option from the **Recently used date ranges** section to revert to a previous setting.
 
 ---
-## The Alerts list
 
-The Alerts list displays all findings according to the time when the alert was triggered, the alert's trigger name, the detector that triggered the alert, the alert status, and alert severity.
-Use the **Alert severity** dropdown list to filter the list of alerts by severity. Use the **Status** dropdown list to filter the list by alert status.
+## Alerts list
+
+The **Alerts list** displays all alerts, with two tabs for different types of alerts:
+
+- **Findings**: The **Alerts list** displays all findings according to the time when the alert was triggered, the alert's trigger name, the detector that triggered the alert, the alert status, and the alert severity.
+- **Correlations**:  The **Alerts list** displays all correlations, including the correlation rule and time window, the alert's trigger name, the correlation rule name that triggered the alert, the alert status, and the alert severity.
 
+Use the **Alert severity** dropdown menu to filter the list of alerts by severity. Use the **Status** dropdown menu to filter the list by alert status.