elastic · benskelker · Aug 17, 2020 · Aug 17, 2020
diff --git a/docs/cases/cases-overview.asciidoc b/docs/cases/cases-overview.asciidoc
@@ -68,12 +68,3 @@ To view a case, click on its name. You can then:
 * Refresh the case to retrieve the latest updates.
 
 NOTE: Comments can also contain Markdown syntax and timeline links.
-
-[float]
-[[case-permissions]]
-== Cases prerequisites
-
-To view cases, you need the {kib} space `Read` privilege for the Saved Objects
-Management feature. To create cases and add comments, you need the `All` {kib}
-space privilege for the Saved Objects Management feature. For more information,
-see {kibana-ref}/xpack-spaces.html#spaces-control-user-access[Feature access based on user privileges].
diff --git a/docs/detections/detection-engine-intro.asciidoc b/docs/detections/detection-engine-intro.asciidoc
@@ -107,56 +107,27 @@ Alerts {es-sec} receives from external systems, such as Suricata.
 [[detections-permissions]]
 == Detections configuration and index privilege prerequisites
 
-If you are using an *on-premises* {stack} deployment:
-
-* HTTPS must be configured for communication between
-{kibana-ref}/configuring-tls.html#configuring-tls-kib-es[{es} and {kib}].
-* In the `elasticsearch.yml` configuration file, set the 
-`xpack.security.enabled` setting to `true`. For more information, see 
-{ref}/settings.html[Configuring {es}] and
-{ref}/security-settings.html[Security settings in {es}].
-* In the `kibana.yml` {kibana-ref}/settings.html[configuration file], add the 
-`xpack.encryptedSavedObjects.encryptionKey` setting with any alphanumeric value 
-of at least 32 characters. For example:
-+
-`xpack.encryptedSavedObjects.encryptionKey: 'fhjskloppd678ehkdfdlliverpoolfcr'`
-
-For *all* deployments (on-premises and hosted):
-
-* To view detection rules and alerts, you must have at least:
-** `read` permissions for the `.siem-signals-<space name>` index, where
-`<space name>` is the name of the {kib} space you are using to view Detections
-(see {ref}/security-privileges.html#privileges-list-indices[Indices privileges]).
-** {kib} space `Read` privileges for the `Security` feature (see
-{kibana-ref}/xpack-spaces.html#spaces-control-user-access[Feature access based on user privileges]).
-* To create and modify detection rules, you must have:
-** {kib} space `All` privileges for the `Security` feature (see
-{kibana-ref}/xpack-spaces.html#spaces-control-user-access[Feature access based on user privileges]).
-** Write permissions for the `.siem-signals-<space name>` index, such as 
-`create` `create_doc`, `write`, `index`, and `all`
-(see {ref}/security-privileges.html#privileges-list-indices[Indices privileges]).
+<<detections-permissions-section>> provides detailed information on all the
+permissions required to initiate and use the Detections feature.
+
 
 [float]
 === Resolve UI error messages
 
-Depending on your privileges and whether a `.siem-signals-<space name>` index 
-has already been created for the {kib} space, you might see an error message 
-when you try to open the *Detections* page.
+Depending on your privileges and whether detection system indices have already
+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 these privileges must visit the 
-*Detections* page before you can view detection rules and alerts:
-
-* The `manage` cluster privilege (see {ref}/security-privileges.html[{es} security privileges]).
-* The `create_index` index privilege (see {ref}/security-privileges.html[{es} security privileges]).
-* {kib} space `All` privileges for the `Security` feature (see
-{kibana-ref}/xpack-spaces.html#spaces-control-user-access[Feature access based on user privileges]).
+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. 
 
 NOTE: For *on-premises* {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.
+setting has not been added to the `kibana.yml` file. For more information, see <<detections-on-prem-requirements>>.
 
 *`Detection engine permissions required`*
 
@@ -166,4 +137,4 @@ and you should contact your {kib} administrator.
 
 NOTE: For *on-premises* {stack} deployments only, this message may be
 displayed when the <<detections-permissions, `xpack.security.enabled`>>
-setting is not enabled in the `elasticsearch.yml` file.
+setting is not enabled in the `elasticsearch.yml` file. For more information, see <<detections-on-prem-requirements>>.
diff --git a/docs/detections/machine-learning/machine-learning.asciidoc b/docs/detections/machine-learning/machine-learning.asciidoc
@@ -59,11 +59,11 @@ time frame, previously analysed data is not processed again.
 [[view-anomalies]]
 == View detected anomalies
 To view the `Anomalies` table widget and `Max Anomaly Score By Job` details,
-the user must have the `ml_admin` or `ml_user` role.
+the user must have the `machine_learning_admin` or `machine_learning_user` role.
 
 NOTE: To adjust the `score` threshold that determines which
 {ml-docs}/xpack-ml.html[anomalies] are shown, you can modify {kib} -> 
-Management -> Advanced Settings -> `siem:defaultAnomalyScore`.
+Stack Management -> Advanced Settings -> `securitySolution:defaultAnomalyScore`.
 
 [[prebuilt-ml-jobs]]
 == Prebuilt job reference

diff --git a/docs/getting-started/cases-req.asciidoc b/docs/getting-started/cases-req.asciidoc
@@ -0,0 +1,11 @@
+[[case-permissions]]
+= Cases prerequisites
+
+To view cases, you need the {kib} space `Read` privilege for the `Security` feature. To create cases and add comments, you need the `All` {kib}
+space privilege for the `Security` feature.
+
+For more information, see
+{kibana-ref}/xpack-spaces.html#spaces-control-user-access[Feature access based on user privileges].
+
+NOTE: To send cases to external systems, you need the
+https://www.elastic.co/subscriptions[appropriate license].
diff --git a/docs/getting-started/detections-req.asciidoc b/docs/getting-started/detections-req.asciidoc
@@ -0,0 +1,128 @@
+[[detections-permissions-section]]
+= Detections prerequisites and requirements
+
+To use the <<detection-engine-overview, Detections feature>>, you need to
+configure a few things.
+
+IMPORTANT: There are a number of step that are *only* required for *on-premises*
+{stack} deployments. If you are using a cloud deployments, you only need to
+configure <<enable-detections-ui>> and <<access-detections-ui>>.
+
+Additionally, there are some <<adv-list-settings, advanced settings>> used to
+configure {kib} <<detections-ui-exceptions, value list>> upload limits.
+
+You need the https://www.elastic.co/subscriptions[appropriate license] to send
+<<rule-notifications, notifications>> when detection alerts are generated.
+
+[discrete]
+[[detections-on-prem-requirements]]
+== Configure on-premises {stack} deployments
+
+These steps are only required for *on-premises* deployments:
+
+* HTTPS must be configured for communication between
+{kibana-ref}/configuring-tls.html#configuring-tls-kib-es[{es} and {kib}].
+* In the `elasticsearch.yml` configuration file, set the 
+`xpack.security.enabled` setting to `true`. For more information, see 
+{ref}/settings.html[Configuring {es}] and
+{ref}/security-settings.html[Security settings in {es}].
+* In the `kibana.yml` {kibana-ref}/settings.html[configuration file], add the 
+`xpack.encryptedSavedObjects.encryptionKey` setting with any alphanumeric value 
+of at least 32 characters. For example:
++
+`xpack.encryptedSavedObjects.encryptionKey: 'fhjskloppd678ehkdfdlliverpoolfcr'`
+
+IMPORTANT: After changing the `xpack.encryptedSavedObjects.encryptionKey` value
+and restarting {kib}, you must restart all detection rules.
+
+[discrete]
+[[enable-detections-ui]]
+== Enable Detections
+
+To enable the <<detection-engine-overview, Detections feature>>, a user with
+these privileges must visit (click on) the *Detections* page:
+
+* The `manage` cluster privilege
+* {kib} space `All` privileges for the `Security` feature (see
+{kibana-ref}/xpack-spaces.html#spaces-control-user-access[Feature access based on user privileges]).
+* The `manage`, `write`, and `read` index privileges for all of these system indices:
+** `.siem-signals-<kib-space>`
+** `.lists-<kib-space>`
+** `.items-<kib-space`
++
+Where `<kib-space>` is the {kib} space name.
+
+NOTE: If you want the user to be able to create rules as well as enable the
+Detections feature, assign the user with {kib} space `All` privileges for the `Saved Objects
+Management` feature in addition to the above requirements.
+
+For more information on cluster and index privileges, see
+{ref}/security-privileges.html[{es} security privileges].
+
+[TIP]
+==============
+To create a user who can enable Detections on all {kib} spaces, use glob
+patterns. For example, `.siem-signals-*`, `.lists-*`, and `.items-*`.
+==============
+
+Here's a screenshot of a user role that can enable Detections in all {kib}
+spaces:
+
+[role="screenshot"]
+image::images/sec-admin-user.png[]
+
+[discrete]
+[[access-detections-ui]]
+== Access and use Detections
+
+After enabling Detections, only users with these permission can view and use the
+*Detections* page:
+
+* {kib} space `All` privileges for the `Security`  and `Saved Objects
+Management` features
+* The `read` and `write` index privileges for all of these system indices:
+** `.siem-signals-<kib-space>`
+** `.lists-<kib-space>`
+** `.items-<kib-space`
++
+Where `<kib-space>` is the {kib} space name.
+
+TIP: To enable autocomplete for rule queries when creating or modifying
+detection rules, add `read` privileges for all `securitySolution:defaultIndex`
+indices (*{kib}* -> *Stack Management* -> *Advanced Settings* ->
+*`securitySolution:defaultIndex`*).
+
+Here's a screenshot of a user role that can view and create detection rules in all {kib}
+spaces:
+
+[role="screenshot"]
+image::images/sec-user.png[]
+
+[discrete]
+[[adv-list-settings]]
+== Configure list upload limits
+
+You can set limits to the number of bytes and the buffer size used to upload
+<<detections-ui-exceptions, values lists>> to {kib}.
+
+To set the value:
+
+. Open `kibana.yml` {kibana-ref}/settings.html[configuration file] or edit your
+{kib} cloud instance.
+. Add any of these settings and their required values:
+* `xpack.lists.maxImportPayloadBytes`: Sets the number of bytes allowed for
+uploading Security Solution value lists (default `9000000`, maximum
+`100000000`). For every 10 megabytes, it is recommended to have an additional 1
+gigabyte of RAM reserved for Kibana.
++
+For example, on a Kibana instance with 2 gigabytes of RAM, you can set this value up
+to 20000000 (20 megabytes).
+* `xpack.lists.importBufferSize`: Sets the buffer size used for uploading
+Security Solution value lists (default `1000`). Change the value if you are
+experiencing slow upload speeds or larger than wanted memory usage when
+uploading value lists. Set to a higher value to increase throughput at the
+expense of using more Kibana memory, or a lower value to decrease throughput and
+reduce memory usage.
+
+NOTE: For information on how to configure cloud deployments, see
+{cloud}/ec-manage-kibana-settings.html[Add Kibana user settings].
diff --git a/docs/getting-started/images/add-data.png b/docs/getting-started/images/add-data.png
diff --git a/docs/getting-started/images/sec-admin-user.png b/docs/getting-started/images/sec-admin-user.png
diff --git a/docs/getting-started/images/sec-user.png b/docs/getting-started/images/sec-user.png
diff --git a/docs/getting-started/index.asciidoc b/docs/getting-started/index.asciidoc
@@ -1,8 +1,17 @@
+[role="xpack"]
 [[getting-started]]
 = Get started with Elastic Security
 
 Looking to get started with Elastic Security? This section describes the Elastic Security UI in Kibana, the system requirements required to run the Elastic Agent with the Elastic Endpoint Security integration, as well as instructions on how to configure and install Elastic Security on your host.
 
-include::security-ui.asciidoc[leveloffset=+1]
-include::network-page-overview.asciidoc[leveloffset=+2]
+include::sec-app-requirements.asciidoc[leveloffset=+1]
+include::detections-req.asciidoc[leveloffset=+2]
+include::cases-req.asciidoc[leveloffset=+2]
+include::ml-req.asciidoc[leveloffset=+2]
 include::sensor-full-disk-access.asciidoc[leveloffset=+2]
+include::net-map-req.asciidoc[leveloffset=+2]
+include::ingest-data.asciidoc[leveloffset=+1]
+include::security-ui.asciidoc[]
+include::network-page-overview.asciidoc[leveloffset=+1]
+include::../management/hosts/hosts-overview.asciidoc[leveloffset=+1]
+include::../management/admin/admin-pg-ov.asciidoc[leveloffset=+1]
diff --git a/docs/getting-started/ingest-data.asciidoc b/docs/getting-started/ingest-data.asciidoc
@@ -0,0 +1,101 @@
+[[ingest-data]]
+= Ingest data to Elastic Security
+
+To ingest data, you can use:
+
+* *{beats}* shippers installed for each system you want to monitor.
+* *Elastic Endpoint* ships events and security alerts directly to {es}.
+* Third-party collectors configured to ship ECS-compliant data.
+<<siem-field-reference>> provides a list of all fields used in {es-sec}.
+* *Elastic agent and ingest manager* sends logs, metrics, and endpoint security
+data to {es} (beta). 
+
+[IMPORTANT]
+==============
+If you use a third-party collector to ship data to the {siem-app}, you must 
+map its fields to the {ecs-ref}[Elastic Common Schema (ECS)]. Additionally, 
+you must add its index to the {es-sec} indices (*{kib}* -> 
+*Stack Management* -> *Advanced Settings* -> *`securitySolution:defaultIndex`*).
+
+{siem-soln} uses the {ecs-ref}/ecs-host.html[`host.name`] ECS field as the 
+primary key for identifying hosts.
+==============
+
+[discrete]
+[[install-beats]]
+== Install {beats} shippers
+
+To populate {es-sec} with hosts and network security events, you need to install and
+configure Beats on the systems from which you want to ingest security events:
+
+* https://www.elastic.co/products/beats/filebeat[{filebeat}] for forwarding and
+centralizing logs and files
+* https://www.elastic.co/products/beats/auditbeat[{auditbeat}] for collecting security events
+* https://www.elastic.co/products/beats/winlogbeat[{winlogbeat}] for centralizing
+Windows event logs
+* https://www.elastic.co/products/beats/packetbeat[{packetbeat}] for analyzing
+network activity
+
+You can install {beats} using the {kib} UI guide or directly from the command line.
+
+[discrete]
+=== Install {beats} using the {kib} UI guide
+
+Click *Home* -> *Add events*, and follow the links for the types of data you want to
+collect.
+
+[role="screenshot"]
+image::images/add-data.png[]
+
+[float]
+=== Download and install {beats} from the command line
+
+To install {beats}:
+
+* *{filebeat} and {filebeat} modules.* See the
+{filebeat-ref}/filebeat-installation-configuration.html[{filebeat} quick start]
+and enable modules for the events you want to collect. If there is no module
+for the events you want to collect, see the
+{filebeat-ref}/configuration-filebeat-options.html[Conifgure inputs].
+
+* *Auditbeat.* See {auditbeat-ref}/auditbeat-installation-configuration.html[{auditbeat} quick start].
+
+* *Winlogbeat.* See {winlogbeat-ref}/winlogbeat-installation-configuration.html[{winlogbeat} quick start].
+
+* *Packetbeat.* See {packetbeat-ref}/packetbeat-installation-configuration.html[{packetbeat} quick start].
+
+[discrete]
+=== Enable modules and configuration options
+
+No matter how you installed {beats}, you need to enable modules in {auditbeat}
+and {filebeat} to populate {es-sec} with data.
+
+TIP: For a full list of security-related beat modules, 
+https://www.elastic.co/integrations?solution=security[click here].
+
+To populate *Hosts* data, enable these {auditbeat} modules:
+
+* {auditbeat-ref}/auditbeat-module-system.html[System module  - Linux, macOS, Win]
+* {auditbeat-ref}/auditbeat-module-auditd.html[Auditd module (Linux Kernel Audit info)]
+* {auditbeat-ref}/auditbeat-module-file_integrity.html[File integrity module (FIM) - Linux, macOS, Win]
+
+
+To populate *Network* data, enable the relevant {packetbeat} protocols
+and {filebeat} modules:
+
+* https://www.elastic.co/products/beats/packetbeat[{packetbeat}]:
+** {packetbeat-ref}/packetbeat-dns-options.html[DNS]
+** {packetbeat-ref}/configuration-tls.html[TLS]
+** {packetbeat-ref}/configuration-protocols.html[Other supported protocols]
+* https://www.elastic.co/products/beats/filebeat[{filebeat}]:
+** {filebeat-ref}/filebeat-module-zeek.html[Zeek NMS module]
+** {filebeat-ref}/filebeat-module-suricata.html[Suricata IDS module]
+** {filebeat-ref}/filebeat-module-iptables.html[Iptables/Ubiquiti module]
+** {filebeat-ref}/filebeat-module-coredns.html[CoreDNS module]
+** {filebeat-ref}/filebeat-module-envoyproxy.html[Envoy proxy module (Kubernetes)]
+** {filebeat-ref}/filebeat-module-panw.html[Palo Alto Networks firewall module]
+** {filebeat-ref}/filebeat-module-cisco.html[Cisco ASA firewall module]
+** {filebeat-ref}/filebeat-module-aws.html[AWS module]
+** {filebeat-ref}/filebeat-module-cef.html[CEF module]
+** {filebeat-ref}/filebeat-module-googlecloud.html[Google Cloud module]
+** {filebeat-ref}/filebeat-module-netflow.html[NetFlow module]
diff --git a/docs/getting-started/ml-req.asciidoc b/docs/getting-started/ml-req.asciidoc
@@ -0,0 +1,10 @@
+[[ml-requirements]]
+= Machine learning job and rule requirements
+
+To run and create {ml} jobs and rules, you need all of these:
+
+* The *https://www.elastic.co/subscriptions[appropriate license]*
+* {ml-cap} enabled on all master-eligible and coordinating {es} nodes (see
+{ref}/modules-node.html#ml-node[{ml-cap} node])
+* The `machine_learning_admin` user role (see
+{ref}/built-in-roles.html[Built-in roles])