Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

602 lines (526 sloc) 22.125 kb
.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH PSAD 8 "Oct, 2003" Linux
.SH NAME
.B psad
\- The Port Scan Attack Detector
.SH SYNOPSIS
.B psad [-a
.I auto-ips-file
.B ] [-c
.I config-file
.B ] [-l]
.B ] [-h] [-B] [-F] [-S] [-K] [-R] [-U] [-H] [-V] [-f] [-o] [-p] [-D] [-d] [--signatures
.I sig-file
.B ] [--interval
.I interval
.B ] [--snort-type
.I type
.B ] [--snort-rdir
.I rules-directory
.B ] [--passive-os-sigs
.I posf-file
.B ] [--status-ip
.I ip
.B ] [--status-dl
.I dl
.B ] [--status-sort-dl] [--no-fwcheck] [--no-daemon] [--no-rdns]
.B [--no-whois] [--no-netstat] [--no-ipt-errors]
.B [--no-passive-os] [--no-snort-sids]
.SH DESCRIPTION
.B psad
makes use of iptables log messages to detect, alert, and
(optionally) block port scans in real time. psad configures syslog to
write all kern.info messages to a named pipe
.B /var/lib/psad/psadfifo
and then reads all messages out of the pipe that are matched by a regular
expression 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. For iptables
firewalls in the 2.4.x series kernels, psad analyzes the tcp flags
used in the scan to determine the scan type (syn, fin, xmas, etc.)
and the 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 suspect 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
.B fwsnort
(http://www.cipherdyne.org/fwsnort/). 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 packet length, ttl, tos, ip id, and tcp window sizes
to passively fingerprint remote operating systems from which scans originate.
.B psad
consists of three daemons: psad, kmsgsd, and psadwatchd.
.B 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.
.B kmsgsd
reads all messages that have been written to the
.B /var/lib/psad/psadfifo
named pipe and writes any message that matches a particular regular
expression (or string) to
.B /var/log/psad/fwdata.
.B psadwatchd
is a software watchdog that will restart any of the other three daemons should
a daemon die for any reason.
.SH OPTIONS
.PP
.PD 0
.TP
.BI \-c "\fR,\fP " \-\^\-config " configuration-file"
By default all of the psad makes use of the configuration file
.B /etc/psad/psad.conf
for almost all configuration parameters. psad can be made to
override this path by specifying a different file on the command
line with the --config option.
.TP
.BI \-s "\fR,\fP " \-\^\-signatures " signatures-file"
The iptables firewalling code included within the linux 2.4.x kernel
series has the ability to distinguish and log any of the tcp flags
present within tcp packets that traverse the firewall interfaces. Psad
makes use of this logging capability to detect several types of tcp scan
signatures included within
.B /etc/psad/psad_signatures.
The signatures were
originally included within the Snort intrusion detection
system. New signatures can be included and modifications to existing
signatures can be made to the signature file and psad will import
the changes upon receiving a USR1 signal (see the --USR1 command line
option) without having to restart the psad process. Psad also detects
many udp and icmp signatures that were originally included within Snort.
.TP
.BI \-\^\-snort-type " type"
Restrict the type of snort sids to
.I type.
Allowed types match the file names given to snort rules files such as
"ddos", "backdoor", and "web-attacks".
.TP
.BI \-\^\-snort-rdir " snort-rules-directory"
Manually specify the directory where the snort rules files are located.
The default is
.B /etc/psad/snort_rules.
.TP
.BI \-\^\-passive-os-sigs " passive-os-sigs-file"
Manually specify the passive operating system fingerprinting signatures.
.B /etc/psad/psad_posf.
.TP
.BI \-a "\fR,\fP " \-\^\-auto-ips " auto-ips-file"
Occasionally certain ip addresses are repeat offenders and
should automatically be given a higher danger level than
would normally be assigned. Additionally, some ip addresses
can always be ignored depending on your network configuration
(the loopback interface 127.0.0.1 might be a good candidate
for example).
.B /etc/psad/psad_auto_ips
provides an interface for psad to automatically
increase/decrease/ignore scanning ip danger levels. Modifications
can be made to psad_auto_ips (installed by default in /etc/psad)
and psad will import them without having to restart the psad process.
.TP
.BR \-F ", " \-\^\-Flush
Remove any auto-generated firewall block rules if psad was configured
to automatically respond to scans (see the ENABLE_AUTO_IDS variable
in psad.conf).
.TP
.BR \-S ", " \-\^\-Status
Display the status of any psad processes that may or not be running.
The status output contains a listing of the number of packets that
have been processed by psad, along with all ip addresses and
corresponding danger levels that have scanned the network.
.TP
.BI \-\^\-status-ip " ip"
Display status information associated with
.I ip
such as the protocol packet counters as well as the last 10 packets
logged by iptables.
.TP
.BI \-\^\-status-dl " dl"
Display status information only for scans that have reached a danger
level of at least
.I dl
.TP
.BR \-\^\-status-sort-dl
Sort status output by danger level. The default output is sorted
by ip address to show scans that may be associated with the same
network in an easily readable format.
.TP
.BR \-K ", " \-\^\-Kill
Kill the current psad process along with psadwatchd and kmsgsd.
This provides a quick and easy way to kill all psad processes without
having to look in the process table or appeal to the psad-init script.
.TP
.BR \-R ", " \-\^\-Restart
Restart the currently running psad processes. This option will
preserve the command line options that were supplied to the original
psad process.
.TP
.BR \-B ", " \-\^\-Benchmark
Run psad in benchmark mode. By default benchmark mode will simulate
a scan of 10,000 packets (see the --packets option) and then report
the elapsed time. This is useful to see how fast psad can process
packets on a specific machine.
.TP
.BI \-p "\fR,\fP " \-\^\-packets " packets"
Specify the number of packets to use in benchmark mode. The
default is 10,000 packets.
.TP
.BR \-f ", " \-\^\-fw-check
Analyze the local firewall ruleset, send any alerts if errors are
discovered, and then exit.
.TP
.BI \-\^\-interval " seconds"
Specify the interval (in seconds) that psad should use to
check whether or not packets have been logged by the
firewall. Psad will use the default of 15 seconds unless a
different value is specified.
.TP
.BR \-U ", " \-\^\-USR1
Send a running psad process a USR1 signal. This will cause psad to
dump the contents of the %Scan hash to the file "/var/log/psad/scan_hash.$$"
where "$$" represents the pid of the psad process. This is mostly
useful for debugging purposes, but it also allows the administrator to
peer into the %Scan hash, which is the primary data structure used to
store scan data within system memory.
.TP
.BR \-H ", " \-\^\-HUP
Send all running psad daemons a HUP signal. This will instruct the
daemons to re-read their respective configuration files without causing
scan data to be lost in the process.
.TP
.BR \-d ", " \-\^\-debug
Run psad in debugging mode. This will automatically prevent
psad from running as a daemon, and will print the contents
of the %Scan hash and a few other things on STDOUT at crucial
points as psad executes.
.TP
.BR \-D ", " \-\^\-Dump-conf
Dump the current psad config to STDOUT and exit.
.TP
.BR \-o ", " \-\^\-output
By default all scan warning messages generated by psad are
written to
.B /var/log/psad/scanlog.
Passing the --output option instructs psad to write all alert
messages to STDOUT.
.TP
.BR \-l ", " \-\^\-log-server
This option should be used if psad is being executed on a syslog
logging server. Running psad on a logging server requires that
check_firewall_rules() and auto_psad_response() not be executed
since the firewall is probably not being run locally.
.TP
.BR \-V ", " \-\^\-Version
Print the psad version and exit.
.TP
.BR \-\^\-no-daemon
Do not run psad as a daemon. This option is most useful
if used in conjunction with --output so that scan warning messages
can be viewed on STDOUT instead of being written to
.B /var/log/psad/scanlog.
.TP
.BR \-\^\-no-ipt-error
Occasionally iptables messages written by syslog to
.B /var/lib/psad/psadfifo
or to
.B /var/log/messages
do not conform to the normal firewall logging format if the kernel
ring buffer used by klogd becomes full. psad will write these message to
.B /var/log/psad/fwerrorlog
by default. Passing the --no-ipt-error option will make psad ignore
all such erroneous firewall messages.
.TP
.BR \-\^\-no-whois
By default psad will issue a whois query against any ip from which
a scan has originated, but this can be disabled with the --no-whois
command line argument.
.TP
.BR \-\^\-no-fwcheck
psad performs a rudimentary check of the firewall ruleset that
exists on the machine on which psad is deployed to determine
whether or not the firewall has a compatible configuration.
Passing the --no-fwcheck or --log-server options will
disable this check.
.TP
.BR \-\^\-no-snort-sids
Disable snort sid processing mode. This will instruct psad to not import
snort rules (for snort SID matching in a policy generated by
.B fwsnort
).
.TP
.BR \-\^\-no-passive-os
By default psad will attempt to passively (i.e. without sending
any packets) fingerprint the remote operating system from which
a scan originates. Passing the --no-passive-os option will
disable this feature.
.TP
.BR \-\^\-no-rdns
Psad normally attempts to find the name associated with a
scanning ip address, but this feature can be disabled with
the --no-rdns command line argument.
.TP
.BR \-\^\-no-netstat
By default for iptables firewalls psad will determine whether
or not your machine is listening on a port for which a tcp
signature has been matched. Specifying --no-netstat
disables this feature.
.TP
.BR \-h ", " \-\^\-help
Print a page of usage information for psad and exit.
.SH FILES
.B /etc/psad/psad_signatures
.RS
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.
.RE
.B /etc/psad/snort_rules/*.rules
.RS
Snort rules files that are consulted by default unless the --no-snort-sids
commmand line argument is given.
.RE
.B /etc/psad/psad_auto_ips
.RS
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>.
.RE
.B /etc/psad/psad_posf
.RS
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.
.RE
.B /etc/psad/psad.conf
.RS
The psad configuration file which contains all configuration variables
mentioned in the section below.
.SH PSAD CONFIGURATION VARIABLES
This section describes what each of the more important psad configuration
variables do and how they can be tuned to meet your needs. These variables
are located in the psad configuration file
.B /etc/psad/psad.conf
and are assigned sensible defaults for most network architectures during
the install process.
.PP
.PD
.TP
.BR EMAIL_ADDRESSES
Contains a comma-separated list of email addresses to which email alerts
will be sent. The default is "root@localhost".
.TP
.BR 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.
.TP
.BR 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).
.TP
.BR 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
.B psad_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
.B 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
.B psad_auto_ips
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
.B psad_auto_ips,
then the corresponding danger level is automatically assigned to the scan.
.TP
.BR 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
.B psad_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).
.TP
.BR 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
.B psad_signatures.
.TP
.BR FW_MSG_SEARCH
Defines the string kmsgsd will search for in iptables log messages that are
written to /var/lib/psad/psadfifo. This string is specified with --log-prefix
in the iptables ruleset, and the default is "DROP".
.TP
.BR 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
.B fwsnort
(http://www.cipherdyne.org/fwsnort/).
.TP
.BR 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.
.TP
.BR 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.
.TP
.BR 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.
.TP
.BR 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.
.TP
.BR EMAIL_ALERT_DANGER_LEVEL
Defines the danger level a scan must reach before any alert is sent.
EMAIL_ALERT_DANGER_LEVEL is set to 1 by default.
.TP
.BR ENABLE_AUTO_IDS
.B 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.
.B 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
.B --Flush
option). Your mileage will vary.
.TP
.BR 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").
.SH EXAMPLES
The following examples illustrate the command line arguments that could
be supplied to psad in a few situations:
Signature checking and automatic ip danger level assignment (best for
most situations) is enabled by default without having to specify any
command line arguments:
.B # psad
The
.B psad.conf,
.B psad_signatures,
and
.B psad_auto_ips
files are normally
located within the /etc/psad/ directory, but the paths to each of these
files can be changed:
.B # 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:
.B # 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:
.B # psad --no-rdns --no-whois
.SH DEPENDENCIES
.B 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
.B FW_EXAMPLE_RULES
file that is bundled with the psad source distribution.
.B psad
also requires that syslog be configured to write all kern.info messages to
the named pipe
\fB/var/lib/psad/psadfifo\fR. A simple
.IP
.B echo -e 'kern.info\\\\t|/var/lib/psad/psadfifo' >> /etc/syslog.conf
.PP
will do. Remember also to restart \fBsyslog\fR after the changes to
this file.
.SH DIAGNOSTICS
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
.B /var/log/psad/scan_hash.$$
where
.B $$
represents the pid of the psad process.
.SH "SEE ALSO"
.BR iptables (8),
.BR kmsgsd (8),
.BR psadwatchd (8),
.BR snort (8),
.BR nmap (1)
.SH AUTHOR
Michael Rash <mbr@cipherdyne.org>
.SH BUGS
Send bug reports to mbr@cipherdyne.org. Suggestions and/or comments are
always welcome as well.
-If $ENABLE_PERSISTENCE="Y", the scan data structures can become
large over time and consume lots of memory depending on the popularity
of your machine/site. Restarting psad solves this problem of course,
but a better way is on the TODO list.
-For iptables firewalls as of Linux kernel version 2.4.21, 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 kernel patch "conntrack_patch" is included with 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 in psad.conf
which causes psad to ignore all tcp packets that have the ACK bit set unless
the packets match a specific signature.
.SH DISTRIBUTION
.B psad
is distributed under the GNU General Public License (GPL), and the latest
version may be downloaded from
.B http://www.cipherdyne.org
Jump to Line
Something went wrong with that request. Please try again.