Adding upstream version 1:7.0.3.upstream/1%7.0.3

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

6 files changed, 262 insertions, 0 deletions

diff --git a/doc/userguide/rule-management/adding-your-own-rules.rst b/doc/userguide/rule-management/adding-your-own-rules.rst
new file mode 100644
index 0000000..2a2264b
--- /dev/null
+++ b/doc/userguide/rule-management/adding-your-own-rules.rst
@@ -0,0 +1,77 @@
+Adding Your Own Rules
+=====================
+
+If you would like to create a rule yourself and use it with Suricata,
+this guide might be helpful.
+
+Start creating a file for your rule. Use one of the following examples in
+your console/terminal window:
+
+::
+
+  sudo nano local.rules
+  sudo vim local.rules
+
+Write your rule, see :doc:`../rules/intro` and save it.
+
+Update the Suricata configuration file so your rule is included. Use
+one of the following examples:
+
+::
+
+  sudo nano /etc/suricata/suricata.yaml
+  sudo vim /etc/suricata/suricata.yaml
+
+and make sure your local.rules file is added to the list of rules: ::
+
+    default-rule-path: /usr/local/etc/suricata/rules
+
+    rule-files:
+      - suricata.rules
+      - /path/to/local.rules
+
+Now, run Suricata and see if your rule is being loaded.
+
+::
+
+  suricata -c /etc/suricata/suricata.yaml -i wlan0
+
+If the rule failed to load, Suricata will display as much information as
+it has when it deemed the rule un-loadable. Pay special attention to the
+details: look for mistakes in special characters, spaces, capital characters,
+etc.
+
+Next, check if your log-files are enabled in the Suricata configuration file
+``suricata.yaml``.
+
+If you had to correct your rule and/or modify Suricata's YAML configuration
+file, you'll have to restart Suricata.
+
+If you see your rule is successfully loaded, you can double check your
+rule by doing something that should trigger it.
+
+By default, Suricata will log alerts to two places
+
+- ``eve.json``
+- ``fast.log``
+
+These files will be located in the log output directory which is set by
+one of two methods:
+
+1. Suricata configuration file: see ``default-log-dir`` for the name of the directory
+2. Suricata command line: Using ``-l /path/to/log-dir`` creates log files in the named
+   directory.
+
+The following example assumes that the log directory is named ``/var/log/suricata`` ::
+
+  tail -f /var/log/suricata/fast.log
+
+If you would make a rule like this: ::
+
+  alert http any any -> any any (msg:"Do not read gossip during work";
+  content:"Scarlett"; nocase; classtype:policy-violation; sid:1; rev:1;)
+
+Your alert should look like this: ::
+
+  09/15/2011-16:50:27.725288  [**] [1:1:1] Do not read gossip during work [**]
+  [Classification: Potential Corporate Privacy Violation] [Priority: 1] {TCP} 192.168.0.32:55604 -> 68.67.185.210:80
diff --git a/doc/userguide/rule-management/index.rst b/doc/userguide/rule-management/index.rst
new file mode 100644
index 0000000..633824f
--- /dev/null
+++ b/doc/userguide/rule-management/index.rst
@@ -0,0 +1,9 @@
+Rule Management
+===============
+
+.. toctree::
+
+  suricata-update
+  adding-your-own-rules
+  rule-reload
+  rule-profiling
diff --git a/doc/userguide/rule-management/rule-profiling.rst b/doc/userguide/rule-management/rule-profiling.rst
new file mode 100644
index 0000000..2c99260
--- /dev/null
+++ b/doc/userguide/rule-management/rule-profiling.rst
@@ -0,0 +1,28 @@
+Rules Profiling
+===============
+
+If Suricata is built with the `--enable-profiling-rules` then the ruleset profiling
+can be activated on demand from the unix socket and dumped from it.
+
+To start profiling ::
+
+ suricatasc -c ruleset-profile-start
+
+To stop profiling ::
+
+ suricatasc -c ruleset-profile-stop
+
+To dump profiling ::
+
+ suricatasc -c ruleset-profile
+
+A typical scenario to get rules performance would be ::
+
+ suricatasc -c ruleset-profile-start
+ sleep 30
+ suricatasc -c ruleset-profile-stop
+ suricatasc -c ruleset-profile
+
+On busy systems, using the sampling capability to capture performance
+on a subset of packets can be obtained via the `sample-rate` variable
+in the `profiling` section in the `suricata.yaml` file.
diff --git a/doc/userguide/rule-management/rule-reload.rst b/doc/userguide/rule-management/rule-reload.rst
new file mode 100644
index 0000000..5c29232
--- /dev/null
+++ b/doc/userguide/rule-management/rule-reload.rst
@@ -0,0 +1,32 @@
+Rule Reloads
+============
+
+Suricata can reload the rules without restarting. This way, there
+is minimal service disruption.
+
+This works by sending Suricata a signal or by using the unix socket. When Suricata is told to reload the rules these are the basic steps it takes:
+
+* Load new config to update rule variables and values.
+* Load new rules
+* Construct new detection engine
+* Swap old and new detection engines
+* Make sure all threads are updated
+* Free old detection engine
+
+Suricata will continue to process packets normally during this process. Keep in mind though, that the system should have enough memory for both detection engines.
+
+Signal::
+
+  kill -USR2 $(pidof suricata)
+
+There are two methods available when using the Unix socket.
+
+Blocking reload ::
+
+  suricatasc -c reload-rules
+
+Non blocking reload ::
+
+  suricatasc -c ruleset-reload-nonblocking
+
+It is also possible to get information about the last reload via dedicated commands. See :ref:`standard-unix-socket-commands` for more information.
diff --git a/doc/userguide/rule-management/suricata-update.rst b/doc/userguide/rule-management/suricata-update.rst
new file mode 100644
index 0000000..0c86d0f
--- /dev/null
+++ b/doc/userguide/rule-management/suricata-update.rst
@@ -0,0 +1,116 @@
+Rule Management with Suricata-Update
+====================================
+
+While it is possible to download and install rules manually, it is
+recommended to use a management tool for this. ``suricata-update`` is the
+official way to update and manage rules for Suricata.
+
+``suricata-update`` is bundled with Suricata and is normally installed
+with it. For instructions on installing manually, see http://suricata-update.readthedocs.io/en/latest/quickstart.html#install-suricata-update
+
+.. note:: ``suricata-update`` is bundled with Suricata version 4.1 and
+          later. It can be used with older versions as well. It will
+          have to be installed separately in that case.
+
+To download the Emerging Threats Open ruleset, it is enough to simply run:
+
+::
+
+  sudo suricata-update
+
+This will download the ruleset into `/var/lib/suricata/rules/`
+
+Suricata's configuration will have to be updated to have a rules config like
+this:
+
+::
+
+  default-rule-path: /var/lib/suricata/rules
+  rule-files:
+    - suricata.rules
+
+Now (re)start Suricata.
+
+
+Updating your rules
+~~~~~~~~~~~~~~~~~~~
+
+To update the rules, simply run
+
+::
+
+    sudo suricata-update
+
+It is recommended to update your rules frequently.
+
+
+Using other rulesets
+~~~~~~~~~~~~~~~~~~~~
+
+Suricata-Update is capable of making other rulesets accessible as well.
+
+To see what is available, fetch the master index from the OISF hosts:
+
+::
+
+    sudo suricata-update update-sources
+
+Then have a look at what is available:
+
+::
+
+    sudo suricata-update list-sources
+
+This will give a result similar to
+
+.. image:: suricata-update/suricata-update.png
+
+Each of the rulesets has a name that has a 'vendor' prefix, followed by a
+set name. For example, OISF's traffic id ruleset is called 'oisf/trafficid'.
+
+To enable 'oisf/trafficid', enter:
+
+::
+
+    sudo suricata-update enable-source oisf/trafficid
+    sudo suricata-update
+
+Now restart Suricata again and the rules from the OISF TrafficID ruleset are loaded.
+
+To see which rulesets are currently active, use "list-enabled-sources".
+
+Controlling which rules are used
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default ``suricata-update`` will merge all rules into a single file
+"/var/lib/suricata/rules/suricata.rules".
+
+To enable rules that are disabled by default, use `/etc/suricata/enable.conf`
+
+::
+
+    2019401                   # enable signature with this sid
+    group:emerging-icmp.rules # enable this rulefile
+    re:trojan                 # enable all rules with this string
+
+
+Similarly, to disable rules use `/etc/suricata/disable.conf`:
+
+::
+
+    2019401                   # disable signature with this sid
+    group:emerging-info.rules # disable this rulefile
+    re:heartbleed             # disable all rules with this string
+
+After updating these files, rerun ``suricata-update`` again:
+
+::
+
+    sudo suricata-update
+
+Finally restart Suricata.
+
+Further reading
+~~~~~~~~~~~~~~~
+
+See https://suricata-update.readthedocs.io/en/latest/
diff --git a/doc/userguide/rule-management/suricata-update/suricata-update.png b/doc/userguide/rule-management/suricata-update/suricata-update.png
new file mode 100644
index 0000000..aedd3a2
--- /dev/null
+++ b/doc/userguide/rule-management/suricata-update/suricata-update.png