Skip to main content

Elasticsearch v2

This Integration is part of the Elasticsearch Pack.#

Search for and analyze data in real time. Supports version 6 and later.

Permissions#

The permissions required to use this integration depends on which operations you need to perform. The API user should have the same permissions a regular user would have in order to access the data via the UI. Following are the permissions needed for certain commands:

  • !es-eql-search/search/es-search/fetch-incidents - If the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias.
  • !get-mapping-fields - If the Elasticsearch security features are enabled, you must have the view_index_metadata or manage index privilege for the target data stream, index, or alias.
  • !es-index - If the Elasticsearch security features are enabled, you must have the write index privilege for the target data stream, index, or alias.

Configure Elasticsearch v2 on Cortex XSOAR#

  1. Navigate to Settings > Integrations > Servers & Services.

  2. Search for Elasticsearch v2.

  3. Click Add instance to create and configure a new integration instance.

    ParameterDescriptionRequired
    Server URLThe Elasticsearch server to which the integration connects. Ensure that the URL includes the correct Elasticsearch port. By default this is 9200.True
    Username for server loginProvide Username + Passoword instead of API key + API IDFalse
    Trust any certificate (not secure)False
    Use system proxy settingsFalse
    Client typeIn some hosted ElasticSearch environments, the standard ElasticSearch client is not supported. If you encounter any related client issues, please consider using the OpenSearch client type.False
    Index from which to fetch incidents (CSV)False
    Query StringThe query will be used when fetching incidents. Index time field will be used as a filter in the queryFalse
    Index time field (for sorting sort and limiting data)The time field on which sorting and limiting are performed. If using a nested field, separate field names using dot notation.False
    Raw QueryWill override the 'Query String' Lucene syntax string. Results will not be filtered.False
    Time field typeFalse
    Map JSON fields into labelsFalse
    First fetch timestamp (<number> <time unit>, e.g., 12 hours, 7 days)False
    The maximum number of results to return per fetch.False
    Request timeout (in seconds).False
    Incident typeFalse
    Fetch incidentsFalse
  4. Click Test to validate the URLs, token, and connection.

Commands#

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

es-search#


Queries an index.

Base Command#

es-search

Input#

Argument NameDescriptionRequired
indexThe index in which to perform a search.Required
queryThe string to query (in Lucene syntax). Possible values are: .Optional
fieldsA comma-separated list of document fields to fetch. If empty, the entire document is fetched.Optional
explainCalculates an explanation of a score for a query. For example, "value:1.6943597". Possible values are: true, false. Default is false.Optional
pageThe page number from which to start a search. Default is 0.Optional
sizeThe number of documents displayed per page. Can be an integer between "1" and "10,000". Default is 100.Optional
sort-fieldThe field by which to sort the results table. The supported result types are boolean, numeric, date, and keyword fields. Keyword fields require the doc_values parameter to be set to "true" from the Elasticsearch server. Possible values are: .Optional
sort-orderThe order by which to sort the results table. The results tables can only be sorted if a sort-field is defined. Possible values are: asc, desc. Default is asc.Optional
query_dslWill overwrite the ‘query' arguments.Optional
timestamp_range_startThe starting time of the time range.Optional
timestamp_range_endThe ending time of the time range.Optional
timestamp_fieldTimestamp field name. Default is @timestamp.Optional

Context Output#

PathTypeDescription
Elasticsearch.Search.Results._indexStringThe index to which the document belongs.
Elasticsearch.Search.Results._idStringThe ID of the document.
Elasticsearch.Search.Results._typeStringThe mapping type of the document.
Elasticsearch.Search.max_scoreNumberThe maximum relevance score of a query.
Elasticsearch.Search.QueryStringThe query performed in the search.
Elasticsearch.Search.total.valueNumberThe number of search results.
Elasticsearch.Search.Results._scoreNumberThe relevance score of the search result.
Elasticsearch.Search.IndexStringThe index in which the search was performed.
Elasticsearch.Search.ServerStringThe server on which the search was performed.
Elasticsearch.Search.timed_outBooleanWhether the search stopped due to a timeout.
Elasticsearch.Search.tookNumberThe time in milliseconds taken for the search to complete.
Elasticsearch.Search.PageNumberThe page number from which the search started.
Elasticsearch.Search.SizeNumberThe maximum number of scores that a search can return.

search#


Searches an index.

Base Command#

search

Input#

