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

Correlation engine APIs

원문 보기 위키 갱신

출처: 문서

본문

상관 엔진 API

상관 엔진 API를 사용하면 새로운 상관 규칙을 만들고, 특정 시간 창 내의 finding과 상관 관계를 조회하는 등 다양한 작업을 수행할 수 있어요.

로그 타입 간 상관 규칙 만들기

두 개 이상의 로그 소스에서 발생한 finding들을 서로 연관 짓는 상관 규칙을 만들어요.

엔드포인트

POST /_plugins/_security_analytics/correlation/rules

요청 본문 필드

다음 표에서 사용할 수 있는 요청 본문 필드를 확인할 수 있어요.

필드 데이터 타입 설명
name String 상관 규칙의 이름이에요. 선택 사항이에요.
correlate Array 상관 분석할 로그 소스예요. 최소 두 개 이상 지정해야 해요. 필수예요.
correlate.index String 로그 소스로 사용하는 인덱스의 이름이에요.
correlate.query String 상관 분석을 위해 보안 로그를 필터링하는 쿼리예요.
correlate.category String 로그 소스에 연결된 로그 타입이에요.
time_window Long finding들이 상관되려면 그 안에서 발생해야 하는 시간 창이에요. 단위는 밀리초예요. 선택 사항이며, 지정하지 않으면 plugins.security_analytics.correlation_time_window 클러스터 설정이 적용돼요.
trigger Object 규칙이 finding들을 상관시킬 때 상관 경보를 생성하고 알림을 보내요. 선택 사항이에요.
trigger.name String 트리거의 이름이에요.
trigger.severity String 트리거의 심각도 수준이에요. 정수로 표현해요: 1 = 가장 높음, 2 = 높음, 3 = 중간, 4 = 낮음, 5 = 가장 낮음.
trigger.actions Array 트리거가 경보를 생성할 때 보낼 알림이에요.
trigger.actions.name String 액션의 이름이에요. 각 액션마다 필수예요.
trigger.actions.destination_id String 메시지를 받는 알림 채널의 ID예요.
trigger.actions.subject_template.source String 알림 메시지의 제목이에요. 상관 규칙 트리거 변수를 포함할 수 있어요.
trigger.actions.subject_template.lang String 제목을 정의하는 데 사용하는 스크립팅 언어예요. mustache여야 해요.
trigger.actions.message_template.source String 알림 메시지의 본문이에요. 상관 규칙 트리거 변수를 포함할 수 있어요.
trigger.actions.message_template.lang String 메시지를 정의하는 데 사용하는 스크립팅 언어예요. mustache여야 해요.
trigger.actions.throttle_enabled Boolean 일정 시간 동안 전송되는 알림 수를 제한할지 여부예요. 기본값은 false예요.
trigger.actions.throttle.unit String 스로틀링에 사용하는 시간 단위예요.
trigger.actions.throttle.value Integer 스로틀링에 사용하는 시간 단위의 개수예요.

요청 예시

POST /_plugins/_security_analytics/correlation/rules
{
  "correlate": [
    {
      "index": "vpc_flow",
      "query": "dstaddr:4.5.6.7 or dstaddr:4.5.6.6",
      "category": "network"
    },
    {
      "index": "windows",
      "query": "winlog.event_data.SubjectDomainName:NTAUTHORI*",
      "category": "windows"
    },
    {
      "index": "ad_logs",
      "query": "ResultType:50126",
      "category": "ad_ldap"
    },
    {
      "index": "app_logs",
      "query": "endpoint:/customer_records.txt",
      "category": "others_application"
    }
  ]
}

{% include copy-curl.html %}

응답 예시

