Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SSHGUARD(8)		  BSD System Manager's Manual		   SSHGUARD(8)

NAME
     sshguard -- monitors daemon activity

SYNOPSIS
     sshguard [-b thr:filename]	[-v] [-l source] [-a sAfety_thresh]
	      [-p pardon_min_interval] [-s preScribe_interval]
	      [-w addr/host/block/file]	[-f srv:pidfile]

DESCRIPTION
     sshguard monitors logging activity	and reacts to attacks by blocking
     their source addresses.

     sshguard was born for protecting SSH servers from the today's widespread
     brute force attacks, and evolved to an extensible log supervisor for
     blocking attacks to applications in real-time.

     sshguard can monitor a number of log sources proactively, or receive log
     messages in its standard input. By	means of a parser, it decides whether
     an	entry is normal	activity or attack; in the latter case,	it remarks the
     attacker's	address. When sshguard determines that an attacker committed
     enough danger to the system to discern an abuse, it blocks	the attacker's
     address with the firewall.	The attacker becomes offender, and is released
     after an adequate period of time.

     sshguard supports the following firewalls:

     AIX native	firewall
       for IBM AIX operating systems

     netfilter/iptables
       for Linux-based operating systems

     Packet Filter (PF)
       for BSD operating systems (Open,	Free, Net, DragonFly -BSD)

     IPFirewall	(IPFW)
       for FreeBSD and Mac OS X

     IP	Filter (IPFILTER)
       for FreeBSD, NetBSD and Solaris

     tcpd's hosts_access (/etc/hosts.allow)
       portable	across UNIX

     null
       portable	do-nothing backend for running detection without prevention

     Some terms	in this	manual have a special meaning in the context.
     sshguard refers to	them consistently throughout documentation, source
     code, and log messages. See http://www.sshguard.net/docs/terminology/ to
     get acquainted with them.

USAGE
     sshguard reads log	entries	to analyze by monitoring a number of log
     sources. It can interpret logs with all of	the following formats:
	   +o   syslog
	   +o   syslog-ng
	   +o   metalog
	   +o   multilog
	   +o   raw messages

     sshguard can interface with the following blocking	systems	to block at-
     tackers:
	   +o   IBM AIX firewall
	   +o   PF
	   +o   netfilter/iptables
	   +o   IPFW
	   +o   IP Filter
	   +o   /etc/hosts.allow
	   +o   null firewall

     Depending on the way chosen for giving logs to sshguard, and depending on
     the chosen	blocking system, some setup may	be needed. Instructions	are
     documented	at http://www.sshguard.net/docs/setup/.

     sshguard does not make use	of any configuration file. Instead, a combina-
     tion of optional arguments	can be passed to its process on	the command
     line, for modifying its default behaviour:

     -v	      print summary information	on sshguard and	exit.

     -i	pidfile
	      store my PID in file pidfile at startup (for control scripts).

     -b	[thresh:]filename
	      enable blacklisting: blacklist after thresh (or 40) dangerous-
	      ness committed, and hold the permanent blacklist in filename.
	      See TOUCHINESS & BLACKLISTING below.

     -l	source
	      enable the Log Sucker, and add source to the list	of log sources
	      to monitor.  source is a filename, a FIFO	name, or the magic
	      symbol "-" to identify sshguard's	standard input.	 sshguard han-
	      dles autonomously	file-like sources disappearing,	reappearing,
	      or "rotating". This option can be	used multiple times. When
	      omitted, source defaults to standard input. Otherwise, standard
	      input is ignored unless explicitly added.

     -a	sAfety_thresh
	      block an attacker	after it incurred a total dangerousness	ex-
	      ceeding sAfety_thresh.  Most attacks incur dangerousness 10. See
	      http://www.sshguard.net/docs/reference/attack-signatures/	for
	      details.	(Default: 40)

     -p	secs  release a	blocked	address	no sooner than secs seconds after be-
	      ing blocked for the first	time.  sshguard	will release the ad-
	      dress between X and 3/2 *	X seconds after	blocking it.  (De-
	      fault: 7*60)

     -s	secs  forget about an address after secs seconds. If host A issues one
	      attack every this	many seconds, it will never be blocked.	 (De-
	      fault: 20*60)

     -w	addr/host/block/file
	      see the WHITELISTING section.

     -f	servicecode:pidfile
	      see the LOG VALIDATION section.

     When sshguard is signalled	with SIGTSTP, it suspends activity. When
     sshguard is signalled with	SIGCONT, it resumes monitoring.	During suspen-
     sion, log entries are discarded without being analyzed.

     When sshguard senses the SSHGUARD_DEBUG environment variable, it enables
     debugging mode: logging is	directed to standard error instead of syslog,
     and includes comprehensive	details	of the activity	and parsing process.
     Debugging mode can	help investigating attack signatures: once enabled, a
     log message can be	directly pasted	into the tool from the console,	and
     the behavior is immediately and minutely shown beneath.

