Added the psad.8 man page, made Getopt case sensistive, better docume…

…ntation, a couple of fixes from Bruce Meyer

git-svn-id: file:///home/mbr/svn/psad_repos/psad/trunk@125 91a0a83b-1414-0410-bf9a-c3dbc33e90b6

BENCHMARK

@@ -1,17 +1,18 @@
 Kmsgsd Benchmarks:
 
 The basic strategy in benchmarking kmsgsd is to get syslogd to write kern.info
-messages (which include ipchains and iptables log messages) to the /var/log/psadfifo
-named pipe.  Kmsgsd will then read the messages out of the pipe as quickly as
-possible and write them to /var/log/psad/fwdata.  To calculate how fast kmsgsd is
-we then compare the number of newly written firewall messages to /var/log/messages
-with the number of messages kmsgsd was able to write to /var/log/psad/fwdata in the
-same time frame.  To generate lots of firewall "deny" messages we first make sure we
-have the firewall "default log and deny" policy loaded, and then proceed to scan the
-firewall first from a machine that is linked via a 100MB ethernet segment connected 
-directly to the firewall with a crossover cable, and second with a scan against the 
-loopback address from the firewall itself.  The second scan will eliminate any 
-network latency from slowing the scan down.
+messages (which include ipchains and iptables log messages) to the 
+/var/log/psadfifo named pipe.  Kmsgsd will then read the messages out of the 
+pipe as quickly as possible and write them to /var/log/psad/fwdata.  To 
+calculate how fast kmsgsd is we then compare the number of newly written 
+firewall messages to /var/log/messages with the number of messages kmsgsd was 
+able to write to /var/log/psad/fwdata in the same time frame.  To generate lots
+of firewall "deny" messages we first make sure we have the firewall "default 
+log and deny" policy loaded, and then proceed to scan the firewall first from a 
+machine that is linked via a 100MB ethernet segment connected directly to the 
+firewall with a crossover cable, and second with a scan against the loopback 
+address from the firewall itself.  The second scan will eliminate any network 
+latency from slowing the scan down.
 
 TEST 1:
 - Scanning machine: PIII 700mhz, kernel 2.2.18
@@ -49,17 +50,16 @@ Results:  These results are a bit surprising since kmsgsd caught more
   had a maximum CPU utilization of 5.6% and a maximum memory utilization of
   0.8%
 
-
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 Psad Benchmarks:
 
-To benchmark psad we need to generate lots of messages in the fwdata file.  Normally
-this is the responsibility of kmsgsd, but to perform an effective test of just how fast
-psad is able to parse lots of firewall "deny" messages, we first create a large file
-that contains 10,000 lines of the firewall messages, then we execute "cat /dev/null > 
-/var/log/psad/fwdata", and lastly we copy the large file to /var/log/psad/fwdata. 
-Psad then detects that 10,000 packets were just denied by the firewall and starts to 
-process the lines one by one.
+To benchmark psad we need to generate lots of messages in the fwdata file.  
+Normally this is the responsibility of kmsgsd, but to perform an effective test 
+of just how fast psad is able to parse lots of firewall "deny" messages, we 
+first create a large file that contains 10,000 lines of the firewall messages,
+then we execute "cat /dev/null > /var/log/psad/fwdata", and lastly we copy the 
+large file to /var/log/psad/fwdata.  Psad then detects that 10,000 packets were 
+just denied by the firewall and starts to process the lines one by one.
 
 - PIII 500mhz, 128MB ram, kernel 2.4.0
 - Perl 5.005_03

CREDITS

@@ -13,8 +13,7 @@ Sweth Chandramouli	(Bastille Linux) Various suggestions for psad
 			and install.pl, including invaluable help 
 			with various Perl vagaries.
 
-Jay Beale		(Bastille Linux) Psad/Bastille integration.
-			Excellent suggestions for psad reporting and 
-			enhanced security, and also for integrating
-			psad with Bastille. 
+Jay Beale		(Bastille Linux) Excellent suggestions for 
+			psad reporting and enhanced security, and 
+			also for integrating psad with Bastille. 
 

INSTALL

@@ -8,7 +8,7 @@ them), then psad will NOT detect port scans.  Usually the best and most
 secure way to configure your firewall is to first put the minimal rules 
 needed to allow only necessary traffic to and from your machine, and 
 then have a default drop/deny/reject-and-log rule toward the end of the 
