doc/userguide: dataset upgrade notes

diff --git a/doc/userguide/rules/datasets.rst b/doc/userguide/rules/datasets.rst
index f2f900bd6f7a309a7b8adfeed4fa6abae07beb82..647b12e36d87447c31589aa2a48a969f5abb6dde 100644 (file)
--- a/doc/userguide/rules/datasets.rst
+++ b/doc/userguide/rules/datasets.rst
@@ -289,3 +289,60 @@ field:
 Syntax::
 
     <data>,<value>
+
+.. _datasets_file_locations:
+
+File Locations
+--------------
+
+Dataset filenames configured in the ``suricata.yaml`` can exist
+anywhere on your filesytem.
+
+When a dataset filename is specified in rule, the following *rules*
+are applied:
+
+- For ``load``, the filename is opened relative to the rule file
+  containing the rule. Absolute filenames and parent directory
+  traversals are allowed.
+- For ``save`` and ``state`` the filename is relative to
+  ``$LOCALSTATEDIR/suricata/data``. On many installs this will be
+  ``/var/lib/suricata/data``, but run ``suricata --build-info`` and
+  check the value of ``--localstatedir`` to verify this location onn
+  your installation.
+
+  - Absolute filenames, or filenames containing parent directory
+    traversal (``..``) are not allowed unless the configuration
+    paramater ``datasets.allow-absolute-filenames`` is set to
+    ``true``.
+
+.. _datasets_security:
+
+Security
+--------
+
+As datasets potentially allow a rule distributor write access to your
+system with ``save`` and ``state`` dataset rules, the locations
+allowed are strict by default, however there are two dataset options
+to tune the security of rules utilizing dataset filenames::
+
+  datasets:
+    rules:
+      # Set to true to allow absolute filenames and filenames that use
+      # ".." components to reference parent directories in rules that specify
+      # their filenames.
+      allow-absolute-filenames: false
+
+      # Allow datasets in rules write access for "save" and
+      # "state". This is enabled by default, however write access is
+      # limited to the data directory.
+      allow-write: true
+
+By setting ``datasets.rules.allow-write`` to false, all ``save`` and
+``state`` rules will fail to load. This option is enabled by default
+to preserve compatiblity with previous 6.0 Suricata releases, however
+may change in a future major release.
+
+Pre-Suricata 6.0.13 behavior can be restored by setting
+``datasets.rules.allow-absolute-filenames`` to ``true``, however
+allowing so will allow any rule to overwrite any file on your system
+that Suricata has write access to.

diff --git a/doc/userguide/upgrade.rst b/doc/userguide/upgrade.rst
index e50f0e9a9d3c9c3e3eda70fee44622749e5f599e..ccf583f1a51f5698f2a8349ea1c7cc19e2045c73 100644 (file)
--- a/doc/userguide/upgrade.rst
+++ b/doc/userguide/upgrade.rst
@@ -45,6 +45,11 @@ Security changes
 - suricata.yaml now prevents process creation by Suricata by default with `security.limit-noproc`.
   The suricata.yaml configuration file needs to be updated to enable this feature.
   For more info, see :ref:`suricata-yaml-config-hardening`.
+- Absolute filenames and filenames containing parent directory
+  traversal are no longer allowed by default for datasets when the
+  filename is specified as part of a rule. See :ref:`Datasets Security
+  <datasets_security>` and :ref:`Datasets File Locations
+  <datasets_file_locations>` for more information.
 
 Removals
 ~~~~~~~~