psad (Port Scan Attack Detector)
Version:  1.0.0-pre1
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, udp, and icmp 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 and syslog 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/lib/psad/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_EXAMPLE_RULES 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.

    -c  --config <configuration file>
          By default all of the psad daemons (psad, psadwatchd, kmsgsd,
          and diskmond) make use of the configuration file
          /etc/psad/psad.conf for almost all configuration parameters.
          psad can be made to override this path by specifying a
          different file on the command line with the --config option.

    -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, 2.4.0, and 2.4.17, 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.


$Id: README,v 1.6 2002/09/24 02:06:20 mbr Exp $
