Describe provisional configuration and capabilities of the plugin: Maping from SNFServer result code to SA score, short-circuiting further processing, and effect of GBUdb scan on the SA score.

git-svn-id: https://svn.microneil.com/svn/PKG-SNF-CS-NIX/trunk@4 233e721a-07f6-49eb-a7da-05e0e16828fc

SNF_CS_Developer_Package.3.0.2_p4/SNF4SA/INSTALL

@@ -10,13 +10,102 @@ following steps:
 
   1) Copy snf4sa.pm and snf4sa.cf to /etc/mail/spamassassin .
 
-  2) Edit /etc/mail/spamassassin/snf4sa.cf to set the score to the
-  desired value.  Setting the score to "10" would result in email
-  detected as spam by SNFServer would be marked as spam by
-  SpamAssassin.
+  2) Edit /etc/mail/spamassassin/snf4sa.cf plugin configuration file
+  to meet your needs.  See below for a description of the
+  configuration settings.
 
 The module writes the email message to a temporary file in
 /tmp/snf4sa.  If this directory doesn't exist, the script creates it
 with permission 777.  This allows both the script and SNFServer to
 write to that directory.  If that directory already exists, ensure
 that it has a permission of 777.
+
+Plugin Configuation Settings
+----------------------------
+
+The plugin file (snf4sa.cf) contains required lines that:
+
+  1) Configures SpamAssassin to load the plugin.
+
+  2) Describes the plugin.
+
+  3) Configures SpamAssassin to add the X-Spam-SNF-Result header to
+  the email.  This header contains the results of the SNF scan.
+
+In addition, there are lines that can be configured by the user that
+specifies:
+
+  1) Which emails to process through SNFServer.
+
+  2) The relationship between SNFServer results and the SpamAssassin
+  score.  You can specify the value added to or subtracted from the
+  SpamAssasin score for each SNFServer result.  You can also specify
+  whether SpamAssasin should abort further processing for eacn
+  SNFServer result.
+
+  3) The relationship between the GBUdb results and the SpamAssassin
+  score.  The GBUdb probability p and confidence c add the following
+  value to the SpamAssasin score:
+
+    (p * c) ^ 2 * sign(p) * MaxWeight
+
+  where sign(p) is -1 if p < 0, and +1 otherwise, and MaxWeight is
+  specified on a configuration line.  MaxWeight is greater than or
+  equal to zero.
+
+To specify which emails to process, use a line similar to:
+
+  full SNF4SA eval:snf4sa_sacheck()
+
+The above line specifies that all emails be processed.  Please see the
+SpamAssassin documentation for other options.
+
+To specify the relationship between the SNFServer results and the
+SpamAssassin score, enter zero or more lines with the format:
+
+  snf_result: NN sa_score: S short_circuit: YES_OR_NO
+
+where NN specifies the SNFServer result, and S is the SpamAssassin
+score for that SNFServer result.  YES_OR_NO is "yes" if further
+scanning should be skipped if SNFServer returns the result specified
+by NN, or "no" if further scanning should not be skipped.  NN can be a
+combination of a series of one or more integers, and a range of
+integers specified by N-M, where N and M are integers.  The
+"short_circuit: YES_OR_NO" is optional, and the default value for
+YES_OR_NO is "no" (which specifies that SpamAssasin continue
+scanning).
+
+For example:
+
+  snf_result: 63 sa_score: 2.5 short_circuit: no
+
+causes the plugin to add 2.5 to the SpamAssassin score if SNFServer
+returns 63 (which in the default SNFServer configuration corresponds
+to "caution").
+
+Another example:
+
+  snf_result: 45 47-62 sa_score: 5.0 short_circuit: yes
+
+causes the plugin to add 5.0 to the SpamAssassin score and stop
+further processing if SNFServer returns 45 or 47 thru 62.
+
+Final example:
+
+  snf_result: 1 sa_score: -5.0
+
+causes the plugin to subtract 5.0 from the SpamAssassin score.
+SpamAssassin continues to process the email.
+
+If SNFServer returns a result that isn't specified, then the plugin
+adds zero to the SpamAssassin score.
+
+The following line specifies the MaxWeight parameter:
+
+  GBUdb_max_weight: MaxWeight
+
+where MaxWeight is the value to specify.  For example,
+
+  GBUdb_max_weight: 3.0
+
+specifies a MaxWeight value of 3.0.

SNF_CS_Developer_Package.3.0.2_p4/SNF4SA/README

@@ -8,7 +8,35 @@
 This directory contains the SpamAssassin plugin for SNFServer.
 
 The plugin implements a rule that checks the email message with
-SNFServer.  If SNFServer determines that the email message is spam,
-then SpamAssassin adds to the email score.
+SNFServer.
+
+If SNFServer determines that the email message is spam, then
+SpamAssassin increments the score by an amount that depends on the
+SNFServer result.  The amount to add for each SNFServer result is
+specified in the configuration file.
+
+The GBUdb scan result also changes the score by:
+
+  (p * c) ^ 2 * sign(p) * MaxWeight
+
+where p is the probability and c is the confidence returned by the
+GBUdb scan, sign(p) is -1 if p < 0 and +1 otherwise, and MaxWeight is
+specified in the configuration file.  If SNFServer is not configured
+to insert the GBUdb scan results into a header in the message, then
+the SpamAssassin score is not affected by the GBUdb scan results.
+
+In addition to scanning the message, the plugin inserts headers into
+the email.  The SNFServer must be configured to insert the headers
+into the email message.  The following headers are copied by the
+plugin into the message if SNFServer is configured to generate them:
+
+  1) 'X-SPAM-MessageSniffer-Scan-Result' contains the body of the
+  X-MessageSniffer-Scan-Result header inserted by SNFServer.
+
+  2) 'X-SPAM-MessageSniffer-Rules' contains the body of the
+  X-MessageSniffer-Rules header inserted by SNFServer.
+
+  3) 'X-SPAM-GBUdb-Analysis' contains the body of the X-GBUdb-Analysis
+  header inserted by SNFServer.
 
 Please see the INSTALL file for installation and configuration.