NAME

pmx-spam - Interface to the PureMessage anti-spam component


SYNOPSIS

 pmx-spam <command> [options]


DESCRIPTION

The pmx-spam program is used to view and set weights for anti-spam rules. pmx-spam can be used to scan individual messages and display the matching rules.

Rule tests are defined in the *.rules files located in the /opt/pmx6/etc/data/antispam directory. Customer-specific overrides or new rules can be found in the /opt/pmx6/etc/spam.d directory.

The anti-spam engine in PureMessage uses 'features' and 'weights', two separate attributes of message scanning.

  1. Features

    A ``feature'' is a characteristic of a message. If a message has a feature, it is similar in some way to other messages that have the same feature. Similarly, a message without a particular feature is different from a message with that feature.

    The presence of a feature in a message is determined by testing components of the message against regular expressions defined in /opt/pmx6/etc/data/antispam/re.rules. Custom features can be defined in the file /opt/pmx6/etc/spam.d/re.rules.

  2. Weights

    Each feature has an associated ``weight''. A feature's weight expresses the likelihood that a message containing that feature is spam. The higher the weight, the more likely the presence of the feature is indicative of spam. Conversely, negative weights express the likelihood that a message is not spam; the lower the negative number, the more likely that the message is not spam.

    Weights can be expressed as either numerical values or 'probability deltas' (percentages). Weights for custom rules are configured using the pmx-spam weights --set or the pmx-spam pdeltas --set command, as described below. Weights for custom rules are deleted using the pmx-spam weights --del or the pmx-spam pdeltas --del command. (In previous versions of PureMessage, weights were referred to as ``scores'', and were defined in the same files as rules: spam-tests.conf and site-spam-tests.conf.)

    If both a weight and a probability delta are assigned to a feature, both values are used when messages are scanned for spam. The weight is first converted to a probability, then the value of the probability delta is added to determine the total score.


COMMANDS

The following sub-commands are recognized by pmx-spam:

weights
The weights command is used to view or alter the weight associated with a feature. To view all features and their assigned weights, enter:
   pmx-spam weights

The weights command recognizes the following options:

   pmx-spam weights --sort name
   pmx-spam weights --sort value
   pmx-spam weights --sort name --ascending
   pmx-spam weights --sort name --descending
   pmx-spam weights --trim 0.5
   pmx-spam weights --set NAME VALUE
   pmx-spam weights --del NAME

For example:

   pmx-spam weights --sort name --descending

By default, the display is sorted by value, in descending order. To sort the display alphabetically by feature name, or to sort by ascending value, use the --sort option:

   pmx-spam weights --sort name
   pmx-spam weights --sort value

To reverse the order, use the --ascending and --descending flags. Sorting by name defaults to ascending; sorting by value defaults to descending.

To view weights greater than or equal to a specified threshold, use the --trim option. Specify a numeric threshold, up to three decimal places. If no threshold is specified, the default is 0.001.

Note: The --trim option returns the absolute values of all matching results. Therefore, some results may be in the form of negative numbers.

To modify a weight, specify its name and a new value:

   pmx-spam weights --set <name> <value>

For example, to set the ACCOUNT_CLICK feature's weight to 0.5, enter:

   pmx-spam weights --set ACCOUNT_CLICK 0.5

To delete a weight, use the --del switch.

   pmx-spam weights --del <name>

For example:

   pmx-spam weights --del MY_RULE

The --set and --del options cannot be used simultaneously.

pdeltas
The pdeltas command is used to view or alter the probability delta (percentage) associated with a feature. To view all features and their assigned probability deltas, enter:
   pmx-spam pdeltas

The pdeltas command has the same arguments as the weights command:

   pmx-spam pdeltas --sort name
   pmx-spam pdeltas --sort value
   pmx-spam pdeltas --sort name --ascending
   pmx-spam pdeltas --sort name --descending
   pmx-spam pdeltas --trim 0.5
   pmx-spam pdeltas --set NAME VALUE
   pmx-spam pdeltas --del NAME

By default, the display is sorted by value, in descending order. To sort the display alphabetically by feature name, or to sort by ascending value, use the --sort option:

   pmx-spam pdeltas --sort name
   pmx-spam pdeltas --sort value

To reverse the order, use the --ascending and --descending flags. Sorting by name defaults to ascending; sorting by value defaults to descending.

To modify a pdelta, specify its name and a new value:

   pmx-spam pdeltas --set <name> <value>

For example, to set the ACCOUNT_CLICK feature's pdelta to 5%, use this command:

   pmx-spam pdeltas --set ACCOUNT_CLICK 0.05

To delete a feature's pdelta value, use the --del switch.

   pmx-spam pdeltas --del <name>

For example:

  pmx-spam pdeltas --del MY_RULE

The --set and --del options cannot be used simultaneously.

groups
The groups command is used to view the Feature Groups defined by the anti-spam heuristics currently installed. A group can be enabled or disabled by modifying the appropriate file in /opt/pmx6/etc/spam.d/groups.d/.

scan
The scan command is used to test the anti-spam rule set against one or more messages. The command will display a list of the spam features identified in the message, and will calculate the message's total spam score.

To scan a single message, enter the following command:

   pmx-spam scan /tmp/file

If the first line of the file matches the regular expression /^From /, the file is parsed as a UNIX mbox file; otherwise, the entire file is considered to be a single message.

To scan every file in a directory, simply specify the directory:

   pmx-spam scan /tmp/maildir

Each file in the directory is parsed as if it were specified individually.


COPYRIGHT

Copyright (C) 2000-2011 Sophos Limited. All rights reserved. Sophos and PureMessage are trademarks of Sophos Limited.

Regular expression support is provided by a modified version of the PCRE library package (see http://www.pcre.org), which is open source software, written by Philip Hazel. Copyright (c) 1997-2003 University of Cambridge.