diff --git a/docs/detections/api/lists-api-index.asciidoc b/docs/detections/api/lists-api-index.asciidoc deleted file mode 100644 index 69c01778bd..0000000000 --- a/docs/detections/api/lists-api-index.asciidoc +++ /dev/null @@ -1,25 +0,0 @@ -include::lists/lists-api-overview.asciidoc[] - -include::lists/api-create-list-container.asciidoc[] - -include::lists/api-create-list-item.asciidoc[] - -include::lists/api-import-list-items.asciidoc[] - -include::lists/api-find-list-containers.asciidoc[] - -include::lists/api-find-list-items.asciidoc[] - -include::lists/api-get-list-containers.asciidoc[] - -include::lists/api-get-list-items.asciidoc[] - -include::lists/api-update-list-container.asciidoc[] - -include::lists/api-update-list-item.asciidoc[] - -include::lists/api-export-list-item.asciidoc[] - -include::lists/api-delete-list-container.asciidoc[] - -include::lists/api-delete-list-item.asciidoc[] diff --git a/docs/detections/api/lists/api-create-list-container.asciidoc b/docs/detections/api/lists/api-create-list-container.asciidoc deleted file mode 100644 index bb82ee70bc..0000000000 --- a/docs/detections/api/lists/api-create-list-container.asciidoc +++ /dev/null @@ -1,166 +0,0 @@ -[[lists-api-create-container]] -=== Create list container - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-lists-api[lists APIs]. --- - -Creates a list container. - -A list container groups common <> that -define exceptions for when detection rule alerts are *not* generated even when -a rule's other criteria are met. - -All list items in the same list container refer to the same type of exception. -For example, each list item in an `ip` list container excludes an IP address. - -TIP: You can retrieve `ip` items in a list container using CIDR notation, and -`ip_range` items using a single IP value. For examples, see -<>. - -==== Request URL - -`POST :/api/lists` - -==== Request body - -A JSON object that defines the list container's properties. - -===== Required fields - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|`description` |String |Describes the list container. -|`name` |String |The list container's name. -|`type` |String a|Specifies the {es} {ref}/mapping-types.html[data type] of -excludes the list container holds. Some common examples: - -* `keyword`: Many ECS fields are {es} {ref}/keyword.html[keywords] -* `ip`: IP addresses -* `ip_range`: {ref}/range.html[Range of IP addresses] (supports IPv4, IPv6, and -CIDR notation) -|============================================== - -===== Optional fields - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|`deserializer` |String a|Determines how retrieved list item values are presented. -By default list items are presented using these -https://handlebarsjs.com/guide/expressions.html[Handelbar] expressions: - -* `{{{value}}}` - Single value item types, such as `ip`, `long`, `date`, `keyword`, -and `text`. -* `{{{gte}}}-{{{lte}}}` - Range value item types, such as `ip_range`, -`double_range`, `float_range`, `integer_range`, and `long_range`. -* `{{{gte}}},{{{lte}}}` - Date range values. - -For information on parsing item values when they are uploaded, see -<>. - -|`id` |String |Unique identifier. Automatically created when it is not -provided. -|`meta` |Object |Placeholder for metadata about the list container. - -|[[serializer]] `serializer` |String a|Determines how uploaded list item values -are parsed. By default, list items are parsed using these -https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Groups_and_Ranges[named regex groups]: - -* `(?.+)` - Single value item types, such as `ip`, `long`, `date`, `keyword`, -and `text`. -* `(?.+)-(?.+)\|(?.+)` - Range value item types, such as -`date_range`, `ip_range`, `double_range`, `float_range`, `integer_range`, and -`long_range`. - -|`version` |Integer |The list container's version number. Defaults to `1`. - -|============================================== - -===== Example requests - -Creates a list container for IP addresses: - -[source,console] --------------------------------------------------- -POST api/lists -{ - "id": "internal-ip-excludes", - "name": "Exclude internal IP addresses", - "description": "Contains list items that exclude internal IP addresses from detection rules.", - "type": "ip" -} --------------------------------------------------- -// KIBANA - -Creates a list container for a keyword: - -[source,console] --------------------------------------------------- -POST api/lists -{ - "id": "host.name-container", - "name": "Exclude hosts", - "description": "Contains list items that exclude host names from detection rules.", - "type": "keyword" -} --------------------------------------------------- -// KIBANA - -Creates a list container for `ip_range` items with custom parsing: - -[source,console] --------------------------------------------------- -POST api/lists -{ - "id": "internal-ip-range-excludes", - "name": "Exclude IP ranges", - "description": "Contains excluded IP ranges.", - "serializer": "(?.+)/(?.+)", <1> - "deserializer": "{{{gte}}}--{{{lte}}}", <2> - "type": "ip_range" -} --------------------------------------------------- -// KIBANA - -<1> Uploads IP ranges using `/` characters instead of `-` characters. The list -item or source file from which the IP ranges are uploaded must use the `/` -character to define the range. For example, `192.168.0.1/192.168.0.27`. -<2> Presents the container's retrieved IP range list items using `--` -characters. For example, `192.168.0.1--192.168.0.27`. - -==== Response code - -`200`:: - Indicates a successful call. - - -==== Response payload - -[source,json] --------------------------------------------------- -{ - "_version": "WzAsMV0=", <1> - "id": "internal-ip-excludes", - "created_at": "2020-08-11T10:08:05.289Z", - "created_by": "elastic", - "description": "Contains list items that exclude internal IP addresses from detection rule matches.", - "immutable": false, - "name": "Exclude internal IP addresses", - "tie_breaker_id": "f7951678-ad13-4d65-8d15-a4c706d4893e", - "type": "ip", - "updated_at": "2020-08-11T10:08:05.289Z", - "updated_by": "elastic", - "version": 1 -} --------------------------------------------------- - -<1> Base-64 encoded value of `if_seq_no` and `if_primary_term` parameters, used -for {ref}/optimistic-concurrency-control.html[Optimistic concurrency control]. -To ensure there are no conflicts, use this value when -<>. diff --git a/docs/detections/api/lists/api-create-list-item.asciidoc b/docs/detections/api/lists/api-create-list-item.asciidoc deleted file mode 100644 index ea8fc5ef0e..0000000000 --- a/docs/detections/api/lists/api-create-list-item.asciidoc +++ /dev/null @@ -1,101 +0,0 @@ -[[lists-api-create-list-item]] -=== Create list item - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-lists-api[lists APIs]. --- - -Creates a list item and associates it with the specified -<>. - -All list items in the same list container must be the same type. For example, -each list item in an `ip` list container must define a specific IP address. - -NOTE: Before creating list items, you must create a list container. - -==== Request URL - -`POST :/api/lists/items` - -==== Request body - -A JSON object with these fields: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`id` |String |Unique identifier of the list item. |No, automatically created -when it is not provided. -|`list_id` |String |ID of the associated <>. |Yes -|`meta` |Object |Placeholder for metadata about the list item. |No -|`value` |String |The value used to evaluate exceptions. For information on how -list item exceptions are evaluated, see {api-kibana}/operation/operation-createexceptionlistitem[Create an exception list item]. |Yes -|{ref}/docs-refresh.html[`refresh`] |String a| Determines when changes made by the request become visible to search. Defaults to `wait_for`. Valid values are: - -* `true` -* `false` -* `wait_for` - -|No -|============================================== - -===== Example requests - -Adds an IP address to the `internal-ip-excludes` list container: - -[source,console] --------------------------------------------------- -POST api/lists/items -{ - "id": "internal-ip-1", - "list_id": "internal-ip-excludes", - "value": "10.0.0.12" -} --------------------------------------------------- -// KIBANA - -Adds a host name to the `host.name-container` list container: - -[source,console] --------------------------------------------------- -POST api/lists -{ - "id": "win-prem-19", - "list_id": "host.name-container", - "value": "hostname-123" -} --------------------------------------------------- -// KIBANA - - - -==== Response code - -`200`:: - Indicates a successful call. - -==== Response payload - -[source,json] --------------------------------------------------- -{ - "_version": "WzEsMV0=", <1> - "id": "internal-ip-1", - "type": "ip", - "value": "10.0.0.12", - "created_at": "2020-08-11T10:54:46.080Z", - "created_by": "elastic", - "list_id": "internal-ip-excludes", - "tie_breaker_id": "ed3f9d84-cd85-4122-b93d-07d1de4fd8bb", - "updated_at": "2020-08-11T10:54:46.080Z", - "updated_by": "elastic" -} --------------------------------------------------- - -<1> Base-64 encoded value of `if_seq_no` and `if_primary_term` parameters, used -for {ref}/optimistic-concurrency-control.html[Optimistic concurrency control]. -To ensure there are no conflicts, use this value when -<>. diff --git a/docs/detections/api/lists/api-delete-list-container.asciidoc b/docs/detections/api/lists/api-delete-list-container.asciidoc deleted file mode 100644 index 6479886c6a..0000000000 --- a/docs/detections/api/lists/api-delete-list-container.asciidoc +++ /dev/null @@ -1,37 +0,0 @@ -[[lists-api-delete-container]] -=== Delete list container - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-lists-api[lists APIs]. --- - -Deletes a list container. - -NOTE: When you delete a list container, all of its list items are also deleted. - -==== Request URL - -`DELETE :/api/lists` - -===== URL query parameters - -The URL query must include the list container's `id`: - -`id` - `DELETE /api/lists?id=` - -===== Example request - -Deletes the list container with an `id` of `external-ip-excludes`: - -[source,console] --------------------------------------------------- -DELETE api/lists?id=external-ip-excludes --------------------------------------------------- -// KIBANA - -==== Response code - -`200`:: - Indicates a successful call. diff --git a/docs/detections/api/lists/api-delete-list-item.asciidoc b/docs/detections/api/lists/api-delete-list-item.asciidoc deleted file mode 100644 index e22763e4c3..0000000000 --- a/docs/detections/api/lists/api-delete-list-item.asciidoc +++ /dev/null @@ -1,62 +0,0 @@ -[[lists-api-delete-item]] -=== Delete list item - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-lists-api[lists APIs]. --- - -Deletes list items. - -==== Request URL - -`DELETE :/api/lists/items` - -===== URL query parameters - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`id` |String |Unique identifier of the list item. |Required if `list_id` and `value` are not specified. -|`list_id` |String |Unique identifier of the <>. -|Required if `id` is not specified. -|`value` |String |The value used to evaluate exceptions. For information on how -list item exceptions are evaluated, refer to -{api-kibana}/operation/operation-createexceptionlistitem[Create an exception list item]. |Required if `id` is not specified. -|{ref}/docs-refresh.html[`refresh`] |String a| Determines when changes made by the request are made visible to search. Defaults to `false`. Valid values are: - -* `true` -* `false` - -|Optional. -|============================================== - -The URL query must include one of the following: - -* `id` - `DELETE /api/lists/items?id=` -* `list_id` and `value` - `DELETE /api/lists/items?list_id=&value=` - -===== Example request - -Deletes the list item with an `id` of `internal-ip-london`: - -[source,console] --------------------------------------------------- -DELETE api/lists/items?id=internal-ip-london --------------------------------------------------- -// KIBANA - -Deletes list items from an `ip` container using CIDR notation: - -[source,console] --------------------------------------------------- -DELETE api/lists/items?list_id=internal-ip-excludes&value=127.0.0.0/30 --------------------------------------------------- -// KIBANA - -==== Response code - -`200`:: - Indicates a successful call. diff --git a/docs/detections/api/lists/api-export-list-item.asciidoc b/docs/detections/api/lists/api-export-list-item.asciidoc deleted file mode 100644 index 74cf58a01d..0000000000 --- a/docs/detections/api/lists/api-export-list-item.asciidoc +++ /dev/null @@ -1,40 +0,0 @@ -[[lists-api-export-items]] -=== Export list items - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-lists-api[lists APIs]. --- - -Exports list item values from the specified list container. - -==== Request URL - -`POST :/api/lists/items/_export` - - -===== URL query parameters - -The URL query must include the list container's `id`: - -`id` - `POST /api/lists/items/_export?list_id=` - -TIP: If you want to to use cURL to export rules to a file, use the `-o` option -to specify a file name. - -===== Example request - -Exports the values of the `external-ip-excludes` list container: - -[source,console] --------------------------------------------------- -POST api/lists/items/_export?list_id=external-ip-excludes --------------------------------------------------- -// KIBANA - - -==== Response code - -`200`:: - Indicates a successful call. diff --git a/docs/detections/api/lists/api-find-list-containers.asciidoc b/docs/detections/api/lists/api-find-list-containers.asciidoc deleted file mode 100644 index 015aac113c..0000000000 --- a/docs/detections/api/lists/api-find-list-containers.asciidoc +++ /dev/null @@ -1,92 +0,0 @@ -[[lists-api-find-list-containers]] -=== Find list containers - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-lists-api[lists APIs]. --- - -Retrieves a paginated subset of list containers. By default, the first page is -returned with 20 results per page. - -==== Request URL - -`GET :/api/lists/_find` - -===== URL query parameters - -All parameters are optional: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description - -|`page` |Integer |The page number to return. - -|`per_page` |Integer |The number of list containers to return per page. - -|`sort_field` |String |Determines which field is used to sort the results. - -|`sort_order` |String |Determines the sort order, which can be `desc` or `asc`. - -|`cursor` |String |Returns the containers that come after the last container -returned in the previous call (use the `cursor` value returned in the previous -call). This parameter uses the `tie_breaker_id` field to ensure all containers -are sorted and returned correctly. -See {ref}/search-request-body.html#request-body-search-search-after[Search After] for more information. - -|`filter` |String a|Filters the returned results according to the value of the -specified field, using the `:` syntax, where -`` can be: - -* `name` -* `type` -* `created_by` -* `updated_by` - -|============================================== - -===== Example request - -Retrieves the first two `keyword` list containers, sorted by `name` in -descending order: - -[source,console] --------------------------------------------------- -GET api/lists/_find?filter=type:keyword&page=1&per_page=2&sort_field=name&sort_order=desc --------------------------------------------------- -// KIBANA - -==== Response code - -`200`:: - Indicates a successful call. - -==== Response payload - -[source,json] --------------------------------------------------- -{ - "cursor": "WzIwLFsiMTk1ZjU0ZmItMjQ0ZC00ZjlhLTlhNWItZTcyODkwMTM0N2UwIl1d", - "data": [ - { - "_version": "WzcsMV0=", - "id": "internal-ip-excludes", - "created_at": "2020-08-11T10:38:51.087Z", - "created_by": "elastic", - "description": "Contains list items that exclude internal IP addresses from detection rule matches.", - "immutable": false, - "name": "Trusted internal IP addresses", - "tie_breaker_id": "195f54fb-244d-4f9a-9a5b-e728901347e0", - "type": "ip", - "updated_at": "2020-08-11T10:42:30.205Z", - "updated_by": "elastic", - "version": 1 - } - ], - "page": 1, - "per_page": 20, - "total": 1 -} --------------------------------------------------- diff --git a/docs/detections/api/lists/api-find-list-items.asciidoc b/docs/detections/api/lists/api-find-list-items.asciidoc deleted file mode 100644 index c848b0bb34..0000000000 --- a/docs/detections/api/lists/api-find-list-items.asciidoc +++ /dev/null @@ -1,105 +0,0 @@ -[[lists-api-find-list-items]] -=== Find list items - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-lists-api[lists APIs]. --- - -Retrieves a paginated subset of list items in the specified container. By -default, the first page is returned with 20 results per page. - -==== Request URL - -`GET :/api/lists/items/_find` - -===== URL query parameters - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`list_id` |String |ID of the <>. |Yes - -|`page` |Integer |The page number to return. |No - -|`per_page` |Integer |The number of items to return per page. |No - -|`sort_field` |String |Determines which field is used to sort the results. |No - -|`sort_order` |String |Determines the sort order, which can be `desc` or `asc`. -|No -|`cursor` |String |Returns the items that come after the last item -returned in the previous call (use the `cursor` value returned in the previous -call). This parameter uses the `tie_breaker_id` field to ensure all items -are sorted and returned correctly. -See {ref}/search-request-body.html#request-body-search-search-after[Search After] for more information. |No - -|============================================== - -===== Example request - -Retrieves list items in the `external-ip-excludes` list container: - -[source,console] --------------------------------------------------- -GET api/lists/items/_find?list_id=external-ip-excludes --------------------------------------------------- -// KIBANA - -==== Response code - -`200`:: - Indicates a successful call. - -==== Response payload - -[source,json] --------------------------------------------------- -{ - "cursor": "WzIwLFsiZmFjZmZmOTQtNzIzZS00YmQ0LTk4ZTUtNzI2OGJjNTA3NWNmIl1d", - "data": [ - { - "_version": "WzgsMV0=", - "created_at": "2020-08-11T11:22:13.670Z", - "created_by": "elastic", - "id": "bpdB3XMBx7pemMHopQ6M", - "list_id": "internal-ip-excludes-meta", - "tie_breaker_id": "17d3befb-dc22-4b3c-a286-b5504c4fbeeb", - "type": "ip", - "updated_at": "2020-08-11T11:22:13.670Z", - "updated_by": "elastic", - "value": "127.0.0.6" - }, - { - "_version": "WzMsMV0=", - "created_at": "2020-08-11T11:22:13.669Z", - "created_by": "elastic", - "id": "aZdB3XMBx7pemMHopQ6L", - "list_id": "internal-ip-excludes-meta", - "tie_breaker_id": "26115356-c2c2-4f1c-a4ed-19b81191775a", - "type": "ip", - "updated_at": "2020-08-11T11:22:13.669Z", - "updated_by": "elastic", - "value": "127.0.0.1" - }, - ... - { - "_version": "WzksMV0=", - "created_at": "2020-08-11T11:22:13.670Z", - "created_by": "elastic", - "id": "b5dB3XMBx7pemMHopQ6M", - "list_id": "internal-ip-excludes-meta", - "tie_breaker_id": "facfff94-723e-4bd4-98e5-7268bc5075cf", - "type": "ip", - "updated_at": "2020-08-11T11:22:13.670Z", - "updated_by": "elastic", - "value": "127.0.0.7" - } - ], - "page": 1, - "per_page": 20, - "total": 11 -} --------------------------------------------------- diff --git a/docs/detections/api/lists/api-get-list-containers.asciidoc b/docs/detections/api/lists/api-get-list-containers.asciidoc deleted file mode 100644 index 3cf6e5eb4f..0000000000 --- a/docs/detections/api/lists/api-get-list-containers.asciidoc +++ /dev/null @@ -1,52 +0,0 @@ -[[lists-api-get-container]] -=== Get list container - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-lists-api[lists APIs]. --- - -Retrieves a list container using its `id` field. - -==== Request URL - -`GET :/api/lists` - -===== URL query parameters - -The URL query must include the list container's `id`: - -`id` - `GET /api/lists?id=` - -===== Example request - -Retrieves the list container with a `id` of `internal-ip-excludes`: - -[source,console] --------------------------------------------------- -GET api/lists?id=internal-ip-excludes --------------------------------------------------- -// KIBANA - -==== Response code - -`200`:: - Indicates a successful call. - -==== Response payload - -[source,json] --------------------------------------------------- -{ - "id": "internal-ip-excludes", - "created_at": "2020-07-07T04:09:55.028Z", - "created_by": "Threat Hunter", - "description": "Contains list items that exclude internal IP addresses from detection rules.", - "name": "Exclude internal IP addresses", - "tie_breaker_id": "b123ab0e-d7c0-4ee5-9630-63a38641aa0c", - "type": "ip", - "updated_at": "2020-07-07T04:09:55.028Z", - "updated_by": "Threat Hunter" -} --------------------------------------------------- diff --git a/docs/detections/api/lists/api-get-list-items.asciidoc b/docs/detections/api/lists/api-get-list-items.asciidoc deleted file mode 100644 index fadf97363a..0000000000 --- a/docs/detections/api/lists/api-get-list-items.asciidoc +++ /dev/null @@ -1,106 +0,0 @@ -[[lists-api-get-item]] -=== Get list item - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-lists-api[lists APIs]. --- - -Retrieves list items using its `id`, or its `list_id` and `value` fields. - -IMPORTANT: For `ip` and `ip_range` list containers, you can retrieve up to -10,000 list items. - -==== Request URL - -`GET :/api/lists/items` - -===== URL query parameters - -The URL query must include one of the following: - -* `id` - `GET /api/lists/items?id=` -* `list_id` and `value` - `GET /api/lists/items?list_id=&value=` - -===== Example requests - -Retrieves the list item with an `id` of `internal-ip-address`: - -[source,console] --------------------------------------------------- -GET api/lists/items?id=internal-ip-excludes --------------------------------------------------- -// KIBANA - -Retrieves the list item in the `internal-ip-excludes` container, with a `value` -of `10.0.0.1`: - -[source,console] --------------------------------------------------- -GET api/lists/items?list_id=internal-ip-excludes&value=10.0.0.1 --------------------------------------------------- -// KIBANA - -Retrieves list items from an `ip` container using CIDR notation: - -[source,console] --------------------------------------------------- -GET api/lists/items?list_id=internal-ip-excludes&value=127.0.0.0/30 --------------------------------------------------- -// KIBANA - -Retrieves list items from an `ip_range` container that include the specified IP -address: - -[source,console] --------------------------------------------------- -GET api/lists/items?list_id=internal-ip-ranges&value=192.168.1.14 --------------------------------------------------- -// KIBANA - -==== Response code - -`200`:: - Indicates a successful call. - -==== Response payload - -[source,json] --------------------------------------------------- -[ - { - "created_at": "2020-08-11T11:22:13.669Z", - "created_by": "elastic", - "id": "aZdB3XMBx7pemMHopQ6L", - "list_id": "internal-ip-excludes", - "tie_breaker_id": "26115356-c2c2-4f1c-a4ed-19b81191775a", - "type": "ip", - "updated_at": "2020-08-11T11:22:13.669Z", - "updated_by": "elastic", - "value": "127.0.0.1" - }, - { - "created_at": "2020-08-11T11:22:13.669Z", - "created_by": "elastic", - "id": "apdB3XMBx7pemMHopQ6L", - "list_id": "internal-ip-excludes", - "tie_breaker_id": "fa247f45-bf8b-48bc-b89d-5191cba096e6", - "type": "ip", - "updated_at": "2020-08-11T11:22:13.669Z", - "updated_by": "elastic", - "value": "127.0.0.2" - }, - { - "created_at": "2020-08-11T11:22:13.670Z", - "created_by": "elastic", - "id": "a5dB3XMBx7pemMHopQ6L", - "list_id": "internal-ip-excludes", - "tie_breaker_id": "60edc3e4-9a79-4bff-b7dc-096b052797f8", - "type": "ip", - "updated_at": "2020-08-11T11:22:13.670Z", - "updated_by": "elastic", - "value": "127.0.0.3" - } -] --------------------------------------------------- diff --git a/docs/detections/api/lists/api-import-list-items.asciidoc b/docs/detections/api/lists/api-import-list-items.asciidoc deleted file mode 100644 index 843b828bfe..0000000000 --- a/docs/detections/api/lists/api-import-list-items.asciidoc +++ /dev/null @@ -1,98 +0,0 @@ -[[lists-api-import-list-items]] -=== Import list items - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-lists-api[lists APIs]. --- - -Imports a list of items from a `.txt` or `.csv` file. The maximum file size is 9 million bytes. - -You can import items to a new or existing -<>. - -==== Request URL - -`POST :/api/lists/items/_import` - -The request must include: - -* The `Content-Type: multipart/form-data` HTTP header. -* A link to the file containing the list items. - -For example, using cURL: - -[source,console] --------------------------------------------------- -curl -X POST ":/api/lists/items/_import" --u : -H 'kbn-xsrf: true' --H 'Content-Type: multipart/form-data' ---form "file=@" <1> --------------------------------------------------- -<1> The relative link to the file containing the list items. - -===== URL query parameters - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`list_id` |String |ID of the <>. -|Required when importing to an existing container. -|`type` |String |The datatype of excludes the list container holds, which can -be either `ip` or `keyword`. |Required when importing to a new container. -|{ref}/docs-refresh.html[`refresh`] |String a| Determines when changes made by the request become visible to search. Defaults to `wait_for`. Valid values are: - -* `true` -* `false` -* `wait_for` - -|Optional. -|============================================== - -===== Example requests - -Adds the IP addresses in the `internal-IPs.txt` to the `internal-ip-excludes` -list container: - -[source,console] --------------------------------------------------- -curl -X POST "api/lists/items/_import?list_id=internal-ip-excludes" --H 'kbn-xsrf: true' -H 'Content-Type: multipart/form-data' ---form "file=@internal-IPs.txt" --------------------------------------------------- - -Adds the IP addresses in the `internal-IPs.txt` to a new list container: - -[source,console] --------------------------------------------------- -curl -X POST "api/lists/items/_import?type=ip" --H 'kbn-xsrf: true' -H 'Content-Type: multipart/form-data' ---form "file=@internal-IPs.txt" --------------------------------------------------- - -==== Response code - -`200`:: - Indicates a successful call. - -==== Response payload - -[source,json] --------------------------------------------------- -{ - "_version": "WzcsMV0=", - "id": "internal-ip-excludes", - "created_at": "2020-08-11T10:38:51.087Z", - "created_by": "elastic", - "description": "Contains list items that exclude internal IP addresses from detection rule matches.", - "immutable": false, - "name": "Trusted internal IP addresses", - "tie_breaker_id": "195f54fb-244d-4f9a-9a5b-e728901347e0", - "type": "ip", - "updated_at": "2020-08-11T10:42:30.205Z", - "updated_by": "elastic", - "version": 1 -} --------------------------------------------------- diff --git a/docs/detections/api/lists/api-update-list-container.asciidoc b/docs/detections/api/lists/api-update-list-container.asciidoc deleted file mode 100644 index abf5b2ad76..0000000000 --- a/docs/detections/api/lists/api-update-list-container.asciidoc +++ /dev/null @@ -1,93 +0,0 @@ -[[lists-api-update-container]] -=== Update list container - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-lists-api[lists APIs]. --- - -Updates an existing list container. - -You can use `PUT` or `PATCH` methods to update list containers, where: - -* `PUT` replaces the original container and deletes fields that are not -specified. -* `PATCH` updates the specified fields. - -==== Request URL - -`PUT :/api/lists` - -`PATCH :/api/lists` - -==== Request body - -A JSON object with: - -* The `id` of the list container you want to update. -* The fields you want to modify. - -IMPORTANT: If you call `PUT` to update a rule, all unspecified fields are -deleted. You cannot modify the `id` and `type` fields. - -For `PATCH` calls, any of the fields can be modified, whereas for `PUT` calls, -some fields are required. - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required (`PUT` calls) - -|`description` |String |Describes the list container. |Yes -|`meta` |Object |Placeholder for metadata about the list container. |No -|`name` |String |The list container's name. |Yes -|`_version` |String |Base-64 encoded value of `if_seq_no` and `if_primary_term` -parameters, used to prevent update conflicts (see -{ref}/optimistic-concurrency-control.html[Optimistic concurrency control]). |No - -|============================================== - - -===== Example request - -Updates the `name` field: - -[source,console] --------------------------------------------------- -PATCH api/lists -{ - "id": "internal-ip-excludes", - "name": "Trusted internal IP addresses", - "_version": "WzYsMV0=" -} --------------------------------------------------- -// KIBANA - -==== Response code - -`200`:: - Indicates a successful call. - -==== Response payload - -The updated object, including the time it was updated. - -Example response: - -[source,json] --------------------------------------------------- -{ - "_version": "WzcsMV0=", - "created_at": "2020-08-11T10:38:51.087Z", - "created_by": "elastic", - "description": "Contains list items that exclude internal IP addresses from detection rule matches.", - "id": "internal-ip-excludes-meta", - "immutable": false, - "name": "Trusted internal IP addresses", - "tie_breaker_id": "195f54fb-244d-4f9a-9a5b-e728901347e0", - "type": "ip", - "updated_at": "2020-08-11T10:42:30.205Z", - "updated_by": "elastic", - "version": 2 -} --------------------------------------------------- diff --git a/docs/detections/api/lists/api-update-list-item.asciidoc b/docs/detections/api/lists/api-update-list-item.asciidoc deleted file mode 100644 index 6eb768283b..0000000000 --- a/docs/detections/api/lists/api-update-list-item.asciidoc +++ /dev/null @@ -1,98 +0,0 @@ -[[lists-api-update-item]] -=== Update list item - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-lists-api[lists APIs]. --- - -Updates an existing list item. - -You can use `PUT` or `PATCH` methods to update list items, where: - -* `PUT` replaces the original items and deletes fields that are not -specified. -* `PATCH` updates the specified fields. - -==== Request URL - -`PUT :/api/lists/items` - -`PATCH :/api/lists/items` - -==== Request body - -A JSON object with: - -* The `id` of the list item you want to update. -* The fields you want to modify. - -IMPORTANT: If you call `PUT` to update a rule, all unspecified fields are -deleted. You cannot modify the `list_id` and `id` fields. - -For `PATCH` calls, any of the fields can be modified, whereas for `PUT` calls, -some fields are required. - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required (`PUT` calls) - -|`meta` |Object |Placeholder for metadata about the list item. |No -|`value` |String |The value used to evaluate exceptions. For information on how -list item exceptions are evaluated, see -{api-kibana}/operation/operation-createexceptionlistitem[Create an exception list item]. |Yes -|`_version` |String |Base-64 encoded value of `if_seq_no` and `if_primary_term` -parameters, used to prevent update conflicts (see -{ref}/optimistic-concurrency-control.html[Optimistic concurrency control]). |No -|{ref}/docs-refresh.html[`refresh`] |String a| Determines when changes made by the request become visible to search. Defaults to `false`. Valid values are: - -* `true` -* `false` - -|No - -|============================================== - - -===== Example request - -Updates the `value` field: - -[source,console] --------------------------------------------------- -PATCH api/lists/items -{ - "id": "internal-ip-1", - "value": "10.0.0.17", - "_version": "WzEsMV0=" -} --------------------------------------------------- -// KIBANA - -==== Response code - -`200`:: - Indicates a successful call. - -==== Response payload - -The updated object, including the time it was updated. - -Example response: - -[source,json] --------------------------------------------------- -{ - "_version": "WzIsMV0=", - "created_at": "2020-08-11T10:54:46.080Z", - "created_by": "elastic", - "id": "internal-ip-1", - "list_id": "internal-ip-excludes", - "tie_breaker_id": "ed3f9d84-cd85-4122-b93d-07d1de4fd8bb", - "type": "ip", - "updated_at": "2020-08-11T11:00:12.202Z", - "updated_by": "elastic", - "value": "10.0.0.17" -} --------------------------------------------------- diff --git a/docs/detections/api/lists/lists-api-overview.asciidoc b/docs/detections/api/lists/lists-api-overview.asciidoc deleted file mode 100644 index cbc8847564..0000000000 --- a/docs/detections/api/lists/lists-api-overview.asciidoc +++ /dev/null @@ -1,66 +0,0 @@ -[[lists-api-overview]] -== Lists API - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-lists-api[lists APIs]. --- - -Lists can be used with detection rule {api-kibana}/group/endpoint-security-exceptions-api[exceptions] -to define values that prevent a rule from generating alerts. - -Lists are made up of: - -* *List containers*: A container for values of the same {es} -{ref}/mapping-types.html[data type]. The following data types can be used: - -** `boolean` -** `byte` -** `date` -** `date_nanos` -** `date_range` -** `double` -** `double_range` -** `float` -** `float_range` -** `half_float` -** `integer` -** `integer_range` -** `ip` -** `ip_range` -** `keyword` -** `long` -** `long_range` -** `short` -** `text` - -* *List items*: The values used to determine whether the exception prevents an -alert from being generated. - -All list items in the same list container must be of the same data type, and -each item defines a single value. For example, an IP list container, named -`internal-ip-addresses-southport`, contains five items, where each item defines -one internal IP address: - -. `192.168.1.1` -. `192.168.1.3` -. `192.168.1.18` -. `192.168.1.12` -. `192.168.1.7` - -To use these IP addresses as values for defining rule exceptions, use the Exceptions API to {api-kibana}/operation/operation-createexceptionlistitem[create an exception item] that references the -`internal-ip-addresses-southport` list. - -NOTE: Lists cannot be added directly to rules, nor do they define the operators -used to determine when exceptions are applied (`is in list`, `is not in list`). -Use an {api-kibana}/operation/operation-createexceptionlistitem[exception item] to define the -operator and associate it with an {api-kibana}/operation/operation/operation-createexceptionlist[exception container]. -You can then add the exception container to a rule's `exceptions_list` object. - -[float] -=== Lists requirements - -Before you can start using lists, you must create the `.lists` and `.items` data streams for the relevant {kib} space. To learn how to do this, go to {api-kibana}/operation/operation-createlistindex[Create list data streams]. - -Once these data streams are created, your role needs privileges to manage rules. Refer to <> for a complete list of requirements. \ No newline at end of file diff --git a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc index 6b98ba9bd2..577509167e 100644 --- a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc +++ b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc @@ -6,7 +6,7 @@ A default exception list contains exceptions that are associated with a single r If a default exception list doesn't exist for a rule, one is automatically created when you try to add an exception to it. -TIP: For more information about creating exceptions that are used by multiple rules, refer to {api-kibana}/operation/operation-createexceptionlistitem[Create an exception list item]. For more information about creating exception items from a list, such as a list of IP addresses or hosts names, refer to <>. +TIP: For more information about creating exceptions that are used by multiple rules, refer to {api-kibana}/operation/operation-createexceptionlistitem[Create an exception list item]. For more information about creating exception items from a list, such as a list of IP addresses or hosts names, refer to {api-kibana}/group/endpoint-security-lists-api[Lists API]. ==== Request URL @@ -119,8 +119,7 @@ a|Field value or values: |============================================== -IMPORTANT: When you use <> -(`"type": "list"`), you cannot use other types in the `entries` array (`match`, +IMPORTANT: When you use {api-kibana}/operation/operation-createlist[list containers] (`"type": "list"`), you cannot use other types in the `entries` array (`match`, `match_any`, `exists`, or `nested`). For endpoint exceptions, you cannot create exception items based on excluded diff --git a/docs/siem-apis.asciidoc b/docs/siem-apis.asciidoc index 5c7b5d9d94..a46a879f82 100644 --- a/docs/siem-apis.asciidoc +++ b/docs/siem-apis.asciidoc @@ -15,7 +15,7 @@ NOTE: Console supports sending requests to {kib} APIs. Prepend any {kib} API end * <>: Manage detection rules, rule exceptions for individual rules, and alerts * {api-kibana}/group/endpoint-security-exceptions-api[Exceptions API]: Create and manage rule exceptions -* <>: Create source event value lists for use with rule exceptions +* {api-kibana}/group/endpoint-security-lists-api[Lists API]: Create source event value lists for use with rule exceptions * {api-kibana}/group/endpoint-security-timeline-api[Timeline API]: Import and export timelines * {api-kibana}/group/endpoint-cases[Cases API]: Open and manage cases * <>: Interact with and manage Elastic AI Assistant @@ -95,8 +95,6 @@ how to work with and disable the random path component. include::detections/api/det-api-index.asciidoc[] -include::detections/api/lists-api-index.asciidoc[] - include::detections/api/signals-migration-api.asciidoc[] include::AI-for-security/api/ai-for-security-index.asciidoc[]