본문 바로가기
WIKI 기술 지식 베이스

Alerts and findings APIs

원문 보기 위키 갱신

출처: 문서

본문

알림 및 findings API

다음 API는 알림 및 findings와 관련된 작업에 사용할 수 있어요.

Get alerts

특정 detector type이나 detector ID에 해당하는 알림을 조회하는 옵션을 제공해요.

파라미터

알림을 요청할 때 다음 파라미터를 지정할 수 있어요.

파라미터 설명
detector_id 알림을 가져올 때 사용하는 detector의 ID예요. detectorType을 지정하면 생략할 수 있고, 그렇지 않으면 필수예요.
detectorType 알림을 가져올 때 사용하는 detector의 타입이에요. detector_Id를 지정하면 생략할 수 있고, 그렇지 않으면 필수예요.
severityLevel 알림 심각도 수준으로 필터링할 때 사용해요. 생략할 수 있어요.
alertState 알림 상태로 필터링할 때 사용해요. 가능한 값은 ACTIVE, ACKNOWLEDGED, COMPLETED, ERROR, DELETED예요. 생략할 수 있어요.
sortString Security Analytics가 알림을 정렬할 때 사용하는 문자열을 지정하는 필드예요. 생략할 수 있어요.
sortOrder findings 목록을 정렬할 때 사용하는 순서예요. 가능한 값은 asc 또는 desc예요. 생략할 수 있어요.
missing alias 매핑을 찾지 못한 필드들의 목록이에요. 생략할 수 있어요.
size 응답에 반환되는 최대 결과 수를 제한하는 옵션이에요. 생략할 수 있어요.
startIndex 페이지네이션 지시자예요. 생략할 수 있어요.
searchString 검색 시 반환받고 싶은 알림 속성이에요. 생략할 수 있어요.

요청 예시

GET /_plugins/_security_analytics/alerts?detectorType=windows

응답 예시

{
    "alerts": [{
        "detector_id": "detector_12345",
        "id": "alert_id_1",
        "version": -3,
        "schema_version": 0,
        "trigger_id": "trigger_id_1",
        "trigger_name": "my_trigger",
        "finding_ids": ["finding_id_1"],
        "related_doc_ids": ["docId1"],
        "state": "ACTIVE",
        "error_message": null,
        "alert_history": [],
        "severity": null,
        "action_execution_results": [{
            "action_id": "action_id_1",
            "last_execution_time": 1665693544996,
            "throttled_count": 0
        }],
        "start_time": "2022-10-13T20:39:04.995023Z",
        "last_notification_time": "2022-10-13T20:39:04.995028Z",
        "end_time": "2022-10-13T20:39:04.995027Z",
        "acknowledged_time": "2022-10-13T20:39:04.995028Z"
    }],
    "total_alerts": 1,
    "detectorType": "windows"
}

응답 본문 필드

알림은 근본 원인을 해결할 때까지 유지되며, 다음과 같은 상태를 가져요:

상태 설명
ACTIVE 알림이 진행 중이고 아직 acknowledge되지 않은 상태예요. 알림을 acknowledge하거나, 알림과 연관된 trigger를 삭제하거나, monitor를 완전히 삭제하기 전까지는 이 상태로 유지돼요.
ACKNOWLEDGED 누군가 알림을 acknowledge했지만 근본 원인은 수정하지 않은 상태예요.
COMPLETED 알림이 더 이상 진행 중이 아닌 상태예요. 해당 trigger의 평가 결과가 false가 되면 알림이 이 상태로 바뀌어요.
ERROR trigger를 실행하는 동안 오류가 발생한 상태예요. 이 오류는 보통 잘못된 trigger나 destination 때문에 발생해요.
DELETED 알림이 진행 중인 동안 누군가 이 알림과 연관된 detector나 trigger를 삭제한 상태예요.

Acknowledge alerts

알림이 트리거되면 acknowledgment를 전송해요.

요청 예시

POST /_plugins/_security_analytics/detectors/{detector_id}/_acknowledge/alerts

{"alerts":["4dc7f5a9-2c82-4786-81ca-433a209d5205"]}

응답 예시

