wip

x-pack/plugins/security_solution/docs/prebuilt_rules_customization_rfc.md

@@ -251,21 +251,22 @@ With the rule schema updated, we will allow users to **edit their prebuilt rules
 
 Endpoints that users will be able to use to modify rules are:
 
-- Update Rule - `PUT /rules`: called by the UI when updating/modifying a single rule via the Rule Details page
-- Patch Rule - `PATCH /rules`: used for attaching shared exceptions list to rules
-- Bulk Patch Rules - `PATCH /rules/_bulk_update`: deprecated and unused by the UI (might still be used by public API users)
-- Bulk Update Rules - `PUT /rules/_bulk_update`: deprecated and unused by the UI (might still be used by public API users)
-- Bulk Actions - `POST /rules/_bulk_action` - with `edit` action: called when applying bulk actions via the Rules Table
+- **Update Rule** - `PUT /rules`: called by the UI when updating/modifying a single rule via the Rule Details page
+- **Patch Rule** - `PATCH /rules`: used for attaching shared exceptions list to rules
+- **Bulk Patch Rules** - `PATCH /rules/_bulk_update`: deprecated and unused by the UI (might still be used by public API users)
+- **Bulk Update Rules** - `PUT /rules/_bulk_update`: deprecated and unused by the UI (might still be used by public API users)
+- **Bulk Actions** - `POST /rules/_bulk_action` - with `edit` action: called when applying bulk actions via the Rules Table
 
 The first four endpoints listed above **currently allow users to modify their Elastic prebuilt rules** as well, in (almost) all of their fields, and no difference is made between updating/patching prebuilt rules and custom rules in the docs. However, none of those four endpoints allow to change a prebuilt rule to a custom rule (or vice-versa) by changing the current `immutable` field (i.e. the field is maintained from the existing rule).
 
-> - **Will we want to allow users to modify (via API) a prebuilt rule to transform into a Custom Rule, by modifying the `prebuilt` parameter?**
+> - **Will we want to allow users to modify (via API) a prebuilt rule to transform it into a Custom Rule, by modifying the `prebuilt` parameter?**
  >  - No. We want to keep the current endpoint logic where the `immutable` field for the updated value comes from the existing value of the rule. Allowing that modification would create issues with the corresponding `security_detection_engine` package rule, as it will clash with the modified rule if the `rule_id` is not modified as well. This requirement is therefore not needed anyway since will now offer users the option to customize a prebuilt rule, or alternatively, duplicate a prebuilt rule.
 
 The endpoint **Bulk Actions** - `POST /rules/_bulk_action` does provide validation in the endpoint logic itself: if a user attempts to edit prebuilt rule (`immutable: true`) the endpoint rejects that edit in two ways:
 - in `dryRun` mode, with an error: "editing prebuilt rules is not supported".
 - in normal mode, with validation that throws the error "Elastic rule can't be edited".
-In both cases, the validation checks if the `immutable` param of the rule is `true`, and if the action sent in the payload is setting or adding actions to a rule. If any of those two conditions are true, the validation succeeds.
+
+In both cases, the validation checks if the `immutable` param of the rule is `false`, or if the action sent in the payload is setting or adding actions to a rule. If any of those two conditions are true, the validation succeeds and the rule(s) can be edited.
 
 #### Changes needed to endpoints
 
@@ -318,74 +319,46 @@ The current behaviour of the app allows to modify a rule's fields in the followi
 #### Via the Rule Edit Page
 
 The **Rule Edit Page** is currently split into four tabs:
