Skip to content

Elasticsearch#

README

Elastic Security Alert Status Sync#

ElasticSecurity_AlertStatusSync mirrors a TheHive case/alert stage onto the matching Elastic Security detection alert(s), via Kibana's detection alert status API. It runs on thehive:case / thehive:alert.

It targets Kibana, not Elasticsearch (that's the Elasticsearch_Analysis analyzer) — different URL and credentials, hence the separate ElasticSecurity baseConfig.

Alert ID source#

  1. If custom_field_name_alert_id is set, the responder reads that custom field. Required when running on a case.
  2. Otherwise it falls back to TheHive's native sourceRef. This works for alerts imported by Elastic's stock TheHive connector (it sets sourceRef to the alert UUID, which equals the detection alert _id), but sourceRef does not exist on cases.

Either source may hold one _id or a comma-separated list; merged-alert cases producing a list are handled automatically.

We recommend using custom fields, which is elastic-alert-uuid by default.

Status mapping#

Elastic's status enum is fixed (open, acknowledged, in-progress, closed); which one each TheHive stage means is configurable:

TheHive stage Config item Default
New status_new open
InProgress status_in_progress in-progress
Imported status_imported in-progress
Closed status_closed closed

Closing reasons#

When the resulting status is closed, a reason is sent (Elastic ignores it otherwise). The reason_map config item holds the full TheHiveStatus:elastic_reason mapping, pre-filled with:

TheHive status Elastic reason
FalsePositive false_positive
TruePositive true_positive
BenignPositive benign_positive
Duplicated / Duplicate duplicate
Indeterminate / Ignored / Other other

Edit, add or remove pairs as needed (for example, Contained:true_positive for a custom status). Unmapped statuses fall back to default_close_reason (other). Clearing reason_map entirely restores the built-in defaults. Elastic's own reasons are false_positive, duplicate, true_positive, benign_positive, automated_closure and other, but any string up to 1024 chars is accepted.

Setup#

  • Create a Kibana API key that can write to Elastic Security alerts (.alerts-security.alerts-*), or use basic auth — one or the other, not both.
  • kibana_url is the Kibana endpoint, not Elasticsearch. On Elastic Cloud these are different hostnames.
  • Set space_id if alerts live in a non-default Kibana space.
  • Populate custom_field_name_alert_id's field with the Elastic alert _id at alert creation.

ElasticSecurity_AlertStatusSync#

Author: Fabien Bloume, StrangeBee
License: AGPL-V3
Version: 1.0
Supported data types:
- thehive:case
- thehive:alert
Registration required: True
Subscription required: True
Free subscription: True
Third party service: https://www.elastic.co/security

Description#

Sync TheHive case/alert status back to the corresponding Elastic Security detection alert(s), including a closing reason

Configuration#

kibana_url Base Kibana URL, for example https://my-deployment.kb.eu-west-1.aws.found.io. Not the Elasticsearch URL
Default value if not configured __
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
api_key Kibana API key. Needs write access to Elastic Security alerts. Use this or username/password, not both
Default value if not configured __
Type of the configuration item string
The configuration item can contain multiple values False
Is required False
username Kibana username, only if not using an API key
Default value if not configured __
Type of the configuration item string
The configuration item can contain multiple values False
Is required False
password Kibana password, only if not using an API key
Default value if not configured __
Type of the configuration item string
The configuration item can contain multiple values False
Is required False
verify_ssl Verify Kibana's TLS certificate. Disable only for self-signed or lab instances
Default value if not configured True
Type of the configuration item boolean
The configuration item can contain multiple values False
Is required False
space_id Kibana space holding the alerts. Leave empty for the default space
Default value if not configured __
Type of the configuration item string
The configuration item can contain multiple values False
Is required False
custom_field_name_alert_id Custom field in TheHive holding the Elastic alert _id(s), comma separated if more than one. Falls back to the native sourceRef field when empty, which works for alerts imported by Elastic's stock TheHive connector because it sets sourceRef to the alert UUID, and that equals the alert _id. sourceRef does not exist on cases, so set this if the responder will ever run on a thehive:case
Default value if not configured elastic-alert-uuid
Type of the configuration item string
The configuration item can contain multiple values False
Is required False
status_new Elastic status for TheHive's 'New' stage. One of open, acknowledged, in-progress, closed
Default value if not configured open
Type of the configuration item string
The configuration item can contain multiple values False
Is required False
status_in_progress Elastic status for TheHive's 'InProgress' stage. Set to 'acknowledged' instead if your team treats acknowledgement as the working state
Default value if not configured in-progress
Type of the configuration item string
The configuration item can contain multiple values False
Is required False
status_imported Elastic status for TheHive's 'Imported' stage (alerts promoted to a case)
Default value if not configured in-progress
Type of the configuration item string
The configuration item can contain multiple values False
Is required False
status_closed Elastic status for TheHive's 'Closed' stage
Default value if not configured closed
Type of the configuration item string
The configuration item can contain multiple values False
Is required False
reason_map How a TheHive resolution status becomes an Elastic closing reason, as 'TheHiveStatus:elastic_reason' pairs (for example 'Contained:true_positive'). The full mapping is pre-filled with sensible defaults; edit, add or remove pairs as needed. Anything not listed here falls back to default_close_reason. Elastic's own reasons are false_positive, duplicate, true_positive, benign_positive, automated_closure and other, but any text up to 1024 characters is accepted. If this list is cleared entirely the built-in defaults are used
Default value if not configured ['FalsePositive:false_positive', 'TruePositive:true_positive', 'BenignPositive:benign_positive', 'Duplicated:duplicate', 'Duplicate:duplicate', 'Indeterminate:other', 'Ignored:other', 'Other:other']
Type of the configuration item string
The configuration item can contain multiple values True
Is required False
default_close_reason Closing reason used when a TheHive status has no mapping. Elastic's own values are false_positive, duplicate, true_positive, benign_positive, automated_closure and other, but any text up to 1024 characters is accepted
Default value if not configured other
Type of the configuration item string
The configuration item can contain multiple values False
Is required False