The SpamCheck API allows plugins to interact in a standardized way with anti-spam plugins. Thanks to the SpamCheck API Nucleus can request a spam check without knowing if an anti-spam plugin is installed or which anti-spam plugin is installed. The same thing applies to plugins, they can also call the SpamCheck API themselves if they want to request a spam check. One of the more prominent examples of a plugin calling the SpamCheck API is the NP_Trackback plugin.

In short, the SpamCheck API allows multiple anti-spam plugins to work together and offers support for many types of spam, such as comment spam, trackback spam and referer spam.

Version 2.0 of the SpamCheck API adds a number of features, such as marking false-positives and false-negatives. The specification of version 2 is also much stricter and now defines the data structures you should use.

The SpamCheck Api builds on Nucleus’ build-in event system. The plugin that requires a spam check simply creates a SpamCheck event and passes as simple data structure which contains the data that must be checked. After the check is finished the plugin simply checks the return value embedded in the data structure.

The anti-spam plugin listens to the SpamCheck event and every time such an event is created, the anti-spam plugin receives the data structure. The plugin will perform all of its tests based on the contents of the data structure. The result will be stored inside of the data structure after which the anti-spam plugin will give control back to the event system.

Example of calling the API:

$spamcheck = array (
    /* data structure */
);
 
$manager->notify('SpamCheck', array ('spamcheck' => & $spamcheck));
    
if (isset($spamcheck['result']) && $spamcheck['result'] == true) 
{
    /* this is spam */
}

The data structure is an array. The values of the array can vary between types of spam. In order to be able to identify between the different types of spam there is a required value with the key type. This value can contain any of the following values:

• comment
• referer
• trackback

It is possible to use values other than the ones defined above, but if you do you must realize that there is no guarantee that a spam check plugin will be able to use the data structure.

Apart from the type specific values there are also some generic values that apply to all types of spam.

• live
• return

live
The live value is a boolean and can be set to true or false. If this value is set to true, it means the check is called for an event that is happing in real time.

If live is set to true, the anti-spam plugin is allowed to use the values of the global $_SERVER and $_REQUEST arrays to retrieve any extra information. If live is set to false, the spam check is manually called by a user or administrator. This means that the $_SERVER and $_REQUEST arrays do not contain any information about a possible spam attempt, but information about the administrator. If set to false, the anti-spam plugin should never use these global arrays in it’s spam detection routines.

return
The return value is a boolean and can be set to true or false. If this value is set to true, it means the anti-spam plugin is not allowed to use any counter measures against the spam attack. Once it has determined we are dealing with a spam attack it should return control to the calling plugin.

If return is set to true the anti-spam plugin is allowed (but not required) to take any counter measure it wants, such as keeping the HTTP session alive. If return is set to true the anti-spam plugin does not need to return control back to the calling plugin.

If you want to check a comment for spam you should provide the following values in the data structure array:

• body
• name
• email
• url
• id

Example of the data structure:

$spamcheck = array (
    'type' => 'comment',
    'body' => 'This is a test comment',
    'author' => 'rakaz',
    'url' => 'http://www.rakaz.nl',
    'id' => 32,
    'live' => true,
    'return' => true
);

body
The body value is required and must contain a raw and unfiltered copy of the comment body. This means that any processing that Nucleus does before the PostAddComment event must be ignored.

Note: If you rely on the PostAddComment event you might run into a problem. You cannot use the $data parameter of the PostAddComment event, because it is already processed by Nucleus. You should use requestVar(’body’) instead which should contain the raw data provided by the comment form.

name
The name value is optional and should contain the name of the user who posted the comment.

email
The email value is optional and should contain the email address of the user who posted the comment. If the email address contains the mailto: protocol prefix, it should be removed before calling the SpamCheck API.

url
The url value is optional and should contain the URL provided by the user who posted the comment. The URL should not be relative and should start with either http:// or https://.

Note: The current version of Nucleus uses one field to provide either the email address or the url of the user who posted the comment. The plugin calling the SpamCheck API should determine what this combined field contains and use it to fill the appropriate value in the data structure.

id
The id value is optional and should contain the id of the article on which the user has commented.

If you want to check a trackback for spam you should provide the following values in the data structure array:

• title
• excerpt
• blogname
• url
• id

Example of the data structure:

$spamcheck = array (
    'type' => 'trackback',
    'title' => 'apuesta dinero',
    'excerpt' => 'In your free time, check the sites about ruleta',
    'blogname' => 'apuesta dinero',
    'url' => 'http://www.poker4spain.com/apuesta-dinero.html',
    'id' => 19,
    'live' => true,
    'return' => true
);

