From cb9e94e0cf4f8f71af3a219a973fde62884061f3 Mon Sep 17 00:00:00 2001 From: Ying Mao Date: Wed, 17 Feb 2021 09:48:26 -0500 Subject: [PATCH 1/8] Removing REST API from README. Updating configuration docs --- docs/user/alerting/defining-alerts.asciidoc | 4 +- x-pack/plugins/actions/README.md | 88 ++------------------- 2 files changed, 11 insertions(+), 81 deletions(-) diff --git a/docs/user/alerting/defining-alerts.asciidoc b/docs/user/alerting/defining-alerts.asciidoc index ed0e2966b22882..6a599f1c3d3924 100644 --- a/docs/user/alerting/defining-alerts.asciidoc +++ b/docs/user/alerting/defining-alerts.asciidoc @@ -90,8 +90,10 @@ If you are using a cloud deployment, you can set these via the console. Here's a list of the available global configuration options and an explanation of what each one does: +* `xpack.actions.enabled`: Feature toggle which enables Actions in {kib}. Default: `true` * `xpack.actions.allowedHosts`: Specifies an array of host names which actions such as email, Slack, PagerDuty, and webhook can connect to. An element of * indicates any host can be connected to. An empty array indicates no hosts can be connected to. Default: [ {asterisk} ] -* `xpack.actions.enabledActionTypes`: Specifies to an array of action types that are enabled. An {asterisk} indicates all action types registered are enabled. The action types that {kib} provides are: .server-log, .slack, .email, .index, .pagerduty, .webhook. Default: [ {asterisk} ] +* `xpack.actions.enabledActionTypes`: Specifies to an array of action types that are enabled. An {asterisk} indicates all action types registered are enabled. The action types that {kib} provides are: `.email`, `.index`, `.jira`, `.pagerduty`, `.resilient`, `.server-log`, `.servicenow`, `.servicenow-sir`, `.slack`, `.teams`, `.webhook`. Default: [ {asterisk} ] +* `xpack.actions.preconfigured`: Specifies preconfigured action ids and configs. Default: {} * `xpack.actions.proxyUrl`: Specifies the proxy URL to use, if using a proxy for actions. * `xpack.actions.proxyHeader`: Specifies HTTP headers for proxy, if using a proxy for actions. * `xpack.actions.proxyRejectUnauthorizedCertificates`: Set to `false` to bypass certificate validation for proxy, if using a proxy for actions. diff --git a/x-pack/plugins/actions/README.md b/x-pack/plugins/actions/README.md index 9d48e618b76dce..9e42a3ae4dbaed 100644 --- a/x-pack/plugins/actions/README.md +++ b/x-pack/plugins/actions/README.md @@ -26,13 +26,6 @@ Table of Contents - [Executor](#executor) - [Example](#example) - [RESTful API](#restful-api) - - [`POST /api/actions/action`: Create action](#post-apiactionsaction-create-action) - - [`DELETE /api/actions/action/{id}`: Delete action](#delete-apiactionsactionid-delete-action) - - [`GET /api/actions`: Get all actions](#get-apiactions-get-all-actions) - - [`GET /api/actions/action/{id}`: Get action](#get-apiactionsactionid-get-action) - - [`GET /api/actions/list_action_types`: List action types](#get-apiactionslist_action_types-list-action-types) - - [`PUT /api/actions/action/{id}`: Update action](#put-apiactionsactionid-update-action) - - [`POST /api/actions/action/{id}/_execute`: Execute action](#post-apiactionsactionid_execute-execute-action) - [Firing actions](#firing-actions) - [Accessing a scoped ActionsClient](#accessing-a-scoped-actionsclient) - [actionsClient.enqueueExecution(options)](#actionsclientenqueueexecutionoptions) @@ -119,14 +112,18 @@ Implemented under the [Actions Config](./server/actions_config.ts). ### Configuration Options -Built-In-Actions are configured using the _xpack.actions_ namespoace under _kibana.yml_, and have the following configuration options: +Built-In-Actions are configured using the _xpack.actions_ namespace under _kibana.yml_, and have the following configuration options: | Namespaced Key | Description | Type | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -| _xpack.actions._**enabled** | Feature toggle which enabled Actions in Kibana. | boolean | +| _xpack.actions._**enabled** | Feature toggle which enables Actions in Kibana. | boolean | | _xpack.actions._**allowedHosts** | Which _hostnames_ are allowed for the Built-In-Action? This list should contain hostnames of every external service you wish to interact with using Webhooks, Email or any other built in Action. Note that you may use the string "\*" in place of a specific hostname to enable Kibana to target any URL, but keep in mind the potential use of such a feature to execute [SSRF](https://www.owasp.org/index.php/Server_Side_Request_Forgery) attacks from your server. | Array | -| _xpack.actions._**enabledActionTypes** | A list of _actionTypes_ id's that are enabled. A "\*" may be used as an element to indicate all registered actionTypes should be enabled. The actionTypes registered for Kibana are `.server-log`, `.slack`, `.email`, `.index`, `.pagerduty`, `.webhook`. Default: `["*"]` | Array | +| _xpack.actions._**enabledActionTypes** | A list of _actionTypes_ IDs that are enabled. A "\*" may be used as an element to indicate all registered actionTypes should be enabled. The actionTypes registered for Kibana are `.email`, `.index`, `.jira`, `.pagerduty`, `.resilient`, `.server-log`, `.servicenow`, `.servicenow-sir`, `.slack`, `.teams`, `.webhook`. Default: `["*"]` | Array | | _xpack.actions._**preconfigured** | A object of action id / preconfigured actions. Default: `{}` | Array | +| _xpack.actions._**proxyUrl** | Specifies the proxy URL to use, if using a proxy for actions. | String | +| _xpack.actions._**proxyHeaders** | Specifies HTTP headers for proxy, if using a proxy for actions. | Object | +| _xpack.actions._**proxyRejectUnauthorizedCertificates** | Set to `false` to bypass certificate validation for proxy, if using a proxy for actions. | Boolean | +| _xpack.actions._**rejectUnauthorized** | Set to `false` to bypass certificate validation for actions. | Boolean | #### Adding Built-in Action Types to allowedHosts @@ -189,76 +186,7 @@ The built-in email action type provides a good example of creating an action typ ## RESTful API -Using an action type requires an action to be created that will contain and encrypt configuration for a given action type. See below for CRUD operations using the API. - -### `POST /api/actions/action`: Create action - -Payload: - -| Property | Description | Type | -| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -| name | A name to reference and search in the future. This value will be used to populate dropdowns. | string | -| actionTypeId | The id value of the action type you want to call when the action executes. | string | -| config | The configuration the action type expects. See related action type to see what attributes are expected. This will also validate against the action type if config validation is defined. | object | -| secrets | The secrets the action type expects. See related action type to see what attributes are expected. This will also validate against the action type if secrets validation is defined. | object | - -### `DELETE /api/actions/action/{id}`: Delete action - -Params: - -| Property | Description | Type | -| -------- | --------------------------------------------- | ------ | -| id | The id of the action you're trying to delete. | string | - -### `GET /api/actions`: Get all actions - -No parameters. - -Return all actions from saved objects merged with predefined list. -Use the [saved objects API for find](https://www.elastic.co/guide/en/kibana/master/saved-objects-api-find.html) with the proprties: `type: 'action'` and `perPage: 10000`. -List of predefined actions should be set up in Kibana.yaml. - -### `GET /api/actions/action/{id}`: Get action - -Params: - -| Property | Description | Type | -| -------- | ------------------------------------------ | ------ | -| id | The id of the action you're trying to get. | string | - -### `GET /api/actions/list_action_types`: List action types - -No parameters. - -### `PUT /api/actions/action/{id}`: Update action - -Params: - -| Property | Description | Type | -| -------- | --------------------------------------------- | ------ | -| id | The id of the action you're trying to update. | string | - -Payload: - -| Property | Description | Type | -| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -| name | A name to reference and search in the future. This value will be used to populate dropdowns. | string | -| config | The configuration the action type expects. See related action type to see what attributes are expected. This will also validate against the action type if config validation is defined. | object | -| secrets | The secrets the action type expects. See related action type to see what attributes are expected. This will also validate against the action type if secrets validation is defined. | object | - -### `POST /api/actions/action/{id}/_execute`: Execute action - -Params: - -| Property | Description | Type | -| -------- | ---------------------------------------------- | ------ | -| id | The id of the action you're trying to execute. | string | - -Payload: - -| Property | Description | Type | -| -------- | ---------------------------------------------------------- | ------ | -| params | The parameters the action type requires for the execution. | object | +Using an action type requires an action to be created that will contain and encrypt configuration for a given action type. See the [REST API Documentation](https://www.elastic.co/guide/en/kibana/master/actions-and-connectors-api.html) API for CRUD operations for Actions. ## Firing actions From b647e2cde1e370c58b95dfd8bb2790d58b9cc674 Mon Sep 17 00:00:00 2001 From: Ying Mao Date: Wed, 17 Feb 2021 11:24:11 -0500 Subject: [PATCH 2/8] Updating action config docs --- docs/user/alerting/defining-alerts.asciidoc | 1 + x-pack/plugins/actions/README.md | 98 ++++++++++----------- 2 files changed, 47 insertions(+), 52 deletions(-) diff --git a/docs/user/alerting/defining-alerts.asciidoc b/docs/user/alerting/defining-alerts.asciidoc index 6a599f1c3d3924..f88e4cd19c65f3 100644 --- a/docs/user/alerting/defining-alerts.asciidoc +++ b/docs/user/alerting/defining-alerts.asciidoc @@ -83,6 +83,7 @@ Actions are not required on alerts. In some cases you may want to run an alert w ============================================== [float] +[[actions-configuration]] === Global actions configuration Some actions configuration options apply to all actions. If you are using an *on-prem* Elastic Stack deployment, you can set these in the kibana.yml file. diff --git a/x-pack/plugins/actions/README.md b/x-pack/plugins/actions/README.md index 9e42a3ae4dbaed..e35a1f18870031 100644 --- a/x-pack/plugins/actions/README.md +++ b/x-pack/plugins/actions/README.md @@ -27,11 +27,11 @@ Table of Contents - [Example](#example) - [RESTful API](#restful-api) - [Firing actions](#firing-actions) - - [Accessing a scoped ActionsClient](#accessing-a-scoped-actionsclient) + - [Accessing a scoped ActionsClient](#accessing-a-scoped-actionsclient) - [actionsClient.enqueueExecution(options)](#actionsclientenqueueexecutionoptions) - - [Example](#example-1) + - [Example](#example-1) - [actionsClient.execute(options)](#actionsclientexecuteoptions) - - [Example](#example-2) + - [Example](#example-2) - [Built-in Action Types](#built-in-action-types) - [Server log](#server-log) - [`config`](#config) @@ -102,9 +102,9 @@ action types. ## Usage -1. Develop and register an action type (see action types -> example). -2. Create an action by using the RESTful API (see actions -> create action). -3. Use alerts to execute actions or execute manually (see firing actions). +1. Develop and register an action type (see [Action types -> Example](#example)). +2. Create an action by using the [RESTful API](#restful-api). +3. Use alerts to execute actions or execute manually (see [Firing actions](#firing-actions)). ## Kibana Actions Configuration @@ -112,54 +112,48 @@ Implemented under the [Actions Config](./server/actions_config.ts). ### Configuration Options -Built-In-Actions are configured using the _xpack.actions_ namespace under _kibana.yml_, and have the following configuration options: +Built-In-Actions are configured using the _xpack.actions_ namespace under _kibana.yml_. See the [Actions configuration Documentation](https://www.elastic.co/guide/en/kibana/master/defining-alerts.html#actions-configuration) for all configuration options. -| Namespaced Key | Description | Type | -| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -| _xpack.actions._**enabled** | Feature toggle which enables Actions in Kibana. | boolean | -| _xpack.actions._**allowedHosts** | Which _hostnames_ are allowed for the Built-In-Action? This list should contain hostnames of every external service you wish to interact with using Webhooks, Email or any other built in Action. Note that you may use the string "\*" in place of a specific hostname to enable Kibana to target any URL, but keep in mind the potential use of such a feature to execute [SSRF](https://www.owasp.org/index.php/Server_Side_Request_Forgery) attacks from your server. | Array | -| _xpack.actions._**enabledActionTypes** | A list of _actionTypes_ IDs that are enabled. A "\*" may be used as an element to indicate all registered actionTypes should be enabled. The actionTypes registered for Kibana are `.email`, `.index`, `.jira`, `.pagerduty`, `.resilient`, `.server-log`, `.servicenow`, `.servicenow-sir`, `.slack`, `.teams`, `.webhook`. Default: `["*"]` | Array | -| _xpack.actions._**preconfigured** | A object of action id / preconfigured actions. Default: `{}` | Array | -| _xpack.actions._**proxyUrl** | Specifies the proxy URL to use, if using a proxy for actions. | String | -| _xpack.actions._**proxyHeaders** | Specifies HTTP headers for proxy, if using a proxy for actions. | Object | -| _xpack.actions._**proxyRejectUnauthorizedCertificates** | Set to `false` to bypass certificate validation for proxy, if using a proxy for actions. | Boolean | -| _xpack.actions._**rejectUnauthorized** | Set to `false` to bypass certificate validation for actions. | Boolean | +#### **allowedHosts** configuration -#### Adding Built-in Action Types to allowedHosts +- You may use the string "*" in the **allowedHosts** configuration in place of a specific hostname to enable Kibana to target any URL, but keep in mind the potential to use such a feature to execute [SSRF](https://www.owasp.org/index.php/Server_Side_Request_Forgery) attacks from your server. -It is worth noting that the **allowedHosts** configuation applies to built-in action types (such as Slack, or PagerDuty) as well. - -Uniquely, the _PagerDuty Action Type_ has been configured to support the service's Events API (at _https://events.pagerduty.com/v2/enqueue_, which you can read about [here](https://v2.developer.pagerduty.com/docs/events-api-v2)) as a default, but this too, must be included in the allowedHosts before the PagerDuty action can be used. +- The **allowedHosts** configuration applies to built-in action types (such as Slack, or PagerDuty) as well. Uniquely, the _PagerDuty Action Type_ has been configured to support the service's Events API (at _https://events.pagerduty.com/v2/enqueue_, which you can read about [here](https://v2.developer.pagerduty.com/docs/events-api-v2)) as a default, but this too, must be included in the allowedHosts before the PagerDuty action can be used. ### Configuration Utilities -This module provides a Utilities for interacting with the configuration. +This module provides utilities for interacting with the configuration. -| Method | Arguments | Description | Return Type | -| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -| isUriAllowed | _uri_: The URI you wish to validate is allowed | Validates whether the URI is allowed. This checks the configuration and validates that the hostname of the URI is in the list of allowed Hosts and returns `true` if it is allowed. If the configuration says that all URI's are allowed (using an "\*") then it will always return `true`. | Boolean | -| isHostnameAllowed | _hostname_: The Hostname you wish to validate is allowed | Validates whether the Hostname is allowed. This checks the configuration and validates that the hostname is in the list of allowed Hosts and returns `true` if it is allowed. If the configuration says that all Hostnames are allowed (using an "\*") then it will always return `true`. | Boolean | -| isActionTypeEnabled | _actionType_: The actionType to check to see if it's enabled | Returns true if the actionType is enabled, otherwise false. | Boolean | -| ensureUriAllowed | _uri_: The URI you wish to validate is allowed | Validates whether the URI is allowed. This checks the configuration and validates that the hostname of the URI is in the list of allowed Hosts and throws an error if it is not allowed. If the configuration says that all URI's are allowed (using an "\*") then it will never throw. | No return value, throws if URI isn't allowed | -| ensureHostnameAllowed | _hostname_: The Hostname you wish to validate is allowed | Validates whether the Hostname is allowed. This checks the configuration and validates that the hostname is in the list of allowed Hosts and throws an error if it is not allowed. If the configuration says that all Hostnames are allowed (using an "\*") then it will never throw | No return value, throws if Hostname isn't allowed . | -| ensureActionTypeEnabled | _actionType_: The actionType to check to see if it's enabled | Throws an error if the actionType is not enabled | No return value, throws if actionType isn't enabled | +| Method | Arguments | Description | Return Type | +| - | - | - | - | +| isUriAllowed | _uri_: The URI you wish to validate is allowed | Validates whether the URI is allowed. This checks the configuration and validates that the hostname of the URI is in the list of allowed Hosts and returns `true` if it is allowed. If the configuration says that all URI's are allowed (using an "\*") then it will always return `true`. | Boolean | +| isHostnameAllowed | _hostname_: The Hostname you wish to validate is allowed | Validates whether the Hostname is allowed. This checks the configuration and validates that the hostname is in the list of allowed Hosts and returns `true` if it is allowed. If the configuration says that all Hostnames are allowed (using an "\*") then it will always return `true`. | Boolean | +| isActionTypeEnabled | _actionType_: The actionType to check to see if it's enabled | Returns true if the actionType is enabled, otherwise false. | Boolean | +| ensureUriAllowed | _uri_: The URI you wish to validate is allowed | Validates whether the URI is allowed. This checks the configuration and validates that the hostname of the URI is in the list of allowed Hosts and throws an error if it is not allowed. If the configuration says that all URI's are allowed (using an "\*") then it will never throw. | No return value, throws if URI isn't allowed | +| ensureHostnameAllowed | _hostname_: The Hostname you wish to validate is allowed | Validates whether the Hostname is allowed. This checks the configuration and validates that the hostname is in the list of allowed Hosts and throws an error if it is not allowed. If the configuration says that all Hostnames are allowed (using an "\*") then it will never throw. | No return value, throws if Hostname isn't allowed . | +| ensureActionTypeEnabled | _actionType_: The actionType to check to see if it's enabled | Throws an error if the actionType is not enabled. | No return value, throws if actionType isn't enabled | +| isRejectUnauthorizedCertificatesEnabled | _none_ | Returns value of `rejectUnauthorized` from configuration. | Boolean | +| getProxySettings | _none_ | If `proxyUrl` is set in the configuration, returns the proxy settings `proxyUrl`, `proxyHeaders` and `proxyRejectUnauthorizedCertificates`. Otherwise returns _undefined_. | Undefined or ProxySettings | ## Action types ### Methods -**server.plugins.actions.setup.registerType(options)** +**server.plugins.actions.setup.registerType (options)** The following table describes the properties of the `options` object. -| Property | Description | Type | -| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -| id | Unique identifier for the action type. For convention, ids starting with `.` are reserved for built in action types. We recommend using a convention like `.mySpecialAction` for your action types. | string | -| name | A user-friendly name for the action type. These will be displayed in dropdowns when chosing action types. | string | -| unencryptedAttributes | A list of opt-out attributes that don't need to be encrypted. These attributes won't need to be re-entered on import / export when the feature becomes available. These attributes will also be readable / displayed when it comes to a table / edit screen. | array of strings | -| validate.params | When developing an action type, it needs to accept parameters to know what to do with the action. (Example to, from, subject, body of an email). See the current built-in email action type for an example of the state-of-the-art validation.

