Import rules | Elastic Security Solution [master]

You are looking at preliminary documentation for a future release. Not what you want? See the current release documentation.

› › ›

« Tags endpoint Export rules »

Import rulesedit

Imports rules from an .ndjson file. The following configuration items are also included in the .ndjson file:

Actions
Exception lists

This API supports Token-based authentication only.

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 Import value lists UI (Rules → Detection rules (SIEM) → Import value lists) to export and import value lists separately.

Request URLedit

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

The request must include:

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

For example, using cURL:

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>"

The relative link to the .ndjson file containing the rules.

URL query parametersedit

Name	Type	Description	Required
`overwrite`	Boolean	Determines whether existing rules with the same `rule_id` are overwritten.	No, defaults to `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.	No, defaults to `false`.
`overwrite_action_connectors`	Boolean	Determines whether existing actions with the same `kibana.alert.rule.actions.id` are overwritten.	No, defaults to `false`.

Example requestedit

Imports the rules in the detection_rules.ndjson file and overwrites existing rules with the same rule_id values:

curl -X POST "api/detection_engine/rules/_import?overwrite=true"
-H 'kbn-xsrf: true' -H 'Content-Type: multipart/form-data'
--form "file=@detection_rules.ndjson"

Response codeedit

200: Indicates a successful call.

Example responseedit

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

« Tags endpoint Export rules »