Skip to content

Commit

Permalink
[DOCS][8.3] Update note on API page (#2033)
Browse files Browse the repository at this point in the history
* Fixes #1970 by removing a note that no longer applies.

* Updates API note throughout docs

* Removes NOTE from API pages except "Elastic Security APIS"

* Update docs/siem-apis.asciidoc

Co-authored-by: Janeen Mikell-Straughn <[email protected]>

Co-authored-by: Janeen Mikell-Straughn <[email protected]>
  • Loading branch information
benironside and jmikell821 authored Jun 16, 2022
1 parent dc57d45 commit be69c3b
Show file tree
Hide file tree
Showing 59 changed files with 17 additions and 138 deletions.
6 changes: 1 addition & 5 deletions docs/cases/api/actions-api/cases-actions-api-intro.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@ You can push {es-sec} cases to these third-party systems:
* {ibm-r}
* {swimlane}

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

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.
Expand All @@ -18,7 +17,7 @@ which stores the information required to interface with the external system.

* {sn}: https://developer.servicenow.com/dev.do#!/reference/api/rome/rest/c_ImportSetAPI[Import Set API]
+
IMPORTANT: {sn} ITSM and SecOps connectors created in {stack} version 7.15.0 or earlier use the https://developer.servicenow.com/dev.do#!/reference/api/quebec/rest/c_TableAPI[Table API]. They are marked as deprecated after you upgrade to version 7.16.0 or later and must be <<post-upgrade-deprecated-sn-connector, updated>> to ensure you have access to new connector enhancements. For example, you can push incident updates from cases using connectors created in version 7.15.0 or earlier. However, pushing incident updates from rules is a newer enhancement and you must update your connector or create a new one to use it.
IMPORTANT: {sn} ITSM and SecOps connectors created in {stack} version 7.15.0 or earlier use the https://developer.servicenow.com/dev.do#!/reference/api/quebec/rest/c_TableAPI[Table API]. They are marked as deprecated after you upgrade to version 7.16.0 or later and must be <<post-upgrade-deprecated-sn-connector, updated>> to ensure you have access to new connector enhancements. For example, you can push incident updates from cases using connectors created in version 7.15.0 or earlier. However, pushing incident updates from rules is a newer enhancement and you must update your connector or create a new one to use it.

* {jira}: https://developer.atlassian.com/cloud/jira/platform/rest/v2/[REST API v2]
* {ibm-r}: https://developer.ibm.com/security/resilient/rest/[Resilient REST API]
Expand All @@ -36,7 +35,6 @@ To send cases to an external system and keep the {es-sec-ui} updated:
Creates a connector, which can then be used to open and update cases in external
systems. Note that data from mapped case fields can be pushed to external systems but cannot be pulled in.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

Expand Down Expand Up @@ -306,7 +304,6 @@ A JSON object with a connector `id` that is required to push cases to {sn}.

Updates a connector.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

Expand Down Expand Up @@ -449,7 +446,6 @@ The updated JSON connector object.

Creates a new or updates an existing external incident from a {es-sec} case.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

NOTE: You can only send cases to external systems after you have
<<register-connector, created>> a connector.
Expand Down
2 changes: 0 additions & 2 deletions docs/cases/api/cases-api/cases-api.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@

You can create, manage, configure, and send cases to external systems with these APIs:

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

NOTE: Cases return a warning header for deprecated endpoints. The value of the warning header is in the form `299 Kibana-{kibana_version} "{warning_text}"`

* {kibana-ref}/cases-api.html[Cases API]: Used to open and manage security action items.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Creates an exception container.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

An exception container groups <<exceptions-api-create-exception-item, exception items>>
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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@
Creates an exception item and associates it with the specified
<<exceptions-api-create-container, exception container>>.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

See <<lists-api-overview>> for information about creating exception items from
lists, such as a list of IP addresses or host names.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Deletes an exception container.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`DELETE <kibana host>:<port>/api/exception_lists`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Deletes an exception item.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`DELETE <kibana host>:<port>/api/exception_lists/items`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@
Retrieves a paginated subset of exception containers. By default, the first
page is returned with 20 results per page.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`GET <kibana host>:<port>/api/exception_lists/_find`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@
Retrieves a paginated subset of exception items in the specified container. By
default, the first page is returned with 20 results per page.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`GET <kibana host>:<port>/api/exception_lists/items/_find`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Retrieves an exception container using its `id` or `list_id` field.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`GET <kibana host>:<port>/api/exception_lists`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Retrieves an exception item using its `id` or `item_id` field.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`GET <kibana host>:<port>/api/exception_lists/items`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Retrieves an exception container summary.

NOTE: Console supports only Elasticsearch APIs. You cannot interact with {kib} APIs with Console and must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`POST <kibana host>:<port>/api/exception_lists/summary`
Expand Down Expand Up @@ -65,7 +63,7 @@ A summary of the exception container:
}
--------------------------------------------------

NOTE: For a host isolation exception, the values for `windows`, `linux`, `macos`, and `total` are all the same, as each host isolation exception entry applies to all operating systems.
NOTE: For a host isolation exception, the values for `windows`, `linux`, `macos`, and `total` are all the same, as each host isolation exception entry applies to all operating systems.
For example:

[source,json]
Expand All @@ -77,4 +75,3 @@ For example:
total: 5,
}
--------------------------------------------------

Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Updates an existing exception container.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`PUT <kibana host>:<port>/api/lists`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Updates an existing exception item.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`PUT <kibana host>:<port>/api/exception_lists/items`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,6 @@ 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: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

