psad (Port Scan Attack Detector) 
Version:  0.8.6
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:

	-d  -daemon   
		  Do not run psad as a daemon.  This option is most useful
		  if used in conjunction with -o so that scan warning messages
		  are written to STDOUT instead of the scanlog file.
	
	-e  -error    
		  Occasionally messages that are written by to the psadfifo 
		  named pipe and also to /var/log/messages do not conform to 
		  the normal firewall logging format and psad will write these
		  message to /var/log/psad/fwerrorlog by default.  Passing the
		  -error option will make psad ignore all such erroneous
		  firewall messages.

	-o  -output
		  By default all scan warning messages generated by psad are
		  written to /var/log/psad/scanlog.  Passing the -o option 
		  instructs psad to write all error messages to STDOUT.

	-f  -firewallcheck
		  Psad performs a rudimentary check of the firewall rules that
		  exist on the machine on which psad is deployed to determine
		  whether or not the firewall has a compatible configuration.
		  Passing the -f option will disable this check.

	-c  -config  <configuration file>
		  By default psad uses configuration parameters that are
		  present within the configuration section of the psad script
		  itself.  This can be overridden by specifying a configuration
		  file on the command line.

	-n  -namelookups
		  Psad normally attempts to find the name associated with a
		  scanning ip address, but this feature can be disabled with 
		  the -n command line argument.

	-s  -signatures <sig file>
		  The firewalling code included within the linux 2.4.x kernel
		  series, iptables, has the ability to distinguish and log any
		  of the tcp flags present within tcp packets that traverse 
		  the interfaces.  Psad makes use of this logging capability 
		  to detect several types of tcp scan signatures included
		  within the psad_signatures file.  The signatures were 
		  originally included within the Snort intrusion detection
		  system (see http://www.snort.org).  A modification can be 
		  made to the signature file (installed by default in /etc/psad)
		  and psad will import the change automatically without having
		  to restart the psad process.  Unfortunately tcp signature 
		  checking is not compatible with the ipchains firewalling code 
		  built into the 2.2.x kernel series due to the fact that 
		  ipchains cannot distinguish any tcp flags other than syn and 
		  ack.

	-a  -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).  The psad_auto_ips file 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.

	-l  -local_port_lookup
		  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 the -l command line 
		  argument disables this feature.


Usage: psad [-d] [-o] [-e] [-f] [-c <config file>] [-s <signature file>] [-a <auto ips 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.
	-auto_ips <ips file>	- import auto ips file for automatic
				  ip danger level increases/decreases.
        -local_port_lookup      - disable local port lookups for scan
                                  signatures.
        -h                      - prints this help message.


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

	(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.  

Ipfilter support on *BSD boxes is coming soon.
