Skip to content

Commit

Permalink
[Reporting] Document Network Policy configuration (#80431) (#80895)
Browse files Browse the repository at this point in the history
* [Reporting] Document Network Policy configuration

* Apply suggestions from code review

Co-authored-by: Larry Gregory <lgregorydev@gmail.com>

* 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 <lgregorydev@gmail.com>
Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

Co-authored-by: Larry Gregory <lgregorydev@gmail.com>
Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>
  • Loading branch information
3 people authored Oct 16, 2020
1 parent 65e146b commit d662f23
Show file tree
Hide file tree
Showing 3 changed files with 77 additions and 0 deletions.
5 changes: 5 additions & 0 deletions docs/settings/reporting-settings.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -268,6 +268,11 @@ For information about {kib} memory limits, see <<production, using {kib} in a pr
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
<<reporting-network-policy, network policy>> for Reporting.

| `xpack.reporting.roles.allow`
| Specifies the roles in addition to superusers that can use reporting.
Defaults to `[ "reporting_user" ]`. +
Expand Down
1 change: 1 addition & 0 deletions docs/user/reporting/configuring-reporting.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
71 changes: 71 additions & 0 deletions docs/user/reporting/network-policy.asciidoc
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit d662f23

Please sign in to comment.