mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 17:28:26 -04:00
# Backport This will backport the following commits from `main` to `8.18`: - [[Security Solution] Migrate legacy Detections API docs to OpenAPI specs (#212367)](https://github.com/elastic/kibana/pull/212367) <!--- Backport version: 9.6.6 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport) <!--BACKPORT [{"author":{"name":"Jacek Kolezynski","email":"jacek.kolezynski@elastic.co"},"sourceCommit":{"committedDate":"2025-04-01T13:43:02Z","message":"[Security Solution] Migrate legacy Detections API docs to OpenAPI specs (#212367)\n\n**Partially resolves: #211808**\n\n## Summary\n\nThis is the first part of the migration effort, containing changes for:\n- CRUD endpoints\n- BULK Actions\n- Export / Import Rule\n- Find Rule\n- List Tags\n- Get Status\n- Install Rule\n\nI migrated the examples and the description of the fields. Some of the\nfields contained description that was very similar to the legacy, then I\ndidn't change it. I only modified the descriptions where it was\nvaluable.\n\nI also discovered some problems. For example the value for the 'query'\nfield, always shows 'EQL query to execute'. I reported this to the docs\nteam, in the 'next-api-reference' channel.\n\nAnother issue was with 'related_integrations field', which also didn't\nshow the long description. I also wrote about it to the docs team\n[here](https://elastic.slack.com/archives/C05UL5YC06B/p1740137094701209).\nIn this PR I decided to try moving the description one level up, where\nit renders properly.\n\n\n# Testing\n1. cd x-pack/solutions/security/plugins/security_solution\n2. yarn openapi:bundle:detections \n3. Take the bundled file\n(docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml)\nand load it into bump.sh console to see the changes.\n4. Compare the changes with the [Legacy\ndocumentation](https://www.elastic.co/guide/en/security/current/rule-api-overview.html)\n\nYou can also use this [link](https://bump.sh/jkelas/doc/kibana_wip/)\nwhere I deployed the generated bundled doc.\n\n---------\n\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"2b01257343335ad7ea5d40577c7e10deb94db19b","branchLabelMapping":{"^v9.1.0$":"main","^v8.19.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","Team:Detections and Resp","Team: SecuritySolution","APIDocs","Team:Detection Rule Management","backport:version","8.18 candidate","v9.1.0","v8.19.0"],"title":"[Security Solution] Migrate legacy Detections API docs to OpenAPI specs","number":212367,"url":"https://github.com/elastic/kibana/pull/212367","mergeCommit":{"message":"[Security Solution] Migrate legacy Detections API docs to OpenAPI specs (#212367)\n\n**Partially resolves: #211808**\n\n## Summary\n\nThis is the first part of the migration effort, containing changes for:\n- CRUD endpoints\n- BULK Actions\n- Export / Import Rule\n- Find Rule\n- List Tags\n- Get Status\n- Install Rule\n\nI migrated the examples and the description of the fields. Some of the\nfields contained description that was very similar to the legacy, then I\ndidn't change it. I only modified the descriptions where it was\nvaluable.\n\nI also discovered some problems. For example the value for the 'query'\nfield, always shows 'EQL query to execute'. I reported this to the docs\nteam, in the 'next-api-reference' channel.\n\nAnother issue was with 'related_integrations field', which also didn't\nshow the long description. I also wrote about it to the docs team\n[here](https://elastic.slack.com/archives/C05UL5YC06B/p1740137094701209).\nIn this PR I decided to try moving the description one level up, where\nit renders properly.\n\n\n# Testing\n1. cd x-pack/solutions/security/plugins/security_solution\n2. yarn openapi:bundle:detections \n3. Take the bundled file\n(docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml)\nand load it into bump.sh console to see the changes.\n4. Compare the changes with the [Legacy\ndocumentation](https://www.elastic.co/guide/en/security/current/rule-api-overview.html)\n\nYou can also use this [link](https://bump.sh/jkelas/doc/kibana_wip/)\nwhere I deployed the generated bundled doc.\n\n---------\n\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"2b01257343335ad7ea5d40577c7e10deb94db19b"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v9.1.0","branchLabelMappingKey":"^v9.1.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/212367","number":212367,"mergeCommit":{"message":"[Security Solution] Migrate legacy Detections API docs to OpenAPI specs (#212367)\n\n**Partially resolves: #211808**\n\n## Summary\n\nThis is the first part of the migration effort, containing changes for:\n- CRUD endpoints\n- BULK Actions\n- Export / Import Rule\n- Find Rule\n- List Tags\n- Get Status\n- Install Rule\n\nI migrated the examples and the description of the fields. Some of the\nfields contained description that was very similar to the legacy, then I\ndidn't change it. I only modified the descriptions where it was\nvaluable.\n\nI also discovered some problems. For example the value for the 'query'\nfield, always shows 'EQL query to execute'. I reported this to the docs\nteam, in the 'next-api-reference' channel.\n\nAnother issue was with 'related_integrations field', which also didn't\nshow the long description. I also wrote about it to the docs team\n[here](https://elastic.slack.com/archives/C05UL5YC06B/p1740137094701209).\nIn this PR I decided to try moving the description one level up, where\nit renders properly.\n\n\n# Testing\n1. cd x-pack/solutions/security/plugins/security_solution\n2. yarn openapi:bundle:detections \n3. Take the bundled file\n(docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml)\nand load it into bump.sh console to see the changes.\n4. Compare the changes with the [Legacy\ndocumentation](https://www.elastic.co/guide/en/security/current/rule-api-overview.html)\n\nYou can also use this [link](https://bump.sh/jkelas/doc/kibana_wip/)\nwhere I deployed the generated bundled doc.\n\n---------\n\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"2b01257343335ad7ea5d40577c7e10deb94db19b"}},{"branch":"8.x","label":"v8.19.0","branchLabelMappingKey":"^v8.19.0$","isSourceBranch":false,"url":"https://github.com/elastic/kibana/pull/216734","number":216734,"state":"MERGED","mergeCommit":{"sha":"9c8b23ad7b5cf5025506e1d51fa22d7de7194305","message":"[8.x] [Security Solution] Migrate legacy Detections API docs to OpenAPI specs (#212367) (#216734)\n\n# Backport\n\nThis will backport the following commits from `main` to `8.x`:\n- [[Security Solution] Migrate legacy Detections API docs to OpenAPI\nspecs (#212367)](https://github.com/elastic/kibana/pull/212367)\n\n\n\n### Questions ?\nPlease refer to the [Backport tool\ndocumentation](https://github.com/sorenlouv/backport)\n\n\n\nCo-authored-by: Jacek Kolezynski <jacek.kolezynski@elastic.co>"}}]}] BACKPORT--> --------- Co-authored-by: Jacek Kolezynski <jacek.kolezynski@elastic.co> Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
This commit is contained in:
Georgii Gorbachev
GitHub
parent
331691bd1c
commit
0e90f2d2f2
42 changed files with 9797 additions and 561 deletions
File diff suppressed because it is too large
Load diff
|
|
@ -5707,10 +5707,12 @@ Object {
|
|||
"additionalProperties": false,
|
||||
"properties": Object {
|
||||
"id": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"list_id": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"namespace_type": Object {
|
||||
"enum": Array [
|
||||
|
|
@ -5785,6 +5787,7 @@ Object {
|
|||
"type": "string",
|
||||
},
|
||||
"maxSignals": Object {
|
||||
"default": 100,
|
||||
"minimum": 1,
|
||||
"type": "integer",
|
||||
},
|
||||
|
|
@ -5838,10 +5841,12 @@ Object {
|
|||
"type": "boolean",
|
||||
},
|
||||
"name": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"type": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
},
|
||||
"required": Array [
|
||||
|
|
@ -6244,7 +6249,6 @@ Object {
|
|||
"ruleId",
|
||||
"immutable",
|
||||
"outputIndex",
|
||||
"maxSignals",
|
||||
"riskScore",
|
||||
"riskScoreMapping",
|
||||
"severity",
|
||||
|
|
@ -6374,10 +6378,12 @@ Object {
|
|||
"additionalProperties": false,
|
||||
"properties": Object {
|
||||
"id": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"list_id": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"namespace_type": Object {
|
||||
"enum": Array [
|
||||
|
|
@ -6452,6 +6458,7 @@ Object {
|
|||
"type": "string",
|
||||
},
|
||||
"maxSignals": Object {
|
||||
"default": 100,
|
||||
"minimum": 1,
|
||||
"type": "integer",
|
||||
},
|
||||
|
|
@ -6505,10 +6512,12 @@ Object {
|
|||
"type": "boolean",
|
||||
},
|
||||
"name": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"type": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
},
|
||||
"required": Array [
|
||||
|
|
@ -6911,7 +6920,6 @@ Object {
|
|||
"ruleId",
|
||||
"immutable",
|
||||
"outputIndex",
|
||||
"maxSignals",
|
||||
"riskScore",
|
||||
"riskScoreMapping",
|
||||
"severity",
|
||||
|
|
@ -7104,10 +7112,12 @@ Object {
|
|||
"additionalProperties": false,
|
||||
"properties": Object {
|
||||
"id": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"list_id": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"namespace_type": Object {
|
||||
"enum": Array [
|
||||
|
|
@ -7182,6 +7192,7 @@ Object {
|
|||
"type": "string",
|
||||
},
|
||||
"maxSignals": Object {
|
||||
"default": 100,
|
||||
"minimum": 1,
|
||||
"type": "integer",
|
||||
},
|
||||
|
|
@ -7235,10 +7246,12 @@ Object {
|
|||
"type": "boolean",
|
||||
},
|
||||
"name": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"type": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
},
|
||||
"required": Array [
|
||||
|
|
@ -7641,7 +7654,6 @@ Object {
|
|||
"ruleId",
|
||||
"immutable",
|
||||
"outputIndex",
|
||||
"maxSignals",
|
||||
"riskScore",
|
||||
"riskScoreMapping",
|
||||
"severity",
|
||||
|
|
@ -7752,10 +7764,12 @@ Object {
|
|||
"additionalProperties": false,
|
||||
"properties": Object {
|
||||
"id": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"list_id": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"namespace_type": Object {
|
||||
"enum": Array [
|
||||
|
|
@ -7830,6 +7844,7 @@ Object {
|
|||
"type": "string",
|
||||
},
|
||||
"maxSignals": Object {
|
||||
"default": 100,
|
||||
"minimum": 1,
|
||||
"type": "integer",
|
||||
},
|
||||
|
|
@ -7883,10 +7898,12 @@ Object {
|
|||
"type": "boolean",
|
||||
},
|
||||
"name": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"type": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
},
|
||||
"required": Array [
|
||||
|
|
@ -8289,7 +8306,6 @@ Object {
|
|||
"ruleId",
|
||||
"immutable",
|
||||
"outputIndex",
|
||||
"maxSignals",
|
||||
"riskScore",
|
||||
"riskScoreMapping",
|
||||
"severity",
|
||||
|
|
@ -8358,7 +8374,8 @@ Object {
|
|||
"type": "array",
|
||||
},
|
||||
"historyWindowStart": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"index": Object {
|
||||
"items": Object {
|
||||
|
|
@ -8455,10 +8472,12 @@ Object {
|
|||
"additionalProperties": false,
|
||||
"properties": Object {
|
||||
"id": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"list_id": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"namespace_type": Object {
|
||||
"enum": Array [
|
||||
|
|
@ -8533,6 +8552,7 @@ Object {
|
|||
"type": "string",
|
||||
},
|
||||
"maxSignals": Object {
|
||||
"default": 100,
|
||||
"minimum": 1,
|
||||
"type": "integer",
|
||||
},
|
||||
|
|
@ -8586,10 +8606,12 @@ Object {
|
|||
"type": "boolean",
|
||||
},
|
||||
"name": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"type": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
},
|
||||
"required": Array [
|
||||
|
|
@ -8992,7 +9014,6 @@ Object {
|
|||
"ruleId",
|
||||
"immutable",
|
||||
"outputIndex",
|
||||
"maxSignals",
|
||||
"riskScore",
|
||||
"riskScoreMapping",
|
||||
"severity",
|
||||
|
|
@ -9160,10 +9181,12 @@ Object {
|
|||
"additionalProperties": false,
|
||||
"properties": Object {
|
||||
"id": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"list_id": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"namespace_type": Object {
|
||||
"enum": Array [
|
||||
|
|
@ -9238,6 +9261,7 @@ Object {
|
|||
"type": "string",
|
||||
},
|
||||
"maxSignals": Object {
|
||||
"default": 100,
|
||||
"minimum": 1,
|
||||
"type": "integer",
|
||||
},
|
||||
|
|
@ -9291,10 +9315,12 @@ Object {
|
|||
"type": "boolean",
|
||||
},
|
||||
"name": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"type": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
},
|
||||
"required": Array [
|
||||
|
|
@ -9697,7 +9723,6 @@ Object {
|
|||
"ruleId",
|
||||
"immutable",
|
||||
"outputIndex",
|
||||
"maxSignals",
|
||||
"riskScore",
|
||||
"riskScoreMapping",
|
||||
"severity",
|
||||
|
|
@ -9865,10 +9890,12 @@ Object {
|
|||
"additionalProperties": false,
|
||||
"properties": Object {
|
||||
"id": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"list_id": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"namespace_type": Object {
|
||||
"enum": Array [
|
||||
|
|
@ -9943,6 +9970,7 @@ Object {
|
|||
"type": "string",
|
||||
},
|
||||
"maxSignals": Object {
|
||||
"default": 100,
|
||||
"minimum": 1,
|
||||
"type": "integer",
|
||||
},
|
||||
|
|
@ -9996,10 +10024,12 @@ Object {
|
|||
"type": "boolean",
|
||||
},
|
||||
"name": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
"type": Object {
|
||||
"$ref": "#/allOf/0/properties/investigationFields/anyOf/0/properties/field_names/items",
|
||||
"minLength": 1,
|
||||
"type": "string",
|
||||
},
|
||||
},
|
||||
"required": Array [
|
||||
|
|
@ -10402,7 +10432,6 @@ Object {
|
|||
"ruleId",
|
||||
"immutable",
|
||||
"outputIndex",
|
||||
"maxSignals",
|
||||
"riskScore",
|
||||
"riskScoreMapping",
|
||||
"severity",
|
||||
|
|
|
|||
|
|
@ -21,6 +21,9 @@ export const ResponseActionTypes = z.enum(['.osquery', '.endpoint']);
|
|||
export type ResponseActionTypesEnum = typeof ResponseActionTypes.enum;
|
||||
export const ResponseActionTypesEnum = ResponseActionTypes.enum;
|
||||
|
||||
/**
|
||||
* Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}
|
||||
*/
|
||||
export type EcsMapping = z.infer<typeof EcsMapping>;
|
||||
export const EcsMapping = z.object({}).catchall(
|
||||
z.object({
|
||||
|
|
@ -51,11 +54,23 @@ export const OsqueryQuery = z.object({
|
|||
|
||||
export type OsqueryParams = z.infer<typeof OsqueryParams>;
|
||||
export const OsqueryParams = z.object({
|
||||
/**
|
||||
* To run a single query, use the query field and enter a SQL query. Example: "query": "SELECT * FROM processes;"
|
||||
*/
|
||||
query: z.string().optional(),
|
||||
ecs_mapping: EcsMapping.optional(),
|
||||
queries: z.array(OsqueryQuery).optional(),
|
||||
/**
|
||||
* To specify a query pack, use the packId field. Example: "packId": "processes_elastic"
|
||||
*/
|
||||
pack_id: z.string().optional(),
|
||||
/**
|
||||
* To run a saved query, use the saved_query_id field and specify the saved query ID. Example: "saved_query_id": "processes_elastic"
|
||||
*/
|
||||
saved_query_id: z.string().optional(),
|
||||
/**
|
||||
* A timeout period, in seconds, after which the query will stop running. Overwriting the default timeout allows you to support queries that require more time to complete. The default and minimum supported value is 60. The maximum supported value is 900. Example: "timeout": 120.
|
||||
*/
|
||||
timeout: z.number().optional(),
|
||||
});
|
||||
|
||||
|
|
@ -89,7 +104,13 @@ export const DefaultParams = z.object({
|
|||
|
||||
export type ProcessesParams = z.infer<typeof ProcessesParams>;
|
||||
export const ProcessesParams = z.object({
|
||||
/**
|
||||
* To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"
|
||||
*/
|
||||
command: z.enum(['kill-process', 'suspend-process']),
|
||||
/**
|
||||
* Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"
|
||||
*/
|
||||
comment: z.string().optional(),
|
||||
config: z.object({
|
||||
/**
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@ openapi: 3.0.0
|
|||
info:
|
||||
title: Response Actions Schema
|
||||
version: 'not applicable'
|
||||
paths: { }
|
||||
paths: {}
|
||||
components:
|
||||
x-codegen-enabled: true
|
||||
schemas:
|
||||
|
|
@ -14,6 +14,7 @@ components:
|
|||
|
||||
EcsMapping:
|
||||
type: object
|
||||
description: 'Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}'
|
||||
additionalProperties:
|
||||
type: object
|
||||
properties:
|
||||
|
|
@ -55,6 +56,7 @@ components:
|
|||
properties:
|
||||
query:
|
||||
type: string
|
||||
description: 'To run a single query, use the query field and enter a SQL query. Example: "query": "SELECT * FROM processes;"'
|
||||
ecs_mapping:
|
||||
$ref: '#/components/schemas/EcsMapping'
|
||||
queries:
|
||||
|
|
@ -63,10 +65,13 @@ components:
|
|||
$ref: '#/components/schemas/OsqueryQuery'
|
||||
pack_id:
|
||||
type: string
|
||||
description: 'To specify a query pack, use the packId field. Example: "packId": "processes_elastic"'
|
||||
saved_query_id:
|
||||
type: string
|
||||
description: 'To run a saved query, use the saved_query_id field and specify the saved query ID. Example: "saved_query_id": "processes_elastic"'
|
||||
timeout:
|
||||
type: number
|
||||
description: 'A timeout period, in seconds, after which the query will stop running. Overwriting the default timeout allows you to support queries that require more time to complete. The default and minimum supported value is 60. The maximum supported value is 900. Example: "timeout": 120.'
|
||||
|
||||
OsqueryParamsCamelCase:
|
||||
type: object
|
||||
|
|
@ -133,8 +138,10 @@ components:
|
|||
enum:
|
||||
- kill-process
|
||||
- suspend-process
|
||||
description: 'To run an endpoint response action, specify a value for the command field. Example: "command": "isolate"'
|
||||
comment:
|
||||
type: string
|
||||
description: 'Add a note that explains or describes the action. You can find your comment in the response actions history log. Example: "comment": "Check processes"'
|
||||
config:
|
||||
required:
|
||||
- field
|
||||
|
|
|
|||
|
|
@ -15,22 +15,31 @@
|
|||
*/
|
||||
|
||||
import { z } from '@kbn/zod';
|
||||
import { isValidDateMath } from '@kbn/zod-helpers';
|
||||
import { isValidDateMath, isNonEmptyString } from '@kbn/zod-helpers';
|
||||
|
||||
import { UUID, NonEmptyString } from '../../../model/primitives.gen';
|
||||
|
||||
/**
|
||||
* A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object `id`s.
|
||||
*/
|
||||
export type RuleObjectId = z.infer<typeof RuleObjectId>;
|
||||
export const RuleObjectId = UUID;
|
||||
|
||||
/**
|
||||
* Could be any string, not necessarily a UUID
|
||||
* A stable unique identifier for the rule object. It can be assigned during rule creation. It can be any string, but often is a UUID. It should be unique not only within a given Kibana space, but also across spaces and Elastic environments. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have the same `rule_id`s.
|
||||
*/
|
||||
export type RuleSignatureId = z.infer<typeof RuleSignatureId>;
|
||||
export const RuleSignatureId = z.string();
|
||||
|
||||
/**
|
||||
* A human-readable name for the rule.
|
||||
*/
|
||||
export type RuleName = z.infer<typeof RuleName>;
|
||||
export const RuleName = z.string().min(1);
|
||||
|
||||
/**
|
||||
* The rule’s description.
|
||||
*/
|
||||
export type RuleDescription = z.infer<typeof RuleDescription>;
|
||||
export const RuleDescription = z.string().min(1);
|
||||
|
||||
|
|
@ -87,7 +96,7 @@ export type RuleSource = z.infer<typeof RuleSource>;
|
|||
export const RuleSource = z.discriminatedUnion('type', [ExternalRuleSource, InternalRuleSource]);
|
||||
|
||||
/**
|
||||
* Determines whether the rule is enabled.
|
||||
* Determines whether the rule is enabled. Defaults to true.
|
||||
*/
|
||||
export type IsRuleEnabled = z.infer<typeof IsRuleEnabled>;
|
||||
export const IsRuleEnabled = z.boolean();
|
||||
|
|
@ -108,8 +117,13 @@ export type RuleIntervalTo = z.infer<typeof RuleIntervalTo>;
|
|||
export const RuleIntervalTo = z.string();
|
||||
|
||||
/**
|
||||
* Risk score (0 to 100)
|
||||
*/
|
||||
* A numerical representation of the alert's severity from 0 to 100, where:
|
||||
* `0` - `21` represents low severity
|
||||
* `22` - `47` represents medium severity
|
||||
* `48` - `73` represents high severity
|
||||
* `74` - `100` represents critical severity
|
||||
|
||||
*/
|
||||
export type RiskScore = z.infer<typeof RiskScore>;
|
||||
export const RiskScore = z.number().int().min(0).max(100);
|
||||
|
||||
|
|
@ -119,6 +133,9 @@ export const RiskScore = z.number().int().min(0).max(100);
|
|||
export type RiskScoreMapping = z.infer<typeof RiskScoreMapping>;
|
||||
export const RiskScoreMapping = z.array(
|
||||
z.object({
|
||||
/**
|
||||
* Source event field used to override the default `risk_score`.
|
||||
*/
|
||||
field: z.string(),
|
||||
operator: z.literal('equals'),
|
||||
value: z.string(),
|
||||
|
|
@ -127,8 +144,13 @@ export const RiskScoreMapping = z.array(
|
|||
);
|
||||
|
||||
/**
|
||||
* Severity of the rule
|
||||
*/
|
||||
* Severity level of alerts produced by the rule, which must be one of the following:
|
||||
* `low`: Alerts that are of interest but generally not considered to be security incidents
|
||||
* `medium`: Alerts that require investigation
|
||||
* `high`: Alerts that require immediate investigation
|
||||
* `critical`: Alerts that indicate it is highly likely a security incident has occurred
|
||||
|
||||
*/
|
||||
export type Severity = z.infer<typeof Severity>;
|
||||
export const Severity = z.enum(['low', 'medium', 'high', 'critical']);
|
||||
export type SeverityEnum = typeof Severity.enum;
|
||||
|
|
@ -140,6 +162,9 @@ export const SeverityEnum = Severity.enum;
|
|||
export type SeverityMapping = z.infer<typeof SeverityMapping>;
|
||||
export const SeverityMapping = z.array(
|
||||
z.object({
|
||||
/**
|
||||
* Source event field used to override the default `severity`.
|
||||
*/
|
||||
field: z.string(),
|
||||
operator: z.literal('equals'),
|
||||
severity: Severity,
|
||||
|
|
@ -153,6 +178,12 @@ export const SeverityMapping = z.array(
|
|||
export type RuleTagArray = z.infer<typeof RuleTagArray>;
|
||||
export const RuleTagArray = z.array(z.string());
|
||||
|
||||
/**
|
||||
* Placeholder for metadata about the rule.
|
||||
> info
|
||||
> This field is overwritten when you save changes to the rule’s settings.
|
||||
|
||||
*/
|
||||
export type RuleMetadata = z.infer<typeof RuleMetadata>;
|
||||
export const RuleMetadata = z.object({}).catchall(z.unknown());
|
||||
|
||||
|
|
@ -162,12 +193,21 @@ export const RuleMetadata = z.object({}).catchall(z.unknown());
|
|||
export type RuleLicense = z.infer<typeof RuleLicense>;
|
||||
export const RuleLicense = z.string();
|
||||
|
||||
/**
|
||||
* The rule’s author.
|
||||
*/
|
||||
export type RuleAuthorArray = z.infer<typeof RuleAuthorArray>;
|
||||
export const RuleAuthorArray = z.array(z.string());
|
||||
|
||||
/**
|
||||
* String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
|
||||
*/
|
||||
export type RuleFalsePositiveArray = z.infer<typeof RuleFalsePositiveArray>;
|
||||
export const RuleFalsePositiveArray = z.array(z.string());
|
||||
|
||||
/**
|
||||
* Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
|
||||
*/
|
||||
export type RuleReferenceArray = z.infer<typeof RuleReferenceArray>;
|
||||
export const RuleReferenceArray = z.array(z.string());
|
||||
|
||||
|
|
@ -177,12 +217,18 @@ export const RuleReferenceArray = z.array(z.string());
|
|||
export type InvestigationGuide = z.infer<typeof InvestigationGuide>;
|
||||
export const InvestigationGuide = z.string();
|
||||
|
||||
/**
|
||||
* Populates the rule’s setup guide with instructions on rule prerequisites such as required integrations, configuration steps, and anything else needed for the rule to work correctly.
|
||||
*/
|
||||
export type SetupGuide = z.infer<typeof SetupGuide>;
|
||||
export const SetupGuide = z.string();
|
||||
|
||||
/**
|
||||
* Determines if the rule acts as a building block. By default, building-block alerts are not displayed in the UI. These rules are used as a foundation for other rules that do generate alerts. Its value must be default.
|
||||
*/
|
||||
* Determines if the rule acts as a building block. If yes, the value must be `default`.
|
||||
By default, building-block alerts are not displayed in the UI. These rules are used as a foundation for other rules that do generate alerts.
|
||||
For more information, refer to [About building block rules](https://www.elastic.co/guide/en/security/current/building-block-rule.html).
|
||||
|
||||
*/
|
||||
export type BuildingBlockType = z.infer<typeof BuildingBlockType>;
|
||||
export const BuildingBlockType = z.string();
|
||||
|
||||
|
|
@ -199,8 +245,14 @@ export const AlertsIndex = z.string();
|
|||
export type AlertsIndexNamespace = z.infer<typeof AlertsIndexNamespace>;
|
||||
export const AlertsIndexNamespace = z.string();
|
||||
|
||||
/**
|
||||
* Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run [advanced setting](https://www.elastic.co/guide/en/security/current/rules-ui-create.html#rule-ui-advanced-params) value).
|
||||
> info
|
||||
> This setting can be superseded by the [Kibana configuration setting](https://www.elastic.co/guide/en/kibana/current/alert-action-settings-kb.html#alert-settings) `xpack.alerting.rules.run.alerts.max`, which determines the maximum alerts generated by any rule in the Kibana alerting framework. For example, if `xpack.alerting.rules.run.alerts.max` is set to 1000, the rule can generate no more than 1000 alerts even if `max_signals` is set higher.
|
||||
|
||||
*/
|
||||
export type MaxSignals = z.infer<typeof MaxSignals>;
|
||||
export const MaxSignals = z.number().int().min(1);
|
||||
export const MaxSignals = z.number().int().min(1).default(100);
|
||||
|
||||
export type ThreatSubtechnique = z.infer<typeof ThreatSubtechnique>;
|
||||
export const ThreatSubtechnique = z.object({
|
||||
|
|
@ -232,12 +284,17 @@ export const ThreatTechnique = z.object({
|
|||
* Technique reference
|
||||
*/
|
||||
reference: z.string(),
|
||||
/**
|
||||
* Array containing more specific information on the attack technique
|
||||
*/
|
||||
/**
|
||||
* Array containing more specific information on the attack technique.
|
||||
|
||||
*/
|
||||
subtechnique: z.array(ThreatSubtechnique).optional(),
|
||||
});
|
||||
|
||||
/**
|
||||
* Object containing information on the attack type
|
||||
|
||||
*/
|
||||
export type ThreatTactic = z.infer<typeof ThreatTactic>;
|
||||
export const ThreatTactic = z.object({
|
||||
/**
|
||||
|
|
@ -254,6 +311,11 @@ export const ThreatTactic = z.object({
|
|||
reference: z.string(),
|
||||
});
|
||||
|
||||
/**
|
||||
* > info
|
||||
> Currently, only threats described using the MITRE ATT&CK™ framework are supported.
|
||||
|
||||
*/
|
||||
export type Threat = z.infer<typeof Threat>;
|
||||
export const Threat = z.object({
|
||||
/**
|
||||
|
|
@ -270,29 +332,51 @@ export const Threat = z.object({
|
|||
export type ThreatArray = z.infer<typeof ThreatArray>;
|
||||
export const ThreatArray = z.array(Threat);
|
||||
|
||||
/**
|
||||
* Indices on which the rule functions. Defaults to the Security Solution indices defined on the Kibana Advanced Settings page (Kibana → Stack Management → Advanced Settings → `securitySolution:defaultIndex`).
|
||||
> info
|
||||
> This field is not supported for ES|QL rules.
|
||||
|
||||
*/
|
||||
export type IndexPatternArray = z.infer<typeof IndexPatternArray>;
|
||||
export const IndexPatternArray = z.array(z.string());
|
||||
|
||||
export type DataViewId = z.infer<typeof DataViewId>;
|
||||
export const DataViewId = z.string();
|
||||
|
||||
/**
|
||||
* Kibana [saved search](https://www.elastic.co/guide/en/kibana/current/save-open-search.html) used by the rule to create alerts.
|
||||
*/
|
||||
export type SavedQueryId = z.infer<typeof SavedQueryId>;
|
||||
export const SavedQueryId = z.string();
|
||||
|
||||
/**
|
||||
* [Query](https://www.elastic.co/guide/en/kibana/8.17/search.html) used by the rule to create alerts.
|
||||
|
||||
- For indicator match rules, only the query’s results are used to determine whether an alert is generated.
|
||||
- ES|QL rules have additional query requirements. Refer to [Create ES|QL](https://www.elastic.co/guide/en/security/current/rules-ui-create.html#create-esql-rule) rules for more information.
|
||||
|
||||
*/
|
||||
export type RuleQuery = z.infer<typeof RuleQuery>;
|
||||
export const RuleQuery = z.string();
|
||||
|
||||
/**
|
||||
* The query and filter context array used to define the conditions for when alerts are created from events. Defaults to an empty array.
|
||||
> info
|
||||
> This field is not supported for ES|QL rules.
|
||||
|
||||
*/
|
||||
export type RuleFilterArray = z.infer<typeof RuleFilterArray>;
|
||||
export const RuleFilterArray = z.array(z.unknown());
|
||||
|
||||
/**
|
||||
* Sets the source field for the alert's signal.rule.name value
|
||||
* Sets which field in the source event is used to populate the alert's `signal.rule.name` value (in the UI, this value is displayed on the Rules page in the Rule column). When unspecified, the rule’s `name` value is used. The source field must be a string data type.
|
||||
*/
|
||||
export type RuleNameOverride = z.infer<typeof RuleNameOverride>;
|
||||
export const RuleNameOverride = z.string();
|
||||
|
||||
/**
|
||||
* Sets the time field used to query indices
|
||||
* Sets the time field used to query indices. When unspecified, rules query the `@timestamp` field. The source field must be an Elasticsearch date data type.
|
||||
*/
|
||||
export type TimestampOverride = z.infer<typeof TimestampOverride>;
|
||||
export const TimestampOverride = z.string();
|
||||
|
|
@ -332,13 +416,13 @@ export const RequiredField = z.object({
|
|||
/**
|
||||
* Name of an Elasticsearch field
|
||||
*/
|
||||
name: NonEmptyString,
|
||||
name: z.string().min(1).superRefine(isNonEmptyString),
|
||||
/**
|
||||
* Type of the Elasticsearch field
|
||||
*/
|
||||
type: NonEmptyString,
|
||||
type: z.string().min(1).superRefine(isNonEmptyString),
|
||||
/**
|
||||
* Whether the field is an ECS field
|
||||
* Indicates whether the field is ECS-compliant. This property is only present in responses. Its value is computed based on field’s name and type.
|
||||
*/
|
||||
ecs: z.boolean(),
|
||||
});
|
||||
|
|
@ -351,11 +435,11 @@ export const RequiredFieldInput = z.object({
|
|||
/**
|
||||
* Name of an Elasticsearch field
|
||||
*/
|
||||
name: NonEmptyString,
|
||||
name: z.string().min(1).superRefine(isNonEmptyString),
|
||||
/**
|
||||
* Type of an Elasticsearch field
|
||||
* Type of the Elasticsearch field
|
||||
*/
|
||||
type: NonEmptyString,
|
||||
type: z.string().min(1).superRefine(isNonEmptyString),
|
||||
});
|
||||
|
||||
export type RequiredFieldArray = z.infer<typeof RequiredFieldArray>;
|
||||
|
|
@ -408,19 +492,6 @@ There are Fleet packages like `windows` that contain only one integration; in th
|
|||
`integration` should be unspecified. There are also packages like `aws` and `azure` that contain
|
||||
several integrations; in this case, `integration` should be specified.
|
||||
|
||||
@example
|
||||
const x: RelatedIntegration = {
|
||||
package: 'windows',
|
||||
version: '1.5.x',
|
||||
};
|
||||
|
||||
@example
|
||||
const x: RelatedIntegration = {
|
||||
package: 'azure',
|
||||
version: '~1.1.6',
|
||||
integration: 'activitylogs',
|
||||
};
|
||||
|
||||
*/
|
||||
export type RelatedIntegration = z.infer<typeof RelatedIntegration>;
|
||||
export const RelatedIntegration = z.object({
|
||||
|
|
@ -435,17 +506,6 @@ export const RelatedIntegrationArray = z.array(RelatedIntegration);
|
|||
/**
|
||||
* Schema for fields relating to investigation fields. These are user defined fields we use to highlight
|
||||
in various features in the UI such as alert details flyout and exceptions auto-population from alert.
|
||||
Added in PR #163235
|
||||
Right now we only have a single field but anticipate adding more related fields to store various
|
||||
configuration states such as `override` - where a user might say if they want only these fields to
|
||||
display, or if they want these fields + the fields we select. When expanding this field, it may look
|
||||
something like:
|
||||
```typescript
|
||||
const investigationFields = z.object({
|
||||
field_names: NonEmptyArray(NonEmptyString),
|
||||
override: z.boolean().optional(),
|
||||
});
|
||||
```
|
||||
|
||||
*/
|
||||
export type InvestigationFields = z.infer<typeof InvestigationFields>;
|
||||
|
|
@ -463,7 +523,7 @@ export const RuleActionThrottle = z.union([
|
|||
]);
|
||||
|
||||
/**
|
||||
* The condition for throttling the notification: `onActionGroupChange`, `onActiveAlert`, or `onThrottleInterval`
|
||||
* Defines how often rules run actions.
|
||||
*/
|
||||
export type RuleActionNotifyWhen = z.infer<typeof RuleActionNotifyWhen>;
|
||||
export const RuleActionNotifyWhen = z.enum([
|
||||
|
|
@ -487,12 +547,54 @@ export const RuleActionFrequency = z.object({
|
|||
throttle: RuleActionThrottle.nullable(),
|
||||
});
|
||||
|
||||
/**
|
||||
* Object containing an action’s conditional filters.
|
||||
|
||||
- `timeframe` (object, optional): Object containing the time frame for when this action can be run.
|
||||
- `days` (array of integers, required): List of days of the week on which this action will be run. Days of the week are expressed as numbers between `1-7`, where `1` is Monday and `7` is Sunday. To select all days of the week, enter an empty array.
|
||||
- `hours` (object, required): The hours of the day during which this action will run. Hours of the day are expressed as two strings in the format `hh:mm` in `24` hour time. A start of `00:00` and an end of `24:00` means the action can run all day.
|
||||
- start (string, required): Start time in `hh:mm` format.
|
||||
- end (string, required): End time in `hh:mm` format.
|
||||
- `timezone` (string, required): An ISO timezone name, such as `Europe/Madrid` or `America/New_York`. Specific offsets such as `UTC` or `UTC+1` will also work, but lack built-in DST.
|
||||
- `query` (object, optional): Object containing a query filter which gets applied to an action and determines whether the action should run.
|
||||
- `kql` (string, required): A KQL string.
|
||||
- `filters` (array of objects, required): Array of filter objects, as defined in the `kbn-es-query` package.
|
||||
|
||||
|
||||
*/
|
||||
export type RuleActionAlertsFilter = z.infer<typeof RuleActionAlertsFilter>;
|
||||
export const RuleActionAlertsFilter = z.object({}).catchall(z.unknown());
|
||||
|
||||
/**
|
||||
* Object containing the allowed connector fields, which varies according to the connector type.
|
||||
*/
|
||||
* Object containing the allowed connector fields, which varies according to the connector type.
|
||||
|
||||
For Slack:
|
||||
|
||||
- `message` (string, required): The notification message.
|
||||
|
||||
For email:
|
||||
|
||||
- `to`, `cc`, `bcc` (string): Email addresses to which the notifications are sent. At least one field must have a value.
|
||||
- `subject` (string, optional): Email subject line.
|
||||
- `message` (string, required): Email body text.
|
||||
|
||||
For Webhook:
|
||||
|
||||
- `body` (string, required): JSON payload.
|
||||
|
||||
For PagerDuty:
|
||||
|
||||
- `severity` (string, required): Severity of on the alert notification, can be: `Critical`, `Error`, `Warning` or `Info`.
|
||||
- `eventAction` (string, required): Event [action type](https://v2.developer.pagerduty.com/docs/events-api-v2#event-action), which can be `trigger`, `resolve`, or `acknowledge`.
|
||||
- `dedupKey` (string, optional): Groups alert notifications with the same PagerDuty alert.
|
||||
- `timestamp` (DateTime, optional): ISO-8601 format [timestamp](https://v2.developer.pagerduty.com/docs/types#datetime).
|
||||
- `component` (string, optional): Source machine component responsible for the event, for example `security-solution`.
|
||||
- `group` (string, optional): Enables logical grouping of service components.
|
||||
- `source` (string, optional): The affected system. Defaults to the Kibana saved object ID of the action.
|
||||
- `summary` (string, options): Summary of the event. Defaults to `No summary provided`. Maximum length is 1024 characters.
|
||||
- `class` (string, optional): Value indicating the class/type of the event.
|
||||
|
||||
*/
|
||||
export type RuleActionParams = z.infer<typeof RuleActionParams>;
|
||||
export const RuleActionParams = z.object({}).catchall(z.unknown());
|
||||
|
||||
|
|
@ -510,9 +612,28 @@ export const RuleActionId = z.string();
|
|||
|
||||
export type RuleAction = z.infer<typeof RuleAction>;
|
||||
export const RuleAction = z.object({
|
||||
/**
|
||||
* The action type used for sending notifications.
|
||||
*/
|
||||
/**
|
||||
* The action type used for sending notifications, can be:
|
||||
|
||||
- `.slack`
|
||||
- `.slack_api`
|
||||
- `.email`
|
||||
- `.index`
|
||||
- `.pagerduty`
|
||||
- `.swimlane`
|
||||
- `.webhook`
|
||||
- `.servicenow`
|
||||
- `.servicenow-itom`
|
||||
- `.servicenow-sir`
|
||||
- `.jira`
|
||||
- `.resilient`
|
||||
- `.opsgenie`
|
||||
- `.teams`
|
||||
- `.torq`
|
||||
- `.tines`
|
||||
- `.d3security`
|
||||
|
||||
*/
|
||||
action_type_id: z.string(),
|
||||
group: RuleActionGroup.optional(),
|
||||
id: RuleActionId,
|
||||
|
|
@ -538,16 +659,20 @@ export const ExceptionListType = z.enum([
|
|||
export type ExceptionListTypeEnum = typeof ExceptionListType.enum;
|
||||
export const ExceptionListTypeEnum = ExceptionListType.enum;
|
||||
|
||||
/**
|
||||
* Array of [exception containers](https://www.elastic.co/guide/en/security/current/exceptions-api-overview.html), which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
|
||||
|
||||
*/
|
||||
export type RuleExceptionList = z.infer<typeof RuleExceptionList>;
|
||||
export const RuleExceptionList = z.object({
|
||||
/**
|
||||
* ID of the exception container
|
||||
*/
|
||||
id: NonEmptyString,
|
||||
id: z.string().min(1).superRefine(isNonEmptyString),
|
||||
/**
|
||||
* List ID of the exception container
|
||||
*/
|
||||
list_id: NonEmptyString,
|
||||
list_id: z.string().min(1).superRefine(isNonEmptyString),
|
||||
type: ExceptionListType,
|
||||
/**
|
||||
* Determines the exceptions validity in rule's Kibana space
|
||||
|
|
@ -555,6 +680,9 @@ export const RuleExceptionList = z.object({
|
|||
namespace_type: z.enum(['agnostic', 'single']),
|
||||
});
|
||||
|
||||
/**
|
||||
* Time unit
|
||||
*/
|
||||
export type AlertSuppressionDurationUnit = z.infer<typeof AlertSuppressionDurationUnit>;
|
||||
export const AlertSuppressionDurationUnit = z.enum(['s', 'm', 'h']);
|
||||
export type AlertSuppressionDurationUnitEnum = typeof AlertSuppressionDurationUnit.enum;
|
||||
|
|
@ -582,6 +710,9 @@ export const AlertSuppressionMissingFieldsStrategyEnum = AlertSuppressionMissing
|
|||
export type AlertSuppressionGroupBy = z.infer<typeof AlertSuppressionGroupBy>;
|
||||
export const AlertSuppressionGroupBy = z.array(z.string()).min(1).max(3);
|
||||
|
||||
/**
|
||||
* Defines alert suppression configuration.
|
||||
*/
|
||||
export type AlertSuppression = z.infer<typeof AlertSuppression>;
|
||||
export const AlertSuppression = z.object({
|
||||
group_by: AlertSuppressionGroupBy,
|
||||
|
|
|
|||
|
|
@ -8,18 +8,23 @@ components:
|
|||
schemas:
|
||||
RuleObjectId:
|
||||
$ref: '../../../model/primitives.schema.yaml#/components/schemas/UUID'
|
||||
description: A dynamic unique identifier for the rule object. It is randomly generated when a rule is created and cannot be changed after that. It is always a UUID. It is unique within a given Kibana space. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have different object `id`s.
|
||||
|
||||
RuleSignatureId:
|
||||
type: string
|
||||
description: Could be any string, not necessarily a UUID
|
||||
description: A stable unique identifier for the rule object. It can be assigned during rule creation. It can be any string, but often is a UUID. It should be unique not only within a given Kibana space, but also across spaces and Elastic environments. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have the same `rule_id`s.
|
||||
|
||||
RuleName:
|
||||
type: string
|
||||
description: A human-readable name for the rule.
|
||||
minLength: 1
|
||||
example: Anomalous Windows Process Creation
|
||||
|
||||
RuleDescription:
|
||||
type: string
|
||||
description: The rule’s description.
|
||||
minLength: 1
|
||||
example: Detects anomalous Windows process creation events.
|
||||
|
||||
RuleVersion:
|
||||
type: integer
|
||||
|
|
@ -84,7 +89,7 @@ components:
|
|||
|
||||
IsRuleEnabled:
|
||||
type: boolean
|
||||
description: Determines whether the rule is enabled.
|
||||
description: Determines whether the rule is enabled. Defaults to true.
|
||||
|
||||
RuleInterval:
|
||||
type: string
|
||||
|
|
@ -100,7 +105,12 @@ components:
|
|||
|
||||
RiskScore:
|
||||
type: integer
|
||||
description: Risk score (0 to 100)
|
||||
description: |
|
||||
A numerical representation of the alert's severity from 0 to 100, where:
|
||||
* `0` - `21` represents low severity
|
||||
* `22` - `47` represents medium severity
|
||||
* `48` - `73` represents high severity
|
||||
* `74` - `100` represents critical severity
|
||||
minimum: 0
|
||||
maximum: 100
|
||||
|
||||
|
|
@ -111,6 +121,7 @@ components:
|
|||
properties:
|
||||
field:
|
||||
type: string
|
||||
description: Source event field used to override the default `risk_score`.
|
||||
operator:
|
||||
type: string
|
||||
enum:
|
||||
|
|
@ -124,11 +135,15 @@ components:
|
|||
- operator
|
||||
- value
|
||||
description: Overrides generated alerts' risk_score with a value from the source event
|
||||
|
||||
Severity:
|
||||
type: string
|
||||
enum: [low, medium, high, critical]
|
||||
description: Severity of the rule
|
||||
description: |
|
||||
Severity level of alerts produced by the rule, which must be one of the following:
|
||||
* `low`: Alerts that are of interest but generally not considered to be security incidents
|
||||
* `medium`: Alerts that require investigation
|
||||
* `high`: Alerts that require immediate investigation
|
||||
* `critical`: Alerts that indicate it is highly likely a security incident has occurred
|
||||
|
||||
SeverityMapping:
|
||||
type: array
|
||||
|
|
@ -137,6 +152,7 @@ components:
|
|||
properties:
|
||||
field:
|
||||
type: string
|
||||
description: Source event field used to override the default `severity`.
|
||||
operator:
|
||||
type: string
|
||||
enum:
|
||||
|
|
@ -160,6 +176,11 @@ components:
|
|||
|
||||
RuleMetadata:
|
||||
type: object
|
||||
description: |
|
||||
Placeholder for metadata about the rule.
|
||||
> info
|
||||
> This field is overwritten when you save changes to the rule’s settings.
|
||||
|
||||
additionalProperties: true
|
||||
|
||||
RuleLicense:
|
||||
|
|
@ -168,16 +189,19 @@ components:
|
|||
|
||||
RuleAuthorArray:
|
||||
type: array
|
||||
description: The rule’s author.
|
||||
items:
|
||||
type: string
|
||||
|
||||
RuleFalsePositiveArray:
|
||||
type: array
|
||||
description: String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.
|
||||
items:
|
||||
type: string
|
||||
|
||||
RuleReferenceArray:
|
||||
type: array
|
||||
description: Array containing notes about or references to relevant information about the rule. Defaults to an empty array.
|
||||
items:
|
||||
type: string
|
||||
|
||||
|
|
@ -187,10 +211,14 @@ components:
|
|||
|
||||
SetupGuide:
|
||||
type: string
|
||||
description: Populates the rule’s setup guide with instructions on rule prerequisites such as required integrations, configuration steps, and anything else needed for the rule to work correctly.
|
||||
|
||||
BuildingBlockType:
|
||||
type: string
|
||||
description: Determines if the rule acts as a building block. By default, building-block alerts are not displayed in the UI. These rules are used as a foundation for other rules that do generate alerts. Its value must be default.
|
||||
description: |
|
||||
Determines if the rule acts as a building block. If yes, the value must be `default`.
|
||||
By default, building-block alerts are not displayed in the UI. These rules are used as a foundation for other rules that do generate alerts.
|
||||
For more information, refer to [About building block rules](https://www.elastic.co/guide/en/security/current/building-block-rule.html).
|
||||
|
||||
AlertsIndex:
|
||||
type: string
|
||||
|
|
@ -203,6 +231,11 @@ components:
|
|||
|
||||
MaxSignals:
|
||||
type: integer
|
||||
default: 100
|
||||
description: |
|
||||
Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run [advanced setting](https://www.elastic.co/guide/en/security/current/rules-ui-create.html#rule-ui-advanced-params) value).
|
||||
> info
|
||||
> This setting can be superseded by the [Kibana configuration setting](https://www.elastic.co/guide/en/kibana/current/alert-action-settings-kb.html#alert-settings) `xpack.alerting.rules.run.alerts.max`, which determines the maximum alerts generated by any rule in the Kibana alerting framework. For example, if `xpack.alerting.rules.run.alerts.max` is set to 1000, the rule can generate no more than 1000 alerts even if `max_signals` is set higher.
|
||||
minimum: 1
|
||||
|
||||
ThreatSubtechnique:
|
||||
|
|
@ -236,9 +269,10 @@ components:
|
|||
description: Technique reference
|
||||
subtechnique:
|
||||
type: array
|
||||
description: |
|
||||
Array containing more specific information on the attack technique.
|
||||
items:
|
||||
$ref: '#/components/schemas/ThreatSubtechnique'
|
||||
description: Array containing more specific information on the attack technique
|
||||
required:
|
||||
- id
|
||||
- name
|
||||
|
|
@ -246,6 +280,8 @@ components:
|
|||
|
||||
ThreatTactic:
|
||||
type: object
|
||||
description: |
|
||||
Object containing information on the attack type
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
|
|
@ -263,6 +299,9 @@ components:
|
|||
|
||||
Threat:
|
||||
type: object
|
||||
description: |
|
||||
> info
|
||||
> Currently, only threats described using the MITRE ATT&CK™ framework are supported.
|
||||
properties:
|
||||
framework:
|
||||
type: string
|
||||
|
|
@ -284,6 +323,10 @@ components:
|
|||
$ref: '#/components/schemas/Threat'
|
||||
|
||||
IndexPatternArray:
|
||||
description: |
|
||||
Indices on which the rule functions. Defaults to the Security Solution indices defined on the Kibana Advanced Settings page (Kibana → Stack Management → Advanced Settings → `securitySolution:defaultIndex`).
|
||||
> info
|
||||
> This field is not supported for ES|QL rules.
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
|
|
@ -293,21 +336,31 @@ components:
|
|||
|
||||
SavedQueryId:
|
||||
type: string
|
||||
description: Kibana [saved search](https://www.elastic.co/guide/en/kibana/current/save-open-search.html) used by the rule to create alerts.
|
||||
|
||||
RuleQuery:
|
||||
type: string
|
||||
description: |
|
||||
[Query](https://www.elastic.co/guide/en/kibana/8.17/search.html) used by the rule to create alerts.
|
||||
|
||||
- For indicator match rules, only the query’s results are used to determine whether an alert is generated.
|
||||
- ES|QL rules have additional query requirements. Refer to [Create ES|QL](https://www.elastic.co/guide/en/security/current/rules-ui-create.html#create-esql-rule) rules for more information.
|
||||
|
||||
RuleFilterArray:
|
||||
type: array
|
||||
description: |
|
||||
The query and filter context array used to define the conditions for when alerts are created from events. Defaults to an empty array.
|
||||
> info
|
||||
> This field is not supported for ES|QL rules.
|
||||
items: {} # unknown
|
||||
|
||||
RuleNameOverride:
|
||||
type: string
|
||||
description: Sets the source field for the alert's signal.rule.name value
|
||||
description: Sets which field in the source event is used to populate the alert's `signal.rule.name` value (in the UI, this value is displayed on the Rules page in the Rule column). When unspecified, the rule’s `name` value is used. The source field must be a string data type.
|
||||
|
||||
TimestampOverride:
|
||||
type: string
|
||||
description: Sets the time field used to query indices
|
||||
description: Sets the time field used to query indices. When unspecified, rules query the `@timestamp` field. The source field must be an Elasticsearch date data type.
|
||||
|
||||
TimestampOverrideFallbackDisabled:
|
||||
type: boolean
|
||||
|
|
@ -339,14 +392,18 @@ components:
|
|||
};
|
||||
properties:
|
||||
name:
|
||||
$ref: '../../../model/primitives.schema.yaml#/components/schemas/NonEmptyString'
|
||||
type: string
|
||||
format: nonempty
|
||||
minLength: 1
|
||||
description: Name of an Elasticsearch field
|
||||
type:
|
||||
$ref: '../../../model/primitives.schema.yaml#/components/schemas/NonEmptyString'
|
||||
type: string
|
||||
format: nonempty
|
||||
minLength: 1
|
||||
description: Type of the Elasticsearch field
|
||||
ecs:
|
||||
type: boolean
|
||||
description: Whether the field is an ECS field
|
||||
description: Indicates whether the field is ECS-compliant. This property is only present in responses. Its value is computed based on field’s name and type.
|
||||
required:
|
||||
- name
|
||||
- type
|
||||
|
|
@ -357,11 +414,15 @@ components:
|
|||
description: Input parameters to create a RequiredField. Does not include the `ecs` field, because `ecs` is calculated on the backend based on the field name and type.
|
||||
properties:
|
||||
name:
|
||||
$ref: '../../../model/primitives.schema.yaml#/components/schemas/NonEmptyString'
|
||||
type: string
|
||||
format: nonempty
|
||||
minLength: 1
|
||||
description: Name of an Elasticsearch field
|
||||
type:
|
||||
$ref: '../../../model/primitives.schema.yaml#/components/schemas/NonEmptyString'
|
||||
description: Type of an Elasticsearch field
|
||||
type: string
|
||||
format: nonempty
|
||||
minLength: 1
|
||||
description: Type of the Elasticsearch field
|
||||
required:
|
||||
- name
|
||||
- type
|
||||
|
|
@ -398,36 +459,23 @@ components:
|
|||
RelatedIntegration:
|
||||
type: object
|
||||
description: |
|
||||
Related integration is a potential dependency of a rule. It's assumed that if the user installs
|
||||
one of the related integrations of a rule, the rule might start to work properly because it will
|
||||
have source events (generated by this integration) potentially matching the rule's query.
|
||||
Related integration is a potential dependency of a rule. It's assumed that if the user installs
|
||||
one of the related integrations of a rule, the rule might start to work properly because it will
|
||||
have source events (generated by this integration) potentially matching the rule's query.
|
||||
|
||||
NOTE: Proper work is not guaranteed, because a related integration, if installed, can be
|
||||
configured differently or generate data that is not necessarily relevant for this rule.
|
||||
NOTE: Proper work is not guaranteed, because a related integration, if installed, can be
|
||||
configured differently or generate data that is not necessarily relevant for this rule.
|
||||
|
||||
Related integration is a combination of a Fleet package and (optionally) one of the
|
||||
package's "integrations" that this package contains. It is represented by 3 properties:
|
||||
Related integration is a combination of a Fleet package and (optionally) one of the
|
||||
package's "integrations" that this package contains. It is represented by 3 properties:
|
||||
|
||||
- `package`: name of the package (required, unique id)
|
||||
- `version`: version of the package (required, semver-compatible)
|
||||
- `integration`: name of the integration of this package (optional, id within the package)
|
||||
- `package`: name of the package (required, unique id)
|
||||
- `version`: version of the package (required, semver-compatible)
|
||||
- `integration`: name of the integration of this package (optional, id within the package)
|
||||
|
||||
There are Fleet packages like `windows` that contain only one integration; in this case,
|
||||
`integration` should be unspecified. There are also packages like `aws` and `azure` that contain
|
||||
several integrations; in this case, `integration` should be specified.
|
||||
|
||||
@example
|
||||
const x: RelatedIntegration = {
|
||||
package: 'windows',
|
||||
version: '1.5.x',
|
||||
};
|
||||
|
||||
@example
|
||||
const x: RelatedIntegration = {
|
||||
package: 'azure',
|
||||
version: '~1.1.6',
|
||||
integration: 'activitylogs',
|
||||
};
|
||||
There are Fleet packages like `windows` that contain only one integration; in this case,
|
||||
`integration` should be unspecified. There are also packages like `aws` and `azure` that contain
|
||||
several integrations; in this case, `integration` should be specified.
|
||||
properties:
|
||||
package:
|
||||
$ref: '../../../model/primitives.schema.yaml#/components/schemas/NonEmptyString'
|
||||
|
|
@ -435,6 +483,10 @@ components:
|
|||
$ref: '../../../model/primitives.schema.yaml#/components/schemas/NonEmptyString'
|
||||
integration:
|
||||
$ref: '../../../model/primitives.schema.yaml#/components/schemas/NonEmptyString'
|
||||
example:
|
||||
package: 'azure'
|
||||
version: '~1.1.6'
|
||||
integration: 'activitylogs'
|
||||
required:
|
||||
- package
|
||||
- version
|
||||
|
|
@ -449,17 +501,6 @@ components:
|
|||
description: |
|
||||
Schema for fields relating to investigation fields. These are user defined fields we use to highlight
|
||||
in various features in the UI such as alert details flyout and exceptions auto-population from alert.
|
||||
Added in PR #163235
|
||||
Right now we only have a single field but anticipate adding more related fields to store various
|
||||
configuration states such as `override` - where a user might say if they want only these fields to
|
||||
display, or if they want these fields + the fields we select. When expanding this field, it may look
|
||||
something like:
|
||||
```typescript
|
||||
const investigationFields = z.object({
|
||||
field_names: NonEmptyArray(NonEmptyString),
|
||||
override: z.boolean().optional(),
|
||||
});
|
||||
```
|
||||
properties:
|
||||
field_names:
|
||||
type: array
|
||||
|
|
@ -487,7 +528,7 @@ components:
|
|||
- 'onActiveAlert'
|
||||
- 'onThrottleInterval'
|
||||
- 'onActionGroupChange'
|
||||
description: 'The condition for throttling the notification: `onActionGroupChange`, `onActiveAlert`, or `onThrottleInterval`'
|
||||
description: Defines how often rules run actions.
|
||||
|
||||
RuleActionFrequency:
|
||||
type: object
|
||||
|
|
@ -509,10 +550,49 @@ components:
|
|||
RuleActionAlertsFilter:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
description: |
|
||||
Object containing an action’s conditional filters.
|
||||
|
||||
- `timeframe` (object, optional): Object containing the time frame for when this action can be run.
|
||||
- `days` (array of integers, required): List of days of the week on which this action will be run. Days of the week are expressed as numbers between `1-7`, where `1` is Monday and `7` is Sunday. To select all days of the week, enter an empty array.
|
||||
- `hours` (object, required): The hours of the day during which this action will run. Hours of the day are expressed as two strings in the format `hh:mm` in `24` hour time. A start of `00:00` and an end of `24:00` means the action can run all day.
|
||||
- start (string, required): Start time in `hh:mm` format.
|
||||
- end (string, required): End time in `hh:mm` format.
|
||||
- `timezone` (string, required): An ISO timezone name, such as `Europe/Madrid` or `America/New_York`. Specific offsets such as `UTC` or `UTC+1` will also work, but lack built-in DST.
|
||||
- `query` (object, optional): Object containing a query filter which gets applied to an action and determines whether the action should run.
|
||||
- `kql` (string, required): A KQL string.
|
||||
- `filters` (array of objects, required): Array of filter objects, as defined in the `kbn-es-query` package.
|
||||
|
||||
RuleActionParams:
|
||||
type: object
|
||||
description: Object containing the allowed connector fields, which varies according to the connector type.
|
||||
description: |
|
||||
Object containing the allowed connector fields, which varies according to the connector type.
|
||||
|
||||
For Slack:
|
||||
|
||||
- `message` (string, required): The notification message.
|
||||
|
||||
For email:
|
||||
|
||||
- `to`, `cc`, `bcc` (string): Email addresses to which the notifications are sent. At least one field must have a value.
|
||||
- `subject` (string, optional): Email subject line.
|
||||
- `message` (string, required): Email body text.
|
||||
|
||||
For Webhook:
|
||||
|
||||
- `body` (string, required): JSON payload.
|
||||
|
||||
For PagerDuty:
|
||||
|
||||
- `severity` (string, required): Severity of on the alert notification, can be: `Critical`, `Error`, `Warning` or `Info`.
|
||||
- `eventAction` (string, required): Event [action type](https://v2.developer.pagerduty.com/docs/events-api-v2#event-action), which can be `trigger`, `resolve`, or `acknowledge`.
|
||||
- `dedupKey` (string, optional): Groups alert notifications with the same PagerDuty alert.
|
||||
- `timestamp` (DateTime, optional): ISO-8601 format [timestamp](https://v2.developer.pagerduty.com/docs/types#datetime).
|
||||
- `component` (string, optional): Source machine component responsible for the event, for example `security-solution`.
|
||||
- `group` (string, optional): Enables logical grouping of service components.
|
||||
- `source` (string, optional): The affected system. Defaults to the Kibana saved object ID of the action.
|
||||
- `summary` (string, options): Summary of the event. Defaults to `No summary provided`. Maximum length is 1024 characters.
|
||||
- `class` (string, optional): Value indicating the class/type of the event.
|
||||
additionalProperties: true
|
||||
|
||||
RuleActionGroup:
|
||||
|
|
@ -528,7 +608,26 @@ components:
|
|||
properties:
|
||||
action_type_id:
|
||||
type: string
|
||||
description: The action type used for sending notifications.
|
||||
description: |
|
||||
The action type used for sending notifications, can be:
|
||||
|
||||
- `.slack`
|
||||
- `.slack_api`
|
||||
- `.email`
|
||||
- `.index`
|
||||
- `.pagerduty`
|
||||
- `.swimlane`
|
||||
- `.webhook`
|
||||
- `.servicenow`
|
||||
- `.servicenow-itom`
|
||||
- `.servicenow-sir`
|
||||
- `.jira`
|
||||
- `.resilient`
|
||||
- `.opsgenie`
|
||||
- `.teams`
|
||||
- `.torq`
|
||||
- `.tines`
|
||||
- `.d3security`
|
||||
group:
|
||||
$ref: '#/components/schemas/RuleActionGroup'
|
||||
id:
|
||||
|
|
@ -560,12 +659,18 @@ components:
|
|||
|
||||
RuleExceptionList:
|
||||
type: object
|
||||
description: |
|
||||
Array of [exception containers](https://www.elastic.co/guide/en/security/current/exceptions-api-overview.html), which define exceptions that prevent the rule from generating alerts even when its other criteria are met.
|
||||
properties:
|
||||
id:
|
||||
$ref: '../../../model/primitives.schema.yaml#/components/schemas/NonEmptyString'
|
||||
type: string
|
||||
format: nonempty
|
||||
minLength: 1
|
||||
description: ID of the exception container
|
||||
list_id:
|
||||
$ref: '../../../model/primitives.schema.yaml#/components/schemas/NonEmptyString'
|
||||
type: string
|
||||
format: nonempty
|
||||
minLength: 1
|
||||
description: List ID of the exception container
|
||||
type:
|
||||
$ref: '#/components/schemas/ExceptionListType'
|
||||
|
|
@ -583,6 +688,7 @@ components:
|
|||
|
||||
AlertSuppressionDurationUnit:
|
||||
type: string
|
||||
description: Time unit
|
||||
enum:
|
||||
- s
|
||||
- m
|
||||
|
|
@ -619,6 +725,7 @@ components:
|
|||
|
||||
AlertSuppression:
|
||||
type: object
|
||||
description: Defines alert suppression configuration.
|
||||
properties:
|
||||
group_by:
|
||||
$ref: '#/components/schemas/AlertSuppressionGroupBy'
|
||||
|
|
|
|||
|
|
@ -130,6 +130,9 @@ export const BaseDefaultableFields = z.object({
|
|||
interval: RuleInterval.optional(),
|
||||
from: RuleIntervalFrom.optional(),
|
||||
to: RuleIntervalTo.optional(),
|
||||
/**
|
||||
* Array defining the automated actions (notifications) taken when alerts are generated.
|
||||
*/
|
||||
actions: z.array(RuleAction).optional(),
|
||||
exceptions_list: z.array(RuleExceptionList).optional(),
|
||||
author: RuleAuthorArray.optional(),
|
||||
|
|
@ -139,6 +142,12 @@ export const BaseDefaultableFields = z.object({
|
|||
threat: ThreatArray.optional(),
|
||||
setup: SetupGuide.optional(),
|
||||
related_integrations: RelatedIntegrationArray.optional(),
|
||||
/**
|
||||
* Elasticsearch fields and their types that need to be present for the rule to function.
|
||||
> info
|
||||
> The value of `required_fields` does not affect the rule’s behavior, and specifying it incorrectly won’t cause the rule to fail. Use `required_fields` as an informational property to document the fields that the rule expects to be present in the data.
|
||||
|
||||
*/
|
||||
required_fields: z.array(RequiredFieldInput).optional(),
|
||||
});
|
||||
|
||||
|
|
@ -206,9 +215,6 @@ export const EqlRequiredFields = z.object({
|
|||
* Rule type
|
||||
*/
|
||||
type: z.literal('eql'),
|
||||
/**
|
||||
* EQL query to execute
|
||||
*/
|
||||
query: RuleQuery,
|
||||
/**
|
||||
* Query language to use
|
||||
|
|
@ -564,9 +570,6 @@ export const EsqlRuleRequiredFields = z.object({
|
|||
*/
|
||||
type: z.literal('esql'),
|
||||
language: EsqlQueryLanguage,
|
||||
/**
|
||||
* ESQL query to execute
|
||||
*/
|
||||
query: RuleQuery,
|
||||
});
|
||||
|
||||
|
|
|
|||
|
|
@ -109,6 +109,7 @@ components:
|
|||
# Rule actions
|
||||
actions:
|
||||
type: array
|
||||
description: Array defining the automated actions (notifications) taken when alerts are generated.
|
||||
items:
|
||||
$ref: './common_attributes.schema.yaml#/components/schemas/RuleAction'
|
||||
|
||||
|
|
@ -141,10 +142,13 @@ components:
|
|||
# Related integrations
|
||||
related_integrations:
|
||||
$ref: './common_attributes.schema.yaml#/components/schemas/RelatedIntegrationArray'
|
||||
|
||||
# Required fields
|
||||
required_fields:
|
||||
type: array
|
||||
description: |
|
||||
Elasticsearch fields and their types that need to be present for the rule to function.
|
||||
> info
|
||||
> The value of `required_fields` does not affect the rule’s behavior, and specifying it incorrectly won’t cause the rule to fail. Use `required_fields` as an informational property to document the fields that the rule expects to be present in the data.
|
||||
items:
|
||||
$ref: './common_attributes.schema.yaml#/components/schemas/RequiredFieldInput'
|
||||
|
||||
|
|
@ -272,7 +276,6 @@ components:
|
|||
description: Rule type
|
||||
query:
|
||||
$ref: './common_attributes.schema.yaml#/components/schemas/RuleQuery'
|
||||
description: EQL query to execute
|
||||
language:
|
||||
$ref: '#/components/schemas/EqlQueryLanguage'
|
||||
description: Query language to use
|
||||
|
|
@ -827,7 +830,6 @@ components:
|
|||
$ref: '#/components/schemas/EsqlQueryLanguage'
|
||||
query:
|
||||
$ref: './common_attributes.schema.yaml#/components/schemas/RuleQuery'
|
||||
description: ESQL query to execute
|
||||
required:
|
||||
- type
|
||||
- language
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ export type EventCategoryOverride = z.infer<typeof EventCategoryOverride>;
|
|||
export const EventCategoryOverride = z.string();
|
||||
|
||||
/**
|
||||
* Contains the event timestamp used for sorting a sequence of events
|
||||
* Specifies the name of the event timestamp field used for sorting a sequence of events. Not to be confused with `timestamp_override`, which specifies the more general field used for querying events within a range. Defaults to the @timestamp ECS field.
|
||||
*/
|
||||
export type TimestampField = z.infer<typeof TimestampField>;
|
||||
export const TimestampField = z.string();
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ components:
|
|||
type: string
|
||||
TimestampField:
|
||||
type: string
|
||||
description: Contains the event timestamp used for sorting a sequence of events
|
||||
description: Specifies the name of the event timestamp field used for sorting a sequence of events. Not to be confused with `timestamp_override`, which specifies the more general field used for querying events within a range. Defaults to the @timestamp ECS field.
|
||||
TiebreakerField:
|
||||
type: string
|
||||
description: Sets a secondary field for sorting events
|
||||
|
|
|
|||
|
|
@ -17,13 +17,13 @@
|
|||
import { z } from '@kbn/zod';
|
||||
|
||||
/**
|
||||
* Anomaly threshold
|
||||
* Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.
|
||||
*/
|
||||
export type AnomalyThreshold = z.infer<typeof AnomalyThreshold>;
|
||||
export const AnomalyThreshold = z.number().int().min(0);
|
||||
|
||||
/**
|
||||
* Machine learning job ID
|
||||
* Machine learning job ID(s) the rule monitors for anomaly scores.
|
||||
*/
|
||||
export type MachineLearningJobId = z.infer<typeof MachineLearningJobId>;
|
||||
export const MachineLearningJobId = z.union([z.string(), z.array(z.string()).min(1)]);
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ components:
|
|||
AnomalyThreshold:
|
||||
type: integer
|
||||
minimum: 0
|
||||
description: Anomaly threshold
|
||||
description: Anomaly score threshold above which the rule creates an alert. Valid values are from 0 to 100.
|
||||
MachineLearningJobId:
|
||||
oneOf:
|
||||
- type: string
|
||||
|
|
@ -17,4 +17,4 @@ components:
|
|||
items:
|
||||
type: string
|
||||
minItems: 1
|
||||
description: Machine learning job ID
|
||||
description: Machine learning job ID(s) the rule monitors for anomaly scores.
|
||||
|
|
|
|||
|
|
@ -15,11 +15,16 @@
|
|||
*/
|
||||
|
||||
import { z } from '@kbn/zod';
|
||||
import { isNonEmptyString } from '@kbn/zod-helpers';
|
||||
|
||||
import { NonEmptyString } from '../../../../model/primitives.gen';
|
||||
|
||||
/**
|
||||
* Fields to monitor for new values.
|
||||
*/
|
||||
export type NewTermsFields = z.infer<typeof NewTermsFields>;
|
||||
export const NewTermsFields = z.array(z.string()).min(1).max(3);
|
||||
|
||||
/**
|
||||
* Start date to use when checking if a term has been seen before. Supports relative dates – for example, now-30d will search the last 30 days of data when checking if a term is new. We do not recommend using absolute dates, which can cause issues with rule performance due to querying increasing amounts of data over time.
|
||||
*/
|
||||
export type HistoryWindowStart = z.infer<typeof HistoryWindowStart>;
|
||||
export const HistoryWindowStart = NonEmptyString;
|
||||
export const HistoryWindowStart = z.string().min(1).superRefine(isNonEmptyString);
|
||||
|
|
|
|||
|
|
@ -10,7 +10,11 @@ components:
|
|||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Fields to monitor for new values.
|
||||
minItems: 1
|
||||
maxItems: 3
|
||||
HistoryWindowStart:
|
||||
$ref: '../../../../model/primitives.schema.yaml#/components/schemas/NonEmptyString'
|
||||
type: string
|
||||
format: nonempty
|
||||
minLength: 1
|
||||
description: Start date to use when checking if a term has been seen before. Supports relative dates – for example, now-30d will search the last 30 days of data when checking if a term is new. We do not recommend using absolute dates, which can cause issues with rule performance due to querying increasing amounts of data over time.
|
||||
|
|
|
|||
|
|
@ -19,11 +19,21 @@ import { z } from '@kbn/zod';
|
|||
import { NonEmptyString } from '../../../../model/primitives.gen';
|
||||
|
||||
/**
|
||||
* Query to run
|
||||
* Query used to determine which fields in the Elasticsearch index are used for generating alerts.
|
||||
*/
|
||||
export type ThreatQuery = z.infer<typeof ThreatQuery>;
|
||||
export const ThreatQuery = z.string();
|
||||
|
||||
/**
|
||||
* Array of entries objects that define mappings between the source event fields and the values in the Elasticsearch threat index. Each entries object must contain these fields:
|
||||
|
||||
- field: field from the event indices on which the rule runs
|
||||
- type: must be mapping
|
||||
- value: field from the Elasticsearch threat index
|
||||
|
||||
You can use Boolean and and or logic to define the conditions for when matching fields and values generate alerts. Sibling entries objects are evaluated using or logic, whereas multiple entries in a single entries object use and logic. See Example of Threat Match rule which uses both `and` and `or` logic.
|
||||
|
||||
*/
|
||||
export type ThreatMapping = z.infer<typeof ThreatMapping>;
|
||||
export const ThreatMapping = z
|
||||
.array(
|
||||
|
|
@ -39,6 +49,9 @@ export const ThreatMapping = z
|
|||
)
|
||||
.min(1);
|
||||
|
||||
/**
|
||||
* Elasticsearch indices used to check which field values generate alerts.
|
||||
*/
|
||||
export type ThreatIndex = z.infer<typeof ThreatIndex>;
|
||||
export const ThreatIndex = z.array(z.string());
|
||||
|
||||
|
|
|
|||
|
|
@ -8,10 +8,18 @@ components:
|
|||
schemas:
|
||||
ThreatQuery:
|
||||
type: string
|
||||
description: Query to run
|
||||
description: Query used to determine which fields in the Elasticsearch index are used for generating alerts.
|
||||
|
||||
ThreatMapping:
|
||||
type: array
|
||||
description: |
|
||||
Array of entries objects that define mappings between the source event fields and the values in the Elasticsearch threat index. Each entries object must contain these fields:
|
||||
|
||||
- field: field from the event indices on which the rule runs
|
||||
- type: must be mapping
|
||||
- value: field from the Elasticsearch threat index
|
||||
|
||||
You can use Boolean and and or logic to define the conditions for when matching fields and values generate alerts. Sibling entries objects are evaluated using or logic, whereas multiple entries in a single entries object use and logic. See Example of Threat Match rule which uses both `and` and `or` logic.
|
||||
minItems: 1
|
||||
items:
|
||||
type: object
|
||||
|
|
@ -38,6 +46,7 @@ components:
|
|||
|
||||
ThreatIndex:
|
||||
type: array
|
||||
description: Elasticsearch indices used to check which field values generate alerts.
|
||||
items:
|
||||
type: string
|
||||
|
||||
|
|
|
|||
|
|
@ -18,22 +18,31 @@ import { z } from '@kbn/zod';
|
|||
|
||||
import { AlertSuppressionDuration } from '../common_attributes.gen';
|
||||
|
||||
/**
|
||||
* The field on which the cardinality is applied.
|
||||
*/
|
||||
export type ThresholdCardinality = z.infer<typeof ThresholdCardinality>;
|
||||
export const ThresholdCardinality = z.array(
|
||||
z.object({
|
||||
/**
|
||||
* The field on which to calculate and compare the cardinality.
|
||||
*/
|
||||
field: z.string(),
|
||||
/**
|
||||
* The threshold value from which an alert is generated based on unique number of values of cardinality.field.
|
||||
*/
|
||||
value: z.number().int().min(0),
|
||||
})
|
||||
);
|
||||
|
||||
/**
|
||||
* Threshold value
|
||||
* The threshold value from which an alert is generated.
|
||||
*/
|
||||
export type ThresholdValue = z.infer<typeof ThresholdValue>;
|
||||
export const ThresholdValue = z.number().int().min(1);
|
||||
|
||||
/**
|
||||
* Field to aggregate on
|
||||
* The field on which the threshold is applied. If you specify an empty array ([]), alerts are generated when the query returns at least the number of results specified in the value field.
|
||||
*/
|
||||
export type ThresholdField = z.infer<typeof ThresholdField>;
|
||||
export const ThresholdField = z.union([z.string(), z.array(z.string())]);
|
||||
|
|
@ -65,6 +74,9 @@ export const ThresholdWithCardinality = z.object({
|
|||
cardinality: ThresholdCardinality,
|
||||
});
|
||||
|
||||
/**
|
||||
* Defines alert suppression configuration.
|
||||
*/
|
||||
export type ThresholdAlertSuppression = z.infer<typeof ThresholdAlertSuppression>;
|
||||
export const ThresholdAlertSuppression = z.object({
|
||||
duration: AlertSuppressionDuration,
|
||||
|
|
|
|||
|
|
@ -8,13 +8,16 @@ components:
|
|||
schemas:
|
||||
ThresholdCardinality:
|
||||
type: array
|
||||
description: The field on which the cardinality is applied.
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
field:
|
||||
type: string
|
||||
description: The field on which to calculate and compare the cardinality.
|
||||
value:
|
||||
type: integer
|
||||
description: The threshold value from which an alert is generated based on unique number of values of cardinality.field.
|
||||
minimum: 0
|
||||
required:
|
||||
- field
|
||||
|
|
@ -23,7 +26,7 @@ components:
|
|||
ThresholdValue:
|
||||
type: integer
|
||||
minimum: 1
|
||||
description: Threshold value
|
||||
description: The threshold value from which an alert is generated.
|
||||
|
||||
ThresholdField:
|
||||
oneOf:
|
||||
|
|
@ -31,7 +34,7 @@ components:
|
|||
- type: array
|
||||
items:
|
||||
type: string
|
||||
description: Field to aggregate on
|
||||
description: The field on which the threshold is applied. If you specify an empty array ([]), alerts are generated when the query returns at least the number of results specified in the value field.
|
||||
|
||||
ThresholdFieldNormalized:
|
||||
type: array
|
||||
|
|
@ -81,8 +84,9 @@ components:
|
|||
|
||||
ThresholdAlertSuppression:
|
||||
type: object
|
||||
description: Defines alert suppression configuration.
|
||||
properties:
|
||||
duration:
|
||||
duration:
|
||||
$ref: '../common_attributes.schema.yaml#/components/schemas/AlertSuppressionDuration'
|
||||
required:
|
||||
- duration
|
||||
- duration
|
||||
|
|
|
|||
|
|
@ -9,7 +9,18 @@ paths:
|
|||
x-codegen-enabled: true
|
||||
operationId: InstallPrebuiltRulesAndTimelines
|
||||
summary: Install prebuilt detection rules and Timelines
|
||||
description: Install and update all Elastic prebuilt detection rules and Timelines.
|
||||
description: |
|
||||
Install and update all Elastic prebuilt detection rules and Timelines.
|
||||
|
||||
This endpoint allows you to install and update prebuilt detection rules and Timelines provided by Elastic.
|
||||
When you call this endpoint, it will:
|
||||
- Install any new prebuilt detection rules that are not currently installed in your system.
|
||||
- Update any existing prebuilt detection rules that have been modified or improved by Elastic.
|
||||
- Install any new prebuilt Timelines that are not currently installed in your system.
|
||||
- Update any existing prebuilt Timelines that have been modified or improved by Elastic.
|
||||
|
||||
This ensures that your detection engine is always up-to-date with the latest rules and Timelines,
|
||||
providing you with the most current and effective threat detection capabilities.
|
||||
tags:
|
||||
- Prebuilt Rules API
|
||||
responses:
|
||||
|
|
@ -42,3 +53,10 @@ paths:
|
|||
- rules_updated
|
||||
- timelines_installed
|
||||
- timelines_updated
|
||||
examples:
|
||||
example1:
|
||||
value:
|
||||
rules_installed: 112
|
||||
rules_updated: 0
|
||||
timelines_installed: 5
|
||||
timelines_updated: 2
|
||||
|
|
|
|||
|
|
@ -9,7 +9,10 @@ paths:
|
|||
x-codegen-enabled: true
|
||||
operationId: ReadPrebuiltRulesAndTimelinesStatus
|
||||
summary: Retrieve the status of prebuilt detection rules and Timelines
|
||||
description: Retrieve the status of all Elastic prebuilt detection rules and Timelines.
|
||||
description: |
|
||||
Retrieve the status of all Elastic prebuilt detection rules and Timelines.
|
||||
|
||||
This endpoint provides detailed information about the number of custom rules, installed prebuilt rules, available prebuilt rules that are not installed, outdated prebuilt rules, installed prebuilt timelines, available prebuilt timelines that are not installed, and outdated prebuilt timelines.
|
||||
tags:
|
||||
- Prebuilt Rules API
|
||||
responses:
|
||||
|
|
@ -57,3 +60,13 @@ paths:
|
|||
- timelines_installed
|
||||
- timelines_not_installed
|
||||
- timelines_not_updated
|
||||
examples:
|
||||
example1:
|
||||
value:
|
||||
rules_custom_installed: 0
|
||||
rules_installed: 0
|
||||
rules_not_installed: 112
|
||||
rules_not_updated: 0
|
||||
timelines_installed: 0
|
||||
timelines_not_installed: 0
|
||||
timelines_not_updated: 0
|
||||
|
|
|
|||
|
|
@ -76,6 +76,9 @@ export const BulkEditActionResults = z.object({
|
|||
skipped: z.array(BulkActionSkipResult),
|
||||
});
|
||||
|
||||
/**
|
||||
* A rule can only be skipped when the bulk action to be performed on it results in nothing being done. For example, if the `edit` action is used to add a tag to a rule that already has that tag, or to delete an index pattern that is not specified in a rule. Objects returned in `attributes.results.skipped` will only include rules' `id`, `name`, and `skip_reason`.
|
||||
*/
|
||||
export type BulkEditActionSummary = z.infer<typeof BulkEditActionSummary>;
|
||||
export const BulkEditActionSummary = z.object({
|
||||
failed: z.number().int(),
|
||||
|
|
@ -103,11 +106,11 @@ export const BulkExportActionResponse = z.string();
|
|||
export type BulkActionBase = z.infer<typeof BulkActionBase>;
|
||||
export const BulkActionBase = z.object({
|
||||
/**
|
||||
* Query to filter rules
|
||||
* Query to filter rules.
|
||||
*/
|
||||
query: z.string().optional(),
|
||||
/**
|
||||
* Array of rule IDs
|
||||
* Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined.
|
||||
*/
|
||||
ids: z.array(z.string()).min(1).optional(),
|
||||
});
|
||||
|
|
@ -144,6 +147,9 @@ export type BulkDuplicateRules = z.infer<typeof BulkDuplicateRules>;
|
|||
export const BulkDuplicateRules = BulkActionBase.merge(
|
||||
z.object({
|
||||
action: z.literal('duplicate'),
|
||||
/**
|
||||
* Duplicate object that describes applying an update action.
|
||||
*/
|
||||
duplicate: z
|
||||
.object({
|
||||
/**
|
||||
|
|
@ -163,6 +169,9 @@ export type BulkManualRuleRun = z.infer<typeof BulkManualRuleRun>;
|
|||
export const BulkManualRuleRun = BulkActionBase.merge(
|
||||
z.object({
|
||||
action: z.literal('run'),
|
||||
/**
|
||||
* Object that describes applying a manual rule run action.
|
||||
*/
|
||||
run: z.object({
|
||||
/**
|
||||
* Start date of the manual rule run
|
||||
|
|
@ -177,8 +186,12 @@ export const BulkManualRuleRun = BulkActionBase.merge(
|
|||
);
|
||||
|
||||
/**
|
||||
* The condition for throttling the notification: 'rule', 'no_actions', or time duration
|
||||
*/
|
||||
* Defines the maximum interval in which a rule’s actions are executed.
|
||||
> info
|
||||
> The rule level `throttle` field is deprecated in Elastic Security 8.8 and will remain active for at least the next 12 months.
|
||||
> In Elastic Security 8.8 and later, you can use the `frequency` field to define frequencies for individual actions. Actions without frequencies will acquire a converted version of the rule’s `throttle` field. In the response, the converted `throttle` setting appears in the individual actions' `frequency` field.
|
||||
|
||||
*/
|
||||
export type ThrottleForBulkActions = z.infer<typeof ThrottleForBulkActions>;
|
||||
export const ThrottleForBulkActions = z.enum(['rule', '1h', '1d', '7d']);
|
||||
export type ThrottleForBulkActionsEnum = typeof ThrottleForBulkActions.enum;
|
||||
|
|
@ -311,9 +324,16 @@ export const BulkEditRules = BulkActionBase.merge(
|
|||
|
||||
export type PerformRulesBulkActionRequestQuery = z.infer<typeof PerformRulesBulkActionRequestQuery>;
|
||||
export const PerformRulesBulkActionRequestQuery = z.object({
|
||||
/**
|
||||
* Enables dry run mode for the request call.
|
||||
*/
|
||||
/**
|
||||
* Enables dry run mode for the request call.
|
||||
|
||||
Enable dry run mode to verify that bulk actions can be applied to specified rules. Certain rules, such as prebuilt Elastic rules on a Basic subscription, can’t be edited and will return errors in the request response. Error details will contain an explanation, the rule name and/or ID, and additional troubleshooting information.
|
||||
|
||||
To enable dry run mode on a request, add the query parameter `dry_run=true` to the end of the request URL. Rules specified in the request will be temporarily updated. These updates won’t be written to Elasticsearch.
|
||||
> info
|
||||
> Dry run mode is not supported for the `export` bulk action. A 400 error will be returned in the request response.
|
||||
|
||||
*/
|
||||
dry_run: BooleanFromString.optional(),
|
||||
});
|
||||
export type PerformRulesBulkActionRequestQueryInput = z.input<
|
||||
|
|
|
|||
|
|
@ -9,13 +9,25 @@ paths:
|
|||
x-codegen-enabled: true
|
||||
operationId: PerformRulesBulkAction
|
||||
summary: Apply a bulk action to detection rules
|
||||
description: Apply a bulk action, such as bulk edit, duplicate, or delete, to multiple detection rules. The bulk action is applied to all rules that match the query or to the rules listed by their IDs.
|
||||
description: |
|
||||
Apply a bulk action, such as bulk edit, duplicate, or delete, to multiple detection rules. The bulk action is applied to all rules that match the query or to the rules listed by their IDs.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
tags:
|
||||
- Bulk API
|
||||
parameters:
|
||||
- name: dry_run
|
||||
in: query
|
||||
description: Enables dry run mode for the request call.
|
||||
description: |
|
||||
Enables dry run mode for the request call.
|
||||
|
||||
Enable dry run mode to verify that bulk actions can be applied to specified rules. Certain rules, such as prebuilt Elastic rules on a Basic subscription, can’t be edited and will return errors in the request response. Error details will contain an explanation, the rule name and/or ID, and additional troubleshooting information.
|
||||
|
||||
To enable dry run mode on a request, add the query parameter `dry_run=true` to the end of the request URL. Rules specified in the request will be temporarily updated. These updates won’t be written to Elasticsearch.
|
||||
> info
|
||||
> Dry run mode is not supported for the `export` bulk action. A 400 error will be returned in the request response.
|
||||
required: false
|
||||
schema:
|
||||
type: boolean
|
||||
|
|
@ -31,6 +43,90 @@ paths:
|
|||
- $ref: '#/components/schemas/BulkDuplicateRules'
|
||||
- $ref: '#/components/schemas/BulkManualRuleRun'
|
||||
- $ref: '#/components/schemas/BulkEditRules'
|
||||
examples:
|
||||
example1:
|
||||
summary: Enable all rules with the test tag
|
||||
description: The following request activates all rules with the test tag
|
||||
value:
|
||||
query: 'alert.attributes.tags: "test"'
|
||||
action: 'enable'
|
||||
example2:
|
||||
summary: Enable a specific rule by ID
|
||||
description: The following request enables the rule with the specified ID.
|
||||
value:
|
||||
action: 'enable'
|
||||
ids:
|
||||
- '748694f0-6977-4ea5-8384-cd2e39730779'
|
||||
example3:
|
||||
summary: Disable a specific rule by ID
|
||||
description: The following request disables the rule with the specified ID.
|
||||
value:
|
||||
action: 'disable'
|
||||
ids:
|
||||
- '748694f0-6977-4ea5-8384-cd2e39730779'
|
||||
example4:
|
||||
summary: Add tags to rules
|
||||
description: The following request adds tags tag-1 and tag-2 to the rules that have the IDs sent in the payload
|
||||
value:
|
||||
ids:
|
||||
- '8bc7dad0-9320-11ec-9265-8b772383a08d'
|
||||
- '8e5c1a40-9320-11ec-9265-8b772383a08d'
|
||||
action: 'edit'
|
||||
edit:
|
||||
- type: 'add_tags'
|
||||
value:
|
||||
- 'tag-1'
|
||||
- 'tag-2'
|
||||
example5:
|
||||
summary: Dry run - Validate add_index_patterns bulk action
|
||||
description: The following request will validate that the add_index_patterns bulk action can be successfully applied to three rules. The dry_run parameter is specified in query parameters, e.g. POST api/detection_engine/rules/_bulk_action?dry_run=true
|
||||
value:
|
||||
action: 'edit'
|
||||
edit:
|
||||
- value:
|
||||
- 'test-*'
|
||||
type: 'add_index_patterns'
|
||||
ids:
|
||||
- '81aa0480-06af-11ed-94fb-dd1a0597d8d2'
|
||||
- 'dc015d10-0831-11ed-ac8b-05a222bd8d4a'
|
||||
- 'de8f5af0-0831-11ed-ac8b-05a222bd8d4a'
|
||||
example6:
|
||||
summary: Duplicate rules with specific IDs
|
||||
description: The following request duplicates rules with the specified IDs, including exceptions but not expired exceptions.
|
||||
value:
|
||||
action: 'duplicate'
|
||||
ids:
|
||||
- '748694f0-6977-4ea5-8384-cd2e39730779'
|
||||
- '461a4c22-416e-4009-a9a7-cf79656454bf'
|
||||
duplicate:
|
||||
include_exceptions: true
|
||||
include_expired_exceptions: false
|
||||
example7:
|
||||
summary: Delete a specific rule by ID
|
||||
description: The following request deletes the rule with the specified ID.
|
||||
value:
|
||||
action: 'delete'
|
||||
ids:
|
||||
- 'cf4abfd1-7c37-4519-ab0f-5ea5c75fac60'
|
||||
example8:
|
||||
summary: Run a specific rule by ID
|
||||
description: The following request runs the rule with the specified ID within the given date range.
|
||||
value:
|
||||
action: 'run'
|
||||
ids:
|
||||
- '748694f0-6977-4ea5-8384-cd2e39730779'
|
||||
run:
|
||||
start_date: '2025-03-01T00:00:00.000Z'
|
||||
end_date: '2025-03-10T23:59:59.999Z'
|
||||
example9:
|
||||
summary: Export specific rules by ID
|
||||
description: The following request exports the rules with the specified IDs.
|
||||
value:
|
||||
action: 'export'
|
||||
ids:
|
||||
- '748694f0-6977-4ea5-8384-cd2e39730779'
|
||||
- '13199674-aff1-418a-9e93-04f585fe36d1'
|
||||
|
||||
responses:
|
||||
200:
|
||||
description: OK
|
||||
|
|
@ -40,7 +136,213 @@ paths:
|
|||
oneOf:
|
||||
- $ref: '#/components/schemas/BulkEditActionResponse'
|
||||
- $ref: '#/components/schemas/BulkExportActionResponse'
|
||||
|
||||
examples:
|
||||
example1:
|
||||
summary: Successful response
|
||||
description: In this response one rule was updated and one was skipped. Objects returned in attributes.results.skipped will only include rules' id, name, and skip_reason.
|
||||
value:
|
||||
success: true
|
||||
rules_count: 1
|
||||
attributes:
|
||||
results:
|
||||
updated:
|
||||
- id: '8bc7dad0-9320-11ec-9265-8b772383a08d'
|
||||
updated_at: '2022-02-21T17:05:50.883Z'
|
||||
updated_by: 'elastic'
|
||||
created_at: '2022-02-21T14:14:13.801Z'
|
||||
created_by: 'elastic'
|
||||
name: 'DNS Tunneling [Duplicate]'
|
||||
tags:
|
||||
- 'Elastic'
|
||||
- 'Network'
|
||||
- 'Threat Detection'
|
||||
- 'ML'
|
||||
interval: '15m'
|
||||
enabled: true
|
||||
description: 'A machine learning job detected unusually large numbers of DNS queries for a single top-level DNS domain, which is often used for DNS tunneling. DNS tunneling can be used for command-and-control, persistence, or data exfiltration activity. For example, dnscat tends to generate many DNS questions for a top-level domain as it uses the DNS protocol to tunnel data.'
|
||||
risk_score: 21
|
||||
severity: 'low'
|
||||
license: 'Elastic License v2'
|
||||
author:
|
||||
- 'Elastic'
|
||||
false_positives:
|
||||
- 'DNS domains that use large numbers of child domains, such as software or content distribution networks, can trigger this alert and such parent domains can be excluded.'
|
||||
from: 'now-45m'
|
||||
rule_id: '7289bf08-4e91-4c70-bf01-e04c4c5d7756'
|
||||
max_signals: 100
|
||||
risk_score_mapping: []
|
||||
severity_mapping: []
|
||||
threat: []
|
||||
to: 'now'
|
||||
references:
|
||||
- 'https://www.elastic.co/guide/en/security/current/prebuilt-ml-jobs.html'
|
||||
version: 6
|
||||
exceptions_list: []
|
||||
immutable: false
|
||||
related_integrations: []
|
||||
required_fields: []
|
||||
setup: ''
|
||||
type: 'machine_learning'
|
||||
anomaly_threshold: 50
|
||||
machine_learning_job_id:
|
||||
- 'packetbeat_dns_tunneling'
|
||||
execution_summary:
|
||||
last_execution:
|
||||
date: '2022-03-23T16:06:12.787Z'
|
||||
status: 'partial failure'
|
||||
status_order: 20
|
||||
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:
|
||||
total_search_duration_ms: 135
|
||||
total_indexing_duration_ms: 15
|
||||
execution_gap_duration_s: 0
|
||||
created: []
|
||||
deleted: []
|
||||
skipped:
|
||||
- id: '51658332-a15e-4c9e-912a-67214e2e2359'
|
||||
name: 'Skipped rule'
|
||||
skip_reason: 'RULE_NOT_MODIFIED'
|
||||
summary:
|
||||
failed: 0
|
||||
skipped: 1
|
||||
succeeded: 1
|
||||
total: 2
|
||||
example2:
|
||||
summary: Partial failure
|
||||
description: If processing of any rule fails, a partial error outputs the ID and/or name of the affected rule and the corresponding error, as well as successfully processed rules (in the same format as a successful 200 request).
|
||||
value:
|
||||
value:
|
||||
success: false
|
||||
status_code: 500
|
||||
message: 'Bulk edit partially failed'
|
||||
rules_count: 2
|
||||
attributes:
|
||||
results:
|
||||
updated:
|
||||
- id: '8e5c1a40-9320-11ec-9265-8b772383a08d'
|
||||
updated_at: '2022-02-21T16:56:22.818Z'
|
||||
updated_by: 'elastic'
|
||||
created_at: '2022-02-21T14:14:17.883Z'
|
||||
created_by: 'elastic'
|
||||
name: 'External Alerts [Duplicate]'
|
||||
tags:
|
||||
- 'Elastic'
|
||||
- 'Network'
|
||||
- 'Windows'
|
||||
- 'APM'
|
||||
- 'macOS'
|
||||
- 'Linux'
|
||||
interval: '5m'
|
||||
enabled: true
|
||||
description: 'Generates a detection alert for each external alert written to the configured indices. Enabling this rule allows you to immediately begin investigating external alerts in the app.'
|
||||
risk_score: 47
|
||||
severity: 'medium'
|
||||
license: 'Elastic License v2'
|
||||
rule_name_override: 'message'
|
||||
timestamp_override: 'event.ingested'
|
||||
author:
|
||||
- 'Elastic'
|
||||
false_positives: []
|
||||
from: 'now-6m'
|
||||
rule_id: '941faf98-0cdc-4569-b16d-4af962914d61'
|
||||
max_signals: 10000
|
||||
risk_score_mapping:
|
||||
- field: 'event.risk_score'
|
||||
value: ''
|
||||
operator: 'equals'
|
||||
severity_mapping:
|
||||
- severity: 'low'
|
||||
field: 'event.severity'
|
||||
value: '21'
|
||||
operator: 'equals'
|
||||
- severity: 'medium'
|
||||
field: 'event.severity'
|
||||
value: '47'
|
||||
operator: 'equals'
|
||||
- severity: 'high'
|
||||
field: 'event.severity'
|
||||
value: '73'
|
||||
operator: 'equals'
|
||||
- severity: 'critical'
|
||||
field: 'event.severity'
|
||||
value: '99'
|
||||
operator: 'equals'
|
||||
threat: []
|
||||
to: 'now'
|
||||
references: []
|
||||
version: 5
|
||||
exceptions_list: []
|
||||
immutable: false
|
||||
related_integrations: []
|
||||
required_fields: []
|
||||
setup: ''
|
||||
type: 'query'
|
||||
language: 'kuery'
|
||||
index:
|
||||
- 'apm-*-transaction*'
|
||||
- 'traces-apm*'
|
||||
- 'auditbeat-*'
|
||||
- 'filebeat-*'
|
||||
- 'logs-*'
|
||||
- 'packetbeat-*'
|
||||
- 'winlogbeat-*'
|
||||
- 'added-by-id-*'
|
||||
query: "event.kind:alert and not event.module:(endgame or endpoint)\n"
|
||||
actions: []
|
||||
execution_summary:
|
||||
last_execution:
|
||||
date: '2022-03-23T16:06:12.787Z'
|
||||
status: 'partial failure'
|
||||
status_order: 20
|
||||
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:
|
||||
total_search_duration_ms: 135
|
||||
total_indexing_duration_ms: 15
|
||||
execution_gap_duration_s: 0
|
||||
created: []
|
||||
deleted: []
|
||||
skipped: []
|
||||
summary:
|
||||
failed: 1
|
||||
succeeded: 1
|
||||
skipped: 0
|
||||
total: 2
|
||||
errors:
|
||||
- message: "Index patterns can't be added. Machine learning rule doesn't have index patterns property"
|
||||
status_code: 500
|
||||
rules:
|
||||
- id: '8bc7dad0-9320-11ec-9265-8b772383a08d'
|
||||
name: 'DNS Tunneling [Duplicate]'
|
||||
example3:
|
||||
summary: Dry run
|
||||
description: The attributes.errors section of the response shows that two rules failed to update and one succeeded. The same results would be returned if you ran the request without dry run mode enabled. Notice that there are no arrays in attributes.results. In dry run mode, rule updates are not applied and saved to Elasticsearch, so the endpoint wouldn’t return results for rules that have been updated, created, or deleted.
|
||||
value:
|
||||
message: 'Bulk edit partially failed'
|
||||
status_code: 500
|
||||
attributes:
|
||||
errors:
|
||||
- message: "Elastic rule can't be edited"
|
||||
status_code: 500
|
||||
err_code: 'IMMUTABLE'
|
||||
rules:
|
||||
- id: '81aa0480-06af-11ed-94fb-dd1a0597d8d2'
|
||||
name: 'Unusual AWS Command for a User'
|
||||
- message: "Machine learning rule doesn't have index patterns"
|
||||
status_code: 500
|
||||
err_code: 'MACHINE_LEARNING_INDEX_PATTERN'
|
||||
rules:
|
||||
- id: 'dc015d10-0831-11ed-ac8b-05a222bd8d4a'
|
||||
name: 'Suspicious Powershell Script [Duplicate]'
|
||||
results:
|
||||
updated: []
|
||||
created: []
|
||||
deleted: []
|
||||
skipped: []
|
||||
summary:
|
||||
failed: 2
|
||||
succeeded: 1
|
||||
skipped: 0
|
||||
total: 3
|
||||
components:
|
||||
schemas:
|
||||
BulkEditSkipReason:
|
||||
|
|
@ -127,6 +429,7 @@ components:
|
|||
|
||||
BulkEditActionSummary:
|
||||
type: object
|
||||
description: A rule can only be skipped when the bulk action to be performed on it results in nothing being done. For example, if the `edit` action is used to add a tag to a rule that already has that tag, or to delete an index pattern that is not specified in a rule. Objects returned in `attributes.results.skipped` will only include rules' `id`, `name`, and `skip_reason`.
|
||||
properties:
|
||||
failed:
|
||||
type: integer
|
||||
|
|
@ -179,10 +482,10 @@ components:
|
|||
properties:
|
||||
query:
|
||||
type: string
|
||||
description: Query to filter rules
|
||||
description: Query to filter rules.
|
||||
ids:
|
||||
type: array
|
||||
description: Array of rule IDs
|
||||
description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined.
|
||||
minItems: 1
|
||||
items:
|
||||
type: string
|
||||
|
|
@ -241,6 +544,7 @@ components:
|
|||
enum: [duplicate]
|
||||
duplicate:
|
||||
type: object
|
||||
description: Duplicate object that describes applying an update action.
|
||||
properties:
|
||||
include_exceptions:
|
||||
type: boolean
|
||||
|
|
@ -264,6 +568,7 @@ components:
|
|||
enum: [run]
|
||||
run:
|
||||
type: object
|
||||
description: Object that describes applying a manual rule run action.
|
||||
properties:
|
||||
start_date:
|
||||
type: string
|
||||
|
|
@ -279,7 +584,11 @@ components:
|
|||
|
||||
ThrottleForBulkActions:
|
||||
type: string
|
||||
description: "The condition for throttling the notification: 'rule', 'no_actions', or time duration"
|
||||
description: |
|
||||
Defines the maximum interval in which a rule’s actions are executed.
|
||||
> info
|
||||
> The rule level `throttle` field is deprecated in Elastic Security 8.8 and will remain active for at least the next 12 months.
|
||||
> In Elastic Security 8.8 and later, you can use the `frequency` field to define frequencies for individual actions. Actions without frequencies will acquire a converted version of the rule’s `throttle` field. In the response, the converted `throttle` setting appears in the individual actions' `frequency` field.
|
||||
enum:
|
||||
- rule
|
||||
- 1h
|
||||
|
|
|
|||
|
|
@ -9,15 +9,306 @@ paths:
|
|||
x-codegen-enabled: true
|
||||
operationId: CreateRule
|
||||
summary: Create a detection rule
|
||||
description: Create a new detection rule.
|
||||
tags:
|
||||
- Rules API
|
||||
description: |
|
||||
Create a new detection rule.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
|
||||
You can create the following types of rules:
|
||||
|
||||
* **Custom query**: Searches the defined indices and creates an alert when a document matches the rule's KQL query.
|
||||
* **Event correlation**: Searches the defined indices and creates an alert when results match an [Event Query Language (EQL)](https://www.elastic.co/guide/en/elasticsearch/reference/current/eql.html) query.
|
||||
* **Threshold**: Searches the defined indices and creates an alert when the number of times the specified field's value meets the threshold during a single execution. When there are multiple values that meet the threshold, an alert is generated for each value.
|
||||
For example, if the threshold `field` is `source.ip` and its `value` is `10`, an alert is generated for every source IP address that appears in at least 10 of the rule's search results. If you're interested, see [Terms Aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html) for more information.
|
||||
* **Indicator match**: Creates an alert when fields match values defined in the specified [Elasticsearch index](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html). For example, you can create an index for IP addresses and use this index to create an alert whenever an event's `destination.ip` equals a value in the index. The index's field mappings should be [ECS-compliant](https://www.elastic.co/guide/en/ecs/current/ecs-reference.html).
|
||||
* **New terms**: Generates an alert for each new term detected in source documents within a specified time range.
|
||||
* **ES|QL**: Uses [Elasticsearch Query Language (ES|QL)](https://www.elastic.co/guide/en/elasticsearch/reference/current/esql.html) to find events and aggregate search results.
|
||||
* **Machine learning rules**: Creates an alert when a machine learning job discovers an anomaly above the defined threshold.
|
||||
> info
|
||||
> To create machine learning rules, you must have the [appropriate license](https://www.elastic.co/subscriptions) or use a [cloud deployment](https://cloud.elastic.co/registration). Additionally, for the machine learning rule to function correctly, the associated machine learning job must be running.
|
||||
|
||||
To retrieve machine learning job IDs, which are required to create machine learning jobs, call the [Elasticsearch Get jobs API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-job.html). Machine learning jobs that contain `siem` in the `groups` field can be used to create rules:
|
||||
|
||||
```json
|
||||
...
|
||||
"job_id": "linux_anomalous_network_activity_ecs",
|
||||
"job_type": "anomaly_detector",
|
||||
"job_version": "7.7.0",
|
||||
"groups": [
|
||||
"auditbeat",
|
||||
"process",
|
||||
"siem"
|
||||
],
|
||||
...
|
||||
```
|
||||
|
||||
Additionally, you can set up notifications for when rules create alerts. The notifications use the [Alerting and Actions framework](https://www.elastic.co/guide/en/kibana/current/alerting-getting-started.html). Each action type requires a connector. Connectors store the information required to send notifications via external systems. The following connector types are supported for rule notifications:
|
||||
|
||||
* Slack
|
||||
* Email
|
||||
* PagerDuty
|
||||
* Webhook
|
||||
* Microsoft Teams
|
||||
* IBM Resilient
|
||||
* Jira
|
||||
* ServiceNow ITSM
|
||||
> info
|
||||
> For more information on PagerDuty fields, see [Send a v2 Event](https://developer.pagerduty.com/docs/events-api-v2/trigger-events/).
|
||||
|
||||
To retrieve connector IDs, which are required to configure rule notifications, call the [Find objects API](https://www.elastic.co/guide/en/kibana/current/saved-objects-api-find.html) with `"type": "action"` in the request payload.
|
||||
|
||||
For detailed information on Kibana actions and alerting, and additional API calls, see:
|
||||
|
||||
* [Alerting API](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-alerting)
|
||||
* [Alerting and Actions framework](https://www.elastic.co/guide/en/kibana/current/alerting-getting-started.html)
|
||||
* [Connectors API](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-connectors)
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../../../model/rule_schema/rule_schemas.schema.yaml#/components/schemas/RuleCreateProps'
|
||||
examples:
|
||||
example1:
|
||||
summary: Query rule
|
||||
description: Query rule that searches for processes started by MS Office
|
||||
value:
|
||||
rule_id: 'process_started_by_ms_office_program'
|
||||
risk_score: 50
|
||||
description: 'Process started by MS Office program - possible payload'
|
||||
interval: '1h'
|
||||
name: 'MS Office child process'
|
||||
severity: 'low'
|
||||
tags:
|
||||
- 'child process'
|
||||
- 'ms office'
|
||||
type: 'query'
|
||||
from: 'now-70m'
|
||||
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'
|
||||
language: 'kuery'
|
||||
filters:
|
||||
- query:
|
||||
match:
|
||||
event.action:
|
||||
query: 'Process Create (rule: ProcessCreate)'
|
||||
type: 'phrase'
|
||||
required_fields:
|
||||
- name: 'process.parent.name'
|
||||
type: 'keyword'
|
||||
related_integrations:
|
||||
- package: 'o365'
|
||||
version: '^2.3.2'
|
||||
enabled: false
|
||||
example2:
|
||||
summary: Threshold rule
|
||||
description: Threshold rule that detects multiple failed login attempts to a Windows host from the same external source IP address
|
||||
value:
|
||||
description: 'Detects when there are 20 or more failed login attempts from the same IP address with a 2 minute time frame.'
|
||||
enabled: true
|
||||
exceptions_list:
|
||||
- id: 'int-ips'
|
||||
namespace_type: 'single'
|
||||
type: 'detection'
|
||||
from: 'now-180s'
|
||||
index:
|
||||
- 'winlogbeat-*'
|
||||
interval: '2m'
|
||||
name: 'Windows server prml-19'
|
||||
query: 'host.name:prml-19 and event.category:authentication and event.outcome:failure'
|
||||
required_fields:
|
||||
- name: 'source.ip'
|
||||
type: 'ip'
|
||||
risk_score: 30
|
||||
rule_id: 'liv-win-ser-logins'
|
||||
severity: 'low'
|
||||
severity_mapping:
|
||||
- field: 'source.geo.city_name'
|
||||
operator: 'equals'
|
||||
severity: 'low'
|
||||
value: 'Manchester'
|
||||
- field: 'source.geo.city_name'
|
||||
operator: 'equals'
|
||||
severity: 'medium'
|
||||
value: 'London'
|
||||
- field: 'source.geo.city_name'
|
||||
operator: 'equals'
|
||||
severity: 'high'
|
||||
value: 'Birmingham'
|
||||
- field: 'source.geo.city_name'
|
||||
operator: 'equals'
|
||||
severity: 'critical'
|
||||
value: 'Wallingford'
|
||||
tags:
|
||||
- 'Brute force'
|
||||
threshold:
|
||||
field: 'source.ip'
|
||||
value: 20
|
||||
type: 'threshold'
|
||||
example3:
|
||||
summary: Machine learning rule
|
||||
description: Machine learning rule that creates alerts, and sends Slack notifications, when the linux_anomalous_network_activity_ecs machine learning job discovers anomalies with a threshold of 70 or above.
|
||||
value:
|
||||
anomaly_threshold: 70
|
||||
rule_id: 'ml_linux_network_high_threshold'
|
||||
risk_score: 70
|
||||
machine_learning_job_id: 'linux_anomalous_network_activity_ecs'
|
||||
description: 'Generates alerts when the job discovers anomalies over 70'
|
||||
interval: '5m'
|
||||
name: 'Anomalous Linux network activity'
|
||||
note: 'Shut down the internet.'
|
||||
setup: 'This rule requires data coming in from Elastic Defend.'
|
||||
severity: 'high'
|
||||
tags:
|
||||
- 'machine learning'
|
||||
- 'Linux'
|
||||
type: 'machine_learning'
|
||||
from: 'now-6m'
|
||||
enabled: true
|
||||
actions:
|
||||
- action_type_id: '.slack'
|
||||
group: 'default'
|
||||
id: '5ad22cd5-5e6e-4c6c-a81a-54b626a4cec5'
|
||||
params:
|
||||
message: 'Urgent: {{context.rule.description}}'
|
||||
example4:
|
||||
summary: EQL rule
|
||||
description: Event correlation rule that creates alerts when the Windows rundll32.exe process makes unusual network connections
|
||||
value:
|
||||
rule_id: 'eql-outbound-rundll32-connections'
|
||||
risk_score: 21
|
||||
description: 'Unusual rundll32.exe network connection'
|
||||
name: 'rundll32.exe network connection'
|
||||
severity: 'low'
|
||||
tags:
|
||||
- 'EQL'
|
||||
- 'Windows'
|
||||
- 'rundll32.exe'
|
||||
type: 'eql'
|
||||
language: 'eql'
|
||||
query: 'sequence by process.entity_id with maxspan=2h [process where event.type in ("start", "process_started") and (process.name == "rundll32.exe" or process.pe.original_file_name == "rundll32.exe") and ((process.args == "rundll32.exe" and process.args_count == 1) or (process.args != "rundll32.exe" and process.args_count == 0))] [network where event.type == "connection" and (process.name == "rundll32.exe" or process.pe.original_file_name == "rundll32.exe")]'
|
||||
required_fields:
|
||||
- name: 'event.type'
|
||||
type: 'keyword'
|
||||
- name: 'process.args'
|
||||
type: 'keyword'
|
||||
- name: 'process.args_count'
|
||||
type: 'long'
|
||||
- name: 'process.entity_id'
|
||||
type: 'keyword'
|
||||
- name: 'process.name'
|
||||
type: 'keyword'
|
||||
- name: 'process.pe.original_file_name'
|
||||
type: 'keyword'
|
||||
example5:
|
||||
summary: Indicator match rule
|
||||
description: |
|
||||
Indicator match rule that creates an alert when one of the following is true: The event's destination IP address and port number matches destination IP and port values in the threat_index index; The event's source IP address matches a host IP address value in the threat_index index.
|
||||
value:
|
||||
type: 'threat_match'
|
||||
actions: []
|
||||
index:
|
||||
- 'packetbeat-*'
|
||||
query: 'destination.ip:* or host.ip:*'
|
||||
threat_index:
|
||||
- 'ip-threat-list'
|
||||
threat_query: '*:*'
|
||||
threat_mapping:
|
||||
- entries:
|
||||
- field: 'destination.ip'
|
||||
type: 'mapping'
|
||||
value: 'destination.ip'
|
||||
- field: 'destination.port'
|
||||
type: 'mapping'
|
||||
value: 'destination.port'
|
||||
- entries:
|
||||
- field: 'source.ip'
|
||||
type: 'mapping'
|
||||
value: 'host.ip'
|
||||
required_fields:
|
||||
- name: 'destination.ip'
|
||||
type: 'ip'
|
||||
- name: 'destination.port'
|
||||
type: 'long'
|
||||
- name: 'host.ip'
|
||||
type: 'ip'
|
||||
risk_score: 50
|
||||
severity: 'medium'
|
||||
name: 'Bad IP threat match'
|
||||
description: 'Checks for bad IP addresses listed in the ip-threat-list index'
|
||||
example6:
|
||||
summary: New terms rule
|
||||
description: New terms rule that creates alerts a new IP address is detected for a user
|
||||
value:
|
||||
risk_score: 21
|
||||
description: 'Detects a user associated with a new IP address'
|
||||
name: 'New User IP Detected'
|
||||
severity: 'medium'
|
||||
type: 'new_terms'
|
||||
language: 'kuery'
|
||||
query: '*'
|
||||
new_terms_fields:
|
||||
- 'user.id'
|
||||
- 'source.ip'
|
||||
history_window_start: 'now-30d'
|
||||
index:
|
||||
- 'auditbeat*'
|
||||
required_fields:
|
||||
- name: 'user.id'
|
||||
type: 'keyword'
|
||||
- name: 'source.ip'
|
||||
type: 'ip'
|
||||
example7:
|
||||
summary: Esql rule
|
||||
description: esql rule that creates alerts from events that match an Excel parent process
|
||||
value:
|
||||
type: 'esql'
|
||||
language: 'esql'
|
||||
query: 'from auditbeat-8.10.2 METADATA _id, _version, _index | where process.parent.name == "EXCEL.EXE"'
|
||||
name: 'Find Excel events'
|
||||
description: 'Find Excel events'
|
||||
tags: []
|
||||
interval: '5m'
|
||||
from: 'now-360s'
|
||||
to: 'now'
|
||||
enabled: false
|
||||
risk_score: 21
|
||||
severity: 'low'
|
||||
required_fields:
|
||||
- name: 'process.parent.name'
|
||||
type: 'keyword'
|
||||
example8:
|
||||
summary: Query rule 2
|
||||
description: Query rule that searches for processes started by MS Office and suppresses alerts by the process.parent.name field within a 5-hour time period
|
||||
value:
|
||||
rule_id: 'process_started_by_ms_office_program'
|
||||
risk_score: 50
|
||||
description: 'Process started by MS Office program - possible payload'
|
||||
interval: '1h'
|
||||
name: 'MS Office child process'
|
||||
severity: 'low'
|
||||
tags:
|
||||
- 'child process'
|
||||
- 'ms office'
|
||||
type: 'query'
|
||||
from: 'now-70m'
|
||||
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'
|
||||
language: 'kuery'
|
||||
filters:
|
||||
- query:
|
||||
match:
|
||||
event.action:
|
||||
query: 'Process Create (rule: ProcessCreate)'
|
||||
type: 'phrase'
|
||||
enabled: false
|
||||
alert_suppression:
|
||||
duration:
|
||||
unit: 'h'
|
||||
value: 5
|
||||
group_by:
|
||||
- 'process.parent.name'
|
||||
missing_fields_strategy: 'suppress'
|
||||
responses:
|
||||
200:
|
||||
description: Indicates a successful call.
|
||||
|
|
@ -25,3 +316,378 @@ paths:
|
|||
application/json:
|
||||
schema:
|
||||
$ref: '../../../model/rule_schema/rule_schemas.schema.yaml#/components/schemas/RuleResponse'
|
||||
examples:
|
||||
example1:
|
||||
summary: Query rule response
|
||||
description: Example response for a query rule
|
||||
value:
|
||||
created_at: '2020-04-07T14:51:09.755Z'
|
||||
updated_at: '2020-04-07T14:51:09.970Z'
|
||||
created_by: 'elastic'
|
||||
description: 'Process started by MS Office program - possible payload'
|
||||
enabled: false
|
||||
false_positives: []
|
||||
from: 'now-70m'
|
||||
id: '6541b99a-dee9-4f6d-a86d-dbd1869d73b1'
|
||||
immutable: false
|
||||
interval: '1h'
|
||||
rule_id: 'process_started_by_ms_office_program'
|
||||
max_signals: 100
|
||||
risk_score: 50
|
||||
name: 'MS Office child process'
|
||||
references: []
|
||||
severity: 'low'
|
||||
updated_by: 'elastic'
|
||||
tags:
|
||||
- 'child process'
|
||||
- 'ms office'
|
||||
to: 'now'
|
||||
type: 'query'
|
||||
threat: []
|
||||
version: 1
|
||||
actions: []
|
||||
filters:
|
||||
- query:
|
||||
match:
|
||||
event.action:
|
||||
query: 'Process Create (rule: ProcessCreate)'
|
||||
type: 'phrase'
|
||||
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'
|
||||
language: 'kuery'
|
||||
related_integrations:
|
||||
- package: 'o365'
|
||||
version: '^2.3.2'
|
||||
- package: 'azure'
|
||||
version: '^1.11.4'
|
||||
integration: 'graphactivitylogs'
|
||||
required_fields:
|
||||
- name: 'process.parent.name'
|
||||
type: 'keyword'
|
||||
ecs: true
|
||||
setup: ''
|
||||
example2:
|
||||
summary: Machine learning response
|
||||
description: Example response for a machine learning job rule
|
||||
value:
|
||||
created_at: '2020-04-07T14:45:15.679Z'
|
||||
updated_at: '2020-04-07T14:45:15.892Z'
|
||||
created_by: 'elastic'
|
||||
description: 'Generates alerts when the job discovers anomalies over 70'
|
||||
enabled: true
|
||||
false_positives: []
|
||||
from: 'now-6m'
|
||||
id: '83876f66-3a57-4a99-bf37-416494c80f3b'
|
||||
immutable: false
|
||||
interval: '5m'
|
||||
rule_id: 'ml_linux_network_high_threshold'
|
||||
max_signals: 100
|
||||
risk_score: 70
|
||||
name: 'Anomalous Linux network activity'
|
||||
references: []
|
||||
severity: 'high'
|
||||
updated_by: 'elastic'
|
||||
tags:
|
||||
- 'machine learning'
|
||||
- 'Linux'
|
||||
to: 'now'
|
||||
type: 'machine_learning'
|
||||
threat: []
|
||||
version: 1
|
||||
actions:
|
||||
- action_type_id: '.slack'
|
||||
group: 'default'
|
||||
id: '5ad22cd5-5e6e-4c6c-a81a-54b626a4cec5'
|
||||
params:
|
||||
message: 'Urgent: {{context.rule.description}}'
|
||||
frequency:
|
||||
summary: true
|
||||
notifyWhen: 'onActiveAlert'
|
||||
throttle: null
|
||||
note: 'Shut down the internet.'
|
||||
status: 'going to run'
|
||||
status_date: '2020-04-07T14:45:21.685Z'
|
||||
anomaly_threshold: 70
|
||||
machine_learning_job_id: 'linux_anomalous_network_activity_ecs'
|
||||
related_integrations: []
|
||||
required_fields: []
|
||||
setup: ''
|
||||
example3:
|
||||
summary: Threshold rule response
|
||||
description: Example response for a threshold rule
|
||||
value:
|
||||
author: []
|
||||
created_at: '2020-07-22T10:27:23.486Z'
|
||||
updated_at: '2020-07-22T10:27:23.673Z'
|
||||
created_by: 'elastic'
|
||||
description: 'Detects when there are 20 or more failed login attempts from the same IP address with a 2 minute time frame.'
|
||||
enabled: true
|
||||
false_positives: []
|
||||
from: 'now-180s'
|
||||
id: '15dbde26-b627-4d74-bb1f-a5e0ed9e4993'
|
||||
immutable: false
|
||||
interval: '2m'
|
||||
rule_id: 'liv-win-ser-logins'
|
||||
max_signals: 100
|
||||
risk_score: 30
|
||||
risk_score_mapping: []
|
||||
name: 'Windows server prml-19'
|
||||
references: []
|
||||
severity: 'low'
|
||||
severity_mapping:
|
||||
- field: 'source.geo.city_name'
|
||||
operator: 'equals'
|
||||
severity: 'low'
|
||||
value: 'Manchester'
|
||||
- field: 'source.geo.city_name'
|
||||
operator: 'equals'
|
||||
severity: 'medium'
|
||||
value: 'London'
|
||||
- field: 'source.geo.city_name'
|
||||
operator: 'equals'
|
||||
severity: 'high'
|
||||
value: 'Birmingham'
|
||||
- field: 'source.geo.city_name'
|
||||
operator: 'equals'
|
||||
severity: 'critical'
|
||||
value: 'Wallingford'
|
||||
updated_by: 'elastic'
|
||||
tags:
|
||||
- 'Brute force'
|
||||
to: 'now'
|
||||
type: 'threshold'
|
||||
threat: []
|
||||
version: 1
|
||||
exceptions_list:
|
||||
- id: 'int-ips'
|
||||
namespace_type: 'single'
|
||||
type: 'detection'
|
||||
actions: []
|
||||
index:
|
||||
- 'winlogbeat-*'
|
||||
query: 'host.name:prml-19 and event.category:authentication and event.outcome:failure'
|
||||
language: 'kuery'
|
||||
threshold:
|
||||
field: 'source.ip'
|
||||
value: 20
|
||||
related_integrations:
|
||||
- package: 'o365'
|
||||
version: '^2.3.2'
|
||||
required_fields:
|
||||
- name: 'source.ip'
|
||||
type: 'ip'
|
||||
ecs: true
|
||||
setup: ''
|
||||
example4:
|
||||
summary: EQL rule response
|
||||
description: Example response for an EQL rule
|
||||
value:
|
||||
author: []
|
||||
created_at: '2020-10-05T09:06:16.392Z'
|
||||
updated_at: '2020-10-05T09:06:16.403Z'
|
||||
created_by: 'elastic'
|
||||
description: 'Unusual rundll32.exe network connection'
|
||||
enabled: true
|
||||
false_positives: []
|
||||
from: 'now-6m'
|
||||
id: '93808cae-b05b-4dc9-8479-73574b50f8b1'
|
||||
immutable: false
|
||||
interval: '5m'
|
||||
rule_id: 'eql-outbound-rundll32-connections'
|
||||
max_signals: 100
|
||||
risk_score: 21
|
||||
risk_score_mapping: []
|
||||
name: 'rundll32.exe network connection'
|
||||
references: []
|
||||
severity: 'low'
|
||||
severity_mapping: []
|
||||
updated_by: 'elastic'
|
||||
tags:
|
||||
- 'EQL'
|
||||
- 'Windows'
|
||||
- 'rundll32.exe'
|
||||
to: 'now'
|
||||
type: 'eql'
|
||||
threat: []
|
||||
version: 1
|
||||
exceptions_list: []
|
||||
throttle: 'no_actions'
|
||||
query: 'sequence by process.entity_id with maxspan=2h [process where event.type in ("start", "process_started") and (process.name == "rundll32.exe" or process.pe.original_file_name == "rundll32.exe") and ((process.args == "rundll32.exe" and process.args_count == 1) or (process.args != "rundll32.exe" and process.args_count == 0))] [network where event.type == "connection" and (process.name == "rundll32.exe" or process.pe.original_file_name == "rundll32.exe")]'
|
||||
language: 'eql'
|
||||
related_integrations:
|
||||
- package: 'o365'
|
||||
version: '^2.3.2'
|
||||
required_fields:
|
||||
- name: 'event.type'
|
||||
type: 'keyword'
|
||||
ecs: true
|
||||
- name: 'process.args'
|
||||
type: 'keyword'
|
||||
ecs: true
|
||||
- name: 'process.args_count'
|
||||
type: 'long'
|
||||
ecs: true
|
||||
- name: 'process.entity_id'
|
||||
type: 'keyword'
|
||||
ecs: true
|
||||
- name: 'process.name'
|
||||
type: 'keyword'
|
||||
ecs: true
|
||||
- name: 'process.pe.original_file_name'
|
||||
type: 'keyword'
|
||||
ecs: true
|
||||
setup: ''
|
||||
example5:
|
||||
summary: Indicator match rule response
|
||||
description: Example response for an indicator match rule
|
||||
value:
|
||||
author: []
|
||||
created_at: '2020-10-06T07:07:58.227Z'
|
||||
updated_at: '2020-10-06T07:07:58.237Z'
|
||||
created_by: 'elastic'
|
||||
description: 'Checks for bad IP addresses listed in the ip-threat-list index'
|
||||
enabled: true
|
||||
false_positives: []
|
||||
from: 'now-6m'
|
||||
id: 'd5daa13f-81fb-4b13-be2f-31011e1d9ae1'
|
||||
immutable: false
|
||||
interval: '5m'
|
||||
rule_id: '608501e4-c768-4f64-9326-cec55b5d439b'
|
||||
max_signals: 100
|
||||
risk_score: 50
|
||||
risk_score_mapping: []
|
||||
name: 'Bad IP threat match'
|
||||
references: []
|
||||
severity: 'medium'
|
||||
severity_mapping: []
|
||||
updated_by: 'elastic'
|
||||
tags: []
|
||||
to: 'now'
|
||||
type: 'threat_match'
|
||||
threat: []
|
||||
version: 1
|
||||
exceptions_list: []
|
||||
index:
|
||||
- 'packetbeat-*'
|
||||
query: 'destination.ip:* or host.ip:*'
|
||||
language: 'kuery'
|
||||
threat_query: '*:*'
|
||||
threat_index:
|
||||
- 'ip-threat-list'
|
||||
threat_mapping:
|
||||
- entries:
|
||||
- field: 'destination.ip'
|
||||
type: 'mapping'
|
||||
value: 'destination.ip'
|
||||
- field: 'destination.port'
|
||||
type: 'mapping'
|
||||
value: 'destination.port'
|
||||
- entries:
|
||||
- field: 'source.ip'
|
||||
type: 'mapping'
|
||||
value: 'host.ip'
|
||||
related_integrations:
|
||||
- package: 'o365'
|
||||
version: '^2.3.2'
|
||||
required_fields:
|
||||
- name: 'destination.ip'
|
||||
type: 'ip'
|
||||
ecs: true
|
||||
- name: 'destination.port'
|
||||
type: 'long'
|
||||
ecs: true
|
||||
- name: 'host.ip'
|
||||
type: 'ip'
|
||||
ecs: true
|
||||
setup: ''
|
||||
example6:
|
||||
summary: New terms rule response
|
||||
description: Example response for a new terms rule
|
||||
value:
|
||||
author: []
|
||||
created_at: '2020-10-06T07:07:58.227Z'
|
||||
updated_at: '2020-10-06T07:07:58.237Z'
|
||||
created_by: 'elastic'
|
||||
description: 'Detects a user associated with a new IP address'
|
||||
enabled: true
|
||||
false_positives: []
|
||||
from: 'now-6m'
|
||||
id: 'eb7225c0-566b-11ee-8b4f-bbf3afdeb9f4'
|
||||
immutable: false
|
||||
interval: '5m'
|
||||
rule_id: 'c6f5d0bc-7be9-47d4-b2f3-073d22641e30'
|
||||
max_signals: 100
|
||||
risk_score: 21
|
||||
risk_score_mapping: []
|
||||
name: 'New User IP Detected'
|
||||
references: []
|
||||
severity: 'medium'
|
||||
severity_mapping: []
|
||||
updated_by: 'elastic'
|
||||
tags: []
|
||||
to: 'now'
|
||||
type: 'new_terms'
|
||||
threat: []
|
||||
version: 1
|
||||
exceptions_list: []
|
||||
index:
|
||||
- 'auditbeat*'
|
||||
query: '*'
|
||||
language: 'kuery'
|
||||
new_terms_fields:
|
||||
- 'user.id'
|
||||
- 'source.ip'
|
||||
history_window_start: 'now-30d'
|
||||
related_integrations:
|
||||
- package: 'o365'
|
||||
version: '^2.3.2'
|
||||
required_fields:
|
||||
- name: 'user.id'
|
||||
type: 'keyword'
|
||||
ecs: true
|
||||
- name: 'source.ip'
|
||||
type: 'ip'
|
||||
ecs: true
|
||||
setup: ''
|
||||
example7:
|
||||
summary: Esql rule response
|
||||
description: Example response for an Esql rule
|
||||
value:
|
||||
name: 'Find Excel events'
|
||||
description: 'Find Excel events'
|
||||
risk_score: 21
|
||||
severity: 'low'
|
||||
output_index: ''
|
||||
tags: []
|
||||
interval: '5m'
|
||||
enabled: false
|
||||
author: []
|
||||
false_positives: []
|
||||
from: 'now-360s'
|
||||
max_signals: 100
|
||||
risk_score_mapping: []
|
||||
severity_mapping: []
|
||||
threat: []
|
||||
to: 'now'
|
||||
references: []
|
||||
version: 1
|
||||
exceptions_list: []
|
||||
actions: []
|
||||
id: 'd0f20490-6da4-11ee-b85e-09e9b661f2e2'
|
||||
updated_at: '2023-10-18T10:55:14.269Z'
|
||||
updated_by: 'elastic'
|
||||
created_at: '2023-10-18T10:55:14.269Z'
|
||||
created_by: 'elastic'
|
||||
revision: 0
|
||||
rule_id: 'e4b53a89-debd-4a0d-a3e3-20606952e589'
|
||||
immutable: false
|
||||
related_integrations:
|
||||
- package: 'o365'
|
||||
version: '^2.3.2'
|
||||
required_fields:
|
||||
- name: 'process.parent.name'
|
||||
type: 'keyword'
|
||||
ecs: true
|
||||
setup: ''
|
||||
type: 'esql'
|
||||
language: 'esql'
|
||||
query: 'from auditbeat-8.10.2 METADATA _id | where process.parent.name == "EXCEL.EXE"'
|
||||
|
|
|
|||
|
|
@ -9,7 +9,15 @@ paths:
|
|||
x-codegen-enabled: true
|
||||
operationId: DeleteRule
|
||||
summary: Delete a detection rule
|
||||
description: Delete a detection rule using the `rule_id` or `id` field.
|
||||
description: |
|
||||
Delete a detection rule using the `rule_id` or `id` field.
|
||||
|
||||
The URL query must include one of the following:
|
||||
|
||||
* `id` - `DELETE /api/detection_engine/rules?id=<id>`
|
||||
* `rule_id`- `DELETE /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.
|
||||
tags:
|
||||
- Rules API
|
||||
parameters:
|
||||
|
|
@ -25,6 +33,12 @@ paths:
|
|||
description: The rule's `rule_id` value.
|
||||
schema:
|
||||
$ref: '../../../model/rule_schema/common_attributes.schema.yaml#/components/schemas/RuleSignatureId'
|
||||
x-codeSamples:
|
||||
- lang: cURL
|
||||
source: |
|
||||
curl \
|
||||
--request DELETE 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"
|
||||
responses:
|
||||
200:
|
||||
description: Indicates a successful call.
|
||||
|
|
|
|||
|
|
@ -9,15 +9,82 @@ paths:
|
|||
x-codegen-enabled: true
|
||||
operationId: PatchRule
|
||||
summary: Patch a detection rule
|
||||
description: Update specific fields of an existing detection rule using the `rule_id` or `id` field.
|
||||
description: |
|
||||
Update specific fields of an existing detection rule using the `rule_id` or `id` field.
|
||||
|
||||
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.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
tags:
|
||||
- Rules API
|
||||
requestBody:
|
||||
required: true
|
||||
description: |
|
||||
> info
|
||||
> You cannot modify the `id` or `rule_id` values.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../../../model/rule_schema/rule_schemas.schema.yaml#/components/schemas/RulePatchProps'
|
||||
examples:
|
||||
example1:
|
||||
summary: Patch query rule
|
||||
value:
|
||||
id: '14b7b513-3d8d-4b22-b7da-a7ae632f7e76'
|
||||
name: 'New name'
|
||||
example2:
|
||||
summary: Patch EQL rule
|
||||
value:
|
||||
rule_id: 'process_started_by_ms_office_program_possible_payload'
|
||||
threat:
|
||||
- framework: 'MITRE ATT&CK'
|
||||
tactic:
|
||||
id: 'TA0001'
|
||||
reference: 'https://attack.mitre.org/tactics/TA0001'
|
||||
name: 'Initial Access'
|
||||
technique:
|
||||
- id: 'T1193'
|
||||
name: 'Spearphishing Attachment'
|
||||
reference: 'https://attack.mitre.org/techniques/T1193'
|
||||
example3:
|
||||
summary: Patch threshold rule
|
||||
value:
|
||||
id: '005d2c4f-51ca-493d-a2bd-20ef076339b1'
|
||||
query: 'agent.version : * and agent.id : "243d9b4f-ca01-4311-8e5c-9abbee91afd8"'
|
||||
threshold:
|
||||
field: []
|
||||
value: 600
|
||||
cardinality: []
|
||||
example4:
|
||||
summary: Patch new terms rule
|
||||
value:
|
||||
id: '569aac91-40dc-4807-a8ae-a2c8698089c4'
|
||||
new_terms_fields:
|
||||
- 'Endpoint.policy.applied.artifacts.global.identifiers.name'
|
||||
history_window_start: 'now-3d'
|
||||
example5:
|
||||
summary: Patch esql rule
|
||||
value:
|
||||
id: '0b15e8a2-49b6-47e0-a8e6-d63a6cc335bd'
|
||||
query: |
|
||||
FROM logs-abc*
|
||||
| STATS count = COUNT(*), min_timestamp = MIN(@timestamp)
|
||||
| EVAL event_rate = count / DATE_DIFF("seconds", min_timestamp, NOW())
|
||||
| KEEP event_rate
|
||||
example6:
|
||||
summary: Patch indicator match rule
|
||||
value:
|
||||
id: '462f1986-10fe-40a3-a22c-2b1c9c4c48fd'
|
||||
threat_query: '@timestamp >= "now-30d/d" and event.module:(threatintel or ti_*) and threat.indicator.ip:* and not labels.is_ioc_transform_source:"false"'
|
||||
example7:
|
||||
summary: Patch machine learning rule
|
||||
value:
|
||||
id: '60b13926-289b-41b1-a537-197ef1fa5059'
|
||||
anomaly_threshold: 50
|
||||
machine_learning_job_id:
|
||||
- 'auth_high_count_logon_events'
|
||||
responses:
|
||||
200:
|
||||
description: Indicates a successful call.
|
||||
|
|
@ -25,3 +92,41 @@ paths:
|
|||
application/json:
|
||||
schema:
|
||||
$ref: '../../../model/rule_schema/rule_schemas.schema.yaml#/components/schemas/RuleResponse'
|
||||
examples:
|
||||
example1:
|
||||
summary: Example response for an updated rule
|
||||
value:
|
||||
created_at: '2020-04-07T14:51:09.755Z'
|
||||
updated_at: '2020-04-07T14:51:09.970Z'
|
||||
created_by: 'elastic'
|
||||
description: 'Updated description for the rule.'
|
||||
enabled: false
|
||||
false_positives: []
|
||||
from: 'now-70m'
|
||||
id: '6541b99a-dee9-4f6d-a86d-dbd1869d73b1'
|
||||
immutable: false
|
||||
interval: '1h'
|
||||
rule_id: 'process_started_by_ms_office_program'
|
||||
max_signals: 100
|
||||
risk_score: 50
|
||||
name: 'Updated Rule Name'
|
||||
references: []
|
||||
severity: 'low'
|
||||
updated_by: 'elastic'
|
||||
tags:
|
||||
- 'child process'
|
||||
- 'ms office'
|
||||
to: 'now'
|
||||
type: 'query'
|
||||
threat: []
|
||||
version: 2
|
||||
actions: []
|
||||
filters:
|
||||
- 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'
|
||||
language: 'kuery'
|
||||
related_integrations:
|
||||
- package: 'o365'
|
||||
required_fields:
|
||||
- name: 'process.parent.name'
|
||||
setup: ''
|
||||
|
|
|
|||
|
|
@ -9,7 +9,15 @@ paths:
|
|||
x-codegen-enabled: true
|
||||
operationId: ReadRule
|
||||
summary: Retrieve a detection rule
|
||||
description: Retrieve a detection rule using the `rule_id` or `id` field.
|
||||
description: |
|
||||
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.
|
||||
tags:
|
||||
- Rules API
|
||||
parameters:
|
||||
|
|
@ -25,10 +33,85 @@ paths:
|
|||
description: The rule's `rule_id` value.
|
||||
schema:
|
||||
$ref: '../../../model/rule_schema/common_attributes.schema.yaml#/components/schemas/RuleSignatureId'
|
||||
x-codeSamples:
|
||||
- lang: cURL
|
||||
source: |
|
||||
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"
|
||||
responses:
|
||||
200:
|
||||
description: Indicates a successful call.
|
||||
description: |
|
||||
Indicates a successful call.
|
||||
> info
|
||||
> These fields are under development and their usage or schema may change: execution_summary.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../../../model/rule_schema/rule_schemas.schema.yaml#/components/schemas/RuleResponse'
|
||||
examples:
|
||||
example1:
|
||||
summary: Example response for a retrieved rule
|
||||
value:
|
||||
created_at: '2020-02-03T11:19:04.259Z'
|
||||
updated_at: '2020-02-03T11:19:04.462Z'
|
||||
created_by: 'elastic'
|
||||
description: 'Process started by MS Office program in user folder'
|
||||
enabled: false
|
||||
false_positives: []
|
||||
filters:
|
||||
- query:
|
||||
match:
|
||||
event.action:
|
||||
query: 'Process Create (rule: ProcessCreate)'
|
||||
type: 'phrase'
|
||||
from: 'now-4200s'
|
||||
id: 'c41d170b-8ba6-4de6-b8ec-76440a35ace3'
|
||||
immutable: false
|
||||
interval: '1h'
|
||||
rule_id: 'process_started_by_ms_office_user_folder'
|
||||
related_integrations:
|
||||
- package: 'o365'
|
||||
version: '^2.3.2'
|
||||
required_fields:
|
||||
- name: 'process.name'
|
||||
type: 'keyword'
|
||||
ecs: true
|
||||
- name: 'process.parent.name'
|
||||
type: 'keyword'
|
||||
ecs: true
|
||||
setup: ''
|
||||
language: 'kuery'
|
||||
max_signals: 100
|
||||
risk_score: 21
|
||||
name: 'MS Office child process'
|
||||
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'
|
||||
references: []
|
||||
severity: 'low'
|
||||
updated_by: 'elastic'
|
||||
tags:
|
||||
- 'child process'
|
||||
- 'ms office'
|
||||
to: 'now-300s'
|
||||
type: 'query'
|
||||
threat:
|
||||
- framework: 'MITRE ATT&CK'
|
||||
tactic:
|
||||
id: 'TA0001'
|
||||
reference: 'https://attack.mitre.org/tactics/TA0001'
|
||||
name: 'Initial Access'
|
||||
technique:
|
||||
- id: 'T1193'
|
||||
name: 'Spearphishing Attachment'
|
||||
reference: 'https://attack.mitre.org/techniques/T1193'
|
||||
execution_summary:
|
||||
last_execution:
|
||||
date: '2022-03-23T16:06:12.787Z'
|
||||
status: 'partial failure'
|
||||
status_order: 20
|
||||
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:
|
||||
total_search_duration_ms: 135
|
||||
total_indexing_duration_ms: 15
|
||||
execution_gap_duration_s: 0
|
||||
version: 1
|
||||
|
|
|
|||
|
|
@ -11,16 +11,126 @@ paths:
|
|||
summary: Update a detection rule
|
||||
description: |
|
||||
Update a detection rule using the `rule_id` or `id` field. The original rule is replaced, and all unspecified fields are deleted.
|
||||
> info
|
||||
> You cannot modify the `id` or `rule_id` values.
|
||||
|
||||
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.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
tags:
|
||||
- Rules API
|
||||
requestBody:
|
||||
required: true
|
||||
description: |
|
||||
> info
|
||||
> All unspecified fields are deleted. You cannot modify the `id` or `rule_id` values.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../../../model/rule_schema/rule_schemas.schema.yaml#/components/schemas/RuleUpdateProps'
|
||||
examples:
|
||||
example1:
|
||||
summary: Update query rule
|
||||
value:
|
||||
id: '14b7b513-3d8d-4b22-b7da-a7ae632f7e76'
|
||||
type: 'query'
|
||||
name: 'A new name for the rule'
|
||||
description: 'A new description'
|
||||
risk_score: 22
|
||||
severity: 'medium'
|
||||
example2:
|
||||
summary: Update EQL rule
|
||||
value:
|
||||
id: '9b684efb-acf9-4323-9bff-8335b3867d14'
|
||||
name: 'New name for EQL rule'
|
||||
description: 'eql rule test'
|
||||
risk_score: 21
|
||||
severity: 'low'
|
||||
type: 'eql'
|
||||
language: 'eql'
|
||||
index:
|
||||
- 'apm-*-transaction*'
|
||||
query: 'process where process.name == "regsvr32.exe"'
|
||||
example3:
|
||||
summary: Update threshold rule
|
||||
value:
|
||||
id: '005d2c4f-51ca-493d-a2bd-20ef076339b1'
|
||||
name: 'New name for threat rule'
|
||||
tags: ['new_tag']
|
||||
description: 'Description of threat rule test'
|
||||
risk_score: 21
|
||||
severity: 'low'
|
||||
type: 'threshold'
|
||||
language: 'kuery'
|
||||
query: 'agent.version : * and agent.id : "243d9b4f-ca01-4311-8e5c-9abbee91afd8"'
|
||||
threshold:
|
||||
field: []
|
||||
value: 400
|
||||
cardinality: []
|
||||
example4:
|
||||
summary: Update new terms rule
|
||||
value:
|
||||
id: '569aac91-40dc-4807-a8ae-a2c8698089c4'
|
||||
name: 'New terms rule name'
|
||||
description: 'New description'
|
||||
type: 'new_terms'
|
||||
interval: '5m'
|
||||
risk_score: 21
|
||||
severity: 'low'
|
||||
query: 'agent.version : "9.1.0"'
|
||||
new_terms_fields:
|
||||
- 'Endpoint.policy.applied.artifacts.global.identifiers.name'
|
||||
history_window_start: 'now-7d'
|
||||
example5:
|
||||
summary: Update esql rule
|
||||
value:
|
||||
id: '0b15e8a2-49b6-47e0-a8e6-d63a6cc335bd'
|
||||
name: 'New name for esql rule'
|
||||
description: 'New description for esql rule'
|
||||
risk_score: 21
|
||||
severity: 'low'
|
||||
type: 'esql'
|
||||
language: 'esql'
|
||||
query: |
|
||||
FROM logs*
|
||||
| STATS count = COUNT(*), min_timestamp = MIN(@timestamp) /* MIN(dateField) finds the earliest timestamp in the dataset. */
|
||||
| EVAL event_rate = count / DATE_DIFF("seconds", min_timestamp, NOW()) /* Calculates the event rate by dividing the total count of events by the time difference (in seconds) between the earliest event and the current time. */
|
||||
| KEEP event_rate
|
||||
example6:
|
||||
summary: Update indicator match rule
|
||||
value:
|
||||
id: '462f1986-10fe-40a3-a22c-2b1c9c4c48fd'
|
||||
name: 'New name for Indicator Match rule'
|
||||
description: 'New description'
|
||||
risk_score: 99
|
||||
severity: 'critical'
|
||||
type: 'threat_match'
|
||||
query: 'source.ip:* or destination.ip:*\n'
|
||||
threat_query: '@timestamp >= "now-30d/d" and event.module:(threatintel or ti_*) and threat.indicator.ip:* and not labels.is_ioc_transform_source:"true"'
|
||||
threat_mapping:
|
||||
- entries:
|
||||
- field: 'source.ip'
|
||||
type: 'mapping'
|
||||
value: 'threat.indicator.ip'
|
||||
- entries:
|
||||
- field: 'destination.ip'
|
||||
type: 'mapping'
|
||||
value: 'threat.indicator.ip'
|
||||
threat_index:
|
||||
- 'filebeat-*'
|
||||
- 'logs-ti_*'
|
||||
example7:
|
||||
summary: Update machine learning rule
|
||||
value:
|
||||
id: '60b13926-289b-41b1-a537-197ef1fa5059'
|
||||
name: 'New name of ml rule'
|
||||
description: 'New description of ml rule'
|
||||
risk_score: 21
|
||||
severity: 'low'
|
||||
type: 'machine_learning'
|
||||
anomaly_threshold: 50
|
||||
machine_learning_job_id:
|
||||
- 'auth_high_count_logon_events'
|
||||
responses:
|
||||
200:
|
||||
description: Indicates a successful call.
|
||||
|
|
@ -28,3 +138,41 @@ paths:
|
|||
application/json:
|
||||
schema:
|
||||
$ref: '../../../model/rule_schema/rule_schemas.schema.yaml#/components/schemas/RuleResponse'
|
||||
examples:
|
||||
example1:
|
||||
summary: Example response for an updated rule
|
||||
value:
|
||||
created_at: '2020-04-07T14:51:09.755Z'
|
||||
updated_at: '2020-04-07T14:51:09.970Z'
|
||||
created_by: 'elastic'
|
||||
description: 'Updated description for the rule.'
|
||||
enabled: false
|
||||
false_positives: []
|
||||
from: 'now-70m'
|
||||
id: '6541b99a-dee9-4f6d-a86d-dbd1869d73b1'
|
||||
immutable: false
|
||||
interval: '1h'
|
||||
rule_id: 'process_started_by_ms_office_program'
|
||||
max_signals: 100
|
||||
risk_score: 50
|
||||
name: 'Updated Rule Name'
|
||||
references: []
|
||||
severity: 'low'
|
||||
updated_by: 'elastic'
|
||||
tags:
|
||||
- 'child process'
|
||||
- 'ms office'
|
||||
to: 'now'
|
||||
type: 'query'
|
||||
threat: []
|
||||
version: 2
|
||||
actions: []
|
||||
filters:
|
||||
- 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'
|
||||
language: 'kuery'
|
||||
related_integrations:
|
||||
- package: 'o365'
|
||||
required_fields:
|
||||
- name: 'process.parent.name'
|
||||
setup: ''
|
||||
|
|
|
|||
|
|
@ -25,9 +25,12 @@ export const ExportRulesRequestQuery = z.object({
|
|||
* Determines whether a summary of the exported rules is returned.
|
||||
*/
|
||||
exclude_export_details: BooleanFromString.optional().default(false),
|
||||
/**
|
||||
* File name for saving the exported rules.
|
||||
*/
|
||||
/**
|
||||
* File name for saving the exported rules.
|
||||
> info
|
||||
> When using cURL to export rules to a file, use the -O and -J options to save the rules to the file name specified in the URL.
|
||||
|
||||
*/
|
||||
file_name: z.string().optional().default('export.ndjson'),
|
||||
});
|
||||
export type ExportRulesRequestQueryInput = z.input<typeof ExportRulesRequestQuery>;
|
||||
|
|
|
|||
|
|
@ -14,7 +14,11 @@ paths:
|
|||
- Actions
|
||||
- Exception lists
|
||||
> info
|
||||
> You cannot export prebuilt rules.
|
||||
> Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) is not included. You must re-add missing connector details after importing detection rules.
|
||||
|
||||
> You can use Kibana’s [Saved Objects](https://www.elastic.co/guide/en/kibana/current/managing-saved-objects.html) UI (Stack Management → Kibana → Saved Objects) or the Saved Objects APIs (experimental) to [export](https://www.elastic.co/docs/api/doc/kibana/operation/operation-exportsavedobjectsdefault) and [import](https://www.elastic.co/docs/api/doc/kibana/operation/operation-importsavedobjectsdefault) any necessary connectors before importing detection rules.
|
||||
|
||||
> Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the [Manage value lists](https://www.elastic.co/guide/en/security/current/value-lists-exceptions.html#manage-value-lists) UI (Rules → Detection rules (SIEM) → Manage value lists) to export and import value lists separately.
|
||||
tags:
|
||||
- Import/Export API
|
||||
parameters:
|
||||
|
|
@ -28,10 +32,27 @@ paths:
|
|||
- name: file_name
|
||||
in: query
|
||||
required: false
|
||||
description: File name for saving the exported rules.
|
||||
description: |
|
||||
File name for saving the exported rules.
|
||||
> info
|
||||
> When using cURL to export rules to a file, use the -O and -J options to save the rules to the file name specified in the URL.
|
||||
schema:
|
||||
type: string
|
||||
default: export.ndjson
|
||||
x-codeSamples:
|
||||
- lang: cURL
|
||||
source: |
|
||||
curl -X POST "localhost:5601/api/detection_engine/rules/_export?exclude_export_details=true&file_name=exported_rules.ndjson" -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d'
|
||||
{
|
||||
"objects": [
|
||||
{
|
||||
"rule_id":"343580b5-c811-447c-8d2d-2ccf052c6900"
|
||||
},
|
||||
{
|
||||
"rule_id":"2938c9fa-53eb-4c04-b79c-33cbf041b18d"
|
||||
}
|
||||
]
|
||||
}
|
||||
requestBody:
|
||||
required: false
|
||||
content:
|
||||
|
|
@ -60,4 +81,7 @@ paths:
|
|||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
description: An `.ndjson` file containing the returned rules.
|
||||
description: |
|
||||
An `.ndjson` file containing the returned rules.
|
||||
|
||||
Each line in the file represents an object (a rule, exception list parent container, or exception list item), and the last line includes a summary of what was exported.
|
||||
|
|
|
|||
|
|
@ -43,9 +43,20 @@ export const FindRulesSortFieldEnum = FindRulesSortField.enum;
|
|||
export type FindRulesRequestQuery = z.infer<typeof FindRulesRequestQuery>;
|
||||
export const FindRulesRequestQuery = z.object({
|
||||
fields: ArrayFromString(z.string()).optional(),
|
||||
/**
|
||||
* Search query
|
||||
*/
|
||||
/**
|
||||
* Search query
|
||||
|
||||
Filters the returned results according to the value of the specified field, using the alert.attributes.<field name>:<field value> syntax, where <field name> can be:
|
||||
- name
|
||||
- enabled
|
||||
- tags
|
||||
- createdBy
|
||||
- interval
|
||||
- updatedBy
|
||||
> info
|
||||
> Even though the JSON rule object uses created_by and updated_by fields, you must use createdBy and updatedBy fields in the filter.
|
||||
|
||||
*/
|
||||
filter: z.string().optional(),
|
||||
/**
|
||||
* Field to sort by
|
||||
|
|
|
|||
|
|
@ -22,7 +22,18 @@ paths:
|
|||
type: string
|
||||
- name: 'filter'
|
||||
in: query
|
||||
description: Search query
|
||||
description: |
|
||||
Search query
|
||||
|
||||
Filters the returned results according to the value of the specified field, using the alert.attributes.<field name>:<field value> syntax, where <field name> can be:
|
||||
- name
|
||||
- enabled
|
||||
- tags
|
||||
- createdBy
|
||||
- interval
|
||||
- updatedBy
|
||||
> info
|
||||
> Even though the JSON rule object uses created_by and updated_by fields, you must use createdBy and updatedBy fields in the filter.
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -66,10 +77,16 @@ paths:
|
|||
required: false
|
||||
schema:
|
||||
type: string
|
||||
|
||||
x-codeSamples:
|
||||
- lang: cURL
|
||||
source: |
|
||||
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'
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
description: |
|
||||
Successful response
|
||||
> info
|
||||
> These fields are under development and their usage or schema may change: execution_summary.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -90,6 +107,73 @@ paths:
|
|||
- perPage
|
||||
- total
|
||||
- data
|
||||
examples:
|
||||
example1:
|
||||
value:
|
||||
page: 1
|
||||
perPage: 5
|
||||
total: 4
|
||||
data:
|
||||
- created_at: '2020-02-02T10:05:19.613Z'
|
||||
updated_at: '2020-02-02T10:05:19.830Z'
|
||||
created_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.'
|
||||
enabled: false
|
||||
false_positives: []
|
||||
from: 'now-6m'
|
||||
id: '89761517-fdb0-4223-b67b-7621acc48f9e'
|
||||
immutable: true
|
||||
index:
|
||||
- 'winlogbeat-*'
|
||||
interval: '5m'
|
||||
rule_id: 'f545ff26-3c94-4fd0-bd33-3c7f95a3a0fc'
|
||||
language: 'kuery'
|
||||
max_signals: 33
|
||||
risk_score: 21
|
||||
name: 'Windows Script Executing PowerShell'
|
||||
query: 'event.action:"Process Create (rule: ProcessCreate)" and process.parent.name:("wscript.exe" or "cscript.exe") and process.name:"powershell.exe"'
|
||||
references: []
|
||||
severity: 'low'
|
||||
updated_by: 'elastic'
|
||||
tags:
|
||||
- 'Elastic'
|
||||
- 'Windows'
|
||||
to: 'now'
|
||||
related_integrations:
|
||||
- package: 'o365'
|
||||
version: '^2.3.2'
|
||||
required_fields:
|
||||
- name: 'event.action'
|
||||
type: 'keyword'
|
||||
ecs: true
|
||||
- name: 'process.name'
|
||||
type: 'keyword'
|
||||
ecs: true
|
||||
- name: 'process.parent.name'
|
||||
type: 'keyword'
|
||||
ecs: true
|
||||
setup: ''
|
||||
type: 'query'
|
||||
threat:
|
||||
- framework: 'MITRE ATT&CK'
|
||||
tactic:
|
||||
id: 'TA0002'
|
||||
name: 'Execution'
|
||||
reference: 'https://attack.mitre.org/tactics/TA0002/'
|
||||
technique:
|
||||
- id: 'T1193'
|
||||
name: 'Spearphishing Attachment'
|
||||
reference: 'https://attack.mitre.org/techniques/T1193/'
|
||||
execution_summary:
|
||||
last_execution:
|
||||
date: '2022-03-23T16:06:12.787Z'
|
||||
status: 'partial failure'
|
||||
status_order: 20
|
||||
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:
|
||||
total_search_duration_ms: 135
|
||||
total_indexing_duration_ms: 15
|
||||
execution_gap_duration_s: 0
|
||||
|
||||
components:
|
||||
schemas:
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ export const ImportRulesRequestQuery = z.object({
|
|||
*/
|
||||
overwrite: BooleanFromString.optional().default(false),
|
||||
/**
|
||||
* Determines whether existing exception lists with the same `list_id` are overwritten.
|
||||
* Determines whether existing exception lists with the same `list_id` are overwritten. Both the exception list container and its items are overwritten.
|
||||
*/
|
||||
overwrite_exceptions: BooleanFromString.optional().default(false),
|
||||
/**
|
||||
|
|
|
|||
|
|
@ -13,8 +13,28 @@ paths:
|
|||
Import detection rules from an `.ndjson` file, including actions and exception lists. The request must include:
|
||||
- The `Content-Type: multipart/form-data` HTTP header.
|
||||
- A link to the `.ndjson` file containing the rules.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
> info
|
||||
> To import rules with actions, you need at least Read privileges for the Action and Connectors feature. To overwrite or add new connectors, you need All privileges for the Actions and Connectors feature. To import rules without actions, you don’t need Actions and Connectors privileges. Refer to [Enable and access detections](https://www.elastic.co/guide/en/security/current/detections-permissions-section.html#enable-detections-ui) for more information.
|
||||
|
||||
> info
|
||||
> Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) is not included. You must re-add missing connector details after importing detection rules.
|
||||
|
||||
> You can use Kibana’s [Saved Objects](https://www.elastic.co/guide/en/kibana/current/managing-saved-objects.html) UI (Stack Management → Kibana → Saved Objects) or the Saved Objects APIs (experimental) to [export](https://www.elastic.co/docs/api/doc/kibana/operation/operation-exportsavedobjectsdefault) and [import](https://www.elastic.co/docs/api/doc/kibana/operation/operation-importsavedobjectsdefault) any necessary connectors before importing detection rules.
|
||||
|
||||
> Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the [Manage value lists](https://www.elastic.co/guide/en/security/current/value-lists-exceptions.html#manage-value-lists) UI (Rules → Detection rules (SIEM) → Manage value lists) to export and import value lists separately.
|
||||
tags:
|
||||
- Import/Export API
|
||||
x-codeSamples:
|
||||
- lang: cURL
|
||||
source: |
|
||||
curl -X POST "<KibanaURL>/api/detection_engine/rules/_import"
|
||||
-u <username>:<password> -H 'kbn-xsrf: true'
|
||||
-H 'Content-Type: multipart/form-data'
|
||||
--form "file=@<link to file>"
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
|
|
@ -37,7 +57,7 @@ paths:
|
|||
- name: overwrite_exceptions
|
||||
in: query
|
||||
required: false
|
||||
description: Determines whether existing exception lists with the same `list_id` are overwritten.
|
||||
description: Determines whether existing exception lists with the same `list_id` are overwritten. Both the exception list container and its items are overwritten.
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
|
|
@ -110,3 +130,14 @@ paths:
|
|||
action_connectors_success_count:
|
||||
type: integer
|
||||
minimum: 0
|
||||
examples:
|
||||
example1:
|
||||
summary: Import rules with success
|
||||
value:
|
||||
success: true
|
||||
success_count: 1
|
||||
rules_count: 1
|
||||
errors: []
|
||||
exceptions_errors: []
|
||||
exceptions_success: true
|
||||
exceptions_success_count: 0
|
||||
|
|
|
|||
|
|
@ -19,3 +19,14 @@ paths:
|
|||
application/json:
|
||||
schema:
|
||||
$ref: '../../model/rule_schema/common_attributes.schema.yaml#/components/schemas/RuleTagArray'
|
||||
examples:
|
||||
example1:
|
||||
value:
|
||||
- "zeek"
|
||||
- "suricata"
|
||||
- "windows"
|
||||
- "linux"
|
||||
- "network"
|
||||
- "initial access"
|
||||
- "remote access"
|
||||
- "phishing"
|
||||
|
|
|
|||
|
|
@ -19,6 +19,12 @@ import { z } from '@kbn/zod';
|
|||
import { RuleExecutionStatus, RuleExecutionStatusOrder } from './execution_status.gen';
|
||||
import { RuleExecutionMetrics } from './execution_metrics.gen';
|
||||
|
||||
/**
|
||||
* Summary of the last execution of a rule.
|
||||
> info
|
||||
> This field is under development and its usage or schema may change
|
||||
|
||||
*/
|
||||
export type RuleExecutionSummary = z.infer<typeof RuleExecutionSummary>;
|
||||
export const RuleExecutionSummary = z.object({
|
||||
last_execution: z.object({
|
||||
|
|
|
|||
|
|
@ -8,6 +8,10 @@ components:
|
|||
schemas:
|
||||
RuleExecutionSummary:
|
||||
type: object
|
||||
description: |
|
||||
Summary of the last execution of a rule.
|
||||
> info
|
||||
> This field is under development and its usage or schema may change
|
||||
properties:
|
||||
last_execution:
|
||||
type: object
|
||||
|
|
|
|||
|
|
@ -736,8 +736,62 @@ If a record already exists for the specified entity, that record is overwritten
|
|||
.catch(catchAxiosErrorFormatAndThrow);
|
||||
}
|
||||
/**
|
||||
* Create a new detection rule.
|
||||
*/
|
||||
* Create a new detection rule.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
|
||||
You can create the following types of rules:
|
||||
|
||||
* **Custom query**: Searches the defined indices and creates an alert when a document matches the rule's KQL query.
|
||||
* **Event correlation**: Searches the defined indices and creates an alert when results match an [Event Query Language (EQL)](https://www.elastic.co/guide/en/elasticsearch/reference/current/eql.html) query.
|
||||
* **Threshold**: Searches the defined indices and creates an alert when the number of times the specified field's value meets the threshold during a single execution. When there are multiple values that meet the threshold, an alert is generated for each value.
|
||||
For example, if the threshold `field` is `source.ip` and its `value` is `10`, an alert is generated for every source IP address that appears in at least 10 of the rule's search results. If you're interested, see [Terms Aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html) for more information.
|
||||
* **Indicator match**: Creates an alert when fields match values defined in the specified [Elasticsearch index](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html). For example, you can create an index for IP addresses and use this index to create an alert whenever an event's `destination.ip` equals a value in the index. The index's field mappings should be [ECS-compliant](https://www.elastic.co/guide/en/ecs/current/ecs-reference.html).
|
||||
* **New terms**: Generates an alert for each new term detected in source documents within a specified time range.
|
||||
* **ES|QL**: Uses [Elasticsearch Query Language (ES|QL)](https://www.elastic.co/guide/en/elasticsearch/reference/current/esql.html) to find events and aggregate search results.
|
||||
* **Machine learning rules**: Creates an alert when a machine learning job discovers an anomaly above the defined threshold.
|
||||
> info
|
||||
> To create machine learning rules, you must have the [appropriate license](https://www.elastic.co/subscriptions) or use a [cloud deployment](https://cloud.elastic.co/registration). Additionally, for the machine learning rule to function correctly, the associated machine learning job must be running.
|
||||
|
||||
To retrieve machine learning job IDs, which are required to create machine learning jobs, call the [Elasticsearch Get jobs API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-job.html). Machine learning jobs that contain `siem` in the `groups` field can be used to create rules:
|
||||
|
||||
```json
|
||||
...
|
||||
"job_id": "linux_anomalous_network_activity_ecs",
|
||||
"job_type": "anomaly_detector",
|
||||
"job_version": "7.7.0",
|
||||
"groups": [
|
||||
"auditbeat",
|
||||
"process",
|
||||
"siem"
|
||||
],
|
||||
...
|
||||
```
|
||||
|
||||
Additionally, you can set up notifications for when rules create alerts. The notifications use the [Alerting and Actions framework](https://www.elastic.co/guide/en/kibana/current/alerting-getting-started.html). Each action type requires a connector. Connectors store the information required to send notifications via external systems. The following connector types are supported for rule notifications:
|
||||
|
||||
* Slack
|
||||
* Email
|
||||
* PagerDuty
|
||||
* Webhook
|
||||
* Microsoft Teams
|
||||
* IBM Resilient
|
||||
* Jira
|
||||
* ServiceNow ITSM
|
||||
> info
|
||||
> For more information on PagerDuty fields, see [Send a v2 Event](https://developer.pagerduty.com/docs/events-api-v2/trigger-events/).
|
||||
|
||||
To retrieve connector IDs, which are required to configure rule notifications, call the [Find objects API](https://www.elastic.co/guide/en/kibana/current/saved-objects-api-find.html) with `"type": "action"` in the request payload.
|
||||
|
||||
For detailed information on Kibana actions and alerting, and additional API calls, see:
|
||||
|
||||
* [Alerting API](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-alerting)
|
||||
* [Alerting and Actions framework](https://www.elastic.co/guide/en/kibana/current/alerting-getting-started.html)
|
||||
* [Connectors API](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-connectors)
|
||||
|
||||
*/
|
||||
async createRule(props: CreateRuleProps) {
|
||||
this.log.info(`${new Date().toISOString()} Calling API CreateRule`);
|
||||
return this.kbnClient
|
||||
|
|
@ -859,8 +913,16 @@ If a record already exists for the specified entity, that record is overwritten
|
|||
.catch(catchAxiosErrorFormatAndThrow);
|
||||
}
|
||||
/**
|
||||
* Delete a detection rule using the `rule_id` or `id` field.
|
||||
*/
|
||||
* Delete a detection rule using the `rule_id` or `id` field.
|
||||
|
||||
The URL query must include one of the following:
|
||||
|
||||
* `id` - `DELETE /api/detection_engine/rules?id=<id>`
|
||||
* `rule_id`- `DELETE /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.
|
||||
|
||||
*/
|
||||
async deleteRule(props: DeleteRuleProps) {
|
||||
this.log.info(`${new Date().toISOString()} Calling API DeleteRule`);
|
||||
return this.kbnClient
|
||||
|
|
@ -1227,7 +1289,11 @@ If a record already exists for the specified entity, that record is overwritten
|
|||
- Actions
|
||||
- Exception lists
|
||||
> info
|
||||
> You cannot export prebuilt rules.
|
||||
> Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) is not included. You must re-add missing connector details after importing detection rules.
|
||||
|
||||
> You can use Kibana’s [Saved Objects](https://www.elastic.co/guide/en/kibana/current/managing-saved-objects.html) UI (Stack Management → Kibana → Saved Objects) or the Saved Objects APIs (experimental) to [export](https://www.elastic.co/docs/api/doc/kibana/operation/operation-exportsavedobjectsdefault) and [import](https://www.elastic.co/docs/api/doc/kibana/operation/operation-importsavedobjectsdefault) any necessary connectors before importing detection rules.
|
||||
|
||||
> Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the [Manage value lists](https://www.elastic.co/guide/en/security/current/value-lists-exceptions.html#manage-value-lists) UI (Rules → Detection rules (SIEM) → Manage value lists) to export and import value lists separately.
|
||||
|
||||
*/
|
||||
async exportRules(props: ExportRulesProps) {
|
||||
|
|
@ -1725,6 +1791,19 @@ finalize it.
|
|||
* Import detection rules from an `.ndjson` file, including actions and exception lists. The request must include:
|
||||
- The `Content-Type: multipart/form-data` HTTP header.
|
||||
- A link to the `.ndjson` file containing the rules.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
> info
|
||||
> To import rules with actions, you need at least Read privileges for the Action and Connectors feature. To overwrite or add new connectors, you need All privileges for the Actions and Connectors feature. To import rules without actions, you don’t need Actions and Connectors privileges. Refer to [Enable and access detections](https://www.elastic.co/guide/en/security/current/detections-permissions-section.html#enable-detections-ui) for more information.
|
||||
|
||||
> info
|
||||
> Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) is not included. You must re-add missing connector details after importing detection rules.
|
||||
|
||||
> You can use Kibana’s [Saved Objects](https://www.elastic.co/guide/en/kibana/current/managing-saved-objects.html) UI (Stack Management → Kibana → Saved Objects) or the Saved Objects APIs (experimental) to [export](https://www.elastic.co/docs/api/doc/kibana/operation/operation-exportsavedobjectsdefault) and [import](https://www.elastic.co/docs/api/doc/kibana/operation/operation-importsavedobjectsdefault) any necessary connectors before importing detection rules.
|
||||
|
||||
> Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the [Manage value lists](https://www.elastic.co/guide/en/security/current/value-lists-exceptions.html#manage-value-lists) UI (Rules → Detection rules (SIEM) → Manage value lists) to export and import value lists separately.
|
||||
|
||||
*/
|
||||
async importRules(props: ImportRulesProps) {
|
||||
|
|
@ -1815,8 +1894,19 @@ finalize it.
|
|||
.catch(catchAxiosErrorFormatAndThrow);
|
||||
}
|
||||
/**
|
||||
* Install and update all Elastic prebuilt detection rules and Timelines.
|
||||
*/
|
||||
* Install and update all Elastic prebuilt detection rules and Timelines.
|
||||
|
||||
This endpoint allows you to install and update prebuilt detection rules and Timelines provided by Elastic.
|
||||
When you call this endpoint, it will:
|
||||
- Install any new prebuilt detection rules that are not currently installed in your system.
|
||||
- Update any existing prebuilt detection rules that have been modified or improved by Elastic.
|
||||
- Install any new prebuilt Timelines that are not currently installed in your system.
|
||||
- Update any existing prebuilt Timelines that have been modified or improved by Elastic.
|
||||
|
||||
This ensures that your detection engine is always up-to-date with the latest rules and Timelines,
|
||||
providing you with the most current and effective threat detection capabilities.
|
||||
|
||||
*/
|
||||
async installPrebuiltRulesAndTimelines() {
|
||||
this.log.info(`${new Date().toISOString()} Calling API InstallPrebuiltRulesAndTimelines`);
|
||||
return this.kbnClient
|
||||
|
|
@ -1888,8 +1978,15 @@ finalize it.
|
|||
.catch(catchAxiosErrorFormatAndThrow);
|
||||
}
|
||||
/**
|
||||
* Update specific fields of an existing detection rule using the `rule_id` or `id` field.
|
||||
*/
|
||||
* Update specific fields of an existing detection rule using the `rule_id` or `id` field.
|
||||
|
||||
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.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
|
||||
*/
|
||||
async patchRule(props: PatchRuleProps) {
|
||||
this.log.info(`${new Date().toISOString()} Calling API PatchRule`);
|
||||
return this.kbnClient
|
||||
|
|
@ -1920,8 +2017,13 @@ finalize it.
|
|||
.catch(catchAxiosErrorFormatAndThrow);
|
||||
}
|
||||
/**
|
||||
* Apply a bulk action, such as bulk edit, duplicate, or delete, to multiple detection rules. The bulk action is applied to all rules that match the query or to the rules listed by their IDs.
|
||||
*/
|
||||
* Apply a bulk action, such as bulk edit, duplicate, or delete, to multiple detection rules. The bulk action is applied to all rules that match the query or to the rules listed by their IDs.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
|
||||
*/
|
||||
async performRulesBulkAction(props: PerformRulesBulkActionProps) {
|
||||
this.log.info(`${new Date().toISOString()} Calling API PerformRulesBulkAction`);
|
||||
return this.kbnClient
|
||||
|
|
@ -2030,8 +2132,11 @@ finalize it.
|
|||
.catch(catchAxiosErrorFormatAndThrow);
|
||||
}
|
||||
/**
|
||||
* Retrieve the status of all Elastic prebuilt detection rules and Timelines.
|
||||
*/
|
||||
* Retrieve the status of all Elastic prebuilt detection rules and Timelines.
|
||||
|
||||
This endpoint provides detailed information about the number of custom rules, installed prebuilt rules, available prebuilt rules that are not installed, outdated prebuilt rules, installed prebuilt timelines, available prebuilt timelines that are not installed, and outdated prebuilt timelines.
|
||||
|
||||
*/
|
||||
async readPrebuiltRulesAndTimelinesStatus() {
|
||||
this.log.info(`${new Date().toISOString()} Calling API ReadPrebuiltRulesAndTimelinesStatus`);
|
||||
return this.kbnClient
|
||||
|
|
@ -2076,8 +2181,16 @@ detection engine rules.
|
|||
.catch(catchAxiosErrorFormatAndThrow);
|
||||
}
|
||||
/**
|
||||
* Retrieve a detection rule using the `rule_id` or `id` field.
|
||||
*/
|
||||
* 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.
|
||||
|
||||
*/
|
||||
async readRule(props: ReadRuleProps) {
|
||||
this.log.info(`${new Date().toISOString()} Calling API ReadRule`);
|
||||
return this.kbnClient
|
||||
|
|
@ -2338,8 +2451,12 @@ detection engine rules.
|
|||
}
|
||||
/**
|
||||
* Update a detection rule using the `rule_id` or `id` field. The original rule is replaced, and all unspecified fields are deleted.
|
||||
> info
|
||||
> You cannot modify the `id` or `rule_id` values.
|
||||
|
||||
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.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
|
||||
*/
|
||||
async updateRule(props: UpdateRuleProps) {
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load diff
File diff suppressed because it is too large
Load diff
|
|
@ -1,14 +1,24 @@
|
|||
openapi: 3.0.3
|
||||
info:
|
||||
title: "Security Detections API (Elastic Cloud and self-hosted)"
|
||||
description: "Use the detections APIs to create and manage detection rules. Detection rules search events and external alerts sent to Elastic Security and generate detection alerts from any hits. Alerts are displayed on the **Alerts** page and can be assigned and triaged, using the alert status to mark them as open, closed, or acknowledged."
|
||||
title: 'Security Detections API (Elastic Cloud and self-hosted)'
|
||||
description: 'Use the detections APIs to create and manage detection rules. Detection rules search events and external alerts sent to Elastic Security and generate detection alerts from any hits. Alerts are displayed on the **Alerts** page and can be assigned and triaged, using the alert status to mark them as open, closed, or acknowledged.'
|
||||
|
||||
tags:
|
||||
- name: "Security Detections API"
|
||||
x-displayName: "Security detections"
|
||||
- name: 'Security Detections API'
|
||||
x-displayName: 'Security detections'
|
||||
description: |
|
||||
Use the detections APIs to create and manage detection rules. Detection rules search events and external alerts sent to Elastic Security and generate detection alerts from any hits. Alerts are displayed on the **Alerts** page and can be assigned and triaged, using the alert status to mark them as open, closed, or acknowledged.
|
||||
|
||||
This API supports both key-based authentication and basic authentication.
|
||||
|
||||
To use key-based authentication, create an API key, then specify the key in the header of your API calls.
|
||||
|
||||
To use basic authentication, provide a username and password; this automatically creates an API key that matches the current user’s privileges.
|
||||
|
||||
In both cases, the API key is subsequently used for authorization when the rule runs.
|
||||
> warn
|
||||
> If the API key used for authorization has different privileges than the key that created or most recently updated a rule, the rule behavior might change.
|
||||
|
||||
> If the API key that created a rule is deleted, or the user that created the rule becomes inactive, the rule will stop running.
|
||||
> If the API key that created a rule is deleted, or the user that created the rule becomes inactive, the rule will stop running.
|
||||
|
||||
To create and run rules, the user must meet specific requirements for the Kibana space. Refer to the [Detections requirements](https://www.elastic.co/guide/en/security/current/detections-permissions-section.html) for a complete list of requirements.
|
||||
|
|
|
|||
|
|
@ -1,14 +1,24 @@
|
|||
openapi: 3.0.3
|
||||
info:
|
||||
title: "Security Detections API (Elastic Cloud Serverless)"
|
||||
description: "Use the detections APIs to create and manage detection rules. Detection rules search events and external alerts sent to Elastic Security and generate detection alerts from any hits. Alerts are displayed on the **Alerts** page and can be assigned and triaged, using the alert status to mark them as open, closed, or acknowledged."
|
||||
title: 'Security Detections API (Elastic Cloud Serverless)'
|
||||
description: 'Use the detections APIs to create and manage detection rules. Detection rules search events and external alerts sent to Elastic Security and generate detection alerts from any hits. Alerts are displayed on the **Alerts** page and can be assigned and triaged, using the alert status to mark them as open, closed, or acknowledged.'
|
||||
|
||||
tags:
|
||||
- name: "Security Detections API"
|
||||
x-displayName: "Security detections"
|
||||
- name: 'Security Detections API'
|
||||
x-displayName: 'Security detections'
|
||||
description: |
|
||||
Use the detections APIs to create and manage detection rules. Detection rules search events and external alerts sent to Elastic Security and generate detection alerts from any hits. Alerts are displayed on the **Alerts** page and can be assigned and triaged, using the alert status to mark them as open, closed, or acknowledged.
|
||||
|
||||
This API supports both key-based authentication and basic authentication.
|
||||
|
||||
To use key-based authentication, create an API key, then specify the key in the header of your API calls.
|
||||
|
||||
To use basic authentication, provide a username and password; this automatically creates an API key that matches the current user’s privileges.
|
||||
|
||||
In both cases, the API key is subsequently used for authorization when the rule runs.
|
||||
> warn
|
||||
> If the API key used for authorization has different privileges than the key that created or most recently updated a rule, the rule behavior might change.
|
||||
|
||||
> If the API key that created a rule is deleted, or the user that created the rule becomes inactive, the rule will stop running.
|
||||
> If the API key that created a rule is deleted, or the user that created the rule becomes inactive, the rule will stop running.
|
||||
|
||||
To create and run rules, the user must meet specific requirements for the Kibana space. Refer to the [Detections requirements](https://www.elastic.co/guide/en/security/current/detections-permissions-section.html) for a complete list of requirements.
|
||||
|
|
|
|||
|
|
@ -411,8 +411,62 @@ If a record already exists for the specified entity, that record is overwritten
|
|||
.send(props.body as object);
|
||||
},
|
||||
/**
|
||||
* Create a new detection rule.
|
||||
*/
|
||||
* Create a new detection rule.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
|
||||
You can create the following types of rules:
|
||||
|
||||
* **Custom query**: Searches the defined indices and creates an alert when a document matches the rule's KQL query.
|
||||
* **Event correlation**: Searches the defined indices and creates an alert when results match an [Event Query Language (EQL)](https://www.elastic.co/guide/en/elasticsearch/reference/current/eql.html) query.
|
||||
* **Threshold**: Searches the defined indices and creates an alert when the number of times the specified field's value meets the threshold during a single execution. When there are multiple values that meet the threshold, an alert is generated for each value.
|
||||
For example, if the threshold `field` is `source.ip` and its `value` is `10`, an alert is generated for every source IP address that appears in at least 10 of the rule's search results. If you're interested, see [Terms Aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html) for more information.
|
||||
* **Indicator match**: Creates an alert when fields match values defined in the specified [Elasticsearch index](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html). For example, you can create an index for IP addresses and use this index to create an alert whenever an event's `destination.ip` equals a value in the index. The index's field mappings should be [ECS-compliant](https://www.elastic.co/guide/en/ecs/current/ecs-reference.html).
|
||||
* **New terms**: Generates an alert for each new term detected in source documents within a specified time range.
|
||||
* **ES|QL**: Uses [Elasticsearch Query Language (ES|QL)](https://www.elastic.co/guide/en/elasticsearch/reference/current/esql.html) to find events and aggregate search results.
|
||||
* **Machine learning rules**: Creates an alert when a machine learning job discovers an anomaly above the defined threshold.
|
||||
> info
|
||||
> To create machine learning rules, you must have the [appropriate license](https://www.elastic.co/subscriptions) or use a [cloud deployment](https://cloud.elastic.co/registration). Additionally, for the machine learning rule to function correctly, the associated machine learning job must be running.
|
||||
|
||||
To retrieve machine learning job IDs, which are required to create machine learning jobs, call the [Elasticsearch Get jobs API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-job.html). Machine learning jobs that contain `siem` in the `groups` field can be used to create rules:
|
||||
|
||||
```json
|
||||
...
|
||||
"job_id": "linux_anomalous_network_activity_ecs",
|
||||
"job_type": "anomaly_detector",
|
||||
"job_version": "7.7.0",
|
||||
"groups": [
|
||||
"auditbeat",
|
||||
"process",
|
||||
"siem"
|
||||
],
|
||||
...
|
||||
```
|
||||
|
||||
Additionally, you can set up notifications for when rules create alerts. The notifications use the [Alerting and Actions framework](https://www.elastic.co/guide/en/kibana/current/alerting-getting-started.html). Each action type requires a connector. Connectors store the information required to send notifications via external systems. The following connector types are supported for rule notifications:
|
||||
|
||||
* Slack
|
||||
* Email
|
||||
* PagerDuty
|
||||
* Webhook
|
||||
* Microsoft Teams
|
||||
* IBM Resilient
|
||||
* Jira
|
||||
* ServiceNow ITSM
|
||||
> info
|
||||
> For more information on PagerDuty fields, see [Send a v2 Event](https://developer.pagerduty.com/docs/events-api-v2/trigger-events/).
|
||||
|
||||
To retrieve connector IDs, which are required to configure rule notifications, call the [Find objects API](https://www.elastic.co/guide/en/kibana/current/saved-objects-api-find.html) with `"type": "action"` in the request payload.
|
||||
|
||||
For detailed information on Kibana actions and alerting, and additional API calls, see:
|
||||
|
||||
* [Alerting API](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-alerting)
|
||||
* [Alerting and Actions framework](https://www.elastic.co/guide/en/kibana/current/alerting-getting-started.html)
|
||||
* [Connectors API](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-connectors)
|
||||
|
||||
*/
|
||||
createRule(props: CreateRuleProps, kibanaSpace: string = 'default') {
|
||||
return supertest
|
||||
.post(routeWithNamespace('/api/detection_engine/rules', kibanaSpace))
|
||||
|
|
@ -513,8 +567,16 @@ If a record already exists for the specified entity, that record is overwritten
|
|||
.send(props.body as object);
|
||||
},
|
||||
/**
|
||||
* Delete a detection rule using the `rule_id` or `id` field.
|
||||
*/
|
||||
* Delete a detection rule using the `rule_id` or `id` field.
|
||||
|
||||
The URL query must include one of the following:
|
||||
|
||||
* `id` - `DELETE /api/detection_engine/rules?id=<id>`
|
||||
* `rule_id`- `DELETE /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.
|
||||
|
||||
*/
|
||||
deleteRule(props: DeleteRuleProps, kibanaSpace: string = 'default') {
|
||||
return supertest
|
||||
.delete(routeWithNamespace('/api/detection_engine/rules', kibanaSpace))
|
||||
|
|
@ -795,7 +857,11 @@ If a record already exists for the specified entity, that record is overwritten
|
|||
- Actions
|
||||
- Exception lists
|
||||
> info
|
||||
> You cannot export prebuilt rules.
|
||||
> Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) is not included. You must re-add missing connector details after importing detection rules.
|
||||
|
||||
> You can use Kibana’s [Saved Objects](https://www.elastic.co/guide/en/kibana/current/managing-saved-objects.html) UI (Stack Management → Kibana → Saved Objects) or the Saved Objects APIs (experimental) to [export](https://www.elastic.co/docs/api/doc/kibana/operation/operation-exportsavedobjectsdefault) and [import](https://www.elastic.co/docs/api/doc/kibana/operation/operation-importsavedobjectsdefault) any necessary connectors before importing detection rules.
|
||||
|
||||
> Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the [Manage value lists](https://www.elastic.co/guide/en/security/current/value-lists-exceptions.html#manage-value-lists) UI (Rules → Detection rules (SIEM) → Manage value lists) to export and import value lists separately.
|
||||
|
||||
*/
|
||||
exportRules(props: ExportRulesProps, kibanaSpace: string = 'default') {
|
||||
|
|
@ -1195,6 +1261,19 @@ finalize it.
|
|||
* Import detection rules from an `.ndjson` file, including actions and exception lists. The request must include:
|
||||
- The `Content-Type: multipart/form-data` HTTP header.
|
||||
- A link to the `.ndjson` file containing the rules.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
> info
|
||||
> To import rules with actions, you need at least Read privileges for the Action and Connectors feature. To overwrite or add new connectors, you need All privileges for the Actions and Connectors feature. To import rules without actions, you don’t need Actions and Connectors privileges. Refer to [Enable and access detections](https://www.elastic.co/guide/en/security/current/detections-permissions-section.html#enable-detections-ui) for more information.
|
||||
|
||||
> info
|
||||
> Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) is not included. You must re-add missing connector details after importing detection rules.
|
||||
|
||||
> You can use Kibana’s [Saved Objects](https://www.elastic.co/guide/en/kibana/current/managing-saved-objects.html) UI (Stack Management → Kibana → Saved Objects) or the Saved Objects APIs (experimental) to [export](https://www.elastic.co/docs/api/doc/kibana/operation/operation-exportsavedobjectsdefault) and [import](https://www.elastic.co/docs/api/doc/kibana/operation/operation-importsavedobjectsdefault) any necessary connectors before importing detection rules.
|
||||
|
||||
> Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the [Manage value lists](https://www.elastic.co/guide/en/security/current/value-lists-exceptions.html#manage-value-lists) UI (Rules → Detection rules (SIEM) → Manage value lists) to export and import value lists separately.
|
||||
|
||||
*/
|
||||
importRules(props: ImportRulesProps, kibanaSpace: string = 'default') {
|
||||
|
|
@ -1264,8 +1343,19 @@ finalize it.
|
|||
.send(props.body as object);
|
||||
},
|
||||
/**
|
||||
* Install and update all Elastic prebuilt detection rules and Timelines.
|
||||
*/
|
||||
* Install and update all Elastic prebuilt detection rules and Timelines.
|
||||
|
||||
This endpoint allows you to install and update prebuilt detection rules and Timelines provided by Elastic.
|
||||
When you call this endpoint, it will:
|
||||
- Install any new prebuilt detection rules that are not currently installed in your system.
|
||||
- Update any existing prebuilt detection rules that have been modified or improved by Elastic.
|
||||
- Install any new prebuilt Timelines that are not currently installed in your system.
|
||||
- Update any existing prebuilt Timelines that have been modified or improved by Elastic.
|
||||
|
||||
This ensures that your detection engine is always up-to-date with the latest rules and Timelines,
|
||||
providing you with the most current and effective threat detection capabilities.
|
||||
|
||||
*/
|
||||
installPrebuiltRulesAndTimelines(kibanaSpace: string = 'default') {
|
||||
return supertest
|
||||
.put(routeWithNamespace('/api/detection_engine/rules/prepackaged', kibanaSpace))
|
||||
|
|
@ -1313,8 +1403,15 @@ finalize it.
|
|||
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
|
||||
},
|
||||
/**
|
||||
* Update specific fields of an existing detection rule using the `rule_id` or `id` field.
|
||||
*/
|
||||
* Update specific fields of an existing detection rule using the `rule_id` or `id` field.
|
||||
|
||||
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.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
|
||||
*/
|
||||
patchRule(props: PatchRuleProps, kibanaSpace: string = 'default') {
|
||||
return supertest
|
||||
.patch(routeWithNamespace('/api/detection_engine/rules', kibanaSpace))
|
||||
|
|
@ -1335,8 +1432,13 @@ finalize it.
|
|||
.send(props.body as object);
|
||||
},
|
||||
/**
|
||||
* Apply a bulk action, such as bulk edit, duplicate, or delete, to multiple detection rules. The bulk action is applied to all rules that match the query or to the rules listed by their IDs.
|
||||
*/
|
||||
* Apply a bulk action, such as bulk edit, duplicate, or delete, to multiple detection rules. The bulk action is applied to all rules that match the query or to the rules listed by their IDs.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
|
||||
*/
|
||||
performRulesBulkAction(props: PerformRulesBulkActionProps, kibanaSpace: string = 'default') {
|
||||
return supertest
|
||||
.post(routeWithNamespace('/api/detection_engine/rules/_bulk_action', kibanaSpace))
|
||||
|
|
@ -1412,8 +1514,11 @@ finalize it.
|
|||
.query(props.query);
|
||||
},
|
||||
/**
|
||||
* Retrieve the status of all Elastic prebuilt detection rules and Timelines.
|
||||
*/
|
||||
* Retrieve the status of all Elastic prebuilt detection rules and Timelines.
|
||||
|
||||
This endpoint provides detailed information about the number of custom rules, installed prebuilt rules, available prebuilt rules that are not installed, outdated prebuilt rules, installed prebuilt timelines, available prebuilt timelines that are not installed, and outdated prebuilt timelines.
|
||||
|
||||
*/
|
||||
readPrebuiltRulesAndTimelinesStatus(kibanaSpace: string = 'default') {
|
||||
return supertest
|
||||
.get(routeWithNamespace('/api/detection_engine/rules/prepackaged/_status', kibanaSpace))
|
||||
|
|
@ -1443,8 +1548,16 @@ detection engine rules.
|
|||
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
|
||||
},
|
||||
/**
|
||||
* Retrieve a detection rule using the `rule_id` or `id` field.
|
||||
*/
|
||||
* 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.
|
||||
|
||||
*/
|
||||
readRule(props: ReadRuleProps, kibanaSpace: string = 'default') {
|
||||
return supertest
|
||||
.get(routeWithNamespace('/api/detection_engine/rules', kibanaSpace))
|
||||
|
|
@ -1640,8 +1753,12 @@ detection engine rules.
|
|||
},
|
||||
/**
|
||||
* Update a detection rule using the `rule_id` or `id` field. The original rule is replaced, and all unspecified fields are deleted.
|
||||
> info
|
||||
> You cannot modify the `id` or `rule_id` values.
|
||||
|
||||
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.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
|
||||
*/
|
||||
updateRule(props: UpdateRuleProps, kibanaSpace: string = 'default') {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue