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 your ElasticSearch instance, returning a list of indices configured on your ElasticSearch instance, and running a query on your ElasticSearch instance.
Version information
Connector Version: 2.2.1
FortiSOAR™ Version Tested on: 6.4.0-1555
Elastic Search Version Tested on: 7.4.1-1
Authored By: Fortinet
Certified: Yes
Release Notes for version 2.2.1
Following enhancements have been made to the ElasticSearch Connector in version 2.2.1:
- Certified this version of the connector
- Added the annotation for the "Get Saved Search" operation.
- Updated the trigger label in the "Execute Lucene Query" sample playbook for the "Execute Lucene query"
Installing the connector
From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:
yum install cyops-connector-elasticsearch
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 (Username-Password pair) 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, click the ElasticSearch connector row, and in the Configure tab enter the required configuration details.
| Parameter |
Description |
| Server URL |
FQDN or IP address of the ElasticSearch server to which you will connect and perform the automated operations. |
| Protocol |
Protocol used to connect to the ElasticSearch server remotely. 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. |
| Port |
Port number that is used to connect to the ElasticSearch.
By default, this is set to 9200. |
| 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, based on the index you have specified. |
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 |
| Execute Lucene Query |
Executes a search query without using Elastic's DSL Query Syntax.
An example query to search for the term "phishing" in documents where the "status" field is set to 200 would look like this:
phishing AND status:200 |
execute_lucene_query
Investigation |
| Get Saved Search |
Retrieves details of saved searches from ElasticSearch. |
get_saved_search
Investigation |
operation: Get Cluster Details
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.
Specify a particular index whose cluster details you want to retrieve from ElasticSearch. |
| Run As User |
Run As User is a kind of delegation of an account, i.e., the account access is delegated to a different account or an admin account. For example, User X takes on the role of User Y with the help of the "run as user" mechanism. |
Output
The JSON output contains the details and health information of the cluster configured on your ElasticSearch instance.
The output contains the following populated JSON schema:
{
"cluster_details": {
"blocks": {},
"snapshots": {},
"routing_nodes": {},
"nodes": {},
"state_uuid": "",
"master_node": "",
"metadata": {},
"cluster_name": "",
"version": "",
"routing_table": {}
}
}
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. |
| Run As User |
Run As User is a kind of delegation of an account, i.e., the account access is delegated to a different account or an admin account. For example, User X takes on the role of User Y with the help of the "run as user" mechanism. |
Output
The JSON output contains a list of indices, which includes the type of indices that are currently configured on your ElasticSearch instance.
The output contains the following populated JSON schema:
{
"mapping": {}
}
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. |
| Run As User |
Run As User is a kind of delegation of an account, i.e., the account access is delegated to a different account or an admin account. For example, User X takes on the role of User Y with the help of the "run as user" mechanism. |
Output
The JSON output contains details of the record that matches the query you have specified.
The output contains the following populated JSON schema:
{
"_shards": "",
"aggregations": "",
"took": "",
"hits": "",
"timed_out": ""
}
operation: Execute Lucene Query
Input parameters
| Parameter |
Description |
| Query |
Single-line Lucene query used for searching data in ElasticSearch.
For example: EventID: "1" AND ParentImage: "C:\Program Files\*" |
| 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. |
| Run As User |
Run As User is a kind of delegation of an account, i.e., the account access is delegated to a different account or an admin account. For example, User X takes on the role of User Y with the help of the "run as user" mechanism. |
Output
The output contains the following populated JSON schema:
{
"_shards": "",
"aggregations": "",
"took": "",
"hits": "",
"timed_out": ""
}
operation: Get Saved Search
Input parameters
| Parameter |
Description |
| Object ID |
ID of the object whose saved search details you want to retrieve from ElasticSearch. |
| Port |
Port of the Kibana server from which you want to retrieve details of the saved searches. |
Output
The output contains the following populated JSON schema:
{
"version": "",
"id": "",
"updated_at": "",
"type": "",
"attributes": {}
}
Included playbooks
The Sample-ElasticSearch-2.2.1 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.
- Execute Lucene Query
- Execute Query
- Get Cluster Details
- Get Mapping
- Get Saved Search
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 the connector upgrade and delete.
