About the connector
ElasticSearch is a distributed, RESTful search and analytics engine capable of solving a number of use cases. As the heart of the Elastic Stack, it centrally stores your data so you can discover the expected and uncover the unexpected.
This document provides information about the ElasticSearch connector, which facilitates automated interactions, with an ElasticSearch server using FortiSOAR™ playbooks. Add the ElasticSearch connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving cluster details and health information about the cluster configured on you ElasticSearch instance, returning a list of indices configured on your ElasticSearch instance, and running a query on your ElasticSearch instance.
Version information
Connector Version: 1.0.0
Compatibility with FortiSOAR™ Versions: 4.9.0.0-708 and later
Compatibility with ElasticSearch Versions: 6.1 and later
Installing the connector
For the procedure to install a connector, click here.
Prerequisites to configuring the connector
- You must have the FQDN or IP address of the ElasticSearch server to which you will connect and perform the automated operations and credentials to access that server.
- To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.
Configuring the connector
For the procedure to configure a connector, click here.
Configuration parameters
In FortiSOAR™, on the Connectors page, select the ElasticSearch connector and click Configure to configure the following parameters:
| Parameter |
Description |
| Server Address |
FQDN or IP address of the ElasticSearch server to which you will connect and perform the automated operations. |
| Protocol |
Protocol used to remotely connect to the ElasticSearch server. Choose between http or https.
By default, https is used. |
| Username |
Username to access the ElasticSearch server to which you will connect and perform the automated operations. |
| Password |
Password to access the ElasticSearch server to which you will connect and perform the automated operations. |
| Verify SSL |
Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True. |
Actions supported by the connector
The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:
| Function |
Description |
Annotation and Category |
| Get Cluster Details |
Retrieves cluster details and the health information about the cluster configured on your ElasticSearch instance. |
get_cluster_details
Investigation |
| Get Mapping |
Retrieves a list of indices, which includes the type of indices that are currently configured on your ElasticSearch instance. |
get_mapping
Investigation |
| Execute Query |
Executes a query and fetches data from your ElasticSearch instance, based on the input filters. |
execute_query
Investigation |
operation: Get Cluster Details
Input parameters
| Parameter |
Description |
| Level |
Level up to which details and health information is retrieved from your ElasticSearch instance. Level can be Cluster, Indices, or Shards. By default, it is set to Cluster. |
| Timeout in Seconds |
Default time, in seconds, that the connector will wait for to retrieve cluster details from your ElasticSearch instance before timing out.
By default, it is set to 30 seconds. |
| Minimal Active Shards |
Minimum number of shards that must be active for health information is retrieved from ElasticSearch. |
Output
The JSON output contains the details and health information of the cluster configured on your ElasticSearch instance.
Following image displays a sample output:
operation: Get Mapping
Input parameters
| Parameter |
Description |
| Index |
An index is a logical namespace that maps to one or more primary shards and can have zero or more replica shards.
You can specify a particular index or if you search for all indices, which are currently configured on your ElasticSearch instance, use _all. |
| Type |
Type in ElasticSearch represents a class of similar documents.
Specify the type of indices for which you want to retrieve details. |
Output
The JSON output contains a list of indices, which includes the type of indices that are currently configured on your ElasticSearch instance.
Following image displays a sample output:
operation: Execute Query
Input parameters
| Parameter |
Description |
| Query |
Stringified JSON formatted query used for searching data in ElasticSearch.
For example:
{"id": "template_1", "params": {"query_string": "search for these words" }} |
| Index |
An index is a logical namespace that maps to one or more primary shards and can have zero or more replica shards.
Specify a particular index, based on which you want to run the query. |
| Type |
Type in ElasticSearch represents a class of similar documents.
Specify the type of indices, based on which you want to run the query. |
| Routing |
Name of the shard for which you want to retrieve data. |
Output
The JSON output contains details of the record that matches the query you have specified.
Following image displays a sample output:
Included playbooks
The Sample-ElasticSearch-1.0.0 playbook collection comes bundled with the ElasticSearch connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the ElasticSearch connector.
- Get Mapping
- Execute Query
- Get Cluster Details
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection, since the sample playbook collection gets deleted during connector upgrade and delete.
