From 2a459c4e46899f65844f7e65be63865b9df7cdce Mon Sep 17 00:00:00 2001 From: Tim Sullivan Date: Fri, 16 Oct 2020 12:05:09 -0700 Subject: [PATCH] [Reporting] Document Network Policy configuration (#80431) (#80897) * [Reporting] Document Network Policy configuration * Apply suggestions from code review Co-authored-by: Larry Gregory * Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * remove detail about policy acting on responses * Update docs/user/reporting/network-policy.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * lowercase network policy * typo Co-authored-by: Larry Gregory Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: Larry Gregory Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/settings/reporting-settings.asciidoc | 5 ++ .../reporting/configuring-reporting.asciidoc | 1 + docs/user/reporting/network-policy.asciidoc | 71 +++++++++++++++++++ 3 files changed, 77 insertions(+) create mode 100644 docs/user/reporting/network-policy.asciidoc diff --git a/docs/settings/reporting-settings.asciidoc b/docs/settings/reporting-settings.asciidoc index 0214f0c04f882..0610368f42ee3 100644 --- a/docs/settings/reporting-settings.asciidoc +++ b/docs/settings/reporting-settings.asciidoc @@ -211,6 +211,11 @@ When `xpack.reporting.capture.browser.type` is set to `chromium` (default) you c exist. Configure this to a unique value, beginning with `.reporting-`, for every {kib} instance that has a unique `kibana.index` setting. Defaults to `.reporting`. +| `xpack.reporting.capture.networkPolicy` + | Capturing a screenshot from a {kib} page involves sending out requests for all the linked web assets. For example, a Markdown + visualization can show an image from a remote server. You can configure what type of requests to allow or filter by setting a + <> for Reporting. + | `xpack.reporting.roles.allow` | Specifies the roles in addition to superusers that can use reporting. Defaults to `[ "reporting_user" ]`. + diff --git a/docs/user/reporting/configuring-reporting.asciidoc b/docs/user/reporting/configuring-reporting.asciidoc index 21bc50d51c821..f7a8af0f1f3c9 100644 --- a/docs/user/reporting/configuring-reporting.asciidoc +++ b/docs/user/reporting/configuring-reporting.asciidoc @@ -75,3 +75,4 @@ to point to a proxy host requires that the Kibana server has network access to the proxy. include::{kib-repo-dir}/user/security/reporting.asciidoc[] +include::network-policy.asciidoc[] diff --git a/docs/user/reporting/network-policy.asciidoc b/docs/user/reporting/network-policy.asciidoc new file mode 100644 index 0000000000000..782473a3b0f18 --- /dev/null +++ b/docs/user/reporting/network-policy.asciidoc @@ -0,0 +1,71 @@ +[role="xpack"] +[[reporting-network-policy]] +=== Restrict requests with a Reporting network policy + +When Reporting generates PDF reports, it uses the Chromium browser to fully load the {kib} page on the server. This +potentially involves sending requests to external hosts. For example, a request might go to an external image server to show a +field formatted as an image, or to show an image in a Markdown visualization. + +If the Chromium browser is asked to send a request that violates the network policy, Reporting stops processing the page +before the request goes out, and the report is marked as a failure. Additional information about the event is in +the Kibana server logs. + +[NOTE] +============ +{kib} installations are not designed to be publicly accessible over the Internet. The Reporting network policy and other capabilities +of the Elastic Stack security features do not change this condition. +============ + +==== Configure a Reporting network policy + +You configure the network policy by specifying the `xpack.reporting.capture.networkPolicy.rules` setting in `kibana.yml`. A policy is specified as +an array of objects that describe what to allow or deny based on a host or protocol. If a host or protocol +is not specified, the rule matches any host or protocol. + +The rule objects are evaluated sequentially from the beginning to the end of the array, and continue until there is a matching rule. +If no rules allow a request, the request is denied. + +[source,yaml] +------------------------------------------------------- +# Only allow requests to placeholder.com +xpack.reporting.capture.networkPolicy: + rules: [ { allow: true, host: "placeholder.com" } ] +------------------------------------------------------- + +[source,yaml] +------------------------------------------------------- +# Only allow requests to https://placeholder.com +xpack.reporting.capture.networkPolicy: + rules: [ { allow: true, host: "placeholder.com", protocol: "https:" } ] +------------------------------------------------------- + +A final `allow` rule with no host or protocol will allow all requests that are not explicitly denied. + +[source,yaml] +------------------------------------------------------- +# Denies requests from http://placeholder.com, but anything else is allowed. +xpack.reporting.capture.networkPolicy: + rules: [{ allow: false, host: "placeholder.com", protocol: "http:" }, { allow: true }]; +------------------------------------------------------- + +A network policy can be composed of multiple rules. + +[source,yaml] +------------------------------------------------------- +# Allow any request to http://placeholder.com but for any other host, https is required +xpack.reporting.capture.networkPolicy + rules: [ + { allow: true, host: "placeholder.com", protocol: "http:" }, + { allow: true, protocol: "https:" }, + ] +------------------------------------------------------- + +[NOTE] +============ +The `file:` protocol is always denied, even if no network policy is configured. +============ + +==== Disable a Reporting network policy + +You can use the `xpack.reporting.capture.networkPolicy.enabled: false` setting to disable the network policy feature. The default for +this configuration property is `true`, so it is not necessary to explicitly enable it.