From c8f2511336debe950c2e2be64d95cad4dce4382b Mon Sep 17 00:00:00 2001 From: Maxim Palenov Date: Wed, 8 May 2024 12:46:29 +0200 Subject: [PATCH] allow editing related integrations --- .../api/rules/rules-api-bulk-actions.asciidoc | 8 ++-- .../api/rules/rules-api-create.asciidoc | 42 ++++++++++++------- .../api/rules/rules-api-find.asciidoc | 4 +- .../api/rules/rules-api-get.asciidoc | 4 +- .../api/rules/rules-api-update.asciidoc | 12 +++++- 5 files changed, 46 insertions(+), 24 deletions(-) diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc index 23339d815e9..36ad61fce77 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": [], <1> "setup": "", <1> "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`, `setup`, and `execution_summary`. +<1> dev:[] These fields are under development and their usage or schema may change: `required_fields`, `setup`, and `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": [], <1> "setup": "", <1> "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`, `required_fields`, `setup`, and `execution_summary`. +<1> dev:[] These fields are under development and their usage or schema may change: `required_fields`, `setup`, and `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 621d3fe1020..b87584db1ac 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -380,6 +380,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]] @@ -815,6 +821,9 @@ POST api/detection_engine/rules } } ], + "related_integrations": [ + { "package": "o365", "version": "^2.3.2"} + ], "enabled": false } -------------------------------------------------- @@ -1179,12 +1188,15 @@ 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": [], <1> "setup": "" } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage may change: `related_integrations` and `required_fields`. +<1> dev:[] These fields are under development and their usage may change: `required_fields`. Example response for a {ml} job rule: @@ -1237,12 +1249,12 @@ 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": [], <1> "setup": "" } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage may change: `related_integrations` and `required_fields`. +<1> dev:[] These fields are under development and their usage may change: `required_fields`. Example response for a threshold rule: @@ -1318,12 +1330,12 @@ Example response for a threshold rule: "field": "source.ip", "value": 20 }, - "related_integrations": [], <1> + "related_integrations": [], "required_fields": [], <1> "setup": "" } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage may change: `related_integrations` and `required_fields`. +<1> dev:[] These fields are under development and their usage may change: `required_fields`. Example response for an EQL rule: @@ -1363,12 +1375,12 @@ 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": [], "required_fields": [], <1> "setup": "" } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage may change: `related_integrations` and `required_fields`. +<1> dev:[] These fields are under development and their usage may change: `required_fields`. Example response for an indicator match rule: @@ -1435,12 +1447,12 @@ Example response for an indicator match rule: ] } ], - "related_integrations": [], <1> + "related_integrations": [], "required_fields": [], <1> "setup": "" } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage may change: `related_integrations` and `required_fields`. +<1> dev:[] These fields are under development and their usage may change: `required_fields`. Example response for a new terms rule: @@ -1480,12 +1492,14 @@ 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": "system", "version": "^1.55.2" }, + ], "required_fields": [], <1> "setup": "" } -------------------------------------------------- -<1> dev:[] These fields are under development and their usage may change: `related_integrations` and `required_fields`. +<1> dev:[] These fields are under development and their usage may change: `required_fields`. Example response for an {esql} rule: @@ -1520,7 +1534,7 @@ Example response for an {esql} rule: "revision": 0, "rule_id": "e4b53a89-debd-4a0d-a3e3-20606952e589", "immutable": false, - "related_integrations": [], <1> + "related_integrations": [], "required_fields": [], <1> "setup": "", "type": "esql", @@ -1528,4 +1542,4 @@ 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` and `required_fields`. +<1> dev:[] These fields are under development and their usage may change: `required_fields`. diff --git a/docs/detections/api/rules/rules-api-find.asciidoc b/docs/detections/api/rules/rules-api-find.asciidoc index 486c0e902c4..cba633605f1 100644 --- a/docs/detections/api/rules/rules-api-find.asciidoc +++ b/docs/detections/api/rules/rules-api-find.asciidoc @@ -96,7 +96,7 @@ Example response: "Windows" ], "to": "now", - "related_integrations": [], <1> + "related_integrations": [], "required_fields": [], <1> "setup": "", <1> "type": "query", @@ -138,4 +138,4 @@ Example response: -------------------------------------------------- -<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, `required_fields`, `setup`, and `execution_summary`. +<1> dev:[] These fields are under development and their usage or schema may change: `required_fields`, `setup`, and `execution_summary`. diff --git a/docs/detections/api/rules/rules-api-get.asciidoc b/docs/detections/api/rules/rules-api-get.asciidoc index 4e5792abd46..8c43390ec9c 100644 --- a/docs/detections/api/rules/rules-api-get.asciidoc +++ b/docs/detections/api/rules/rules-api-get.asciidoc @@ -61,7 +61,7 @@ Example response: "immutable": false, "interval": "1h", "rule_id": "process_started_by_ms_office_user_folder", - "related_integrations": [], <1> + "related_integrations": [], "required_fields": [], <1> "setup": "", <1> "language": "kuery", @@ -113,4 +113,4 @@ Example response: -------------------------------------------------- -<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, `required_fields`, `setup`, and `execution_summary`. +<1> dev:[] These fields are under development and their usage or schema may change: `required_fields`, `setup`, and `execution_summary`. diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc index 06d267226b5..2069673a4c8 100644 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ b/docs/detections/api/rules/rules-api-update.asciidoc @@ -278,6 +278,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 @@ -631,7 +637,9 @@ Example response: "child process", "ms office" ], - "related_integrations": [], <1> + "related_integrations": [ + { "package": "o365", "version": "^2.3.2"} + ], "required_fields": [], <1> "setup": "", "type": "query", @@ -669,4 +677,4 @@ Example response: } -------------------------------------------------- -<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: `required_fields`, and `execution_summary`.