Fortinet Document Library

Version:

Version:


Table of Contents

Copy Link

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: 2.1.1

FortiSOAR™ Version Tested on: 4.12.0-746

Authored By: Fortinet 

Certified: Yes

Release Notes for version 2.1.1

Following enhancements have been made to the ElasticSearch Connector in version 2.1.1:

  • Removed the "Impersonate User" configuration parameter.
  • Added the Get Saved Search operation and playbook.
  • Changed all the input parameters for the Get Cluster Details operation.
  • Added the "Run As User" input parameter for the Get Cluster Details, Execute Query, and Get Mapping operations.

Installing the connector

All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:

yum install cyops-connector-elasticsearch

For the detailed 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  (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
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 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": {}
}

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 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 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:
{
     "took": "",
     "hits": "",
     "_shards": "",
     "timed_out": ""
}

operation: Get Saved Search

Input parameters

Parameter Description
Object ID     ID of the object whose saved searches 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.1.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.

  • Get Cluster Details
  • Get Mapping
  • Get Saved Search
  • Execute Query

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.

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: 2.1.1

FortiSOAR™ Version Tested on: 4.12.0-746

Authored By: Fortinet 

Certified: Yes

Release Notes for version 2.1.1

Following enhancements have been made to the ElasticSearch Connector in version 2.1.1:

Installing the connector

All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:

yum install cyops-connector-elasticsearch

For the detailed procedure to install a connector, click here.

Prerequisites to configuring the connector

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
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 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": {}
}

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 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 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:
{
     "took": "",
     "hits": "",
     "_shards": "",
     "timed_out": ""
}

operation: Get Saved Search

Input parameters

Parameter Description
Object ID     ID of the object whose saved searches 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.1.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.

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.