elastic · nastasha-solomon · Jul 25, 2022 · Jul 25, 2022 · Jul 25, 2022 · Jul 25, 2022
@@ -9,23 +9,10 @@ Please view this template for guidance on creating issues: https://github.com/el
 ## Contributing to Elastic Security docs
 
 If you are an Elastic employee and would like to contribute to Elastic Security documentation: 
-
 1. Please clone and fork the `security-docs` repo. 
 2. Open an issue using the appropriate [template](https://github.com/elastic/security-docs/tree/master/.github/ISSUE_TEMPLATE).
 3. Check out the `main` branch and fetch the latest changes. 
 4. Check out a new branch and make your changes. 
 5. Save your changes and open a pull request. 
-6. Add the `[@elastic/security-docs](https://github.com/orgs/elastic/teams/security-docs)` team and any other appropriate members as reviewers. 
-7. Add the appropriate release version label, backport version label if appropriate, and team label to the PR. 
-8. Once the docs team approves all changes, you can merge it. If a backport version label was added to a PR for stack versions 7.14.0 and newer, mergify will automatically open a backport PR. 
-9. Merge the backport PR once it passes all CI checks. 
-
-### Preview documentation changes
-
-Once the PR is opened, and the build complete, the changes can be previewed via this URL (replace `<YOUR_PR_NUMBER_HERE>` with the PR number):
-
-```
-https://security-docs_<YOUR_PR_NUMBER_HERE>.docs-preview.app.elstc.co/guide/en/security/master
-```
-
+6. Tag the the `@security-docs` team and any other appropriate reviewers. We'll take care of merging and backporting.  
 
@@ -4,10 +4,10 @@
 
 You can push {es-sec} cases to these third-party systems:
 
-* {sn-itsm}
-* {sn-sir}
 * {jira} (including Jira Service Desk)
 * {ibm-r}
+* {sn-itsm}
+* {sn-sir}
 * {swimlane}
 * {webhook-cm}
 
@@ -25,14 +25,90 @@ https://www.elastic.co/subscriptions[appropriate license], and your role needs *
 [role="screenshot"]
 image::images/cases-ui-connector.png[Shows the page for creating connectors]
 . From the *Incident management system* list, select *Add new connector*.
-. Select the system to send cases to: *{sn}*, *{jira}*, *{ibm-r}*, *{swimlane}*, or *{webhook-cm}*.
-. Enter your required settings. For connector configuration details, refer to:
-- {kibana-ref}/servicenow-action-type.html[{sn-itsm} connector]
-- {kibana-ref}/servicenow-sir-action-type.html[{sn-sir} connector]
-- {kibana-ref}/jira-action-type.html[{jira} connector]
-- {kibana-ref}/resilient-action-type.html[{ibm-r} connector]
-- {kibana-ref}/swimlane-action-type.html[{swimlane} connector]
-- {kibana-ref}/cases-webhook-action-type.html[{webhook-cm} connector]
+. Select the system to send cases to *{sn}*, *{jira}*, *{ibm-r}*, or *{swimlane}*.
+
+. Enter a name for the connector, provide the required settings, and then save it.
++
+** For {jira} connectors:
+
+* *URL*: The URL of the external system to which you want to send cases.
+* *Project key*: The key of the {jira} project to which you are sending cases.
+* *Email address*: The {jira} account username or email.
+* *API token*: The API token or password is used to authenticate {jira} updates.
+
+** For {ibm-r} connectors:
+
+* *URL*: The URL of the external system to which you want to send cases.
+* *Organization ID*: Your organization’s {ibm-r} ID number.
+* *API key ID*: The API key used to authenticate {ibm-r} updates.
+* *API key secret*: The API key secret used to authenticate {ibm-r} updates.
+
+** For {sn} connectors:
++
+IMPORTANT: If you've upgraded from {stack} version 7.15.0 or earlier to 7.16.0 or later, you must complete several prerequisites before creating a new {sn-itsm} or {sn-sir} connector. For more information, refer to prerequisites for {kibana-ref}/servicenow-action-type.html#servicenow-itsm-connector-prerequisites[{sn-itsm}] and {kibana-ref}/servicenow-sir-action-type.html#servicenow-sir-connector-prerequisites[{sn-sir}].
++
+
+* *{sn} instance URL*: The URL of the {sn} instance to which you want to send cases.
+* *Use OAuth authentication*: Enable this to use open authorization (OAuth) to authenticate a connection between Elastic and {sn}.
++
+NOTE: To use open authorization (OAuth), you must {kibana-ref}/servicenow-action-type.html#servicenow-itsm-connector-prerequisites-rsa-key[create an RSA keypair and add an X.509 Certificate] and also {kibana-ref}/servicenow-action-type.html#servicenow-itsm-connector-prerequisites-endpoint[create an OAuth JWT API endpoint for external clients with a JWT Verifiers Map.]
++
+
+* *Username*: (Displays if *Use OAuth authentication* is turned _off_.) The username of the {sn} account used to access the {sn} instance.
+* *Password*: (Displays if *Use OAuth authentication* is turned _off_.) The password of the {sn} account used to access the {sn} instance.
+* *Client ID*: (Displays if *Use OAuth authentication* is turned _on_.) The client ID assigned to your OAuth application.
+* *User Identifier*: (Displays if *Use OAuth authentication* is turned _on_.) Identifier to use for OAuth type authentication. Use the value you entered into the *User field* when you created an OAuth JWT API endpoint for external clients.
+* *JWT Verifier Key ID*: (Displays if *Use OAuth authentication* is turned _on_.)
+The key ID assigned to the JWT Verifier Map of your OAuth application.
+* *Client Secret*: (Displays if *Use OAuth authentication* is turned _on_.) The client secret assigned to your OAuth application.
+* *Private Key*: (Displays if *Use OAuth authentication* is turned _on_.)
+The RSA private key generated when you created an RSA keypair.
+* *Private Key Password*: (Displays if *Use OAuth authentication* is turned _on_.) The password for the RSA private key generated during setup, if set.
+
+** For {swimlane} connectors:
+
+* *API URL*: The URL of the {swimlane} instance to which you want to send cases.
+* *Application ID*: The application ID of your {swimlane} application. From {swimlane}, you can find the application
+ID by checking your application’s settings or at the end of your application’s URL after you’ve opened it.
+* *API token*: The {swimlane} API authentication token used for HTTP Basic authentication.
+This is the personal access token for your user role.
+* *Connector Type*: Select a connector type:
+*** *All*: You can choose to set all or no field mappings when creating your new {swimlane} connector. However, note that if you don’t set field mappings now, you’ll be prompted to do so if you want to use the connector for a case or a rule.
-*** *All*: You can choose to set all or no field mappings when creating your new {swimlane} connector. However, note that if you don’t set field mappings now, you’ll be prompted to do so if you want to use the connector for a case or a rule.
+*** *All*: You can choose to set all or no field mappings when creating your new {swimlane} connector. However, note that if you don’t set field mappings now, you’ll be prompted to do so before you use the connector for a case or a rule.
-*** *All*: You can choose to set all or no field mappings when creating your new {swimlane} connector. However, note that if you don’t set field mappings now, you’ll be prompted to do so if you want to use the connector for a case or a rule.
+*** *All*: You can choose to set all or no field mappings when creating your new {swimlane} connector. However, note that if you don’t set field mappings now, you’ll be prompted to do so before you use the connector for a case or a rule.
+*** *Alerts*: Provide an alert ID and rule name.
+*** *Cases*: Provide a case ID, a case name, comments, and a description.
+
+
+[float]
+[[mapped-case-fields]]
+=== Mapped case fields
+
+To represent an {es-sec} case in an external system, {es-sec} case fields are mapped to existing fields in {sn}, {jira}, {ibm-r}, and {swimlane}. Once fields are mapped, you can push updates to external systems and mapped fields are overwritten or appended. Retrieving data from external systems is not supported.
+
+|===
+
+| *Case field* | *Mapped field*
+
+| Title
+
+a| The case `Title` field is mapped to corresponding fields in external systems. Mapped field values are overwritten when you push updates.
+
+* *{sn}*: Mapped to the `Short description` field.
+* *{jira}*: Mapped to the `Summary` field.
+* *{ibm-r}*: Mapped to the `Name` field.
+* *{swimlane}*: Mapped to the `Description` field.
+
+| Description
+| The case `Description` field is mapped to the `Description` field in {sn}, {jira}, {ibm-r}, and {swimlane}. Mapped field values are overwritten when you push updates.
+
+| Comments
+
+a| For {sn} connctors, the case `Comments` field is mapped to the `Work Notes` field in {sn}.
+
+For {jira}, {ibm-r}, and {swimlane} connectors, the case `Comments` field is mapped to the `Comments` field in {jira}, {ibm-r}, and {swimlane}.
+
+New and edited comments are added to incident records when pushed to {sn}, {jira}, or {ibm-r}. Comments pushed to {swimlane} are appended to the `Comment` field in {swimlane} and posted individually.
+
+|===
 
 [[close-connector]]
 [float]

@@ -39,7 +39,7 @@ NOTE: When updating alert results to include building block alerts, the Security
 [role="screenshot"]
 image::images/additional-filters.png[Alerts table with Additional filters menu highlighted]
 
-* View detection alerts generated by a specific rule. Go to *Manage* -> *Rules*, then select a rule name in the table. The rule details page displays a comprehensive view of the rule's settings, and the Alerts table under the Trend histogram displays the alerts associated with the rule, including alerts from any previous or deleted revision of that rule.
+* View detection alerts generated by a specific rule. Go to *Detect* -> *Rules*, then select a rule name in the table. The rule details page displays a comprehensive view of the rule's settings, and the Alerts table under the Trend histogram displays the alerts associated with the rule, including alerts from any previous or deleted revision of that rule.
 
 [float]
 [[customize-the-alerts-table]]

@@ -394,7 +394,7 @@ a value from the source event:
 
 |rule_name_override |String |Sets which field in the source event is used to
 populate the alert's `signal.rule.name` value (in the UI, this value is
-displayed on the *Rules* page in the *Rule* column). When unspecified, the
+displayed in the *Rule* column on the Detections page). When unspecified, the
 rule's `name` value is used. The source field must be a string data type.
 
 |severity_mapping |Object[] a|Overrides generated alerts' `severity` with
