[DOCS] Blocklist (#1811)

joepeeples · benironside · nastasha-solomon · mergify-bot · commit cd67cdedf5dd · 2022-04-12T20:45:45.000Z
* Create new Blocklist page * Add Blocklist page to TOC * Add new Blocklist section on UI overview page for * Correction * Align description on UI overview page * Update config integration policy page, image * Add info about int policy to blocklist page * Add Blocklist to UI list * Adds prelim "coming" tag, some corrections * Correction * Add info about multiple values, lists * another. correction. * Apply first round of feedback Co-authored-by: benironside <91905639+benironside@users.noreply.github.com> Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com> * Apply a few more feedback edits Co-authored-by: benironside <91905639+benironside@users.noreply.github.com> * Update docs/management/admin/blocklist.asciidoc * Update docs/management/admin/blocklist.asciidoc Co-authored-by: benironside <91905639+benironside@users.noreply.github.com> * Apply suggestions from Janeen's review Co-authored-by: Janeen Mikell-Straughn <57149392+jmikell821@users.noreply.github.com> * Rename actions menu (prev button) * Update docs/management/admin/blocklist.asciidoc * Update docs/getting-started/configure-integration-policy.asciidoc Co-authored-by: Kevin Logan <56395104+kevinlog@users.noreply.github.com> Co-authored-by: benironside <91905639+benironside@users.noreply.github.com> Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com> Co-authored-by: Janeen Mikell-Straughn <57149392+jmikell821@users.noreply.github.com> Co-authored-by: Kevin Logan <56395104+kevinlog@users.noreply.github.com> (cherry picked from commit 89b1455)
diff --git a/docs/getting-started/configure-integration-policy.asciidoc b/docs/getting-started/configure-integration-policy.asciidoc
@@ -19,10 +19,10 @@ To configure the integration policy:
 * <<adv-policy-settings>>
 * <<save-policy>>
 
-4. Click the **Trusted applications**, **Event filters**, and **Host isolation exceptions** tabs to review the endpoint policy artifacts assigned to this integration policy (for more information, refer to <<trusted-apps-ov>>, <<event-filters>>, and <<host-isolation-exceptions>>). On these tabs, you can:
+4. Click the **Trusted applications**, **Event filters**, **Host isolation exceptions**, and **Blocklist** tabs to review the endpoint policy artifacts assigned to this integration policy (for more information, refer to <<trusted-apps-ov>>, <<event-filters>>, <<host-isolation-exceptions>>, and <<blocklist>>). On these tabs, you can:
 * Expand and view an artifact — Click the arrow next to its name.
-* View an artifact's details — Click the actions button (**...**), then select **View full details**.
-* Unassign an artifact (Platinum or Enterprise subscription) — Click the actions button (**...**), then select **Remove from policy**. This does not delete the artifact; this just unassigns it from the current policy.
+* View an artifact's details — Click the actions menu (**...**), then select **View full details**.
+* Unassign an artifact (Platinum or Enterprise subscription) — Click the actions menu (**...**), then select **Remove from policy**. This does not delete the artifact; this just unassigns it from the current policy.
 * Assign an existing artifact (Platinum or Enterprise subscription) — Click **Assign _x_ to policy**, then select an item from the flyout. This view lists any existing artifacts that aren't already assigned to the current policy.
 
 NOTE: You can't create a new endpoint policy artifact while configuring an integration policy. To create a new artifact, go to its main page in the {security-app} (for example, to create a new trusted application, go to **Manage** -> **Trusted applications**).
@@ -42,6 +42,8 @@ Malware protection levels are:
 +
 TIP: Platinum and Enterprise customers can customize these notifications using the `Elastic Security {action} {filename}` syntax.
 
+Malware protection also allows you to manage a blocklist to prevent specified applications from running on hosts, extending the list of processes that {endpoint-sec} considers malicious. Use the **Blocklist enabled** toggle to enable or disable this feature for all hosts associated with the integration policy. To configure the blocklist, refer to <<blocklist>>.
+
 [role="screenshot"]
 image::images/install-endpoint/malware-protection.png[Detail of malware protection section.]
 
diff --git a/docs/getting-started/images/install-endpoint/malware-protection.png b/docs/getting-started/images/install-endpoint/malware-protection.png
diff --git a/docs/getting-started/security-ui.asciidoc b/docs/getting-started/security-ui.asciidoc
@@ -33,6 +33,7 @@ The {security-app} contains the following pages that enable analysts to view, an
 * Trusted applications
 * Event filters
 * Host isolation exceptions
+* Blocklist
 
 Pages are grouped into four main sections within the navigation pane -- Detect, Explore, Investigate, and Manage. Each section supports a different part of your workflow and describes actions you can perform in the {security-app}.
 
@@ -191,6 +192,15 @@ The Host isolation exceptions page allows you to specify IP addresses that allow
 [role="screenshot"]
 image::management/admin/images/host-isolation-exceptions-ui.png[Shows the Host isolation exceptions page]
 
+[float]
+[[blocklist-page]]
+=== Blocklist page
+
+The Blocklist page allows you to prevent specified applications from running on hosts, extending the list of processes that {endpoint-sec} considers malicious. Refer to <<blocklist, Blocklist>> for more information.
+
+[role="screenshot"]
+image::management/admin/images/blocklist.png[Blocklist page]
+
 [discrete]
 [[timeline-accessibility-features]]
 == Accessibility features
diff --git a/docs/management/admin/blocklist.asciidoc b/docs/management/admin/blocklist.asciidoc
@@ -0,0 +1,82 @@
+[[blocklist]]
+[chapter]
+= Blocklist
+
+coming[8.2.0]
+
+The blocklist allows you to prevent specified applications from running on hosts, extending the list of processes that {endpoint-sec} considers malicious. This is especially useful for ensuring that known malicious processes aren't accidentally executed by end users. 
+
+[NOTE] 
+=====
+In addition to configuring specific entries on the **Blocklist** page, you must also ensure that the blocklist is enabled on the {endpoint-sec} integration policy in the <<malware-protection, Malware protection settings>>. This setting is enabled by default.
+
+You must have the built-in `superuser` role to access the blocklist. For more information, refer to {ref}/built-in-users.html[Built-in users].
+=====
+
+By default, a blocklist entry is recognized globally across all hosts running {endpoint-sec}. If you have a https://www.elastic.co/pricing[Platinum or Enterprise subscription], you can also assign a blocklist entry to specific {endpoint-sec} integration policies, which blocks the process only on hosts assigned to that policy.
+
+. Go to **Manage** -> **Blocklist**.
+
+. Click **Add blocklist entry**. The **Add blocklist** flyout appears.
+
+. Fill in these fields in the **Details** section:
+.. `Name`: Enter a name to identify the application in the blocklist.
+.. `Description`: Enter a description to provide more information on the blocklist entry (optional).
+
+. In the **Conditions** section, enter the following information about the application you want to block:
+.. `Select operating system`: Select the appropriate operating system from the drop-down.
+.. `Field`: Select a field to identify the application being blocked:
+  * `Hash`: The MD5, SHA-1, or SHA-256 hash value of the application's executable.
+  * `Path`: The full file path of the application's executable.
+  * `Signature`: (Windows only) The name of the application's digital signer.
++
+TIP: To find the signer's name for an application, go to *Kibana* -> *Discover* and query the process name of the application's executable (for example, `process.name : "mctray.exe"` for a McAfee security binary). Then, search the results for the `process.code_signature.subject_name` field, which contains the signer's name (for example, `McAfee, Inc.`).
+
+.. `Operator`: The operator is `is one of` and cannot be modified.
+
+.. `Value`: Enter the hash value, file path, or signer name. To enter multiple values (such as a list of known malicious hash values), you can enter each value individually or paste a comma-delimited list, then press **Return**.
++
+NOTE: Hash values must be valid to add them to the blocklist.
+
+. Select an option in the *Assignment* section to assign the blocklist entry to a specific integration policy:
++
+* `Global`: Assign the blocklist entry to all {endpoint-sec} integration policies.
+* `Per Policy`: Assign the blocklist entry to one or more specific {endpoint-sec} integration policies. Select each policy where you want the blocklist entry to apply.
++
+NOTE: You can also select the `Per Policy` option without immediately assigning a policy to the blocklist entry. For example, you could do this to create and review your blocklist configurations before putting them into action with a policy.
+
+. Click **Add blocklist**. The new entry is added to the **Blocklist** page.
+
+. When you're done adding entries to the blocklist, ensure that the blocklist is enabled for the {endpoint-sec} integration policies that you just assigned:
+.. Go to **Manage** -> **Policies**, then click on an integration policy.
+.. On the **Policy settings** tab, ensure that the **Malware protections enabled** and **Blocklist enabled** toggles are switched on. Both settings are enabled by default.
+
+[discrete]
+[[manage-blocklist]]
+== View and manage the blocklist
+
+The *Blocklist* page displays all the blocklist entries that have been added to the {security-app}. To refine the list, use the search bar to search by name, description, or field value.
+
+[role="screenshot"]
+image::images/blocklist.png[]
+
+[discrete]
+[[edit-blocklist-entry]]
+=== Edit a blocklist entry
+You can individually modify each blocklist entry. With a Platinum or Enterprise subscription, you can also change the policies that a blocklist entry is assigned to.
+
+To edit a blocklist entry:
+
+. Click the actions menu (*...*​) for the blocklist entry you want to edit, then select *Edit blocklist*.
+. Modify details as needed.
+. Click *Save*.
+
+[discrete]
+[[delete-blocklist-entry]]
+=== Delete a blocklist entry
+You can delete a blocklist entry, which removes it entirely from all {endpoint-sec} policies. This allows end users to access the application that was previously blocked.
+
+To delete a blocklist entry:
+
+. Click the actions menu (*...*) for the blocklist entry you want to delete, then select *Delete blocklist*.
+. On the dialog that opens, verify that you are removing the correct blocklist entry, then click *Delete*. A confirmation message displays.
diff --git a/docs/management/admin/images/blocklist.png b/docs/management/admin/images/blocklist.png
diff --git a/docs/management/manage-intro.asciidoc b/docs/management/manage-intro.asciidoc
@@ -9,3 +9,4 @@ include::{security-docs-root}/docs/management/admin/host-isolation-ov.asciidoc[l
 include::{security-docs-root}/docs/management/admin/trusted-apps.asciidoc[leveloffset=+1]
 include::{security-docs-root}/docs/management/admin/event-filters.asciidoc[leveloffset=+1]
 include::{security-docs-root}/docs/management/admin/host-isolation-exceptions.asciidoc[leveloffset=+1]
+include::{security-docs-root}/docs/management/admin/blocklist.asciidoc[leveloffset=+1]
