From b4da90311cab35be811baa9192278f12bd2b193a Mon Sep 17 00:00:00 2001 From: Gail Chappell Date: Wed, 30 Jun 2021 11:39:21 -0700 Subject: [PATCH 1/8] [DOCS] Creates separate doc for security in production --- ...lerting-production-considerations.asciidoc | 2 +- .../production-considerations/index.asciidoc | 1 + .../production.asciidoc | 82 ++++--------------- ...ecurity-production-considerations.asciidoc | 52 ++++++++++++ 4 files changed, 70 insertions(+), 67 deletions(-) create mode 100644 docs/user/production-considerations/security-production-considerations.asciidoc diff --git a/docs/user/production-considerations/alerting-production-considerations.asciidoc b/docs/user/production-considerations/alerting-production-considerations.asciidoc index bd19a11435a99..9ed681f07e58f 100644 --- a/docs/user/production-considerations/alerting-production-considerations.asciidoc +++ b/docs/user/production-considerations/alerting-production-considerations.asciidoc @@ -36,7 +36,7 @@ For detailed guidance, see < [float] [[alerting-scaling-guidance]] -=== Scaling Guidance +=== Scaling guidance As rules and actions leverage background tasks to perform the majority of work, scaling Alerting is possible by following the <>. diff --git a/docs/user/production-considerations/index.asciidoc b/docs/user/production-considerations/index.asciidoc index 198e8324af3e6..22307f6394248 100644 --- a/docs/user/production-considerations/index.asciidoc +++ b/docs/user/production-considerations/index.asciidoc @@ -1,4 +1,5 @@ include::production.asciidoc[] +include::security-production-considerations.asciidoc[] include::alerting-production-considerations.asciidoc[] include::reporting-production-considerations.asciidoc[] include::task-manager-production-considerations.asciidoc[] diff --git a/docs/user/production-considerations/production.asciidoc b/docs/user/production-considerations/production.asciidoc index b75b556588cfd..2c788495c9030 100644 --- a/docs/user/production-considerations/production.asciidoc +++ b/docs/user/production-considerations/production.asciidoc @@ -5,74 +5,24 @@ Production considerations ++++ -* <> -* <> -* <> -* <> -* <> -* <> -* <> - -How you deploy Kibana largely depends on your use case. If you are the only user, -you can run Kibana on your local machine and configure it to point to whatever -Elasticsearch instance you want to interact with. Conversely, if you have a large -number of heavy Kibana users, you might need to load balance across multiple -Kibana instances that are all connected to the same Elasticsearch instance. - -While Kibana isn't terribly resource intensive, we still recommend running Kibana -separate from your Elasticsearch data or master nodes. To distribute Kibana -traffic across the nodes in your Elasticsearch cluster, -you can configure Kibana to use a list of Elasticsearch hosts. +How you deploy {kib} largely depends on your use case. If you are the only user, +you can run {kib} on your local machine and configure it to point to whatever +{es} instance you want to interact with. Conversely, if you have a large +number of heavy {kib} users, you might need to load balance across multiple +{kib} instances that are all connected to the same {es} instance. -[float] -[[configuring-kibana-shield]] -=== Use {stack} {security-features} - -You can use {stack} {security-features} to control what {es} data users can -access through Kibana. - -When {security-features} are enabled, Kibana users have to log in. They need to -have a role granting <> as well as access -to the indices they will be working with in Kibana. - -If a user loads a Kibana dashboard that accesses data in an index that they -are not authorized to view, they get an error that indicates the index does -not exist. - -For more information on granting access to Kibana, see <>. - -[float] -[[csp-strict-mode]] -=== Require Content Security Policy - -Kibana uses a Content Security Policy to help prevent the browser from allowing -unsafe scripting, but older browsers will silently ignore this policy. If your -organization does not need to support Internet Explorer 11 or much older -versions of our other supported browsers, we recommend that you enable Kibana's -`strict` mode for content security policy, which will block access to Kibana -for any browser that does not enforce even a rudimentary set of CSP -protections. - -To do this, set `csp.strict` to `true` in your `kibana.yml`: - -[source,js] --------- -csp.strict: true --------- - - -[float] -[[enabling-ssl]] -=== Enable SSL - -See <>. +While {kib} isn't terribly resource intensive, we still recommend running {kib} +separate from your {es} data or master nodes. To distribute {kib} +traffic across the nodes in your {es} cluster, +you can configure {kib} to use a list of {es} hosts. [float] [[load-balancing-kibana]] -=== Load balancing across multiple Kibana instances -To serve multiple Kibana installations behind a load balancer, you must change the configuration. See {kibana-ref}/settings.html[Configuring Kibana] for details on each setting. +=== Load balancing across multiple {kib} instances +To serve multiple {kib} installations behind a load balancer, you must change the configuration. +See {kibana-ref}/settings.html[Configuring {kib}] for details on each setting. -Settings unique across each Kibana instance: +Settings unique across each {kib} instance: [source,js] -------- server.uuid @@ -119,8 +69,8 @@ active in case of failure from the currently used instance. [float] [[high-availability]] === High availability across multiple {es} nodes -Kibana can be configured to connect to multiple Elasticsearch nodes in the same cluster. In situations where a node becomes unavailable, -Kibana will transparently connect to an available node and continue operating. Requests to available hosts will be routed in a round robin fashion. +{kib} can be configured to connect to multiple {es} nodes in the same cluster. In situations where a node becomes unavailable, +{kib} will transparently connect to an available node and continue operating. Requests to available hosts will be routed in a round robin fashion. In kibana.yml: [source,js] @@ -136,7 +86,7 @@ These can be used to automatically update the list of hosts as a cluster is resi [float] [[memory]] === Memory -Kibana has a default maximum memory limit of 1.4 GB, and in most cases, we recommend leaving this unconfigured. In some scenarios, such as large reporting jobs, +{kib} has a default maximum memory limit of 1.4 GB, and in most cases, we recommend leaving this unconfigured. In some scenarios, such as large reporting jobs, it may make sense to tweak limits to meet more specific requirements. You can modify this limit by setting `--max-old-space-size` in the `node.options` config file that can be found inside `kibana/config` folder or any other configured with the environment variable `KBN_PATH_CONF` (for example in debian based system would be `/etc/kibana`). diff --git a/docs/user/production-considerations/security-production-considerations.asciidoc b/docs/user/production-considerations/security-production-considerations.asciidoc new file mode 100644 index 0000000000000..72f5b580df05a --- /dev/null +++ b/docs/user/production-considerations/security-production-considerations.asciidoc @@ -0,0 +1,52 @@ +[role="xpack"] +[[Security-production-considerations]] +== Security production considerations + +++++ +Security +++++ +:keywords: administrator, analyst, concept, setup, security +:description: Consider the production components for Kibana security. + +[float] +[[configuring-kibana-shield]] +=== Use {stack} {security-features} + +You can use {stack} {security-features} to control what {es} data users can +access through Kibana. + +When {security-features} are enabled, Kibana users have to log in. They need to +have a role granting <> as well as access +to the indices they will be working with in Kibana. + +If a user loads a Kibana dashboard that accesses data in an index that they +are not authorized to view, they get an error that indicates the index does +not exist. + +For more information on granting access to Kibana, see <>. + +[float] +[[csp-strict-mode]] +=== Require Content Security Policy + +Kibana uses a Content Security Policy to help prevent the browser from allowing +unsafe scripting, but older browsers will silently ignore this policy. If your +organization does not need to support Internet Explorer 11 or much older +versions of our other supported browsers, we recommend that you enable Kibana's +`strict` mode for content security policy, which will block access to Kibana +for any browser that does not enforce even a rudimentary set of CSP +protections. + +To do this, set `csp.strict` to `true` in your `kibana.yml`: + +[source,js] +-------- +csp.strict: true +-------- + + +[float] +[[enabling-ssl]] +=== Enable SSL + +See <>. From 8fbe2ecd0a3faa1de8394096f17ae0d05816a6c8 Mon Sep 17 00:00:00 2001 From: Joe Portner <5295965+jportner@users.noreply.github.com> Date: Tue, 6 Jul 2021 14:44:23 -0400 Subject: [PATCH 2/8] Use Kibana attribute --- ...lerting-production-considerations.asciidoc | 2 +- ...ecurity-production-considerations.asciidoc | 20 +++++++++---------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/user/production-considerations/alerting-production-considerations.asciidoc b/docs/user/production-considerations/alerting-production-considerations.asciidoc index 9ed681f07e58f..57cc2a72a8895 100644 --- a/docs/user/production-considerations/alerting-production-considerations.asciidoc +++ b/docs/user/production-considerations/alerting-production-considerations.asciidoc @@ -58,7 +58,7 @@ Alerts and actions log activity in a set of "event log" indices. These indices The name of the index policy is `kibana-event-log-policy`. {kib} creates the index policy on startup, if it doesn't already exist. The index policy can be customized for your environment, but {kib} never modifies the index policy after creating it. -Because Kibana uses the documents to display historic data, you should set the delete phase longer than you would like the historic data to be shown. For example, if you would like to see one month's worth of historic data, you should set the delete phase to at least one month. +Because {kib} uses the documents to display historic data, you should set the delete phase longer than you would like the historic data to be shown. For example, if you would like to see one month's worth of historic data, you should set the delete phase to at least one month. For more information on index lifecycle management, see: {ref}/index-lifecycle-management.html[Index Lifecycle Policies]. diff --git a/docs/user/production-considerations/security-production-considerations.asciidoc b/docs/user/production-considerations/security-production-considerations.asciidoc index 72f5b580df05a..c74c203de30df 100644 --- a/docs/user/production-considerations/security-production-considerations.asciidoc +++ b/docs/user/production-considerations/security-production-considerations.asciidoc @@ -6,34 +6,34 @@ Security ++++ :keywords: administrator, analyst, concept, setup, security -:description: Consider the production components for Kibana security. +:description: Consider the production components for {kib} security. [float] [[configuring-kibana-shield]] === Use {stack} {security-features} You can use {stack} {security-features} to control what {es} data users can -access through Kibana. +access through {kib}. -When {security-features} are enabled, Kibana users have to log in. They need to -have a role granting <> as well as access -to the indices they will be working with in Kibana. +When {security-features} are enabled, {kib} users have to log in. They need to +have a role granting <> as well as access +to the indices they will be working with in {kib}. -If a user loads a Kibana dashboard that accesses data in an index that they +If a user loads a {kib} dashboard that accesses data in an index that they are not authorized to view, they get an error that indicates the index does not exist. -For more information on granting access to Kibana, see <>. +For more information on granting access to {kib}, see <>. [float] [[csp-strict-mode]] === Require Content Security Policy -Kibana uses a Content Security Policy to help prevent the browser from allowing +{kib} uses a Content Security Policy to help prevent the browser from allowing unsafe scripting, but older browsers will silently ignore this policy. If your organization does not need to support Internet Explorer 11 or much older -versions of our other supported browsers, we recommend that you enable Kibana's -`strict` mode for content security policy, which will block access to Kibana +versions of our other supported browsers, we recommend that you enable {kib}'s +`strict` mode for content security policy, which will block access to {kib} for any browser that does not enforce even a rudimentary set of CSP protections. From 16149addb3047563fef9000a25ee185d7ea4f431 Mon Sep 17 00:00:00 2001 From: Joe Portner <5295965+jportner@users.noreply.github.com> Date: Tue, 6 Jul 2021 14:46:07 -0400 Subject: [PATCH 3/8] Update CSP section --- .../security-production-considerations.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user/production-considerations/security-production-considerations.asciidoc b/docs/user/production-considerations/security-production-considerations.asciidoc index c74c203de30df..a4ba29d739e9a 100644 --- a/docs/user/production-considerations/security-production-considerations.asciidoc +++ b/docs/user/production-considerations/security-production-considerations.asciidoc @@ -29,9 +29,9 @@ For more information on granting access to {kib}, see < Date: Tue, 6 Jul 2021 14:46:48 -0400 Subject: [PATCH 4/8] Move SSL section to the top This is the highest priority item for securing a production installation of Kibana. --- .../security-production-considerations.asciidoc | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/user/production-considerations/security-production-considerations.asciidoc b/docs/user/production-considerations/security-production-considerations.asciidoc index a4ba29d739e9a..73d735858058d 100644 --- a/docs/user/production-considerations/security-production-considerations.asciidoc +++ b/docs/user/production-considerations/security-production-considerations.asciidoc @@ -8,6 +8,12 @@ :keywords: administrator, analyst, concept, setup, security :description: Consider the production components for {kib} security. +[float] +[[enabling-ssl]] +=== Enable SSL + +See <>. + [float] [[configuring-kibana-shield]] === Use {stack} {security-features} @@ -43,10 +49,3 @@ To do this, set `csp.strict` to `true` in your `kibana.yml`: -------- csp.strict: true -------- - - -[float] -[[enabling-ssl]] -=== Enable SSL - -See <>. From 3720c1f453f82c966e636c103fd729543100c47c Mon Sep 17 00:00:00 2001 From: Joe Portner <5295965+jportner@users.noreply.github.com> Date: Tue, 6 Jul 2021 15:35:13 -0400 Subject: [PATCH 5/8] Add section on using secure HTTP headers --- ...ecurity-production-considerations.asciidoc | 30 ++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/docs/user/production-considerations/security-production-considerations.asciidoc b/docs/user/production-considerations/security-production-considerations.asciidoc index 73d735858058d..b69905174c912 100644 --- a/docs/user/production-considerations/security-production-considerations.asciidoc +++ b/docs/user/production-considerations/security-production-considerations.asciidoc @@ -10,7 +10,7 @@ [float] [[enabling-ssl]] -=== Enable SSL +=== Enable SSL/TLS See <>. @@ -31,6 +31,34 @@ not exist. For more information on granting access to {kib}, see <>. +[float] +[[configuring-security-headers]] +=== Use secure HTTP headers + +The {kib} server can instruct browsers to enable additional security controls using HTTP headers. + +1. Enable HTTP Strict-Transport-Security ++ +You can use <> to ensure that browsers will only attempt +to access {kib} with SSL/TLS encryption. This is designed to prevent man-in-the-middle attacks. To configure this with a lifetime of one +year in your `kibana.yml`: ++ +[source,js] +-------- +server.securityResponseHeaders.strictTransportSecurity: "max-age=31536000" +-------- ++ +WARNING: This header will block unencrypted connections for the entire domain. If you host more than one web application on the same domain using different ports or paths, all of them will be affected. + +2. Disable embedding ++ +You can use to ensure that {kib} cannot be embedded in other website. To configure this in your `kibana.yml`: ++ +[source,js] +-------- +server.securityResponseHeaders.disableEmbedding: true +-------- + [float] [[csp-strict-mode]] === Require Content Security Policy From 7676c4c8797257bcc9292d336e54387302d0024e Mon Sep 17 00:00:00 2001 From: Joe Portner <5295965+jportner@users.noreply.github.com> Date: Tue, 6 Jul 2021 15:46:54 -0400 Subject: [PATCH 6/8] Write intro --- .../security-production-considerations.asciidoc | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/user/production-considerations/security-production-considerations.asciidoc b/docs/user/production-considerations/security-production-considerations.asciidoc index b69905174c912..59202a750ccc6 100644 --- a/docs/user/production-considerations/security-production-considerations.asciidoc +++ b/docs/user/production-considerations/security-production-considerations.asciidoc @@ -8,11 +8,15 @@ :keywords: administrator, analyst, concept, setup, security :description: Consider the production components for {kib} security. +To secure your {kib} installation in production, there are a few high priority topics to consider to ensure that {kib} can only be accessed +by authorized users. For more information on {kib}'s security controls, see <>. + [float] [[enabling-ssl]] === Enable SSL/TLS -See <>. +You should use SSL/TLS encryption to ensure that traffic between browsers and the {kib} server cannot be viewed or tampered with by third +parties. See <>. [float] [[configuring-kibana-shield]] @@ -48,11 +52,13 @@ year in your `kibana.yml`: server.securityResponseHeaders.strictTransportSecurity: "max-age=31536000" -------- + -WARNING: This header will block unencrypted connections for the entire domain. If you host more than one web application on the same domain using different ports or paths, all of them will be affected. +WARNING: This header will block unencrypted connections for the entire domain. If you host more than one web application on the same domain +using different ports or paths, all of them will be affected. 2. Disable embedding + -You can use to ensure that {kib} cannot be embedded in other website. To configure this in your `kibana.yml`: +You can use to ensure that {kib} cannot be embedded in other website. +To configure this in your `kibana.yml`: + [source,js] -------- From e6a34700b2f5e46e7e8b1c8ffe8e4fa4895ef3c4 Mon Sep 17 00:00:00 2001 From: Gail Chappell Date: Wed, 7 Jul 2021 11:05:16 -0700 Subject: [PATCH 7/8] [DOCS] Fixes broken link and other minor edits --- docs/setup/settings.asciidoc | 3 +- ...ecurity-production-considerations.asciidoc | 33 ++++++++++--------- 2 files changed, 19 insertions(+), 17 deletions(-) diff --git a/docs/setup/settings.asciidoc b/docs/setup/settings.asciidoc index d9a48835553cf..7e7e2b9d1a4cf 100644 --- a/docs/setup/settings.asciidoc +++ b/docs/setup/settings.asciidoc @@ -557,11 +557,10 @@ deprecation warning at startup. This setting cannot end in a slash (`/`). proxy sitting in front of it. This determines whether HTTP compression may be used for responses, based on the request `Referer` header. This setting may not be used when <> is set to `false`. *Default: `none`* -[[server-securityResponseHeaders-strictTransportSecurity]] a| `server.securityResponseHeaders:` `strictTransportSecurity:` -| Controls whether the https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security[`Strict-Transport-Security`] +| [[server-securityResponseHeaders-strictTransportSecurity]] Controls whether the https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security[`Strict-Transport-Security`] header is used in all responses to the client from the {kib} server, and specifies what value is used. Allowed values are any text value or `null`. To disable, set to `null`. *Default:* `null` diff --git a/docs/user/production-considerations/security-production-considerations.asciidoc b/docs/user/production-considerations/security-production-considerations.asciidoc index 59202a750ccc6..96f18ff0fe7b9 100644 --- a/docs/user/production-considerations/security-production-considerations.asciidoc +++ b/docs/user/production-considerations/security-production-considerations.asciidoc @@ -8,8 +8,9 @@ :keywords: administrator, analyst, concept, setup, security :description: Consider the production components for {kib} security. -To secure your {kib} installation in production, there are a few high priority topics to consider to ensure that {kib} can only be accessed -by authorized users. For more information on {kib}'s security controls, see <>. +To secure your {kib} installation in production, consider these high-priority topics to ensure +that only authorized users can access {kib}. +For more information on {kib}'s security controls, see <>. [float] [[enabling-ssl]] @@ -25,9 +26,9 @@ parties. See <>. You can use {stack} {security-features} to control what {es} data users can access through {kib}. -When {security-features} are enabled, {kib} users have to log in. They need to -have a role granting <> as well as access -to the indices they will be working with in {kib}. +When {security-features} are enabled, {kib} users have to log in. They must +have a role granting <> and access +to the indices that they will be working with in {kib}. If a user loads a {kib} dashboard that accesses data in an index that they are not authorized to view, they get an error that indicates the index does @@ -41,10 +42,11 @@ For more information on granting access to {kib}, see <> to ensure that browsers will only attempt -to access {kib} with SSL/TLS encryption. This is designed to prevent man-in-the-middle attacks. To configure this with a lifetime of one +Use <> to ensure that browsers will only attempt +to access {kib} with SSL/TLS encryption. This is designed to prevent man-in-the-middle attacks. +To configure this with a lifetime of one year in your `kibana.yml`: + [source,js] @@ -55,9 +57,10 @@ server.securityResponseHeaders.strictTransportSecurity: "max-age=31536000" WARNING: This header will block unencrypted connections for the entire domain. If you host more than one web application on the same domain using different ports or paths, all of them will be affected. -2. Disable embedding +2. Disable embedding. + -You can use to ensure that {kib} cannot be embedded in other website. +Use <> to ensure +that {kib} cannot be embedded in other websites. To configure this in your `kibana.yml`: + [source,js] @@ -67,13 +70,13 @@ server.securityResponseHeaders.disableEmbedding: true [float] [[csp-strict-mode]] -=== Require Content Security Policy +=== Require a Content Security Policy -{kib} uses a Content Security Policy (CSP) to help prevent the browser from allowing +{kib} uses a Content Security Policy (CSP) to prevent the browser from allowing unsafe scripting, but older browsers will silently ignore this policy. If your -organization does not need to support extremely old -versions of our other supported browsers, we recommend that you enable {kib}'s -`strict` mode for content security policy, which will block access to {kib} +organization does not need to support very old +versions of our supported browsers, we recommend that you enable {kib}'s +`strict` mode for the CSP. This will block access to {kib} for any browser that does not enforce even a rudimentary set of CSP protections. From 2ba02f4032cddb178bd79dcb2cab6147ab610fe1 Mon Sep 17 00:00:00 2001 From: Gail Chappell Date: Wed, 7 Jul 2021 11:29:51 -0700 Subject: [PATCH 8/8] [DOCS] Changes man to manipulator --- .../security-production-considerations.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/production-considerations/security-production-considerations.asciidoc b/docs/user/production-considerations/security-production-considerations.asciidoc index 96f18ff0fe7b9..a23911375639f 100644 --- a/docs/user/production-considerations/security-production-considerations.asciidoc +++ b/docs/user/production-considerations/security-production-considerations.asciidoc @@ -45,7 +45,7 @@ The {kib} server can instruct browsers to enable additional security controls us 1. Enable HTTP Strict-Transport-Security. + Use <> to ensure that browsers will only attempt -to access {kib} with SSL/TLS encryption. This is designed to prevent man-in-the-middle attacks. +to access {kib} with SSL/TLS encryption. This is designed to prevent manipulator-in-the-middle attacks. To configure this with a lifetime of one year in your `kibana.yml`: +