Create ruleedit
Creates a new signal detection rule.
Request URLedit
POST <kibana host>:<port>/api/detection_engine/rules
Request bodyedit
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
|
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,
|
No, defaults to |
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 → |
interval |
String |
Frequency of rule execution, using a
date math range. For example, |
No, defaults to |
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
|
No, defaults to |
output_index |
String |
Index to which signals detected by the rule are saved. |
No, if unspecified signals are saved to |
saved_id |
String |
Kibana saved search used by the rule to create signals. |
Yes, for |
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:
|
Yes |
max_signals |
Integer |
Maximum number of signals the rule can create during a single execution. |
No, defaults to |
name |
String |
The rule’s name. |
Yes |
severity |
String |
Severity level of signals produced by the rule, which must be one of the following:
|
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:
|
Yes |
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 |
threat
schemaedit
Only threats described using the MITRE ATT&CKTM 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:
|
Yes |
technique |
Object |
Object containing information on the attack technique:
|
Yes |
Example requestedit
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 codeedit
-
200
- Indicates a successful call.
Response payloadedit
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 }