Create rule

edit

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Create rule

edit

Creates a new signal detection rule.

Request URL

edit

POST <kibana host>:<port>/api/detection_engine/rules

Request body

edit

A JSON object with these fields:

Name	Type	Description	Required
description	String	The rule’s description.	Yes
enabled	Boolean	Determines whether the rule is enabled.	No, defaults to `true`.
false_positives	String[]	String array used to describe common reasons why the rule may issue false-positive signals.	No, defaults to an empty array.
filters	Object[]	The query and filter context array used to define the conditions for when signals are created from events.	No, defaults to an empty array.
from	String	Time from which data is analyzed each time the rule executes, using a date math range. For example, `now-4200s` means the rule analyzes data from 70 minutes before its start time.	No, defaults to `now-6m` (analyzes data from 6 minutes before the start time).
rule_id	String	Unique ID used to identify rules. For example, when a rule is converted from a third-party security solution.	No, automatically created when it is not provided.
index	String[]	Indices on which the rule functions.	No, defaults to the SIEM indices defined on the Kibana Advanced Settings page (Kibana → Management → Advanced Settings → `siem:defaultIndex`).
interval	String	Frequency of rule execution, using a date math range. For example, `"1h"` means the rule runs every hour.	No, defaults to `5m` (5 minutes).
query	String	Query used by the rule to create a signal.	No, defaults to an empty string.
language	String	Determines the query language, which must be `kuery` or `lucene`.	No, defaults to `kuery`.
output_index	String	Index to which signals detected by the rule are saved.	No, if unspecified signals are saved to `.siem-signals-<space_name>` index, where `<space_name>` is the name of the Kibana space in which the rule exists.
saved_id	String	Kibana saved search used by the rule to create signals.	Yes, for `saved_query` rules only.
meta	Object	Placeholder for metadata about the rule.	No
risk_score	Integer	A numerical representation of the signal’s severity from 0 to 100, where: `0` - `21` represents low severity `22` - `47` represents medium severity `48` - `73` represents high severity `74` - `100` represents critical severity	Yes
max_signals	Integer	Maximum number of signals the rule can create during a single execution.	No, defaults to `100`.
name	String	The rule’s name.	Yes
severity	String	Severity level of signals produced by the rule, which must be one of the following: `low`: Signals that are of interest but generally not considered to be security incidents `medium`: Signals that require investigation `high`: Signals that require immediate investigation `critical`: Signals that indicate it is highly likely a security incident has occurred	Yes
tags	String[]	String array containing words and phrases to help categorize, filter, and search rules.	No, defaults to an empty array.
type	String	Data type on which the rule is based: `query`: query-based conditions with or without additional filters `saved_query`: saved search, identified in the `saved_id` field	Yes
threat	threat[]	Object containing attack information about the type of threat the rule monitors, see ECS threat fields.	No, defaults to an empty array.
references	String[]	String array containing notes about or references to relevant information about the rule.	No, defaults to an empty array.
version	Integer	The rule’s version number.	No, defaults to `1`.

`threat` schema

edit

Only threats described using the MITRE ATT&CK^TM framework are displayed in the UI (SIEM → Detections → Manage signal detection rules → <rule name>).

Name	Type	Description	Required
framework	String	Relevant attack framework.	Yes
tactic	Object	Object containing information on the attack type: `id` - string, required `name` - string, required `reference` - string, required	Yes
technique	Object	Object containing information on the attack technique: `id` - string, required `name` - string, required `reference` - string, required	Yes

Example request

edit

Searches for processes started by MS Office:

POST api/detection_engine/rules
{
  "rule_id": "process_started_by_ms_office_program_possible_payload",
  "risk_score": 50,
  "description": "Process started by MS Office program - possible payload",
  "interval": "1h", 
  "name": "MS Office child process",
  "severity": "low",
  "tags": [
   "child process",
   "ms office"
   ],
  "type": "query",
  "from": "now-70m", 
  "query": "process.parent.name:EXCEL.EXE or process.parent.name:MSPUB.EXE or process.parent.name:OUTLOOK.EXE or process.parent.name:POWERPNT.EXE or process.parent.name:VISIO.EXE or process.parent.name:WINWORD.EXE",
  "language": "kuery",
  "filters": [
     {
      "query": {
         "match": {
            "event.action": {
               "query": "Process Create (rule: ProcessCreate)",
               "type": "phrase"
            }
         }
      }
     }
  ],
  "enabled": false
}

	The rule runs every hour.
	When the rule runs it analyzes data from 70 minutes before its start time.

Example

If the rule starts to run at 15:00, it analyzes data from 13:50 until 15:00. When it runs next, at 16:00, it will analyze data from 14:50 until 16:00.

Response code

edit

200: Indicates a successful call.

Response payload

edit

A JSON object that includes a unique ID, the time the rule was created, and its version number. If the request payload did not include a rule_id field, a unique rule ID is also generated.

Example response:

{
  "created_at": "2020-01-05T09:56:11.805Z",
  "updated_at": "2020-01-05T09:56:11.805Z",
  "created_by": "elastic",
  "description": "Process started by MS Office program - possible payload",
  "enabled": false,
  "false_positives": [],
  "filters": [
    {
      "query": {
        "match": {
          "event.action": {
            "query": "Process Create (rule: ProcessCreate)",
            "type": "phrase"
          }
        }
      }
    }
  ],
  "from": "now-4200s",
  "id": "4f228868-9928-47e4-9785-9a1a9b520c7f",
  "interval": "1h",
  "rule_id": "process_started_by_ms_office_program_possible_payload",
  "language": "kuery",
  "output_index": ".siem-signals-default",
  "max_signals": 100,
  "risk_score": 50,
  "name": "MS Office child process",
  "query": "process.parent.name:EXCEL.EXE or process.parent.name:MSPUB.EXE or process.parent.name:OUTLOOK.EXE or process.parent.name:POWERPNT.EXE or process.parent.name:VISIO.EXE or process.parent.name:WINWORD.EXE",
  "references": [],
  "severity": "low",
  "updated_by": "elastic",
  "tags": [
    "child process",
    "ms office"
  ],
  "type": "query",
  "threat": [],
  "version": 1
}

« Detections API Get rule »

Create rule

Create rule

Request URL

Request body

threat schema

Example request

Response code

Response payload

`threat` schema