Update ruleedit

Updates an existing signal detection rule.

You can use PUT or PATCH methods to update rules, where:

  • PUT replaces the original rule and deletes fields that are not specified.
  • PATCH updates the specified fields.

Request URLedit

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

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

Request bodyedit

A JSON object with:

  • The id or rule_id field of the rule you want to update.
  • The fields you want to modify.

If you call PUT to update a rule, all unspecified fields are deleted. You cannot modify the id or rule_id values.

For PATCH calls, any of the fields can be modified, whereas for PUT calls, some fields are required.

Name Type Description Required (PUT calls)

actions

actions[]

Array defining the automated actions (notifications) taken when signals are produced.

No

anomaly_threshold

Integer

Anomaly score threshold above which the rule creates signals. Valid values are from 0 to 100.

Yes, for machine learning rules. Not allowed in query rule types.

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).

index

String[]

Indices on which the rule functions.

No, defaults to the SIEM indices defined on the Kibana Advanced Settings page (KibanaManagementAdvanced Settingssiem: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).

machine_learning_job_id

String

Machine learning job ID the rule monitors for anomaly scores.

Yes, for machine learning rules. Not allowed in query rules types.

query

String

Query used by the rule to create a signal.

No. For query rules types, defaults to an empty string. Not allowed in machine-learning rule types.

language

String

Determines the query language, which must be kuery or lucene.

No. For query rule types, defaults to kuery. Not allowed in machine-learning rule types.

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

note

String

Notes to help investigate signals produced by the rule.

No

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.

throttle

String

Determines how often actions are taken:

  • no_actions: Never
  • rule: Every time new signals are detected
  • 1h: Every hour
  • 1d: Every day
  • 7d: Every week

Yes, when actions are used to send notifications.

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
  • machine_learning: rule based on a machine learning job’s anomaly scores.

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. If this is not provided, the rule’s version number is incremented by 1.

PATCH calls enabling and disabling the rule do not increment its version number.

No

actions schemaedit

Name Type Description Required (PUT calls)

action_type_id

String

The action type used for sending notifications, can be:

  • .slack
  • .email
  • .pagerduty
  • .webhook

Yes

group

String

Optionally groups actions by use cases. Use default for signal notifications.

Yes

id

String

The connector ID.

Yes

params

Object

Object containing the allowed connector fields, which varies according to the connector type:

  • For Slack:

    • message (string, required): The notification message.
  • For email:

    • to, cc, bcc (string): Email addresses to which the notifications are sent. At least one field must have a value.
    • subject (string, optional): Email subject line.
    • message (string, required): Email body text.
  • For Webhook:

    • body (string, required): JSON payload.
  • For PagerDuty:

    • severity (string, required): Severity of on the signal notification, can be: Critical, Error, Warning or Info.
    • eventAction (string, required): Event action type, which can be trigger, resolve, or acknowledge.
    • dedupKey (string, optional): Groups signal notifications with the same PagerDuty alert.
    • timestamp (DateTime, optional): ISO-8601 format timestamp.
    • component (string, optional): Source machine component responsible for the event, for example siem.
    • group (string, optional): Enables logical grouping of service components.
    • source (string, optional): The affected system. Defaults to the Kibana saved object ID of the action.
    • summary (string, options): Summary of the event. Defaults to No summary provided. Maximum length is 1024 characters.
    • class (string, optional): Value indicating the class/type of the event.

Yes

threat schemaedit

Only threats described using the MITRE ATT&CKTM framework are displayed in the UI (SIEMDetectionsManage signal detection rules → <rule name>).

Name Type Description Required (PUT calls)

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 requestedit

Updates the threat object:

PATCH api/detection_engine/rules
{
  "rule_id": "process_started_by_ms_office_program_possible_payload",
  "threat": [
   {
      "framework": "MITRE ATT&CK",
      "tactic": {
         "id": "TA0001",
         "reference": "https://attack.mitre.org/tactics/TA0001",
         "name": "Initial Access"
      },
      "technique": [
         {
            "id": "T1193",
            "name": "Spearphishing Attachment",
            "reference": "https://attack.mitre.org/techniques/T1193"
         }
      ]
   }
  ]
}

Response codeedit

200
Indicates a successful call.

Response payloadedit

The rule’s updated JSON object, including the time the rule was updated and an incremented version number.

Example response:

{
  "created_at": "2020-01-05T09:56:11.805Z",
  "updated_at": "2020-01-05T09:59:59.129Z",
  "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-6m",
  "id": "4f228868-9928-47e4-9785-9a1a9b520c7f",
  "interval": "5m",
  "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": [
    {
      "framework": "MITRE ATT&CK",
      "tactic": {
        "id": "TA0001",
        "reference": "https://attack.mitre.org/tactics/TA0001",
        "name": "Initial Access"
      },
      "technique": [
        {
          "id": "T1193",
          "name": "Spearphishing Attachment",
          "reference": "https://attack.mitre.org/techniques/T1193"
        }
      ]
    }
  ],
  "version": 2
}