[DOCS] Add ES security principles

docs/reference/redirects.asciidoc

@@ -3,6 +3,11 @@
 
 The following pages have moved or been deleted.
 
+[role="exclude",id="modules-scripting-other-layers"]
+=== Other security layers
+
+Refer to <<modules-scripting-security>>.
+
 [role="exclude",id="grok-basics"]
 === Grok basics
 

docs/reference/scripting/security.asciidoc

@@ -1,114 +1,63 @@
 [[modules-scripting-security]]
 == Scripting and security
+Painless and {es} implement layers of security to build a defense in depth
+strategy for running scripts safely.
 
-While Elasticsearch contributors make every effort to prevent scripts from
-running amok, security is something best done in
-{wikipedia}/Defense_in_depth_(computing)[layers] because
-all software has bugs and it is important to minimize the risk of failure in
-any security layer. Find below rules of thumb for how to keep Elasticsearch
-from being a vulnerability.
+Painless uses a fine-grained allowlist. Anything that is not part of the
+allowlist results in a compilation error. This capability is the first layer of
+security in a defense in depth strategy for scripting.
 
-[discrete]
-=== Do not run as root
-First and foremost, never run Elasticsearch as the `root` user as this would
-allow any successful effort to circumvent the other security layers to do
-*anything* on your server. Elasticsearch will refuse to start if it detects
-that it is running as `root` but this is so important that it is worth double
-and triple checking.
-
-[discrete]
-=== Do not expose Elasticsearch directly to users
-Do not expose Elasticsearch directly to users, instead have an application
-make requests on behalf of users. If this is not possible, have an application
-to sanitize requests from users. If *that* is not possible then have some
-mechanism to track which users did what. Understand that it is quite possible
-to write a <<search, `_search`>> that overwhelms Elasticsearch and brings down
-the cluster. All such searches should be considered bugs and the Elasticsearch
-contributors make an effort to prevent this but they are still possible.
-
-[discrete]
-=== Do not expose Elasticsearch directly to the Internet
-Do not expose Elasticsearch to the Internet, instead have an application
-make requests on behalf of the Internet. Do not entertain the thought of having
-an application "sanitize" requests to Elasticsearch. Understand that it is
-possible for a sufficiently determined malicious user to write searches that
-overwhelm the Elasticsearch cluster and bring it down. For example:
-
-Good:
-
-* Users type text into a search box and the text is sent directly to a
-<<query-dsl-match-query>>, <<query-dsl-match-query-phrase>>,
-<<query-dsl-simple-query-string-query>>, or any of the <<search-suggesters>>.
-* Running a script with any of the above queries that was written as part of
-the application development process.
-* Running a script with `params` provided by users.
-* User actions makes documents with a fixed structure.
+The second layer of security is the https://www.oracle.com/java/technologies/javase/seccodeguide.html[Java Security Manager]. As part of its startup
+sequence, {es} enables the Java Security Manager to limit the actions that
+portions of the code can take. <<modules-scripting-painless,Painless>> uses 
+the Java Security Manager as an additional layer of defense to prevent scripts 
+from doing things like writing files and listening to sockets.
 
-Bad:
-
-* Users can write arbitrary scripts, queries, `_search` requests.
-* User actions make documents with structure defined by users.
-
-[discrete]
-[[modules-scripting-other-layers]]
-=== Other security layers
-In addition to user privileges and script sandboxing Elasticsearch uses the
-https://www.oracle.com/java/technologies/javase/seccodeguide.html[Java Security Manager]
-and native security tools as additional layers of security.
-
-As part of its startup sequence Elasticsearch enables the Java Security Manager
-which limits the actions that can be taken by portions of the code. Painless
-uses this to limit the actions that generated Painless scripts can take,
-preventing them from being able to do things like write files and listen to
-sockets.
-
-Elasticsearch uses
+{es} uses
 {wikipedia}/Seccomp[seccomp] in Linux,
 https://www.chromium.org/developers/design-documents/sandbox/osx-sandboxing-design[Seatbelt]
 in macOS, and
 https://msdn.microsoft.com/en-us/library/windows/desktop/ms684147[ActiveProcessLimit]
