psad - The Port Scan Attack Detector

psad [-a auto-dl-file ] [-c config-file ] [-l] [-h] [-B] [-A] [-F] [-S] [-K] [-R] [-U] [-H] [-V] [-p] [-e] [-w] [-D] [-d] [--signatures sig-file ] [--interval interval ] [-m messages-file ] [--snort-type type ] [--snort-rdir rules-directory ] [--passive-os-sigs posf-file ] [--status-ip ip ] [--status-dl dl ] [--fw-file policy-file ] [--fw-block-ip ip ] [--fw-search fw-search file ] [--fw-analyze] [--fw-list-auto] [--fw-del-chains] [--fw-dump] [--status-sort-dl] [--status-brief] [--no-fwcheck] [--no-daemon] [--no-rdns] [--no-auto-dl] [--no-kmsgsd] [--no-whois] [--no-netstat] [--no-ipt-errors] [--no-passive-os] [--no-signatures] [--no-icmp-types] [--no-snort-sids]

psad makes use of iptables log messages to detect, alert, and (optionally) block port scans and other suspect traffic. For tcp scans psad analyzes tcp flags to determine the scan type (syn, fin, xmas, etc.) and corresponding command line options that could be supplied to nmap to generate such a scan. In addition, psad makes use of many tcp, udp, and icmp signatures contained within the Snort intrusion detection system (see http://www.snort.org/) to detect suspicious network traffic such as probes for common backdoors, DDoS tools, OS fingerprinting attempts, and more. By default psad also provides alerts for snort rules that are detected directly by iptables through the use of a ruleset generated by fwsnort (http://www.cipherdyne.org/fwsnort/). This enables psad to send alerts for application layer attacks. psad features a set of highly configurable danger thresholds (with sensible defaults provided) that allow the administrator to define what constitutes a port scan or other suspect traffic. Email alerts sent by psad contain the scanning ip, number of packets sent to each port, any tcp, udp, or icmp signatures that have been matched (e.g. "NMAP XMAS scan"), the scanned port range, the current danger level (from 1 to 5), reverse dns info, and whois information. psad also makes use of various packet header fields associated with TCP SYN packets to passively fingerprint remote operating systems (in a manner similar to the p0f fingerprinter) from which scans originate. This requires the use of the --log-tcp-options argument for Netfilter logging rules; if this option is not used, psad will fall back to a fingerprinting method that makes use of packet length, TTL and TOS values, IP id, and tcp window sizes.

psad Syslog needs to be configured to write all kern.info messages to a named pipe /var/lib/psad/psadfifo. A simple

echo -e 'kern.info\\t|/var/lib/psad/psadfifo' >> /etc/syslog.conf

will do. Remember also to restart syslog after the changes to this file.

Psad reads all messages out of the pipe that are matched by a string designed to catch any packets that have been logged (and possibly dropped) by the firewall. In this way psad is supplied with a pure data stream that exclusively contains packets that the firewall has deemed unfit to enter the network. psad consists of three daemons: psad, kmsgsd, and psadwatchd. psad is responsible for processing all packets that have been logged by the firewall and applying the signature logic in order to determine what type of scan has been leveraged against the machine and/or network. kmsgsd reads all messages that have been written to the /var/lib/psad/psadfifo named pipe and writes any message that matches a particular regular expression (or string) to /var/log/psad/fwdata. psadwatchd is a software watchdog that will restart any of the other two daemons should a daemon die for any reason.

/etc/psad/psad.conf The main psad configuration file which contains configuration variables mentioned in the section below.

/etc/psad/fw_search.conf Used to configure the strategy both psad and kmsgsd employ to parse iptables messages. Using configuration directive within this file, psad can be configured to parse all iptables messages or only those that match specific log prefix strings (see the --log-prefix option to iptables).

/etc/psad/signatures Contains the signatures psad uses to recognize nasty traffic. The signatures are written in a manner similar to the *lib signature files used in the snort IDS.

/etc/psad/icmp_types Contains all valid icmp types and corresponding codes as defined by RFC 792. By default, icmp packets are validated against these values and an alert will be generated if a non-matching icmp packet is logged by iptables.

/etc/psad/snort_rules/*.rules Snort rules files that are consulted by default unless the --no-snort-sids commmand line argument is given.

/etc/psad/auto_dl Contains a listing of any IP addresses that should be assigned a danger level based on any traffic that is logged by the firewall. The syntax is "<IP address> <danger level>" where <danger level> is an integer from 0 to 5, with 0 meaning to ignore all traffic from <IP address>, and 5 is to assign the highest danger level to <IP address>.

/etc/psad/posf Contains a listing of all passive operating system fingerprinting signatures. These signatures include packet lengths, ttl, tos, IP id, and tcp window size values that are specific to various operating systems.

This section describes what each of the more important psad configuration variables do and how they can be tuned to meet your needs. Most of the variables are located in the psad configuration file /etc/psad/psad.conf but the FW_SEARCH_ALL and FW_MSG_SEARCH variables are located in the file /etc/psad/fw_search.conf. Each variable is assigned sensible defaults for most network architectures during the install process. More information on psad config keywords may be found at: http://www.cipherdyne.org/psad/config.html

EMAIL_ADDRESSES

Contains a comma-separated list of email addresses to which email alerts will be sent. The default is "root@localhost".

HOSTNAME

Defines the hostname of the machine on which psad is running. This will be used in the email alerts generated by psad.

HOME_NET

Define the internal network(s) that are connected to the local system. This will be used in the signature matching code to determine whether traffic matches snort rules, which invariably contain a source and destination network. Multiple networks are supported as a comma separated list, and each network should be specified in CIDR notation. Normally the network(s) contained in the HOME_NET variable should be directly connected to the machine that is running psad.

IMPORT_OLD_SCANS

Preserve scan data across restarts of psad or even across reboots of the machine. This is accomplished by importing the data contained in the filesystem cache psad writes to during normal operation back into memory as psad is started. The filesystem cache data in contained within the directory /var/log/psad.

FW_SEARCH_ALL

Defines the search mode psad uses to parse iptables messages. By default FW_SEARCH_ALL is set to "Y" since normally most people want all iptables log messages to be parsed for scan activity. However, if FW_SEARCH_ALL is set to "N", psad will only parse those iptables log messages that match certain search strings that appear in iptables logs with the --log-prefix option. This is useful for restricting psad to only operate on specific iptables chains or rules. The strings that will be searched for are defined with the FW_MSG_SEARCH variable (see below). The FW_SEARCH_ALL variable is defined in the file /etc/psad/fw_search.conf since it is referenced by both psad and kmsgsd.

FW_MSG_SEARCH

Defines a set of search strings that psad uses to identify iptables messages that should be parsed for scan activity. These search strings should match the log prefix strings specified in the iptables ruleset with the --log-prefix option, and the default value for FW_MSG_SEARCH is "DROP". Note that psad normally parses all iptables messages, and so the FW_MSG_SEARCH variable is only needed if FW_SEARCH_ALL (see above) is set to "N". The FW_MSG_SEARCH variable is referenced by both psad and kmsgsd so it lives in the file /etc/psad/fw_search.conf.

SYSLOG_DAEMON

Define the specific syslog daemon that psad should interface with. Psad supports three syslog daemons: syslogd, syslog-ng, and metalog. The default value of SYSLOG_DAEMON is syslogd.

IGNORE_PORTS

Specify a list of port ranges and/or individual ports and corresponding protocols that psad should complete ignore. This is particularly useful for ignore ports that are used as a part of a port knocking scheme (such as fwknop http://www.cipherdyne.org/fwknop) for network authentication since such log messages generated by the knock sequence may otherwise be interpreted as a scan. Multiple ports and/or port ranges may be specified as a comma-separated list, e.g. "tcp/22, tcp/61000-61356, udp/53".

ENABLE_PERSISTENCE

If "Y", psad will keep all scans in memory and not let them timeout. This can help discover stealthy scans where an attacker tries to slip beneath IDS thresholds by only scanning a few ports over a long period of time. ENABLE_PERSISTENCE is set to "Y" by default.

SCAN_TIMEOUT

If ENABLE_PERSISTENCE is "N" then psad will use the value set by SCAN_TIMEOUT to remove packets from the scan threshold calculation. The default is 3600 seconds (1 hour).

DANGER_LEVEL{1,2,3,4,5}

psad uses a scoring system to keep track of the severity a scans reaches (represented as a "danger level") over time. The DANGER_LEVEL{n} variables define the number of packets that must be dropped by the firewall before psad will assign the respective danger level to the scan. A scan may also be assigned a danger level if the scan matches a particular signature contained in the signatures file. There are five possible danger levels with one being the lowest and five the highest. Note there are several factors that can influence how danger levels are calculated: whether or not a scan matches a signature listed in /etc/psad/signatures, the value of PORT_RANGE_SCAN_THRESHOLD (see below), whether or not a scan comes from an IP that is listed in the /etc/psad/auto_dl file, and finally whether or not scans are allowed to timeout as determined by SCAN_TIMEOUT above. If a signature is matched or the scanning IP is listed in /etc/psad/auto_dl, then the corresponding danger level is automatically assigned to the scan.

PORT_RANGE_SCAN_THRESHOLD

Defines the minimum difference between the lowest port and the highest port scanned before an alert is sent (the default is 1 which means that at least two ports must be scanned to generate an alert). For example, suppose an ip repeatedly scans a single port for which there is no special signature in signatures. Then if PORT_RANGE_SCAN_THRESHOLD=1, psad will never send an alert for this "scan" no matter how many packets are sent to the port (i.e. no matter what the value of DANGER_LEVEL1 is). The reason for the default of 1 is that a "scan" usually means that at least two ports are probed, but if you want psad to be extra paranoid you can set PORT_RANGE_SCAN_THRESHOLD=0 to alert on scans to single ports (as long as the number of packets also exceeds DANGER_LEVEL1).

SHOW_ALL_SIGNATURES

If "Y", psad will display all signatures detected from a single scanning IP since a scan was first detected instead of just displaying newly-detected signatures. SHOW_ALL_SIGNATURES is set to "N" by default. All signatures are listed in the file /etc/psad/signatures.

SNORT_SID_STR

Defines the string kmsgsd will search for in iptables log messages that are generated by iptables rules designed to detect snort rules. The default is "SID". See fwsnort (http://www.cipherdyne.org/fwsnort/).

ENABLE_DSHIELD_ALERTS

Enable dshield alerting mode. This will send a parsed version of iptables log messages to dshield.org which is a (free) distributed intrusion detection service. For more information, see http://www.dshield.org.

IGNORE_CONNTRACK_BUG_PKTS

If "Y", all tcp packets that have the ACK or RST flag bits set will be ignored by psad since usually we see such packets being blocked as a result of the iptables connection tracking bug. Note there are no signatures that make use of the RST flag and very few that use ACK flag.

ALERT_ALL

If "Y", send email for all new bad packets instead of just when a danger level increases. ALERT_ALL is set to "Y" by default.

PSAD_EMAIL_LIMIT

Defines the maximum number of emails that will be sent for a single scanning IP (default is 50). This variable gives you some protection from psad sending countless alerts if an IP scans your machine constantly. psad will send a special alert if an IP has exceeded the email limit. If PSAD_EMAIL_LIMIT is set to zero, then psad will ignore the limit and send alert emails indefinitely for any scanning ip.

EMAIL_ALERT_DANGER_LEVEL

Defines the danger level a scan must reach before any alert is sent. This variable is set to 1 by default.

ENABLE_AUTO_IDS

psad has the capability of dynamically blocking all traffic from an IP that has reached a (configurable) danger level through modification of iptables or tcpwrapper rulesets. IMPORTANT: This feature is disabled by default since it is possible for an attacker to spoof packets from a well known (web)site in an effort to make it look as though the site is scanning your machine, and then psad will consequently block all access to it. Also, psad works by parsing firewall messages for packets the firewall has already dropped, so the "scans" are unsuccessful anyway. However, some administrators prefer to take this risk anyway reasoning that they can always review which sites are being blocked and manually remove the block if necessary (see the --Flush option). Your mileage will vary.

AUTO_IDS_DANGER_LEVEL

Defines the danger level a scan must reach before psad will automatically block the IP (ENABLE_AUTO_IDS must be set to "Y").

The following examples illustrate the command line arguments that could be supplied to psad in a few situations:

Signature checking, passive OS fingerprinting, and automatic IP danger level assignments are enabled by default without having to specify any command line arguments (best for most situations):

# psad

Same as above, but this time we use the init script to start psad:

# /etc/init.d/psad start

Use psad as a forensics tool to analyze an old iptables logfile (psad defaults to analyzing the /var/log/messages file if the -m option is not specified):

# psad -A -m <iptables logfile>

The psad.conf, signatures, and auto_dl files are normally located within the /etc/psad/ directory, but the paths to each of these files can be changed:

# psad -c <config file> -s <signatures file> -a <auto ips file>

Disable the firewall check and the local port lookup subroutines; most useful if psad is deployed on a syslog logging server:

# psad --log-server --no-netstat

Disable reverse dns and whois lookups of scanning IP addresses; most useful if speed of psad is the main concern:

# psad --no-rdns --no-whois

psad requires that iptables is configured with a "drop and log" policy for any traffic that is not explicitly allowed through. This is consistent with a secure network configuration since all traffic that has not been explicitly allowed should be blocked by the firewall ruleset. By default, psad attempts to determine whether or not the firewall has been configured in this way. This feature can be disabled with the --no-fwcheck or --log-server options. The --log-server option is useful if psad is running on a syslog logging server that is separate from the firewall. For more information on compatible iptables rulesets, see the FW_EXAMPLE_RULES file that is bundled with the psad source distribution.

psad also requires that syslog be configured to write all kern.info messages to the named pipe /var/lib/psad/psadfifo. A simple

echo -e 'kern.info\\t|/var/lib/psad/psadfifo' >> /etc/syslog.conf

will do. Remember also to restart syslog after the changes to this file.

The --debug option can be used to display crucial information about the psad data structures on STDOUT as a scan generates firewall log messages. --debug disables daemon mode execution.

Another more effective way to peer into the runtime execution of psad is to send (as root) a USR1 signal to the psad process which will cause psad to dump the contents of the %Scan hash to /var/log/psad/scan_hash.$$ where $$ represents the pid of the psad process.

iptables(8), kmsgsd(8), psadwatchd(8), fwsnort(8), snort(8), nmap(1), pscan(8), psadwatchd(8), diskmond(8), kmsgsd(8), p0f(1)

Michael Rash <mbr@cipherdyne.org>

Send bug reports to mbr@cipherdyne.org. Suggestions and/or comments are always welcome as well.

-For iptables firewalls as of Linux kernel version 2.4.26, if the ip_conntrack module is loaded (or compiled into the kernel) and the firewall has been configured to keep state of connections, occasionally packets that are supposed to be part of normal TCP traffic will not be correctly identified due to a bug in the firewall state timeouts and hence dropped. Such packets will then be interpreted as a scan by psad even though they are not part of any malicious activity. Fortunately, an interim fix for this problem is to simply extend the TCP_CONNTRACK_CLOSE_WAIT timeout value in linux/net/ipv4/netfilter/ip_conntrack_proto_tcp.c from 60 seconds to 2 minutes, and a set of kernel patches is included within the patches/ directory in the psad sources to change this. (Requires a kernel recompile of course; see the Kernel-HOWTO.) Also, by default the IGNORE_CONNTRACK_BUG_PKTS variable is set to "Y" in psad.conf which causes psad to ignore all tcp packets that have the ACK bit set unless the packets match a specific signature.

psad is distributed under the GNU General Public License (GPL), and the latest version may be downloaded from: http://www.cipherdyne.org