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
- If
custom_field_name_alert_id is set, the responder reads that custom field. Required when running on a case.
- 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 |