-on Windows to prevent Elasticsearch from forking or executing other processes.
+on Windows as additional security layers to prevent {es} from forking or 
+running other processes.
 
-Below this we describe the security settings for scripts and how you can
-change from the defaults described above. You should be very, very careful
-when allowing more than the defaults. Any extra permissions weakens the total
-security of the Elasticsearch deployment.
+You can modify the following script settings to restrict the type of scripts
+that are allowed to run, and control the available 
+{painless}/painless-contexts.html[contexts] that scripts can run in. To
+implement additional layers in your defense in depth strategy, follow the 
+<<es-security-principles,{es} security principles>>.
 
 [[allowed-script-types-setting]]
 [discrete]
 === Allowed script types setting
 
-Elasticsearch supports two script types: `inline` and `stored` (<<modules-scripting-using>>).
-By default, {es} is configured to run both types of scripts.
-To limit what type of scripts are run, set `script.allowed_types` to `inline` or `stored`.
-To prevent any scripts from running, set `script.allowed_types` to `none`.
+{es} supports two script types: `inline` and `stored`. By default, {es} is 
+configured to run both types of scripts. To limit what type of scripts are run, 
+set `script.allowed_types` to `inline` or `stored`. To prevent any scripts from 
+running, set `script.allowed_types` to `none`.
 
 IMPORTANT: If you use {kib}, set `script.allowed_types` to `both` or `inline`.
 Some {kib} features rely on inline scripts and do not function as expected
 if {es} does not allow inline scripts.
 
-For example, to run `inline` scripts but not `stored` scripts, specify:
+For example, to run `inline` scripts but not `stored` scripts:
 
 [source,yaml]
 ----
-script.allowed_types: inline <1>
+script.allowed_types: inline
 ----
-<1> This will allow only inline scripts to be executed but not stored scripts
-(or any other types).
-
 
 [[allowed-script-contexts-setting]]
 [discrete]
 === Allowed script contexts setting
 
-By default all script contexts are allowed to be executed. This can be modified using the
-setting `script.allowed_contexts`. Only the contexts specified as part of the setting will
-be allowed to be executed. To specify no contexts are allowed, set `script.allowed_contexts`
-to be `none`.
+By default, all script contexts are permitted. Use the `script.allowed_contexts`
+setting to specify the contexts that are allowed. To specify that no contexts
+are allowed, set `script.allowed_contexts` to `none`.
+
+For example, to allow scripts to run only in `scoring` and `update` contexts:
 
 [source,yaml]
 ----
-script.allowed_contexts: score, update <1>
+script.allowed_contexts: score, update
 ----
-<1> This will allow only scoring and update scripts to be executed but not
-aggs or plugin scripts (or any other contexts).

x-pack/docs/en/security/es-security-principles.asciidoc

