agentsmith Manual Page

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
USAGE
CONFIGURATION
LOGGING
SIGNALS
FILES
CAVEATS
SEE ALSO
AUTHOR

NAME

agentsmith − monitor log file for break−in attempts

SYNOPSIS

agentsmith [ −c configfile ] [ −p pidfile ] [ −d ] [ −h | -t | −L | −V ]

DESCRIPTION

agentsmith is a daemon that continuously monitors a log file for break−in attempts by remote hosts. Upon detection of a break−in attempt, it launches a user defined script or application.

The criteria what is considered a break-in attempt can be configured by means of a regular expression. See agentsmith.conf(5) for further information on this.

OPTIONS

The following options are supported:
−c configfile

File path of the configuration file to use. If not specified, the default /usr/local/etc/agentsmith/agentsmith.conf is used. See also agentsmith.conf(5).

−p pidfile

File path of the file where the PID of the daemon will be written to. If not specified, the default /usr/local/var/agentsmith/agentsmith.pid is used.

	−d		Do not fork to background but stay in foreground. Most useful for debugging.
	−h		Show a brief help of the supported options.
	−t		Check the configuration file and regular expression, and exit.
	−L		Show the license and exit.
	−V		Show the version and exit.

USAGE

agentsmith reads the configuration at the default location (see FILES) or at the location provided with the -c option when started. It is recommended to launch agentsmith with the -t option specified after the configuration has been altered in order to identify possible configuration errors.

After successful start agentsmith will fork to background (unless the -d option is provided) and monitor the log file specified in the configuration file. It will only read new lines added to the log file. Lines present in the log file prior starting agentsmith are ignored.

Each new line added to the log file will be matched against the regular expression. If a line matches, agentsmith will read the value from the catching expression which has to be a host IP address (hereafter called ‘‘offending host’’). The offending host will then be remembered by agentsmith. If the offending host exceeds the configured threshold of occurrences within a specified time span, the action script will be called.

The action script is only called once for each offending host that meets the above mentioned criteria.

However, the last seen time stamp will be updated regardless, for each further occurrence of the offending host after the action script has been called.

If an IP address remembered by agentsmith is not seen for a specified amount of time, the action script will be called again and the offending host will be purged from memory.

agentsmith uses no persistent storage for storing offending hosts, thus the information is only kept during the run-time of the process and is lost upon termination.

Action Script
The action script is called in two cases:

An offending host has triggered the action script as explained above. The script will be invoked by agentsmith with the following arguments:

<ipaddress> <occurrences> new <sender>

<ipaddress> is the IP address of the offending host, i.e. the IP address that has been caught by the regular expression. <occurrences> is the number of occurrences. The literal word ’new’ is used to indicate that the call of the action script is for a new host. <sender> is the origin of the offending host, i.e. the instance of agentsmith that encountered the offending host (see Networking).

An offending host entry will be purged from memory, due to user request or because it has expired. In either case, the script will be invoked with the following arguments:

<ipaddress> <occurrences> remove <sender>

<ipaddress>, <occurrences>, and <sender> are the same as in case 1) however <occurrences> may be higher. The literal word ’remove’ is used to indicate that the offending host will be purged from memory.

The action script is the corner stone of agentsmith. You are completely free to put whatever you suits in this file, e.g. commands for updating firewall rules, for sending mails, and so on.

It is important that the execution bit is set (see also chmod(1)) and agentsmith has read and execution access to the file.

Networking
agentsmith can exchange information on offending hosts with instances running on remote hosts and thus trigger remote action scripts.

In order to provide authentication and prevent unauthorized access agentsmith employs OpenSSL. agentsmith will only exchange information with a another instance if both sides can verify the certificate of the peer.
Inform Mode

In inform mode agentsmith can inform other agentsmith instances running on remote hosts of offending hosts detected. It will, however, not inform remote instances when offending hosts are purged from memory. Further, agentsmith informs other instances only if the offending host triggers the action script, any further occurrence of the offending host will not passed on to remote instances.
It is possible to specify several agentsmith instances to be informed about offending hosts.

Server Mode

agentsmith can receive offending hosts to block from remote agentsmith instances. Upon receiving offending host informations from remote instances, the action script of the receiving agentsmith will be called.
agentsmith can be configured to check remotely received offending hosts for exclusion, or to ignore the local exclusion list.

It is possible to run agentsmith in both modes simultaneously.

CONFIGURATION

agentsmith relies on a configuration file for proper operation. The default location of the configuration file is /usr/local/etc/agentsmith/agentsmith.conf. Please see agentsmith.conf(5) for further information about how to configure agentsmith.

LOGGING

The logging facility used by agentsmith is daemon. Regular messages are sent to daemon.info. Error messages are sent to daemon.error. If agentsmith is compiled with debug code, debug messages are sent to daemon.debug.

You may need to adjust the configuration of the system logger in order to catch all messages from agentsmith. Please refer to syslog.conf(5) or your System Manual.

SIGNALS

Following signals are recognized (see also kill(1)):
SIGHUP

If an exclude file has been specified (see also agentsmith_exclude(5)), its content will be re-read.

SIGUSR1

Request the list of offending hosts. It will be printed to the system log (see also LOGGING).

SIGUSR2

Request that all offending hosts are purged from memory. This will also call the action script with the ’remove’ option.

SIGTERM

Terminate agentsmith gracefully.

FILES

/usr/local/var/agentsmith/agentsmith.pid

The default file path of the PID file. Can be overridden with the -p option.

/usr/local/etc/agentsmith/agentsmith.conf

The default location of the configuration file. Can be overridden with the -c option.

CAVEATS

	*		Although calling agentsmith with the -t option shows no error, it is possible that agentsmith does not start because it cannot write the PID file. Please make sure you check the system log after starting agentsmith as daemon to make sure it started successfully.
	*		If started as root, agentsmith does not drop root privileges.
	*		agentsmith has to be started from an user account with read access to the specified log file, else agentsmith is unable to read the log file and cannot start.
	*		Support for IPv6 addresses is implemented but not tested.
	*		If the log file is removed during the operation of agentsmith, it will repeatedly suspend for 30 seconds until the file reappears.

AUTHOR

Rafael Ostertag <rafi@guengel.ch>