Technically, the value of this property should have a property named `validate()` which is a function that takes a params object to validate and returns a sanitized version of that object to pass to the execution function. Validation errors should be thrown from the `validate()` function and will be available as an error message | schema / validation function | -| validate.config | Similar to params, a config is required when creating an action (for example host, port, username, and password of an email server). | schema / validation function | -| executor | This is where the code of an action type lives. This is a function gets called for executing an action from either alerting or manually by using the exposed function (see firing actions). For full details, see executor section below. | Function | +| Property | Description | Type | +| - | - | - | +| id | Unique identifier for the action type. For convention, ids starting with `.` are reserved for built in action types. We recommend using a convention like `.mySpecialAction` for your action types. | string | +| name | A user-friendly name for the action type. These will be displayed in dropdowns when chosing action types. | string | +| maxAttempts | The maximum number of times this action will attempt to execute when scheduled. | number | +| minimumLicenseRequired | The license required to use the action type. | string | +| validate.params | When developing an action type, it needs to accept parameters to know what to do with the action. (Example `to`, `from`, `subject`, `body` of an email). See the current built-in email action type for an example of the state-of-the-art validation.

Technically, the value of this property should have a property named `validate()` which is a function that takes a params object to validate and returns a sanitized version of that object to pass to the execution function. Validation errors should be thrown from the `validate()` function and will be available as an error message. | schema / validation function | +| validate.config | Similar to params, a config may be required when creating an action (for example `host` and `port` for an email server). | schema / validation function | +| validate.secrets | Similar to params, a secrets object may be required when creating an action (for example `user` and `password` for an email server). | schema / validation function | +| executor | This is where the code of an action type lives. This is a function gets called for executing an action from either alerting or manually by using the exposed function (see firing actions). For full details, see executor section below. | Function | +| renderParameterTemplates | Optionally define a function to provide custom rendering for this action type. | Function | **Important** - The config object is persisted in ElasticSearch and updated via the ElasticSearch update document API. This API allows "partial updates" - and this can cause issues with the encryption used on specified properties. So, a `validate()` function should return values for all configuration properties, so that partial updates do not occur. Setting property values to `null` rather than `undefined`, or not including a property in the config object, is all you need to do to ensure partial updates won't occur. @@ -169,15 +163,15 @@ This is the primary function for an action type. Whenever the action needs to ex **executor(options)** -| Property | Description | -| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| actionId | The action saved object id that the action type is executing for. | -| config | The decrypted configuration given to an action. This comes from the action saved object that is partially or fully encrypted within the data store. If you would like to validate the config before being passed to the executor, define `validate.config` within the action type. | -| params | Parameters for the execution. These will be given at execution time by either an alert or manually provided when calling the plugin provided execute function. | -| services.callCluster(path, opts) | Use this to do Elasticsearch queries on the cluster Kibana connects to. This function is the same as any other `callCluster` in Kibana but runs in the context of the user who is calling the action when security is enabled. | -| services.getLegacyScopedClusterClient | This function returns an instance of the LegacyScopedClusterClient scoped to the user who is calling the action when security is enabled. | -| services.savedObjectsClient | This is an instance of the saved objects client. This provides the ability to do CRUD on any saved objects within the same space the alert lives in.

The scope of the saved objects client is tied to the user in context calling the execute API or the API key provided to the execute plugin function (only when security isenabled). | -| services.log(tags, [data], [timestamp]) | Use this to create server logs. (This is the same function as server.log) | +| Property | Description | +| - | - | +| actionId | The action saved object id that the action type is executing for. | +| config | The action configuration. If you would like to validate the config before being passed to the executor, define `validate.config` within the action type. | +| secrets | The decrypted secrets object given to an action. This comes from the action saved object that is partially or fully encrypted within the data store. If you would like to validate the secrets object before being passed to the executor, define `validate.secrets` within the action type. | +| params | Parameters for the execution. These will be given at execution time by either an alert or manually provided when calling the plugin provided execute function. | +| services.callCluster(path, opts) | Use this to do Elasticsearch queries on the cluster Kibana connects to. This function is the same as any other `callCluster` in Kibana but runs in the context of the user who is calling the action when security is enabled. | +| services.getLegacyScopedClusterClient | This function returns an instance of the LegacyScopedClusterClient scoped to the user who is calling the action when security is enabled. | +| services.savedObjectsClient | This is an instance of the saved objects client. This provides the ability to do CRUD on any saved objects within the same space the alert lives in.

