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

Thanks to: Bruce Meyer (gh1@rocsoft.net) for suggestions and testing.

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

Copyright (C)1999,2000,2001 Michael B. Rash (mbr@cipherdyne.com)

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 signatures available in Snort (written by
Marty Roesch, see http://www.snort.org).

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

	The Port Scan Attack Detector (psad) is a program written in Perl 
that is designed to work with Linux firewalling code (iptables in the 2.4.x
kernels, and ipchains in the 2.2.x kernels) to detect port scans.  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 (Linux 2.4.x kernels only), reverse DNS info,
email alerting, and automatic blocking of offending ip addresses via dynamic 
configuration of ipchains/iptables firewall rulesets.  In addition, for the
2.4.x kernels psad incorporates many of the tcp signatures included in Snort 
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. 

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

	All information psad analyzes is gathered from iptables/ipchains log
messages.  psad creates a named pipe (/var/log/psadfifo) and reconfigures 
syslog to write kern.info messages to the pipe.  As log messages are 
generated by iptables or ipchains, 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 writes 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 alerts to /var/log/psad/scanlog, send alert emails,
and (optionally) block offending ip addresses.  psad includes a signal
handler such that if a SIGUSR1 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/ipchains to generate appropriate
log messages for unauthorized packets, psad is only as good as the logging
rules included in the iptables/ipchains ruleset.  Usually the best way to 
accomplish this is with a default "deny and log" rule at the end of the 
ruleset and allow only the things that should be allowed through above this
last rule.  Both install.pl and psad itself attempt to ascertain whether or 
not such a default deny rule exists, and will warn the administrator if it
doesn't.  See the FW.EXAMPLES file for example firewall rulesets that are
compatible with psad.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
USAGE:

Usage: psad [-d] [-o] [-e] [-f] [-c <config file>] [-s <signature file> [-h]

        -daemon                 - do not run as a daemon.
        -error                  - do not write errors to the error log.
        -firewallcheck          - disable firewall rules verification.
        -output                 - print all messages to STDOUT (this
                                  does not include bad packet messages
                                  that are printed to the error log).
        -config <config file>   - use config file instead of the values
                                  contained within the psad script.
        -namelookups            - disable name resolution against
                                  scanning ips.
        -signatures <sig file>  - import scan signatures.
        -local_port_lookup      - disable local port lookups for scan
                                  signatures.
        -h                      - prints this help message.


=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
INSTALL:

	(See the INSTALL file in the source directory.) 

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

	psad has been tested on RedHat 6.2 running kernels 2.2.14-5.0, 2.2.18, 
and 2.4.0 although it should work on any Linux system that has a properly
configured firewall.  The only program that depends on the RedHat architecture 
is psad-init, which specifically depends on /etc/rc.d/init.d/functions.  
psad-init is mostly included as a nicety; it can be run from the command line
like any other program.
