From c8aa530eea04ef56f4dc96192dfc53ae3f779892 Mon Sep 17 00:00:00 2001 From: Maxim Palenov Date: Fri, 5 Jul 2024 15:53:01 +0200 Subject: [PATCH 1/2] Updates related_integrations field API docs (#5183) * allow editing related integrations * improve readability * add an EPR link --------- Co-authored-by: Joe Peeples --- .../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 440d335a4b..82ea9e8ae5 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| {integrations-docs}[Elastic integrations] the rule depends on. The object has these fields: + +* `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`. + |============================================== [[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 a3fdddf55d..3ce24d139c 100644 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ b/docs/detections/api/rules/rules-api-update.asciidoc @@ -288,6 +288,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| {integrations-docs}[Elastic integrations] the rule depends on. The object has these fields: + +* `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`. + |============================================== ===== Optional fields for threat-match rules @@ -641,7 +647,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 } ], @@ -681,4 +689,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 bfdc179947a1a2b669e7abaf83dca58ae6cff718 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Fri, 5 Jul 2024 09:56:30 -0400 Subject: [PATCH 2/2] First draft (#5482) --- docs/release-notes.asciidoc | 1 + docs/release-notes/8.14.asciidoc | 10 ++++++++++ 2 files changed, 11 insertions(+) diff --git a/docs/release-notes.asciidoc b/docs/release-notes.asciidoc index 7ede416432..8b63022e7c 100644 --- a/docs/release-notes.asciidoc +++ b/docs/release-notes.asciidoc @@ -3,6 +3,7 @@ This section summarizes the changes in each release. +* <> * <> * <> * <> diff --git a/docs/release-notes/8.14.asciidoc b/docs/release-notes/8.14.asciidoc index 7f6d8ad971..477d12c701 100644 --- a/docs/release-notes/8.14.asciidoc +++ b/docs/release-notes/8.14.asciidoc @@ -1,6 +1,16 @@ [[release-notes-header-8.14.0]] == 8.14 +[discrete] +[[release-notes-8.14.2]] +=== 8.14.2 + +[discrete] +[[bug-fixes-8.14.2]] +==== Bug fixes + +There are no user-facing changes in 8.14.2. + [discrete] [[release-notes-8.14.1]] === 8.14.1