The scope of the saved objects client is tied to the user in context calling the execute API or the API key provided to the execute plugin function (only when security isenabled). | ### Example @@ -193,7 +187,7 @@ Using an action type requires an action to be created that will contain and encr Running actions is possible by using the ActionsClient which is provided by the `getActionsClientWithRequest` function part of the plugin's Start Contract. By providing the user's Request you'll receive an instance of the ActionsClient which is tailered to the current user and is scoped to the resources the user is authorized to access. -## Accessing a scoped ActionsClient +### Accessing a scoped ActionsClient ``` const actionsClient = server.plugins.actions.getActionsClientWithRequest(request); @@ -207,7 +201,7 @@ This api schedules a task which will run the action using the current user scope Running the action by scheduling a task means that we will no longer have a user request by which to ascertain the action's privileges and so you might need to provide these yourself: -- The **SpaceId** in which the user's action is expected to run +- The **spaceId** in which the user's action is expected to run - When security is enabled you'll also need to provide an **apiKey** which allows us to mimic the user and their privileges. The following table describes the properties of the `options` object. @@ -220,7 +214,7 @@ The following table describes the properties of the `options` object. | apiKey | The Elasticsearch API key to use for context. (Note: only required and used when security is enabled). | string | | source | The source of the execution, either an HTTP request or a reference to a Saved Object. | object, optional | -## Example +#### Example This example makes action `3c5b2bd4-5424-4e4b-8cf5-c0a58c762cc5` send an email. The action plugin will load the saved object and find what action type to call with `params`. @@ -252,7 +246,7 @@ The following table describes the properties of the `options` object. | params | The `params` value to give the action type executor. | object | | source | The source of the execution, either an HTTP request or a reference to a Saved Object. | object, optional | -## Example +#### Example As with the previous example, we'll use the action `3c5b2bd4-5424-4e4b-8cf5-c0a58c762cc5` to send an email. From 0d993d7b892a40575c4a5db09f2c2b258747f8cb Mon Sep 17 00:00:00 2001 From: Ying Mao Date: Wed, 17 Feb 2021 16:04:00 -0500 Subject: [PATCH 3/8] Cleaning up action type configs in README and user docs --- .../user/alerting/action-types/email.asciidoc | 21 +- .../user/alerting/action-types/index.asciidoc | 4 +- .../alerting/action-types/pagerduty.asciidoc | 24 +- .../alerting/action-types/server-log.asciidoc | 1 + .../alerting/action-types/servicenow.asciidoc | 68 ++++- .../user/alerting/action-types/slack.asciidoc | 15 +- .../alerting/action-types/webhook.asciidoc | 18 +- x-pack/plugins/actions/README.md | 270 +----------------- 8 files changed, 117 insertions(+), 304 deletions(-) diff --git a/docs/user/alerting/action-types/email.asciidoc b/docs/user/alerting/action-types/email.asciidoc index 3562be1e405f6f..0404f0b1a5dd2a 100644 --- a/docs/user/alerting/action-types/email.asciidoc +++ b/docs/user/alerting/action-types/email.asciidoc @@ -11,12 +11,12 @@ The email action type uses the SMTP protocol to send mail message, using an inte Email connectors have the following configuration properties: Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action. -Sender:: The from address for all emails sent with this connector, specified in `user@host-name` format. +Sender:: The from address for all emails sent with this connector. This can be specified in `user@host-name` format or as `"human name "` format. See the [nodemailer address documentation](https://nodemailer.com/message/addresses/) for more information. Host:: Host name of the service provider. If you are using the <> setting, make sure this hostname is added to the allowed hosts. Port:: The port to connect to on the service provider. Secure:: If true, the connection will use TLS when connecting to the service provider. Refer to the https://nodemailer.com/smtp/#tls-options[Nodemailer TLS documentation] for more information. If not true, the connection will initially connect over TCP, then attempt to switch to TLS via the SMTP STARTTLS command. -Username:: username for 'login' type authentication. -Password:: password for 'login' type authentication. +User:: Username for 'login' type authentication. +Password:: Password for 'login' type authentication. [float] [[Preconfigured-email-configuration]] @@ -38,11 +38,14 @@ Password:: password for 'login' type authentication. -- [[email-connector-config-properties]] -`config` defines the action type specific to the configuration and contains the following properties: +**`config`** defines the action type specific to the configuration and contains the following properties: [cols="2*<"] |=== +| `service` +| The name of a [well-known email service provider](https://nodemailer.com/smtp/well-known/) value. If `service` is provided, `host`, `port`, and `secure` properties are ignored. For more information on the `gmail` service value specifically, see the [nodemailer gmail documentation](https://nodemailer.com/usage/using-gmail/). + | `from` | An email address that corresponds to *Sender*. @@ -55,18 +58,22 @@ Password:: password for 'login' type authentication. | `secure` | A boolean that corresponds to *Secure*. +| `hasAuth` +| If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`. + |=== -`secrets` defines sensitive information for the action type: +[[email-connector-secret-properties]] +**`secrets`** defines sensitive information for the action type and contains the following properties: [cols="2*<"] |=== | `user` -| A string that corresponds to *User*. +| A string that corresponds to *User*. Required if `hasAuth` is set to `true`. | `password` -| A string that corresponds to *Password*. Should be stored in the <>. +| A string that corresponds to *Password*. Should be stored in the <>. Required if `hasAuth` is set to `true`. |=== diff --git a/docs/user/alerting/action-types/index.asciidoc b/docs/user/alerting/action-types/index.asciidoc index 2f459edea28f14..7ecc1cdb4f74e8 100644 --- a/docs/user/alerting/action-types/index.asciidoc +++ b/docs/user/alerting/action-types/index.asciidoc @@ -31,7 +31,7 @@ Execution time field:: This field will be automatically set to the time the ale -- [[index-connector-config-properties]] -`config` defines the action type specific to the configuration and contains the following properties: +**`config`** defines the action type specific to the configuration and contains the following properties: [cols="2*<"] |=== @@ -40,7 +40,7 @@ Execution time field:: This field will be automatically set to the time the ale | A string that corresponds to *Index*. |`refresh` -| A boolean that corresponds to *Refresh*. +| A boolean that corresponds to *Refresh*. Defaults to `false`. |`executionTimeField` | A string that corresponds to *Execution time field*. diff --git a/docs/user/alerting/action-types/pagerduty.asciidoc b/docs/user/alerting/action-types/pagerduty.asciidoc index e1078a55ddd0d5..835f748fb738f4 100644 --- a/docs/user/alerting/action-types/pagerduty.asciidoc +++ b/docs/user/alerting/action-types/pagerduty.asciidoc @@ -151,14 +151,26 @@ Integration Key:: A 32 character PagerDuty Integration Key for an integration -- [[pagerduty-connector-config-properties]] -`config` defines the action type specific to the configuration. -`config` contains -`apiURL`, a string that corresponds to *API URL*. +**`config`** defines the action type specific to the configuration and contains the following properties: -`secrets` defines sensitive information for the action type. -`secrets` contains -`routingKey`, a string that corresponds to *Integration Key*. +[cols="2*<"] +|=== +|`apiURL` +| A URL string that corresponds to *API URL*. + +|=== + +[[pagerduty-connector-secrets-properties]] +**`secrets`** defines sensitive information for the action type and contains the following properties: + +[cols="2*<"] +|=== + +|`routingKey` +| A string that corresponds to *Integration Key*. + +|=== [float] [[pagerduty-action-configuration]] diff --git a/docs/user/alerting/action-types/server-log.asciidoc b/docs/user/alerting/action-types/server-log.asciidoc index 7022320328c859..f66e1714b8c73c 100644 --- a/docs/user/alerting/action-types/server-log.asciidoc +++ b/docs/user/alerting/action-types/server-log.asciidoc @@ -30,3 +30,4 @@ Name:: The name of the connector. The name is used to identify a connector Server log actions have the following properties: Message:: The message to log. +Level:: The log level of the message. Either `trace`, `debug`, `info`, `warn`, `error` or `fatal`. Defaults to `info`. diff --git a/docs/user/alerting/action-types/servicenow.asciidoc b/docs/user/alerting/action-types/servicenow.asciidoc index 5d8782c14e5815..674f9ea0ce33b6 100644 --- a/docs/user/alerting/action-types/servicenow.asciidoc +++ b/docs/user/alerting/action-types/servicenow.asciidoc @@ -32,7 +32,7 @@ Password:: Password for HTTP Basic authentication. -- [[servicenow-connector-config-properties]] -`config` defines the action type specific to the configuration and contains the following properties: +**`config`** defines the action type specific to the configuration and contains the following properties: [cols="2*<"] |=== @@ -42,7 +42,8 @@ Password:: Password for HTTP Basic authentication. |=== -`secrets` defines sensitive information for the action type: +[[servicenow-connector-secrets-properties]] +**`secrets`** defines sensitive information for the action type and contains the following properties: [cols="2*<"] |=== @@ -60,12 +61,63 @@ Password:: Password for HTTP Basic authentication. ServiceNow actions have the following configuration properties: -Urgency:: The extent to which the incident resolution can delay. -Severity:: The severity of the incident. -Impact:: The effect an incident has on business. Can be measured by the number of affected users or by how critical it is to the business in question. -Short description:: A short description for the incident, used for searching the contents of the knowledge base. -Description:: The details about the incident. -Additional comments:: Additional information for the client, such as how to troubleshoot the issue. +Subaction:: The sub action to perform. It can be `pushToService`, `getFields`, `getIncident`, and `getChoices`. +Subaction Params:: The parameters of the subaction. + +===== pushToService subaction configuration + +Incident:: The ServiceNow incident. + +[cols="3*<"] +|=== + +| `short_description` +| A short description for the incident, used for searching the contents of the knowledge base. +| string + +| `description` +| The details about the incident. +| string _(optional)_ + +| `externalId` +| The id of the incident in ServiceNow. If presented the incident will be update. Otherwise a new incident will be created. +| string _(optional)_ + +| `severity` +| The severity of the incident. +| string _(optional)_ + +| `urgency` +| The extent to which the incident resolution can delay. +| string _(optional)_ + +| `impact` +| The effect an incident has on business. Can be measured by the number of affected users or by how critical it is to the business in question. +| string _(optional)_ + +| `category` +| The name of the category in ServiceNow. +| string _(optional)_ + +| `subcategory` +| The name of the subcategory in ServiceNow. +| string _(optional)_ + +|=== + +Comments:: The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. + +===== getFields subaction configuration + +No parameters for `getFields` sub-action. Provide an empty object `{}`. + +===== getIncident subaction configuration + +External ID:: The id of the incident in ServiceNow. + +===== getChoices subaction configuration + +Fields:: An array of fields. Example: `[priority, category, impact]`. [[configuring-servicenow]] ==== Configuring and testing ServiceNow diff --git a/docs/user/alerting/action-types/slack.asciidoc b/docs/user/alerting/action-types/slack.asciidoc index 6a38e5c827ab28..13387d8c430189 100644 --- a/docs/user/alerting/action-types/slack.asciidoc +++ b/docs/user/alerting/action-types/slack.asciidoc @@ -22,15 +22,20 @@ Webhook URL:: The URL of the incoming webhook. See https://api.slack.com/messa my-slack: name: preconfigured-slack-action-type actionTypeId: .slack - config: + secrets: webhookUrl: 'https://hooks.slack.com/services/abcd/efgh/ijklmnopqrstuvwxyz' -- -[[slack-connector-config-properties]] -`config` defines the action type specific to the configuration. -`config` contains -`webhookUrl`, a string that corresponds to *Webhook URL*. +[[slack-connector-secrets-properties]] +**`secrets`** defines sensitive information for the action type and contains the following properties: +[cols="2*<"] +|=== + +| `webhookUrl` +| A string that corresponds to *Webhook URL*. + +|=== [float] [[slack-action-configuration]] diff --git a/docs/user/alerting/action-types/webhook.asciidoc b/docs/user/alerting/action-types/webhook.asciidoc index 2d626d53d1c77e..9092b6f8e166c1 100644 --- a/docs/user/alerting/action-types/webhook.asciidoc +++ b/docs/user/alerting/action-types/webhook.asciidoc @@ -12,10 +12,10 @@ Webhook connectors have the following configuration properties: Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action. URL:: The request URL. If you are using the <> setting, make sure the hostname is added to the allowed hosts. -Method:: HTTP request method, either `post`(default) or `put`. +Method:: HTTP request method, either `POST`(default) or `PUT`. Headers:: A set of key-value pairs sent as headers with the request -User:: An optional username. If set, HTTP basic authentication is used. Currently only basic authentication is supported. -Password:: An optional password. If set, HTTP basic authentication is used. Currently only basic authentication is supported. +User:: Username for HTTP basic authentication. +Password:: Password for HTTP basic authentication. [float] [[Preconfigured-webhook-configuration]] @@ -37,7 +37,7 @@ Password:: An optional password. If set, HTTP basic authentication is used. Cur -- [[webhook-connector-config-properties]] -`config` defines the action type specific to the configuration and contains the following properties: +**`config`** defines the action type specific to the configuration and contains the following properties: [cols="2*<"] |=== @@ -51,18 +51,22 @@ Password:: An optional password. If set, HTTP basic authentication is used. Cur |`headers` |A record that corresponds to *Headers*. +| `hasAuth` +| If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`. + |=== -`secrets` defines sensitive information for the action type: +[[webhook-connector-secret-properties]] +**`secrets`** defines sensitive information for the action type and contains the following properties: [cols="2*<"] |=== |`user` -|A string that corresponds to *User*. +|A string that corresponds to *User*. Required if `hasAuth` is set to `true`. |`password` -|A string that corresponds to *Password*. Should be stored in the <>. +|A string that corresponds to *Password*. Should be stored in the <>. Required if `hasAuth` is set to `true`. |=== diff --git a/x-pack/plugins/actions/README.md b/x-pack/plugins/actions/README.md index e35a1f18870031..2269491d226393 100644 --- a/x-pack/plugins/actions/README.md +++ b/x-pack/plugins/actions/README.md @@ -269,275 +269,7 @@ const result = await actionsClient.execute({ # Built-in Action Types -Kibana ships with a set of built-in action types: - -| Type | Id | Description | -| ------------------------------- | ----------------- | ------------------------------------------------------------------ | -| [Server log](#server-log) | `.server-log` | Logs messages to the Kibana log using Kibana's logger | -| [Email](#email) | `.email` | Sends an email using SMTP | -| [Slack](#slack) | `.slack` | Posts a message to a slack channel | -| [Index](#index) | `.index` | Indexes document(s) into Elasticsearch | -| [Webhook](#webhook) | `.webhook` | Send a payload to a web service using HTTP POST or PUT | -| [PagerDuty](#pagerduty) | `.pagerduty` | Trigger, resolve, or acknowlege an incident to a PagerDuty service | -| [ServiceNow ITSM](#servicenow) | `.servicenow` | Create or update an incident to a ServiceNow ITSM instance | -| [ServiceNow SIR](#servicenow) | `.servicenow-sir` | Create or update an incident to a ServiceNow SIR instance | -| [Jira](#jira) | `.jira` | Create or update an issue to a Jira instance | -| [IBM Resilient](#ibm-resilient) | `.resilient` | Create or update an incident to a IBM Resilient instance | - ---- - -## Server log - -ID: `.log` - -The params properties are modelled after the arguments to the [Hapi.server.log()](https://hapijs.com/api#-serverlogtags-data-timestamp) function. - -### `config` - -This action has no `config` properties. - -### `secrets` - -This action type has no `secrets` properties. - -### `params` - -| Property | Description | Type | -| -------- | ---------------------------------------- | --------------------- | -| message | The message to log. | string | -| tags | Tags associated with the message to log. | string[] _(optional)_ | - ---- - -## Email - -ID: `.email` - -This action type uses [nodemailer](https://nodemailer.com/about/) to send emails. - -### `config` - -Either the property `service` must be provided, or the `host` and `port` properties must be provided. If `service` is provided, `host`, `port` and `secure` are ignored. For more information on the `gmail` service value specifically, see the [nodemailer gmail documentation](https://nodemailer.com/usage/using-gmail/). - -The `secure` property defaults to `false`. See the [nodemailer TLS documentation](https://nodemailer.com/smtp/#tls-options) for more information. - -The `from` field can be specified as in typical `"user@host-name"` format, or as `"human name "` format. See the [nodemailer address documentation](https://nodemailer.com/message/addresses/) for more information. - -| Property | Description | Type | -| -------- | ------------------------------------------------------------------------------------------ | -------------------- | -| service | the name of a [well-known email service provider](https://nodemailer.com/smtp/well-known/) | string _(optional)_ | -| host | host name of the service provider | string _(optional)_ | -| port | port number of the service provider | number _(optional)_ | -| secure | whether to use TLS with the service provider | boolean _(optional)_ | -| from | the from address for all emails sent with this action type | string | - -### `secrets` - -| Property | Description | Type | -| -------- | ----------------------------------------- | ------ | -| user | userid to use with the service provider | string | -| password | password to use with the service provider | string | - -### `params` - -There must be at least one entry in the `to`, `cc` and `bcc` arrays. - -The message text will be sent as both plain text and html text. Additional function may be provided later. - -The `to`, `cc`, and `bcc` array entries can be in the same format as the `from` property described in the config object above. - -| Property | Description | Type | -| -------- | ----------------------------- | --------------------- | -| to | list of to addressees | string[] _(optional)_ | -| cc | list of cc addressees | string[] _(optional)_ | -| bcc | list of bcc addressees | string[] _(optional)_ | -| subject | the subject line of the email | string | -| message | the message text | string | - ---- - -## Slack - -ID: `.slack` - -This action type interfaces with the [Slack Incoming Webhooks feature](https://api.slack.com/incoming-webhooks). Currently the params property `message` will be used as the `text` property of the Slack incoming message. Additional function may be provided later. - -### `config` - -This action type has no `config` properties. - -### `secrets` - -| Property | Description | Type | -| ---------- | ------------------------------------- | ------ | -| webhookUrl | the url of the Slack incoming webhook | string | - -### `params` - -| Property | Description | Type | -| -------- | ---------------- | ------ | -| message | the message text | string | - ---- - -## Index - -ID: `.index` - -The config and params properties are modelled after the [Watcher Index Action](https://www.elastic.co/guide/en/elasticsearch/reference/master/actions-index.html). The index can be set in the config or params, and if set in config, then the index set in the params will be ignored. - -### `config` - -| Property | Description | Type | -| -------------------- | ---------------------------------------------------------- | -------------------- | -| index | The Elasticsearch index to index into. | string _(optional)_ | -| doc_id | The optional \_id of the document. | string _(optional)_ | -| execution_time_field | The field that will store/index the action execution time. | string _(optional)_ | -| refresh | Setting of the refresh policy for the write request. | boolean _(optional)_ | - -### `secrets` - -This action type has no `secrets` properties. - -### `params` - -| Property | Description | Type | -| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| documents | JSON object that describes the [document](https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started-index.html#getting-started-batch-processing). | object[] | - ---- - -## Webhook - -ID: `.webhook` - -The webhook action uses [axios](https://github.com/axios/axios) to send a POST or PUT request to a web service. - -### `config` - -| Property | Description | Type | -| -------- | ------------------------------------------------------- | ------------------------------------------------ | -| url | Request URL | string | -| method | HTTP request method, either `post`_(default)_ or `put` | string _(optional)_ | -| headers | Key-value pairs of the headers to send with the request | object, keys and values are strings _(optional)_ | - -### `secrets` - -| Property | Description | Type | -| -------- | -------------------------------------- | ------------------- | -| user | Username for HTTP Basic authentication | string _(optional)_ | -| password | Password for HTTP Basic authentication | string _(optional)_ | - -### `params` - -| Property | Description | Type | -| -------- | --------------------- | ------------------- | -| body | The HTTP request body | string _(optional)_ | - ---- - -## PagerDuty - -ID: `.pagerduty` - -The PagerDuty action uses the [V2 Events API](https://v2.developer.pagerduty.com/docs/events-api-v2) to trigger, acknowlege, and resolve PagerDuty alerts. - -### `config` - -| Property | Description | Type | -| -------- | -------------------------------------------------------------------------- | ------------------- | -| apiUrl | PagerDuty event URL. Defaults to `https://events.pagerduty.com/v2/enqueue` | string _(optional)_ | - -### `secrets` - -| Property | Description | Type | -| ---------- | ---------------------------------------------------------------------------------------------------------- | ------ | -| routingKey | This is the 32 character PagerDuty Integration Key for an integration on a service or on a global ruleset. | string | - -### `params` - -| Property | Description | Type | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | -| eventAction | One of `trigger` _(default)_, `resolve`, or `acknowlege`. See [event action](https://v2.developer.pagerduty.com/docs/events-api-v2#event-action) for more details. | string _(optional)_ | -| dedupKey | All actions sharing this key will be associated with the same PagerDuty alert. Used to correlate trigger and resolution. The maximum length is **255** characters. See [alert deduplication](https://v2.developer.pagerduty.com/docs/events-api-v2#alert-de-duplication) for details. | string _(optional)_ | -| summary | A text summary of the event, defaults to `No summary provided`. The maximum length is **1024** characters. | string _(optional)_ | -| source | The affected system, preferably a hostname or fully qualified domain name. Defaults to `Kibana Action `. | string _(optional)_ | -| severity | The perceived severity of on the affected system. This can be one of `critical`, `error`, `warning` or `info`_(default)_. | string _(optional)_ | -| timestamp | An [ISO-8601 format date-time](https://v2.developer.pagerduty.com/v2/docs/types#datetime), indicating the time the event was detected or generated. | string _(optional)_ | -| component | The component of the source machine that is responsible for the event, for example `mysql` or `eth0`. | string _(optional)_ | -| group | Logical grouping of components of a service, for example `app-stack`. | string _(optional)_ | -| class | The class/type of the event, for example `ping failure` or `cpu load`. | string _(optional)_ | - -For more details see [PagerDuty v2 event parameters](https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2). - ---- - -## ServiceNow - -ServiceNow ITSM ID: `.servicenow` - -ServiceNow SIR ID: `.servicenow-sir` - -The ServiceNow actions use the [V2 Table API](https://developer.servicenow.com/app.do#!/rest_api_doc?v=orlando&id=c_TableAPI) to create and update ServiceNow incidents. Both action types use the same `config`, `secrets`, and `params` schema. - -### `config` - -| Property | Description | Type | -| -------- | ------------------------ | ------ | -| apiUrl | ServiceNow instance URL. | string | - -### `secrets` - -| Property | Description | Type | -| -------- | -------------------------------------- | ------ | -| username | Username for HTTP Basic authentication | string | -| password | Password for HTTP Basic authentication | string | - -### `params` - -| Property | Description | Type | -| --------------- | -------------------------------------------------------------------------------------------------- | ------ | -| subAction | The sub action to perform. It can be `pushToService`, `getFields`, `getIncident`, and `getChoices` | string | -| subActionParams | The parameters of the sub action | object | - -#### `subActionParams (pushToService)` - -| Property | Description | Type | -| -------- | ------------------------------------------------------------------------------------------------------------- | --------------------- | -| incident | The ServiceNow incident. | object | -| comments | The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. | object[] _(optional)_ | - -The following table describes the properties of the `incident` object. - -| Property | Description | Type | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------- | -| short_description | The title of the incident. | string | -| description | The description of the incident. | string _(optional)_ | -| externalId | The id of the incident in ServiceNow. If presented the incident will be update. Otherwise a new incident will be created. | string _(optional)_ | -| severity | The name of the severity in ServiceNow. | string _(optional)_ | -| urgency | The name of the urgency in ServiceNow. | string _(optional)_ | -| impact | The name of the impact in ServiceNow. | string _(optional)_ | -| category | The name of the category in ServiceNow. | string _(optional)_ | -| subcategory | The name of the subcategory in ServiceNow. | string _(optional)_ | - -#### `subActionParams (getFields)` - -No parameters for `getFields` sub-action. Provide an empty object `{}`. - -#### `subActionParams (getIncident)` - -| Property | Description | Type | -| ---------- | ------------------------------------- | ------ | -| externalId | The id of the incident in ServiceNow. | string | - - -#### `subActionParams (getChoices)` - -| Property | Description | Type | -| -------- | ------------------------------------------------------------ | -------- | -| fields | An array of fields. Example: `[priority, category, impact]`. | string[] | - ---- +Kibana ships with a set of built-in action types. See [Actions and connector types Documentation](https://www.elastic.co/guide/en/kibana/master/action-types.html). ## Jira From c06727364ead891d66d6c7305d5eb027ece88004 Mon Sep 17 00:00:00 2001 From: Ying Mao Date: Wed, 17 Feb 2021 22:02:06 -0500 Subject: [PATCH 4/8] Cleaning up action type configs in README and user docs --- .../user/alerting/action-types/email.asciidoc | 1 - docs/user/alerting/action-types/jira.asciidoc | 50 +++++-- .../alerting/action-types/pagerduty.asciidoc | 1 - .../alerting/action-types/resilient.asciidoc | 33 ++++- .../alerting/action-types/servicenow.asciidoc | 63 +++------ .../user/alerting/action-types/slack.asciidoc | 1 - .../user/alerting/action-types/teams.asciidoc | 14 +- .../alerting/action-types/webhook.asciidoc | 1 - x-pack/plugins/actions/README.md | 130 ------------------ 9 files changed, 92 insertions(+), 202 deletions(-) diff --git a/docs/user/alerting/action-types/email.asciidoc b/docs/user/alerting/action-types/email.asciidoc index 0404f0b1a5dd2a..62ce57cb74bda0 100644 --- a/docs/user/alerting/action-types/email.asciidoc +++ b/docs/user/alerting/action-types/email.asciidoc @@ -63,7 +63,6 @@ Password:: Password for 'login' type authentication. |=== -[[email-connector-secret-properties]] **`secrets`** defines sensitive information for the action type and contains the following properties: [cols="2*<"] diff --git a/docs/user/alerting/action-types/jira.asciidoc b/docs/user/alerting/action-types/jira.asciidoc index 6e47d5618d5982..3bbe5536a545a3 100644 --- a/docs/user/alerting/action-types/jira.asciidoc +++ b/docs/user/alerting/action-types/jira.asciidoc @@ -34,7 +34,7 @@ API token (or password):: Jira API authentication token (or password) for HTTP -- [[jira-connector-config-properties]] -`config` defines the action type specific to the configuration and contains the following properties: +**`config`** defines the action type specific to the configuration and contains the following properties: [cols="2*<"] |=== @@ -47,7 +47,7 @@ API token (or password):: Jira API authentication token (or password) for HTTP |=== -`secrets` defines sensitive information for the action type: +**`secrets`** defines sensitive information for the action type and contains the following properties: [cols="2*<"] |=== @@ -65,14 +65,44 @@ API token (or password):: Jira API authentication token (or password) for HTTP Jira actions have the following configuration properties: -Issue type:: The type of the issue. -Priority:: The priority of the incident. -Labels:: The labels of the incident. -Title:: A title for the issue, used for searching the contents of the knowledge base. -Description:: The details about the incident. -Parent:: The parent issue id or key. Only for `Sub-task` issue types. -Priority:: The priority of the incident. -Additional comments:: Additional information for the client, such as how to troubleshoot the issue. +Subaction:: The subaction to perform. Either `pushToService`, `getIncident`, `issueTypes`, `fieldsByIssueType`, `issues`, `issue`, or `getFields`. +Subaction Params:: The parameters of the subaction. + +==== `pushToService` subaction configuration + +Incident:: The Jira incident which has the following properties: +* `summary` - The title of the issue. +* `description` - The description of the issue. +* `externalId` - The id of the issue in Jira. If present the issue will be updated. Otherwise a new issue will be created. +* `issueType` - The id of the issue type in Jira. +* `priority` - The name of the priority in Jira. Example: `Medium`. +* `labels` - An array of labels. Labels cannot contain spaces. +* `parent` - The parent issue id or key. Only for Sub-task issue types. +Comments:: The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. + +==== `getIncident` subaction configuration + +External ID:: The id of the issue in Jira. + +==== `issueTypes` subaction configuration + +No parameters for `issueTypes` subaction. Provide an empty object `{}`. + +==== `fieldsByIssueType` subaction configuration + +ID:: The id of the issue in Jira. + +==== `issues` subaction configuration + +Title:: The title to search for. + +==== `issue` subaction configuration + +ID:: The id of the issue in Jira. + +==== `getFields` subaction configuration + +No parameters for `getFields` subaction. Provide an empty object `{}`. [[configuring-jira]] ==== Configuring and testing Jira diff --git a/docs/user/alerting/action-types/pagerduty.asciidoc b/docs/user/alerting/action-types/pagerduty.asciidoc index 835f748fb738f4..c3185aaad553a6 100644 --- a/docs/user/alerting/action-types/pagerduty.asciidoc +++ b/docs/user/alerting/action-types/pagerduty.asciidoc @@ -161,7 +161,6 @@ Integration Key:: A 32 character PagerDuty Integration Key for an integration |=== -[[pagerduty-connector-secrets-properties]] **`secrets`** defines sensitive information for the action type and contains the following properties: [cols="2*<"] diff --git a/docs/user/alerting/action-types/resilient.asciidoc b/docs/user/alerting/action-types/resilient.asciidoc index 112246ab91162e..6754dc0ddb50e4 100644 --- a/docs/user/alerting/action-types/resilient.asciidoc +++ b/docs/user/alerting/action-types/resilient.asciidoc @@ -34,7 +34,7 @@ API key secret:: The authentication key secret for HTTP Basic authentication. -- [[resilient-connector-config-properties]] -`config` defines the action type specific to the configuration and contains the following properties: +**`config`** defines the action type specific to the configuration and contains the following properties: [cols="2*<"] |=== @@ -47,7 +47,7 @@ API key secret:: The authentication key secret for HTTP Basic authentication. |=== -`secrets` defines sensitive information for the action type: +**`secrets`** defines sensitive information for the action type and contains the following properties: [cols="2*<"] |=== @@ -65,11 +65,30 @@ API key secret:: The authentication key secret for HTTP Basic authentication. IBM Resilient actions have the following configuration properties: -Incident types:: The incident types of the incident. -Severity code:: The severity of the incident. -Name:: A name for the issue, used for searching the contents of the knowledge base. -Description:: The details about the incident. -Additional comments:: Additional information for the client, such as how to troubleshoot the issue. +Subaction:: The subaction to perform. Either `pushToService`, `getFields`, `incidentTypes`, or `severity`. +Subaction Params:: The parameters of the subaction. + +==== `pushToService` subaction configuration + +Incident:: The IBM resilient incident which has the following properties: +* `name` - A name for the issue, used for searching the contents of the knowledge base. +* `description` - The details about the incident. +* `externalId` - The id of the incident in IBM Resilient. If present the incident will be updated. Otherwise a new incident will be created. +* `incidentTypes` - An array with the ids of IBM Resilient incident types. +* `severityCode` - IBM Resilient id of the severity code. +Comments:: The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. + +===== `getFields` subaction configuration + +No parameters for `getFields` subaction. Provide an empty object `{}`. + +===== `incidentTypes` subaction configuration + +No parameters for `incidentTypes` subaction. Provide an empty object `{}`. + +===== `severity` subaction configuration + +No parameters for `severity` subaction. Provide an empty object `{}`. [[configuring-resilient]] ==== Configuring and testing IBM Resilient diff --git a/docs/user/alerting/action-types/servicenow.asciidoc b/docs/user/alerting/action-types/servicenow.asciidoc index 674f9ea0ce33b6..a3447a3310d974 100644 --- a/docs/user/alerting/action-types/servicenow.asciidoc +++ b/docs/user/alerting/action-types/servicenow.asciidoc @@ -42,7 +42,6 @@ Password:: Password for HTTP Basic authentication. |=== -[[servicenow-connector-secrets-properties]] **`secrets`** defines sensitive information for the action type and contains the following properties: [cols="2*<"] @@ -61,61 +60,31 @@ Password:: Password for HTTP Basic authentication. ServiceNow actions have the following configuration properties: -Subaction:: The sub action to perform. It can be `pushToService`, `getFields`, `getIncident`, and `getChoices`. +Subaction:: The subaction to perform. Either `pushToService`, `getFields`, `getIncident`, or `getChoices`. Subaction Params:: The parameters of the subaction. -===== pushToService subaction configuration - -Incident:: The ServiceNow incident. - -[cols="3*<"] -|=== - -| `short_description` -| A short description for the incident, used for searching the contents of the knowledge base. -| string - -| `description` -| The details about the incident. -| string _(optional)_ - -| `externalId` -| The id of the incident in ServiceNow. If presented the incident will be update. Otherwise a new incident will be created. -| string _(optional)_ - -| `severity` -| The severity of the incident. -| string _(optional)_ - -| `urgency` -| The extent to which the incident resolution can delay. -| string _(optional)_ - -| `impact` -| The effect an incident has on business. Can be measured by the number of affected users or by how critical it is to the business in question. -| string _(optional)_ - -| `category` -| The name of the category in ServiceNow. -| string _(optional)_ - -| `subcategory` -| The name of the subcategory in ServiceNow. -| string _(optional)_ - -|=== - +==== `pushToService` subaction configuration + +Incident:: The ServiceNow incident which has the following properties: +* `short_description` - A short description for the incident, used for searching the contents of the knowledge base. +* `description` - The details about the incident. +* `externalId` - The id of the incident in ServiceNow. If present the incident will be updated. Otherwise a new incident will be created. +* `severity` - The severity of the incident. +* `urgency` - The extent to which the incident resolution can delay. +* `impact` - The effect an incident has on business. Can be measured by the number of affected users or by how critical it is to the business in question. +* `category` - The name of the category in ServiceNow. +* `subcategory` - The name of the subcategory in ServiceNow. Comments:: The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. -===== getFields subaction configuration +===== `getFields` subaction configuration -No parameters for `getFields` sub-action. Provide an empty object `{}`. +No parameters for `getFields` subaction. Provide an empty object `{}`. -===== getIncident subaction configuration +===== `getIncident` subaction configuration External ID:: The id of the incident in ServiceNow. -===== getChoices subaction configuration +===== `getChoices` subaction configuration Fields:: An array of fields. Example: `[priority, category, impact]`. diff --git a/docs/user/alerting/action-types/slack.asciidoc b/docs/user/alerting/action-types/slack.asciidoc index 13387d8c430189..62589697533562 100644 --- a/docs/user/alerting/action-types/slack.asciidoc +++ b/docs/user/alerting/action-types/slack.asciidoc @@ -26,7 +26,6 @@ Webhook URL:: The URL of the incoming webhook. See https://api.slack.com/messa webhookUrl: 'https://hooks.slack.com/services/abcd/efgh/ijklmnopqrstuvwxyz' -- -[[slack-connector-secrets-properties]] **`secrets`** defines sensitive information for the action type and contains the following properties: [cols="2*<"] diff --git a/docs/user/alerting/action-types/teams.asciidoc b/docs/user/alerting/action-types/teams.asciidoc index e1ce91fc0c1231..7f4a29dc86fc52 100644 --- a/docs/user/alerting/action-types/teams.asciidoc +++ b/docs/user/alerting/action-types/teams.asciidoc @@ -22,14 +22,20 @@ Webhook URL:: The URL of the incoming webhook. See https://docs.microsoft.com/ my-teams: name: preconfigured-teams-action-type actionTypeId: .teams - config: + secrets: webhookUrl: 'https://outlook.office.com/webhook/abcd@0123456/IncomingWebhook/abcdefgh/ijklmnopqrstuvwxyz' -- [[teams-connector-config-properties]] -`config` defines the action type specific to the configuration. -`config` contains -`webhookUrl`, a string that corresponds to *Webhook URL*. +**`secrets`** defines sensitive information for the action type and contains the following properties: + +[cols="2*<"] +|=== + +| `webhookUrl` +| A string that corresponds to *Webhook URL*. + +|=== [float] diff --git a/docs/user/alerting/action-types/webhook.asciidoc b/docs/user/alerting/action-types/webhook.asciidoc index 9092b6f8e166c1..efe1077707ef09 100644 --- a/docs/user/alerting/action-types/webhook.asciidoc +++ b/docs/user/alerting/action-types/webhook.asciidoc @@ -56,7 +56,6 @@ Password:: Password for HTTP basic authentication. |=== -[[webhook-connector-secret-properties]] **`secrets`** defines sensitive information for the action type and contains the following properties: [cols="2*<"] diff --git a/x-pack/plugins/actions/README.md b/x-pack/plugins/actions/README.md index 2269491d226393..4e12eee96f2f15 100644 --- a/x-pack/plugins/actions/README.md +++ b/x-pack/plugins/actions/README.md @@ -271,136 +271,6 @@ const result = await actionsClient.execute({ Kibana ships with a set of built-in action types. See [Actions and connector types Documentation](https://www.elastic.co/guide/en/kibana/master/action-types.html). -## Jira - -ID: `.jira` - -The Jira action uses the [V2 API](https://developer.atlassian.com/cloud/jira/platform/rest/v2/) to create and update Jira incidents. - -### `config` - -| Property | Description | Type | -| -------- | ------------------ | ------ | -| apiUrl | Jira instance URL. | string | - -### `secrets` - -| Property | Description | Type | -| -------- | ----------------------------------------------------- | ------ | -| email | email (or username) for HTTP Basic authentication | string | -| apiToken | API token (or password) for HTTP Basic authentication | string | - -### `params` - -| Property | Description | Type | -| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------ | -| subAction | The sub action to perform. It can be `pushToService`, `getIncident`, `issueTypes`, `fieldsByIssueType`, `issues`, `issue`, and `getFields` | string | -| subActionParams | The parameters of the sub action | object | - -#### `subActionParams (pushToService)` - -| Property | Description | Type | -| -------- | ------------------------------------------------------------------------------------------------------------- | --------------------- | -| incident | The Jira incident. | object | -| comments | The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. | object[] _(optional)_ | - -The following table describes the properties of the `incident` object. - -| Property | Description | Type | -| ----------- | ---------------------------------------------------------------------------------------------------------------- | --------------------- | -| summary | The title of the issue | string | -| description | The description of the issue | string _(optional)_ | -| externalId | The id of the issue in Jira. If presented the incident will be update. Otherwise a new incident will be created. | string _(optional)_ | -| issueType | The id of the issue type in Jira. | string _(optional)_ | -| priority | The name of the priority in Jira. Example: `Medium`. | string _(optional)_ | -| labels | An array of labels. Labels cannot contain spaces. | string[] _(optional)_ | -| parent | The parent issue id or key. Only for `Sub-task` issue types. | string _(optional)_ | - -#### `subActionParams (getIncident)` - -| Property | Description | Type | -| ---------- | --------------------------- | ------ | -| externalId | The id of the issue in Jira | string | - -#### `subActionParams (issueTypes)` - -No parameters for `issueTypes` sub-action. Provide an empty object `{}`. - -#### `subActionParams (fieldsByIssueType)` - -| Property | Description | Type | -| -------- | -------------------------------- | ------ | -| id | The id of the issue type in Jira | string | - -#### `subActionParams (issues)` - -| Property | Description | Type | -| -------- | ----------------------- | ------ | -| title | The title to search for | string | - -#### `subActionParams (issue)` - -| Property | Description | Type | -| -------- | --------------------------- | ------ | -| id | The id of the issue in Jira | string | - -#### `subActionParams (getFields)` - -No parameters for `getFields` sub-action. Provide an empty object `{}`. - -## IBM Resilient - -ID: `.resilient` - -### `config` - -| Property | Description | Type | -| -------- | --------------------------- | ------ | -| apiUrl | IBM Resilient instance URL. | string | - -### `secrets` - -| Property | Description | Type | -| ------------ | -------------------------------------------- | ------ | -| apiKeyId | API key ID for HTTP Basic authentication | string | -| apiKeySecret | API key secret for HTTP Basic authentication | string | - -### `params` - -| Property | Description | Type | -| --------------- | -------------------------------------------------------------------------------------------------- | ------ | -| subAction | The sub action to perform. It can be `pushToService`, `getFields`, `incidentTypes`, and `severity` | string | -| subActionParams | The parameters of the sub action | object | - -#### `subActionParams (pushToService)` - -| Property | Description | Type | -| -------- | ------------------------------------------------------------------------------------------------------------- | --------------------- | -| incident | The IBM Resilient incident. | object | -| comments | The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. | object[] _(optional)_ | - -The following table describes the properties of the `incident` object. - -| Property | Description | Type | -| ------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------- | -| name | The title of the incident | string _(optional)_ | -| description | The description of the incident | string _(optional)_ | -| externalId | The id of the incident in IBM Resilient. If presented the incident will be update. Otherwise a new incident will be created. | string _(optional)_ | -| incidentTypes | An array with the ids of IBM Resilient incident types. | number[] _(optional)_ | -| severityCode | IBM Resilient id of the severity code. | number _(optional)_ | - -#### `subActionParams (getFields)` - -No parameters for `getFields` sub-action. Provide an empty object `{}`. - -#### `subActionParams (incidentTypes)` - -No parameters for `incidentTypes` sub-action. Provide an empty object `{}`. - -#### `subActionParams (severity)` - -No parameters for `severity` sub-action. Provide an empty object `{}`. - # Command Line Utility The [`kbn-action`](https://github.com/pmuellr/kbn-action) tool can be used to send HTTP requests to the Actions plugin. For instance, to create a Slack action from the `.slack` Action Type, use the following command: From 5a55a9514f0904e8b8f79f2be1de1ed8ed7d8134 Mon Sep 17 00:00:00 2001 From: Ying Mao Date: Wed, 17 Feb 2021 22:30:01 -0500 Subject: [PATCH 5/8] Fixing formatting --- x-pack/plugins/actions/README.md | 59 ++++++++++++++++---------------- 1 file changed, 30 insertions(+), 29 deletions(-) diff --git a/x-pack/plugins/actions/README.md b/x-pack/plugins/actions/README.md index 4e12eee96f2f15..4905835388fe1b 100644 --- a/x-pack/plugins/actions/README.md +++ b/x-pack/plugins/actions/README.md @@ -124,16 +124,16 @@ Built-In-Actions are configured using the _xpack.actions_ namespace under _kiban This module provides utilities for interacting with the configuration. -| Method | Arguments | Description | Return Type | -| - | - | - | - | -| isUriAllowed | _uri_: The URI you wish to validate is allowed | Validates whether the URI is allowed. This checks the configuration and validates that the hostname of the URI is in the list of allowed Hosts and returns `true` if it is allowed. If the configuration says that all URI's are allowed (using an "\*") then it will always return `true`. | Boolean | -| isHostnameAllowed | _hostname_: The Hostname you wish to validate is allowed | Validates whether the Hostname is allowed. This checks the configuration and validates that the hostname is in the list of allowed Hosts and returns `true` if it is allowed. If the configuration says that all Hostnames are allowed (using an "\*") then it will always return `true`. | Boolean | -| isActionTypeEnabled | _actionType_: The actionType to check to see if it's enabled | Returns true if the actionType is enabled, otherwise false. | Boolean | -| ensureUriAllowed | _uri_: The URI you wish to validate is allowed | Validates whether the URI is allowed. This checks the configuration and validates that the hostname of the URI is in the list of allowed Hosts and throws an error if it is not allowed. If the configuration says that all URI's are allowed (using an "\*") then it will never throw. | No return value, throws if URI isn't allowed | -| ensureHostnameAllowed | _hostname_: The Hostname you wish to validate is allowed | Validates whether the Hostname is allowed. This checks the configuration and validates that the hostname is in the list of allowed Hosts and throws an error if it is not allowed. If the configuration says that all Hostnames are allowed (using an "\*") then it will never throw. | No return value, throws if Hostname isn't allowed . | -| ensureActionTypeEnabled | _actionType_: The actionType to check to see if it's enabled | Throws an error if the actionType is not enabled. | No return value, throws if actionType isn't enabled | -| isRejectUnauthorizedCertificatesEnabled | _none_ | Returns value of `rejectUnauthorized` from configuration. | Boolean | -| getProxySettings | _none_ | If `proxyUrl` is set in the configuration, returns the proxy settings `proxyUrl`, `proxyHeaders` and `proxyRejectUnauthorizedCertificates`. Otherwise returns _undefined_. | Undefined or ProxySettings | +| Method | Arguments | Description | Return Type | +| --------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | +| isUriAllowed | _uri_: The URI you wish to validate is allowed | Validates whether the URI is allowed. This checks the configuration and validates that the hostname of the URI is in the list of allowed Hosts and returns `true` if it is allowed. If the configuration says that all URI's are allowed (using an "\*") then it will always return `true`. | Boolean | +| isHostnameAllowed | _hostname_: The Hostname you wish to validate is allowed | Validates whether the Hostname is allowed. This checks the configuration and validates that the hostname is in the list of allowed Hosts and returns `true` if it is allowed. If the configuration says that all Hostnames are allowed (using an "\*") then it will always return `true`. | Boolean | +| isActionTypeEnabled | _actionType_: The actionType to check to see if it's enabled | Returns true if the actionType is enabled, otherwise false. | Boolean | +| ensureUriAllowed | _uri_: The URI you wish to validate is allowed | Validates whether the URI is allowed. This checks the configuration and validates that the hostname of the URI is in the list of allowed Hosts and throws an error if it is not allowed. If the configuration says that all URI's are allowed (using an "\*") then it will never throw. | No return value, throws if URI isn't allowed | +| ensureHostnameAllowed | _hostname_: The Hostname you wish to validate is allowed | Validates whether the Hostname is allowed. This checks the configuration and validates that the hostname is in the list of allowed Hosts and throws an error if it is not allowed. If the configuration says that all Hostnames are allowed (using an "\*") then it will never throw | No return value, throws if Hostname isn't allowed . | +| ensureActionTypeEnabled | _actionType_: The actionType to check to see if it's enabled | Throws an error if the actionType is not enabled | No return value, throws if actionType isn't enabled | +| isRejectUnauthorizedCertificatesEnabled | _none_ | Returns value of `rejectUnauthorized` from configuration. | Boolean | +| getProxySettings | _none_ | If `proxyUrl` is set in the configuration, returns the proxy settings `proxyUrl`, `proxyHeaders` and `proxyRejectUnauthorizedCertificates`. Otherwise returns _undefined_. | Undefined or ProxySettings | ## Action types @@ -143,16 +143,16 @@ This module provides utilities for interacting with the configuration. The following table describes the properties of the `options` object. -| Property | Description | Type | -| - | - | - | -| id | Unique identifier for the action type. For convention, ids starting with `.` are reserved for built in action types. We recommend using a convention like `.mySpecialAction` for your action types. | string | -| name | A user-friendly name for the action type. These will be displayed in dropdowns when chosing action types. | string | -| maxAttempts | The maximum number of times this action will attempt to execute when scheduled. | number | -| minimumLicenseRequired | The license required to use the action type. | string | -| validate.params | When developing an action type, it needs to accept parameters to know what to do with the action. (Example `to`, `from`, `subject`, `body` of an email). See the current built-in email action type for an example of the state-of-the-art validation.

