Add documentation for the URL whitelist (#757) (#767)

* Add documentation for the URL whitelist * Adjust wording and screenshot to match current implementation * add comma Co-Authored-By: Dan Torrey <dan@graylog.com> * wording Co-Authored-By: Dan Torrey <dan@graylog.com> * Capitalization Co-Authored-By: Dan Torrey <dan@graylog.com> * State that whitelist is enabled by default. Co-Authored-By: Dan Torrey <dan@graylog.com> * Use capitalized form of "Whitelist" everywhere. Co-authored-by: Dan Torrey <dan@graylog.com> Co-authored-by: Dan Torrey <dan@graylog.com>
Graylog2 · Jan 14, 2020 · 7ed1a2c · 7ed1a2c
1 parent 6be3e9f
commit 7ed1a2c
Show file tree

Hide file tree

Showing 2 changed files with 42 additions and 0 deletions.
diff --git a/images/url_whitelist.png b/images/url_whitelist.png
diff --git a/pages/secure/sec_url_whitelist.rst b/pages/secure/sec_url_whitelist.rst
@@ -0,0 +1,42 @@
+.. _sec_url_whitelist:
+
+*******************************
+The URL Whitelist
+*******************************
+
+There are certain components in Graylog which will perform outgoing HTTP requests. Among those, are event notifications
+and HTTP-based data adapters.
+
+Allowing Graylog to interact with resources using arbitrary URLs may pose a security risk. HTTP requests are executed
+from Graylog servers and might therefore be able to reach more sensitive systems than an external user would have
+access to, including AWS EC2 metadata, which can contain keys and other secrets, Elasticsearch and others.
+
+It is therefore advisable to restrict access by explicitly whitelisting URLs which are considered safe. HTTP requests
+will be validated against the Whitelist and are prohibited if there is no Whitelist entry matching the URL.
+
+Configuring the Whitelist
+=========================
+
+The Whitelist configuration is located at ``System/Configurations``. The Whitelist is enabled by default.
+
+.. image:: /images/url_whitelist.png
+
+Disabling the Whitelist
+-----------------------
+
+If the security implications mentioned above are of no concern, the Whitelist can be completely disabled. When disabled, HTTP
+requests will not be restricted.
+
+"Exact match" Whitelist entries
+-------------------------------
+
+Whitelist entries of type ``Exact match`` contain a string which will be matched against a URL by direct comparison. If
+the URL is equal to this string, it is considered to be whitelisted.
+
+"Regex" Whitelist entries
+-------------------------
+
+Whitelist entries of type ``Regex`` contain a regular expression. If a URL matches the regular expression, the URL is
+considered to be whitelisted. Graylog uses the
+`Java Pattern class <http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html>`_ to evaluate regular
+expressions.