From b5fdaf2acde56c76eb57cdec93a62e85e8a81a92 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Tue, 16 Jan 2024 18:01:55 -0600 Subject: [PATCH] Correct SA findings alerts API (#6179) * Correct SA findings alerts API Signed-off-by: Naarcha-AWS <naarcha@amazon.com> * Apply suggestions from code review Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM> Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --------- Signed-off-by: Naarcha-AWS <naarcha@amazon.com> Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM> --- .../api-tools/alert-finding-api.md | 32 ++++++++++++++----- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/_security-analytics/api-tools/alert-finding-api.md b/_security-analytics/api-tools/alert-finding-api.md index 129ebf058e..a22b601b08 100644 --- a/_security-analytics/api-tools/alert-finding-api.md +++ b/_security-analytics/api-tools/alert-finding-api.md @@ -11,7 +11,8 @@ nav_order: 50 The following APIs can be used for tasks related to alerts and findings. --- -## Get Alerts + +## Get alerts Provides an option for retrieving alerts related to a specific detector type or detector ID. @@ -21,12 +22,12 @@ You can specify the following parameters when requesting an alert. Parameter | Description :--- | :--- -`detectorId` | The ID of the detector used to fetch alerts. Optional when the `detectorType` is specified. Otherwise required. -`detectorType` | The type of detector used to fetch alerts. Optional when the `detectorId` is specified. Otherwise required. +`detector_id` | The ID of the detector used to fetch alerts. Optional when the `detectorType` is specified. Otherwise required. +`detectorType` | The type of detector used to fetch alerts. Optional when the `detector_Id` is specified. Otherwise required. `severityLevel` | Used to filter by alert severity level. Optional. -`alertState` | Used to filter by alert state. Possible values: ACTIVE, ACKNOWLEDGED, COMPLETED, ERROR, DELETED. Optional. +`alertState` | Used to filter by alert state. Possible values are ACTIVE, ACKNOWLEDGED, COMPLETED, ERROR, or DELETED. Optional. `sortString` | This field specifies which string Security Analytics uses to sort the alerts. Optional. -`sortOrder` | The order used to sort the list of findings, either `ascending` or `descending`. Optional. +`sortOrder` | The order used to sort the list of findings. Possible values are `asc` or `desc`. Optional. `missing` | A list of fields for which there are no found alias mappings. Optional. `size` | An optional limit for the maximum number of results returned in the response. Optional. `startIndex` | The pagination indicator. Optional. @@ -83,7 +84,10 @@ State | Description `DELETED` | Someone deleted the detector or trigger associated with this alert while the alert was ongoing. --- -## Acknowledge Alerts + +## Acknowledge alerts + +Sends an acknowledgement when an alert is triggered. ### Example request @@ -134,9 +138,21 @@ POST /_plugins/_security_analytics/<detector_id>/_acknowledge/alerts ``` --- -## Get Findings -The Get findings API based on detector attributes. +## Get findings + +The Get findings API returns findings based on the detector attributes. + +### Parameters + +You can specify the following parameters when getting findings. + +Parameter | Description +:--- | :--- +`detector_id` | The ID of the detector used to fetch alerts. Optional when the `detectorType` is specified. Otherwise required. +`detectorType` | The type of detector used to fetch alerts. Optional when the `detector_id` is specified. Otherwise required. +`sortOrder` | The order used to sort the list of findings. Possible values are `asc` or `desc`. Optional. +`size` | An optional limit for the maximum number of results returned in the response. Optional. ### Example request