Add tallow.patterns man page

Add a tallow.patterns man page which explains the json configuration
files that contain regex patterns and banning thresholds. This
functionality was added by 9174590.

Author: puneetse

man/tallow.1.md

@@ -48,7 +48,7 @@ the `-DDEBUG=1` symbol passed to the compiler.
 
 ## SEE ALSO
 
-systemd-journald(1), iptables(1), ipset(1), tallow.conf(5)
+systemd-journald(1), iptables(1), ipset(1), tallow.conf(5), tallow.patterns(5)
 
 ## BUGS
 

man/tallow.conf.5.md

@@ -87,7 +87,7 @@ Use the following commands if you're using firewalld(1):
 
 ## SEE ALSO
 
-tallow(1)
+tallow(1), tallow.patterns(5)
 
 ## AUTHOR
 

man/tallow.patterns.5.md

@@ -0,0 +1,134 @@
+## tallow.patterns
+
+Tallow pattern matching configuration files.
+
+
+## SYNOPSIS
+
+tallow(1) uses regular expressions to match journal entries and extract an IP
+address from them. JSON files are used to configure the patterns and banning
+thresholds used by tallow(1).
+
+`/etc/tallow/*.json`
+`/usr/share/tallow/*.json`
+
+
+## DESCRIPTION
+
+tallow(1) uses regular expressions to match journal entries and extract an IP
+address from them. JSON files are used to configure the patterns and banning
+thresholds used by tallow(1). This adds the ability to extend the patterns
+tallow(1) will recognize. Many JSON files can exist for logical grouping. The
+tallow(1) daemon will read all JSON files in the configuration directories at
+startup.
+
+tallow(1) operates with default pattern definitions
+in`/usr/share/tallow/*.json`. Users can add more patterns with their own JSON
+files under `/etc/tallow`. The default JSON files can be overridden by creating
+the same file under `/etc/tallow`.
+
+
+## FILE FORMAT 
+
+Pattern configuration files use the JavaScript Object Notation (JSON) format.
+
+The JSON must be two levels deep and all properties are required. The root
+object is an array containing objects with a `filter` key and an `items` key. 
+
+* `filter` is a string that defines a field for filtering the journal file.
+  This helps make sure patterns are only matched to a subset of journal
+  entries. See systemd.journal-fields(7) for valid journal fields.
+
+* `items` is an array of objects that contains three elements: `ban`, `score`,
+  and `pattern`.
+
+   * `ban` is an integer that defines the number of seconds to ban originating
+     IP for. If this value is > 0, the IP address get banned immediately when a
+     journal entry matches `pattern`.
+
+   * `score` is a double that defines a value to add to the accumulated "score"
+     of an originating IP address each time a journal entry matches
+     the `pattern`. If the combined score is > 1.0, tallow bans the originating
+     IP for the default time of 1 hour. The `ban` element value above is not
+     used for bans made due to `score`. 
+
+   * `pattern` is a string that defines a Perl Compatible Regular Expressions
+     (PCRE) to match against the filtered journal entries. The PCRE should
+     extract exactly one substring: the originating IP address for tallow(1).
+     See systemd.journal-fields(7) for valid journal fields.
+
+
+
+## EXAMPLES
+
+1. The JSON below is a snippet from one of the default pattern configuration
+   files for blocking certain failed `sshd` connections. 
+
+   The first pattern will ban an IP address after it fails to login 6 times
+   causing it to reach a total score > 1.0.
+
+   The second pattern will ban an IP address for 10 seconds every time a login is
+   attempted with an invalid user. Additionally, it will ban the IP address for
+   1 hour if it attempts to login with an invalid user 6 times causing it to
+   reach a total score > 1.0.
+
+   See the `/usr/share/tallow/sshd.json` file for more `sshd` examples.
+
+   ```
+   [
+     {
+       "filter": "SYSLOG_IDENTIFIER=sshd",
+       "items": [
+         {
+           "ban": 0,
+           "score": 0.2,
+           "pattern": "MESSAGE=Failed .* for .* from ([0-9a-z:.]+) port \\d+ ssh2"
+         },
+         {
+           "ban": 10,
+           "score": 0.2,
+           "pattern": "MESSAGE=Invalid user .* from ([0-9a-z:.]+) port \\d+"
+         }
+       ]
+     }
+   ]
+   ```
+
+
+
+2. The JSON below defines a pattern for blocking connections based on error logs
+   from `nginx-mainline` if placed in a `/etc/tallow/nginx-mainline.json` file.
+
+   The pattern will ban an IP address for 15 seconds every time it attempts to
+   access a script that does not exist. Additionally, it will ban the IP
+   address for 1 hour if it attempts to access invalid scripts 4 times causing
+   it to reach a total score > 1.0.
+
+   ```
+   [
+     {
+       "filter": "SYSLOG_IDENTIFIER=nginx-mainline",
+       "items": [
+         {
+           "ban": 15,
+           "score": 0.3,
+           "pattern": ".Primary script unknown. while reading response header from upstream, client: ([0-9a-z:.]+),"
+         }
+       ]
+     }
+   ]
+   ```
+
+## SEE ALSO
+
+tallow(1), tallow.conf(5)
+
+## BUGS
+
+`tallow` is `NOT A SECURITY SOLUTION`, nor does it protect against random
+password logins. An attacker may still be able to logon to your systems if you
+allow password logins.
+
+## AUTHOR
+
+Auke Kok <auke-jan.h.kok@intel.com>