Commit fff0775d authored by Jochen Kressin's avatar Jochen Kressin
Browse files

formatting

parent 42adf8b1
...@@ -2,9 +2,8 @@ ...@@ -2,9 +2,8 @@
title: Accounts title: Accounts
html_title: Using Accounts for Signals Alerting html_title: Using Accounts for Signals Alerting
slug: elasticsearch-alerting-accounts slug: elasticsearch-alerting-accounts
category: signals category: actions
subcategory: accounts order: 50
order: 790
layout: docs layout: docs
edition: preview edition: preview
description: description:
...@@ -23,7 +22,7 @@ If you want to use e-mail or Slack actions, you have to configure accounts in th ...@@ -23,7 +22,7 @@ If you want to use e-mail or Slack actions, you have to configure accounts in th
The purpose of the account registry is to: The purpose of the account registry is to:
* Make account data reusable and thus avoid configuring the same accounts again and again for each watch. * Make account data reusable thus avoiding configuring the same accounts again and again for each watch.
* Storing credentials for these accounts safely. * Storing credentials for these accounts safely.
* Controlling which external resources can be used by watches. * Controlling which external resources can be used by watches.
...@@ -31,8 +30,6 @@ While watches may be configured by a wide range of users, accounts shall be only ...@@ -31,8 +30,6 @@ While watches may be configured by a wide range of users, accounts shall be only
## Account Types ## Account Types
The different account types are document in the following sections.
### E-Mail Accounts ### E-Mail Accounts
E-mail accounts represent connection data and credentials for SMTP servers. E-mail accounts represent connection data and credentials for SMTP servers.
...@@ -52,34 +49,21 @@ A typical e-mail account looks like this: ...@@ -52,34 +49,21 @@ A typical e-mail account looks like this:
} }
``` ```
These properties are available: | Name | Description |
|---|---|
**host:** The hostname of the SMTP server to connect to. Required. | host | The hostname of the SMTP server to connect to. Required. |
| port | The number of the port to connect to. Required. |
**port:** The number of the port to connect to. Required. | user | The user name used for authentication. Optional. |
| password | The password user for authentication. Optional. |
**user:** The user name used for authentication. Optional. | enable\_tls | If true, the connection is established by TLS. |
| enable\_start\_tls | If true, the connection is established using STARTTLS. |
**password:** The password user for authentication. Optional. | trusted_hosts | Only accept server certificates issued to one of the provided hostnames, *and disables certificate issuer validation.* Optional; array of host names. *Security warning: Any certificate matching any of the provided host names will be accepted, regardless of the certificate issuer; attackers can abuse this behavior by serving a matching self-signed certificate during a man-in-the-middle attack.* |
| trust_all | If true, trust all hosts and don't validate any SSL keys. Optional. |
**enable_tls:** If true, the connection is established by TLS. | default_from | Defines the from address used in e-mails when an e-mail action does not configure an explicit from address. Optional. |
| default\_to, default\_cc, default\_bcc | Defines the recipient addresses used in e-mails when an e-mail action does not configure an explicit values for the respective recipient types. Optional; array of e-mail addresses |
**enable_start_tls:** If true, the connection is established using STARTTLS. | session_timeout | Sets the timeout for connecting to and communicating with the SMTP server. Optional; time duration in seconds. |
| proxy\_host, proxy\_port, proxy\_user, proxy\_password | Allows the specification of a SOCKS proxy to connect to the SMTP server. Optional. |
**trusted_hosts:** Only accept server certificates issued to one of the provided hostnames, *and disables certificate issuer validation.* Optional; array of host names. | debug | If true, protocol data is logged to the Elasticsearch log when mails are sent. |
*Security warning: Any certificate matching any of the provided host names will be accepted, regardless of the certificate issuer; attackers can abuse this behavior by serving a matching self-signed certificate during a man-in-the-middle attack.*
**trust_all:** If true, trust all hosts and don't validate any SSL keys. Optional.
**default_from:** Defines the from address used in e-mails when an e-mail action does not configure an explicit from address. Optional.
**default_to, default_cc, default_bcc:** Defines the recipient addresses used in e-mails when an e-mail action does not configure an explicit values for the respective recipient types. Optional; array of e-mail addresses.
**session_timeout:** Sets the timeout for connecting to and communicating with the SMTP server. Optional; time duration in seconds.
**proxy_host, proxy_port, proxy_user, proxy_password:** Allows the specification of a SOCKS proxy to connect to the SMTP server. Optional.
**debug:** If true, protocol data is logged to the Elasticsearch log when mails are sent.
### Slack Accounts ### Slack Accounts
...@@ -100,9 +84,9 @@ The value for the `url` property must be optained by creating a Slack App inside ...@@ -100,9 +84,9 @@ The value for the `url` property must be optained by creating a Slack App inside
Accounts may be managed using these REST API endpoints: Accounts may be managed using these REST API endpoints:
* [GET Account](rest_api_destination_get.md) * [Get Account](rest_api_account_get.md)
* [PUT Account](rest_api_destination_put.md) * [Put Account](rest_api_account_put.md)
* [DELETE Account](rest_api_destination_delete.md) * [Delete Account](rest_api_account_delete.md)
* [Search Account](rest_api_destination_search.md) * [Search Account](rest_api_account_search.md)
...@@ -21,30 +21,32 @@ description: ...@@ -21,30 +21,32 @@ description:
When the checks configured in a watch found a situation to be noteworthy, it's time to take action. This is done using the equally named watch building block: Actions. When the checks configured in a watch found a situation to be noteworthy, it's time to take action. This is done using the equally named watch building block: Actions.
Actions can be used to send notifications by e-mail or other messaging services such as Slack. Also, actions allow to write data to Elasticsearch indexes. A general purpose mechanism to invoke external services is the webhook action which allows making HTTP requests to configurable endpoints. Actions can be used to send notifications by e-mail or other messaging services such as [Slack](actions_slack.md). Also, actions allow to write data to [Elasticsearch indices](actions_index.md). A general purpose mechanism to invoke external services is the [webhook action](actions_webhook.md) which allows making HTTP requests to configurable endpoints.
A watch can have several actions; either for sending notifications via different media, or for acting differently depending on the situation. A watch can have several actions; either for sending notifications via different media, or for acting differently depending on the situation.
Actions are generally invoked if all checks configured for a watch ran with a positive result. Thus, if a condition configured in the checks evaluates to false, watch execution is aborted an no actions are invoked. The actions operate on the runtime data collected by these checks. ## Invoking actions
Still, it is possible to configure further action-specific checks. This way, it is for example possible to configure different escalation levels: Certain actions will be only triggered when deemed values exceed a further threshold. Also, action-specific checks can be used to prepare further runtime data for the action. Modifications of the runtime data done by action-specific checks are always scoped to this action and are invisible to other actions. Actions are generally invoked if all checks configured for a watch ran with a positive result. Thus, if a condition configured in the checks evaluates to false, watch execution is aborted an no actions are invoked. The actions operate on the runtime data collected by these checks.
In order to avoid getting spammed or flooded by automatic notifications caused by actions, Signals provides two mechanisms: Throttling automatically suppresses the repeated execution of actions for a configurable amount of time. Furthermore, users can acknowledge actions which suppresses action execution until the checks of a watch change their state. Still, it is possible to configure further action-specific checks. This way, it is for example possible to configure different escalation levels: Certain actions will only be triggered when certain values exceed a further threshold. Also, action-specific checks can be used to prepare further runtime data for the action. Modifications of the runtime data done by action-specific checks are always scoped to this action and are invisible to other actions.
## Action Types ## Action Types
These actions are available right now: These actions are available at the moment:
**E-Mail Action:** Sends e-mails to configurable recipients. Mail content can be defined using templating. **[E-Mail Action](actions_email.md):** Sends e-mails to configurable recipients. Mail content can be defined using templating.
**Slack Action:** Sends Slack messages to configurable recipients. Message content is templateable as well. **[Slack Action](actions_slack.md):** Sends Slack messages to configurable recipients. Message content is templateable as well.
**Webhook Actions:** Sends HTTP requests to external services. **[Webhook Actions](actions_webhook.md):** Sends HTTP requests to external services.
**Index Action:** Writes data to an Elasticsearch index. **[Index Action](actions_index.md):** Writes data to an Elasticsearch index.
## Action Throttling ## Action Throttling
In order to avoid getting spammed or flooded by automatic notifications caused by actions, Signals provides two mechanisms: Throttling automatically suppresses the repeated execution of actions for a configurable amount of time. Furthermore, users can acknowledge actions which suppresses action execution until the checks of a watch change their state.
For each action, a throttle period can be configured. Throttle periods are time durations during which execution of the particular action will be suppressed after the it was executed. This way, a watch can be configured to be run very frequently in order to get quickly notified about newly commencing situations. Yet, actions would be triggered less frequently – in the frequency configured by the throttle period. For each action, a throttle period can be configured. Throttle periods are time durations during which execution of the particular action will be suppressed after the it was executed. This way, a watch can be configured to be run very frequently in order to get quickly notified about newly commencing situations. Yet, actions would be triggered less frequently – in the frequency configured by the throttle period.
If actions are throttled, the watches are still executed. The watch log will contain information about the execution and list the respective actions as throttled. If actions are throttled, the watches are still executed. The watch log will contain information about the execution and list the respective actions as throttled.
...@@ -65,8 +67,8 @@ All action types share a set of common configuration properties. Consider the fo ...@@ -65,8 +67,8 @@ All action types share a set of common configuration properties. Consider the fo
```json ```json
{ {
/* ... */
...
"actions": [ "actions": [
{ {
"type": "email", "type": "email",
...@@ -78,7 +80,7 @@ All action types share a set of common configuration properties. Consider the fo ...@@ -78,7 +80,7 @@ All action types share a set of common configuration properties. Consider the fo
} }
], ],
"throttle_period": "1h", "throttle_period": "1h",
/* ... */ ...
} }
] ]
} }
...@@ -86,11 +88,9 @@ All action types share a set of common configuration properties. Consider the fo ...@@ -86,11 +88,9 @@ All action types share a set of common configuration properties. Consider the fo
The common configuration attributes are: The common configuration attributes are:
**type:** The type of the action. Required. Can be index, email, slack or webhook right now. | Name | Description |
|---|---|
**name:** A name identifying this action. Required. | type | The type of the action. Required. Can be index, email, slack or webhook right now. |
| name | A name identifying this action. Required. |
**checks:** Further checks which can gather or transform data and decide whether to execute the actual action. Optional. | checks | Further checks which can gather or transform data and decide whether to execute the actual action. Optional. |
| throttle_period | The throttle period. Optional. Specify the time duration using an *amount*, followed by its *unit*. Supported units are m (minutes), h (hours), d (days), w (weeks). For example, `1h` means one hour. |
**throttle_period:** The throttle period. Optional. Specify the time duration using an *amount*, followed by its *unit*. Supported units are m (minutes), h (hours), d (days), w (weeks). For example, `1h` means one hour.
...@@ -18,8 +18,6 @@ description: ...@@ -18,8 +18,6 @@ description:
Use e-mail actions to send e-mail notifications from watches. You can use Mustache templates to define dynamic content for mail subject and content. Use e-mail actions to send e-mail notifications from watches. You can use Mustache templates to define dynamic content for mail subject and content.
% LATER: attachments
## Prerequisites ## Prerequisites
In order to use e-mail actions, you need to configure an SMTP server using the [accounts registry](accounts.md) of Signals. In order to use e-mail actions, you need to configure an SMTP server using the [accounts registry](accounts.md) of Signals.
...@@ -66,5 +64,8 @@ The basic configuration attributes are: ...@@ -66,5 +64,8 @@ The basic configuration attributes are:
**text_body:** Defines the content of the mail. Mustache templates can be used to render attributes from the watch runtime data. Optional. **text_body:** Defines the content of the mail. Mustache templates can be used to render attributes from the watch runtime data. Optional.
Note that HTML mails are not supported right now. ## Technical Preview Limitations
* HTML mails are not supported
* Attachements are not supported
...@@ -85,4 +85,6 @@ Further configuration attributes are: ...@@ -85,4 +85,6 @@ Further configuration attributes are:
**timeout:** If the index operation does not complete in the specified time (in seconds), it will be aborted. Optional; default is 60 seconds. **timeout:** If the index operation does not complete in the specified time (in seconds), it will be aborted. Optional; default is 60 seconds.
## Technical Preview Limitations
* It's not possible yet to write the data back to a remote Elasticsearch cluster
\ No newline at end of file
...@@ -3,7 +3,6 @@ title: Administration ...@@ -3,7 +3,6 @@ title: Administration
html_title: Signals Alerting Administration html_title: Signals Alerting Administration
slug: elasticsearch-alerting-administration slug: elasticsearch-alerting-administration
category: signals category: signals
subcategory: administration
order: 1100 order: 1100
layout: docs layout: docs
edition: preview edition: preview
...@@ -27,7 +26,11 @@ The following configuration options can be made in the elasticsearch.yml configu ...@@ -27,7 +26,11 @@ The following configuration options can be made in the elasticsearch.yml configu
**signals.enabled:** Can be used to enable or disable Signals on the respective node. Optional, boolean, defaults to true. **signals.enabled:** Can be used to enable or disable Signals on the respective node. Optional, boolean, defaults to true.
**signals.tenant.{tenant_name}.node_filter:** Can be used to restrict the nodes a tenant runs on. Optional. The value is a node filter as documented here: https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster.html **signals.tenant.{tenant_name}.node\_filter:** Can be used to restrict the nodes a tenant runs on. Optional. The value is a node filter as documented here: https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster.html
**Note:** Be careful to configure these options consistently for the whole cluster. Having inconsistent configuration across different nodes can cause watches not to be executed at all. Also it can happen that watches are executed multiple times. ## Technical Preview Limitations
At the moment, these settings are configured in elasticsearch.yml. Be careful to configure these options consistently for the whole cluster. Having inconsistent configuration across different nodes can cause watches not to be executed at all. Also it can happen that watches are executed multiple times.
The configuration will become dynamic in future releases and will be kept consistent onthe cluster automatically.
...@@ -27,5 +27,5 @@ In actions, conditions can be used to control if a certain action should be exec ...@@ -27,5 +27,5 @@ In actions, conditions can be used to control if a certain action should be exec
Currently, the following condition types are supported Currently, the following condition types are supported
* condition.script * [condition.script](conditions_script.md)
* a condition that uses a Painless script * a condition that uses a Painless script
\ No newline at end of file
...@@ -16,7 +16,7 @@ description: ...@@ -16,7 +16,7 @@ description:
{% include toc.md %} {% include toc.md %}
A script condition is a Painless script that has access to the complete execution context and returns a boolean value. A script condition is a Painless script that has access to the complete execution runtime data and returns a boolean value.
If the script returns false, the execution flow is aborted. If it returns true, the execution flow continues. If the script returns false, the execution flow is aborted. If it returns true, the execution flow continues.
...@@ -69,7 +69,7 @@ To run a stored script, refer to it by using it's id: ...@@ -69,7 +69,7 @@ To run a stored script, refer to it by using it's id:
## Accessing the runtime data ## Accessing the runtime data
All scripts have full access to the runtime data, gathered for example by Elasticsearch or HTTP inputs. All scripts have full access to the runtime data, gathered for example by [Elasticsearch](inputs_elasticsearch.md) or [HTTP](inputs_http.md) inputs.
The runtime data is available via the `data` prefix. The runtime data is available via the `data` prefix.
......
--- ---
title: Execution chain and payload title: Execution chain and payload
html_title: Chaining Inputs, Transformations and Conditions html_title: Execution chain and execution runtime data
slug: elasticsearch-alerting-chaining-checks slug: elasticsearch-alerting-chaining-checks
category: signals category: signals
order: 250 order: 250
...@@ -20,7 +20,7 @@ description: ...@@ -20,7 +20,7 @@ description:
Each watch can define as many inputs, transformations, calculations and conditions as required, in any order. Each watch can define as many inputs, transformations, calculations and conditions as required, in any order.
Each step in the execution chain is called a *check*. Example: Each step in the execution chain is called a *check*. Example:
``` ```
{ {
...@@ -61,17 +61,19 @@ Each step in the execution chain is called a *check*. Example: ...@@ -61,17 +61,19 @@ Each step in the execution chain is called a *check*. Example:
All checks and actions operate on the watch runtime data. All checks and actions operate on the watch runtime data.
[Input](inputs.md) checks can add data to the context; either under a specific property name or at the top level, replacing all data that was possibly stored before. [Transformations](transformations_transformations.md) transform existing data, [Calculations](transformations_calculations.md) add data based on existing data, and [Conditions](conditions.md) control the execution flow based on the runtime data. [Input](inputs.md) checks can add data to the context; either under a specific property name or at the top level, replacing all data that was possibly stored before.
[Transformations](transformations_transformations.md) transform existing data, [Calculations](transformations_calculations.md) add data based on existing data, and [Conditions](conditions.md) control the execution flow based on the runtime data.
[Actions](actions.md) send out notifications based on the runtime data, or store all or parts of the runtime data on a data sink, like Elasticsearch. [Actions](actions.md) send out notifications based on the runtime data, or store all or parts of the runtime data on a data sink, like Elasticsearch.
<p align="center"> <p align="center">
<img src="runtime_context.png" style="width: 40%" class="md_image"/> <img src="runtime_context.png" style="width: 50%" class="md_image"/>
</p> </p>
### Adding data to the runtime data ### Adding data to the runtime data
[Inputs](inputs.md) and [Transformations](transformations_transformations.md) fetch data and place it in the runtime data under a name specified by the `target` of the check. Example: [Inputs](inputs.md) and [Transformations](transformations_transformations.md) fetch data and place it in the runtime data under a name specified by the `target` of the check. Example:
``` ```
{ {
......
...@@ -26,11 +26,11 @@ Signals can be used to create and execute watches that: ...@@ -26,11 +26,11 @@ Signals can be used to create and execute watches that:
## Log file analysis example ## Log file analysis example
Assume you are ingesting log files from production systems to Elasticsearch. The most typical usecase is to use Signals to detect an unusual amount of errors. Assume you are ingesting log files from production systems to Elasticsearch. The most typical use case is to use Signals to detect an unusual amount of errors.
You can use Signals to: You can use Signals to:
* run an aggregation periodically on the logs index that counts the amount of errors in the last 5 minutes * run an aggregation periodically on the logs index that counts the number of errors in the last 5 minutes
* implement a condition that checks whether the error level is above a certain threshold * implement a condition that checks whether the error level is above a certain threshold
* if the condition is met, send out notifications via Email or Slack to inform your DevOps team. * if the condition is met, send out notifications via Email or Slack to inform your DevOps team.
...@@ -43,43 +43,41 @@ You can use Signals to ...@@ -43,43 +43,41 @@ You can use Signals to
* run an aggregation periodically on the auditlog index that looks for documents where the category is FAILED\_LOGIN\_ATTEMPTS * run an aggregation periodically on the auditlog index that looks for documents where the category is FAILED\_LOGIN\_ATTEMPTS
* aggregate the documents by username and count the failed login attempts * aggregate the documents by username and count the failed login attempts
* retain all aggregations where the number of login attempts in the last 30 minutes is above a certain threshold * retain all aggregations where the number of login attempts in the last 30 minutes is above a certain threshold
* Enrich the remaining aggregations by pulling in Geo information from a REST API * Enrich the remaining aggregations by pulling in Geoinformation from a REST API
* send out an email and/or Slack notification * send out an email and/or Slack notification
* send an addition escalation email if the issue persist for more than 1 hour * send an addition escalation email if the issue persists for more than 1 hour
## Building blocks of a Signals watch ## Building blocks of a Signals watch
The basic working principle of a watch goes as follows: After a watch has been *triggered*, it *checks* for specific conditions and takes *action* if necessary.
After a watch has been *triggered*, it *checks* for certain conditions, and takes *action* if necessary.
These three elements also form the three major building blocks of a Signals watch: These three elements also form the three major building blocks of a Signals watch:
* **[Triggers](triggers.md)** define when a watch will be executed. Each watch should have at least on trigger * **[Triggers](triggers.md)** define when a watch will be executed. Each watch should have at least one trigger
* **Checks** are constructs meant for analyzing the situation to be watched. For doing so, Signals offers * **Checks** are constructs meant for analyzing the situation to be watched. For doing so, Signals offers
* *[Inputs](inputs.md)* which pull in data from a source such as an Elasticsearch index or a HTTP service; * *[Inputs](inputs.md)* which pull in data from a source such as an Elasticsearch index or an HTTP service;
* *[Conditions](conditions.md)* to analyze the gathered data using scripts and decide whether to proceed with execution or to abort; * *[Conditions](conditions.md)* to analyze the gathered data using scripts and decide whether to proceed with execution or to abort;
* *[Transformations and calculations](transformations.md)* to transform the gathered data into a format that subsequent operations may require. * *[Transformations and calculations](transformations.md)* to transform the gathered data into a format that subsequent operations may require.
* Each watch can have several checks, which are executed as a chain. Each action of a watch can have a further chain of checks. * Each watch can have several checks, which are executed as a chain. Each action of a watch can also have a chain of checks.
* **[Actions](actions.md)** are executed if all preceding conditions are met. * **[Actions](actions.md)** are executed if all preceding conditions are met.
* Actions be used to alert users via [Email](actions_email.md), [Slack](actions_slack.md), or PagerDuty (coming soon). * Actions can be used to alert users via [Email](actions_email.md), [Slack](actions_slack.md), or PagerDuty (coming soon).
* Actions can be used to write the runtime data back to data sinks like an [Elasticsearch index](actions_index.md). * Actions can be used to write the runtime data back to data sinks like an [Elasticsearch index](actions_index.md).
* Using the [Webhook action](actions_webhook.md), it is actually possible to invoke any kind of operation as result of a Signals watch. * Using the [Webhook action](actions_webhook.md), it is possible to invoke any HTTP service as a result of a Signals watch.
* Each watch can have several actions. The action-specific checks can be used to select which actions are to be executed in which situation. * Each watch can have several actions. Action-specific checks can be used to decide which actions are executed in which situation.
## Watch Runtime Data ## Watch Runtime Data
All watch operations operate on the so-called watch runtime data. Index inputs put the gathered data into the runtime data; conditions can read it and transforms can modify it. Actions read from the runtime data as well. All watches operate on the so-called watch runtime data. Inputs put the gathered data into the runtime data; conditions can read it and transforms can modify it. Actions read from the runtime data as well.
The runtime data is formed like a hierarchical key/value document, quite similar to a document stored in an Elasticsearch index. The runtime data is formed like a hierarchical key/value document, quite similar to a document stored in an Elasticsearch index.
The checks of a watch subsequently modify the runtime data. If action-specific checks are defined, these will be operating on isolated copies of the runtime data. So, modifications of the runtime data done for one action does have no effect on the runtime data visible for other actions. The checks of a watch subsequently modify the runtime data. If action-specific checks are defined, these will be operating on isolated copies of the runtime data. So, modifications of the runtime data for one action have no effect on the runtime data visible for other actions.
## Overview ## Overview
<p align="center"> <p align="center">
<img src="watch_anatomy.png" style="width: 30%" class="md_image"/> <img src="watch_anatomy.png" style="width: 40%" class="md_image"/>
</p> </p>
## Sample Watch ## Sample Watch
......
...@@ -21,11 +21,11 @@ Each input will fetch data from a data source, and place it in the runtime data ...@@ -21,11 +21,11 @@ Each input will fetch data from a data source, and place it in the runtime data
At the moment, Signals supports the following input types: At the moment, Signals supports the following input types:
* Constants * [Constants](inputs_static.md)
* Define constants you can then use at multiple places in the execution chain * Define constants you can then use at multiple places in the execution chain
* Elasticsearch * [Elasticsearch](inputs_elasticsearch.md)
* Use the full power of Elasticsearch queries and aggregations * Use the full power of Elasticsearch queries and aggregations
* HTTP * [HTTP](inputs_http.md)
* Pull in data from a REST endpoint * Pull in data from a REST endpoint
All data from all inputs can be combined by using [Transformation](transformations_transformations.md) and [Calculations](transformations_calculations.md), used in [Conditions](conditions.md) and pushed to [action endpoints](actions.md). All data from all inputs can be combined by using [Transformation](transformations_transformations.md) and [Calculations](transformations_calculations.md), used in [Conditions](conditions.md) and pushed to [action endpoints](actions.md).
......
...@@ -68,7 +68,7 @@ Example: ...@@ -68,7 +68,7 @@ Example:
| target | the name under which the data is available in later execution steps. | | target | the name under which the data is available in later execution steps. |
| request | The search request to execute | | request | The search request to execute |
| request.indices | The indices to execute the `request.query` against. **The user that defines the watch needs to have a role that has access to the specified index / indices.**| | request.indices | The indices to execute the `request.query` against. **The user that defines the watch needs to have a role that has access to the specified index / indices.**|
| request.body | The body of the search request. You can use all features of the Elasticsearch query and aggregation DSL here. All attributes of the request body can be dynamically defined using Mustache templates.| | request.body | The body of the search request. You can use all features of the Elasticsearch query and aggregation DSL here. **All attributes of the request body can be dynamically defined using Mustache templates**.|
......
...@@ -17,9 +17,11 @@ description: ...@@ -17,9 +17,11 @@ description:
{% include toc.md %} {% include toc.md %}
An HTTP input pulls in data by accessing an HTTP endpoint. Most commonly, this will be a REST API. All data from all inputs can be combined by using [Transformation](transformations_transformations.md) and [Calculations](transformations_calculations.md), used in [Conditions](conditions.md) and pushed to [action endpoints](actions.md). An HTTP input pulls in data by accessing an HTTP endpoint. Most commonly, this will be a REST API.
For example, if you aggregate data from the [Search Guard Audit Log](auditlog), you can use an HTTP input to retrieve Geo Data information for the logged IP adresses. All data from all inputs can be combined by using [Transformation](transformations_transformations.md) and [Calculations](transformations_calculations.md), used in [Conditions](conditions.md) and pushed to [action endpoints](actions.md).
For example, if you aggregate data from the [Search Guard Audit Log](auditlog), you can use an HTTP input to retrieve Geo Data information for the logged IP adresses and enrich the data from the audit log.
## Example ## Example
...@@ -46,7 +48,7 @@ For example, if you aggregate data from the [Search Guard Audit Log](auditlog), ...@@ -46,7 +48,7 @@ For example, if you aggregate data from the [Search Guard Audit Log](auditlog),
| target | the name under which the data is available in later execution steps. | | target | the name under which the data is available in later execution steps. |
| request | The HTTP request details | | request | The HTTP request details |
| request.url | The URL for this HTTP input | | request.url | The URL for this HTTP input |
| request.method | One of GET|PUT|POST|DELETE | | request.method | One of: GET, PUT, POST, DELETE |
| request.auth | Optional. The authentication method for the HTTP request. | | request.auth | Optional. The authentication method for the HTTP request. |
| request.body | The body of the HTTP request. Optional. Mustache templates can be used to render attributes from the watch runtime data. | | request.body | The body of the HTTP request. Optional. Mustache templates can be used to render attributes from the watch runtime data. |
...@@ -87,7 +89,8 @@ The HTTP endpoint in the `request.url` attribute cannot be changed dynamically d ...@@ -87,7 +89,8 @@ The HTTP endpoint in the `request.url` attribute cannot be changed dynamically d
Authentication credentials are configured in the `auth` section if the `request` configuration. At the time of writing, the only authentication method is HTTP Basic Authentication. Authentication credentials are configured in the `auth` section if the `request` configuration. At the time of writing, the only authentication method is HTTP Basic Authentication.
**Note:** In the current version of the tech preview, the password is stored unencrypted and returned in verbatim when the watch is retrieved using the REST API. Future versions will provide a more secure way of storing authentication data. ### Technical Preview Limitations
In the current version of the tech preview, the password is stored unencrypted and returned in verbatim when the watch is retrieved using the REST API. Future versions will provide a more secure way of storing authentication data.
## Advanced Functionality ## Advanced Functionality
...@@ -99,4 +102,4 @@ Furthermore, HTTP inputs provide these configuration options: ...@@ -99,4 +102,4 @@ Furthermore, HTTP inputs provide these configuration options:
## Security Considerations ## Security Considerations
Keep in mind that webhook actions allow to send arbitrary HTTP requests from Elasticsearch nodes. We are still working on mechanisms to define restrictions on the use of webhook actions and the allowed endpoints. Keep in mind that webhook actions allow to send arbitrary HTTP requests from Elasticsearch nodes. We are working on mechanisms to define restrictions on the use of webhook actions and the allowed endpoints.
...@@ -29,7 +29,8 @@ Example: ...@@ -29,7 +29,8 @@ Example:
"value": { "value": {
"threshold": 10, "threshold": 10,
"time_period": "10s", "time_period": "10s",
"admin_lastname": "Anderson", "admin_firstname": "Paul" "admin_lastname": "Anderson",
"admin_firstname": "Paul"
} }
} ], } ],
"actions": [ ... ] "actions": [ ... ]
...@@ -44,7 +45,7 @@ Example: ...@@ -44,7 +45,7 @@ Example:
## Accessing static input data in the execution chain ## Accessing static input data in the execution chain
In this example, the constant values defined in the `value`section can be accessed in later execution steps. Examples: In this example, the constant values defined in the `value` section can be accessed in later execution steps. Examples:
Usage in a trigger: Usage in a trigger:
...@@ -64,7 +65,7 @@ Usage in an action: ...@@ -64,7 +65,7 @@ Usage in an action:
... ...
"email": { "email": {
... ...
"body": "Dear {{data.myconstants.admin_firstname}}. There are too many error in the system, see attached data", "body": "Dear {{data.myconstants.admin_firstname}}. There are too many errors in the system, see attached data"
} }
} }
] ]
......
...@@ -46,12 +46,13 @@ The user does not have the permission to delete accounts. ...@@ -46,12 +46,13 @@ The user does not have the permission to delete accounts.