/ 
Sentry-1.00
River stage zero No dependents
/ Sentry

NAME

Sentry - safe and effective protection against bruteforce attacks

SYNOPSIS

sentry --ip=<ipv4 or ipv6 IP> [ --whitelist | --blacklist | --delist | --connect ]
sentry --report [--verbose --ip=<ipv4 or ipv6 address> ]
sentry --help
sentry --update

ADDITIONAL DOCUMENTATION

See https://github.com/msimerson/sentry

DESCRIPTION

Sentry limits bruteforce attacks using minimal system resources.

SAFE

To prevent inadvertant lockouts, Sentry manages a whitelist of IPs that connect more than 3 times and succeed at least once. A forgetful colleague or errant script running behind the office NAT is far less likely to get the entire office locked out than with many bruteforce blockers.

Sentry includes firewall support for IPFW, PF, and ipchains. It is disabled by default. Be careful though, adding dynamic firewall rules may terminate existing sessions (attn IPFW users). Whitelist your IPs (connect 3x or use --whitelist) before enabling the firewall option.

SIMPLE

Sentry has a compact database for tracking IPs. It records the number of connects and the date when an IP was white or blacklisted.

Sentry is written in perl, which is installed practically everywhere sshd is. The only dependency is Net::IP for IPv6 handling. Sentry installation is extremely simple.

FLEXIBLE

Sentry supports blocking connection attempts using tcpwrappers and several popular firewalls. It is easy to extend Sentry to support additional blocking lists.

Sentry was written to protect the SSH daemon but is also used for FTP and SMTP protection. A primary attack platform is bot nets. The bots are used for carrying out SSH attacks as well as spam delivery. Blocking on multiple attack criteria reduces overall abuse.

The programming style of Sentry makes it easy to insert code for additional functionality.

EFFICIENT

A goal of Sentry is to minimize resource abuse. Many bruteforce blockers (denyhosts, fail2ban, sshdfilter) expect to run as a daemon, tailing a log file. That requires an interpreter to always be running, consuming CPU and RAM. A single hardware node with dozens of virtual servers loses hundreds of megs of RAM to daemon protection.

Sentry uses resources only when connections are made, and then only a few times before an IP is white/blacklisted. Once an IP is blacklisted for abuse, the resources it can abuse are neglible.

REQUIRED ARGUMENTS

ip

An IPv4 or IPv6 address. The IP should come from a reliable source that is difficult to spoof. Tcpwrappers is an excellent source. UDP connections are a poor source as they are easily spoofed. The log files of TCP daemons can be good source if they are parsed carefully to avoid log injection attacks.

All actions except report and help require an IP address. The IP can be manually specified by an administrator, or preferably passed in by a TCP server such as tcpd (tcpwrappers), inetd, or tcpserver (daemontools).

ACTIONS

blacklist

deny all future connections

whitelist

whitelist all future connections, remove the IP from the blacklists, and make it immune to future connection tests.

delist

remove an IP from the white and blacklists. This is useful for testing that Sentry is working as expected.

connect

register a connection by an IP. The connect method will log the attempt and the time. See CONNECT.

update

Check the most recent version of Sentry against the installed version and update if a newer version is available.

EXAMPLES

https://github.com/msimerson/sentry/wiki/Examples

NAUGHTY

Sentry has flexible rules for what constitutes a naughty connection. For SSH, attempts to log in as an invalid user are considered naughty. For SMTP, the sending of a virus, or an email with a high spam score could be considered naughty. See the configuration section in the script related settings.

CONNECT

When new connections arrive, the connect method will log the attempt. If the IP is already white or blacklisted, it exits immediately.

Next, Sentry checks to see if it has seen the IP more than 3 times. If so, check the logs for successful, failed, and naughty attempts from that IP. If there are any successful logins, whitelist the IP and exit.

If there are no successful logins and there are naughty ones, blacklist the IP. If there are no successful and no naughty attempts but more than 10 connection attempts, blacklist the IP. See also NAUGHTY.

CONFIGURATION AND ENVIRONMENT

There is a very brief configuration section at the top of the script. Once your IP is whitelisted, update the booleans for your firewall preference and Sentry will update your firewall too.

Sentry does NOT make changes to your firewall configuration. It merely adds IPs to a table/list/chain. It does this dynamically and it is up to the firewall administrator to add a rule that does whatever you'd like with the IPs in the sentry table.

See PF: https://github.com/msimerson/sentry/wiki/PF

DIAGNOSTICS

Sentry can be run with --verbose which will print informational messages as it runs.

DEPENDENCIES

Net::IP, for IPv6 support.

BUGS AND LIMITATIONS

The IPFW and ipchains code is barely tested.

Report problems to author.

AUTHOR

Matt Simerson (msimerson@cpan.org)

ACKNOWLEDGEMENTS

Those who came before: denyhosts, fail2ban, sshblacklist, et al

LICENCE AND COPYRIGHT

Copyright (c) 2015 The Network People, Inc. http://www.tnpi.net/

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.