Exceptions are made up of:

* *Exception containers*: A container for related exceptions. In general, a
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,6 @@ and `.items` system indices in the relevant
For information about the permissions and privileges required to create
`.lists` and `.items` indices, see <<enable-detections-ui>>.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

[discrete]
=== Create index

Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/lists/api-create-list-container.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Creates a list container.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

A list container groups common <<lists-api-create-list-item, list items>> that
define exceptions for when detection rule alerts are *not* generated even when
a rule's other criteria are met.
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/lists/api-create-list-item.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@
Creates a list item and associates it with the specified
<<lists-api-create-container, list container>>.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

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.

Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/lists/api-delete-list-container.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Deletes a list container.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

NOTE: When you delete a list container, all of its list items are also deleted.

==== Request URL
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/lists/api-delete-list-item.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Deletes list items.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`DELETE <kibana host>:<port>/api/lists/items`
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/lists/api-export-list-item.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Exports list item values from the specified list container.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`POST <kibana host>:<port>/api/lists/items/_export`
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/lists/api-find-list-containers.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@
Retrieves a paginated subset of list containers. By default, the first page is
returned with 20 results per page.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`GET <kibana host>:<port>/api/lists/_find`
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/lists/api-find-list-items.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@
Retrieves a paginated subset of list items in the specified container. By
default, the first page is returned with 20 results per page.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`GET <kibana host>:<port>/api/lists/items/_find`
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/lists/api-get-list-containers.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Retrieves a list container using its `id` field.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`GET <kibana host>:<port>/api/lists`
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/lists/api-get-list-items.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Retrieves list items using its `id`, or its `list_id` and `value` fields.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

IMPORTANT: For `ip` and `ip_range` list containers, you can retrieve up to
10,000 list items.

Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/lists/api-import-list-items.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,6 @@ Imports a list of items from a `.txt` or `.csv` file.
You can import items to a new or existing
<<lists-api-create-container, list container>>.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`POST <kibana host>:<port>/api/lists/items/_import`
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/lists/api-update-list-container.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Updates an existing list container.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

You can use `PUT` or `PATCH` methods to update list containers, where:

* `PUT` replaces the original container and deletes fields that are not
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/lists/api-update-list-item.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Updates an existing list item.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

You can use `PUT` or `PATCH` methods to update list items, where:

* `PUT` replaces the original items and deletes fields that are not
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/lists/lists-api-overview.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@
Lists can be used with detection rule <<exceptions-api-overview, exceptions>>
to define values that prevent a rule from generating alerts.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

Lists are made up of:

* *List containers*: A container for values of the same {es}
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/rules/index-api-overview.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@
You use the index endpoint to create, get, and delete
`.siem-signals-<Kibana-space>` system indices in a {kib} space.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

NOTE: Signal indices store detection alerts.

For information about the permissions and privileges required to create
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/rules/privileges-api-overview.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,6 @@ and index privileges, which determine if the user can create an index
For information about the permissions and privileges required to create
`.siem-signals-<Kibana-space>` indices, see <<enable-detections-ui>>.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Get privileges

Returns user privileges for the {kib} space.
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/rules/rules-api-bulk-actions.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@

You can bulk create, update, and delete rules.

NOTE: Console supports only {es} APIs and doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

'''

[discrete]
Expand Down
4 changes: 1 addition & 3 deletions docs/detections/api/rules/rules-api-create.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,6 @@ WARNING: This API supports {kibana-ref}/api.html#token-api-authentication[Token-

Creates a new detection rule.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

You can create the following types of rules:

* *Custom query*: Searches the defined indices and creates an alert when
Expand Down Expand Up @@ -66,7 +64,7 @@ supported for rule notifications:
* Webhook
* Microsoft Teams
* {ibm-r}
* {jira}
* {jira}
* {sn} ITSM

NOTE: For more information on PagerDuty fields, see
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/rules/rules-api-delete.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Deletes a single rule using the `rule_id` or `id` field.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`DELETE <kibana host>:<port>/api/detection_engine/rules`
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/rules/rules-api-export.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,6 @@ Exports rules to an `.ndjson` file. The following configuration items are also i

You cannot export prebuilt rules, but they are available at https://github.com/elastic/detection-rules/tree/main/rules/.

NOTE: Console supports {es} APIs only. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

[IMPORTANT]
=================
Although detection rule actions are included in the exported file, the connectors used by the actions are not included. Use the {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI in Kibana (*Stack Management* -> *Kibana* -> *Saved Objects*) or the Saved Objects APIs (experimental) to {kibana-ref}/saved-objects-api-export.html[export] and {kibana-ref}/saved-objects-api-import.html[import] any necessary connectors _before_ you export and import the detection rules.
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/rules/rules-api-find.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@
Retrieves a paginated subset of detection rules. By default, the first
page is returned with 20 results per page.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`GET <kibana host>:<port>/api/detection_engine/rules/_find`
Expand Down
2 changes: 0 additions & 2 deletions docs/detections/api/rules/rules-api-get.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@

Retrieves a single rule using the `rule_id` or `id` field.

NOTE: Console supports only Elasticsearch APIs. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests].

==== Request URL

`GET <kibana host>:<port>/api/detection_engine/rules`
Expand Down
Loading

0 comments on commit be69c3b

Please sign in to comment.