{
  "_id": "DxKEUIkBpIjg64IK4nXg",
  "_version": 1,
  "rule": {
    "name": null,
    "correlate": [
      {
        "index": "vpc_flow",
        "query": "dstaddr:4.5.6.7 or dstaddr:4.5.6.6",
        "category": "network"
      },
      {
        "index": "windows",
        "query": "winlog.event_data.SubjectDomainName:NTAUTHORI*",
        "category": "windows"
      },
      {
        "index": "ad_logs",
        "query": "ResultType:50126",
        "category": "ad_ldap"
      },
      {
        "index": "app_logs",
        "query": "endpoint:/customer_records.txt",
        "category": "others_application"
      }
    ]
  }
}

응답 본문 필드

다음 표에서 모든 응답 본문 필드를 확인할 수 있어요.

필드 데이터 타입 설명
_id String 새 규칙의 ID예요.

상관 규칙 트리거

상관 규칙에 trigger를 추가하면 규칙이 finding들을 상관시킬 때마다 상관 경보를 생성하고 알림을 보내요. 다음 요청은 네트워크 finding이 Active Directory finding과 상관될 때 채널에 알림을 보내는 트리거가 포함된 규칙을 만들어요:

POST /_plugins/_security_analytics/correlation/rules
{
  "name": "network-ad-correlation",
  "time_window": 300000,
  "correlate": [
    {
      "index": "vpc_flow",
      "query": "dstaddr:4.5.6.7",
      "category": "network"
    },
    {
      "index": "ad_logs",
      "query": "ResultType:50126",
      "category": "ad_ldap"
    }
  ],
  "trigger": {
    "name": "correlation-trigger",
    "severity": "1",
    "actions": [
      {
        "name": "notify-security-team",
        "destination_id": "6r8ZBoQBKW_6dKriacQb",
        "subject_template": {
          "source": {% raw %}"Correlation alert: {{ctx.correlationRuleName}}"{% endraw %},
          "lang": "mustache"
        },
        "message_template": {
          "source": {% raw %}"Rule {{ctx.correlationRuleName}} correlated finding {{ctx.sourceFinding}} with findings {{ctx.correlatedFindingIds}} within {{ctx.timeWindow}} ms."{% endraw %},
          "lang": "mustache"
        },
        "throttle_enabled": false
      }
    ]
  }
}

{% include copy-curl.html %}

응답에는 생성된 트리거와 액션 ID가 포함되어 있어요:

{
  "_id": "7mBjhqABedeO5z2szdu9",
  "_version": 1,
  "rule": {
    "name": "network-ad-correlation",
    "correlate": [
      {
        "index": "vpc_flow",
        "category": "network",
        "query": "dstaddr:4.5.6.7"
      },
      {
        "index": "ad_logs",
        "category": "ad_ldap",
        "query": "ResultType:50126"
      }
    ],
    "time_window": 300000,
    "trigger": {
      "id": "62BjhqABedeO5z2szdss",
      "name": "correlation-trigger",
      "severity": "1",
      "actions": [
        {
          "id": "6mBjhqABedeO5z2szdsr",
          "name": "notify-security-team",
          "destination_id": "6r8ZBoQBKW_6dKriacQb",
          "message_template": {
            "source": {% raw %}"Rule {{ctx.correlationRuleName}} correlated finding {{ctx.sourceFinding}} with findings {{ctx.correlatedFindingIds}} within {{ctx.timeWindow}} ms."{% endraw %},
            "lang": "mustache"
          },
          "throttle_enabled": false,
          "subject_template": {
            "source": {% raw %}"Correlation alert: {{ctx.correlationRuleName}}"{% endraw %},
            "lang": "mustache"
          }
        }
      ]
    }
  }
}

각 액션에는 name이 필요해요. 이를 생략한 요청은 uninitialized_property_access_exception 오류가 발생하며 실패해요. {: .note}

상관 규칙 트리거 변수

다음 표에서 상관 규칙 트리거 액션의 subject_template과 message_template에서 사용할 수 있는 변수를 확인할 수 있어요. 이 변수들은 모니터 변수에서 설명하는 alerting 모니터에서 사용할 수 있는 변수들과는 달라요.

