Headers
-
elastic-api-version
string Required The version of the API to use
Value is
2023-10-31
. Default value is2023-10-31
. -
kbn-xsrf
string Required A required header to protect against CSRF attacks
curl \
--request POST 'https://localhost:5601/api/apm/fleet/apm_server_schema' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "elastic-api-version: 2023-10-31" \
--header "kbn-xsrf: true" \
--data '{"schema":{"foo":"bar"}}'
Get source maps
Get an array of Fleet artifacts, including source map uploads. You must have read
or all
Kibana privileges for the APM and User Experience feature.
Headers
-
elastic-api-version
string Required The version of the API to use
Value is
2023-10-31
. Default value is2023-10-31
.
curl -X GET "http://localhost:5601/api/apm/sourcemaps" \
-H 'Content-Type: application/json' \
-H 'kbn-xsrf: true' \
-H 'Authorization: ApiKey ${YOUR_API_KEY}'
{
"artifacts": [
{
"type": "sourcemap",
"identifier": "foo-1.0.0",
"relative_url": "/api/fleet/artifacts/foo-1.0.0/644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
"body": {
"serviceName": "foo",
"serviceVersion": "1.0.0",
"bundleFilepath": "/test/e2e/general-usecase/bundle.js",
"sourceMap": {
"version": 3,
"file": "static/js/main.chunk.js",
"sources": [
"fleet-source-map-client/src/index.css",
"fleet-source-map-client/src/App.js",
"webpack:///./src/index.css?bb0a",
"fleet-source-map-client/src/index.js",
"fleet-source-map-client/src/reportWebVitals.js"
],
"sourcesContent": [
"content"
],
"mappings": "mapping",
"sourceRoot": ""
}
},
"created": "2021-07-09T20:47:44.812Z",
"id": "apm:foo-1.0.0-644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
"compressionAlgorithm": "zlib",
"decodedSha256": "644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
"decodedSize": 441,
"encodedSha256": "024c72749c3e3dd411b103f7040ae62633558608f480bce4b108cf5b2275bd24",
"encodedSize": 237,
"encryptionAlgorithm": "none",
"packageName": "apm"
}
]
}
Update cases
You must have all
privileges for the Cases feature in the Management, Observability, or Security section of the Kibana feature privileges, depending on the owner of the case you're updating.
curl \
--request PATCH 'https://localhost:5601/api/cases' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "kbn-xsrf: string" \
--data '{"cases":[{"id":"a18b38a0-71b0-11ea-a0b2-c51ea50a58e2","tags":["tag-1"],"version":"WzIzLDFd","settings":{"syncAlerts":true},"connector":{"id":"131d4448-abe0-4789-939d-8ef60680b498","name":"My connector","type":".jira","fields":{"parent":null,"priority":null,"issueType":"10006"}},"description":"A case description.","customFields":[{"key":"fcc6840d-eb14-42df-8aaf-232201a705ec","type":"toggle","value":false},{"key":"d312efda-ec2b-42ec-9e2c-84981795c581","type":"text","value":"My new field value"}]}]}'
{
"cases": [
{
"id": "a18b38a0-71b0-11ea-a0b2-c51ea50a58e2",
"tags": [
"tag-1"
],
"version": "WzIzLDFd",
"settings": {
"syncAlerts": true
},
"connector": {
"id": "131d4448-abe0-4789-939d-8ef60680b498",
"name": "My connector",
"type": ".jira",
"fields": {
"parent": null,
"priority": null,
"issueType": "10006"
}
},
"description": "A case description.",
"customFields": [
{
"key": "fcc6840d-eb14-42df-8aaf-232201a705ec",
"type": "toggle",
"value": false
},
{
"key": "d312efda-ec2b-42ec-9e2c-84981795c581",
"type": "text",
"value": "My new field value"
}
]
}
]
}
[
{
"id": "66b9aa00-94fa-11ea-9f74-e7e108796192",
"tags": [
"tag-1"
],
"owner": "cases",
"title": "Case title 1",
"status": "open",
"version": "WzU0OCwxXQ==",
"category": null,
"comments": [],
"duration": null,
"settings": {
"syncAlerts": true
},
"severity": "low",
"assignees": [],
"closed_at": null,
"closed_by": null,
"connector": {
"id": "131d4448-abe0-4789-939d-8ef60680b498",
"name": "My connector",
"type": ".jira",
"fields": {
"parent": null,
"priority": null,
"issueType": "10006"
}
},
"created_at": "2023-10-13T09:16:17.416Z",
"created_by": {
"email": null,
"username": "elastic",
"full_name": null,
"profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
},
"updated_at": "2023-10-13T09:48:33.043Z",
"updated_by": {
"email": null,
"username": "elastic",
"full_name": null,
"profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
},
"description": "A case description.",
"totalAlerts": 0,
"customFields": [
{
"key": "d312efda-ec2b-42ec-9e2c-84981795c581",
"type": "text",
"value": "My new field value"
},
{
"key": "fcc6840d-eb14-42df-8aaf-232201a705ec",
"type": "toggle",
"value": false
}
],
"totalComment": 0,
"external_service": {
"pushed_at": "2023-10-13T09:20:40.672Z",
"pushed_by": {
"email": null,
"username": "elastic",
"full_name": null
},
"external_id": "10003",
"connector_id": "05da469f-1fde-4058-99a3-91e4807e2de8",
"external_url": "https://hms.atlassian.net/browse/IS-4",
"connector_name": "Jira",
"external_title": "IS-4"
}
}
]
Delete all case comments and alerts
Deletes all comments and alerts from a case. You must have all
privileges for the Cases feature in the Management, Observability, or Security section of the Kibana feature privileges, depending on the owner of the cases you're deleting.
Path parameters
-
caseId
string Required The identifier for the case. To retrieve case IDs, use the find cases API. All non-ASCII characters must be URL encoded.
curl \
--request DELETE 'https://localhost:5601/api/cases/9c235210-6834-11ea-a78c-6ffb38a34414/comments' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: string"
Delete a case comment or alert
You must have all
privileges for the Cases feature in the Management, Observability, or Security section of the Kibana feature privileges, depending on the owner of the cases you're deleting.
curl \
--request DELETE 'https://localhost:5601/api/cases/9c235210-6834-11ea-a78c-6ffb38a34414/comments/71ec1870-725b-11ea-a0b2-c51ea50a58e2' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: string"
Get case tags
Aggregates and returns a list of case tags. You must have read privileges for the Cases feature in the Management, Observability, or Security section of the Kibana feature privileges, depending on the owner of the cases you're seeking.
curl \
--request GET 'https://localhost:5601/api/cases/tags' \
--header "Authorization: $API_KEY"
[
"observability",
"security",
"tag 1",
"tag 2"
]
Get a list of dashboards
Technical Preview
This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
curl \
--request GET 'https://localhost:5601/api/dashboards/dashboard' \
--header "Authorization: $API_KEY"
Update an existing dashboard
Technical Preview
This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
Path parameters
-
id
string Required A unique identifier for the dashboard.
Body
-
attributes
object Required Additional properties are NOT allowed.
-
references
array[object]
curl \
--request PUT 'https://localhost:5601/api/dashboards/dashboard/{id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "kbn-xsrf: true" \
--data '{"attributes":{"controlGroupInput":{"autoApplySelections":true,"chainingSystem":"HIERARCHICAL","controls":[{"controlConfig":{},"grow":false,"id":"string","order":42.0,"type":"string","width":"medium"}],"enhancements":{},"ignoreParentSettings":{"ignoreFilters":false,"ignoreQuery":false,"ignoreTimerange":false,"ignoreValidations":false},"labelPosition":"oneLine"},"description":"","kibanaSavedObjectMeta":{"searchSource":{"filter":[{"$state":{"store":"appState"},"meta":{"alias":"string","controlledBy":"string","disabled":true,"field":"string","group":"string","index":"string","isMultiIndex":true,"key":"string","negate":true,"type":"string","value":"string"},"query":{}}],"query":{"language":"string","query":"string"},"sort":[{}],"type":"string"}},"options":{"hidePanelTitles":false,"syncColors":true,"syncCursor":true,"syncTooltips":true,"useMargins":true},"panels":[{"gridData":{"h":15,"i":"string","w":24,"x":42.0,"y":42.0},"id":"string","panelConfig":{"description":"string","enhancements":{},"hidePanelTitles":true,"savedObjectId":"string","title":"string","version":"string"},"panelIndex":"string","panelRefName":"string","title":"string","type":"string","version":"string"}],"refreshInterval":{"display":"string","pause":true,"section":42.0,"value":42.0},"tags":["string"],"timeFrom":"string","timeRestore":false,"timeTo":"string","title":"string","version":42.0},"references":[{"id":"string","name":"string","type":"string"}]}'
Delete a runtime field from a data view
curl \
--request DELETE 'https://localhost:5601/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f/runtime_field/hour_of_day' \
--header "Authorization: $API_KEY"
Create an agent action
[Required authorization] Route required privileges: fleet-agents-all.
Path parameters
-
agentId
string Required
curl \
--request POST 'https://localhost:5601/api/fleet/agents/{agentId}/actions' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "kbn-xsrf: true" \
--data '{"action":{"type":"UNENROLL"}}'
Delete an agent binary download source
Delete an agent binary download source by ID.
[Required authorization] Route required privileges: fleet-settings-all.
Path parameters
-
sourceId
string Required
curl \
--request DELETE 'https://localhost:5601/api/fleet/agent_download_sources/{sourceId}' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: true"
Delete an agent
Delete an agent by ID.
[Required authorization] Route required privileges: fleet-agents-all.
Path parameters
-
agentId
string Required
curl \
--request DELETE 'https://localhost:5601/api/fleet/agents/{agentId}' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: true"
Get agent tags
[Required authorization] Route required privileges: fleet-agents-read.
curl \
--request GET 'https://localhost:5601/api/fleet/agents/tags' \
--header "Authorization: $API_KEY"
Update a custom integration
[Required authorization] Route required privileges: fleet-settings-all AND integrations-all.
Path parameters
-
pkgName
string Required
Body
-
categories
array[string] -
readMeData
string Required
curl \
--request PUT 'https://localhost:5601/api/fleet/epm/custom_integrations/{pkgName}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "kbn-xsrf: true" \
--data '{"categories":["string"],"readMeData":"string"}'
Get an enrollment API key
Get an enrollment API key by ID.
[Required authorization] Route required privileges: fleet-agents-all OR fleet-setup.
Path parameters
-
keyId
string Required
curl \
--request GET 'https://localhost:5601/api/fleet/enrollment_api_keys/{keyId}' \
--header "Authorization: $API_KEY"
Get a Fleet Server host
Get a Fleet Server host by ID.
[Required authorization] Route required privileges: fleet-settings-read.
Path parameters
-
itemId
string Required
curl \
--request GET 'https://localhost:5601/api/fleet/fleet_server_hosts/{itemId}' \
--header "Authorization: $API_KEY"
Delete a Fleet Server host
Delete a Fleet Server host by ID.
[Required authorization] Route required privileges: fleet-settings-all.
Path parameters
-
itemId
string Required
curl \
--request DELETE 'https://localhost:5601/api/fleet/fleet_server_hosts/{itemId}' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: true"
Rotate a Fleet message signing key pair
[Required authorization] Route required privileges: fleet-agents-all AND fleet-agent-policies-all AND fleet-settings-all.
Query parameters
-
acknowledge
boolean Default value is
false
.
curl \
--request POST 'https://localhost:5601/api/fleet/message_signing_service/rotate_key_pair' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: true"
Export saved objects
Retrieve sets of saved objects that you want to import into Kibana. You must include type
or objects
in the request body.
Exported saved objects are not backwards compatible and cannot be imported into an older version of Kibana.
NOTE: The savedObjects.maxImportExportSize
configuration setting limits the number of saved objects which may be exported.
Body
-
excludeExportDetails
boolean Do not add export details entry at the end of the stream.
Default value is
false
. hasReference
object | array[object] -
includeReferencesDeep
boolean Includes all of the referenced objects in the exported objects.
Default value is
false
. -
objects
array[object] A list of objects to export. NOTE: this optiona cannot be combined with
types
optionNot more than
10000
elements. -
search
string Search for documents to export using the Elasticsearch Simple Query String syntax.
type
string | array[string] The saved object types to include in the export. Use
*
to export all the types.
curl \
--request POST 'https://localhost:5601/api/saved_objects/_export' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "kbn-xsrf: true" \
--data '{"objects":[{"id":"de71f4f0-1902-11e9-919b-ffe5949a18d2","type":"map"}],"excludeExportDetails":true,"includeReferencesDeep":false}'
{
"objects": [
{
"id": "de71f4f0-1902-11e9-919b-ffe5949a18d2",
"type": "map"
}
],
"excludeExportDetails": true,
"includeReferencesDeep": false
}
{
"id": "de71f4f0-1902-11e9-919b-ffe5949a18d2",
"type": "map",
"managed": false,
"version": "WzEzLDFd",
"attributes": {
"title": "[Logs] Total Requests and Bytes",
"description": "",
"uiStateJSON": "{\"isDarkMode\":false}",
"mapStateJSON": "{\"zoom\":3.64,\"center\":{\"lon\":-88.92107,\"lat\":42.16337},\"timeFilters\":{\"from\":\"now-7d\",\"to\":\"now\"},\"refreshConfig\":{\"isPaused\":true,\"interval\":0},\"query\":{\"language\":\"kuery\",\"query\":\"\"},\"settings\":{\"autoFitToDataBounds\":false}}",
"layerListJSON": "[{\"id\":\"0hmz5\",\"alpha\":1,\"sourceDescriptor\":{\"type\":\"EMS_TMS\",\"isAutoSelect\":true,\"lightModeDefault\":\"road_map_desaturated\"},\"visible\":true,\"style\":{},\"type\":\"EMS_VECTOR_TILE\",\"minZoom\":0,\"maxZoom\":24},{\"id\":\"edh66\",\"label\":\"Total Requests by Destination\",\"minZoom\":0,\"maxZoom\":24,\"alpha\":0.5,\"sourceDescriptor\":{\"type\":\"EMS_FILE\",\"id\":\"world_countries\",\"tooltipProperties\":[\"name\",\"iso2\"]},\"visible\":true,\"style\":{\"type\":\"VECTOR\",\"properties\":{\"fillColor\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"__kbnjoin__count__673ff994-fc75-4c67-909b-69fcb0e1060e\",\"origin\":\"join\"},\"color\":\"Greys\",\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"lineColor\":{\"type\":\"STATIC\",\"options\":{\"color\":\"#FFFFFF\"}},\"lineWidth\":{\"type\":\"STATIC\",\"options\":{\"size\":1}},\"iconSize\":{\"type\":\"STATIC\",\"options\":{\"size\":10}},\"symbolizeAs\":{\"options\":{\"value\":\"circle\"}},\"icon\":{\"type\":\"STATIC\",\"options\":{\"value\":\"marker\"}}}},\"type\":\"GEOJSON_VECTOR\",\"joins\":[{\"leftField\":\"iso2\",\"right\":{\"type\":\"ES_TERM_SOURCE\",\"id\":\"673ff994-fc75-4c67-909b-69fcb0e1060e\",\"indexPatternTitle\":\"kibana_sample_data_logs\",\"term\":\"geo.dest\",\"indexPatternRefName\":\"layer_1_join_0_index_pattern\",\"metrics\":[{\"type\":\"count\",\"label\":\"web logs count\"}],\"applyGlobalQuery\":true}}]},{\"id\":\"gaxya\",\"label\":\"Actual Requests\",\"minZoom\":9,\"maxZoom\":24,\"alpha\":1,\"sourceDescriptor\":{\"id\":\"b7486535-171b-4d3b-bb2e-33c1a0a2854c\",\"type\":\"ES_SEARCH\",\"geoField\":\"geo.coordinates\",\"limit\":2048,\"filterByMapBounds\":true,\"tooltipProperties\":[\"clientip\",\"timestamp\",\"host\",\"request\",\"response\",\"machine.os\",\"agent\",\"bytes\"],\"indexPatternRefName\":\"layer_2_source_index_pattern\",\"applyGlobalQuery\":true,\"scalingType\":\"LIMIT\"},\"visible\":true,\"style\":{\"type\":\"VECTOR\",\"properties\":{\"fillColor\":{\"type\":\"STATIC\",\"options\":{\"color\":\"#2200ff\"}},\"lineColor\":{\"type\":\"STATIC\",\"options\":{\"color\":\"#FFFFFF\"}},\"lineWidth\":{\"type\":\"STATIC\",\"options\":{\"size\":2}},\"iconSize\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"bytes\",\"origin\":\"source\"},\"minSize\":1,\"maxSize\":23,\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"symbolizeAs\":{\"options\":{\"value\":\"circle\"}},\"icon\":{\"type\":\"STATIC\",\"options\":{\"value\":\"marker\"}}}},\"type\":\"GEOJSON_VECTOR\"},{\"id\":\"tfi3f\",\"label\":\"Total Requests and Bytes\",\"minZoom\":0,\"maxZoom\":9,\"alpha\":1,\"sourceDescriptor\":{\"type\":\"ES_GEO_GRID\",\"resolution\":\"COARSE\",\"id\":\"8aaa65b5-a4e9-448b-9560-c98cb1c5ac5b\",\"geoField\":\"geo.coordinates\",\"requestType\":\"point\",\"metrics\":[{\"type\":\"count\",\"label\":\"web logs count\"},{\"type\":\"sum\",\"field\":\"bytes\"}],\"indexPatternRefName\":\"layer_3_source_index_pattern\",\"applyGlobalQuery\":true},\"visible\":true,\"style\":{\"type\":\"VECTOR\",\"properties\":{\"fillColor\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"doc_count\",\"origin\":\"source\"},\"color\":\"Blues\",\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"lineColor\":{\"type\":\"STATIC\",\"options\":{\"color\":\"#cccccc\"}},\"lineWidth\":{\"type\":\"STATIC\",\"options\":{\"size\":1}},\"iconSize\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"sum_of_bytes\",\"origin\":\"source\"},\"minSize\":7,\"maxSize\":25,\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"labelText\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"doc_count\",\"origin\":\"source\"},\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"labelSize\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"doc_count\",\"origin\":\"source\"},\"minSize\":12,\"maxSize\":24,\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"symbolizeAs\":{\"options\":{\"value\":\"circle\"}},\"icon\":{\"type\":\"STATIC\",\"options\":{\"value\":\"marker\"}}}},\"type\":\"GEOJSON_VECTOR\"}]"
},
"created_at": "2023-08-23T20:03:32.204Z",
"references": [
{
"id": "90943e30-9a47-11e8-b64d-95841ca0b247",
"name": "layer_1_join_0_index_pattern",
"type": "index-pattern"
},
{
"id": "90943e30-9a47-11e8-b64d-95841ca0b247",
"name": "layer_2_source_index_pattern",
"type": "index-pattern"
},
{
"id": "90943e30-9a47-11e8-b64d-95841ca0b247",
"name": "layer_3_source_index_pattern",
"type": "index-pattern"
}
],
"updated_at": "2023-08-23T20:03:32.204Z",
"coreMigrationVersion": "8.8.0",
"typeMigrationVersion": "8.4.0"
}
Delete a conversation
Delete an existing conversation using the conversation ID.
Path parameters
-
id
string(nonempty) Required The conversation's
id
value.Minimum length is
1
.
curl \
--request DELETE 'https://localhost:5601/api/security_ai_assistant/current_user/conversations/{id}' \
--header "Authorization: $API_KEY"
curl \
--request GET 'https://localhost:5601/api/detection_engine/index' \
--header "Authorization: $API_KEY"
{
"name": ".alerts-security.alerts-default",
"index_mapping_outdated": false
}
Retrieve a detection rule
Retrieve a detection rule using the rule_id
or id
field.
The URL query must include one of the following:
id
-GET /api/detection_engine/rules?id=<id>
rule_id
-GET /api/detection_engine/rules?rule_id=<rule_id>
The difference between the id
and rule_id
is that the id
is a unique rule identifier that is randomly generated when a rule is created and cannot be set, whereas rule_id
is a stable rule identifier that can be assigned during rule creation.
Responses
-
200 application/json
Indicates a successful call.
These fields are under development and their usage or schema may change: execution_summary.
Any of: Security_Detections_API_EqlRuleResponseFieldsobject Security_Detections_API_QueryRuleResponseFieldsobject Security_Detections_API_SavedQueryRuleResponseFieldsobject Security_Detections_API_ThresholdRuleResponseFieldsobject Security_Detections_API_ThreatMatchRuleResponseFieldsobject Security_Detections_API_MachineLearningRuleResponseFieldsobject Security_Detections_API_NewTermsRuleResponseFieldsobject Security_Detections_API_EsqlRuleResponseFieldsobject
curl \
--request GET https://localhost:5601/api/detection_engine/rules?rule_id=bfeaf89b-a2a7-48a3-817f-e41829dc61ee \
--header "Content-Type: application/json; Elastic-Api-Version=2023-10-31"
{
"id": "c41d170b-8ba6-4de6-b8ec-76440a35ace3",
"to": "now-300s",
"from": "now-4200s",
"name": "MS Office child process",
"tags": [
"child process",
"ms office"
],
"type": "query",
"query": "process.parent.name:EXCEL.EXE or process.parent.name:MSPUB.EXE or process.parent.name:OUTLOOK.EXE or process.parent.name:POWERPNT.EXE or process.parent.name:VISIO.EXE or process.parent.name:WINWORD.EXE",
"setup": "",
"threat": [
{
"tactic": {
"id": "TA0001",
"name": "Initial Access",
"reference": "https://attack.mitre.org/tactics/TA0001"
},
"framework": "MITRE ATT&CK",
"technique": [
{
"id": "T1193",
"name": "Spearphishing Attachment",
"reference": "https://attack.mitre.org/techniques/T1193"
}
]
}
],
"enabled": false,
"filters": [
{
"query": {
"match": {
"event.action": {
"type": "phrase",
"query": "Process Create (rule: ProcessCreate)"
}
}
}
}
],
"rule_id": "process_started_by_ms_office_user_folder",
"version": 1,
"interval": "1h",
"language": "kuery",
"severity": "low",
"immutable": false,
"created_at": "2020-02-03T11:19:04.259Z",
"created_by": "elastic",
"references": [],
"risk_score": 21,
"updated_at": "2020-02-03T11:19:04.462Z",
"updated_by": "elastic",
"description": "Process started by MS Office program in user folder",
"max_signals": 100,
"false_positives": [],
"required_fields": [
{
"ecs": true,
"name": "process.name",
"type": "keyword"
},
{
"ecs": true,
"name": "process.parent.name",
"type": "keyword"
}
],
"execution_summary": {
"last_execution": {
"date": "2022-03-23T16:06:12.787Z",
"status": "partial failure",
"message": "This rule attempted to query data from Elasticsearch indices listed in the \"Index pattern\" section of the rule definition, but no matching index was found.",
"metrics": {
"execution_gap_duration_s": 0,
"total_search_duration_ms": 135,
"total_indexing_duration_ms": 15
},
"status_order": 20
}
},
"related_integrations": [
{
"package": "o365",
"version": "^2.3.2"
}
]
}
List all detection rules
Retrieve a paginated list of detection rules. By default, the first page is returned, with 20 results per page.
Query parameters
-
fields
array[string] -
filter
string Search query
Filters the returned results according to the value of the specified field, using the alert.attributes.: syntax, where can be:
- name
- enabled
- tags
- createdBy
- interval
- updatedBy
Even though the JSON rule object uses created_by and updated_by fields, you must use createdBy and updatedBy fields in the filter.
-
sort_field
string Field to sort by
Values are
created_at
,createdAt
,enabled
,execution_summary.last_execution.date
,execution_summary.last_execution.metrics.execution_gap_duration_s
,execution_summary.last_execution.metrics.total_indexing_duration_ms
,execution_summary.last_execution.metrics.total_search_duration_ms
,execution_summary.last_execution.status
,name
,risk_score
,riskScore
,severity
,updated_at
, orupdatedAt
. -
sort_order
string Sort order
Values are
asc
ordesc
. -
page
integer Page number
Minimum value is
1
. Default value is1
. -
per_page
integer Rules per page
Minimum value is
0
. Default value is20
. -
gaps_range_start
string Gaps range start
-
gaps_range_end
string Gaps range end
curl -X GET "localhost:5601/api/detection_engine/rules/_find?page=1&per_page=5&sort_field=enabled&sort_order=asc&filter=alert.attributes.name:windows" -H 'kbn-xsrf: true'
{
"data": [
{
"id": "89761517-fdb0-4223-b67b-7621acc48f9e",
"to": "now",
"from": "now-6m",
"name": "Windows Script Executing PowerShell",
"tags": [
"Elastic",
"Windows"
],
"type": "query",
"index": [
"winlogbeat-*"
],
"query": "event.action:\"Process Create (rule: ProcessCreate)\" and process.parent.name:(\"wscript.exe\" or \"cscript.exe\") and process.name:\"powershell.exe\"",
"setup": "",
"threat": [
{
"tactic": {
"id": "TA0002",
"name": "Execution",
"reference": "https://attack.mitre.org/tactics/TA0002/"
},
"framework": "MITRE ATT&CK",
"technique": [
{
"id": "T1193",
"name": "Spearphishing Attachment",
"reference": "https://attack.mitre.org/techniques/T1193/"
}
]
}
],
"enabled": false,
"rule_id": "f545ff26-3c94-4fd0-bd33-3c7f95a3a0fc",
"interval": "5m",
"language": "kuery",
"severity": "low",
"immutable": true,
"created_at": "2020-02-02T10:05:19.613Z",
"created_by": "elastic",
"references": [],
"risk_score": 21,
"updated_at": "2020-02-02T10:05:19.830Z",
"updated_by": "elastic",
"description": "Identifies a PowerShell process launched by either cscript.exe or wscript.exe. Observing Windows scripting processes executing a PowerShell script, may be indicative of malicious activity.",
"max_signals": 33,
"false_positives": [],
"required_fields": [
{
"ecs": true,
"name": "event.action",
"type": "keyword"
},
{
"ecs": true,
"name": "process.name",
"type": "keyword"
},
{
"ecs": true,
"name": "process.parent.name",
"type": "keyword"
}
],
"execution_summary": {
"last_execution": {
"date": "2022-03-23T16:06:12.787Z",
"status": "partial failure",
"message": "This rule attempted to query data from Elasticsearch indices listed in the \"Index pattern\" section of the rule definition, but no matching index was found.",
"metrics": {
"execution_gap_duration_s": 0,
"total_search_duration_ms": 135,
"total_indexing_duration_ms": 15
},
"status_order": 20
}
},
"related_integrations": [
{
"package": "o365",
"version": "^2.3.2"
}
]
}
],
"page": 1,
"total": 4,
"perPage": 5
}
Set a detection alert status
Set the status of one or more detection alerts.
Body
object
Required
An object containing desired status and explicit alert ids or a query to select alerts
-
signal_ids
array[string(nonempty)] Required List of alert
id
s.At least
1
element. Minimum length of each is1
. -
status
string Required The status of an alert, which can be
open
,acknowledged
,in-progress
, orclosed
.Values are
open
,closed
,acknowledged
, orin-progress
.
curl \
--request POST 'https://localhost:5601/api/detection_engine/signals/status' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"status":"closed","signal_ids":["80e1383f856e67c1b7f7a1634744fa6d66b6e2ef7aa26d226e57afb5a7b2b4a1"]}'
{
"status": "closed",
"signal_ids": [
"80e1383f856e67c1b7f7a1634744fa6d66b6e2ef7aa26d226e57afb5a7b2b4a1"
]
}
{
"query": {
"bool": {
"must": [],
"filter": [
{
"range": null,
"@timestamp": {
"gte": "2024-10-23T07:00:00.000Z",
"lte": "2025-01-21T20:12:11.704Z",
"format": "strict_date_optional_time"
}
},
{
"bool": {
"filter": {
"bool": {
"must": [],
"filter": [
{
"match_phrase": {
"kibana.alert.workflow_status": "open"
}
},
{
"range": null,
"@timestamp": {
"gte": "2024-10-23T07:00:00.000Z",
"lte": "2025-01-21T20:12:11.704Z",
"format": "strict_date_optional_time"
}
}
],
"should": [],
"must_not": [
{
"exists": {
"field": "kibana.alert.building_block_type"
}
}
]
}
}
}
}
],
"should": [],
"must_not": []
}
},
"status": "closed",
"conflicts": "proceed"
}
{
"took": 81,
"noops": 0,
"total": 1,
"batches": 1,
"deleted": 0,
"retries": {
"bulk": 0,
"search": 0
},
"updated": 1,
"failures": [],
"timed_out": false,
"throttled_millis": 0,
"version_conflicts": 0,
"requests_per_second": -1,
"throttled_until_millis": 0
}
{
"took": 100,
"noops": 0,
"total": 17,
"batches": 1,
"deleted": 0,
"retries": {
"bulk": 0,
"search": 0
},
"updated": 17,
"failures": [],
"timed_out": false,
"throttled_millis": 0,
"version_conflicts": 0,
"requests_per_second": -1,
"throttled_until_millis": 0
}
Body
Required
-
agent_type
string List of agent types to retrieve. Defaults to
endpoint
.Values are
endpoint
,sentinel_one
,crowdstrike
, ormicrosoft_defender_endpoint
. -
alert_ids
array[string(nonempty)] A list of alerts
id
s.At least
1
element. Minimum length of each is1
. -
case_ids
array[string] Case IDs to be updated (cannot contain empty strings)
At least
1
element. Minimum length of each is1
. -
comment
string Optional comment
-
endpoint_ids
array[string] Required List of endpoint IDs (cannot contain empty strings)
At least
1
element. Minimum length of each is1
. -
parameters
object Required Optional parameters object
curl \
--request POST 'https://localhost:5601/api/endpoint/action/execute' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"comment":"Get list of all files","parameters":{"command":"ls -al","timeout":600},"endpoint_ids":["b3d6de74-36b0-4fa8-be46-c375bf1771bf"]}'
{
"comment": "Get list of all files",
"parameters": {
"command": "ls -al",
"timeout": 600
},
"endpoint_ids": [
"b3d6de74-36b0-4fa8-be46-c375bf1771bf"
]
}
{
"data": {
"id": "9f934028-2300-4927-b531-b26376793dc4",
"hosts": {
"ed518850-681a-4d60-bb98-e22640cae2a8": {
"name": "gke-endpoint-gke-clu-endpoint-node-po-e1a3ab89-4c4r"
}
},
"agents": [
"ed518850-681a-4d60-bb98-e22640cae2a8"
],
"status": "pending",
"command": "execute",
"comment": "Get list of all files",
"outputs": {},
"agentType": "endpoint",
"createdBy": "myuser",
"isExpired": false,
"startedAt": "2023-07-28T18:43:27.362Z",
"agentState": {
"ed518850-681a-4d60-bb98-e22640cae2a8": {
"isCompleted": false,
"wasSuccessful": false
}
},
"parameters": {
"command": "ls -al",
"timeout": 600
},
"isCompleted": false,
"wasSuccessful": false
}
}
Suspend a process
Suspend a running process on an endpoint.
Body
Required
-
agent_type
string List of agent types to retrieve. Defaults to
endpoint
.Values are
endpoint
,sentinel_one
,crowdstrike
, ormicrosoft_defender_endpoint
. -
alert_ids
array[string(nonempty)] A list of alerts
id
s.At least
1
element. Minimum length of each is1
. -
case_ids
array[string] Case IDs to be updated (cannot contain empty strings)
At least
1
element. Minimum length of each is1
. -
comment
string Optional comment
-
endpoint_ids
array[string] Required List of endpoint IDs (cannot contain empty strings)
At least
1
element. Minimum length of each is1
. parameters
object Required -
parameters
object Optional parameters object
curl \
--request POST 'https://localhost:5601/api/endpoint/action/suspend_process' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"comment":"suspend the process","parameters":{"entity_id":"abc123"},"endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"]}'
{
"comment": "suspend the process",
"parameters": {
"entity_id": "abc123"
},
"endpoint_ids": [
"ed518850-681a-4d60-bb98-e22640cae2a8"
]
}
{
"data": {
"id": "233db9ea-6733-4849-9226-5a7039c7161d",
"agents": [
"ed518850-681a-4d60-bb98-e22640cae2a8"
],
"errors": [],
"command": "suspend-process",
"comment": "suspend the process",
"outputs": {
"ed518850-681a-4d60-bb98-e22640cae2a8": {
"type": "json",
"content": {
"key": "value"
}
}
},
"agentType": "endpoint",
"createdBy": "myuser",
"isExpired": false,
"startedAt": "2022-07-29T19:08:49.126Z",
"parameters": {
"entity_id": "abc123"
},
"completedAt": "2022-07-29T19:09:44.961Z",
"isCompleted": true,
"wasSuccessful": true
}
}
Release an isolated endpoint
Release an isolated endpoint, allowing it to rejoin a network.
Body
Required
-
agent_type
string List of agent types to retrieve. Defaults to
endpoint
.Values are
endpoint
,sentinel_one
,crowdstrike
, ormicrosoft_defender_endpoint
. -
alert_ids
array[string(nonempty)] A list of alerts
id
s.At least
1
element. Minimum length of each is1
. -
case_ids
array[string] Case IDs to be updated (cannot contain empty strings)
At least
1
element. Minimum length of each is1
. -
comment
string Optional comment
-
endpoint_ids
array[string] Required List of endpoint IDs (cannot contain empty strings)
At least
1
element. Minimum length of each is1
. -
parameters
object Optional parameters object
curl \
--request POST 'https://localhost:5601/api/endpoint/action/unisolate' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"comment":"Benign process identified, releasing group","endpoint_ids":["9972d10e-4b9e-41aa-a534-a85e2a28ea42","bc0e4f0c-3bca-4633-9fee-156c0b505d16","fa89271b-b9d4-43f2-a684-307cffddeb5a"]}'
{
"comment": "Benign process identified, releasing group",
"endpoint_ids": [
"9972d10e-4b9e-41aa-a534-a85e2a28ea42",
"bc0e4f0c-3bca-4633-9fee-156c0b505d16",
"fa89271b-b9d4-43f2-a684-307cffddeb5a"
]
}
{
"endpoint_ids": [
"ed518850-681a-4d60-bb98-e22640cae2a8"
]
}
{
"comment": "Remediation complete, restoring network",
"case_ids": [
"4976be38-c134-4554-bd5e-0fd89ce63667"
],
"endpoint_ids": [
"1aa1f8fd-0fb0-4fe4-8c30-92068272d3f0",
"b30a11bf-1395-4707-b508-fbb45ef9793e"
]
}
{
"data": {
"id": "233db9ea-6733-4849-9226-5a7039c7161d",
"agents": [
"ed518850-681a-4d60-bb98-e22640cae2a8"
],
"errors": [],
"command": "suspend-process",
"comment": "suspend the process",
"outputs": {
"ed518850-681a-4d60-bb98-e22640cae2a8": {
"type": "json",
"content": {
"key": "value"
}
}
},
"agentType": "endpoint",
"createdBy": "myuser",
"isExpired": false,
"startedAt": "2022-07-29T19:08:49.126Z",
"parameters": {
"entity_id": "abc123"
},
"completedAt": "2022-07-29T19:09:44.961Z",
"isCompleted": true,
"wasSuccessful": true
},
"action": "233db9ea-6733-4849-9226-5a7039c7161d"
}
Apply DataView indices to all installed engines
curl \
--request POST 'https://localhost:5601/api/entity_store/engines/apply_dataview_indices' \
--header "Authorization: $API_KEY"
Create rule exception items
Create exception items that apply to a single detection rule.
Path parameters
-
id
string(uuid) Required Detection rule's identifier
curl \
--request POST 'https://localhost:5601/api/detection_engine/rules/330bdd28-eedf-40e1-bed0-f10176c7f9e0/exceptions' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"items":[{"name":"Sample Exception List Item","tags":["malware"],"type":"simple","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["saturn","jupiter"],"operator":"included"}],"item_id":"simple_list_item","list_id":"simple_list","os_types":["linux"],"description":"This is a sample detection type exception item.","namespace_type":"single"}]}'
{
"items": [
{
"name": "Sample Exception List Item",
"tags": [
"malware"
],
"type": "simple",
"entries": [
{
"type": "exists",
"field": "actingProcess.file.signer",
"operator": "excluded"
},
{
"type": "match_any",
"field": "host.name",
"value": [
"saturn",
"jupiter"
],
"operator": "included"
}
],
"item_id": "simple_list_item",
"list_id": "simple_list",
"os_types": [
"linux"
],
"description": "This is a sample detection type exception item.",
"namespace_type": "single"
}
]
}
[
{
"id": "71a9f4b2-c85c-49b4-866f-c71eb9e67da2",
"name": "Sample Exception List Item",
"tags": [
"malware"
],
"type": "simple",
"entries": [
{
"type": "exists",
"field": "actingProcess.file.signer",
"operator": "excluded"
},
{
"type": "match_any",
"field": "host.name",
"value": [
"saturn",
"jupiter"
],
"operator": "included"
}
],
"item_id": "simple_list_item",
"list_id": "simple_list",
"_version": "WzQsMV0=",
"comments": [],
"os_types": [
"linux"
],
"created_at": "2025-01-07T20:07:33.119Z",
"created_by": "elastic",
"updated_at": "2025-01-07T20:07:33.119Z",
"updated_by": "elastic",
"description": "This is a sample detection type exception item.",
"namespace_type": "single",
"tie_breaker_id": "09434836-9db9-4942-a234-5a9268e0b34c"
}
]
{
"error": "Bad Request",
"message": "Invalid request payload JSON format",
"statusCode": 400
}
{
"error": "Bad Request",
"message": "[request params]: id: Invalid uuid",
"statusCode": 400
}
{
"error": "Unauthorized",
"message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
"statusCode": 401
}
{
"message": "Unable to create exception-list",
"status_code": 403
}
{
"message": "Internal Server Error",
"status_code": 500
}
Create an exception list
An exception list groups exception items and can be associated with detection rules. You can assign exception lists to multiple detection rules.
All exception items added to the same list are evaluated using OR
logic. That is, if any of the items in a list evaluate to true
, the exception prevents the rule from generating an alert. Likewise, OR
logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the AND
operator, you can define multiple clauses (entries
) in a single exception item.
Body
Required
Exception list's properties
-
description
string Required Describes the exception list.
-
list_id
string(nonempty) Exception list's human readable string identifier, e.g.
trusted-linux-processes
.Minimum length is
1
. -
meta
object Placeholder for metadata about the list container.
Additional properties are allowed.
-
name
string Required The name of the exception list.
-
namespace_type
string Determines whether the exception container is available in all Kibana spaces or just the space in which it is created, where:
single
: Only available in the Kibana space in which it is created.agnostic
: Available in all Kibana spaces.
Values are
agnostic
orsingle
. Default value issingle
. -
os_types
array[string] Use this field to specify the operating system. Only enter one value.
Values are
linux
,macos
, orwindows
. -
type
string Required The type of exception list to be created. Different list types may denote where they can be utilized.
Values are
detection
,rule_default
,endpoint
,endpoint_trusted_apps
,endpoint_events
,endpoint_host_isolation_exceptions
, orendpoint_blocklists
. -
version
integer The document version, automatically increasd on updates.
Minimum value is
1
.
Responses
-
200 application/json
Successful response
-
400 application/json
Invalid input data response
-
401 application/json
Unsuccessful authentication response
-
403 application/json
Not enough privileges response
-
409 application/json
Exception list already exists response
-
500 application/json
Internal server error response
curl \
--request POST 'https://localhost:5601/api/exception_lists' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"Sample Detection Exception List","tags":["malware"],"type":"detection","list_id":"simple_list","os_types":["linux"],"description":"This is a sample detection type exception list.","namespace_type":"single"}'
{
"name": "Sample Detection Exception List",
"tags": [
"malware"
],
"type": "detection",
"list_id": "simple_list",
"os_types": [
"linux"
],
"description": "This is a sample detection type exception list.",
"namespace_type": "single"
}
{
"id": "28243c2f-624a-4443-823d-c0b894880931",
"name": "Sample Detection Exception List",
"tags": [
"malware"
],
"type": "detection",
"list_id": "8c1aae4c-1ef5-4bce-a2e3-16584b501783",
"version": 1,
"_version": "WzMsMV0=",
"os_types": [],
"immutable": false,
"created_at": "2025-01-09T01:05:23.019Z",
"created_by": "elastic",
"updated_at": "2025-01-09T01:05:23.020Z",
"updated_by": "elastic",
"description": "This is a sample detection type exception with an autogenerated list_id.",
"namespace_type": "single",
"tie_breaker_id": "ad94de31-39f7-4ad7-b8e4-988bfa95f338"
}
{
"id": "1a744e77-22ca-4b6b-9085-54f55275ebe5",
"name": "Sample Agnostic Endpoint Exception List",
"tags": [
"malware"
],
"type": "endpoint",
"list_id": "b935eb55-7b21-4c1c-b235-faa1df23b3d6",
"version": 1,
"_version": "WzUsMV0=",
"os_types": [
"linux"
],
"immutable": false,
"created_at": "2025-01-09T01:10:36.369Z",
"created_by": "elastic",
"updated_at": "2025-01-09T01:10:36.369Z",
"updated_by": "elastic",
"description": "This is a sample agnostic endpoint type exception.",
"namespace_type": "agnostic",
"tie_breaker_id": "49ea0adc-a2b8-4d83-a8f3-2fb98301dea3"
}
{
"id": "9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85",
"name": "Sample Detection Exception List",
"tags": [
"malware"
],
"type": "detection",
"list_id": "simple_list",
"version": 1,
"_version": "WzIsMV0=",
"os_types": [
"linux"
],
"immutable": false,
"created_at": "2025-01-07T19:34:27.942Z",
"created_by": "elastic",
"updated_at": "2025-01-07T19:34:27.942Z",
"updated_by": "elastic",
"description": "This is a sample detection type exception list.",
"namespace_type": "single",
"tie_breaker_id": "78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3"
}
{
"id": "a79f4730-6e32-4278-abfc-349c0add7d54",
"name": "Sample Endpoint Exception List",
"tags": [
"malware"
],
"type": "endpoint",
"list_id": "endpoint_list",
"version": 1,
"_version": "WzQsMV0=",
"os_types": [
"linux"
],
"immutable": false,
"created_at": "2025-01-09T01:07:49.658Z",
"created_by": "elastic",
"updated_at": "2025-01-09T01:07:49.658Z",
"updated_by": "elastic",
"description": "This is a sample endpoint type exception list.",
"namespace_type": "single",
"tie_breaker_id": "94a028af-8f47-427a-aca5-ffaf829e64ee"
}
{
"error": "Bad Request",
"message": "[request body]: list_id: Expected string, received number",
"statusCode": 400
}
{
"error": "Unauthorized",
"message": "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
"statusCode": 401
}
{
"error": "Forbidden",
"message": "API [POST /api/exception_lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
"statusCode": 403
}
{
"message": "exception list id: \"simple_list\" already exists",
"status_code": 409
}
{
"message": "Internal Server Error",
"status_code": 500
}
Query parameters
-
filter
string Filters the returned results according to the value of the specified field.
Uses the
so type.field name:field
value syntax, whereso type
can be:exception-list
: Specify a space-aware exception list.exception-list-agnostic
: Specify an exception list that is shared across spaces.
-
namespace_type
array[string] Determines whether the returned containers are Kibana associated with a Kibana space or available in all spaces (
agnostic
orsingle
)Values are
agnostic
orsingle
. Default value is["single"]
. -
page
integer The page number to return
Minimum value is
1
. -
per_page
integer The number of exception lists to return per page
Minimum value is
1
. -
sort_field
string Determines which field is used to sort the results.
-
sort_order
string Determines the sort order, which can be
desc
orasc
.Values are
desc
orasc
.
curl \
--request GET 'https://localhost:5601/api/exception_lists/_find' \
--header "Authorization: $API_KEY"
{
"data": [
{
"id": "9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85",
"name": "Detection Exception List",
"tags": [
"malware"
],
"type": "detection",
"list_id": "simple_list",
"version": 1,
"_version": "WzIsMV0=",
"os_types": [],
"immutable": false,
"created_at": "2025-01-07T19:34:27.942Z",
"created_by": "elastic",
"updated_at": "2025-01-07T19:34:27.942Z",
"updated_by": "elastic",
"description": "This is a sample detection type exception list.",
"namespace_type": "single",
"tie_breaker_id": "78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3"
}
],
"page": 1,
"total": 1,
"per_page": 20
}
{
"error": "Bad Request",
"message": "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'",
"statusCode": 400
}
{
"error": "Unauthorized",
"message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
"statusCode": 401
}
{
"error": "Forbidden",
"message": "API [GET /api/exception_lists/_find?namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]",
"statusCode": 403
}
{
"message": "Internal Server Error",
"status_code": 500
}
Security lists
Lists can be used with detection rule exceptions to define values that prevent a rule from generating alerts.
Lists are made up of:
- List containers: A container for values of the same Elasticsearch data type. The following data types can be used:
boolean
byte
date
date_nanos
date_range
double
double_range
float
float_range
half_float
integer
integer_range
ip
ip_range
keyword
long
long_range
short
text
- List items: The values used to determine whether the exception prevents an alert from being generated.
All list items in the same list container must be of the same data type, and each item defines a single value. For example, an IP list container named internal-ip-addresses-southport
contains five items, where each item defines one internal IP address:
192.168.1.1
192.168.1.3
192.168.1.18
192.168.1.12
192.168.1.7
To use these IP addresses as values for defining rule exceptions, use the Security exceptions API to create an exception list item that references the internal-ip-addresses-southport
list.
Lists cannot be added directly to rules, nor do they define the operators used to determine when exceptions are applied (is in list
, is not in list
). Use an exception item to define the operator and associate it with an exception container. You can then add the exception container to a rule's exceptions_list
object.
Lists requirements
Before you can start using lists, you must create the .lists
and .items
data streams for the relevant Kibana space. To do this, use the Create list data streams endpoint. Once these data streams are created, your role needs privileges to manage rules. Refer to Enable and access detections for a complete list of requirements.