title
The title value is optional and corresponds directly with the title value defined in the Trackback specification.

excerpt
The excerpt value is required and corresponds directly with the excerpt value defined in the Trackback specification.

blogname
The blogname value is optional and corresponds directly with the blog_name value defined in the Trackback specification.

url
The url value is required and corresponds directly with the url value defined in the Trackback specification.

id
The id value is optional and should contain the id of the article. This value is also defined in the Trackback specification as tb_id.

Note: It is possible that the trackback is send using a character encoding that is different from the encoding used by your nucleus installation. If this is the case, the trackback data should be converted to the character encoding of your nucleus installation before checking for trackback spam.

If you want to check a referer for spam you should provide the following values in the data structure array:

• url
• id

Example of the data structure:

$spamcheck = array (
    'type' => 'referer',
    'url' => 'http://www.poker4spain.com/apuesta-dinero.html',
    'id' => 74,
    'live' => true,
    'return' => true
);

url
The url value is required and should contain the full URL that apparently was used to refer the visitor to your website. This value is usually present in the $_SERVER[’HTTP_REFERER’] global variable. Relative URLs are not allowed and URLs should always start with http:// or https://.

id
The id value is optional and should contain the id of the article on which the visitor entered the website.

If you want to maintain compatibility with older implementations of the SpamCheck API you can include one additional data value. This value contains all the other type specific fields concatenated to a single string.

For example:

$spamcheck = array (
    'type' => 'comment',
    'body' => 'This is a test comment',
    'author' => 'rakaz',
    'url' => 'http://www.rakaz.nl',
    'id' => 32,
    'live' => true,
    'return' => true,
    'data' => 'rakaz This is a test comment http://www.rakaz.nl'
);

result
If return is set to true, the anti-spam plugin is expected to give the verdict back to the calling plugin. The anti-spam plugin should add a new value to the data structure called result.

This value is a boolean and can be true or false. If the value is true the anti-spam plugin thinks it is spam. If the anti-spam plugin thinks the comment, trackback or referer is normal, it will set result to false.

Note: It is possible to install more than one anti-spam plugin. Every anti-spam plugin will be called in the order that they were installed. This also means that it is possible the result is already set by another anti-plugin.

If this is the case you should follow the following rules:

• If the result is false, you must run your own test. If your own test indicates that we are dealing with spam you should overwrite the result with true.
• If the result is false, you must run your own test. If your own test does not indicate that we are dealing with spam you should simply leave result to false.
• If the result is true, you can run your own test, but if you test indicates that we are not dealing with spam, you should NEVER overwrite the existing value of result. Another plugin already marked this as spam and you should honour that.
• If the result is true, you could simply skip any tests of your own because another plugin already marked this as spam.

In addition to this, if the anti-spam plugin marks this comment, trackback or referer as spam, the anti-spam plugin should also add it’s own name and a status message to the data structure. This way other plugins could use this information to show why the comment was marked as spam.

plugin
The plugin value contains the name of the plugin. This is usually equal to the the return value of the getName() function of the plugin. This value should only be set when the comment, trackback or referer is marked as spam.

message
The message value contains some additional information about the reason why the comment was marked as spam. This message should not be more than 255 characters and may be translated into the language of the Nucleus installation.

Examples of messages are:
- Score 66 out of 100
- Contains spamvertised URL according to Rbl.bulkfeeds.jp

Some anti-spam plugins have the ability to learn and improve their spam detection. To make this possible we have an event that can tell anti-spam plugins about their mistakes.

For example, if the anti-spam plugin failed to detect a comment as spam you can use the SpamMark event to tell the plugin it is spam. The term for these kinds of mistakes is false-negatives. The other way around is also possible. If you anti-spam plugin marked a normal comment as spam you can use the SpamMark event to tell the plugin it is not spam. The term for these kinds of mistakes are false-positives.

Note: The SpamMark event is optional for both calling plugins as anti-spam plugins. However, if you do implement it, you should implement it in the way described in this specification.

Example of calling the API:

$spammark = array (
    /* data structure */
);
 
$manager->notify('SpamMark', array ('spammark' => & $spammark));

The data structure is similar to the datastructure of the SpamCheck event. The differences are explained below.

The generic values live and return are not valid in the SpamMark data structure. Instead, the anti-spam plugin should always return control back to the plugin initiating the SpamMark event.

There is one new generic value called result. This value should contain a boolean that indicates what the SpamCheck event should have returned. If this value is true the comment, trackback or referer will be marked as being spam. If this value is false the comment, trackback or referer will be marked as a false-positive.