psad (Port Scan Attack Detector)
Version:  3.0
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 two 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(8) man page, and also here:

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

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

    All information psad analyzes is gathered from iptables log messages.
psad by default reads the /var/log/messages file for new iptables messages and
optionally writes them out to a dedicated file (/var/log/psad/fwdata).
psad is then responsible for 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.

Additionally, extensive coverage of psad is included in the book "Linux
Firewalls: Attack Detection and Response" published by No Starch Press, and a
supporting script in this book is compatible with psad.  This script can be
found here:

http://www.cipherdyne.org/LinuxFirewalls/ch01/

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