WHITELISTING
     sshguard supports address whitelisting. Whitelisted addresses are not
     blocked even if they appear to generate attacks. This is useful for pro-
     tecting lame LAN users (or	external friendly users) from being inciden-
     tally blocked.

     Whitelist addresses are controlled	through	the -w command-line option.
     This option can add explicit addresses, host names	and address blocks:

     addresses
       specify the numeric IPv4	or IPv6	address	directly, like:
	     -w	192.168.1.10
       or in multiple occurrences:
	     -w	192.168.1.10 -w	2001:0db8:85a3:0000:0000:8a2e:0370:7334

     host names
       specify the host	name directly, like:
	     -w	friendhost.enterprise.com
       or in multiple occurrences:
	     -w	friendhost.enterprise.com -w friend2.enterprise.com
       All IPv4	and IPv6 addresses that	the host resolves to are whitelisted.
       Hosts are resolved to addresses once, when sshguard starts up.

     address blocks
       specify the IPv4	or IPv6	address	block in the usual CIDR	notation:
	     -w	2002:836b:4179::836b:0000/126
       or in multiple occurrences:
	     -w	192.168.0.0/24 -w 1.2.3.128/26

     file
       When longer lists are needed for	whitelisting, they can be wrapped into
       a plain text file, one address/hostname/block per line, with the	same
       syntax given above.

       sshguard	can take whitelists from files when the	-w option argument be-
       gins with a `.' (dot) or	`/' (slash).

       This is a sample	whitelist file (say /etc/friends):

	     # comment line (a '#' as very first character)
	     #	 a single IPv4 and IPv6	address
	     1.2.3.4
	     2001:0db8:85a3:08d3:1319:8a2e:0370:7344
	     #	 address blocks	in CIDR	notation
	     127.0.0.0/8
	     10.11.128.0/17
	     192.168.0.0/24
	     2002:836b:4179::836b:0000/126
	     #	 hostnames
	     rome-fw.enterprise.com
	     hosts.friends.com

       And this	is how sshguard	is told	to make	a whitelist up from the
       /etc/friends file:
	     sshguard -w /etc/friends

     The -w option can be used only once for files. For	addresses, host	names
     and address blocks	it can be used with any	multiplicity, even with	mixes
     of	them.