변수 데이터 타입 설명
ctx.correlationRuleName String 경보를 생성한 상관 규칙의 이름이에요.
ctx.sourceFinding String 상관 관계를 시작한 finding의 ID예요.
ctx.correlatedFindingIds Array 소스 finding과 상관된 finding들의 ID예요.
ctx.timeWindow Long 상관 시간 창이에요. 단위는 밀리초예요.

컨텍스트 객체 전체를 보려면 메시지 본문에 {% raw %}{{ctx}}{% endraw %}를 추가하면 돼요.

특정 시간 창 내의 모든 finding과 상관 관계 목록 조회

특정 시간 창 내의 모든 finding과 그 상관 관계를 목록으로 보여줘요.

엔드포인트

GET /_plugins/_security_analytics/correlations

쿼리 파라미터

다음 표에서 사용할 수 있는 쿼리 파라미터를 확인할 수 있어요. 두 파라미터 모두 필수예요.

파라미터 데이터 타입 설명
start_timestamp Number 시간 창의 시작 시간이에요. 단위는 밀리초예요.
end_timestamp Number 시간 창의 종료 시간이에요. 단위는 밀리초예요.

요청 예시

GET /_plugins/_security_analytics/correlations?start_timestamp=1689289210000&end_timestamp=1689300010000

{% include copy-curl.html %}

응답 예시

{
  "findings": [
    {
      "finding1": "931de5f0-a276-45d5-9cdb-83e1045a3630",
      "logType1": "network",
      "finding2": "1e6f6a12-83f1-4a38-9bb8-648f196859cc",
      "logType2": "test_windows",
      "rules": [
        "nqI2TokBgL5wWFPZ6Gfu"
      ]
    }
  ]
}

응답 본문 필드

다음 표에서 모든 응답 본문 필드를 확인할 수 있어요.

필드 데이터 타입 설명
finding1 String 상관 관계에서 첫 번째 finding의 ID예요.
logType1 String 첫 번째 finding에 연결된 로그 타입이에요.
finding2 String 상관 관계에서 두 번째 finding의 ID예요.
logType2 String 두 번째 finding에 연결된 로그 타입이에요.
rules Array 상관된 finding들에 연결된 상관 규칙 ID 목록이에요.

로그 타입에 속한 finding의 상관 관계 목록 조회

주어진 finding과 상관된 finding들을 목록으로 보여줘요.

엔드포인트

GET /_plugins/_security_analytics/findings/correlate

쿼리 파라미터

다음 표에서 사용할 수 있는 쿼리 파라미터를 확인할 수 있어요.

파라미터 데이터 타입 설명
finding String finding의 ID예요. 필수예요.
detector_type String 디텍터의 로그 타입이에요. 필수예요.
nearby_findings Number 주어진 finding ID를 기준으로 주변에 있는 finding의 개수예요. 선택 사항이에요.
time_window String 모든 상관 관계가 함께 발생했어야 하는 시간 창을 설정해요. 선택 사항이에요.

요청 예시

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 %}

응답 예시

{
  "findings": [
    {
      "finding": "5c661104-aaa9-484b-a91f-9cad4ae6d5f5",
      "detector_type": "others_application",
      "score": 0.000015182109564193524
    },
    {
      "finding": "2485b623-6573-42f4-a055-9b927e38a65f",
      "detector_type": "ad_ldap",
      "score": 0.000001615897872397909
    },
    {
      "finding": "051e00ad-5996-4c41-be20-f992451d1331",
      "detector_type": "windows",
      "score": 0.000016230604160227813
    },
    {
      "finding": "f11ca8a3-50d7-4074-a951-51439aa9e67b",
      "detector_type": "s3",
      "score": 0.000001759401811796124
    },
    {
      "finding": "9b86980e-5fb7-4c5a-bd1b-879a1e3baf12",
      "detector_type": "network",
      "score": 0.0000016306962606904563
    },
    {
      "finding": "e7dea5a1-164f-48f9-880e-4ba33e508713",
      "detector_type": "network",
      "score": 0.00001632626481296029
    }
  ]
}

응답 본문 필드