Technically, the value of this property should have a property named `validate()` which is a function that takes a params object to validate and returns a sanitized version of that object to pass to the execution function. Validation errors should be thrown from the `validate()` function and will be available as an error message. | schema / validation function | -| validate.config | Similar to params, a config may be required when creating an action (for example `host` and `port` for an email server). | schema / validation function | -| validate.secrets | Similar to params, a secrets object may be required when creating an action (for example `user` and `password` for an email server). | schema / validation function | -| executor | This is where the code of an action type lives. This is a function gets called for executing an action from either alerting or manually by using the exposed function (see firing actions). For full details, see executor section below. | Function | +| Property | Description | Type | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | +| id | Unique identifier for the action type. For convention, ids starting with `.` are reserved for built in action types. We recommend using a convention like `.mySpecialAction` for your action types. | string | +| name | A user-friendly name for the action type. These will be displayed in dropdowns when chosing action types. | string | +| maxAttempts | The maximum number of times this action will attempt to execute when scheduled. | number | +| minimumLicenseRequired | The license required to use the action type. | string | +| validate.params | When developing an action type, it needs to accept parameters to know what to do with the action. (Example `to`, `from`, `subject`, `body` of an email). See the current built-in email action type for an example of the state-of-the-art validation.

Technically, the value of this property should have a property named `validate()` which is a function that takes a params object to validate and returns a sanitized version of that object to pass to the execution function. Validation errors should be thrown from the `validate()` function and will be available as an error message | schema / validation function | +| validate.config | Similar to params, a config may be required when creating an action (for example `host` and `port` for an email server). | schema / validation function | +| validate.secrets | Similar to params, a secrets object may be required when creating an action (for example `user` and `password` for an email server). | schema / validation function | +| executor | This is where the code of an action type lives. This is a function gets called for executing an action from either alerting or manually by using the exposed function (see firing actions). For full details, see executor section below. | Function | | renderParameterTemplates | Optionally define a function to provide custom rendering for this action type. | Function | **Important** - The config object is persisted in ElasticSearch and updated via the ElasticSearch update document API. This API allows "partial updates" - and this can cause issues with the encryption used on specified properties. So, a `validate()` function should return values for all configuration properties, so that partial updates do not occur. Setting property values to `null` rather than `undefined`, or not including a property in the config object, is all you need to do to ensure partial updates won't occur. @@ -163,15 +163,16 @@ This is the primary function for an action type. Whenever the action needs to ex **executor(options)** -| Property | Description | -| - | - | -| actionId | The action saved object id that the action type is executing for. | -| config | The action configuration. If you would like to validate the config before being passed to the executor, define `validate.config` within the action type. | -| secrets | The decrypted secrets object given to an action. This comes from the action saved object that is partially or fully encrypted within the data store. If you would like to validate the secrets object before being passed to the executor, define `validate.secrets` within the action type. | -| params | Parameters for the execution. These will be given at execution time by either an alert or manually provided when calling the plugin provided execute function. | -| services.callCluster(path, opts) | Use this to do Elasticsearch queries on the cluster Kibana connects to. This function is the same as any other `callCluster` in Kibana but runs in the context of the user who is calling the action when security is enabled. | -| services.getLegacyScopedClusterClient | This function returns an instance of the LegacyScopedClusterClient scoped to the user who is calling the action when security is enabled. | -| services.savedObjectsClient | This is an instance of the saved objects client. This provides the ability to do CRUD on any saved objects within the same space the alert lives in.

