[Security Solution][Detections]Adds dry_run mode description to _bulk_action API #2210
Conversation
|
This pull request does not have a backport label. Could you fix it @vitaliidm? 🙏
NOTE: |
There was a problem hiding this comment.
Thanks for documenting this mode @vitaliidm. I have a bunch of suggestions regarding the wording and would like a native English speaker to check them (@joepeeples could you please help with this or delegate it to someone?). Also, how can we build the docs for this PR to be able to preview the changes?
|
Hey @banderror, we'll definitely review for language and consistency. I added the preview link to @vitaliidm's first comment - link is here. |
There was a problem hiding this comment.
Thanks for writing this up @vitaliidm and @banderror! I left some suggestions for your consideration and one question. Hopefully they're helpful!
Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com>
There was a problem hiding this comment.
Looks great! Thank you for your help @jmikell821 and @nastasha-solomon 🙏
Co-authored-by: Georgii Gorbachev <banderror@gmail.com>
There was a problem hiding this comment.
@banderror @vitaliidm left a few edits and some more comments for your consideration. Feel free to ping me if you have any questions!
| [[bulk-actions-rules-api-dry-run]] | ||
| [discrete] | ||
| ==== Dry run mode | ||
| Enable dry run mode before you bulk update or delete rules to verify that the selected rules can be modified _before_ you permanently change them. When dry mode is enabled, the bulk action is temporarily applied to selected rules. These updates are not written to {es}. |
There was a problem hiding this comment.
@banderror @vitaliidm should we tweak the first sentence a bit more? Looking at this again, I'm not sure that it fully encompasses the main use cases that this feature addresses. Here's my understanding:
- The dry run allows users do a test run of the bulk action they select (enable, disable, delete, etc.) to help them verify that the rules they specified can actually be updated.
- Users can complete a pelimiary and temporary bulk rule update with this feature. This would give them an extra buffer layer, or another layer of checks, before they permanently alter their rules.
There was a problem hiding this comment.
If the above is correct, here's another revision that includes both. Let me know what you think:
| Enable dry run mode before you bulk update or delete rules to verify that the selected rules can be modified _before_ you permanently change them. When dry mode is enabled, the bulk action is temporarily applied to selected rules. These updates are not written to {es}. | |
| Enable dry run mode to allow test runs when applying bulk actions to rules. Dry runs can help you verify that the rules you specified can actually be updated. They're also useful for testing bulk rule updates before they're permanently applied. When dry mode is enabled, bulk actions are temporarily applied to specified rules to show you a realistic set of results. Rule updates are not written to {es}. |
There was a problem hiding this comment.
@nastasha-solomon I don't think that strictly speaking this is a correct statement:
When dry mode is enabled, bulk actions are temporarily applied to specified rules to show you a realistic set of results.
In the dry run mode, we don't return any results in the response body. We only return errors if there are any. So it's correct to say that this mode "can help you verify that the rules you specified can actually be updated". But it won't help the user to preview what would be the result (the updated, created, or deleted rules) of an action. So, you can think about this mode as a validation function.
There was a problem hiding this comment.
@banderror ah, thanks for clarifying that. Would it be correct to say that dry run mode identifies rules that will not accept bulk actions?
There was a problem hiding this comment.
@nastasha-solomon yep, that would be correct!
Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com>
Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com>
Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com>
Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com>
Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com>
Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com>
|
@nastasha-solomon, @benironside thanks for the feedback. Have applied the suggestions with some small amends. Please, have a look at final version. thanks |
Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com>
Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com>
Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com>
…_action API (#2210) Adds dry_run mode description to _bulk_action API Preview [here](https://security-docs_2210.docs-preview.app.elstc.co/guide/en/security/master/bulk-actions-rules-api.html). - issue elastic/kibana#125512 - PR elastic/kibana#134664 (cherry picked from commit 14f75a2)
…_action API (#2210) (#2239) Adds dry_run mode description to _bulk_action API Preview [here](https://security-docs_2210.docs-preview.app.elstc.co/guide/en/security/master/bulk-actions-rules-api.html). - issue elastic/kibana#125512 - PR elastic/kibana#134664 (cherry picked from commit 14f75a2) Co-authored-by: Vitalii Dmyterko <92328789+vitaliidm@users.noreply.github.com>
Adds dry_run mode description to _bulk_action API
Preview here.