From a1a5336d3e154e7544ad3831731ddc9f6d373e73 Mon Sep 17 00:00:00 2001 From: Maxim Palenov Date: Wed, 8 May 2024 12:46:29 +0200 Subject: [PATCH 1/3] allow editing related integrations --- .../api/rules/rules-api-bulk-actions.asciidoc | 8 ++-- .../api/rules/rules-api-create.asciidoc | 44 ++++++++++++------- .../api/rules/rules-api-find.asciidoc | 6 ++- .../api/rules/rules-api-get.asciidoc | 6 ++- .../api/rules/rules-api-update.asciidoc | 12 ++++- 5 files changed, 51 insertions(+), 25 deletions(-) diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc index 1fc09ef8f6..9e5bfca580 100644 --- a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc +++ b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc @@ -583,7 +583,7 @@ A rule can only be `skipped` when the bulk action to be performed on it results ], "immutable":false, - "related_integrations": [], <1> + "related_integrations": [], "required_fields": [], "setup": "", "type":"machine_learning", @@ -626,7 +626,7 @@ A rule can only be `skipped` when the bulk action to be performed on it results } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, `required_fields`, and `execution_summary`. +<1> dev:[] These fields are under development and their usage or schema may change: `execution_summary`. For an `export` action, an `.ndjson` file containing exported rules. @@ -751,7 +751,7 @@ If processing of any rule fails, a partial error outputs the ID and/or name of t "version": 5, "exceptions_list": [], "immutable": false, - "related_integrations": [], <1> + "related_integrations": [], "required_fields": [], "setup": "", "type": "query", @@ -797,7 +797,7 @@ If processing of any rule fails, a partial error outputs the ID and/or name of t } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations` and `execution_summary`. +<1> dev:[] These fields are under development and their usage or schema may change: `execution_summary`. *Example 3, Dry run* diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 0b60cba3de..7329409b94 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -388,6 +388,12 @@ Required when `actions` are used to send notifications. * `field_names`: String[] , required +|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields: + +* `package` (String, required): Integration package's name EPR uses +* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations. +* `version`: (String, required): Integration (package containing the integration) version constraint in https://semver.org/[semantic versioning] format. For version ranges, you must use tilde or caret syntax. For example, `~1.2.3` is from 1.2.3 to any patch version less than `1.3.0`, and `^1.2.3` is from `1.2.3`` to any minor and patch version less than `2.0.0`. + |============================================== [[opt-fields-threat-match]] @@ -826,6 +832,9 @@ POST api/detection_engine/rules "required_fields": [ { name: "process.parent.name", "type": "keyword" } ], + "related_integrations": [ + { "package": "o365", "version": "^2.3.2"} + ], "enabled": false } -------------------------------------------------- @@ -1213,15 +1222,16 @@ Example response for a query rule: ], "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": [], <1> + "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": "" } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage may change: `related_integrations`. - Example response for a {ml} job rule: @@ -1273,12 +1283,11 @@ Example response for a {ml} job rule: "status_date": "2020-04-07T14:45:21.685Z", "anomaly_threshold": 70, "machine_learning_job_id": "linux_anomalous_network_activity_ecs", - "related_integrations": [], <1> + "related_integrations": [], "required_fields": [], "setup": "" } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage may change: `related_integrations`. Example response for a threshold rule: @@ -1354,14 +1363,15 @@ Example response for a threshold rule: "field": "source.ip", "value": 20 }, - "related_integrations": [], <1> + "related_integrations": [ + { "package": "o365", "version": "^2.3.2" } + ], "required_fields": [ { "name": "source.ip", "type": "ip", "ecs": true } ], "setup": "" } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage may change: `related_integrations`. Example response for an EQL rule: @@ -1401,7 +1411,9 @@ Example response for an EQL rule: "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": [], <1> + "related_integrations": [ + { "package": "o365", "version": "^2.3.2" } + ], "required_fields": [ { "name": "event.type", "type": "keyword", "ecs": true }, { "name": "process.args", "type": "keyword", "ecs": true }, @@ -1413,7 +1425,6 @@ Example response for an EQL rule: "setup": "" } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage may change: `related_integrations`. Example response for an indicator match rule: @@ -1480,7 +1491,9 @@ Example response for an indicator match rule: ] } ], - "related_integrations": [], <1> + "related_integrations": [ + { "package": "o365", "version": "^2.3.2" } + ], "required_fields": [ { "name": "destination.ip", "type": "ip", "ecs": true }, { "name": "destination.port", "type": "long", "ecs": true }, @@ -1489,7 +1502,6 @@ Example response for an indicator match rule: "setup": "" } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage may change: `related_integrations`. Example response for a new terms rule: @@ -1529,7 +1541,9 @@ Example response for a new terms rule: "language": "kuery", "new_terms_fields": ["user.id", "source.ip"], "history_window_start": "now-30d", - "related_integrations": [], <1> + "related_integrations": [ + { "package": "o365", "version": "^2.3.2" } + ], "required_fields": [ { "name": "user.id", "type": "keyword", "ecs": true }, { "name": "source.ip", "type": "ip", "ecs": true } @@ -1537,7 +1551,6 @@ Example response for a new terms rule: "setup": "" } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage may change: `related_integrations`. Example response for an {esql} rule: @@ -1572,7 +1585,9 @@ Example response for an {esql} rule: "revision": 0, "rule_id": "e4b53a89-debd-4a0d-a3e3-20606952e589", "immutable": false, - "related_integrations": [], <1> + "related_integrations": [ + { "package": "o365", "version": "^2.3.2" } + ], "required_fields": [ { "name": "process.parent.name", "type": "keyword", "ecs": true } ], @@ -1582,4 +1597,3 @@ Example response for an {esql} rule: "query": "from auditbeat-8.10.2 METADATA _id | where process.parent.name == \"EXCEL.EXE\"" } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage may change: `related_integrations`. diff --git a/docs/detections/api/rules/rules-api-find.asciidoc b/docs/detections/api/rules/rules-api-find.asciidoc index 8997a58f1a..0d3df2c205 100644 --- a/docs/detections/api/rules/rules-api-find.asciidoc +++ b/docs/detections/api/rules/rules-api-find.asciidoc @@ -96,7 +96,9 @@ Example response: "Windows" ], "to": "now", - "related_integrations": [], <1> + "related_integrations": [ + { "package": "o365", "version": "^2.3.2"} + ], "required_fields": [ { "name": "event.action", "type": "keyword", "ecs": true }, { "name": "process.name", "type": "keyword", "ecs": true }, @@ -142,4 +144,4 @@ Example response: -------------------------------------------------- -<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations` and `execution_summary`. +<1> dev:[] These fields are under development and their usage or schema may change: `execution_summary`. diff --git a/docs/detections/api/rules/rules-api-get.asciidoc b/docs/detections/api/rules/rules-api-get.asciidoc index 7c85435d6e..66248aa203 100644 --- a/docs/detections/api/rules/rules-api-get.asciidoc +++ b/docs/detections/api/rules/rules-api-get.asciidoc @@ -61,7 +61,9 @@ Example response: "immutable": false, "interval": "1h", "rule_id": "process_started_by_ms_office_user_folder", - "related_integrations": [], <1> + "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 } @@ -116,4 +118,4 @@ Example response: -------------------------------------------------- -<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, and `execution_summary`. +<1> dev:[] These fields are under development and their usage or schema may change: `execution_summary`. diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc index 6171e426e2..382dce8616 100644 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ b/docs/detections/api/rules/rules-api-update.asciidoc @@ -286,6 +286,12 @@ rule's version number is incremented by 1. `PATCH` calls enabling and disabling the rule do not increment its version number. +|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields: + +* `package` (String, required): Integration package's name EPR uses +* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations. +* `version`: (String, required): Integration (package containing the integration) version constraint in https://semver.org/[semantic versioning] format. For version ranges, you must use tilde or caret syntax. For example, `~1.2.3` is from 1.2.3 to any patch version less than `1.3.0`, and `^1.2.3` is from `1.2.3`` to any minor and patch version less than `2.0.0`. + |============================================== ===== Optional fields for threat-match rules @@ -639,7 +645,9 @@ Example response: "child process", "ms office" ], - "related_integrations": [], <1> + "related_integrations": [ + { "package": "o365", "version": "^2.3.2"} + ], "required_fields": [ { "name": "process.parent.name", "type": "keyword", "ecs": true } ], @@ -679,4 +687,4 @@ Example response: } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, and `execution_summary`. +<1> dev:[] These fields are under development and their usage or schema may change: `execution_summary`. From e8dbbbbf32db9927ec0b9c5856656cbcb15d4b36 Mon Sep 17 00:00:00 2001 From: Maxim Palenov Date: Wed, 22 May 2024 13:08:51 +0200 Subject: [PATCH 2/3] improve readability --- docs/detections/api/rules/rules-api-create.asciidoc | 4 ++-- docs/detections/api/rules/rules-api-update.asciidoc | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 7329409b94..03a572bc9f 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -388,10 +388,10 @@ Required when `actions` are used to send notifications. * `field_names`: String[] , required -|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields: +|related_integrations |Object[] a| {integrations-docs}[Elastic integrations] the rule depends on. The object has these fields: * `package` (String, required): Integration package's name EPR uses -* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations. +* `integration` (String, optional): The integration's name. This field is optional for packages with only one integration whose name matches the package name, but it's required for packages with multiple integrations. * `version`: (String, required): Integration (package containing the integration) version constraint in https://semver.org/[semantic versioning] format. For version ranges, you must use tilde or caret syntax. For example, `~1.2.3` is from 1.2.3 to any patch version less than `1.3.0`, and `^1.2.3` is from `1.2.3`` to any minor and patch version less than `2.0.0`. |============================================== diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc index 382dce8616..dc7768b523 100644 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ b/docs/detections/api/rules/rules-api-update.asciidoc @@ -286,10 +286,10 @@ rule's version number is incremented by 1. `PATCH` calls enabling and disabling the rule do not increment its version number. -|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields: +|related_integrations |Object[] a| {integrations-docs}[Elastic integrations] the rule depends on. The object has these fields: * `package` (String, required): Integration package's name EPR uses -* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations. +* `integration` (String, optional): The integration's name. This field is optional for packages with only one integration whose name matches the package name, but it's required for packages with multiple integrations. * `version`: (String, required): Integration (package containing the integration) version constraint in https://semver.org/[semantic versioning] format. For version ranges, you must use tilde or caret syntax. For example, `~1.2.3` is from 1.2.3 to any patch version less than `1.3.0`, and `^1.2.3` is from `1.2.3`` to any minor and patch version less than `2.0.0`. |============================================== From a191acc0871245b8900acd725e7f7779b384f48f Mon Sep 17 00:00:00 2001 From: Maxim Palenov Date: Thu, 23 May 2024 11:00:02 +0200 Subject: [PATCH 3/3] add an EPR link --- docs/detections/api/rules/rules-api-create.asciidoc | 2 +- docs/detections/api/rules/rules-api-update.asciidoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 03a572bc9f..923a64696b 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -390,7 +390,7 @@ Required when `actions` are used to send notifications. |related_integrations |Object[] a| {integrations-docs}[Elastic integrations] the rule depends on. The object has these fields: -* `package` (String, required): Integration package's name EPR uses +* `package` (String, required): The integration package's name, as used by the https://github.com/elastic/package-registry[Elastic Package Registry]. * `integration` (String, optional): The integration's name. This field is optional for packages with only one integration whose name matches the package name, but it's required for packages with multiple integrations. * `version`: (String, required): Integration (package containing the integration) version constraint in https://semver.org/[semantic versioning] format. For version ranges, you must use tilde or caret syntax. For example, `~1.2.3` is from 1.2.3 to any patch version less than `1.3.0`, and `^1.2.3` is from `1.2.3`` to any minor and patch version less than `2.0.0`. diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc index dc7768b523..bd6d0a50c9 100644 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ b/docs/detections/api/rules/rules-api-update.asciidoc @@ -288,7 +288,7 @@ number. |related_integrations |Object[] a| {integrations-docs}[Elastic integrations] the rule depends on. The object has these fields: -* `package` (String, required): Integration package's name EPR uses +* `package` (String, required): The integration package's name, as used by the https://github.com/elastic/package-registry[Elastic Package Registry]. * `integration` (String, optional): The integration's name. This field is optional for packages with only one integration whose name matches the package name, but it's required for packages with multiple integrations. * `version`: (String, required): Integration (package containing the integration) version constraint in https://semver.org/[semantic versioning] format. For version ranges, you must use tilde or caret syntax. For example, `~1.2.3` is from 1.2.3 to any patch version less than `1.3.0`, and `^1.2.3` is from `1.2.3`` to any minor and patch version less than `2.0.0`.