-firewall rulebase.  Some example firewall rulesets that are compatible
+firewall ruleset.  Some example firewall rulesets that are compatible
 with psad are contained within the file FW.EXAMPLES.
 
 
@@ -34,25 +34,31 @@ and diskmond, or just run them from the command line.  The install.pl
 script installs psad, kmsgsd, and diskmond in /usr/local/bin/ by 
 default.  
 
-	Note: You can install a new version of psad over an
+	You can install a new version of psad over an
 existing one; just run install.pl.  The installation script will
 preserve any old configuration parameters when installing the new 
 versions of psad, kmsgsd, and diskmond.  If you don't need/want any
 old configurations to be preserved, just execute "./install.pl -n".
 
-	Note: Even though it is a good idea to edit the config sections
+	Even though it is a good idea to edit the config sections
 of each of the programs included with psad, both install.pl and psad
 attempt to use the correct system binaries even if an incorrect path
 is given.  This is accomplished by simply using the path provided by
 'which <system binary>' if the binary is not found in the place 
 specified in the config section.
 
+	psad can be completely removed from the system by executing
+install.pl with the --uninstall option.
+
 USAGE:
 
-Usage: psad [-f] [-h] [-n] [-h]
+Usage: psad [-f] [-n] [-e] [-u] [-v] [-h]
 
-        --no_preserve            - disable preservation of old configs.
-        --exec_psad              - execute psad after installing.
-        --firewallcheck          - disable firewall rules verification.
-        --help                   - prints this help message.
+        -n  --no_preserve            - disable preservation of old configs.
+        -e  --exec_psad              - execute psad after installing.
+        -f  --firewallcheck          - disable firewall rules verification.
+	-u  --uninstall              - completely remove psad from the
+				       system.
+	-v  --verbose                - verbose mode.		
+        -h  --help                   - prints this help message.
 

README

@@ -75,10 +75,11 @@ compatible with psad.
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 USAGE:
 
-	-n  --noDaemon   
+	-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.
+		  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 
@@ -121,6 +122,11 @@ USAGE:
 		  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  --Syslog_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.
 
 	-s  --signatures <sig file>
 		  The firewalling code included within the linux 2.4.x kernel
@@ -161,7 +167,7 @@ USAGE:
 Usage: psad [-n] [-d] [-o] [-e] [-f] [-r] [-w] [-l] [-i <interval>] [-h]
 		[-c <config file>] [-s <signature file>] [-a <auto ips file>]
 
-        -n   --noDaemon                 - do not run as a daemon.
+        -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.
@@ -180,7 +186,9 @@ Usage: psad [-n] [-d] [-o] [-e] [-f] [-r] [-w] [-l] [-i <interval>] [-h]
                                           scanning ips.
         -s   --signatures <sig file>    - import scan signatures.
         -a   --auto_ips <ips file>      - import auto ips file for automatic
-                                          ip danger level increases/decreses.
+                                          ip danger level increases/decreases.
+	-S   --Syslog_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.

install.pl

