[DOCS] New rule fields for prerequisites: Related Integrations, Requi…

…red Fields, and Setup (#2069) * Add new section to Advanced Settings * Update page's mini-TOC * Re-adds RNs for 132409 and 131475 * Revise advanced setting description * Create new section for related integrations etc. Includes placeholder image syntax, commented out * Add fields to API response examples * Update release notes * Add new section to What's New Includes placeholder image syntax, commented out * Additional revisions * Complete main documentation Add and update screenshots Revise explanatory text * Update release notes and What's New * Revert changes to whats-new.asciidoc What's new 8.3 will be updated in PR security-docs#2327 * Update per new nav UI * Apply suggestions from Nastasha's review Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com> * Apply suggestions from Ben's review * Update docs/release-notes/8.3.asciidoc Co-authored-by: nastasha.solomon <nastasha.solomon@elastic.co> Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com> (cherry picked from commit 953f781)
elastic · Aug 25, 2022 · 4fdb252 · 4fdb252
1 parent 690a2e9
commit 4fdb252
Show file tree

Hide file tree

Showing 12 changed files with 76 additions and 12 deletions.
diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc
@@ -392,6 +392,9 @@ For `enable`, `disable`, `delete`, `edit`, and `duplicate` actions, a JSON objec
 
                ],
                "immutable":false,
+               "related_integrations": [],       <1>
+               "required_fields": [],            <1>
+               "setup": "",                      <1>
                "type":"machine_learning",
                "anomaly_threshold":50,
                "machine_learning_job_id":[
@@ -432,7 +435,7 @@ For `enable`, `disable`, `delete`, `edit`, and `duplicate` actions, a JSON objec
 }
 --------------------------------------------------
 
-<1> dev:[] `execution_summary` is under development and its schema may change.
+<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, `required_fields`, `setup`, and `execution_summary`.
 
 
 For an `export` action, an `.ndjson` file containing exported rules.
@@ -558,6 +561,9 @@ 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>
+                    "required_fields": [],            <1>
+                    "setup": "",                      <1>
                     "type": "query",
                     "language": "kuery",
                     "index": [
@@ -600,7 +606,7 @@ If processing of any rule fails, a partial error outputs the ID and/or name of t
 }
 --------------------------------------------------
 
-<1> dev:[] `execution_summary` is under development and its schema may change.
+<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, `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
@@ -861,9 +861,14 @@ Example response for a query rule:
   ],
   "throttle": "no_actions",
   "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"
+  "language": "kuery",
+  "related_integrations": [],       <1>
+  "required_fields": [],            <1>
+  "setup": ""                       <1>
 }
 --------------------------------------------------
+<1> dev:[] These fields are under development and their usage may change: `related_integrations`, `required_fields`, and `setup`.
+
 
 Example response for a {ml} job rule:
 
@@ -911,9 +916,13 @@ Example response for a {ml} job rule:
   "status": "going to run",
   "status_date": "2020-04-07T14:45:21.685Z",
   "anomaly_threshold": 70,
-  "machine_learning_job_id": "linux_anomalous_network_activity_ecs"
+  "machine_learning_job_id": "linux_anomalous_network_activity_ecs",
+  "related_integrations": [],       <1>
+  "required_fields": [],            <1>
+  "setup": ""                       <1>
 }
 --------------------------------------------------
+<1> dev:[] These fields are under development and their usage may change: `related_integrations`, `required_fields`, and `setup`.
 
 Example response for a threshold rule:
 
@@ -990,9 +999,13 @@ Example response for a threshold rule:
   "threshold": {
     "field": "source.ip",
     "value": 20
-  }
+  },
+  "related_integrations": [],       <1>
+  "required_fields": [],            <1>
+  "setup": ""                       <1>
 }
 --------------------------------------------------
+<1> dev:[] These fields are under development and their usage may change: `related_integrations`, `required_fields`, and `setup`.
 
 Example response for an EQL rule:
 
@@ -1033,9 +1046,13 @@ Example response for an EQL rule:
   "actions": [],
   "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"
+  "language": "eql",
+  "related_integrations": [],       <1>
+  "required_fields": [],            <1>
+  "setup": ""                       <1>
 }
 --------------------------------------------------
+<1> dev:[] These fields are under development and their usage may change: `related_integrations`, `required_fields`, and `setup`.
 
 Example response for an indicator match rule:
 
@@ -1104,6 +1121,10 @@ Example response for an indicator match rule:
         }
       ]
     }
-  ]
+  ],
+  "related_integrations": [],       <1>
+  "required_fields": [],            <1>
+  "setup": ""                       <1>
 }
 --------------------------------------------------
+<1> dev:[] These fields are under development and their usage may change: `related_integrations`, `required_fields`, and `setup`.
diff --git a/docs/detections/api/rules/rules-api-find.asciidoc b/docs/detections/api/rules/rules-api-find.asciidoc
@@ -97,6 +97,9 @@ Example response:
         "Windows"
       ],
       "to": "now",
+      "related_integrations": [],       <1>
+      "required_fields": [],            <1>
+      "setup": "",                      <1>
       "type": "query",
       "threat": [
         {
@@ -136,4 +139,4 @@ Example response:
 
 --------------------------------------------------
 
-<1> dev:[] `execution_summary` is under development and its schema may change.
+<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, `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
@@ -61,6 +61,9 @@ Example response:
   "immutable": false,
   "interval": "1h",
   "rule_id": "process_started_by_ms_office_user_folder",