The scope of the saved objects client is tied to the user in context calling the execute API or the API key provided to the execute plugin function (only when security isenabled). | +| Property | Description | +| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| actionId | The action saved object id that the action type is executing for. | +| config | The action configuration. If you would like to validate the config before being passed to the executor, define `validate.config` within the action type. | +| secrets | The decrypted secrets object given to an action. This comes from the action saved object that is partially or fully encrypted within the data store. If you would like to validate the secrets object before being passed to the executor, define `validate.secrets` within the action type. | +| params | Parameters for the execution. These will be given at execution time by either an alert or manually provided when calling the plugin provided execute function. | +| services.callCluster(path, opts) | Use this to do Elasticsearch queries on the cluster Kibana connects to. This function is the same as any other `callCluster` in Kibana but runs in the context of the user who is calling the action when security is enabled. | +| services.getLegacyScopedClusterClient | This function returns an instance of the LegacyScopedClusterClient scoped to the user who is calling the action when security is enabled. | +| services.savedObjectsClient | This is an instance of the saved objects client. This provides the ability to do CRUD on any saved objects within the same space the alert lives in.

The scope of the saved objects client is tied to the user in context calling the execute API or the API key provided to the execute plugin function (only when security isenabled). | +| services.log(tags, [data], [timestamp]) | Use this to create server logs. (This is the same function as server.log) ### Example From ea22deff4335fe6a753ea3f6acc2dce33101d423 Mon Sep 17 00:00:00 2001 From: ymao1 Date: Fri, 19 Feb 2021 18:43:18 -0500 Subject: [PATCH 6/8] Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- .../user/alerting/action-types/email.asciidoc | 8 +++--- docs/user/alerting/action-types/jira.asciidoc | 26 +++++++++---------- .../alerting/action-types/resilient.asciidoc | 18 ++++++------- .../alerting/action-types/server-log.asciidoc | 2 +- .../alerting/action-types/servicenow.asciidoc | 12 ++++----- docs/user/alerting/defining-alerts.asciidoc | 6 ++--- x-pack/plugins/actions/README.md | 4 +-- 7 files changed, 38 insertions(+), 38 deletions(-) diff --git a/docs/user/alerting/action-types/email.asciidoc b/docs/user/alerting/action-types/email.asciidoc index 62ce57cb74bda0..199118018f0e8b 100644 --- a/docs/user/alerting/action-types/email.asciidoc +++ b/docs/user/alerting/action-types/email.asciidoc @@ -11,12 +11,12 @@ The email action type uses the SMTP protocol to send mail message, using an inte Email connectors have the following configuration properties: Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action. -Sender:: The from address for all emails sent with this connector. This can be specified in `user@host-name` format or as `"human name "` format. See the [nodemailer address documentation](https://nodemailer.com/message/addresses/) for more information. +Sender:: The from address for all emails sent with this connector. This can be specified in `user@host-name` format or as `"human name "` format. See the https://nodemailer.com/message/addresses/[Nodemailer address documentation] for more information. Host:: Host name of the service provider. If you are using the <> setting, make sure this hostname is added to the allowed hosts. Port:: The port to connect to on the service provider. Secure:: If true, the connection will use TLS when connecting to the service provider. Refer to the https://nodemailer.com/smtp/#tls-options[Nodemailer TLS documentation] for more information. If not true, the connection will initially connect over TCP, then attempt to switch to TLS via the SMTP STARTTLS command. -User:: Username for 'login' type authentication. -Password:: Password for 'login' type authentication. +User:: Username for login type authentication. +Password:: Password for login type authentication. [float] [[Preconfigured-email-configuration]] @@ -44,7 +44,7 @@ Password:: Password for 'login' type authentication. |=== | `service` -| The name of a [well-known email service provider](https://nodemailer.com/smtp/well-known/) value. If `service` is provided, `host`, `port`, and `secure` properties are ignored. For more information on the `gmail` service value specifically, see the [nodemailer gmail documentation](https://nodemailer.com/usage/using-gmail/). +| The name of a https://nodemailer.com/smtp/well-known/[well-known email service provider]. If `service` is provided, `host`, `port`, and `secure` properties are ignored. For more information on the `gmail` service value, see the (https://nodemailer.com/usage/using-gmail/)[Nodemailer Gmail documentation]. | `from` | An email address that corresponds to *Sender*. diff --git a/docs/user/alerting/action-types/jira.asciidoc b/docs/user/alerting/action-types/jira.asciidoc index 3bbe5536a545a3..02f2a9be892542 100644 --- a/docs/user/alerting/action-types/jira.asciidoc +++ b/docs/user/alerting/action-types/jira.asciidoc @@ -65,32 +65,32 @@ API token (or password):: Jira API authentication token (or password) for HTTP Jira actions have the following configuration properties: -Subaction:: The subaction to perform. Either `pushToService`, `getIncident`, `issueTypes`, `fieldsByIssueType`, `issues`, `issue`, or `getFields`. +Subaction:: The subaction to perform: `pushToService`, `getIncident`, `issueTypes`, `fieldsByIssueType`, `issues`, `issue`, or `getFields`. Subaction Params:: The parameters of the subaction. ==== `pushToService` subaction configuration -Incident:: The Jira incident which has the following properties: +Incident:: A Jira incident has the following properties: * `summary` - The title of the issue. -* `description` - The description of the issue. -* `externalId` - The id of the issue in Jira. If present the issue will be updated. Otherwise a new issue will be created. -* `issueType` - The id of the issue type in Jira. -* `priority` - The name of the priority in Jira. Example: `Medium`. +* `description` - A description of the issue. +* `externalId` - The ID of the issue in Jira. If present, the issue is updated. Otherwise, a new issue is created. +* `issueType` - The ID of the issue type in Jira. +* `priority` - The priority level in Jira. Example: `Medium`. * `labels` - An array of labels. Labels cannot contain spaces. -* `parent` - The parent issue id or key. Only for Sub-task issue types. -Comments:: The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. +* `parent` - The parent issue ID or key. Only for subtask issue types. +Comments:: A comment in the form of `{ commentId: string, version: string, comment: string }`. ==== `getIncident` subaction configuration -External ID:: The id of the issue in Jira. +External ID:: The ID of the issue in Jira. ==== `issueTypes` subaction configuration -No parameters for `issueTypes` subaction. Provide an empty object `{}`. +The `issueTypes` subaction has no parameters. Provide an empty object `{}`. ==== `fieldsByIssueType` subaction configuration -ID:: The id of the issue in Jira. +ID:: The ID of the issue in Jira. ==== `issues` subaction configuration @@ -98,11 +98,11 @@ Title:: The title to search for. ==== `issue` subaction configuration -ID:: The id of the issue in Jira. +ID:: The ID of the issue in Jira. ==== `getFields` subaction configuration -No parameters for `getFields` subaction. Provide an empty object `{}`. +The `getFields` subaction has no parameters. Provide an empty object `{}`. [[configuring-jira]] ==== Configuring and testing Jira diff --git a/docs/user/alerting/action-types/resilient.asciidoc b/docs/user/alerting/action-types/resilient.asciidoc index 6754dc0ddb50e4..4b0b0a9730a2cc 100644 --- a/docs/user/alerting/action-types/resilient.asciidoc +++ b/docs/user/alerting/action-types/resilient.asciidoc @@ -65,30 +65,30 @@ API key secret:: The authentication key secret for HTTP Basic authentication. IBM Resilient actions have the following configuration properties: -Subaction:: The subaction to perform. Either `pushToService`, `getFields`, `incidentTypes`, or `severity`. +Subaction:: The subaction to perform: `pushToService`, `getFields`, `incidentTypes`, or `severity`. Subaction Params:: The parameters of the subaction. ==== `pushToService` subaction configuration -Incident:: The IBM resilient incident which has the following properties: +Incident:: The IBM resilient incident has the following properties: * `name` - A name for the issue, used for searching the contents of the knowledge base. * `description` - The details about the incident. -* `externalId` - The id of the incident in IBM Resilient. If present the incident will be updated. Otherwise a new incident will be created. -* `incidentTypes` - An array with the ids of IBM Resilient incident types. -* `severityCode` - IBM Resilient id of the severity code. -Comments:: The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. +* `externalId` - The ID of the incident in IBM Resilient. If present, the incident is updated. Otherwise, a new incident is created. +* `incidentTypes` - An array with the IDs of IBM Resilient incident types. +* `severityCode` - The IBM Resilient ID of the severity code. +Comments:: A comment in the form of `{ commentId: string, version: string, comment: string }`. ===== `getFields` subaction configuration -No parameters for `getFields` subaction. Provide an empty object `{}`. +The `getFields` subaction has not parameters. Provide an empty object `{}`. ===== `incidentTypes` subaction configuration -No parameters for `incidentTypes` subaction. Provide an empty object `{}`. +The `incidentTypes` subaction has no parameters. Provide an empty object `{}`. ===== `severity` subaction configuration -No parameters for `severity` subaction. Provide an empty object `{}`. +The `severity` subaction has no parameters. Provide an empty object `{}`. [[configuring-resilient]] ==== Configuring and testing IBM Resilient diff --git a/docs/user/alerting/action-types/server-log.asciidoc b/docs/user/alerting/action-types/server-log.asciidoc index f66e1714b8c73c..276f64e7786bd9 100644 --- a/docs/user/alerting/action-types/server-log.asciidoc +++ b/docs/user/alerting/action-types/server-log.asciidoc @@ -30,4 +30,4 @@ Name:: The name of the connector. The name is used to identify a connector Server log actions have the following properties: Message:: The message to log. -Level:: The log level of the message. Either `trace`, `debug`, `info`, `warn`, `error` or `fatal`. Defaults to `info`. +Level:: The log level of the message: `trace`, `debug`, `info`, `warn`, `error` or `fatal`. Defaults to `info`. diff --git a/docs/user/alerting/action-types/servicenow.asciidoc b/docs/user/alerting/action-types/servicenow.asciidoc index a3447a3310d974..1e4923a7d449ed 100644 --- a/docs/user/alerting/action-types/servicenow.asciidoc +++ b/docs/user/alerting/action-types/servicenow.asciidoc @@ -60,29 +60,29 @@ Password:: Password for HTTP Basic authentication. ServiceNow actions have the following configuration properties: -Subaction:: The subaction to perform. Either `pushToService`, `getFields`, `getIncident`, or `getChoices`. +Subaction:: The subaction to perform: `pushToService`, `getFields`, `getIncident`, or `getChoices`. Subaction Params:: The parameters of the subaction. ==== `pushToService` subaction configuration -Incident:: The ServiceNow incident which has the following properties: +Incident:: The ServiceNow incident has the following properties: * `short_description` - A short description for the incident, used for searching the contents of the knowledge base. * `description` - The details about the incident. -* `externalId` - The id of the incident in ServiceNow. If present the incident will be updated. Otherwise a new incident will be created. +* `externalId` - The ID of the incident in ServiceNow. If present, the incident is updated. Otherwise, a new incident is created. * `severity` - The severity of the incident. * `urgency` - The extent to which the incident resolution can delay. * `impact` - The effect an incident has on business. Can be measured by the number of affected users or by how critical it is to the business in question. * `category` - The name of the category in ServiceNow. * `subcategory` - The name of the subcategory in ServiceNow. -Comments:: The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. +Comments:: A comment in the form of `{ commentId: string, version: string, comment: string }`. ===== `getFields` subaction configuration -No parameters for `getFields` subaction. Provide an empty object `{}`. +The `getFields` subaction has no parameters. Provide an empty object `{}`. ===== `getIncident` subaction configuration -External ID:: The id of the incident in ServiceNow. +External ID:: The ID of the incident in ServiceNow. ===== `getChoices` subaction configuration diff --git a/docs/user/alerting/defining-alerts.asciidoc b/docs/user/alerting/defining-alerts.asciidoc index f88e4cd19c65f3..01bf6a35597be5 100644 --- a/docs/user/alerting/defining-alerts.asciidoc +++ b/docs/user/alerting/defining-alerts.asciidoc @@ -91,10 +91,10 @@ If you are using a cloud deployment, you can set these via the console. Here's a list of the available global configuration options and an explanation of what each one does: -* `xpack.actions.enabled`: Feature toggle which enables Actions in {kib}. Default: `true` +* `xpack.actions.enabled`: Feature toggle that enables Actions in {kib}. Default: `true` * `xpack.actions.allowedHosts`: Specifies an array of host names which actions such as email, Slack, PagerDuty, and webhook can connect to. An element of * indicates any host can be connected to. An empty array indicates no hosts can be connected to. Default: [ {asterisk} ] -* `xpack.actions.enabledActionTypes`: Specifies to an array of action types that are enabled. An {asterisk} indicates all action types registered are enabled. The action types that {kib} provides are: `.email`, `.index`, `.jira`, `.pagerduty`, `.resilient`, `.server-log`, `.servicenow`, `.servicenow-sir`, `.slack`, `.teams`, `.webhook`. Default: [ {asterisk} ] -* `xpack.actions.preconfigured`: Specifies preconfigured action ids and configs. Default: {} +* `xpack.actions.enabledActionTypes`: Specifies an array of action types that are enabled. An {asterisk} indicates all action types registered are enabled. The action types that {kib} provides are `.email`, `.index`, `.jira`, `.pagerduty`, `.resilient`, `.server-log`, `.servicenow`, `.servicenow-sir`, `.slack`, `.teams`, and `.webhook`. Default: [ {asterisk} ] +* `xpack.actions.preconfigured`: Specifies preconfigured action IDs and configs. Default: {} * `xpack.actions.proxyUrl`: Specifies the proxy URL to use, if using a proxy for actions. * `xpack.actions.proxyHeader`: Specifies HTTP headers for proxy, if using a proxy for actions. * `xpack.actions.proxyRejectUnauthorizedCertificates`: Set to `false` to bypass certificate validation for proxy, if using a proxy for actions. diff --git a/x-pack/plugins/actions/README.md b/x-pack/plugins/actions/README.md index 4905835388fe1b..6546f625af8899 100644 --- a/x-pack/plugins/actions/README.md +++ b/x-pack/plugins/actions/README.md @@ -116,7 +116,7 @@ Built-In-Actions are configured using the _xpack.actions_ namespace under _kiban #### **allowedHosts** configuration -- You may use the string "*" in the **allowedHosts** configuration in place of a specific hostname to enable Kibana to target any URL, but keep in mind the potential to use such a feature to execute [SSRF](https://www.owasp.org/index.php/Server_Side_Request_Forgery) attacks from your server. +- You can use the string "*" in the **allowedHosts** configuration in place of a specific hostname to enable Kibana to target any URL, but keep in mind the potential to use such a feature to execute [SSRF](https://www.owasp.org/index.php/Server_Side_Request_Forgery) attacks from your server. - The **allowedHosts** configuration applies to built-in action types (such as Slack, or PagerDuty) as well. Uniquely, the _PagerDuty Action Type_ has been configured to support the service's Events API (at _https://events.pagerduty.com/v2/enqueue_, which you can read about [here](https://v2.developer.pagerduty.com/docs/events-api-v2)) as a default, but this too, must be included in the allowedHosts before the PagerDuty action can be used. @@ -326,4 +326,4 @@ Instead of `schema.maybe()`, use `schema.nullable()`, which is the same as `sche ## user interface -In order to make this action usable in the Kibana UI, you will need to provide all the UI editing aspects of the action. The existing action type user interfaces are defined in [`x-pack/plugins/triggers_actions_ui/public/application/components/builtin_action_types`](../triggers_actions_ui/public/application/components/builtin_action_types). For more information, see the [UI documentation](../triggers_actions_ui/README.md#create-and-register-new-action-type-ui). \ No newline at end of file +In order to make this action usable in the Kibana UI, you will need to provide all the UI editing aspects of the action. The existing action type user interfaces are defined in [`x-pack/plugins/triggers_actions_ui/public/application/components/builtin_action_types`](../triggers_actions_ui/public/application/components/builtin_action_types). For more information, see the [UI documentation](../triggers_actions_ui/README.md#create-and-register-new-action-type-ui). From 53e516cba77c9f52ae56e7b9eb5f8c0ca8c08b09 Mon Sep 17 00:00:00 2001 From: Ying Mao Date: Fri, 19 Feb 2021 19:03:24 -0500 Subject: [PATCH 7/8] PR fixes --- docs/user/alerting/action-types/jira.asciidoc | 2 +- docs/user/alerting/action-types/resilient.asciidoc | 2 +- docs/user/alerting/action-types/servicenow.asciidoc | 2 +- x-pack/plugins/actions/README.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user/alerting/action-types/jira.asciidoc b/docs/user/alerting/action-types/jira.asciidoc index 02f2a9be892542..0740cf7838b15a 100644 --- a/docs/user/alerting/action-types/jira.asciidoc +++ b/docs/user/alerting/action-types/jira.asciidoc @@ -66,7 +66,7 @@ API token (or password):: Jira API authentication token (or password) for HTTP Jira actions have the following configuration properties: Subaction:: The subaction to perform: `pushToService`, `getIncident`, `issueTypes`, `fieldsByIssueType`, `issues`, `issue`, or `getFields`. -Subaction Params:: The parameters of the subaction. +Subaction params:: The parameters of the subaction. ==== `pushToService` subaction configuration diff --git a/docs/user/alerting/action-types/resilient.asciidoc b/docs/user/alerting/action-types/resilient.asciidoc index 4b0b0a9730a2cc..dfa95e2deec008 100644 --- a/docs/user/alerting/action-types/resilient.asciidoc +++ b/docs/user/alerting/action-types/resilient.asciidoc @@ -66,7 +66,7 @@ API key secret:: The authentication key secret for HTTP Basic authentication. IBM Resilient actions have the following configuration properties: Subaction:: The subaction to perform: `pushToService`, `getFields`, `incidentTypes`, or `severity`. -Subaction Params:: The parameters of the subaction. +Subaction params:: The parameters of the subaction. ==== `pushToService` subaction configuration diff --git a/docs/user/alerting/action-types/servicenow.asciidoc b/docs/user/alerting/action-types/servicenow.asciidoc index 1e4923a7d449ed..d1ee1b9357737d 100644 --- a/docs/user/alerting/action-types/servicenow.asciidoc +++ b/docs/user/alerting/action-types/servicenow.asciidoc @@ -61,7 +61,7 @@ Password:: Password for HTTP Basic authentication. ServiceNow actions have the following configuration properties: Subaction:: The subaction to perform: `pushToService`, `getFields`, `getIncident`, or `getChoices`. -Subaction Params:: The parameters of the subaction. +Subaction params:: The parameters of the subaction. ==== `pushToService` subaction configuration diff --git a/x-pack/plugins/actions/README.md b/x-pack/plugins/actions/README.md index 6546f625af8899..6606d5e0aafcd7 100644 --- a/x-pack/plugins/actions/README.md +++ b/x-pack/plugins/actions/README.md @@ -118,7 +118,7 @@ Built-In-Actions are configured using the _xpack.actions_ namespace under _kiban - You can use the string "*" in the **allowedHosts** configuration in place of a specific hostname to enable Kibana to target any URL, but keep in mind the potential to use such a feature to execute [SSRF](https://www.owasp.org/index.php/Server_Side_Request_Forgery) attacks from your server. -- The **allowedHosts** configuration applies to built-in action types (such as Slack, or PagerDuty) as well. Uniquely, the _PagerDuty Action Type_ has been configured to support the service's Events API (at _https://events.pagerduty.com/v2/enqueue_, which you can read about [here](https://v2.developer.pagerduty.com/docs/events-api-v2)) as a default, but this too, must be included in the allowedHosts before the PagerDuty action can be used. +- The **allowedHosts** configuration applies to built-in action types (such as Slack and PagerDuty). While the _PagerDuty Action Type_ has been configured to support the service's Events API (at _https://events.pagerduty.com/v2/enqueue_, which you can read about in [Pagerduty's documentation](https://v2.developer.pagerduty.com/docs/events-api-v2)), the PagerDuty domain must still be included in the allowedHosts configuration before the action can be used. ### Configuration Utilities From e10fcbe5757ba56fdbd1641488bcccc731091749 Mon Sep 17 00:00:00 2001 From: ymao1 Date: Tue, 23 Feb 2021 18:59:41 -0500 Subject: [PATCH 8/8] Update x-pack/plugins/actions/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- x-pack/plugins/actions/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/plugins/actions/README.md b/x-pack/plugins/actions/README.md index 6606d5e0aafcd7..78094f4c0eb0b1 100644 --- a/x-pack/plugins/actions/README.md +++ b/x-pack/plugins/actions/README.md @@ -326,4 +326,4 @@ Instead of `schema.maybe()`, use `schema.nullable()`, which is the same as `sche ## user interface -In order to make this action usable in the Kibana UI, you will need to provide all the UI editing aspects of the action. The existing action type user interfaces are defined in [`x-pack/plugins/triggers_actions_ui/public/application/components/builtin_action_types`](../triggers_actions_ui/public/application/components/builtin_action_types). For more information, see the [UI documentation](../triggers_actions_ui/README.md#create-and-register-new-action-type-ui). +To make this action usable in the Kibana UI, you will need to provide all the UI editing aspects of the action. The existing action type user interfaces are defined in [`x-pack/plugins/triggers_actions_ui/public/application/components/builtin_action_types`](../triggers_actions_ui/public/application/components/builtin_action_types). For more information, see the [UI documentation](../triggers_actions_ui/README.md#create-and-register-new-action-type-ui).