Welcome to part three of our series. As I promised in the previous article, now we will build an External Agent definition for an anti-virus product.

What will we need?
First of all, ORF of course (External Agents are supported since version 2.1), an external software which is capable of scanning a file from command line (I chose “McAfee VirusScan Command Line Scanner for Windows” for this demonstration, (you can download it from this page), and a test virus file we can use to test. For the latter, we will use the Eicar test file, which was created for testing anti-virus products (i.e. anti-virus products think it is a virus, but it is not, you can grab it here.

Getting Started
Let’s download the above mentioned files and extract the anti-virus product to an arbitrary directory. Read the documentation file of the anti-virus product, especially those sections which discuss the command line parameters and the exit codes, we will need those later on.

ORF Configuration
As I mentioned in the previous article, ORF creates a temporary copy of the email, which can be scanned by the external product. The temporary email file path should be configured in ORF (Configuration / Filtering – On Arrival / External Agents / Path for temporary email files). This could be any directory, but make sure it is excluded from antivirus filtering, otherwise it may delete the temporary file before ORF would scan it. Now, let’s create the agent definition:

Select Configuration / Filtering – On Arrival / External Agents in the left navigation pane of the ORF Administration Tool, and click New. The External Agent properties dialog will pop up. Let’s go through the different tabs:

Description tab
You can assign a name for the Agent so you can identify it later (e.g. “McAfee VirusScan”), and write some description for it.

Run tab
Agent executable: the path of the external executable should be set here, e.g. C:\Program Files\McAfee\scan.exe
Parameters: this is where we specify the parameters to be passed to the command line executable. The {EMAILFILESPEC} parameter is the variable pointing to the temporary file location. You should use this instead of the actual path of the file to be scanned (the temporary email copy ORF creates), because the file name differs for each email. For McAfee, we will use the following parameters:

/ALL (as we want to scan the file regardless of its extension)
/MIME (scan MIME encoded files)
/NOMEM (this will disable scanning the memory: we would like to restrict the scan for our temporary file only)
/SILENT (as the scan won’t be issued by a human being, there is no need to report anything back to ORF other than the exit codes)
/UNZIP (as we want to scan attached archive files as well)

So the parameter should look like this:

{EMAILFILESPEC} /ALL /MIME /NOMEM /SILENT /UNZIP

Timeout: the name speaks for itself – you can set how long ORF should wait for the response (return code) sent by the external software. If no response is returned within the specified time frame, the test will be simply skipped and ORF will proceed with the next external agent test (if there is any more).

Role tab
As we discussed in the previous article, there are two roles, which could be assigned to our External Agent: the Spam Filter Role should be selected if the agent is used for spam filtering (and whitelists should override the blacklisting it triggers), while the blacklisting triggered by an External Agent with Anti-Virus or Other Email Security Role can override whitelistings (if it is enabled in Configuration / Tests / Tests / Whitelist Test Exceptions). We will choose the latter in this case.

Logging tab
Check what should be recorded in the ORF text log (agent outpot on hit and/or error). Since version 4.3, you can also configure ORF to log the temporary file name.

Exit codes tab
Probably the most important setting: on this tab, you can set what the default action should be (e.g. tag the subject or reject the mail), and assign different actions for different exit codes. For the default action, I will choose “Accept email and perform further actions > Tag email subject with the text below: [VIRUS]” for now, because I want to test my agent first. Now let’s add some exit codes and assign different actions for them:

If you check the documentation of McAfee, you will find a list of exit codes and their meaning. For example exit code 13 means “virus found”, while exit code 6 indicates that “an error occured”. You should add all relevant exit codes and assign different categories for them (you would never guess: “Hit” for hit, and “Error” for error :), than you can assign different actions (e.g. perform the default action on hit, which is tagging the subject). You should not add those exit codes, which indicate the file is clean (unless you want to tag clean emails with a text as well).

I configured the following:

Exit codes 2,6,8,12,15,20,21,102: Error
Exit codes 13, 19: Hit

If everything is set, we can click OK on the External Agent dialog. Make sure you have the Agent enabled and you have the External Agent test enabled in Configuration / Tests / Tests. Now we can proceed with testing…which will be the next part of our series.