psad (Port Scan Attack Detector)
Version:  1.4.1
Author:   Michael Rash (mbr@cipherdyne.org)
Website:  http://www.cipherdyne.org

Thanks to: (see the CREDITS file).

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
DESCRIPTION:

    The Port Scan Attack Detector (psad) is a collection of three lightweight
system daemons written in Perl and in C that are designed to work with Linux
iptables firewalling code to detect port scans and other suspect traffic.  It
features a set of highly configurable danger thresholds (with sensible
defaults provided), verbose alert messages that include the source,
destination, scanned port range, begin and end times, tcp flags and
corresponding nmap options, reverse DNS info, email and syslog alerting,
automatic blocking of offending ip addresses via dynamic configuration of
iptables rulesets, passive operating system fingerprinting, and DSheild
reporting.  In addition, psad incorporates many of the tcp, udp, and icmp
signatures included in the snort intrusion detection system
(http://www.snort.org) to detect highly suspect scans for various backdoor
programs (e.g. EvilFTP, GirlFriend, SubSeven), DDoS tools (mstream, shaft),
and advanced port scans (syn, fin, xmas) which are easily leveraged against a
machine via nmap.  psad can also alert on snort signatures that are logged
via fwsnort, which makes use of the iptables string match module to detect
application layer signatures.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
CONFIGURATION INFORMATION:

    Information on config keywords referenced by psad may be found both in the
psad man(8) page, and also here:

http://www.cipherdyne.org/psad/docs/config.html

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
METHODOLOGY:

    All information psad analyzes is gathered from iptables log messages.
psad creates a named pipe (/var/lib/psad/psadfifo) and reconfigures syslog to
write kern.info messages to the pipe.  As log messages are generated by
iptables, a separate daemon (called kmsgsd) reads any messages that match a
particular regular expression designed to catch dropped/rejected packets out
of the pipe and write them to a separate file (/var/log/psad/fwdata).  psad is
then responsible for reading messages as they are generated from this file and
applying the danger threshold and signature logic in order to determine
whether or not a port scan has taken place, send appropriate alert emails,
and (optionally) block offending ip addresses.  psad includes a signal
handler such that if a USR1 signal is received, psad will dump the contents
of the current scan hash data structure to /var/log/psad/scan_hash.$$ where
"$$" represents the pid of the running psad daemon.

    NOTE:  Since psad relies on iptables to generate appropriate log messages
for unauthorized packets, psad is only as good as the logging rules included
in the iptables ruleset.  Usually the best way setup the firewall is with
default "drop and log" rules at the end of the ruleset, and include rules
above this last rule that only allow traffic that should be allowed through.
Upon execution, the psad daemon will attempt to ascertain whether or not such
a default deny rule exists, and will warn the administrator if it doesn't.
See the FW_EXAMPLE_RULES file for example firewall rulesets that are
compatible with psad.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
INSTALLATION:

    See the INSTALL file in the psad sources directory.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
FIREWALL SETUP:

    See the FW_HELP file in the psad sources directory.  Also, read the
    README.SYSLOG file.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
PLATFORMS:

    psad has been tested on RedHat 6.2 - 9.0, Fedora Core 1 and 2, and
Gentoo Linux systems running various kernels.  The only program that
specifically depends on the RedHat architecture is psad-init, which depends
on /etc/rc.d/init.d/functions.  For non-RedHat systems a more generic init
script is included called "psad-init.generic".  The psad init scripts are
mostly included as a nicety; psad can be run from the command line like any
other program.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
COPYRIGHT:

Copyright (C)1999-2006 Michael Rash (mbr@cipherdyne.org)

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

psad makes use of many of the tcp, udp, and icmp signatures available in
Snort (written by Marty Roesch, see http://www.snort.org).  Snort is a
registered trademark of Sourcefire, Inc.


$Id: README 2270 2009-07-30 06:11:13Z mbr $