diff --git a/.gitignore b/.gitignore index 92f19e4..5e4bc16 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,4 @@ tallow-*/ tallow.service *~ DEADJOE +man/*.[0-9] diff --git a/Makefile.am b/Makefile.am index a55d78f..53c4231 100644 --- a/Makefile.am +++ b/Makefile.am @@ -28,17 +28,20 @@ EXTRA_DIST = \ man/tallow.patterns.5.md \ man/tallow.1.md -dist_man_MANS = man/tallow.1 man/tallow.conf.5 man/tallow.patterns.5 - dist_doc_DATA = tallow.conf DISTCHECK_CONFIGURE_FLAGS = \ --with-systemdsystemunitdir=$(DESTDIR)$(SYSTEMDSYSTEMUNITDIR) -docs: $(dist_man_MANS) +man_MANS = man/tallow.1 man/tallow.conf.5 man/tallow.patterns.5 +clean-local: + rm -f $(man_MANS) + man/%.5: man/%.5.md - ronn -r $< --pipe > $@ + @mkdir -p $$(dirname $@) + pandoc -s -f markdown -t man $< --output $@ man/%.1: man/%.1.md - ronn -r $< --pipe > $@ + @mkdir -p $$(dirname $@) + pandoc -s -f markdown -t man $< --output $@ diff --git a/configure.ac b/configure.ac index 842f8d8..396bb8a 100644 --- a/configure.ac +++ b/configure.ac @@ -11,6 +11,11 @@ AC_CONFIG_FILES([Makefile]) AC_PROG_CC AC_PROG_INSTALL +AC_CHECK_PROG([PANDOC],[pandoc],yes) +if test x"${PANDOC}" != x"yes" ; then + AC_MSG_ERROR([Pandoc is required to create manual pages.]) +fi + PKG_CHECK_MODULES(PCRE, libpcre) PKG_CHECK_MODULES(JSON_C, json-c) PKG_CHECK_MODULES(LIBSYSTEMD, libsystemd,, [PKG_CHECK_MODULES(LIBSYSTEMD, libsystemd-journal)]) diff --git a/man/tallow.1 b/man/tallow.1 deleted file mode 100644 index 663603e..0000000 --- a/man/tallow.1 +++ /dev/null @@ -1,40 +0,0 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "TALLOW" "1" "February 2020" "" "" -. -.SH "NAME" -\fBtallow\fR -. -.SH "tallow" -Reduce log clutter due to ssh login attempts\. -. -.SH "SYNOPSIS" -\fB/usr/sbin/tallow\fR -. -.SH "DESCRIPTION" -\fBtallow\fR is a daemon that watches the systemd journal for messages from the \fBsshd\fR service\. It parses the messages and looks for attempted random logins such as failed logins to the root account and failed logins to invalid user accounts, and various other obviously malicious login attempts that try things as forcing old protocols, or weak key systems\. -. -.P -If such logins were detected, the offending IP address is stored in a list\. Items from this list are regularly purged, but if the amount of times that a specific IP address is seen exceeds a threshold, an ipset(1) entry is inserted in the \fBtallow\fR or \fBtallow6\fR ipset, and further packets from that ip address will be blocked by an \fBiptables(1)\fR or \fBip6tables(1)\fR rule that tallow creates at startup\. Additionally, certain types of login failure will trigger a short term ban of further packets from the offending IP address immediately\. -. -.P -The system administrator needs to assure that the tallow and tallow6 ipsets are left alone and that the inserted iptables rules are properly matching on packets\. -. -.P -Care should be taken to assure that legitimate users are not blocked inadvertently\. You may wish to list any valid IP address with the whitelist option in tallow\.conf(5)\. Multiple addresses can be whitelisted\. -. -.SH "OPTIONS" -The \fBtallow\fR daemon itself has no runtime configuration\. All configuration is done through the tallow\.conf(5) config file\. -. -.SH "SIGNALS" -The \fBUSR1\fR signal causes \fBtallow\fR to print out it\'s internal tracking table of IP addresses\. This requires that tallow is compiled with the \fB\-DDEBUG=1\fR symbol passed to the compiler\. -. -.SH "SEE ALSO" -systemd\-journald(1), iptables(1), ipset(1), tallow\.conf(5), tallow\.patterns(5) -. -.SH "BUGS" -\fBtallow\fR is \fBNOT A SECURITY SOLUTION\fR, nor does it protect against random password logins\. A attacker may still be able to logon to your systems if you allow password logins\. -. -.SH "AUTHOR" -Auke Kok \fIauke\-jan\.h\.kok@intel\.com\fR diff --git a/man/tallow.1.md b/man/tallow.1.md index 86bab3d..6cb70e7 100644 --- a/man/tallow.1.md +++ b/man/tallow.1.md @@ -1,13 +1,15 @@ +% TALLOW(1) +% Auke Kok `` -## tallow +# tallow Reduce log clutter due to ssh login attempts. -## SYNOPSIS +# SYNOPSIS `/usr/sbin/tallow` -## DESCRIPTION +# DESCRIPTION `tallow` is a daemon that watches the systemd journal for messages from the `sshd` service. It parses the messages and looks for @@ -35,27 +37,23 @@ blocked inadvertently. You may wish to list any valid IP address with the whitelist option in tallow.conf(5). Multiple addresses can be whitelisted. -## OPTIONS +# OPTIONS The `tallow` daemon itself has no runtime configuration. All configuration is done through the tallow.conf(5) config file. -## SIGNALS +# SIGNALS The `USR1` signal causes `tallow` to print out it's internal tracking table of IP addresses. This requires that tallow is compiled with the `-DDEBUG=1` symbol passed to the compiler. -## SEE ALSO +# SEE ALSO systemd-journald(1), iptables(1), ipset(1), tallow.conf(5), tallow.patterns(5) -## BUGS +# BUGS `tallow` is `NOT A SECURITY SOLUTION`, nor does it protect against random password logins. A attacker may still be able to logon to your systems if you allow password logins. - -## AUTHOR - -Auke Kok diff --git a/man/tallow.conf.5 b/man/tallow.conf.5 deleted file mode 100644 index 47da2a4..0000000 --- a/man/tallow.conf.5 +++ /dev/null @@ -1,80 +0,0 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "TALLOW" "5" "February 2020" "" "" -. -.SH "NAME" -\fBtallow\fR -. -.SH "tallow\.conf" -The tallow configuration file -. -.SH "NAME" -tallow\.conf \- Tallow daemon configuration file -. -.SH "SYNOPSIS" -\fB/etc/tallow\.conf\fR -. -.SH "DESCRIPTION" -This file is read on startup by the tallow(1) daemon, and can be used to provide options to the tallow daemon\. If not present, tallow will operate with built\-in defaults\. -. -.SH "OPTIONS" -\fBfwcmd_path\fR=\fB\fR Specifies the location of the ipset(1) firewall\-cmd(1) programs\. By default, tallow will look in "/usr/sbin" for them\. -. -.P -\fBipt_path\fR=\fB\fR Specifies the location of the ipset(1) program and iptables(1) or ip6tables(1) programs\. By default, tallow will look in "/usr/sbin" for them\. -. -.P -\fBexpires\fR=\fB\fR The number of seconds that IP addresses are blocked for\. Note that due to the implementation, IP addresses may be blocked for much longer than this period\. If IP addresses are seen, but not blocked within this period, they are also removed from the watch list\. Defaults to 3600s\. -. -.P -\fBwhitelist\fR=\fB\fR Specify an IP address or \fBpattern\fR that should never be blocked\. Multiple IP addresses can be included by repeating the \fBwhitelist\fR option several times\. By default, 127\.0\.0\.1, 192\.168\., and 10\. are whitelisted\. If you create a manual whitelist, you must include these entries if you want to continue them to be whitelisted as well, otherwise they will be omitted from the whitelist\. -. -.P -If the last character of the listed ip adress is a \fB\.\fR or a \fB:\fR, then the matching is only performed on the leftmost characters of an IP address against the whitelist entry\. For instance, if you whitelist \fB10\.\fR then all IP addresses in the \fB10/8\fR subnet mask will match this whitelist entry and never be blocked\. -. -.P -\fBipv6\fR=\fB<0|1>\fR Enable or disable ipv6 (ip6tables) support\. Ipv6 is disabled automatically on systems that do not appear to have ipv6 support and enabled when ipv6 is present\. Use this option to explicitly disable ipv6 support if your system does not have ipv6 or is missing ip6tables\. Even with ipv6 disabled, tallow will track and log ipv6 addresses\. -. -.P -\fBnocreate\fR=\fB<0|1>\fR Disable the creation of firewall rules and ipset sets\. By default, tallow will create new firewall\-cmd(1) or iptables(1) and ip6tables(1) rules when needed automatically\. If set to \fB1\fR, \fBtallow(1)\fR will not create any new firewall DROP rules or ipset sets that are needed work\. You should create them manually before tallow starts up and remove them afterwards using the sets of commands below\. -. -.P -Use the following commands if you\'re using iptables(1): -. -.IP "" 4 -. -.nf - - ipset create tallow hash:ip family inet timeout 3600 - iptables \-t filter \-I INPUT 1 \-m set \-\-match\-set tallow src \-j DROP - - ipset create tallow6 hash:ip family inet6 timeout 3600 - ip6tables \-t filter \-I INPUT 1 \-m set \-\-match\-set tallow6 src \-j DROP -. -.fi -. -.IP "" 0 -. -.P -Use the following commands if you\'re using firewalld(1): -. -.IP "" 4 -. -.nf - - firewall\-cmd \-\-permanent \-\-new\-ipset=tallow \-\-type=hash:ip \-\-family=inet \-\-option=timeout=3600 - firewall\-cmd \-\-permanent \-\-direct \-\-add\-rule ipv4 filter INPUT 1 \-m set \-\-match\-set tallow src \-j DROP - - firewall\-cmd \-\-permanent \-\-new\-ipset=tallow6 \-\-type=hash:ip \-\-family=inet6 \-\-option=timeout=3600 - firewall\-cmd \-\-permanent \-\-direct \-\-add\-rule ipv6 filter INPUT 1 \-m set \-\-match\-set tallow6 src \-j DROP -. -.fi -. -.IP "" 0 -. -.SH "SEE ALSO" -tallow(1), tallow\.patterns(5) -. -.SH "AUTHOR" -Auke Kok \fIauke\-jan\.h\.kok@intel\.com\fR diff --git a/man/tallow.conf.5.md b/man/tallow.conf.5.md index 6e2eb3f..979c54f 100644 --- a/man/tallow.conf.5.md +++ b/man/tallow.conf.5.md @@ -1,23 +1,25 @@ +% TALLOW.CONF(5) +% Auke Kok `` -## tallow.conf +# tallow.conf The tallow configuration file -## NAME +# NAME tallow.conf - Tallow daemon configuration file -## SYNOPSIS +# SYNOPSIS `/etc/tallow.conf` -## DESCRIPTION +# DESCRIPTION This file is read on startup by the tallow(1) daemon, and can be used to provide options to the tallow daemon. If not present, tallow will operate with built-in defaults. -## OPTIONS +# OPTIONS `fwcmd_path`=`` Specifies the location of the ipset(1) firewall-cmd(1) programs. By @@ -79,16 +81,12 @@ Use the following commands if you're using firewalld(1): ``` firewall-cmd --permanent --new-ipset=tallow --type=hash:ip --family=inet --option=timeout=3600 firewall-cmd --permanent --direct --add-rule ipv4 filter INPUT 1 -m set --match-set tallow src -j DROP - + firewall-cmd --permanent --new-ipset=tallow6 --type=hash:ip --family=inet6 --option=timeout=3600 firewall-cmd --permanent --direct --add-rule ipv6 filter INPUT 1 -m set --match-set tallow6 src -j DROP - + ``` -## SEE ALSO +# SEE ALSO tallow(1), tallow.patterns(5) - -## AUTHOR - -Auke Kok diff --git a/man/tallow.patterns.5 b/man/tallow.patterns.5 deleted file mode 100644 index 7e3ed56..0000000 --- a/man/tallow.patterns.5 +++ /dev/null @@ -1,128 +0,0 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "TALLOW" "5" "February 2020" "" "" -. -.SH "NAME" -\fBtallow\fR -. -.SH "tallow\.patterns" -Tallow pattern matching configuration files\. -. -.SH "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)\. -. -.P -\fB/etc/tallow/*\.json\fR \fB/usr/share/tallow/*\.json\fR -. -.SH "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\. -. -.P -tallow(1) operates with default pattern definitions in\fB/usr/share/tallow/*\.json\fR\. Users can add more patterns with their own JSON files under \fB/etc/tallow\fR\. The default JSON files can be overridden by creating the same file under \fB/etc/tallow\fR\. -. -.SH "FILE FORMAT" -Pattern configuration files use the JavaScript Object Notation (JSON) format\. -. -.P -The JSON must be two levels deep and all properties are required\. The root object is an array containing objects with a \fBfilter\fR key and an \fBitems\fR key\. -. -.IP "\(bu" 4 -\fBfilter\fR 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\. -. -.IP "\(bu" 4 -\fBitems\fR is an array of objects that contains three elements: \fBban\fR, \fBscore\fR, and \fBpattern\fR\. -. -.IP "\(bu" 4 -\fBban\fR 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 \fBpattern\fR\. -. -.IP "\(bu" 4 -\fBscore\fR 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 \fBpattern\fR\. If the combined score is > 1\.0, tallow bans the originating IP for the default time of 1 hour\. The \fBban\fR element value above is not used for bans made due to \fBscore\fR\. -. -.IP "\(bu" 4 -\fBpattern\fR 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\. -. -.IP "" 0 - -. -.IP "" 0 -. -.SH "EXAMPLES" -. -.IP "1." 4 -The JSON below is a snippet from one of the default pattern configuration files for blocking certain failed \fBsshd\fR connections\. -. -.IP -The first pattern will ban an IP address after it fails to login 6 times causing it to reach a total score > 1\.0\. -. -.IP -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\. -. -.IP -See the \fB/usr/share/tallow/sshd\.json\fR file for more \fBsshd\fR examples\. -. -.IP "" 4 -. -.nf - -[ - { - "filter": "SYSLOG_IDENTIFIER=sshd", - "items": [ - { - "ban": 0, - "score": 0\.2, - "pattern": "MESSAGE=Failed \.* for \.* from ([0\-9a\-z:\.]+) port \e\ed+ ssh2" - }, - { - "ban": 10, - "score": 0\.2, - "pattern": "MESSAGE=Invalid user \.* from ([0\-9a\-z:\.]+) port \e\ed+" - } - ] - } -] -. -.fi -. -.IP "" 0 - -. -.IP "2." 4 -The JSON below defines a pattern for blocking connections based on error logs from \fBnginx\-mainline\fR if placed in a \fB/etc/tallow/nginx\-mainline\.json\fR file\. -. -.IP -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\. -. -.IP "" 4 -. -.nf - -[ - { - "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:\.]+)," - } - ] - } -] -. -.fi -. -.IP "" 0 - -. -.IP "" 0 -. -.SH "SEE ALSO" -tallow(1), tallow\.conf(5) -. -.SH "BUGS" -\fBtallow\fR is \fBNOT A SECURITY SOLUTION\fR, nor does it protect against random password logins\. An attacker may still be able to logon to your systems if you allow password logins\. -. -.SH "AUTHOR" -Auke Kok \fIauke\-jan\.h\.kok@intel\.com\fR diff --git a/man/tallow.patterns.5.md b/man/tallow.patterns.5.md index 8baab93..c12ae42 100644 --- a/man/tallow.patterns.5.md +++ b/man/tallow.patterns.5.md @@ -1,9 +1,12 @@ -## tallow.patterns +% TALLOW.PATTERNS(5) +% Auke Kok `` + +# tallow.patterns Tallow pattern matching configuration files. -## SYNOPSIS +# 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 @@ -13,7 +16,7 @@ thresholds used by tallow(1). `/usr/share/tallow/*.json` -## DESCRIPTION +# 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 @@ -28,12 +31,12 @@ files under `/etc/tallow`. The default JSON files can be overridden by creating the same file under `/etc/tallow`. -## FILE FORMAT +# 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. +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 @@ -50,7 +53,7 @@ object is an array containing objects with a `filter` key and an `items` key. 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`. + 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 @@ -58,11 +61,10 @@ object is an array containing objects with a `filter` key and an `items` key. See systemd.journal-fields(7) for valid journal fields. - -## EXAMPLES +# EXAMPLES 1. The JSON below is a snippet from one of the default pattern configuration - files for blocking certain failed `sshd` connections. + 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. @@ -119,16 +121,14 @@ object is an array containing objects with a `filter` key and an `items` key. ] ``` -## SEE ALSO + +# SEE ALSO tallow(1), tallow.conf(5) -## BUGS + +# 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