9. Integrations

Halon provides integrations with various security vendors, the embedded anti-spam and anti-virus engines are only available in the full system distribution (virtual machine) package. All connectors are available in the script library.

Context	Cyren IPrep	Cyren RPD	SophosAV	ClamAV	SpamAssassin	ScanDLP	rate
Connect	✓						✓
HELO	✓						✓
AUTH	✓						✓
MAIL FROM	✓						✓
RCPT TO	✓						✓
End-of-DATA	✓	✓	✓	✓	✓	✓	✓
Proxy	✓						✓
Disconnect	✓						✓
Pre-delivery	✓						✓
Post-delivery	✓						✓

9.1. Functions

integrations.globalview(ip)

Query the embedded Cyren IP reputation, ctipd.

Parameters: ip (string) – IP or IPv6 address to check
Returns: the recommended action to take for the ip accept, tempfail or permfail.
Return type: string

integrations.ScanRPD([options])

Scan the message using Cyren; anti-spam ctasd (RPD and LocalView) and zero-hour malware detection (VOD). It runs in either inbound or outbound mode, and it’s important to configure this correctly with the outbound option in order to detect spam properly and prevent false-positives and -negatives.

Parameters: options (array) – options array
Returns: score or refid
Return type: number, string or array

The following options are available in the options array.

refid (boolean) Return RefID (used to report FN and FP). The default is false.

outbound (boolean) Use RPD in outbound mode. The default is false.

extended_result (boolean) Return extended results. The default is false.

senderip (string) Change the value of the X-CTCH-SenderIP header.

mailfrom (string) Change the value of the X-CTCH-MailFrom header.

senderid (string) Set the value of the X-CTCH-SenderID header (only for outbound).

rcptcount (number) Set the value of the X-CTCH-RcptCount header (only for outbound).

The following results are available in the extended results array.

refid (string) The refid

rules (array) The LocalView spam rules matched

spam_score (number) The spam score

spam_class (string) The spam class

virus_score (number) The virus score (VOD)

virus_class (string) The virus class (VOD)

viruses (array) List of Cyren AV viruses found (requires an additional license)

On error the following items are available.

error (boolean) Indicates if there was an error during the scanning

RPD’s anti-spam classification scores and class names

Score	Class	Description
0	non-spam, unknown	Unknown
10	suspect	Suspect
40	valid-bulk	Valid bulk
50	bulk	Bulk
100	spam	Spam

RPD’s anti-virus (VOD) classification scores and class names

Score	Class	Description
0	non-virus, unknown	Unknown
50	medium	Medium probability
100	virus, high	High probability

integrations.ScanSA([options])

Scan the message using SpamAssassin.

Parameters: options (array) – options array
Returns: score or rules
Return type: number or array

The following options are available in the options array.

rules (boolean) Return rules in an associative array with scores. The default is false.

extended_result (boolean) Return extended results. The default is false.

sender (string) Change the value of the X-Envelope-From header. The default is the sender address.

The following results are available in the extended results array.

rules (array) The rules matched

scantime (number) The actual scan time in seconds (excluding waiting time)

On error the following items are available.

error (boolean) Indicates if there was an error during the scanning

scantime (number) The actual scan time in seconds (excluding waiting time)

Builtin rules	Score	Description
NOT_SCANNED_TOO_BIG	0	Message was to big too big to be scanned
NOT_SCANNED_QUEUE_TOO_LONG	0	Queue was too long to SpamAssassin

Note

A score of 5 or higher is what most people accept to be considered spam.

integrations.ScanKAV([options])

Scan the message using the Sophos anti-virus.

Parameters: options (array) – options array
Returns: any viruses found
Return type: array

The following options are available in the options array.

extended_result (boolean) Return extended results. The default is false.

The following results are available in the extended results array.

rules (array) The rules matched

result (array) The result code (number) and text (string) from Sophos (if available)

On error the following items are available.

error (boolean) Indicates if there was an error during the scanning

result (array) The result code (number) and text (string) from Sophos (if available)

integrations.ScanCLAM([options])

Scan the message using ClamAV anti-virus.

Parameters: options (array) – options array
Returns: any viruses found (only one result)
Return type: array

The following options are available in the options array.

extended_result (boolean) Return extended results. The default is false.

The following results are available in the extended results array.

rules (array) The rules matched

On error the following items are available.

error (boolean) Indicates if there was an error during the scanning

Warning

The ClamAV engine uses stop on first match. So whitelist matches based on the result with care since it can consequently allow messages with multiple viruses through.

integrations.ScanDLP([patterns[, options]])

Scan a message using the builtin DLP engine.

Parameters

patterns (array) – array of pre-configured rules or an array of custom rules
options (array) – options array

Returns

all patterns found (may include ERR_ rules even if not explicitly given in the patterns argument)

Return type

array

The following options are available in the options array.

stop_on_match (boolean) processing the mail when one match (of the requested type) is found. The default is false.

timeout (number) set an approximate timeout time in seconds. The default in no timeout.

recursion_limit (number) how deep to dig through MIME trees, archive files (such as ZIP), etc. The default is 9.

partid (boolean) return a data structure with the partid where the pattern is found. The default is false.

extended_result (boolean) Return extended results. The default is false.

The following results are available in the extended results array.

rules (array) The rules matched

On error the following items are available.

error (boolean) Indicates if there was an error during the scanning

The patterns array may either be an array of pre-configured rules by name.

["RULE1", "RULE2", ...]

Or a custom rule with the patterns provided. A custom rule may contain multiple types (eg. filename, sha1hash etc.) with multiple patterns each. The available types may be extracted from the DLP configuration.

["RULE1" => ["filename" => ["/\\.exe$/i", "/\\.zip$/i"], "sha1hash" => ["..."]], ...]

Warning

Do not allow untrusted users to add custom regular expression, since not all regular expressions are safe. All user data should be escaped using pcre_quote() before compiled into a regular expression.

There are some builtin rules which may occur.

Builtin rules	Description
ERR_UNKNOWN_ERROR	An unknown error occurred (more details may be available in the log)
ERR_PASSWORD_PROTECTED	The archive is password protected
ERR_RECURSION_LIMIT	The archive is too nested

integrations.rate(namespace, entry, count, interval[, options])

Check or account for the rate of entry in namespace during the last interval. On error none is returned.

Parameters

namespace (string) – the namespace
entry (string) – an entry
count (number) – the count
interval (number) – the interval in seconds
options (array) – options array

Returns

if count is greater than zero, it will increase the rate and return true, or return false if the limit is exceeded. If count is zero 0, it will return the number of items during the last interval.

Return type

number or none

The following options are available in the options array.

sync (boolean) Synchronize the rate in between nodes in the cluster. The default is true.

if (rate("outbound", $saslusername, 3, 60) == false) {
      Reject("User is only allowed to send 3 messages per minute");
}

Note

Rates are shared between all contexts, and may also be synchronized in clusters.