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

FreeBSD Manual Pages


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

     sshguard -- monitors daemon activity

     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]

     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

       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

       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 to
     get acquainted with them.

     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-
	   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

     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.

     -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	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.

     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:

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

     host names
       specify the host	name directly, like:
       or in multiple occurrences:
	     -w -w
       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 -w

       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
	     #	 address blocks	in CIDR	notation
	     #	 hostnames

       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.

     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
	   -f 100:/var/run/
     which associates the given	pidfile	to the ssh service (code 100). A list
     of	well-known service codes is available at

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

     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-

     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-

     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
	   -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.

     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

     Extending attack signatures needs some expertise with context-free
     parsers; users are	welcome	to submit samples of the desired log messages

     syslog(1),	syslog.conf(5)

     sshguard website at:

				 Mar 31, 2010


Want to link to this manual page? Use this URL:

home | help