Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[8.15] Updates related_integrations field API docs (backport #5183) #5509

Merged
merged 1 commit into from
Jul 5, 2024
Merged

[8.15] Updates related_integrations field API docs (backport #5183) #5509

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/detections/api/rules/rules-api-bulk-actions.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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*

Expand Down
44 changes: 29 additions & 15 deletions docs/detections/api/rules/rules-api-create.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand Down Expand Up @@ -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
}
--------------------------------------------------
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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 },
Expand All @@ -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:

Expand Down Expand Up @@ -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 },
Expand All @@ -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:

Expand Down Expand Up @@ -1529,15 +1541,16 @@ 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 }
],
"setup": ""
}
--------------------------------------------------
<1> dev:[] These fields are under development and their usage may change: `related_integrations`.

Example response for an {esql} rule:

Expand Down Expand Up @@ -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 }
],
Expand All @@ -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`.
6 changes: 4 additions & 2 deletions docs/detections/api/rules/rules-api-find.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 },
Expand Down Expand Up @@ -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`.
6 changes: 4 additions & 2 deletions docs/detections/api/rules/rules-api-get.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
Expand Down Expand Up @@ -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`.
12 changes: 10 additions & 2 deletions docs/detections/api/rules/rules-api-update.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 }
],
Expand Down Expand Up @@ -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`.