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

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

4 files changed, 147 insertions, 0 deletions

diff --git a/doc/userguide/reputation/index.rst b/doc/userguide/reputation/index.rst
new file mode 100644
index 0000000..0166a2a
--- /dev/null
+++ b/doc/userguide/reputation/index.rst
@@ -0,0 +1,6 @@
+Reputation
+==========
+
+.. toctree::
+
+   ipreputation/ip-reputation.rst
diff --git a/doc/userguide/reputation/ipreputation/ip-reputation-config.rst b/doc/userguide/reputation/ipreputation/ip-reputation-config.rst
new file mode 100644
index 0000000..888facc
--- /dev/null
+++ b/doc/userguide/reputation/ipreputation/ip-reputation-config.rst
@@ -0,0 +1,71 @@
+IP Reputation Config
+====================
+
+IP reputation has a few configuration directives, all disabled by default.
+
+
+::
+
+
+  # IP Reputation
+  #reputation-categories-file: /etc/suricata/iprep/categories.txt
+  #default-reputation-path: /etc/suricata/iprep
+  #reputation-files:
+  # - reputation.list
+
+reputation-categories-file
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The categories file mapping numbered category values to short names.
+
+
+::
+
+
+  reputation-categories-file: /etc/suricata/iprep/categories.txt
+
+default-reputation-path
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Path where reputation files from the "reputation-files" directive are loaded from by default.
+
+
+::
+
+
+  default-reputation-path: /etc/suricata/iprep
+
+reputation-files
+~~~~~~~~~~~~~~~~
+
+YAML list of file names to load. In case of a absolute path the file is loaded directly, otherwise the path from "default-reputation-path" is pre-pended to form the final path.
+
+
+::
+
+
+  reputation-files:
+   - badhosts.list
+   - knowngood.list
+   - sharedhosting.list
+
+Hosts
+~~~~~
+
+IP reputation information is stored in the host table, so the settings of the host table affect it.
+
+Depending on the number of hosts reputation information is available for, the memcap and hash size may have to be increased.
+
+Reloads
+~~~~~~~
+
+Sending Suricata a USR2 signal will reload the IP reputation data, along with the normal rules reload.
+
+During the reload the host table will be updated to contain the new data. The iprep information is versioned. When the reload is complete, Suricata will automatically clean up the old iprep information.
+
+Only the reputation files will be reloaded, the categories file won't be. If categories change, Suricata should be restarted.
+
+File format
+~~~~~~~~~~~
+
+The format of the reputation files is described in the :doc:`ip-reputation-format` page.
diff --git a/doc/userguide/reputation/ipreputation/ip-reputation-format.rst b/doc/userguide/reputation/ipreputation/ip-reputation-format.rst
new file mode 100644
index 0000000..ef465e6
--- /dev/null
+++ b/doc/userguide/reputation/ipreputation/ip-reputation-format.rst
@@ -0,0 +1,56 @@
+IP Reputation Format
+====================
+
+Description of IP Reputation file formats. For the configuration see :doc:`ip-reputation-config` and :doc:`/rules/ip-reputation-rules` for the rule format.
+
+Categories file
+~~~~~~~~~~~~~~~
+
+The categories file provides a mapping between a category number, short name, and long description. It's a simple CSV file:
+
+::
+
+
+  <id>,<short name>,<description>
+
+Example:
+
+::
+
+
+  1,BadHosts,Known bad hosts
+  2,Google,Known google host
+
+The maximum value for the category id is hard coded at 60 currently.
+
+Reputation file
+~~~~~~~~~~~~~~~
+
+The reputation file lists a reputation score for hosts in the categories. It's a simple CSV file:
+
+::
+
+
+  <ip>,<category>,<reputation score>
+
+The IP is an IPv4 address in the quad-dotted notation or an IPv6 address. Both IP types support networks in CIDR notation. The category is the number as defined in the categories file. The reputation score is the confidence that this IP is in the specified category, represented by a number between 1 and 127 (0 means no data).
+
+Example:
+
+::
+
+
+  1.2.3.4,1,101
+  1.1.1.0/24,6,88
+
+If an IP address has a score in multiple categories it should be listed in the file multiple times.
+
+Example:
+
+::
+
+
+  1.1.1.1,1,10
+  1.1.1.1,2,10
+
+This lists 1.1.1.1 in categories 1 and 2, each with a score of 10.
diff --git a/doc/userguide/reputation/ipreputation/ip-reputation.rst b/doc/userguide/reputation/ipreputation/ip-reputation.rst
new file mode 100644
index 0000000..dea7981
--- /dev/null
+++ b/doc/userguide/reputation/ipreputation/ip-reputation.rst
@@ -0,0 +1,14 @@
+IP Reputation
+=============
+
+.. toctree::
+
+   ip-reputation-config
+   ip-reputation-format
+
+The purpose of the IP reputation component is the ranking of IP Addresses within the Suricata Engine.  It will collect, store, update and distribute reputation intelligence on IP Addresses.  The hub and spoke architecture will allows the central database (The Hub) to collect, store and compile updated IP reputation details that are then distributed to user-side sensor databases (Spokes) for inclusion in user security systems.  The reputation data update frequency and security action taken, is defined in the user security configuration.
+
+The intent of IP Reputation is to allow sharing of intelligence regarding a vast number of IP addresses. This can be positive or negative intelligence classified into a number of categories. The technical implementation requires three major efforts; engine integration, the hub that redistributes reputation, and the communication protocol between hubs and sensors.  The hub will have a number of responsibilities. This will be a separate module running on a separate system as any sensor. Most often it would run on a central database that all sensors already have communication with. It will be able to subscribe to one or more external feeds.   The local admin should be able to define the feeds to be subscribed to, provide authentication credentials if required, and give a weight to that feed. The weight can be an overall number or a by category weight. This will allow the admin to minimize the influence a feed has on their overall reputation if they distrust a particular category or feed, or trust another implicitly. Feeds can be configured to accept feedback or not and will report so on connect. The admin can override and choose not to give any feedback, but the sensor should report these to the Hub upstream on connect.  The hub will take all of these feeds and aggregate them into an average single score for each IP or IP Block, and then redistribute this data to all local sensors as configured. It should receive connections from sensors. The sensor will have to provide authentication and will provide feedback. The hub should redistribute that feedback from sensors to all other sensors as well as up to any feeds that accept feedback.  The hub should also have an API to allow outside statistical analysis to be done to the database and fed back into the stream. For instance a local site may choose to change the reputation on all Russian IP blocks, etc.
+
+
+For more information about IP Reputation see :doc:`ip-reputation-config`, :doc:`/rules/ip-reputation-rules` and :doc:`ip-reputation-format`.