@@ -550,7 +550,8 @@ All fields are required:
 |==============================================
 
 NOTE: Only threats described using the MITRE ATT&CK^TM^ framework are displayed
-in the UI (*Manage* -> *Rules* -> *_Rule name_*).
+in the UI (*Detections* -> *Manage detection rules* -> <rule
+name>).
 
 ===== Example requests
 

@@ -12,7 +12,7 @@ You cannot export prebuilt rules, but they are available at https://github.com/e
 =================
 Although detection rule actions are included in the exported file, the connectors used by the actions are not included. Use the {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI in Kibana (*Stack Management* -> *Kibana* -> *Saved Objects*) or the Saved Objects APIs (experimental) to {kibana-ref}/saved-objects-api-export.html[export] and {kibana-ref}/saved-objects-api-import.html[import] any necessary connectors _before_ you export and import the detection rules.
 
-Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the <<edit-value-lists, Upload value lists>> UI (*Manage* -> *Rules* -> *Upload value lists*) to export and import value lists separately.
+Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the <<edit-value-lists, Upload value lists>> UI (*Detect* -> *Rules* -> *Upload value lists*) to export and import value lists separately.
 =================
 
 ==== Request URL

@@ -14,7 +14,7 @@ NOTE: You need at least `Read` privileges for the `Action and Connectors` featur
 =================
 Although detection rule actions are included in the exported file, the connectors used by the actions are not included. Use the {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI in Kibana (*Stack Management* -> *Kibana* -> *Saved Objects*) or the Saved Objects APIs (experimental) to {kibana-ref}/saved-objects-api-export.html[export] and {kibana-ref}/saved-objects-api-import.html[import] any necessary connectors _before_ you export and import the detection rules.
 
-Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the <<edit-value-lists, Upload value lists>> UI (*Manage* -> *Rules* -> *Upload value lists*) to export and import value lists separately.
+Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the <<edit-value-lists, Upload value lists>> UI (*Detect* -> *Rules* -> *Upload value lists*) to export and import value lists separately.
 =================
 
 ==== Request URL

@@ -310,7 +310,7 @@ a value from the source event:
 
 |rule_name_override |String |Sets which field in the source event is used to
 populate the alert's `signal.rule.name` value (in the UI, this value is
-displayed on the *Rules* page in the *Rule* column). When unspecified, the
+displayed in the *Rule* column on the Detections page). When unspecified, the
 rule's `name` value is used. The source field must be a string data type.
 
 |severity_mapping |Object[] a|Overrides generated alerts' `severity` with