LOG VALIDATION
     Syslog and	syslog-ng typically insert a PID of the	generating process in
     every log message.	This can be checked for	authenticating the source of
     the message and avoid false attacks to be detected	because	malicious lo-
     cal users inject crafted log messages. This way sshguard can be safely
     used even on hosts	where this assumption does not hold.

     Log validation is only needed when	sshguard is fed	log messages from sys-
     log or from syslog-ng. When a process logs	directly to a raw file and
     sshguard is configured for	polling	logs directly from it, you only	need
     to	adjust the log file permissions	so that	only root can write on it.

     For enabling log validation on a given service the	-f option is used as
     follows:
	   -f 100:/var/run/sshd.pid
     which associates the given	pidfile	to the ssh service (code 100). A list
     of	well-known service codes is available at
     http://www.sshguard.net/docs/reference/service-codes/.

     The -f option can be used multiple	times for associating different	ser-
     vices with	their pidfile:
	   sshguard -f 100:/var/run/sshd.pid -f	123:/var/run/mydaemon.pid

     Services that are not configured for log validation follow	a default-al-
     low policy	(all of	their log messages are accepted	by default).

     PIDs are checked with the following policy:

     1.	the logging service is searched	in the list of services	configured for
       validation. If not found, the entry is accepted.

     2.	the logged PID is compared with	the pidfile. If	it matches, the	entry
       is accepted

     3.	the PID	is checked for being a direct child of the authoritative
       process.	If it is, the entry is accepted.

     4.	the entry is ignored.
     Low I/O load is committed to the operating	system because of an internal
     caching mechanism.	Changes	in the pidfile value are handled transpar-
     ently.

TOUCHINESS & BLACKLISTING
     In	many cases, attacks against services are performed in bulk in an auto-
     mated form. For example, the attacker goes	trough a dictionary of 1500
     username/password pairs and sequentially tries to violate the SSH service
     with any of them, continuing blindly while	blocked, and re-appearing once
     the block expires.

     To	counteract these cases,	sshguard by default behaves with touchiness.
     Besides observing abuses from the log activity, it	also monitors the
     overall behavior of attackers. The	decision on when and how to block is
     thus made respective to the entire	history	of the offender	as well. For
     example, if address A attacks repeatedly and the base blocking time is
     420 seconds, A will be blocked for	420 seconds (7 mins) at	the first
     abuse, 2*420 (14 mins) the	second,	2*2*420	(28 mins) the third ...	and
     2^(n-1)*420 the n-th time.

     Touchiness	has two	major benefits:	to legitimate users, it	grants forgiv-
     ing blockings on failed logins; to	real attackers,	it effectively renders
     large scale attacks infeasible, because the time to perform one explodes
     with the number of	attempts.

     Touchiness	can be augmented with blacklisting (-b). With this option, af-
     ter a certain total danger	committed, the address is added	to a list of
     offenders to be blocked permanently. The list is intended to be loaded at
     each startup, and maintained/extended with	new entries during operation.
     sshguard inserts a	new address after it exceeded a	threshold of danger
     committed over recorded history. This threshold is	configurable within
     the -b option argument. Blacklisted addresses are never scheduled for re-
     leasing.

     The -b command line option	enables	blacklisting and requires the filename
     to	use for	permanent storage of the blacklist. Optionally,	a custom
     blacklist threshold can be	prefixed to this path, separated by ':'. For
     example,
	   -b 50:/var/db/sshguard/blacklist.db
     requires to blacklist addresses after having committed attacks for	danger
     50	(default per-attack danger is 10), and store the blacklist in file
     /var/db/sshguard/blacklist.db. Although the blacklist file	is not meant
     to	be in human-readable format, the strings(1) command can	be used	to
     peek in it	for listing the	blacklisted addresses.

EXTENSIONS
     sshguard operates firewalls through a general interface, which enables
     easy extension, and allows	back-ends to be	non-local (e.g.	remote appli-
     ances), and non-blocking (e.g. report tools). Additions can be suggested
     at	http://www.sshguard.net/feedback/firewall/submit/.

     Extending attack signatures needs some expertise with context-free
     parsers; users are	welcome	to submit samples of the desired log messages
     to	http://www.sshguard.net/support/attacks/submit/.

SEE ALSO
     syslog(1),	syslog.conf(5)

     sshguard website at: http://www.sshguard.net/

				 Mar 31, 2010

NAME | SYNOPSIS | DESCRIPTION | USAGE | WHITELISTING | LOG VALIDATION | TOUCHINESS & BLACKLISTING | EXTENSIONS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sshguard&sektion=8&manpath=FreeBSD+10.1-RELEASE+and+Ports>

home | help