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.