Argument NameDescriptionRequired
indexThe index in which to perform a search.Required
queryThe string to query (in Lucene syntax). Possible values are: .Optional
fieldsA comma-separated list of document fields to fetch. If empty, fetches the entire document.Optional
explainCalculates an explanation of a score for a query. For example, "value:1.6943597". Possible values are: true, false. Default is false.Optional
pageThe page number from which to start a search. Default is 0.Optional
sizeThe number of documents displayed per page. Can be an integer between "1" and "10,000". Default is 100.Optional
sort-fieldThe field by which to sort the results table. The supported result types are boolean, numeric, date, and keyword fields. Keyword fields require the doc_values parameter to be set to "true" from the Elasticsearch server. Possible values are: .Optional
sort-orderThe order by which to sort the results table. The results tables can only be sorted if a sort-field is defined. Possible values are: asc, desc. Default is asc.Optional
timestamp_fieldTimestamp field name. Default is @timestamp.Optional

Context Output#

PathTypeDescription
Elasticsearch.Search.Results._indexStringThe index to which the document belongs.
Elasticsearch.Search.Results._idStringThe ID of the document.
Elasticsearch.Search.Results._typeStringThe mapping type of the document.
Elasticsearch.Search.max_scoreNumberThe maximum relevance score of a query.
Elasticsearch.Search.QueryStringThe query performed in the search.
Elasticsearch.Search.total.valueNumberThe number of search results.
Elasticsearch.Search.Results._scoreNumberThe relevance score of the search result.
Elasticsearch.Search.IndexStringThe index in which the search was performed.
Elasticsearch.Search.ServerStringThe server on which the search was performed.
Elasticsearch.Search.timed_outBooleanWhether the search stopped due to a time out.
Elasticsearch.Search.tookNumberThe time in milliseconds taken for the search to complete.
Elasticsearch.Search.PageNumberThe page number from which the search started.
Elasticsearch.Search.SizeNumberThe maximum number of scores that a search can return.

get-mapping-fields#


Returns the schema of the index to fetch from. This commmand should be used for debugging purposes.

Base Command#

get-mapping-fields

Input#

There are no input arguments for this command.

Context Output#

There is no context output for this command.

es-eql-search#


Search using EQL query

Base Command#

es-eql-search

Input#

Argument NameDescriptionRequired
indexThe index in which to perform a search.Required
queryThe string to query (in Lucene syntax).Required
fieldsA comma-separated list of document fields to fetch. If empty, fetches the entire document.Optional
sort-tiebreakerIf two or more events share the same timestamp, Elasticsearch uses a tiebreaker field value to sort the events in ascending order.Optional
filterFilter using query DSL.Optional
event_category_fieldThe event category field. Default is event.category.Optional
sizeThe number of documents displayed per page. Can be an integer between "1" and "10,000". Default is 100.Optional
timestamp_range_startThe starting time of the time range.Optional
timestamp_range_endThe ending time of the time range.Optional
timestamp_fieldTimestamp field name. Default is @timestamp.Optional

Context Output#

PathTypeDescription
Elasticsearch.Search.Results._indexStringThe index to which the document belongs.
Elasticsearch.Search.Results._idStringThe ID of the document.
Elasticsearch.Search.Results._typeStringThe mapping type of the document.
Elasticsearch.Search.max_scoreNumberThe maximum relevance score of a query.
Elasticsearch.Search.QueryStringThe query performed in the search.
Elasticsearch.Search.total.valueNumberThe number of search results.
Elasticsearch.Search.Results._scoreNumberThe relevance score of the search result.
Elasticsearch.Search.IndexStringThe index in which the search was performed.
Elasticsearch.Search.ServerStringThe server on which the search was performed.
Elasticsearch.Search.timed_outBooleanWhether the search stopped due to a timeout.
Elasticsearch.Search.tookNumberThe time in milliseconds taken for the search to complete.
Elasticsearch.Search.PageNumberThe page number from which the search started.
Elasticsearch.Search.SizeNumberThe maximum number of scores that a search can return.

es-index#


Indexes a document into an Elasticsearch index.

Base Command#

es-index

Input#

Argument NameDescriptionRequired
index_nameThe name of the index to ingest into.Required
documentThe document object (JSON format) to be indexed. See Elasticsearch documentation for further information about indexing documents via the Elasticsearch client.Required
idThe ID of the indexed document (will be generated if empty). The document will be updated if one with a corresponding ID exists.Optional

Context Output#

PathTypeDescription
Elasticsearch.Index.idStringThe ID of the indexed document.
Elasticsearch.Index.indexStringThe name of the index which the document was ingested to.
Elasticsearch.Index.versionNumberThe version number of the indexed document.
Elasticsearch.Index.resultStringThe result of the index operation.

Command Example#

!es-index index_name=test-xsoar document="{\"name\":\"test\"}" id=1234

Context Example#

{
"Elasticsearch": {
"Index": {
"id": "1234",
"index": "test-xsoar",
"version": 1,
"result": "created"
}
}
}

Human Readable Output#

Indexed document#

IDIndex nameVersionResult
1234test-xsoar1created

es-integration-health-check#


Returns the health status of the integration. This commmand should be used for debugging purposes.

Base Command#

es-integration-health-check

Input#

There are no input arguments for this command.

Context Output#

There is no context output for this command.