@@ -427,7 +427,8 @@ technique:
 |==============================================
 
 NOTE: Only threats described using the MITRE ATT&CK^TM^ framework are displayed
-in the UI (*Manage* -> *Rules* -> *_Rule name_*).
+in the UI (*Security* -> *Detections* -> *Manage detection rules* -> <rule
+name>).
 
 ===== Example request
 

@@ -26,7 +26,7 @@ image::images/alert-indices-ui.png[]
 By default, building block alerts are excluded from the Overview and Alerts pages.
 You can choose to include building block alerts on the Alerts page, which expands the number of alerts.
 
-. Go to *Alerts*.
+. Go to *Detect* -> *Alerts*.
 . In the Alerts table, select *Additional filters* ->
 *Include building block alerts*, located on the far-right.
 

@@ -3,15 +3,15 @@
 
 = Detections and alerts
 
-Use the detection engine to create and manage rules and view the alerts
-these rules create. Rules periodically search indices (such as `logs-*` and
-`filebeat-*`) for suspicious source events and create alerts when a rule's
+Use the Detections feature to create and manage rules, and view the alerts
+these rules create. Rules periodically search indices (such as `endgame-*` and
+`filebeat-*`) for suspicious source events, and create alerts when a rule's
 conditions are met. When an alert is created, its status is `Open`. To help
