mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-09-03 12:21:41 +00:00
137 lines
4.7 KiB
Plaintext
137 lines
4.7 KiB
Plaintext
tallow.patterns
|
||
===============
|
||
|
||
Tallow pattern matching configuration files.
|
||
|
||
SYNOPSIS
|
||
--------
|
||
|
||
`tallow(1) <tallow.1.html>`__ 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) <tallow.1.html>`__.
|
||
|
||
``/etc/tallow/*.json`` ``/usr/share/tallow/*.json``
|
||
|
||
DESCRIPTION
|
||
-----------
|
||
|
||
`tallow(1) <tallow.1.html>`__ 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) <tallow.1.html>`__. This adds the ability to
|
||
extend the patterns `tallow(1) <tallow.1.html>`__ will recognize. Many JSON files can exist
|
||
for logical grouping. The `tallow(1) <tallow.1.html>`__ daemon will read all JSON files in
|
||
the configuration directories at startup.
|
||
|
||
`tallow(1) <tallow.1.html>`__ 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) <tallow.1.html>`__. 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.1.html>`__, `tallow.conf(5) <tallow.conf.5.html>`__
|
||
|
||
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.
|