{
  "acknowledged": [
    {
      "detector_id": "8YT5fYQBZ8IUM4axics6",
      "id": "4dc7f5a9-2c82-4786-81ca-433a209d5205",
      "version": 1,
      "schema_version": 4,
      "trigger_id": "1TP5fYQBMkkIGY6Pg-q8",
      "trigger_name": "test-trigger",
      "finding_ids": [
        "2e167f4b-8063-40ef-80f8-2afd9bf095b8"
      ],
      "related_doc_ids": [
        "1|windows"
      ],
      "state": "ACTIVE",
      "error_message": null,
      "alert_history": [],
      "severity": "1",
      "action_execution_results": [
        {
          "action_id": "BopdoIJKXd",
          "last_execution_time": 1668560817925,
          "throttled_count": 0
        }
      ],
      "start_time": "2022-11-16T01:06:57.748Z",
      "last_notification_time": "2022-11-16T01:06:57.748Z",
      "end_time": null,
      "acknowledged_time": null
    }
  ],
  "failed": [],
  "missing": []
}

Get findings

Get Findings API는 detector 속성을 기준으로 findings를 반환해요.

파라미터

findings를 가져올 때 다음 파라미터를 지정할 수 있어요.

파라미터 설명
detector_id 알림을 가져올 때 사용하는 detector의 ID예요. 생략할 수 있어요.
detectorType 알림을 가져올 때 사용하는 detector의 타입이에요. 생략할 수 있어요.
sortOrder findings 목록을 정렬할 때 사용하는 순서예요. 가능한 값은 asc 또는 desc예요. 생략할 수 있어요.
size 응답에 반환되는 최대 결과 수를 제한하는 옵션이에요. 생략할 수 있어요.
startIndex 페이지네이션 지시자예요. 생략할 수 있어요.
detectionType findings의 조회 방식을 결정하는 탐지 규칙 타입이에요. detection type이 threat이면 threat intelligence feed를 가져오고, rule이면 detector의 규칙을 기준으로 findings를 가져와요. 생략할 수 있어요.
severity 알림을 가져올 때 사용하는 detector 규칙의 심각도예요. 심각도는 critical, high, medium, low 중 하나예요. 생략할 수 있어요.

요청 예시

GET /_plugins/_security_analytics/findings/_search
{
  "total_findings": 2,
  "findings": [
    {
      "detectorId": "b9ZN040Bjlggkcgx1d1W",
      "id": "35efb736-c5d9-499d-b9b5-31f0a7d61251",
      "related_doc_ids": [
        "1"
      ],
      "index": "smallidx",
      "queries": [
        {
          "id": "QdZN040Bjlggkcgxdd3X",
          "name": "QdZN040Bjlggkcgxdd3X",
          "fields": [],
          "query": "field1: *value1*",
          "tags": [
            "high",
            "ad_ldap"
          ]
        }
      ],
      "timestamp": 1708647166500,
      "document_list": [
        {
          "index": "smallidx",
          "id": "1",
          "found": true,
          "document": "{\n  \"field1\": \"value1\"\n}\n"
        }
      ]
    },
    {
      "detectorId": "O9ZM040Bjlggkcgx6N1S",
      "id": "a5022930-4503-4ca8-bf0a-320a2b1fb433",
      "related_doc_ids": [
        "1"
      ],
      "index": "smallidx",
      "queries": [
        {
          "id": "KtZM040Bjlggkcgxkd04",
          "name": "KtZM040Bjlggkcgxkd04",
          "fields": [],
          "query": "field1: *value1*",
          "tags": [
            "critical",
            "ad_ldap"
          ]
        }
      ],
      "timestamp": 1708647166500,
      "document_list": [
        {
          "index": "smallidx",
          "id": "1",
          "found": true,
          "document": "{\n  \"field1\": \"value1\"\n}\n"
        }
      ]
    }
  ]
}


GET /_plugins/_security_analytics/findings/_search?severity=high
{
    "total_findings": 1,
    "findings": [
        {
            "detectorId": "b9ZN040Bjlggkcgx1d1W",
            "id": "35efb736-c5d9-499d-b9b5-31f0a7d61251",
            "related_doc_ids": [
                "1"
            ],
            "index": "smallidx",
            "queries": [
                {
                    "id": "QdZN040Bjlggkcgxdd3X",
                    "name": "QdZN040Bjlggkcgxdd3X",
                    "fields": [],
                    "query": "field1: *value1*",
                    "tags": [
                        "high",
                        "ad_ldap"
                    ]
                }
            ],
            "timestamp": 1708647166500,
            "document_list": [
                {
                    "index": "smallidx",
                    "id": "1",
                    "found": true,
                    "document": "{\n  \"field1\": \"value1\"\n}\n"
                }
            ]
        }
    ]
}
        

