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
orpermfail
.- 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) andtext
(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) andtext
(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 returnfalse
if the limit is exceeded. If count is zero0
, it will return the number of items during the lastinterval
.- 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.