-- **Definition**, which contains the fields:
- - Rule type (cannot be changed)
- - Data Source
- - Query
- - Machine Learning job (ML rules only)
- - Anomaly score threshold (ML rules only)
- - Group by (threshold rules only)
- - Count (cardinality) (threshold rules only)
- - Indicator index patterns (indicator match rules only)
- - Indicator index query (indicator match rules only)
- - Indicator mapping (indicator match rules only)
- - New terms fields (new term rules only)
- - History window size (new terms rules only)
- - Alert Supression (for custom query and threshold rules only)
- - Timeline Template
-- **About**, which contains the fields:
- - Name
- - Description
- - Severity
- - Severity override
- - Risk score
- - Risk score override
- - Tags
- - Reference URLs
- - False positive examples
- - MITRE ATT&CK™ threats
- - Custom highlighted fields
- - Investigation guide
- - Author
- - License
- - Elastic Endpoint exceptions
- - Building block
- - Rule name override
- - Timestamp override
-- **Schedule**, which contains the fields:
- - Interval
- - Lookback time
-- **Actions**, which contains the fields:
- - Actions
- - Response actions (custom query rules only)
+
+| Tab | Contains fields |
+| --------------- | ------ |
+| **Definition** | - Rule type (cannot be changed)<br>- Data Source<br>- Query<br>- Machine Learning job (ML rules only)<br>- Anomaly score threshold (ML rules only)<br>- Group by (threshold rules only)<br>- Count (cardinality) (threshold rules only)<br>- Indicator index patterns (indicator match rules only)<br>- Indicator index query (indicator match rules only)<br>- Indicator mapping (indicator match rules only)<br>- New terms fields (new term rules only)<br>- History window size (new terms rules only)<br>- Alert Suppression (for custom query and threshold rules only)<br>- Timeline Template |
+| **About** | - Name<br>- Description<br>- Severity<br>- Severity override<br>- Risk score<br>- Risk score override<br>- Tags<br>- Reference URLs<br>- False positive examples<br>- MITRE ATT&CK™ threats<br>- Custom highlighted fields<br>- Investigation guide<br>- Author<br>- License<br>- Elastic Endpoint exceptions<br>- Building block<br>- Rule name override<br>- Timestamp override |
+| **Schedule** | - Interval<br>- Lookback time |
+| **Actions** | - Actions<br>- Response actions (custom query rules only) |
 
 Out of these four tabs, only **Actions** is enabled and accesible when editing a prebuilt rule - since actions (and shared exceptions lists) are the only fields that can currently be modified for prebuilt rules from the UI.
 
 All of the fields in the UI, listed above, are currently editable for custom rules, except for rule type, which is read only.
 
 Once done editing the rule, the user clicks on the "Save Changes" button, which calls the **Update Rule** - `PUT /rules` endpoint, passing the payload for the whole rule.
 
-**Expected behaviour**
+**Expected behaviour for customizing prebuilt rules**
 
-- All four tabs should be enabled, and all the fields within each tab should be editable, as they currently are for custom rules.
+- All four tabs of the Rule Edit page should be enabled, and all the fields within each tab should be editable, as they currently are for custom rules.
 - The only field in the UI that should not be customizable is **Rule Type**, that should continue to be read-only.
 - **Definition** should be the default open tab when opening the edit rule page for a prebuilt rule (current default is **Actions**)
 - Field validation should continue to work as it does for custom rules.
 - No fields should return a validation error for the values that come from the `security_detection_engine` package prebuilt rules. This means that a user should be able to successfully save the prebuilt rule with no changes. See **List of things to fix** below.
 
 
+#### Via Bulk Actions
 
-- which endpoint it calls
-- what fields it allows to edit
-- how it does "frontend validation" to only edit Custom Rules
-- changes needed
+Custom rules can currently be updated via the Rule Table's **Bulk Actions**, which uses the **Bulk Actions** - `POST /rules/_bulk_action` endpoint.
 
-#### Via Bulk Actions
+Apart from enabling/disabling a rule - the only other action that modifies a rule's saved object and is currently possible for prebuilt rules - the user can use bulk actions to:
 
-- which endpoint it calls
-- what fields it allows to edit
-- how it does "frontend validation" to only edit Custom Rules (except for adding actions)
-- changes needed
+- Add, delete and overwrite **index patterns**
+- Add, delete and overwrite **tags**
+- Add and overwrite **rule actions**
+- Update the rule's **schedule: interval and lookback time**
+- Select a **timeline template** for the rule
+
+As explained above, the UI validates that the five actions listed above are only possible to custom rules by using the `dryRun` mode of the **bulk actions** endpoint. If any of the selected rules in the request payload is a prebuilt rule, a message is displayed to the user informing them that modifying prebuilt rules is not possible, and that rule is removed from the subsequent request that is made in normal mode to actually edit the rule.
+
+**Expected behaviour for customizing prebuilt rules**
+
+- no validation
 
 #### Via the Shared Exception Lists page