Add documentation for detector rule creation updates (#4499)

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

* fix#4413 detection rule updates

Signed-off-by: cwillum <cwmmoore@amazon.com>

---------

Signed-off-by: cwillum <cwmmoore@amazon.com>

_security-analytics/index.md

@@ -50,9 +50,9 @@ Log types provide the data used to evaluate events occurring in a system. OpenSe
 
 Log types are specified during the creation of detectors, including steps for mapping log fields to the detector. Security Analytics also automatically selects an appropriate set of rules based on a specific log type and populates them for the detector.
 
-### Rules
+### Detection rules
 
-Rules, or threat detection rules, define the conditional logic applied to ingested log data that allows the system to identify an event of interest. Security Analytics uses prepackaged, open source [Sigma rules](https://github.com/SigmaHQ/sigma) as a starting point for describing relevant log events. But with their inherently flexible format and easy portability, Sigma rules provide users of Security Analytics with options for importing and customizing the rules. You can take advantage of these options using either Dashboards or the API.
+The security rules, or threat detection rules, define the conditional logic applied to ingested log data that allows the system to identify an event of interest. Security Analytics uses prepackaged, open source [Sigma rules](https://github.com/SigmaHQ/sigma) as a starting point for describing relevant log events. But with their inherently flexible format and easy portability, Sigma rules provide Security Analytics users with options for importing and customizing the rules. You can take advantage of these options using either OpenSearch Dashboards or the API.
 
 For information about configuring rules, see [Working with rules]({{site.url}}{{site.baseurl}}/security-analytics/usage/rules/).
 

_security-analytics/usage/index.md

@@ -10,12 +10,12 @@ redirect_from:
 
 # Using Security Analytics
 
-After creating detectors and generating findings, functionality within the several Security Analytics windows offers visualizations and tools to help you investigate and manage findings, create focused alerts and notifications, import or customize rules, and edit detectors, among other tasks. This section discusses available features, their uses, and general navigation while working in the various windows. You can use the links below to go directly to information on a specific window.
+After creating detectors and generating findings, functionality within the several Security Analytics windows offers visualizations and tools to help you investigate and manage findings, create focused alerts and notifications, import or customize rules, and edit detectors, among other tasks. This section discusses available features, their uses, and general navigation while working in the various windows. You can use the following links to go directly to information on a specific window:
 
 * [The Overview page]({{site.url}}{{site.baseurl}}/security-analytics/usage/overview/)
 * [Working with detectors]({{site.url}}{{site.baseurl}}/security-analytics/usage/detectors/)
 * [Working with findings]({{site.url}}{{site.baseurl}}/security-analytics/usage/findings/)
-* [Working with rules]({{site.url}}{{site.baseurl}}/security-analytics/usage/rules/)
+* [Working with detection rules]({{site.url}}{{site.baseurl}}/security-analytics/usage/rules/)
 * [Working with the correlation graph]({{site.url}}{{site.baseurl}}/security-analytics/usage/correlation-graph/)
 * [Working with alerts]({{site.url}}{{site.baseurl}}/security-analytics/usage/alerts/)
 

_security-analytics/usage/rules.md

@@ -1,19 +1,19 @@
 ---
 layout: default
-title: Working with rules
+title: Working with detection rules
 parent: Using Security Analytics
 nav_order: 40
 ---
 
-# Working with rules
+# Working with detection rules
 
-The Rules window lists all security rules and provides options for filtering the list and viewing details for each rule. Further options let you import rules and create new rules by first duplicating a Sigma rule then modifying it. This section covers navigation of the Rules page and description of the actions you can perform.
+The **Detection rules** window lists all security rules used for detection creation and provides options for filtering the list and viewing details for each rule. Further options allow you to import rules and create new rules by first duplicating a Sigma rule and then modifying it. This section covers navigation of the **Rules** page and provides descriptions of the actions you can perform.
 
 <img src="{{site.url}}{{site.baseurl}}/images/Security/Rules.png" alt="The Rules page" width="90%">
 
 ## Viewing and filtering rules
 
-When you open the Rules page, all rules are listed in the table. Use the search bar to search for specific rules by entering a full or partial name and pressing **Return/Enter** on your keyboard. The list is filtered and displays matching results.
+When you open the **Detection rules** page, all rules are listed in the table. Use the search bar to search for specific rules by entering a full or partial name and pressing **Return/Enter** on your keyboard. The list is filtered and displays matching results.
 
 Alternatively, you can use the **Rule type**, **Rule severity**, and **Source** dropdown lists to drill down in the alerts and filter for preferred results. You can select multiple options from each list and use all three in combination to narrow results.
 
@@ -30,40 +30,119 @@ In Visual view, rule details are arranged in fields, and the links are active. S
 <img src="{{site.url}}{{site.baseurl}}/images/Security/rule_detail_yaml.png" alt="The rule details pane in YAML file view" width="50%">
 
 * Rule details are formatted as a YAML file according to the Sigma rule specification.
-* To copy the rule, select the copy icon in the top right corner of the rule. To quickly create a new and customized rule, you can paste the rule into the YAML editor and make any modifications before saving it. See [Customizing rules](#customizing-rules) for details.
+* To copy the rule, select the copy icon in the upper-right corner of the rule. To quickly create a new, customized rule, you can paste the rule into the YAML editor and make any modifications before saving it. See [Customizing rules](#customizing-rules) for more information.
 
 ## Creating rules
 
-There are several ways to create rules on the Rules page. The first is to manually fill in the necessary fields that complete the rule, using either the Visual Editor or YAML Editor. To do this, select the **Create new rule** button in the uppper-right corner of the Rules window. The Create a rule window opens.
+There are multiple ways to create rules on the **Detection rules** page. These methods include manually creating a custom rule, importing a rule, and duplicating an existing rule to customize it. The following sections discuss these methods in detail.  
 
-<img src="{{site.url}}{{site.baseurl}}/images/Security/create-a-rule.png" alt="The Create a rule window, which includes the Visual Editor and YAML editor." width="50%">
 
-If you choose to create the rule manually, you can refer to Sigma's [Rule Creation Guide](https://github.com/SigmaHQ/sigma/wiki/Rule-Creation-Guide) to help understand details for each field.
-* By default, the Visual Editor is displayed. Enter the appropriate content in each field and select **Create** in the lower-right corner of the window to save the rule.
-* The Create a rule window also provides the YAML Editor so that you can create the rule directly in a YAML file format. Select **YAML Editor** and then enter information for the pre-populated field types.
+### Custom rules
 
-The alternatives to manually creating a rule, however, simplify and speed up the process. They involve either importing a rule in a YAML file or duplicating an existing rule and customizing it. See the next two sections for detailed steps.
+The first method of rule creation is to create a custom rule by manually filling in the necessary fields that complete the rule, using either the Visual Editor or the YAML Editor. To do this, select **Create detection rule** in the uppper-right corner of the screen. The **Create detection rule** window opens.
 
-## Importing rules
+If you choose to create the rule manually, you can refer to Sigma's [Rule Creation Guide](https://github.com/SigmaHQ/sigma/wiki/Rule-Creation-Guide) for more information about the details of each field.
+{: .tip }
 
-At this time, Security Analytics supports the import of Sigma rules in YAML format. The following sample file shows the basic formatting of a rule in YAML.
+#### The Visual Editor
+
+When the **Create detection rule** window opens, the **Visual Editor** is displayed by default. The required fields in the **Visual Editor** correspond to the basic fields found in a YAML file formatted as a Sigma rule. The descriptions in these steps mention this correspondence when it might not be immediately obvious.
+  
+1. In the **Rule overview** section, enter a name for the rule, a description (optional), and the author of the rule. The **Rule name** corresponds to [title](https://github.com/SigmaHQ/sigma/wiki/Rule-Creation-Guide#title) in a Sigma rule formatted in a YAML file. The following image provides an example of the populated fields.
+  
+   <img src="{{site.url}}{{site.baseurl}}/images/Security/overview-rule.png" alt="The Rule overview fields in the Create detection rule window, which include the rule name, description, and author fields." width="50%">
+  
+1. In the **Details** section, enter the log type for the data source, the rule level, and the rule status. The **Log type** corresponds to the [`logsource`](https://github.com/SigmaHQ/sigma/wiki/Rule-Creation-Guide#log-source) field (specifically, the `logsource: product` field), while the rule level and rule status correspond to [`level`](https://github.com/SigmaHQ/sigma/wiki/Rule-Creation-Guide#level) and [`status`](https://github.com/SigmaHQ/sigma/wiki/Rule-Creation-Guide#status), respectively. Levels in Sigma rules include *informational*, *low*, *medium*, *high*, and *critical*. The following image provides an example.
+  
+   <img src="{{site.url}}{{site.baseurl}}/images/Security/details-rule.png" alt="The Details fields in the Create detection rule window, which include the log type, rule level, and rule status fields." width="40%">
+  
+1. In the **Detection** section, specify key-value pairs to represent the fields and their values in the log source, which will be the target for detection. These key-value pairs define the detection. You can represent key values as either a single value or as a list containing multiple values. 
+   
+   To define a simple key-value pair, first place the cursor on the **Selection_1** label and replace it with a selection name that describes the key-value pair. Next, enter a preferred field from the log source as the **Key**, and then use the **Modifier** dropdown list to define how the value is handled. The following modifiers are available:
+     * `contains` – Adds wildcards on either side of the value so that it is matched anywhere in the field.
+     * `all` – In the case of a list, rather than separate values with OR logic, the logic becomes AND and looks for a match with all values.
+     * `endswith` – Indicates that the value is matched when it appears at the end of the field.
+     * `startswith` – Indicates that the value is matched when it appears at the beginning of the field.
+   
+   After selecting a modifier, select the **Value** radio button and then enter a value for the key in the text field that follows it.
+   
+   You can add fields for mapping a second key-value pair by selecting **Add map**. Follow the previous guidance in this step to map the key-value pair. The following image shows how this definition for two key-value pairs appears in the **Create detection rule** window.
+   
+   <img src="{{site.url}}{{site.baseurl}}/images/Security/detection1.png" alt="An example of the Detection fields." width="50%">
+   
+   To see how this definition compares to how it would be configured in the YAML file, refer to the following example:
+
+   ```yaml
+   detection:
+      selection:
+       selection_schtasks:
+         Image|endswith: \schtasks.exe
+         CommandLine|contains: '/Create '
+   ```
+   
+   To add a second selection, use the **Add selection** bar following the first selection to open another key-value pair mapping. For this selection, values are provided as a list. As described in the first selection, replace the **Selection_2** label with a selection name, enter a field name from the log as the key, and select a modifier from the **Modifier** dropdown list.
+
+   Then, to define a key-value pair using a list rather than a single value, select the **List** radio button. The **Upload file** button appears and the text box is expanded to accommodate the list.
+
+   You can upload an existing list of values in either .csv or .txt format. Select **Upload file** and follow the prompts to upload a file's content into the text field. As an alternative, you can manually compose the list directly in the text field. The following image shows how a key-value pair mapping including a list of values appears.
+
+   <img src="{{site.url}}{{site.baseurl}}/images/Security/detection2.png" alt="An example of the Detection fields." width="50%">
+   
+   To see how the definition with both of the preceding selections compares to how it would be configured in the YAML file, refer to the following example:
+
+   ```yml
+   detection:
+     selection:
+       selection_schtasks:
+         Image|endswith: \schtasks.exe
+         CommandLine|contains: '/Create '
+       selection_rare:
+         CommandLine|contains:
+         - ' bypass '
+         - .DownloadString
+         - .DownloadFile
+         - FromBase64String
+         - ' -w hidden '
+         - ' IEX'
+         - ' -enc '
+         - ' -decode '
+         - '/c start /min '
+         - ' curl '
+   ```
+
+1. In the **Condition** section, specify the conditions for the selections included in the detection definition. These conditions determine how the defined selections are handled by the detection rule. At least one selection is required. In the case of the preceding example, this means that at least one of the two selections `selection_schtasks` and `selection_rare` must be added in the **Conditions** section. 
+
+   Select the `+` sign beside **Select** to add the first selection. Select the `+` sign again to add further selections from the detection definition. Once two selections are present as conditions, the Boolean operator AND appears between them, indicating that both will be used in the detection rule query. You can select the operator's label to open the operator dropdown list and choose from the options `AND`, `OR`, and `NOT`. The following image shows how this option appears.
+
+   <img src="{{site.url}}{{site.baseurl}}/images/Security/condition1.png" alt="specifying the conditions for the selections in the detection definition." width="50%">
+
+1. Specify optional fields for the detection rule.
+  
+   * In the **Tags** section, add tags to associate the detection rule with any attack techniques recorded by a cybersecurity knowledge base such as [MITRE ATT&CK](https://attack.mitre.org/). Select **Add tag** to add multiple tags.
+   * In the **References** section, you can add URLs for rule references. Select **Add URL** to add multiple URLs.
+   * The **False positive cases** section provides a space for listing descriptions of false positive conditions that could trigger unwanted alerts for the rule. Select **Add false positive** to add multiple descriptions.
+  
+ 1. Once the rule is complete and meets your requirements, select **Create detection rule** in the lower-right corner of the window to save the rule. A rule ID is automatically assigned to the new rule and appears in the list of detection rules.
+  
+#### The YAML Editor
+
+The **Create detection rule** window also contains the YAML Editor so that you can create a new rule directly in a YAML file format. Select **YAML Editor** and then enter information for the pre-populated field types. The rule's `id` is provided and assigned when the rule is saved. The following example shows the basic elements of a typical rule:
 
 ```yml
 title: RDP Sensitive Settings Changed
 logsource:
   product: windows
-  service: system
 description: 'Detects changes to RDP terminal service sensitive settings'
 detection:
-  selection_reg:
-  EventType: SetValue
-  TargetObject|contains:
-    - \services\TermService\Parameters\ServiceDll
-    - \Control\Terminal Server\fSingleSessionPerUser
-    - \Control\Terminal Server\fDenyTSConnections
-    - \Policies\Microsoft\Windows NT\Terminal Services\Shadow
-    - \Control\Terminal Server\WinStations\RDP-Tcp\InitialProgram
-  condition: selection_reg
+  selection:
+    EventType: SetValue
+    TargetObject|contains:
+      - \services\TermService\Parameters\ServiceDll
+      - \Control\Terminal Server\fSingleSessionPerUser
+      - \Control\Terminal Server\fDenyTSConnections
+      - \Policies\Microsoft\Windows NT\Terminal Services\Shadow
+      - \Control\Terminal Server\WinStations\RDP-Tcp\InitialProgram
+  condition: selection
 level: high
 tags:
   - attack.defense_evasion
@@ -82,18 +161,25 @@ status: experimental
 ```
 {% include copy.html %}
 
-1. To begin, select the **Import rule** button in the upper-right corner of the page. The Import rule page opens.
-1. Either drag a YAML-formatted Sigma rule into the window or browse for the file by selecting the link and opening it. The Import a rule window opens and the rule definition fields are automatically populated in both the Visual Editor and YAML Editor.
+To assist in rule creation using the **YAML Editor**, you can refer to Sigma's [Rule Creation Guide](https://github.com/SigmaHQ/sigma/wiki/Rule-Creation-Guide) and use the descriptions of each field to learn more about defining the rule.
+
+
+### Importing rules
+
+Security Analytics also supports the importing of Sigma rules in YAML format. In the **Detection rules** window, follow these steps to import a rule.
+
+1. To begin, select **Import detection rule** in the upper-right corner of the page. The **Import rule** page opens.
+1. Either drag a YAML-formatted Sigma rule into the window or browse for the file by selecting the link and opening it. The **Import a rule** window opens and the rule definition fields are automatically populated in both the Visual Editor and YAML Editor.
 1. Verify or modify the information in the fields.
-1. After you confirm the information for the rule is accurate, select the **Create** button in the lower-right corner of the window. A new rule is created, and it appears in the list of rules on the main page of the Rules window.
+1. After you confirm that the information for the rule is accurate, select **Create detection rule** in the lower-right corner of the window. A new rule is created and appears in the list of detection rules.
 
-## Customizing rules
+### Customizing rules
 
-An alternative to importing a rule is duplicating a Sigma rule and then modifying it to create a custom rule. First search for or filter rules in the Rules list to locate the rule you want to duplicate.
+Another option for creating a new detection rule is duplicating a Sigma rule and then modifying it to create a custom rule. First search for or filter rules in the **Rule name** list to locate the rule you want to duplicate. The following image shows the list filtered with a keyword.
 
 <img src="{{site.url}}{{site.baseurl}}/images/Security/rules-dup1.png" alt="Selecting a rule in the Rules name list" width="75%">
 
-1. To begin, select the rule in the Rule name column. The rule details pane opens.
+1. To begin, select the rule in the **Rule name** column. The rule details are displayed.
 
     <img src="{{site.url}}{{site.baseurl}}/images/Security/rule-dup2.png" alt="Opening the rule details pane" width="50%">
 
@@ -102,7 +188,7 @@ An alternative to importing a rule is duplicating a Sigma rule and then modifyin
     <img src="{{site.url}}{{site.baseurl}}/images/Security/dupe-rule.png" alt="Selecting the duplicate button opens the Duplicate rule window" width="50%">
 
 1. In either Visual Editor view or YAML Editor view, modify any of the fields to customize the rule.
-1. After performing any modifications to the rule, select the **Create** button in the lower-right corner of the window. A new and customized rule is created, and it appears in the list of rules on the main page of the Rules window.
+1. After performing any modifications to the rule, select **Create detection rule** in the lower-right corner of the window. A new, customized rule is created. It appears in the list of rules on the main page of the **Detection rules** window.
 
     <img src="{{site.url}}{{site.baseurl}}/images/Security/custom-rule.png" alt="The custom rule now appears in the list of rules." width="70%">