@@ -64,7 +64,7 @@
 if ($uninstall) {
 	my $ans = "";
 	while ($ans ne "y" && $ans ne "n") {
-		print "=-=-=  This will completely psad from your system.  Are you sure (y/n)?  ";
+		print "=-=-=  This will completely remove psad from your system.  Are you sure (y/n)?  ";
 		$ans = <STDIN>;
 		chomp $ans;
 	}
@@ -103,7 +103,7 @@
 	if (-e "/etc/syslog.conf.orig") {
 		`$Cmds{'mv'} /etc/syslog.conf.orig /etc/syslog.conf`;
 	} else {
-		print "=-=-= /etc/syslog.conf.orig does not exist.  Editing /etc/syslog.conf directly\n";
+		print "=-=-= /etc/syslog.conf.orig does not exist.  Editing /etc/syslog.conf directly.\n";
 		open ESYS, "< /etc/syslog.conf" or die "=-=-= Unable to open /etc/syslog.conf: $!\n";
 		my @sys = <ESYS>;
 		close ESYS;
@@ -120,7 +120,7 @@
 	print "=-=-=  Psad has been uninstalled =-=-=\n";
 	exit 0;
 }
-### Start the install code...
+### Start the installation code...
 unless (-e "/var/log/psadfifo") {
 	print "=-=-=  Creating named pipe /var/log/psadfifo\n";
 	# create the named pipe
@@ -235,6 +235,37 @@
 	`$Cmds{'cp'} psad.conf /etc/psad/psad.conf`;
 	perms_ownership("/etc/psad/psad.conf", 0600);
 }
+print "=-=-=  Installing psad(8) man page\n";
+if (-e "/etc/man.config") {
+	# prefer to install psad.8 in /usr/local/man/man8 if this directory is configured in /etc/man.config
+	if (open MPATH, "< /etc/man.config" and grep /MANPATH\s+\/usr\/local\/man/, <MPATH> and close MPATH) {
+		`$Cmds{'cp'} psad.8 /usr/local/man/man8/psad.8`;
+		perms_ownership("/usr/local/man/man8/psad.8", 0644);
+	} else {
+		my $mpath;
+		open MPATH, "< /etc/man.config";
+		while(<MPATH>) {
+			my $line = $_;
+			chomp $line;
+			if ($line =~ /^MANPATH\s+(\S+)/) {
+				$mpath = $1;
+				last;
+			}
+		}
+		close MPATH;
+		if ($mpath) {
+			my $path = $mpath . "/man8/psad.8";
+			`$Cmds{'cp'} psad.8 $path`;
+			perms_ownership($path, 0644);
+		} else {
+			`$Cmds{'cp'} psad.8 /usr/man/man8/psad.8`;
+			perms_ownership("/usr/man/man8/psad.8", 0644);
+		}
+	}
+} else {
+	`$Cmds{'cp'} psad.8 /usr/man/man8/psad.8`;
+	perms_ownership("/usr/man/man8/psad.8", 0644);
+}
 
 my $distro = get_distro();
 my $kernel = get_kernel(\%Cmds);

psad

@@ -24,10 +24,13 @@
 #	  --log-tcp-sequence, etc.) for better signature recognition.
 #	- Allow ipchains to use udp signatures as well as tcp signatures that
 #	  only require a syn packet to a port.
+#	- Deal with the possibility that psad could eat lots of memory over
+#	  time if $ENABLE_PERSISTENCE="Y". This should involve periodically
+#	  undef'ing entries in %Scan (or maybe the entire hash), but this 
+#	  should be done in a way that allows some scan data to persist.
 #	- Put source and destination ip addresses back into psad_signatures.
 #	- Ipfilter support on *BSD platforms.
 #	- Icmp support.
-#	- Man page.
 #	- Re-write significant components (kmsgsd, diskmond, psadwatchd) in C.
 #	- Add a new "minimal execution mode" to psad in which several of the 
 #	  "use <blah>" statements are taken out (not eval'ed or something).
@@ -40,6 +43,8 @@
 # 	  stream provided to psad by kmsgsd since more packet types will be 
 #	  denied without requiring overly complicated firewall rules to detect 
 #	  odd tcp flag combinations.
+#	- Investigate the possibility of passive OS fingerprinting by looking
+#	  at TTL and other fields in the headers.
 #	- Sometimes packets (particularly ACK and RST packets) seem to not
 #	  recognized by ipt_state/ip_conntrack, so such packets get denied and
 #	  hence are picked up by psad.  Solution: parse /proc/net/ip_conntrack
@@ -127,13 +132,16 @@ my $signatures = 0;
 my $auto_ips = 0;
 my $netstat_lookup = 0;
 my $fwcheck = 0;
-my $dnsstring;
+my $Syslog_server = 0;
+# my $dnsstring;
 
 use File::stat;
 use Getopt::Long;
 use Data::Dumper;
 use Socket;
 
+Getopt::Long::Configure("no_ignore_case");  # make Getopts case sensitive
+
 my %Cmds = (
         "ipchains"      => $ipchainsCmd,
         "iptables"      => $iptablesCmd,
@@ -162,7 +170,7 @@ usage_and_exit(1) unless (GetOptions (
         'help'          => \$help,		# display help
 	'auto_ips=s'	=> \$auto_ips,		# enable automatic ip danger level assignment
 	'output'	=> \$output,		# write scanlog messages to STDOUT
-	'noDaemon'	=> \$daemon,		# do not run as a daemon
+	'Daemon'	=> \$daemon,		# do not run as a daemon
 	'debug'		=> \$DEBUG, 		# run in debug mode
 	'interval=s'	=> \$CHECK_INTERVAL,	# set $CHECK_INTERVAL from the command line
 	'firewallcheck'	=> \$fwcheck,		# do not check firewall rules
@@ -171,11 +179,14 @@ usage_and_exit(1) unless (GetOptions (
 	'signatures=s'	=> \$signatures,	# scan signatures
 	'localport'	=> \$netstat_lookup,	# do not check to see if the firewall is listening on localport that has been scanned
 	'errors'	=> \$errors,		# do not write malformed packet messages to error log
+	'Syslog_server'	=> \$Syslog_server,	# we are running psad on a syslog logging server
 	'whois'		=> \$whoislookups	# do not issue whois lookups against the scanning ip
 ));
 usage_and_exit(0) if ($help);
 
-unless ($fwcheck) {
+$< == 0 && $> == 0 or die "You must be root (or equivalent UID 0 account) to execute psad!\n";
+
+unless ($fwcheck || $Syslog_server) { # if psad is running on a syslog server, don't check the firewall rules since they may not be local...
 	unless (check_firewall_rules(\%Cmds)) {
         	die "*** After setting up your firewall per the above note, execute \"/etc/rc.d/init.d/psad-init start\" to start psad\n";
 	}
@@ -218,7 +229,7 @@ for (;;) {
 	my $fwdata_end_lines = (split /\s+/, `$Cmds{'wc'} -l $FW_DATA`)[1];
 	if ($signatures) {  # scan $signatures for any signature updates
 		my $sigs_mtime_end = stat($signatures)->mtime;
-		if ($sigs_mtime_start != $sigs_mtime_end) {  # the signatures were updated... import the new signatures
+		if ($sigs_mtime_start != $sigs_mtime_end) {  # the signatures were updated... import the new signatures.
 			$Sigs_href = import_signatures($signatures);
 			my $hostname = `$Cmds{'hostname'}`;
                 	chomp $hostname;
@@ -250,11 +261,11 @@ for (;;) {
 		print "MAIN: calling logr()\n" if $DEBUG;
 		$Scan_href = logr($Scan_href, $PSAD_LOGFILE, $output, $dnslookups, $whoislookups, $WHOIS_TIMEOUT, $ENABLE_EMAIL_ALERTS,
 					$EMAIL_ALERT_DANGER_LEVEL, $EMAIL_ALERTFILE, \@EMAIL_ADDRESSES, $SHOW_ALL_SIGNATURES, \%Cmds);
-		if ($ENABLE_AUTO_IDS eq "Y") {
+		if ($ENABLE_AUTO_IDS eq "Y" && ! $Syslog_server) {  # don't manage the firewall rules if psad is running on a syslog server.
 			$Scan_href = auto_psad_response($Scan_href, $AUTO_IDS_DANGER_LEVEL, \%Cmds, \@EMAIL_ADDRESSES);
 		}
 	}
-	print "Number of lines in $FW_DATA: $fwdata_end_lines\n" if $DEBUG;
+	print "MAIN: number of lines in $FW_DATA: $fwdata_end_lines\n" if $DEBUG;
 	$fwdata_start_lines = $fwdata_end_lines; # reset fwdata_start_lines to where we just left off so that we don't miss any packets
 }
 
@@ -1152,10 +1163,10 @@ sub usage_and_exit() {
         my $exitcode = shift;
         print <<_HELP_;
 
-Usage: psad [-n] [-d] [-o] [-e] [-f] [-r] [-w] [-l] [-i <interval>] [-h]
+Usage: psad [-D] [-d] [-o] [-e] [-S] [-f] [-r] [-w] [-l] [-i <interval>] [-h]
                 [-c <config file>] [-s <signature file>] [-a <auto ips file>]
 
-        -n   --noDaemon                 - do not run as a daemon.
+        -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.
@@ -1170,6 +1181,8 @@ Usage: psad [-n] [-d] [-o] [-e] [-f] [-r] [-w] [-l] [-i <interval>] [-h]
         -c   --config <config file>     - use config file instead of the
                                           values contained within the psad
                                           script.
+	-S   --Syslog_server		- psad is being run on a syslog
+					  server.
         -r   --reversedns               - disable name resolution against
                                           scanning ips.
         -s   --signatures <sig file>    - import scan signatures.