다음 표에서 모든 응답 본문 필드를 확인할 수 있어요.

필드 데이터 타입 설명
finding String finding의 ID예요.
detector_type String finding에 연결된 로그 타입이에요.
score Number 상관된 finding의 상관 점수예요. 이 점수는 상관 규칙이 정의한 위협 시나리오에서 관련 finding들이 서로 얼마나 가까운지를 기반으로 매겨져요.

상관 경보 목록 조회

상관 규칙 트리거가 생성한 경보를 목록으로 보여줘요.

엔드포인트

GET /_plugins/_security_analytics/correlationAlerts

쿼리 파라미터

다음 표에서 사용할 수 있는 쿼리 파라미터를 확인할 수 있어요. 모든 쿼리 파라미터는 선택 사항이에요.

파라미터 데이터 타입 설명
correlation_rule_id String 상관 규칙의 ID예요.

요청 예시

GET /_plugins/_security_analytics/correlationAlerts?correlation_rule_id=VjY0MpABPzR_pcEveVRq

{% include copy-curl.html %}

응답 예시

응답 {: .text-delta} 
{
    "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
}

응답 본문 필드

다음 표에서 모든 응답 본문 필드를 확인할 수 있어요.

필드 데이터 타입 설명
correlationAlerts Array 요청과 일치하는 상관 경보예요.
correlationAlerts.correlated_finding_ids Array 규칙이 상관시킨 finding들의 ID예요.
correlationAlerts.correlation_rule_id String 경보를 생성한 상관 규칙의 ID예요.
correlationAlerts.correlation_rule_name String 경보를 생성한 상관 규칙의 이름이에요.
correlationAlerts.user Object 상관 규칙에 연결된 사용자예요.
correlationAlerts.id String 경보의 ID예요.
correlationAlerts.version Integer 경보의 버전이에요.
correlationAlerts.schema_version Integer 경보 인덱스 스키마의 버전이에요.
correlationAlerts.trigger_name String 경보를 생성한 트리거의 이름이에요.
correlationAlerts.state String 경보의 상태예요. 유효한 값은 ACTIVE, ACKNOWLEDGED, COMPLETED, ERROR, DELETED예요.
correlationAlerts.error_message String 경보의 오류 메시지예요. 오류가 있는 경우에만 표시돼요.
correlationAlerts.severity String 경보를 생성한 트리거의 심각도 수준이에요.
correlationAlerts.action_execution_results Array 트리거가 실행한 알림 액션의 결과예요.
correlationAlerts.start_time String 경보가 생성된 시간이에요.
correlationAlerts.end_time String 상관 시간 창이 끝난 시간이에요.
correlationAlerts.acknowledged_time String 경보가 확인 처리된 시간이에요. 아직 확인 처리되지 않았다면 null이에요.
total_alerts Integer 반환된 경보의 총 개수예요.

상관 경보 확인 처리

하나 이상의 상관 경보를 확인 처리해요.

엔드포인트

POST /_plugins/_security_analytics/_acknowledge/correlationAlerts

요청 본문 필드

다음 표에서 사용할 수 있는 요청 본문 필드를 확인할 수 있어요.

필드 데이터 타입 설명
alertIds Array 확인 처리할 상관 경보의 ID예요. 필수예요.

요청 예시

POST /_plugins/_security_analytics/_acknowledge/correlationAlerts
{
   "alertIds": ["8532c08b-3ab5-4e95-a1c2-5884c4cd41a5", "8bba85d9-a7fc-4c87-b35e-a7236b87159f"]
}

{% include copy-curl.html %}

응답 예시

응답 {: .text-delta} 
{
    "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": []
}

응답 본문 필드

다음 표에서 모든 응답 본문 필드를 확인할 수 있어요.

필드 데이터 타입 설명
acknowledged Array 확인 처리된 상관 경보예요.
failed Array 확인 처리에 실패한 상관 경보예요.

더 알아보기 (Learn more)

함께 읽는 실무 이야기

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