@@ -0,0 +1,54 @@
+[[es-security-principles]]
+== {es} security principles
+Protecting your {es} cluster and the data it contains is of utmost importance.
+Implementing a defense in depth strategy provides multiple layers of security
+to help safeguard your system. The following principles provide a foundation
+for running {es} in a secure manner that helps to mitigate attacks on your
+system at multiple levels.
+
+[discrete]
+[[security-run-with-security]]
+=== Run {es} with security enabled
+Never run an {es} cluster without security enabled. This principle cannot be
+overstated. Running {es} without security leaves your cluster exposed to anyone
+who can send network traffic to {es}, permitting these individuals to download,
+modify, or delete any data in your cluster.
+<<configuring-stack-security,Start the {stack} with security enabled>> or
+<<manually-configure-security,manually configure security>> to prevent
+unauthorized access to your clusters and ensure that internode communication
+is secure. 
+
+[discrete]
+[[security-not-root-user]]
+=== Run {es} with a dedicated non-root user
+Never try to run {es} as the `root` user, which would invalidate any defense 
+strategy and permit a malicious user to do *anything* on your server. You must 
+create a dedicated, unprivileged user to run {es}. By default, the `rpm`, `deb`, 
+`docker`, and Windows packages of {es} contain an `elasticsearch` user with
+this scope.
+
+[discrete]
+[[security-protect-cluster-traffic]]
+=== Protect {es} from public internet traffic
+Even with security enabled, never expose {es} to public internet traffic.
+Using an application to sanitize requests to {es} still poses risks, such as
+a malicious user writing <<search,`_search`>> requests that could overwhelm an
+{es} cluster and bring it down. Keep {es} as isolated as possible, preferably
+behind a firewall and a VPN. Any internet-facing applications should run 
+pre-canned aggregations, or not run aggregations at all.
+
+While you absolutely shouldn't expose {es} directly to the internet, you also
+shouldn't expose {es} directly to users. Instead, use an intermediary
+application to make requests on behalf of users. This implementation allows you 
+to track user behaviors, such as can submit requests, and to which specific
+nodes in the cluster. For example, you can implement an application that accepts
+a search term from a user and funnels it through a
+<<query-dsl-simple-query-string-query,`simple_query_string`>> query. 
+
+[discrete]
+[[security-create-appropriate-users]]
+=== Implement role based access control
+<<defining-roles,Define roles>> for your users and
+<<security-privileges,assign appropriate privileges>> to ensure that users have
+access only to the resources that they need. This process determines whether the 
+user behind an incoming request is allowed to run that request.

x-pack/docs/en/security/index.asciidoc

@@ -1,19 +1,21 @@
 [[secure-cluster]]
-= Secure the Elastic Stack
+= Secure the {stack}
 
 [partintro]
 --
 
-The Elastic Stack is comprised of many moving parts. There are the {es}
+The {stack} is comprised of many moving parts. There are the {es}
 nodes that form the cluster, plus {ls} instances, {kib} instances, {beats}
-agents, and clients all communicating with the cluster.
+agents, and clients all communicating with the cluster. To keep your cluster
+safe, adhere to the <<es-security-principles,{es} security principles>>.
 
-<<configuring-stack-security,Configure security for the Elastic Stack>> to
+<<configuring-stack-security,Start the {stack} with security enabled>> or
+<<manually-configure-security,manually configure security>> to
 secure {es} clusters and any clients that communicate with your clusters. You
 can password protect access to your data as well as enable more advanced
 security by configuring Transport Layer Security (TLS). This additional layer
 provides confidentiality and integrity protection to your communications with
-the Elastic Stack. You can also implement additional security measures, such as
+the {stack}. You can also implement additional security measures, such as
 role-based access control, IP filtering, and auditing.
 
 Enabling security protects {es} clusters by:
@@ -71,7 +73,7 @@ of your data against tampering, while also providing _confidentiality_ by
 encrypting communications to, from, and within the cluster. For even	greater
 protection, you can increase the <<ciphers,encryption strength>>.
 
-See <<configuring-stack-security,Configure security for the Elastic Stack>>.
+See <<configuring-stack-security,Configure security for the {stack}>>.
 
 [discrete]
 [[maintaining-audit-trail]]
@@ -90,6 +92,8 @@ See <<enable-audit-logging,Enable audit logging>>.
 
 --
 
+include::es-security-principles.asciidoc[]
+
 include::configuring-stack-security.asciidoc[]
 
 include::security-manual-configuration.asciidoc[]

x-pack/docs/en/security/security-manual-configuration.asciidoc

@@ -1,3 +1,4 @@
+[[manually-configure-security]]
 == Manually configure security
 ++++
 <titleabbrev>Configure security</titleabbrev>