Added EMAIL_THROTTLE for email throttling

Added the ability to throttle emails generated by psad via a new
EMAIL_THROTTLE variable which is implemented as a per-IP threshold.  That
is, if EMAIL_THROTTLE is set to "10", then psad will only send 1/10th as
many emails for each scanning IP as it would have normally.  This feature
was suggested by Naji Mouawad.

diff --git a/CREDITS b/CREDITS
index de29bdc..f971a61 100644 (file)
--- a/CREDITS
+++ b/CREDITS
@@ -490,3 +490,7 @@ Oscar Marley
     - Suggested configurable auto-blocking timeout values depending on the
       danger level that a scan or attack achieves.  This resulted in the
       implementation of the AUTO_BLOCK_DL*_TIMEOUT variables.
+
+Naji Mouawad
+    - Suggested the ability to throttle email alerts that psad sends.  The
+      This resulted in the implementation of the EMAIL_THROTTLE variable.

diff --git a/ChangeLog b/ChangeLog
index bd9fafb..e383fe4 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,4 +1,4 @@
-psad-2.2.1 (12//2012):
+psad-2.2.1 (01//2013):
     - Added IP protocol scan detection (nmap -sO).  A new psad.conf variable
       PROTOCOL_SCAN_THRESHOLD defines the minimum number of different IP
       protocols (default = 5) that must be scanned before an alert is
@@ -42,6 +42,14 @@ psad-2.2.1 (12//2012):
       to look for the fwsnort rule set.  This fixes a problem reported by Pui
       Edylie to the psad mailing list where fwsnort logged an attack that psad
       could not map back to a descriptive 'msg' field.
+    - Added the ability to set per-danger level timeouts when psad is
+      configured to run in auto-blocking mode.  These timeouts are implemented
+      with new AUTO_BLOCK_DL*_TIMEOUT variables - one for each of the five
+      possible danger levels that may be assigned to a scanning IP address.
+    - Added the ability to throttle emails generated by psad via a new
+      EMAIL_THROTTLE variable which is implemented as a per-IP threshold.  That
+      is, if EMAIL_THROTTLE is set to "10", then psad will only send 1/10th as
+      many emails for each scanning IP as it would have normally.
 
 psad-2.2 (02/20/2012):
     - Added support for detection of malicious traffic that is delivered via

diff --git a/psad b/psad
index d96fa1c..43a9ff5 100755 (executable)
--- a/psad
+++ b/psad
@@ -5197,6 +5197,10 @@ sub scan_logr() {
             unless ($no_email_alerts) {
                 $scan_email_ctrs{$src}{'email_ctr'}++;
             }
+            if ($config{'EMAIL_THROTTLE'} > 1) {
+                next SRC if (($scan_email_ctrs{$src}{'email_ctr'}
+                        % $config{'EMAIL_THROTTLE'}) == 0);
+            }
         }
 
         DST: for my $dst (keys %{$curr_scan_hr->{$src}}) {
@@ -5251,6 +5255,10 @@ sub scan_logr() {
                 unless ($no_email_alerts) {
                     $scan_email_ctrs{$src}{$dst}{'email_ctr'}++;
                 }
+                if ($config{'EMAIL_THROTTLE'} > 1) {
+                    next DST if (($scan_email_ctrs{$src}{$dst}{'email_ctr'}
+                            % $config{'EMAIL_THROTTLE'}) == 0);
+                }
             }
             print STDERR "[+] scan_logr(): dst IP: $dst\n" if $debug;
 
@@ -10970,7 +10978,7 @@ sub required_vars() {
         ICMP6_TYPES_FILE PROTOCOL_SCAN_THRESHOLD PROTOCOLS_FILE
         AUTO_BLOCK_DL1_TIMEOUT AUTO_BLOCK_DL2_TIMEOUT
         AUTO_BLOCK_DL3_TIMEOUT AUTO_BLOCK_DL4_TIMEOUT
-        AUTO_BLOCK_DL5_TIMEOUT
+        AUTO_BLOCK_DL5_TIMEOUT EMAIL_THROTTLE
     ));
     &defined_vars(\@required_vars);
     return;

diff --git a/psad.conf b/psad.conf
index fe7b105..792c14d 100644 (file)
--- a/psad.conf
+++ b/psad.conf
@@ -242,6 +242,14 @@ ENABLE_EMAIL_LIMIT_PER_DST  N;
 ### EMAIL_LIMIT threshold.
 EMAIL_LIMIT_STATUS_MSG      Y;
 
+### This variable is used to have psad throttle the email alerts it sends,
+### and implemented as a per-IP threshold.  That is, if EMAIL_THROTTLE
+### is set to "10", then psad will only send 1/10th as many emails for each
+### scanning IP as it would have normally.  All other variables also apply,
+### so this throttle value is taken into account after everything else.  The
+### default of zero means to not apply any throttling.
+EMAIL_THROTTLE              0;
+
 ### If "Y", send email for all newly logged packets from the same
 ### source ip instead of just when a danger level increases.
 ALERT_ALL                   Y;

diff --git a/test/conf/auto_blocking.conf b/test/conf/auto_blocking.conf
index f35bc68..bc81dcc 100644 (file)
--- a/test/conf/auto_blocking.conf
+++ b/test/conf/auto_blocking.conf
@@ -240,6 +240,14 @@ ENABLE_EMAIL_LIMIT_PER_DST  N;
 ### EMAIL_LIMIT threshold.
 EMAIL_LIMIT_STATUS_MSG      Y;
 
+### This variable is used to have psad throttle the email alerts it sends,
+### and implemented as a per-IP threshold.  That is, if EMAIL_THROTTLE
+### is set to "10", then psad will only send 1/10th as many emails for each
+### scanning IP as it would have normally.  All other variables also apply,
+### so this throttle value is taken into account after everything else.  The
+### default of zero means to not apply any throttling.
+EMAIL_THROTTLE              0;
+
 ### If "Y", send email for all newly logged packets from the same
 ### source ip instead of just when a danger level increases.
 ALERT_ALL                   Y;

diff --git a/test/conf/default_psad.conf b/test/conf/default_psad.conf
index 29104f3..7902028 100644 (file)
--- a/test/conf/default_psad.conf
+++ b/test/conf/default_psad.conf
@@ -240,6 +240,14 @@ ENABLE_EMAIL_LIMIT_PER_DST  N;
 ### EMAIL_LIMIT threshold.
 EMAIL_LIMIT_STATUS_MSG      Y;
 
+### This variable is used to have psad throttle the email alerts it sends,
+### and implemented as a per-IP threshold.  That is, if EMAIL_THROTTLE
+### is set to "10", then psad will only send 1/10th as many emails for each
+### scanning IP as it would have normally.  All other variables also apply,
+### so this throttle value is taken into account after everything else.  The
+### default of zero means to not apply any throttling.
+EMAIL_THROTTLE              0;
+
 ### If "Y", send email for all newly logged packets from the same
 ### source ip instead of just when a danger level increases.
 ALERT_ALL                   Y;

diff --git a/test/conf/disable_ipv6_detection.conf b/test/conf/disable_ipv6_detection.conf
index 152a957..f356410 100644 (file)
--- a/test/conf/disable_ipv6_detection.conf
+++ b/test/conf/disable_ipv6_detection.conf
@@ -240,6 +240,14 @@ ENABLE_EMAIL_LIMIT_PER_DST  N;
 ### EMAIL_LIMIT threshold.
 EMAIL_LIMIT_STATUS_MSG      Y;
 
+### This variable is used to have psad throttle the email alerts it sends,
+### and implemented as a per-IP threshold.  That is, if EMAIL_THROTTLE
+### is set to "10", then psad will only send 1/10th as many emails for each
+### scanning IP as it would have normally.  All other variables also apply,
+### so this throttle value is taken into account after everything else.  The
+### default of zero means to not apply any throttling.
+EMAIL_THROTTLE              0;
+
 ### If "Y", send email for all newly logged packets from the same
 ### source ip instead of just when a danger level increases.
 ALERT_ALL                   Y;

diff --git a/test/conf/enable_ack_detection.conf b/test/conf/enable_ack_detection.conf
index 9d7bedd..9076664 100644 (file)
--- a/test/conf/enable_ack_detection.conf
+++ b/test/conf/enable_ack_detection.conf
@@ -240,6 +240,14 @@ ENABLE_EMAIL_LIMIT_PER_DST  N;
 ### EMAIL_LIMIT threshold.
 EMAIL_LIMIT_STATUS_MSG      Y;
 
+### This variable is used to have psad throttle the email alerts it sends,
+### and implemented as a per-IP threshold.  That is, if EMAIL_THROTTLE
+### is set to "10", then psad will only send 1/10th as many emails for each
+### scanning IP as it would have normally.  All other variables also apply,
+### so this throttle value is taken into account after everything else.  The
+### default of zero means to not apply any throttling.
+EMAIL_THROTTLE              0;
+
 ### If "Y", send email for all newly logged packets from the same
 ### source ip instead of just when a danger level increases.
 ALERT_ALL                   Y;

diff --git a/test/conf/ignore_tcp.conf b/test/conf/ignore_tcp.conf
index e883839..e42ef1d 100644 (file)
--- a/test/conf/ignore_tcp.conf
+++ b/test/conf/ignore_tcp.conf
@@ -240,6 +240,14 @@ ENABLE_EMAIL_LIMIT_PER_DST  N;
 ### EMAIL_LIMIT threshold.
 EMAIL_LIMIT_STATUS_MSG      Y;
 
+### This variable is used to have psad throttle the email alerts it sends,
+### and implemented as a per-IP threshold.  That is, if EMAIL_THROTTLE
+### is set to "10", then psad will only send 1/10th as many emails for each
+### scanning IP as it would have normally.  All other variables also apply,
+### so this throttle value is taken into account after everything else.  The
+### default of zero means to not apply any throttling.
+EMAIL_THROTTLE              0;
+
 ### If "Y", send email for all newly logged packets from the same
 ### source ip instead of just when a danger level increases.
 ALERT_ALL                   Y;

diff --git a/test/conf/ignore_udp.conf b/test/conf/ignore_udp.conf
index ca136de..180fb40 100644 (file)
--- a/test/conf/ignore_udp.conf
+++ b/test/conf/ignore_udp.conf
@@ -240,6 +240,14 @@ ENABLE_EMAIL_LIMIT_PER_DST  N;
 ### EMAIL_LIMIT threshold.
 EMAIL_LIMIT_STATUS_MSG      Y;
 
+### This variable is used to have psad throttle the email alerts it sends,
+### and implemented as a per-IP threshold.  That is, if EMAIL_THROTTLE
+### is set to "10", then psad will only send 1/10th as many emails for each
+### scanning IP as it would have normally.  All other variables also apply,
+### so this throttle value is taken into account after everything else.  The
+### default of zero means to not apply any throttling.
+EMAIL_THROTTLE              0;
+
 ### If "Y", send email for all newly logged packets from the same
 ### source ip instead of just when a danger level increases.
 ALERT_ALL                   Y;

diff --git a/test/conf/require_DROP_syslog_prefix_str.conf b/test/conf/require_DROP_syslog_prefix_str.conf
index 594246e..4c8089b 100644 (file)
--- a/test/conf/require_DROP_syslog_prefix_str.conf
+++ b/test/conf/require_DROP_syslog_prefix_str.conf
@@ -240,6 +240,14 @@ ENABLE_EMAIL_LIMIT_PER_DST  N;
 ### EMAIL_LIMIT threshold.
 EMAIL_LIMIT_STATUS_MSG      Y;
 
+### This variable is used to have psad throttle the email alerts it sends,
+### and implemented as a per-IP threshold.  That is, if EMAIL_THROTTLE
+### is set to "10", then psad will only send 1/10th as many emails for each
+### scanning IP as it would have normally.  All other variables also apply,
+### so this throttle value is taken into account after everything else.  The
+### default of zero means to not apply any throttling.
+EMAIL_THROTTLE              0;
+
 ### If "Y", send email for all newly logged packets from the same
 ### source ip instead of just when a danger level increases.
 ALERT_ALL                   Y;

diff --git a/test/conf/require_missing_syslog_prefix_str.conf b/test/conf/require_missing_syslog_prefix_str.conf
index 599ae22..89336d8 100644 (file)
--- a/test/conf/require_missing_syslog_prefix_str.conf
+++ b/test/conf/require_missing_syslog_prefix_str.conf
@@ -240,6 +240,14 @@ ENABLE_EMAIL_LIMIT_PER_DST  N;
 ### EMAIL_LIMIT threshold.
 EMAIL_LIMIT_STATUS_MSG      Y;
 
+### This variable is used to have psad throttle the email alerts it sends,
+### and implemented as a per-IP threshold.  That is, if EMAIL_THROTTLE
+### is set to "10", then psad will only send 1/10th as many emails for each
+### scanning IP as it would have normally.  All other variables also apply,
+### so this throttle value is taken into account after everything else.  The
+### default of zero means to not apply any throttling.
+EMAIL_THROTTLE              0;
+
 ### If "Y", send email for all newly logged packets from the same
 ### source ip instead of just when a danger level increases.
 ALERT_ALL                   Y;