Import detection rules

POST /api/detection_engine/rules/_import

Import detection rules from an .ndjson file, including actions and exception lists. The request must include:

The Content-Type: multipart/form-data HTTP header.
A link to the .ndjson file containing the rules.

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.

info To import rules with actions, you need at least Read privileges for the Action and Connectors feature. To overwrite or add new connectors, you need All privileges for the Actions and Connectors feature. To import rules without actions, you don’t need Actions and Connectors privileges. Refer to Enable and access detections for more information.

Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) is not included. You must re-add missing connector details after importing detection rules.

You can use Kibana’s Saved Objects UI (Stack Management → Kibana → Saved Objects) or the Saved Objects APIs (experimental) to export and import any necessary connectors before importing detection rules.

Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the Manage value lists UI (Rules → Detection rules (SIEM) → Manage value lists) to export and import value lists separately.

Query parameters

overwrite boolean

Determines whether existing rules with the same rule_id are overwritten.

Default value is false.
overwrite_exceptions boolean

Determines whether existing exception lists with the same list_id are overwritten. Both the exception list container and its items are overwritten.

Default value is false.
overwrite_action_connectors boolean

Determines whether existing actions with the same kibana.alert.rule.actions.id are overwritten.

Default value is false.
as_new_list boolean

Generates a new list ID for each imported exception list.

Default value is false.

multipart/form-data

Body Required

file string(binary)

The .ndjson file containing the rules.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- action_connectors_errors array[object] Required
  
  Hide action_connectors_errors attributes Show action_connectors_errors attributes object
  
  error object Required
  
  Hide error attributes Show error attributes object
  
  message string Required
  
  status_code integer Required
  
  Minimum value is 400.
  
  id string
  
  item_id string
  
  Minimum length is 1.
  
  list_id string
  
  Minimum length is 1.
  
  rule_id string
  
  A unique identifier for the rule, which could be any string, not necessarily a UUID.
- action_connectors_success boolean Required
- action_connectors_success_count integer Required
  
  Minimum value is 0.
- action_connectors_warnings array[object] Required
  
  Hide action_connectors_warnings attributes Show action_connectors_warnings attributes object
  
  actionPath string Required
  
  buttonLabel string
  
  message string Required
  
  type string Required
- errors array[object] Required
  
  Hide errors attributes Show errors attributes object
  
  error object Required
  
  Hide error attributes Show error attributes object
  
  message string Required
  
  status_code integer Required
  
  Minimum value is 400.
  
  id string
  
  item_id string
  
  Minimum length is 1.
  
  list_id string
  
  Minimum length is 1.
  
  rule_id string
  
  A unique identifier for the rule, which could be any string, not necessarily a UUID.
- exceptions_errors array[object] Required
  
  Hide exceptions_errors attributes Show exceptions_errors attributes object
  
  error object Required
  
  Hide error attributes Show error attributes object
  
  message string Required
  
  status_code integer Required
  
  Minimum value is 400.
  
  id string
  
  item_id string
  
  Minimum length is 1.
  
  list_id string
  
  Minimum length is 1.
  
  rule_id string
  
  A unique identifier for the rule, which could be any string, not necessarily a UUID.
- exceptions_success boolean Required
- exceptions_success_count integer Required
  
  Minimum value is 0.
- rules_count integer Required
  
  Minimum value is 0.
- success boolean Required
- success_count integer Required
  
  Minimum value is 0.

POST /api/detection_engine/rules/_import

curl -X POST "<KibanaURL>/api/detection_engine/rules/_import"
-u <username>:<password> -H 'kbn-xsrf: true'
-H 'Content-Type: multipart/form-data'
--form "file=@<link to file>"

Response examples (200)

{
  "errors": [],
  "success": true,
  "rules_count": 1,
  "success_count": 1,
  "exceptions_errors": [],
  "exceptions_success": true,
  "exceptions_success_count": 0
}