From 878eb64d8955420d5d82d2e3efdc439d8dee8f4f Mon Sep 17 00:00:00 2001 From: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Mon, 24 May 2021 12:38:52 -0400 Subject: [PATCH] [DOCS] Add Dev Tools warning to Security App API subpages (#686) * Added note about dev tool. * Added missing space after note. * Added missing spaces before note. * Adding note to remaining topics. * Added note to other three topics. * Inserting note to newly added Timeline topics. --- .../cases-actions-api-intro.asciidoc | 8 ++++ .../case-api-update-connector.asciidoc | 13 ++--- .../cases-api/cases-api-add-comment.asciidoc | 8 ++-- .../cases-api-assign-connector.asciidoc | 16 ++++--- .../cases-api/cases-api-associate-sn.asciidoc | 8 ++-- .../api/cases-api/cases-api-create.asciidoc | 6 ++- .../cases-api-delete-all-comments.asciidoc | 6 ++- .../cases-api/cases-api-delete-case.asciidoc | 6 ++- .../cases-api-delete-comment.asciidoc | 6 ++- .../cases-api/cases-api-find-cases.asciidoc | 12 +++-- .../cases-api-find-connectors.asciidoc | 8 ++-- .../cases-api-get-case-activity.asciidoc | 8 ++-- .../cases-api-get-case-comments.asciidoc | 8 ++-- .../api/cases-api/cases-api-get-case.asciidoc | 10 ++-- .../cases-api/cases-api-get-comment.asciidoc | 6 ++- .../cases-api-get-connector.asciidoc | 15 +++++- .../cases-api-get-reporters.asciidoc | 8 ++-- .../cases-api/cases-api-get-status.asciidoc | 8 ++-- .../api/cases-api/cases-api-get-tags.asciidoc | 8 ++-- .../api/cases-api/cases-api-push.asciidoc | 10 ++-- .../cases-api-update-comment.asciidoc | 6 ++- .../api/cases-api/cases-api-update.asciidoc | 8 ++-- docs/cases/api/cases-api/cases-api.asciidoc | 2 + .../api-create-exception-container.asciidoc | 10 ++-- .../api-create-exception-item.asciidoc | 2 + .../api-delete-exception-container.asciidoc | 6 ++- .../api-delete-exception-item.asciidoc | 6 ++- .../api-find-exception-containers.asciidoc | 8 ++-- .../api-find-exception-items.asciidoc | 6 ++- .../api-get-exception-containers.asciidoc | 8 ++-- .../api-get-exception-items.asciidoc | 8 ++-- .../api-update-exception-container.asciidoc | 10 ++-- .../api-update-exception-item.asciidoc | 12 +++-- .../exceptions-api-overview.asciidoc | 4 +- .../lists-index-api-overview.asciidoc | 12 +++-- .../lists/api-create-list-container.asciidoc | 12 +++-- .../api/lists/api-create-list-item.asciidoc | 8 ++-- .../lists/api-delete-list-container.asciidoc | 6 ++- .../api/lists/api-delete-list-item.asciidoc | 6 ++- .../api/lists/api-export-list-item.asciidoc | 8 ++-- .../lists/api-find-list-containers.asciidoc | 8 ++-- .../api/lists/api-find-list-items.asciidoc | 6 ++- .../lists/api-get-list-containers.asciidoc | 8 ++-- .../api/lists/api-get-list-items.asciidoc | 8 ++-- .../api/lists/api-import-list-items.asciidoc | 6 ++- .../lists/api-update-list-container.asciidoc | 10 ++-- .../api/lists/api-update-list-item.asciidoc | 10 ++-- .../api/lists/lists-api-overview.asciidoc | 9 ++-- .../api/rules/index-api-overview.asciidoc | 14 +++--- .../rules/privileges-api-overview.asciidoc | 10 ++-- .../api/rules/rules-api-bulk-actions.asciidoc | 20 ++++---- .../api/rules/rules-api-delete.asciidoc | 6 ++- .../api/rules/rules-api-export.asciidoc | 14 +++--- .../api/rules/rules-api-find.asciidoc | 16 ++++--- .../api/rules/rules-api-get.asciidoc | 8 ++-- .../api/rules/rules-api-import.asciidoc | 10 ++-- .../api/rules/rules-api-overview.asciidoc | 2 + .../api/rules/rules-api-prebuilt.asciidoc | 12 +++-- .../api/rules/rules-api-update.asciidoc | 48 ++++++++++--------- .../api/rules/signals-api-overview.asciidoc | 24 +++++----- .../api/rules/tags-api-overview.asciidoc | 6 ++- .../api/signals-migration-api.asciidoc | 2 + docs/events/api/timeline-api-create.asciidoc | 2 + docs/events/api/timeline-api-delete.asciidoc | 4 +- docs/events/api/timeline-api-get.asciidoc | 8 +++- docs/events/api/timeline-api-import.asciidoc | 6 ++- .../events/api/timeline-api-overview.asciidoc | 3 +- docs/events/api/timeline-api-update.asciidoc | 6 ++- 68 files changed, 383 insertions(+), 229 deletions(-) diff --git a/docs/cases/api/actions-api/cases-actions-api-intro.asciidoc b/docs/cases/api/actions-api/cases-actions-api-intro.asciidoc index bb78c1bd72..a85b621e9c 100644 --- a/docs/cases/api/actions-api/cases-actions-api-intro.asciidoc +++ b/docs/cases/api/actions-api/cases-actions-api-intro.asciidoc @@ -8,6 +8,8 @@ You can push {es-sec} cases to these third-party systems: * {jira} (including Jira Service Desk) * {ibm-r} +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + To push cases, you need to create a connector using the {kib} Actions API, which stores the information required to interface with the external system. @@ -35,6 +37,8 @@ required for updating the the {es-sec} case. Creates a connector, which can then be used to open and update cases in external systems. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `POST :/api/actions/action` @@ -183,6 +187,8 @@ A JSON object with a connector `id` that is required to push cases to {sn}. Updates a connector. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `PUT :/api/actions/action/` @@ -288,6 +294,8 @@ The updated JSON connector object. Creates a new or updates an existing external incident from a {es-sec} case. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + NOTE: You can only send cases to external systems after you have <> a connector. After you have sent the case to an external system, you must call <> to update diff --git a/docs/cases/api/cases-api/case-api-update-connector.asciidoc b/docs/cases/api/cases-api/case-api-update-connector.asciidoc index dc0a514680..b6696e4100 100644 --- a/docs/cases/api/cases-api/case-api-update-connector.asciidoc +++ b/docs/cases/api/cases-api/case-api-update-connector.asciidoc @@ -3,6 +3,8 @@ Updates the connector's case closure settings. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + Connectors are used to interface with external systems. You can only call this method after you have created a connector (see <>). After a connector has been created and assigned, call <> to @@ -42,7 +44,7 @@ are pushed. |`id` |String |The ID of the connector you want to use for sending cases to external systems. |Yes |`name` |String a|The connector name. |Yes -|`type` |String a|The type of the connector. +|`type` |String a|The type of the connector. Must be one of these: @@ -80,13 +82,13 @@ NOTE: Fields can be set but are not being used by case configuration. You can se ===== Example request -Changes the connector's case closure option: +Changes the connector's case closure option: [source,sh] -------------------------------------------------- PATCH api/cases/configure { - "connector": { + "connector": { "id": "131d4448-abe0-4789-939d-8ef60680b498", "name": "My connector", "type": ".jira", @@ -100,7 +102,7 @@ PATCH api/cases/configure ==== Response code -`200`:: +`200`:: Indicates a successful call. ===== Example response @@ -108,7 +110,7 @@ PATCH api/cases/configure [source,json] -------------------------------------------------- { - "connector": { + "connector": { "id": "131d4448-abe0-4789-939d-8ef60680b498", "name": "My connector", "type": ".jira", @@ -131,4 +133,3 @@ PATCH api/cases/configure "version": "WzIwMywxXQ==" } -------------------------------------------------- - diff --git a/docs/cases/api/cases-api/cases-api-add-comment.asciidoc b/docs/cases/api/cases-api/cases-api-add-comment.asciidoc index cfed8a20af..5a37786acb 100644 --- a/docs/cases/api/cases-api/cases-api-add-comment.asciidoc +++ b/docs/cases/api/cases-api/cases-api-add-comment.asciidoc @@ -3,13 +3,15 @@ Adds a comment to an existing case. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `POST :/api/cases//comments` ===== URL parts -The URL must include the `case ID` of the case to which you are adding a +The URL must include the `case ID` of the case to which you are adding a comment. Call <> to retrieve case IDs. ==== Request body @@ -45,7 +47,7 @@ POST api/cases/293f1bc0-74f6-11ea-b83a-553aecdb28b6/comments ==== Response code -`200`:: +`200`:: Indicates a successful call. ==== Response payload @@ -102,4 +104,4 @@ comment, and the comment's ID, version, and creation time. "username": "moneypenny" } } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/cases/api/cases-api/cases-api-assign-connector.asciidoc b/docs/cases/api/cases-api/cases-api-assign-connector.asciidoc index 265c76f50d..54d865bdc5 100644 --- a/docs/cases/api/cases-api/cases-api-assign-connector.asciidoc +++ b/docs/cases/api/cases-api/cases-api-assign-connector.asciidoc @@ -3,6 +3,8 @@ Sets the default connector in the {es-sec-ui}. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + Connectors are used to interface with external systems. You can only call this method after you have created a connector (see <>). After a connector has been created and assigned, call <> to @@ -44,7 +46,7 @@ are pushed. |`id` |String |The ID of the connector you want to use for sending cases to external systems. |Yes |`name` |String a|The connector name. |Yes -|`type` |String a|The type of the connector. +|`type` |String a|The type of the connector. Must be one of these: @@ -85,7 +87,7 @@ NOTE: Fields can be set but are not being used by case configuration. You can se -------------------------------------------------- POST api/cases/configure { - "connector": { + "connector": { "id": "131d4448-abe0-4789-939d-8ef60680b498", "name": "Jira", "type": ".jira", @@ -97,15 +99,15 @@ POST api/cases/configure ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Example response [source,json] -------------------------------------------------- { - "connector": { + "connector": { "id": "131d4448-abe0-4789-939d-8ef60680b498", "name": "Jira", "type": ".jira", @@ -120,7 +122,7 @@ POST api/cases/configure }, "error": null, "mappings":[ - { + { "source":"title", <1> "target":"summary", "action_type": "overwrite" @@ -152,4 +154,4 @@ the {jira} `description` field is overwritten. <3> {es-sec} case `comments` fields are mapped to {jira} `comments` fields. When a {es-sec} `comments` field is updated and sent to {jira}, the updated -text is appended to the {jira} `comments` field. \ No newline at end of file +text is appended to the {jira} `comments` field. diff --git a/docs/cases/api/cases-api/cases-api-associate-sn.asciidoc b/docs/cases/api/cases-api/cases-api-associate-sn.asciidoc index d5c5a25a4b..054ef9fdf8 100644 --- a/docs/cases/api/cases-api/cases-api-associate-sn.asciidoc +++ b/docs/cases/api/cases-api/cases-api-associate-sn.asciidoc @@ -3,6 +3,8 @@ Adds the data returned from an external system to the specified case. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + After sending a new or updated case to an external system using the <>, you must associate the external system's returned object with the case in {es-sec}. @@ -53,9 +55,9 @@ POST api/cases/718265d0-733a-11ea-a0b2-c51ea50a58e2/_push ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload The updated JSON case object. @@ -110,4 +112,4 @@ The updated JSON case object. "syncAlerts": true }, } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/cases/api/cases-api/cases-api-create.asciidoc b/docs/cases/api/cases-api/cases-api-create.asciidoc index 1b64ce4fce..6af9dd8d89 100644 --- a/docs/cases/api/cases-api/cases-api-create.asciidoc +++ b/docs/cases/api/cases-api/cases-api-create.asciidoc @@ -3,6 +3,8 @@ Creates a new case. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `POST :/api/cases` @@ -36,7 +38,7 @@ settings. |Yes used for pushing case updates to external systems (returned when calling <>). |Yes |`name` |String a|The connector name. |Yes -|`type` |String a|The type of the connector. +|`type` |String a|The type of the connector. Must be one of these: @@ -107,7 +109,7 @@ POST api/cases ==== Response code -`200`:: +`200`:: Indicates a successful call. ==== Response payload diff --git a/docs/cases/api/cases-api/cases-api-delete-all-comments.asciidoc b/docs/cases/api/cases-api/cases-api-delete-all-comments.asciidoc index f174af7027..7b3c338858 100644 --- a/docs/cases/api/cases-api/cases-api-delete-all-comments.asciidoc +++ b/docs/cases/api/cases-api/cases-api-delete-all-comments.asciidoc @@ -3,6 +3,8 @@ Deletes all comments from the specified case. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `DELETE :/api/cases//comments` @@ -24,5 +26,5 @@ DELETE api/cases/a18b38a0-71b0-11ea-a0b2-c51ea50a58e2/comments ==== Response code -`204`:: - Indicates a successful call. \ No newline at end of file +`204`:: + Indicates a successful call. diff --git a/docs/cases/api/cases-api/cases-api-delete-case.asciidoc b/docs/cases/api/cases-api/cases-api-delete-case.asciidoc index 908cfcb02f..e1a9e29e7f 100644 --- a/docs/cases/api/cases-api/cases-api-delete-case.asciidoc +++ b/docs/cases/api/cases-api/cases-api-delete-case.asciidoc @@ -3,6 +3,8 @@ Deletes the specified cases and all associated comments. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `DELETE :/api/cases?ids=["",""]` @@ -29,5 +31,5 @@ DELETE api/cases?ids=%5B%222e3a54f0-6754-11ea-a1c2-e3a8bc9f7aca%22%2C%2240b9a450 ==== Response code -`204`:: - Indicates a successful call. \ No newline at end of file +`204`:: + Indicates a successful call. diff --git a/docs/cases/api/cases-api/cases-api-delete-comment.asciidoc b/docs/cases/api/cases-api/cases-api-delete-comment.asciidoc index 7c63e76024..703eee1a5a 100644 --- a/docs/cases/api/cases-api/cases-api-delete-comment.asciidoc +++ b/docs/cases/api/cases-api/cases-api-delete-comment.asciidoc @@ -3,6 +3,8 @@ Deletes the specified comment. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `DELETE :/api/cases//comments/` @@ -29,5 +31,5 @@ DELETE api/cases/a18b38a0-71b0-11ea-a0b2-c51ea50a58e2/comments/71ec1870-725b-11e ==== Response code -`204`:: - Indicates a successful call. \ No newline at end of file +`204`:: + Indicates a successful call. diff --git a/docs/cases/api/cases-api/cases-api-find-cases.asciidoc b/docs/cases/api/cases-api/cases-api-find-cases.asciidoc index 7623093946..f0e156d7bb 100644 --- a/docs/cases/api/cases-api/cases-api-find-cases.asciidoc +++ b/docs/cases/api/cases-api/cases-api-find-cases.asciidoc @@ -1,9 +1,11 @@ [[cases-api-find-cases]] === Find cases -Retrieves a paginated subset of cases. By default, the first page is returned +Retrieves a paginated subset of cases. By default, the first page is returned with 20 results per page. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + NOTE: Cases are saved objects. See {kibana-ref}/saved-objects-api-find.html[Find objects API] for more query parameters. @@ -44,7 +46,7 @@ query. ===== Example request -Retrieves the first five cases with the `phishing` tag, in ascending order by +Retrieves the first five cases with the `phishing` tag, in ascending order by last update time. [source,sh] @@ -55,7 +57,7 @@ GET api/cases/_find?page=1&perPage=5&sortField=updatedAt&sortOrder=asc&tags=phis ==== Response code -`200`:: +`200`:: Indicates a successful call. ==== Response payload @@ -140,7 +142,7 @@ A JSON object listing the retrieved cases. } }, "settings": { - "syncAlerts": false + "syncAlerts": false }, "tags": [ "phishing", @@ -152,4 +154,4 @@ A JSON object listing the retrieved cases. "count_open_cases": 2, "count_closed_cases": 0 } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/cases/api/cases-api/cases-api-find-connectors.asciidoc b/docs/cases/api/cases-api/cases-api-find-connectors.asciidoc index 3a979f873c..9ff225b730 100644 --- a/docs/cases/api/cases-api/cases-api-find-connectors.asciidoc +++ b/docs/cases/api/cases-api/cases-api-find-connectors.asciidoc @@ -3,6 +3,8 @@ Retrieves a paginated subset of all connectors. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + NOTE: Only {sn}, {jira}, and {ibm-r} connectors are returned. For more information on connectors, see <>. @@ -20,9 +22,9 @@ GET api/cases/configure/connectors/_find ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload A JSON object describing the connectors and their settings. @@ -56,4 +58,4 @@ A JSON object describing the connectors and their settings. } ] } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/cases/api/cases-api/cases-api-get-case-activity.asciidoc b/docs/cases/api/cases-api/cases-api-get-case-activity.asciidoc index 3dce90ccca..b3ad6f60b3 100644 --- a/docs/cases/api/cases-api/cases-api-get-case-activity.asciidoc +++ b/docs/cases/api/cases-api/cases-api-get-case-activity.asciidoc @@ -3,13 +3,15 @@ Returns all user activity for the specified case. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/cases//user_actions` ===== URL parts -The URL must include the `case ID` of the case for which you are retrieving +The URL must include the `case ID` of the case for which you are retrieving activity. Call <> to retrieve case IDs. ===== Example request @@ -24,7 +26,7 @@ GET api/cases/a18b38a0-71b0-11ea-a0b2-c51ea50a58e2/user_actions ==== Response code -`200`:: +`200`:: Indicates a successful call. ==== Response payload @@ -144,4 +146,4 @@ A JSON array containing all user activity for the specified case. "comment_id":null } ] --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/cases/api/cases-api/cases-api-get-case-comments.asciidoc b/docs/cases/api/cases-api/cases-api-get-case-comments.asciidoc index 6caa43830d..7cd68ab6c6 100644 --- a/docs/cases/api/cases-api/cases-api-get-case-comments.asciidoc +++ b/docs/cases/api/cases-api/cases-api-get-case-comments.asciidoc @@ -3,13 +3,15 @@ Returns all comments for the specified case. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/cases//comments` ===== URL parts -The URL must include the `case ID` of the case for which you are retrieving +The URL must include the `case ID` of the case for which you are retrieving comments. Call <> to retrieve case IDs. ===== Example request @@ -24,7 +26,7 @@ GET api/cases/a18b38a0-71b0-11ea-a0b2-c51ea50a58e2/comments ==== Response code -`200`:: +`200`:: Indicates a successful call. ==== Response payload @@ -89,4 +91,4 @@ A JSON array containing all comments for the specified case. "updated_by": null } ] --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/cases/api/cases-api/cases-api-get-case.asciidoc b/docs/cases/api/cases-api/cases-api-get-case.asciidoc index 4d5c9ee7b4..4060dd3890 100644 --- a/docs/cases/api/cases-api/cases-api-get-case.asciidoc +++ b/docs/cases/api/cases-api/cases-api-get-case.asciidoc @@ -3,6 +3,8 @@ Returns the specified case. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/cases/` @@ -13,12 +15,12 @@ The URL must include the `case ID` of the case you are retrieving. Call <> to retrieve case IDs. ===== URL query parameters - + [width="100%",options="header"] |============================================== |Name |Type |Description |Required -|`includeComments` |Boolean |Determines whether case comments are +|`includeComments` |Boolean |Determines whether case comments are returned. |No, defaults to `true`. |============================================== @@ -34,7 +36,7 @@ GET api/cases/a18b38a0-71b0-11ea-a0b2-c51ea50a58e2?includeComments=false ==== Response code -`200`:: +`200`:: Indicates a successful call. ==== Response payload @@ -86,4 +88,4 @@ The requested case JSON object. "bubblegum" ] } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/cases/api/cases-api/cases-api-get-comment.asciidoc b/docs/cases/api/cases-api/cases-api-get-comment.asciidoc index 44981e76f9..eee99efb25 100644 --- a/docs/cases/api/cases-api/cases-api-get-comment.asciidoc +++ b/docs/cases/api/cases-api/cases-api-get-comment.asciidoc @@ -3,6 +3,8 @@ Gets the specified comment. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/cases//comments/` @@ -29,7 +31,7 @@ GET api/cases/a18b38a0-71b0-11ea-a0b2-c51ea50a58e2/comments/71ec1870-725b-11ea-a ==== Response code -`200`:: +`200`:: Indicates a successful call. ==== Response payload @@ -56,4 +58,4 @@ The requested comment JSON object. "updated_at": null, "updated_by": null } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/cases/api/cases-api/cases-api-get-connector.asciidoc b/docs/cases/api/cases-api/cases-api-get-connector.asciidoc index 9d5c7e8d21..f48ed5b076 100644 --- a/docs/cases/api/cases-api/cases-api-get-connector.asciidoc +++ b/docs/cases/api/cases-api/cases-api-get-connector.asciidoc @@ -3,6 +3,8 @@ Retrieves the connector currently used in the {es-sec-ui}. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + NOTE: For more information on connectors, see <>. ==== Request URL @@ -19,7 +21,7 @@ GET api/cases/configure ==== Response code -`200`:: +`200`:: Indicates a successful call. ===== Example response @@ -27,7 +29,16 @@ GET api/cases/configure [source,json] -------------------------------------------------- { +<<<<<<< HEAD "connector_id": "61787f53-4eee-4741-8df6-8fe84fa616f7", +======= + "connector": { + "id": "131d4448-abe0-4789-939d-8ef60680b498", + "name": "Jira", + "type": ".jira", + "fields": null, + }, +>>>>>>> c9137735... [DOCS] Add Dev Tools warning to Security App API subpages (#686) "closure_type": "close-by-user", "connector_name": "ServiceNow", "created_at": "2020-03-30T13:31:38.083Z", @@ -41,4 +52,4 @@ GET api/cases/configure "updated_by": null, "version": "WzE3NywxXQ==" } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/cases/api/cases-api/cases-api-get-reporters.asciidoc b/docs/cases/api/cases-api/cases-api-get-reporters.asciidoc index 660580a07e..31d96d69a6 100644 --- a/docs/cases/api/cases-api/cases-api-get-reporters.asciidoc +++ b/docs/cases/api/cases-api/cases-api-get-reporters.asciidoc @@ -3,6 +3,8 @@ Returns all case reporters (users who opened cases). +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/cases/reporters` @@ -17,9 +19,9 @@ GET api/cases/reporters ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ===== Example response [source,json] @@ -36,4 +38,4 @@ GET api/cases/reporters "username": "rhustler" } ] --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/cases/api/cases-api/cases-api-get-status.asciidoc b/docs/cases/api/cases-api/cases-api-get-status.asciidoc index 5a794bff7d..b9c6cbedfd 100644 --- a/docs/cases/api/cases-api/cases-api-get-status.asciidoc +++ b/docs/cases/api/cases-api/cases-api-get-status.asciidoc @@ -3,6 +3,8 @@ Returns the number of open and closed cases. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/cases/status` @@ -17,9 +19,9 @@ GET api/cases/status ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ===== Example response [source,json] @@ -29,4 +31,4 @@ GET api/cases/status "count_in_progress_cases": 50, "count_closed_cases": 1198, } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/cases/api/cases-api/cases-api-get-tags.asciidoc b/docs/cases/api/cases-api/cases-api-get-tags.asciidoc index 8ba4d8ac7c..7c16838e46 100644 --- a/docs/cases/api/cases-api/cases-api-get-tags.asciidoc +++ b/docs/cases/api/cases-api/cases-api-get-tags.asciidoc @@ -3,6 +3,8 @@ Aggregates and returns all unique tags from all cases. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/cases/tags` @@ -19,9 +21,9 @@ GET api/cases/tags ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ===== Example response [source,json] @@ -32,4 +34,4 @@ GET api/cases/tags "social engineering", "bubblegum" ] --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/cases/api/cases-api/cases-api-push.asciidoc b/docs/cases/api/cases-api/cases-api-push.asciidoc index ee38d9b104..8236ee1431 100644 --- a/docs/cases/api/cases-api/cases-api-push.asciidoc +++ b/docs/cases/api/cases-api/cases-api-push.asciidoc @@ -1,8 +1,10 @@ [[cases-api-push]] -=== Push case +=== Push case Push case to an external service. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `POST :/api/cases/configure/connectors//push` @@ -15,7 +17,7 @@ A JSON object with these fields: |============================================== |Name |Type |Description |Required -|`connector_type` |String a|The type of the connector. +|`connector_type` |String a|The type of the connector. Must be one of these: @@ -156,9 +158,9 @@ POST api/cases/configure/connectors/7349772f-421a-4de3-b8bb-2d9b22ccee30/push ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload A JSON object with the ID and the URL of the external incident. diff --git a/docs/cases/api/cases-api/cases-api-update-comment.asciidoc b/docs/cases/api/cases-api/cases-api-update-comment.asciidoc index 45dd6e9550..e536c265d1 100644 --- a/docs/cases/api/cases-api/cases-api-update-comment.asciidoc +++ b/docs/cases/api/cases-api/cases-api-update-comment.asciidoc @@ -3,6 +3,8 @@ Updates an existing comment. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `PATCH :/api/cases//comments` @@ -54,7 +56,7 @@ PATCH api/cases/293f1bc0-74f6-11ea-b83a-553aecdb28b6/comments ==== Response code -`200`:: +`200`:: Indicates a successful call. ==== Response payload @@ -115,4 +117,4 @@ comment, and the comment's ID, version, and update time. "username": "_007" } } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/cases/api/cases-api/cases-api-update.asciidoc b/docs/cases/api/cases-api/cases-api-update.asciidoc index 8f3b4aabbb..91b0da8dbe 100644 --- a/docs/cases/api/cases-api/cases-api-update.asciidoc +++ b/docs/cases/api/cases-api/cases-api-update.asciidoc @@ -3,6 +3,8 @@ Updates existing cases. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `PATCH :/api/cases` @@ -53,7 +55,7 @@ settings. |No used for pushing case updates to external systems (returned when calling <>). |Yes |`name` |String a|The connector name. |Yes -|`type` |String a|The type of the connector. +|`type` |String a|The type of the connector. Must be one of these: @@ -135,7 +137,7 @@ PATCH api/cases ==== Response code -`200`:: +`200`:: Indicates a successful call. ==== Response payload @@ -201,4 +203,4 @@ The updated case with a new `version` value. } } ] --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/cases/api/cases-api/cases-api.asciidoc b/docs/cases/api/cases-api/cases-api.asciidoc index a716d724a5..590f4c578b 100644 --- a/docs/cases/api/cases-api/cases-api.asciidoc +++ b/docs/cases/api/cases-api/cases-api.asciidoc @@ -5,6 +5,8 @@ You can create, manage, configure, and send cases to external systems with these APIs: +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + * Cases API: Used to open and manage security action items. * Actions API: Used to send cases to external systems. <> diff --git a/docs/detections/api/exceptions/api-create-exception-container.asciidoc b/docs/detections/api/exceptions/api-create-exception-container.asciidoc index 0743bf903e..c488d2d80d 100644 --- a/docs/detections/api/exceptions/api-create-exception-container.asciidoc +++ b/docs/detections/api/exceptions/api-create-exception-container.asciidoc @@ -3,6 +3,8 @@ Creates an exception container. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + An exception container groups <> and can be associated with rules. When an exception item's query evaluates to `true`, rules do *not* issue alerts even when the rule's other criteria are met. @@ -40,7 +42,7 @@ provided. |No, defaults to `single`. |`tags` |String[] |String array containing words and phrases to help categorize -exception containers. |No +exception containers. |No |`type` |String a|The type of exception, which must be one of these: * `detection`: Detection rule exception @@ -74,9 +76,9 @@ POST api/exception_lists ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload @@ -110,4 +112,4 @@ rules: <1> `id` <2> `list_id` <3> `namespace_type` -<4> `type` \ No newline at end of file +<4> `type` diff --git a/docs/detections/api/exceptions/api-create-exception-item.asciidoc b/docs/detections/api/exceptions/api-create-exception-item.asciidoc index 98aff029e3..5e82fb37ad 100644 --- a/docs/detections/api/exceptions/api-create-exception-item.asciidoc +++ b/docs/detections/api/exceptions/api-create-exception-item.asciidoc @@ -4,6 +4,8 @@ Creates an exception item and associates it with the specified <>. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + See <> for information about creating exception items from lists, such as a list of IP addresses or host names. diff --git a/docs/detections/api/exceptions/api-delete-exception-container.asciidoc b/docs/detections/api/exceptions/api-delete-exception-container.asciidoc index 248bf8c355..facde7b344 100644 --- a/docs/detections/api/exceptions/api-delete-exception-container.asciidoc +++ b/docs/detections/api/exceptions/api-delete-exception-container.asciidoc @@ -3,6 +3,8 @@ Deletes an exception container. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `DELETE :/api/exception_lists` @@ -27,5 +29,5 @@ DELETE api/exception_lists?list_id=linux-processes ==== Response code -`200`:: - Indicates a successful call. \ No newline at end of file +`200`:: + Indicates a successful call. diff --git a/docs/detections/api/exceptions/api-delete-exception-item.asciidoc b/docs/detections/api/exceptions/api-delete-exception-item.asciidoc index c119dcea3c..71326a4186 100644 --- a/docs/detections/api/exceptions/api-delete-exception-item.asciidoc +++ b/docs/detections/api/exceptions/api-delete-exception-item.asciidoc @@ -3,6 +3,8 @@ Deletes an exception item. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `DELETE :/api/exception_lists/items` @@ -26,5 +28,5 @@ DELETE api/exception_lists/items?item_id=external-IPs ==== Response code -`200`:: - Indicates a successful call. \ No newline at end of file +`200`:: + Indicates a successful call. diff --git a/docs/detections/api/exceptions/api-find-exception-containers.asciidoc b/docs/detections/api/exceptions/api-find-exception-containers.asciidoc index 602284a335..658fc265b6 100644 --- a/docs/detections/api/exceptions/api-find-exception-containers.asciidoc +++ b/docs/detections/api/exceptions/api-find-exception-containers.asciidoc @@ -4,6 +4,8 @@ Retrieves a paginated subset of exception containers. By default, the first page is returned with 20 results per page. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/exception_lists/_find` @@ -34,7 +36,7 @@ See {ref}/search-request-body.html#request-body-search-search-after[Search After associated with a {kib} space or available in all spaces (`agnostic` or `single`). -|`filter` |String a|Filters the returned results according to the value of the +|`filter` |String a|Filters the returned results according to the value of the specified field, using the `:` syntax, where `` can be: @@ -57,9 +59,9 @@ GET api/exception_lists/_find?page=1&per_page=2&sort_field=name&sort_order=desc ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload [source,json] diff --git a/docs/detections/api/exceptions/api-find-exception-items.asciidoc b/docs/detections/api/exceptions/api-find-exception-items.asciidoc index 1b5177dc67..573d2284b1 100644 --- a/docs/detections/api/exceptions/api-find-exception-items.asciidoc +++ b/docs/detections/api/exceptions/api-find-exception-items.asciidoc @@ -4,6 +4,8 @@ Retrieves a paginated subset of exception items in the specified container. By default, the first page is returned with 20 results per page. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/exception_lists/items/_find` @@ -45,9 +47,9 @@ GET api/exception_lists/items/_find?list_id=allowed-processes ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload [source,json] diff --git a/docs/detections/api/exceptions/api-get-exception-containers.asciidoc b/docs/detections/api/exceptions/api-get-exception-containers.asciidoc index d886ddbf17..139e823e13 100644 --- a/docs/detections/api/exceptions/api-get-exception-containers.asciidoc +++ b/docs/detections/api/exceptions/api-get-exception-containers.asciidoc @@ -3,6 +3,8 @@ Retrieves an exception container using its `id` or `list_id` field. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/exception_lists` @@ -26,9 +28,9 @@ GET api/exception_lists?list_id=internal-ip-excludes ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload [source,json] @@ -51,4 +53,4 @@ GET api/exception_lists?list_id=internal-ip-excludes "updated_at": "2020-07-14T08:24:23.050Z", "updated_by": "LiverpoolFC" } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/detections/api/exceptions/api-get-exception-items.asciidoc b/docs/detections/api/exceptions/api-get-exception-items.asciidoc index 71b6199836..e287146b22 100644 --- a/docs/detections/api/exceptions/api-get-exception-items.asciidoc +++ b/docs/detections/api/exceptions/api-get-exception-items.asciidoc @@ -3,6 +3,8 @@ Retrieves an exception item using its `id` or `item_id` field. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/exception_lists/items` @@ -26,9 +28,9 @@ GET api/exception_lists/items?item_id=global-allow-processes ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload [source,json] @@ -68,4 +70,4 @@ GET api/exception_lists/items?item_id=global-allow-processes "updated_at": "2020-07-14T13:40:39.980Z", "updated_by": "LiverpoolFC" } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/detections/api/exceptions/api-update-exception-container.asciidoc b/docs/detections/api/exceptions/api-update-exception-container.asciidoc index 790d634b21..159199feb9 100644 --- a/docs/detections/api/exceptions/api-update-exception-container.asciidoc +++ b/docs/detections/api/exceptions/api-update-exception-container.asciidoc @@ -3,6 +3,8 @@ Updates an existing exception container. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `PUT :/api/lists` @@ -26,7 +28,7 @@ the container's `id` field is not used. |No, defaults to `single`. |`tags` |String[] |String array containing words and phrases to help categorize -exception containers. |No +exception containers. |No |`type` |String a|The type of exception, which must be one of these: * `detection`: Detection rule exception @@ -60,9 +62,9 @@ PUT api/exception_lists ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload The updated object, including the time it was updated. @@ -89,4 +91,4 @@ Example response: "updated_at": "2020-07-15T06:12:38.098Z", "updated_by": "LiverpoolFC" } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/detections/api/exceptions/api-update-exception-item.asciidoc b/docs/detections/api/exceptions/api-update-exception-item.asciidoc index bc74caed33..61798c2429 100644 --- a/docs/detections/api/exceptions/api-update-exception-item.asciidoc +++ b/docs/detections/api/exceptions/api-update-exception-item.asciidoc @@ -3,6 +3,8 @@ Updates an existing exception item. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `PUT :/api/exception_lists/items` @@ -17,7 +19,7 @@ Updates an existing exception item. * `comment` (string): Comments about the exception item. * `id` (string): Existing comment ID, required for updating existing comments. -When unspecified, a new comment is created. +When unspecified, a new comment is created. |No, defaults to empty array. @@ -39,7 +41,7 @@ in all {kib} spaces or just the space in which it is created, where: |No, defaults to `single`. |`tags` |String[] |String array containing words and phrases to help categorize -exception items. |No +exception items. |No |`type` |String a|Exception query type, must be `simple`. |Yes |============================================== @@ -87,9 +89,9 @@ PUT api/exception_lists/items ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload The updated object, including the time it was updated. @@ -137,4 +139,4 @@ Example response: "updated_at": "2020-07-15T06:28:50.494Z", "updated_by": "LiverpoolFC" } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/detections/api/exceptions/exceptions-api-overview.asciidoc b/docs/detections/api/exceptions/exceptions-api-overview.asciidoc index 8aa1dcd2ef..43127d2576 100644 --- a/docs/detections/api/exceptions/exceptions-api-overview.asciidoc +++ b/docs/detections/api/exceptions/exceptions-api-overview.asciidoc @@ -7,6 +7,8 @@ rule's other criteria are met. They can be used to reduce the number of false positives, and to prevent trusted processes and network activity from generating unnecessary alerts. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + Exceptions are made up of: * *Exception containers*: A container for related exceptions. In general, a @@ -46,7 +48,7 @@ IMPORTANT: Before you can create exceptions, you must create `.lists` and To create list containers and items, the user role for the {kib} space must have: -* `read` and `write` index privileges for the +* `read` and `write` index privileges for the `.lists` and `.items` indices (the system index used for storing exception lists). * {kib} space `All` privileges for the `Security` and `Saved Objects Management` features (see diff --git a/docs/detections/api/exceptions/lists-index-api-overview.asciidoc b/docs/detections/api/exceptions/lists-index-api-overview.asciidoc index 9601b49bf5..7cc9e64735 100644 --- a/docs/detections/api/exceptions/lists-index-api-overview.asciidoc +++ b/docs/detections/api/exceptions/lists-index-api-overview.asciidoc @@ -8,6 +8,8 @@ and `.items` system indices in the relevant For information about the permissions and privileges required to create `.lists` and `.items` indices, see <>. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + [discrete] === Create index @@ -33,7 +35,7 @@ POST api/lists/index [discrete] ==== Response code -`200`:: +`200`:: Indicates a successful call. [discrete] @@ -60,12 +62,12 @@ GET api/lists/index [discrete] ==== Response code -`200`:: +`200`:: Indicates a successful call. `404`:: Indicates no index exists. -[discrete] +[discrete] ===== Example responses Example response when the indices exist: @@ -112,5 +114,5 @@ DELETE api/lists/index [discrete] ==== Response code -`200`:: - Indicates a successful call. \ No newline at end of file +`200`:: + Indicates a successful call. diff --git a/docs/detections/api/lists/api-create-list-container.asciidoc b/docs/detections/api/lists/api-create-list-container.asciidoc index 8758ef3987..d230d0a34a 100644 --- a/docs/detections/api/lists/api-create-list-container.asciidoc +++ b/docs/detections/api/lists/api-create-list-container.asciidoc @@ -3,6 +3,8 @@ Creates a list container. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + 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. @@ -56,7 +58,7 @@ and `text`. * `{{{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. @@ -126,13 +128,13 @@ POST api/lists 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`. +characters. For example, `192.168.0.1--192.168.0.27`. ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload @@ -157,4 +159,4 @@ characters. For example, `192.168.0.1--192.168.0.27`. <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 -<>. \ No newline at end of file +<>. diff --git a/docs/detections/api/lists/api-create-list-item.asciidoc b/docs/detections/api/lists/api-create-list-item.asciidoc index 79a040934e..a26b80d399 100644 --- a/docs/detections/api/lists/api-create-list-item.asciidoc +++ b/docs/detections/api/lists/api-create-list-item.asciidoc @@ -4,6 +4,8 @@ Creates a list item and associates it with the specified <>. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + 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. @@ -63,9 +65,9 @@ POST api/lists ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload [source,json] @@ -87,4 +89,4 @@ POST api/lists <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 -<>. \ No newline at end of file +<>. diff --git a/docs/detections/api/lists/api-delete-list-container.asciidoc b/docs/detections/api/lists/api-delete-list-container.asciidoc index fcca956983..64cf7e143f 100644 --- a/docs/detections/api/lists/api-delete-list-container.asciidoc +++ b/docs/detections/api/lists/api-delete-list-container.asciidoc @@ -3,6 +3,8 @@ Deletes a list container. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + NOTE: When you delete a list container, all of its list items are also deleted. ==== Request URL @@ -27,5 +29,5 @@ DELETE api/lists?id=external-ip-excludes ==== Response code -`200`:: - Indicates a successful call. \ No newline at end of file +`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 index d1af351a02..89a17d60b6 100644 --- a/docs/detections/api/lists/api-delete-list-item.asciidoc +++ b/docs/detections/api/lists/api-delete-list-item.asciidoc @@ -3,6 +3,8 @@ Deletes list items. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `DELETE :/api/lists/items` @@ -34,5 +36,5 @@ DELETE api/lists/items?list_id=internal-ip-excludes&value=127.0.0.0/30 ==== Response code -`200`:: - Indicates a successful call. \ No newline at end of file +`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 index 2fa300a245..629a6ee464 100644 --- a/docs/detections/api/lists/api-export-list-item.asciidoc +++ b/docs/detections/api/lists/api-export-list-item.asciidoc @@ -1,7 +1,9 @@ [[lists-api-export-items]] === Export list items -Exports list item values from the specified list container. +Exports list item values from the specified list container. + +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. ==== Request URL @@ -30,5 +32,5 @@ POST api/lists/items/_export?list_id=external-ip-excludes ==== Response code -`200`:: - Indicates a successful call. \ No newline at end of file +`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 index 5575a3ed89..c3f68cbee6 100644 --- a/docs/detections/api/lists/api-find-list-containers.asciidoc +++ b/docs/detections/api/lists/api-find-list-containers.asciidoc @@ -4,6 +4,8 @@ Retrieves a paginated subset of list containers. By default, the first page is returned with 20 results per page. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/lists/_find` @@ -30,7 +32,7 @@ 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 +|`filter` |String a|Filters the returned results according to the value of the specified field, using the `:` syntax, where `` can be: @@ -54,9 +56,9 @@ GET api/lists/_find?filter=type:keyword&page=1&per_page=2&sort_field=name&sort_o ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload [source,json] diff --git a/docs/detections/api/lists/api-find-list-items.asciidoc b/docs/detections/api/lists/api-find-list-items.asciidoc index 1ead58fbbd..209e06fded 100644 --- a/docs/detections/api/lists/api-find-list-items.asciidoc +++ b/docs/detections/api/lists/api-find-list-items.asciidoc @@ -4,6 +4,8 @@ Retrieves a paginated subset of list items in the specified container. By default, the first page is returned with 20 results per page. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/lists/items/_find` @@ -44,9 +46,9 @@ GET api/lists/items/_find?list_id=external-ip-excludes ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload [source,json] diff --git a/docs/detections/api/lists/api-get-list-containers.asciidoc b/docs/detections/api/lists/api-get-list-containers.asciidoc index cd707ba9f0..f944552576 100644 --- a/docs/detections/api/lists/api-get-list-containers.asciidoc +++ b/docs/detections/api/lists/api-get-list-containers.asciidoc @@ -3,6 +3,8 @@ Retrieves a list container using its `id` field. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/lists` @@ -25,9 +27,9 @@ GET api/lists?id=internal-ip-excludes ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload [source,json] @@ -43,4 +45,4 @@ GET api/lists?id=internal-ip-excludes "updated_at": "2020-07-07T04:09:55.028Z", "updated_by": "Threat Hunter" } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/detections/api/lists/api-get-list-items.asciidoc b/docs/detections/api/lists/api-get-list-items.asciidoc index 29188e9522..c88cee8271 100644 --- a/docs/detections/api/lists/api-get-list-items.asciidoc +++ b/docs/detections/api/lists/api-get-list-items.asciidoc @@ -3,6 +3,8 @@ Retrieves list items using its `id`, or its `list_id` and `value` fields. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + IMPORTANT: For `ip` and `ip_range` list containers, you can retrieve up to 10,000 list items. @@ -55,9 +57,9 @@ GET api/lists/items?list_id=internal-ip-ranges&value=192.168.1.14 ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload [source,json] @@ -97,4 +99,4 @@ GET api/lists/items?list_id=internal-ip-ranges&value=192.168.1.14 "value": "127.0.0.3" } ] --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/detections/api/lists/api-import-list-items.asciidoc b/docs/detections/api/lists/api-import-list-items.asciidoc index 2abfeb5779..a764b1fa84 100644 --- a/docs/detections/api/lists/api-import-list-items.asciidoc +++ b/docs/detections/api/lists/api-import-list-items.asciidoc @@ -6,6 +6,8 @@ Imports a list of items from a `.txt` or `.csv` file. You can import items to a new or existing <>. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `POST :/api/lists/items/_import` @@ -61,9 +63,9 @@ curl -X POST "api/lists/items/_import?type=ip" ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload [source,json] diff --git a/docs/detections/api/lists/api-update-list-container.asciidoc b/docs/detections/api/lists/api-update-list-container.asciidoc index 0eb5e92b1e..146e538728 100644 --- a/docs/detections/api/lists/api-update-list-container.asciidoc +++ b/docs/detections/api/lists/api-update-list-container.asciidoc @@ -3,6 +3,8 @@ Updates an existing list container. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + You can use `PUT` or `PATCH` methods to update list containers, where: * `PUT` replaces the original container and deletes fields that are not @@ -26,7 +28,7 @@ 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. +some fields are required. [width="100%",options="header"] |============================================== @@ -59,9 +61,9 @@ PATCH api/lists ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload The updated object, including the time it was updated. @@ -84,4 +86,4 @@ Example response: "updated_by": "elastic", "version": 2 } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/detections/api/lists/api-update-list-item.asciidoc b/docs/detections/api/lists/api-update-list-item.asciidoc index c598f05778..9e0ce51096 100644 --- a/docs/detections/api/lists/api-update-list-item.asciidoc +++ b/docs/detections/api/lists/api-update-list-item.asciidoc @@ -3,6 +3,8 @@ Updates an existing list item. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + You can use `PUT` or `PATCH` methods to update list items, where: * `PUT` replaces the original items and deletes fields that are not @@ -26,7 +28,7 @@ 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. +some fields are required. [width="100%",options="header"] |============================================== @@ -60,9 +62,9 @@ PATCH api/lists/items ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload The updated object, including the time it was updated. @@ -83,4 +85,4 @@ Example response: "updated_by": "elastic", "value": "10.0.0.17" } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/detections/api/lists/lists-api-overview.asciidoc b/docs/detections/api/lists/lists-api-overview.asciidoc index 3038d2ac0d..25ad5f4573 100644 --- a/docs/detections/api/lists/lists-api-overview.asciidoc +++ b/docs/detections/api/lists/lists-api-overview.asciidoc @@ -2,8 +2,11 @@ == Lists API Lists can be used with detection rule <> -to define values that prevent a rule from generating alerts. Lists are made up -of: +to define values that prevent a rule from generating alerts. + +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + +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: @@ -62,7 +65,7 @@ indices for the {kib} space (see <>). To create list containers and items, the user role for the {kib} space must have: -* `read` and `write` index privileges for the +* `read` and `write` index privileges for the `.lists` and `.items` indices (the system index used for storing exception lists). * {kib} space `All` privileges for the `Security` and `Saved Objects Management` features (see diff --git a/docs/detections/api/rules/index-api-overview.asciidoc b/docs/detections/api/rules/index-api-overview.asciidoc index 6c9cc6d209..b863f14867 100644 --- a/docs/detections/api/rules/index-api-overview.asciidoc +++ b/docs/detections/api/rules/index-api-overview.asciidoc @@ -4,13 +4,15 @@ You use the index endpoint to create, get, and delete `.siem-signals-` system indices in a {kib} space. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + NOTE: Signal indices store detection alerts. For information about the permissions and privileges required to create `.siem-signals-` indices, see <>. When you create a signal index, the following -{ref}/getting-started-index-lifecycle-management.html[{ilm} ({ilm-init})] +{ref}/getting-started-index-lifecycle-management.html[{ilm} ({ilm-init})] policy is created for the signal index: [source,js] -------------------------------------------------- @@ -54,7 +56,7 @@ POST s/siem/api/detection_engine/index ===== Response code -`200`:: +`200`:: Indicates a successful call. ==== Get index @@ -77,11 +79,11 @@ GET s/siem/api/detection_engine/index ===== Response code -`200`:: +`200`:: Indicates a successful call. `404`:: Indicates no index exists. - + ====== Example responses Example response when index exists: @@ -124,5 +126,5 @@ DELETE s/siem/api/detection_engine/index ===== Response code -`200`:: - Indicates a successful call. \ No newline at end of file +`200`:: + Indicates a successful call. diff --git a/docs/detections/api/rules/privileges-api-overview.asciidoc b/docs/detections/api/rules/privileges-api-overview.asciidoc index b432f5db8e..988f2f74ae 100644 --- a/docs/detections/api/rules/privileges-api-overview.asciidoc +++ b/docs/detections/api/rules/privileges-api-overview.asciidoc @@ -2,13 +2,15 @@ [role="xpack"] === Privileges endpoint -Retrieves whether or not the user is authenticated, and the user's {kib} space +Retrieves whether or not the user is authenticated, and the user's {kib} space and index privileges, which determine if the user can create an index (`.siem-signals-*`) for the {es-sec} alerts generated by detection engine rules. For information about the permissions and privileges required to create `.siem-signals-` indices, see <>. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Get privileges Returns user privileges for the {kib} space. @@ -37,7 +39,7 @@ GET s/siem/api/detection_engine/privileges ===== Response code -`200`:: +`200`:: Indicates a successful call. ====== Example response @@ -100,6 +102,6 @@ GET s/siem/api/detection_engine/privileges } -------------------------------------------------- <1> Indicates whether the user can log in to the {es} deployment. -<2> Indicates whether the +<2> Indicates whether the <> is -set. \ No newline at end of file +set. diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc index 47f3f9f97e..9c66b69f70 100644 --- a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc +++ b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc @@ -4,6 +4,8 @@ You can bulk create, update, and delete rules. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Bulk create Creates new rules. @@ -68,12 +70,12 @@ POST api/detection_engine/rules/_bulk_create ===== Response code -`200`:: +`200`:: Indicates a successful call. - + ===== Response payload -A JSON array that includes a unique ID for each rule. A unique rule ID is +A JSON array that includes a unique ID for each rule. A unique rule ID is generated for all rules that did not include a `rule_id` field. ==== Bulk delete @@ -106,9 +108,9 @@ DELETE api/detection_engine/rules/_bulk_delete ===== Response code -`200`:: +`200`:: Indicates a successful call. - + ===== Response payload A JSON array containing the deleted rules. @@ -140,7 +142,7 @@ deleted. You cannot modify the `id` or `rule_id` values. For `PATCH` calls, any of the fields can be modified. For `PUT` calls, some fields are required (see <> for a list of required -fields). +fields). ====== Example request @@ -178,9 +180,9 @@ PATCH api/detection_engine/rules/_bulk_update ===== Response code -`200`:: +`200`:: Indicates a successful call. - + ===== Response payload -A JSON array containing the updated rules. \ No newline at end of file +A JSON array containing the updated rules. diff --git a/docs/detections/api/rules/rules-api-delete.asciidoc b/docs/detections/api/rules/rules-api-delete.asciidoc index 811a772193..511e1eb7fb 100644 --- a/docs/detections/api/rules/rules-api-delete.asciidoc +++ b/docs/detections/api/rules/rules-api-delete.asciidoc @@ -3,6 +3,8 @@ Deletes a single rule using the `rule_id` or `id` field. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `DELETE :/api/detection_engine/rules` @@ -26,5 +28,5 @@ DELETE api/detection_engine/rules?id=16947168-5405-453d-a8b5-aadad357af42 ==== Response code -`200`:: - Indicates a successful call. \ No newline at end of file +`200`:: + Indicates a successful call. diff --git a/docs/detections/api/rules/rules-api-export.asciidoc b/docs/detections/api/rules/rules-api-export.asciidoc index 8ba02d6c39..23260be5d8 100644 --- a/docs/detections/api/rules/rules-api-export.asciidoc +++ b/docs/detections/api/rules/rules-api-export.asciidoc @@ -3,6 +3,8 @@ Exports rules to an ndjson file. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + NOTE: You cannot export prebuilt rules but they are available at https://github.com/elastic/detection-rules/tree/main/rules/. ==== Request URL @@ -16,9 +18,9 @@ NOTE: You cannot export prebuilt rules but they are available at https://github. |============================================== |Name |Type |Description |Required -|`exclude_export_details` |Boolean |Determines whether a summary of the +|`exclude_export_details` |Boolean |Determines whether a summary of the exported rules is returned.|No, defaults to `false`. -|`file_name` |String |File name for saving the exported rules. |No, defaults to +|`file_name` |String |File name for saving the exported rules. |No, defaults to `export.ndjson` |============================================== @@ -27,21 +29,21 @@ to save the rules to the file name specified in the URL. ==== Request body -An optional JSON `objects` array containing the `rule_id` fields of the rules +An optional JSON `objects` array containing the `rule_id` fields of the rules you want to export: [width="100%",options="header"] |============================================== |Name |Type |Description |Required -|`objects` |String[] |Array of `rule_id` fields. |No, exports all rules when +|`objects` |String[] |Array of `rule_id` fields. |No, exports all rules when unspecified. |============================================== ===== Example request -Exports two rules without details and saves them to the `exported_rules.ndjson` +Exports two rules without details and saves them to the `exported_rules.ndjson` file: [source,console] @@ -63,5 +65,5 @@ POST api/detection_engine/rules/_export?exclude_export_details=true&file_name=ex ==== Response code -`200`:: +`200`:: Indicates a successful call. diff --git a/docs/detections/api/rules/rules-api-find.asciidoc b/docs/detections/api/rules/rules-api-find.asciidoc index 909a2217d7..a829141434 100644 --- a/docs/detections/api/rules/rules-api-find.asciidoc +++ b/docs/detections/api/rules/rules-api-find.asciidoc @@ -4,6 +4,8 @@ Retrieves a paginated subset of detection rules. By default, the first page is returned with 20 results per page. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/detection_engine/rules/_find` @@ -24,8 +26,8 @@ All parameters are optional: |`sort_order` |String |Determines the sort order, which can be `desc` or `asc`. -|`filter` |String a|Filters the returned results according to the value of the -specified field, using the `alert.attributes.:` +|`filter` |String a|Filters the returned results according to the value of the +specified field, using the `alert.attributes.:` syntax, where `` can be: * `name` @@ -35,13 +37,13 @@ syntax, where `` can be: * `interval` * `updatedBy` -NOTE: Even though the JSON rule object uses `created_by` and `updated_by` +NOTE: Even though the JSON rule object uses `created_by` and `updated_by` fields, you must use `createdBy` and `updatedBy` fields in the filter. |============================================== ===== Example request -Retrieves the first five rules with the word `windows` in their names, sorted +Retrieves the first five rules with the word `windows` in their names, sorted in ascending order: [source,console] @@ -52,9 +54,9 @@ GET api/detection_engine/rules/_find?page=1&per_page=5&sort_field=enabled&sort_o ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload A JSON object containing a summary and the returned rules. @@ -121,4 +123,4 @@ Example response: ] } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/detections/api/rules/rules-api-get.asciidoc b/docs/detections/api/rules/rules-api-get.asciidoc index 20df54c1ec..359588a524 100644 --- a/docs/detections/api/rules/rules-api-get.asciidoc +++ b/docs/detections/api/rules/rules-api-get.asciidoc @@ -3,6 +3,8 @@ Retrieves a single rule using the `rule_id` or `id` field. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/detection_engine/rules` @@ -26,9 +28,9 @@ GET api/detection_engine/rules?id=c41d170b-8ba6-4de6-b8ec-76440a35ace3 ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload The returned rule's JSON object. @@ -96,4 +98,4 @@ Example response: "version": 1 } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/detections/api/rules/rules-api-import.asciidoc b/docs/detections/api/rules/rules-api-import.asciidoc index f376d5ad18..ca77bef6f5 100644 --- a/docs/detections/api/rules/rules-api-import.asciidoc +++ b/docs/detections/api/rules/rules-api-import.asciidoc @@ -3,6 +3,8 @@ Imports rules from an ndjson file. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `POST :/api/detection_engine/rules/_import` @@ -29,13 +31,13 @@ curl -X POST "/api/detection_engine/rules/_import" |============================================== |Name |Type |Description |Required -|`overwrite` |Boolean |Determines whether existing rules with the same +|`overwrite` |Boolean |Determines whether existing rules with the same `rule_id` are overwritten. |No, defaults to `false`. |============================================== ===== Example request -Imports the rules in the `detection_rules.ndjson` file and overwrites +Imports the rules in the `detection_rules.ndjson` file and overwrites existing rules with the same `rule_id` values: [source,console] @@ -47,5 +49,5 @@ curl -X POST "api/detection_engine/rules/_import?overwrite=true" ==== Response code -`200`:: - Indicates a successful call. \ No newline at end of file +`200`:: + Indicates a successful call. diff --git a/docs/detections/api/rules/rules-api-overview.asciidoc b/docs/detections/api/rules/rules-api-overview.asciidoc index 3eaa9beffd..5bfce683ec 100644 --- a/docs/detections/api/rules/rules-api-overview.asciidoc +++ b/docs/detections/api/rules/rules-api-overview.asciidoc @@ -6,6 +6,8 @@ You can create rules that automatically turn events and external alerts sent to {es-sec} into detection alerts. These alerts are displayed on the Detections page. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + For more information on detection alerts, and the difference between events, external alerts, and detection alerts, see <>. diff --git a/docs/detections/api/rules/rules-api-prebuilt.asciidoc b/docs/detections/api/rules/rules-api-prebuilt.asciidoc index 5a5e1c7a59..1d10e7d556 100644 --- a/docs/detections/api/rules/rules-api-prebuilt.asciidoc +++ b/docs/detections/api/rules/rules-api-prebuilt.asciidoc @@ -2,9 +2,11 @@ [role="xpack"] === Prebuilt rules -The prepackaged endpoint is for retrieving rule statuses and loading Elastic +The prepackaged endpoint is for retrieving rule statuses and loading Elastic prebuilt detection rules. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Load prebuilt rules Loads and updates Elastic prebuilt rules. @@ -25,9 +27,9 @@ PUT api/detection_engine/rules/prepackaged ===== Response code -`200`:: +`200`:: Indicates a successful call. - + ====== Response payload A JSON object listing the number of loaded and updated prebuilt rules. @@ -60,9 +62,9 @@ GET api/detection_engine/rules/prepackaged/_status ===== Response code -`200`:: +`200`:: Indicates a successful call. - + ====== Response payload A JSON object listing rule statuses. diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc index f87d4cdd48..0d4a86bcea 100644 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ b/docs/detections/api/rules/rules-api-update.asciidoc @@ -3,6 +3,8 @@ Updates an existing detection rule. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + You can use `PUT` or `PATCH` methods to update rules, where: * `PUT` replaces the original rule and deletes fields that are not specified. @@ -37,7 +39,7 @@ some fields are required. |name |String |The rule's name. -|risk_score |Integer a|A numerical representation of the alert's severity from +|risk_score |Integer a|A numerical representation of the alert's severity from 0 to 100, where: * `0` - `21` represents low severity @@ -45,14 +47,14 @@ some fields are required. * `48` - `73` represents high severity * `74` - `100` represents critical severity -|severity |String a|Severity level of alerts produced by the rule, which must +|severity |String a|Severity level of alerts produced by the rule, which must be one of the following: -* `low`: Alerts that are of interest but generally not considered to be +* `low`: Alerts that are of interest but generally not considered to be security incidents * `medium`: Alerts that require investigation * `high`: Alerts that require immediate investigation -* `critical`: Alerts that indicate it is highly likely a security incident has +* `critical`: Alerts that indicate it is highly likely a security incident has occurred |type |String a|Data type on which the rule is based: @@ -127,7 +129,7 @@ generated. creates an alert. Valid values are from `0` to `100`. |machine_learning_job_id |String |{ml-cap} job ID the rule monitors for -anomaly scores. +anomaly scores. |============================================== @@ -177,18 +179,18 @@ used as a foundation for other rules that do generate alerts. Its value must be |enabled |Boolean |Determines whether the rule is enabled. Defaults to `true`. -|false_positives |String[] |String array used to describe common reasons why +|false_positives |String[] |String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array. [[detection-rules-from]] |from |String |Time from which data is analyzed each time the rule executes, -using a {ref}/common-options.html#date-math[date math range]. For example, -`now-4200s` means the rule analyzes data from 70 minutes before its start -time. Defaults to `now-6m` (analyzes data from 6 minutes before the start +using a {ref}/common-options.html#date-math[date math range]. For example, +`now-4200s` means the rule analyzes data from 70 minutes before its start +time. Defaults to `now-6m` (analyzes data from 6 minutes before the start time). |interval |String |Frequency of rule execution, using a -{ref}/common-options.html#date-math[date math range]. For example, `"1h"` +{ref}/common-options.html#date-math[date math range]. For example, `"1h"` means the rule runs every hour. Defaults to `5m` (5 minutes). |license |String |The rule's license. @@ -200,17 +202,17 @@ single execution. Defaults to `100`. |note |String |Notes to help investigate alerts produced by the rule. -|output_index |String |Index to which alerts created by the rule are saved. -If unspecified alerts are saved to `.siem-signals-` index, +|output_index |String |Index to which alerts created by the rule are saved. +If unspecified alerts are saved to `.siem-signals-` index, where `` is the name of the {kib} space in which the rule exists. -|references |String[] |Array containing notes about or references to +|references |String[] |Array containing notes about or references to relevant information about the rule. Defaults to an empty array. |tags |String[] |String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array. -|threat |<> |Object containing attack +|threat |<> |Object containing attack information about the type of threat the rule monitors, see {ecs-ref}/ecs-threat.html[ECS threat fields]. Defaults to an empty array. @@ -224,7 +226,7 @@ information about the type of threat the rule monitors, see Required when `actions` are used to send notifications. -|version |Integer a|The rule's version number. If this is not provided, the +|version |Integer a|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 @@ -279,8 +281,8 @@ documents from the {es} index containing the threat values. |============================================== |Name |Type |Description -|filters |Object[] |The {ref}/query-filter-context.html[query and filter -context] array used to define the conditions for when alerts are created from +|filters |Object[] |The {ref}/query-filter-context.html[query and filter +context] array used to define the conditions for when alerts are created from events. Defaults to an empty array. |index |String[] |Indices on which the rule functions. Defaults to the @@ -362,7 +364,7 @@ PagerDuty alert. event, for example `security-solution`. ** `group` (string, optional): Enables logical grouping of service components. ** `source` (string, optional): The affected system. Defaults to the {kib} -saved object ID of the action. +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. @@ -387,7 +389,7 @@ These fields are required when calling `PUT` to modify the `threat` object: * `name` - string, required * `reference` - string, required -|technique |Object a|Object containing information on the attack +|technique |Object a|Object containing information on the attack technique: * `id` - string, required @@ -396,7 +398,7 @@ technique: |============================================== -NOTE: Only threats described using the MITRE ATT&CK^TM^ framework are displayed +NOTE: Only threats described using the MITRE ATT&CK^TM^ framework are displayed in the UI (*Security* -> *Detections* -> *Manage detection rules* -> ). @@ -432,12 +434,12 @@ PATCH api/detection_engine/rules ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== Response payload -The rule's updated JSON object, including the time the rule was updated and an +The rule's updated JSON object, including the time the rule was updated and an incremented version number. Example response: diff --git a/docs/detections/api/rules/signals-api-overview.asciidoc b/docs/detections/api/rules/signals-api-overview.asciidoc index d7cc1d279e..b8af992c21 100644 --- a/docs/detections/api/rules/signals-api-overview.asciidoc +++ b/docs/detections/api/rules/signals-api-overview.asciidoc @@ -10,6 +10,8 @@ the indices, see: * {ref}/search-aggregations.html[Aggregations] * {ref}/query-dsl.html[Query DSL] +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Get alerts Aggregates and returns alerts. @@ -24,8 +26,8 @@ A query DSL that determines which results are returned. ====== Example request -Gets aggregated results of all open alerts with a risk score equal to or -greater than 70. It also returns the timestamps of the oldest and +Gets aggregated results of all open alerts with a risk score equal to or +greater than 70. It also returns the timestamps of the oldest and newest alerts that meet the query's criteria. [source,console] @@ -65,7 +67,7 @@ POST api/detection_engine/signals/search } -------------------------------------------------- -Gets all in-progress alerts with a risk score equal to or +Gets all in-progress alerts with a risk score equal to or greater than 70. [source,console] @@ -96,9 +98,9 @@ POST api/detection_engine/signals/search ===== Response code -`200`:: +`200`:: Indicates a successful call. - + ====== Response payload A JSON object with the aggregated values and requested alerts. @@ -156,7 +158,7 @@ A JSON object with either a `query` or `signals_id` field: |`signal_ids` |String[] |Array of alert IDs. |Yes, when the `query` field is not used. -|`query` |Query DSL |Query that determines which alerts are updated. |Yes, when +|`query` |Query DSL |Query that determines which alerts are updated. |Yes, when the `signal_ids` field is not used. |`status` |String |The new status, which can be `open`, `in-progress` or @@ -173,7 +175,7 @@ Closes alerts with `signal_ids`: POST api/detection_engine/signals/status { "signal_ids": [ - "694156bbe6a487e06d049bd6019bd49fec4172cfb33f5d81c3b4a977f0026fba", + "694156bbe6a487e06d049bd6019bd49fec4172cfb33f5d81c3b4a977f0026fba", "f4d1c62c4e8946c835cb497329127803c09b955de49a8fa186be3899522667b0" ], "status": "closed" @@ -181,7 +183,7 @@ POST api/detection_engine/signals/status -------------------------------------------------- // KIBANA -Closes alerts that are over a month old and have a risk score less than or +Closes alerts that are over a month old and have a risk score less than or equal to 20: [source,json] @@ -215,9 +217,9 @@ POST api/detection_engine/signals/status ===== Response code -`200`:: +`200`:: Indicates a successful call. - + ====== Response payload A JSON object containing the number of updated alerts. @@ -244,4 +246,4 @@ Example response: "throttled_until_millis": 0, "failures": [] } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/detections/api/rules/tags-api-overview.asciidoc b/docs/detections/api/rules/tags-api-overview.asciidoc index e46ead02b5..ccf538d79f 100644 --- a/docs/detections/api/rules/tags-api-overview.asciidoc +++ b/docs/detections/api/rules/tags-api-overview.asciidoc @@ -4,6 +4,8 @@ Aggregates and returns all rule tags. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Get tags Aggregates and returns all unique tags from all rules. @@ -24,7 +26,7 @@ GET api/detection_engine/tags ===== Response code -`200`:: +`200`:: Indicates a successful call. ====== Example response @@ -41,4 +43,4 @@ GET api/detection_engine/tags "remote access", "phishing" ] --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/detections/api/signals-migration-api.asciidoc b/docs/detections/api/signals-migration-api.asciidoc index d6b61d46a3..241c24c174 100644 --- a/docs/detections/api/signals-migration-api.asciidoc +++ b/docs/detections/api/signals-migration-api.asciidoc @@ -4,6 +4,8 @@ After an upgrade of {kib}, the latest {es-sec} features will be available for any new <> that are generated. However, in order to enable new features on existing detection alerts, migration may be necessary. See <> for instructions specific to your upgrade. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + Migrating detection alerts is performed at the index level and requires the following steps: 1. <> diff --git a/docs/events/api/timeline-api-create.asciidoc b/docs/events/api/timeline-api-create.asciidoc index d4df50547e..4bb9fa7edc 100644 --- a/docs/events/api/timeline-api-create.asciidoc +++ b/docs/events/api/timeline-api-create.asciidoc @@ -3,6 +3,8 @@ Creates a new Timeline or Timeline template. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + Use the `timeline` object's <> field to determine whether a timeline or a timeline template is created, where: diff --git a/docs/events/api/timeline-api-delete.asciidoc b/docs/events/api/timeline-api-delete.asciidoc index 66530a76d1..925aa10c87 100644 --- a/docs/events/api/timeline-api-delete.asciidoc +++ b/docs/events/api/timeline-api-delete.asciidoc @@ -3,6 +3,8 @@ Delete multiple Timelines or Timeline templates. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `DELETE :/api/timeline` @@ -27,4 +29,4 @@ DELETE api/timeline { "savedObjectIds": ["56efaaf0-b274-11eb-8078-5b983613cc0f"] } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/events/api/timeline-api-get.asciidoc b/docs/events/api/timeline-api-get.asciidoc index bc5903292c..335b276565 100644 --- a/docs/events/api/timeline-api-get.asciidoc +++ b/docs/events/api/timeline-api-get.asciidoc @@ -3,6 +3,8 @@ Get Timelines or Timeline templates. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/timelines` @@ -50,6 +52,8 @@ GET api/timelines?page_size=10&page_index=1&sort_field=updated&sort_order=desc&t Get single Timeline or Timeline template by savedObjectId. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/timeline?id=` @@ -69,6 +73,8 @@ GET /api/timeline?id= Get a single Timeline template by templateTimelineId. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `GET :/api/timeline?template_timeline_id=` @@ -82,5 +88,3 @@ Get Timeline by templateTimelineId: GET /api/timeline?template_timeline_id= -------------------------------------------------- - - diff --git a/docs/events/api/timeline-api-import.asciidoc b/docs/events/api/timeline-api-import.asciidoc index df82844415..3cf088d8fe 100644 --- a/docs/events/api/timeline-api-import.asciidoc +++ b/docs/events/api/timeline-api-import.asciidoc @@ -3,6 +3,8 @@ Imports timelines and timeline templates from an `ndjson` file. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + If you are updating an existing timeline template, make sure: * You specify the relevant template's unique ID (`templateTimelineId`). @@ -41,5 +43,5 @@ curl -X POST "api/detection_engine/rules/_import" ==== Response code -`200`:: - Indicates a successful call. \ No newline at end of file +`200`:: + Indicates a successful call. diff --git a/docs/events/api/timeline-api-overview.asciidoc b/docs/events/api/timeline-api-overview.asciidoc index 0845268496..230d9f5a44 100644 --- a/docs/events/api/timeline-api-overview.asciidoc +++ b/docs/events/api/timeline-api-overview.asciidoc @@ -4,4 +4,5 @@ You can create Timelines and Timeline templates via the API, as well as import new Timelines from an `ndjson` file. -NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. \ No newline at end of file +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + diff --git a/docs/events/api/timeline-api-update.asciidoc b/docs/events/api/timeline-api-update.asciidoc index 3e15383eb4..d89ff455e1 100644 --- a/docs/events/api/timeline-api-update.asciidoc +++ b/docs/events/api/timeline-api-update.asciidoc @@ -3,6 +3,8 @@ Add a note to an existing Timeline or Timeline event. +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `PATCH :/api/note` @@ -61,6 +63,8 @@ PATCH api/note === Pin an event to an existing Timeline +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. + ==== Request URL `PATCH :/api/pinned_event` @@ -105,4 +109,4 @@ PATCH api/pinned_event "pinnedEventId":"9bc11e40-b312-11eb-8078-5b983613cc0f", "timelineId":"b2c103b0-a79d-11eb-9dce-0f3114099868" } --------------------------------------------------- \ No newline at end of file +--------------------------------------------------