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

Thanks to: (see the CREDITS file).

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

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
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 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 alerts to /var/log/psad/scanlog, send 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/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 setup 
the firewall is with a default "deny and log" rule 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.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
		  can be viewed on STDOUT instead of being written to 
		  /var/log/psad/scanlog.
	
	-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.

	-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 a crucial points
		  as psad executes.

	-i  --interval
		  Specify the interval (in seconds) that psad should use to 
		  check whether or not packets have been denied by the 
		  firewall.  Psad will use the default of 15 seconds unless a
		  different value is specified.

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

	-r  --reversedns
		  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.
	
	-L  --Logging_server
		  Psad is being executed on a syslog server.  This requires
		  that check_firewall_rules() and auto_psad_response() not be
		  executed since the firewall is probably not being run locally.
	-K  --Kill
                  Kill the current psad process along with psadwatchd, kmsgsd, 
		  and diskmond. 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.

	-R  --Restart
              	  Restart the currently running psad processes. This option 
		  will preserve the command line options that were supplied to 
		  the original psad process.

	-S  --Status
		  Display the status of any psad processes that may or may
		  not be running.

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

	-V  --Version
		  Print the psad version and exit.

	-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 [-n] [-d] [-o] [-e] [-f] [-r] [-w] [-S] [-l] [-i <interval>] [-h]
		[-c <config file>] [-s <signature file>] [-a <auto ips file>]

        -D   --Daemon                   - do not run as a daemon.
        -e   --errors                   - do not write errors to the error 
					  log.
        -d   --debug                    - run psad in debugging mode.
        -w   --whois                    - disable whois lookups.
        -i   --interval                 - configure the check interval from 
					  the command line to override the 15 
					  second default.
        -f   --firewallcheck            - disable firewall rules verification.
        -o   --output                   - print all messages to STDOUT (this
                                          does not include bad packet messages
                                          that are printed to the error log).
        -c   --config <config file>     - use config file instead of the 
					  values contained within the psad 
					  script.
        -r   --reversedns               - disable name resolution against
                                          scanning ips.
        -s   --signatures <sig file>    - import scan signatures.
        -a   --auto_ips <ips file>      - import auto ips file for automatic
                                          ip danger level increases/decreases.
	-L   --Logging_server		- psad is being run on a syslog
					  server.
        -l   --local_port_lookup        - disable local port lookups for scan
                                          signatures.
        -h   --help                     - prints this help message.

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

	(See the INSTALL file in the source directory.) 

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

	psad has been tested on RedHat 6.2 and 7.1 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.