GET /_plugins/_security_analytics/findings/_search?detectionType=rule
{
    "total_findings": 2,
    "findings": [
        {
            "detectorId": "b9ZN040Bjlggkcgx1d1W",
            "id": "35efb736-c5d9-499d-b9b5-31f0a7d61251",
            "related_doc_ids": [
                "1"
            ],
            "index": "smallidx",
            "queries": [
                {
                    "id": "QdZN040Bjlggkcgxdd3X",
                    "name": "QdZN040Bjlggkcgxdd3X",
                    "fields": [],
                    "query": "field1: *value1*",
                    "tags": [
                        "high",
                        "ad_ldap"
                    ]
                }
            ],
            "timestamp": 1708647166500,
            "document_list": [
                {
                    "index": "smallidx",
                    "id": "1",
                    "found": true,
                    "document": "{\n  \"field1\": \"value1\"\n}\n"
                }
            ]
        },
        {
            "detectorId": "O9ZM040Bjlggkcgx6N1S",
            "id": "a5022930-4503-4ca8-bf0a-320a2b1fb433",
            "related_doc_ids": [
                "1"
            ],
            "index": "smallidx",
            "queries": [
                {
                    "id": "KtZM040Bjlggkcgxkd04",
                    "name": "KtZM040Bjlggkcgxkd04",
                    "fields": [],
                    "query": "field1: *value1*",
                    "tags": [
                        "critical",
                        "ad_ldap"
                    ]
                }
            ],
            "timestamp": 1708647166500,
            "document_list": [
                {
                    "index": "smallidx",
                    "id": "1",
                    "found": true,
                    "document": "{\n  \"field1\": \"value1\"\n}\n"
                }
            ]
        }
    ]
}



GET /_plugins/_security_analytics/findings/_search?detectionType=rule&severity=high
{
    "total_findings": 1,
    "findings": [
        {
            "detectorId": "b9ZN040Bjlggkcgx1d1W",
            "id": "35efb736-c5d9-499d-b9b5-31f0a7d61251",
            "related_doc_ids": [
                "1"
            ],
            "index": "smallidx",
            "queries": [
                {
                    "id": "QdZN040Bjlggkcgxdd3X",
                    "name": "QdZN040Bjlggkcgxdd3X",
                    "fields": [],
                    "query": "field1: *value1*",
                    "tags": [
                        "high",
                        "ad_ldap"
                    ]
                }
            ],
            "timestamp": 1708647166500,
            "document_list": [
                {
                    "index": "smallidx",
                    "id": "1",
                    "found": true,
                    "document": "{\n  \"field1\": \"value1\"\n}\n"
                }
            ]
        }
    ]
}
        

GET /_plugins/_security_analytics/findings/_search?*detectorType*=
{
    "total_findings":2,
    "findings":[
       {
            "detectorId":"12345",
            "id":"2b9663f4-ae77-4df8-b84f-688a0195723b",
            "related_doc_ids":[
                "5"
            ],
            "index":"sbwhrzgdlg",
            "queries":[
                {
                    "id":"f1bff160-587b-4500-b60c-ab22c7abc652",
                    "name":"3",
                    "query":"test_field:\"us-west-2\"",
                    "tags":[
                        
                    ]
                }
            ],
            "timestamp":1664401088804,
            "document_list":[
                {
                    "index":"sbwhrzgdlg",
                    "id":"5",
                    "found":true,
                    "document":"{\n            \"message\" : \"This is an error from IAD region\",\n            \"test_strict_date_time\" : \"2022-09-28T21:38:02.888Z\",\n            \"test_field\" : \"us-west-2\"\n        }"
                }
            ]
        },
        {
            "detectorId":"12345",
            "id":"f43a2701-0ef5-4931-8254-bdf510f73952",
            "related_doc_ids":[
                "1"
            ],
            "index":"sbwhrzgdlg",
            "queries":[
                {
                    "id":"f1bff160-587b-4500-b60c-ab22c7abc652",
                    "name":"3",
                    "query":"test_field:\"us-west-2\"",
                    "tags":[
                        
                    ]
                }
            ],
            "timestamp":1664401088746,
            "document_list":[
                {
                    "index":"sbwhrzgdlg",
                    "id":"1",
                    "found":true,
                    "document":"{\n            \"message\" : \"This is an error from IAD region\",\n            \"test_strict_date_time\" : \"2022-09-28T21:38:02.888Z\",\n            \"test_field\" : \"us-west-2\"\n        }"
                }
            ]
        }
    ]
}

더 알아보기 (Learn more)

함께 읽는 실무 이야기

우리 조직에도 적용하고 싶다면, AI 시스템 구축 서비스를 살펴보세요.