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:

POST /_plugins/_security_analytics/correlation/rules

Request fields

Field	Type	Description
`index`	String	The name of the index used as the log source.
`query`	String	The query used to filter security logs for correlation.
`category`	String	The log type associated with the log source.

Example request

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"
    }
  ]
}

copy

Example response

{
  "_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"
      }
    ]
  }
}

Response fields

Field	Type	Description
`_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:

GET /_plugins/_security_analytics/correlations?start_timestamp=<start time in milliseconds>&end_timestamp=<end time in milliseconds>

Query parameters

Parameter	Type	Description
`start_timestamp`	Number	Start time for the time window, in milliseconds.
`end_timestamp`	Number	End time for the time window, in milliseconds.

Example request

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

copy

Example response

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

Response fields

Field	Type	Description
`finding1`	String	The Id for a first finding in the correlation.
`logType1`	String	The log type associated with the first finding.
`finding2`	String	The Id for a second finding in the correlation.
`logType2`	String	The log type associated with the second finding.
`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:

GET /_plugins/_security_analytics/findings/correlate?finding=425dce0b-f5ee-4889-b0c0-7d15669f0871&detector_type=ad_ldap&nearby_findings=20&time_window=10m

Query parameters

Parameter	Type	Description
`finding`	String	The finding ID.
`detector_type`	String	The log type for the detector.
`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

GET /_plugins/_security_analytics/findings/correlate?finding=425dce0b-f5ee-4889-b0c0-7d15669f0871&detector_type=ad_ldap&nearby_findings=20&time_window=10m

copy

Example response

{
  "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
    }
  ]
}

Response fields

Field	Type	Description
`finding`	String	The finding ID.
`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.