+  "related_integrations": [],       <1>
+  "required_fields": [],            <1>
+  "setup": "",                      <1>
   "language": "kuery",
   "output_index": ".siem-signals-siem-test",
   "max_signals": 100,
@@ -111,4 +114,4 @@ Example response:
 
 --------------------------------------------------
 
-<1> dev:[] `execution_summary` is under development and its schema may change.
+<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, `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
@@ -509,6 +509,9 @@ Example response:
     "child process",
     "ms office"
   ],
+  "related_integrations": [],       <1>
+  "required_fields": [],            <1>
+  "setup": "",                      <1>
   "type": "query",
   "threat": [
     {
@@ -544,4 +547,4 @@ Example response:
 }
 --------------------------------------------------
 
-<1> dev:[] `execution_summary` is under development and its schema may change.
+<1> dev:[] These fields are under development and their usage or schema may change: `related_integrations`, `required_fields`, `setup`, and `execution_summary`.
diff --git a/docs/detections/images/all-rules.png b/docs/detections/images/all-rules.png
diff --git a/docs/detections/images/monitor-table.png b/docs/detections/images/monitor-table.png
diff --git a/docs/detections/images/rule-details-prerequisites.png b/docs/detections/images/rule-details-prerequisites.png
diff --git a/docs/detections/images/rules-table-related-integrations.png b/docs/detections/images/rules-table-related-integrations.png
diff --git a/docs/detections/rules-ui-manage.asciidoc b/docs/detections/rules-ui-manage.asciidoc
@@ -13,6 +13,7 @@ On the Rules page, you can:
 * <<load-prebuilt-rules>>
 * <<select-all-prebuilt-rules>>
 * <<download-prebuilt-rules>>
+* <<rule-prerequisites>>
 * <<edit-rules-settings>>
 * <<manage-rules-ui>>
 * <<import-export-rules-ui>>
@@ -36,7 +37,7 @@ NOTE: Searches for index patterns and MITRE ATT&CK tactics and techniques must m
 
 [float]
 [[load-prebuilt-rules]]
-=== Load and activate prebuilt Elastic rules
+=== Load and activate Elastic prebuilt rules
 
 To load the {es-sec-app}'s <<prebuilt-rules, prebuilt rules>>, go to *Manage* -> *Rules* -> *Load Elastic prebuilt rules and Timeline templates*.
 
@@ -63,7 +64,7 @@ You can then modify the duplicated rules and, if required, delete the prebuilt o
 
 [float]
 [[download-prebuilt-rules]]
-=== Download latest prebuilt Elastic rules
+=== Download latest Elastic prebuilt rules
 
 As of {stack} >=7.13.0, you can download the latest version of Elastic prebuilt rules outside of a regular release cycle. This feature ensures you have the latest detection capabilities before upgrading to the latest {stack}.
 
@@ -82,6 +83,24 @@ image::images/install-prebuilt-settings.png[]
 [role="screenshot"]
 image::images/install-prebuilt-rules.png[]
 
+[float]
+[[rule-prerequisites]]
+=== Confirm rule prerequisites
+
+Many Elastic prebuilt rules are designed to work with specific Elastic integrations and data fields. These prerequisites are identified in the *Related integrations* and *Required fields* fields on a rule's details page (*Manage* -> *Rules*, then click a rule's name). *Related integrations* also displays each integration's installation status and includes links for installing and configuring the listed integrations. 
+
+Additionally, the *Setup guide* section provides guidance on setting up the rule's requirements.
+
+[role="screenshot"]
+image::images/rule-details-prerequisites.png[Rule details page with Related integrations, Required fields, and Setup guide highlighted]
+
+You can also check rules' related integrations in the *Rules* and *Rule Monitoring* tables. Click the *integrations* badge to display the related integrations in a popup.
+
+[role="screenshot"]
+image::images/rules-table-related-integrations.png[Rules table with related integrations popup,75%]
+
+TIP: You can hide the *integrations* badge in the Rules tables. Go to *{kib}* -> *Stack Management* -> *Advanced Settings*, then turn off `securitySolution:showRelatedIntegrations`.
+
 [float]
 [[edit-rules-settings]]
 === Modify existing rules settings

diff --git a/docs/getting-started/advanced-setting.asciidoc b/docs/getting-started/advanced-setting.asciidoc
@@ -12,6 +12,7 @@ The advanced settings determine:
 * Which IP reputation links appear on <<network-page-overview, IP detail>>
 pages
 * Whether cross-cluster search (CCS) privilege warnings are displayed
+* Whether related integrations are displayed on the Rules page tables
 
 You need `All` privileges for the *Advanced Settings* feature to change these
 settings (refer to {kibana-ref}/kibana-privileges.html[Kibana privileges]).
@@ -161,3 +162,9 @@ Adds a link to \https://www.dnschecker.org on *IP detail* pages:
 Each time a detection rule runs using a remote cross-cluster search (CCS) index pattern, it will return a warning saying that the rule may not have the required `read` privileges to the remote index. Because privileges cannot be checked across remote indices, this warning displays even when the rule actually does have `read` privileges to the remote index.
 
 If you've ensured that your detection rules have the required privileges across your remote indices, you can use the `securitySolution:enableCcsWarning` setting to disable this warning and reduce noise.
+
+[discrete]
+[[show-related-integrations]]
+== Show/hide related integrations in Rules page tables
+
+By default, Elastic prebuilt rules in the *Rules* and *Rule Monitoring* tables include a badge showing how many related integrations have been installed. Turn off `securitySolution:showRelatedIntegrations` to hide this in the rules tables (related integrations will still appear on rule details pages).
diff --git a/docs/release-notes/8.3.asciidoc b/docs/release-notes/8.3.asciidoc
@@ -157,6 +157,8 @@ On the next scheduled rule execution, the *Last Response* value for the rule wil
 * Provides an option to select a severity level for a case ({pull}131626[#131626]).
 * Adds the experimental *Alerts* tab to cases, which allows users to inspect attached alerts ({pull}131883[#131883]).
 * Adds the *Average time to close* metric to the Cases page ({pull}131909[#131909]).
+* Adds new fields to prebuilt detection rules' schemas: `related_integrations`, `required_fields`, and `setup` ({pull}132409[#132409]).
+* Adds the *Related integrations*, *Required fields*, and *Setup guide* sections to the rule details page to help users identify and meet a rule's prerequisites. Also adds the related integrations badge to the Rules table ({pull}131475[#131475]). Content for these new sections is delivered in a prebuilt rules update, independent of {stack} release versioning.
 
 [discrete]
 [[bug-fixes-8.3.0]]