Create a detection rule

Spaces method and path for this operation:

<div><span class="operation-verb post">post</span>&nbsp;<span class="operation-path">/s/{space_id}/api/detection_engine/rules</span></div>

Refer to Spaces for more information.

Create a new detection rule.

warn When used with API key authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.

If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.

You can create the following types of rules:

• Custom query: Searches the defined indices and creates an alert when a document matches the rule's KQL query.
• Event correlation: Searches the defined indices and creates an alert when results match an Event Query Language (EQL) query.
• Threshold: Searches the defined indices and creates an alert when the number of times the specified field's value meets the threshold during a single execution. When there are multiple values that meet the threshold, an alert is generated for each value. For example, if the threshold field is source.ip and its value is 10, an alert is generated for every source IP address that appears in at least 10 of the rule's search results. If you're interested, see Terms Aggregation for more information.
• Indicator match: Creates an alert when fields match values defined in the specified Elasticsearch index. For example, you can create an index for IP addresses and use this index to create an alert whenever an event's destination.ip equals a value in the index. The index's field mappings should be ECS-compliant.
• New terms: Generates an alert for each new term detected in source documents within a specified time range.
• ES|QL: Uses Elasticsearch Query Language (ES|QL) to find events and aggregate search results.
• Machine learning rules: Creates an alert when a machine learning job discovers an anomaly above the defined threshold.

info To create machine learning rules, you must have the appropriate license or use a cloud deployment. Additionally, for the machine learning rule to function correctly, the associated machine learning job must be running.

To retrieve machine learning job IDs, which are required to create machine learning jobs, call the Elasticsearch Get jobs API. Machine learning jobs that contain siem in the groups field can be used to create rules:

...
"job_id": "linux_anomalous_network_activity_ecs",
"job_type": "anomaly_detector",
"job_version": "7.7.0",
"groups": [
  "auditbeat",
  "process",
  "siem"
],
...

Additionally, you can set up notifications for when rules create alerts. The notifications use the Alerting and Actions framework. Each action type requires a connector. Connectors store the information required to send notifications via external systems. The following connector types are supported for rule notifications:

• Slack
• Email
• PagerDuty
• Webhook
• Microsoft Teams
• IBM Resilient
• Jira
• ServiceNow ITSM

info For more information on PagerDuty fields, see Send a v2 Event.

To retrieve connector IDs, which are required to configure rule notifications, call the Find objects API with "type": "action" in the request payload.

For detailed information on Kibana actions and alerting, and additional API calls, see:

• Alerting API
• Alerting and Actions framework
• Connectors API

{
  "actions": [
    {
      "frequency": {
        "throttle": "1h"
      }
    }
  ],
  "description": "Detects anomalous Windows process creation events.",
  "name": "Anomalous Windows Process Creation",
  "related_integrations": [
    {
      "integration": "activitylogs",
      "package": "azure",
      "version": "~1.1.6"
    }
  ],
  "response_actions": [
    {
      "params": {
        "config": {
          "linux": {
            "timeout": 60
          },
          "macos": {
            "timeout": 60
          },
          "windows": {
            "timeout": 60
          }
        }
      }
    }
  ],
  "throttle": "1h"
}

{
  "actions": [
    {
      "frequency": {
        "throttle": "1h"
      }
    }
  ],
  "description": "Detects anomalous Windows process creation events.",
  "name": "Anomalous Windows Process Creation",
  "related_integrations": [
    {
      "integration": "activitylogs",
      "package": "azure",
      "version": "~1.1.6"
    }
  ],
  "response_actions": [
    {
      "params": {
        "config": {
          "linux": {
            "timeout": 60
          },
          "macos": {
            "timeout": 60
          },
          "windows": {
            "timeout": 60
          }
        }
      }
    }
  ],
  "throttle": "1h"
}