-track investigations, an alert's <<detection-alert-status,status>> can be set as 
-`Open`, `Acknowledged`, or `Closed`.
+track investigations, an alert's status can be set as `Open`, `Acknowledged`, or
+`Closed` (see <<detection-alert-status>>).
 
 [role="screenshot"]
-image::images/alert-page.png[Alerts page]
+image::images/alert-page.png[Shows the Alerts page]
 
 In addition to creating <<rules-ui-create, your own rules>>, enable
 <<load-prebuilt-rules, Elastic prebuilt rules>> to immediately start detecting
@@ -195,26 +195,26 @@ NOTE: Ransomware prevention is a paid feature and is enabled by default if you h
 === Resolve UI error messages
 
 Depending on your privileges and whether detection system indices have already
-been created for the {kib} space, you might get one of these error messages when you 
-open the *Alerts* or *Rules* page:
+been created for the {kib} space, you might see an error message  when you try
+to open the *Detections* page.
+
+*`Let’s set up your detection engine`*
+
+If you see this message, a user with specific privileges must visit the
+*Detections* page before you can view detection rules and alerts.
+See <<enable-detections-ui>> for a list of all the requirements.
 
-* *`Let’s set up your detection engine`*
-+
-If you get this message, a user with specific privileges must visit the
-*Alerts* or *Rules* page before you can view detection alerts and rules.
-Refer to <<enable-detections-ui>> for a list of all the requirements.
-+
 NOTE: For *self-managed* {stack} deployments only, this message may be displayed
 when the
 <<detections-permissions, `xpack.encryptedSavedObjects.encryptionKey`>>
-setting has not been added to the `kibana.yml` file. For more information, refer to <<detections-on-prem-requirements>>.
+setting has not been added to the `kibana.yml` file. For more information, see <<detections-on-prem-requirements>>.
 
-* *`Detection engine permissions required`*
-+
-If you get this message, you do not have the
+*`Detection engine permissions required`*
+
+If you see this message, you do not have the
 <<detections-permissions, required privileges>> to view the *Detections* feature,
 and you should contact your {kib} administrator.
-+
+
 NOTE: For *self-managed* {stack} deployments only, this message may be
 displayed when the <<detections-permissions, `xpack.security.enabled`>>
-setting is not enabled in the `elasticsearch.yml` file. For more information, refer to <<detections-on-prem-requirements>>.
+setting is not enabled in the `elasticsearch.yml` file. For more information, see <<detections-on-prem-requirements>>.
@@ -41,7 +41,7 @@ act as value delimiters.
 * Wildcards are not supported in rule exceptions or value lists. Values must be literal values.
 =========================
 
-. Go to *Manage* -> *Rules*.
+. Go to *Detect* -> *Rules*.
 . Click *Upload value lists*. The *Upload value lists* window opens.
 +
 [role="screenshot"]
@@ -60,7 +60,7 @@ the new file are appended to the previously uploaded values.
 
 To view, delete, or export existing value lists:
 
-. Go to *Manage* -> *Rules*.
+. Go to *Detect* -> *Rules*.
 . Click *Upload value lists*. The *Upload value lists* window opens.
 . In the *Value lists* table, click the required action button.
 
@@ -101,15 +101,15 @@ specific event in the sequence, update the rule's EQL statement. For example:
 --
 * To add an exception from the rule details page:
 .. Go to the rule details page of the rule to which you want to add an
-exception (*Manage* -> *Rules* -> *_<Rule name>_*).
+exception (*Detect* -> *Rules* -> *_<Rule name>_*).
 .. Scroll down below the rule details and select the *Exceptions* tab.
 +
 [role="screenshot"]
 image::images/exception-histogram.png[Detail of Exceptions tab, 75%]
 .. Click *Add new exception* -> *Add rule exception*.
 
 * To add an exception from the Alerts table:
-.. Go to *Alerts*.
+.. Go to *Detect* -> *Alerts*.
 .. Scroll down to the Alerts table, go to the alert you want to create an exception for, click the *More Actions* menu (*...*), then select *Add rule exception*.
 
 The *Add Rule Exception* flyout opens (the example below was opened from the Alerts table):
@@ -189,11 +189,11 @@ Additionally, to add an Endpoint exception to the Elastic Endpoint Security rule
 +
 --
 * To add an Endpoint exception from the rule details page:
-.. Go to the rule details page (*Manage* -> *Rules*), and then search for and  select the Elastic *Endpoint Security* rule.
+.. Go to the rule details page (*Detect* -> *Rules*), and then search for and  select the Elastic *Endpoint Security* rule.
 .. Scroll down to the *Trend* histogram and select the *Exceptions* tab.
 .. Click *Add new exception* -> *Add Endpoint exception*.
 * To add an Endpoint exception from the Alerts table:
-.. Go to *Alerts*.
+.. Go to *Detect* -> *Alerts*.
 .. Scroll down to the Alerts table, and from an {elastic-endpoint} 
 alert, click the *More actions* menu (*...*), then select *Add Endpoint exception*.
 --
@@ -282,7 +282,7 @@ image::images/nested-exp.png[]
 [[manage-exceptions]]
 === View and manage exception lists
 
-The Exception lists table enables you to view and manage all exceptions that have been assigned to rules. To view the Exception lists table, go to *Manage* -> *Exception lists*.
+The Exception lists table enables you to view and manage all exceptions that have been assigned to rules. To view the Exception lists table, go to *Detect* -> *Exception lists*.
 
 [role="screenshot"]
 image::images/exceptions-page.png[]

@@ -3,8 +3,8 @@
 = Anomaly Detection with Machine Learning
 
 {ml-docs}/ml-ad-overview.html[{ml-cap}] functionality is available when
-you have the appropriate subscription, are using a *{ess-trial}[cloud deployment]*,
-or are testing out a *Free Trial*. Refer to <<ml-requirements>>.
+you have the *{subscriptions}[appropriate license]*, are
+using a *{ess-trial}[cloud deployment]*, or are testing out a *Free Trial*.
 
 You can view the details of detected anomalies within the `Anomalies` table
 widget shown on the Hosts, Network, and associated details pages, or even narrow