Running External Process

Xeams allow spawning external processes when a new email is received. This is a two-step process:

• First, you need to create a special file in XML format containing the process you need to run. See below for details
• Second, modify the Profile_XXX.xml file in $INSTALL_DIR\config folder and enable a custom filter.

Step 1 - Adding XML file

• Create a new text file called ExternalTool.xml in $INSTALL_DIR\config folder.
• A sample file is pasted below. This sample spawn Microsoft Defender whenever an email is received with attachments. The goal in this example is to let Microsoft Defender look for viruses in the message. If a virus is found, Xeams will parse the text printed to Standard output by Microsoft Defender and will assign a score.

<?xml version="1.0" encoding="UTF-8"?>
<ExternalTools>
	<ToolSet>
		<oneTool>
			<path>C:\Program Files\Windows Defender\MpCmdRun.exe</path>
			<!-- 
			The condition parameter is used to specify when to trigger the executable. It takes following values:
			0 - all the time (default)
			1 - only if files are attached 
			-->
			<condition>1</condition>
			<!-- A score is assigned if the exit code equals one of the following values.
			More than 1 number can be separated by a comma
			-->
			<exitCode>0</exitCode>
			
			<!-- 
			Contains a regular expression that is searched in standard output/error of the process. A
			score is assigned if a match is found.
			-->
			<resultText><![CDATA[found [1-9][\d]* threats ]]></resultText>
			<parameters>
				<!--
				Specify command line parameters for the executable file, which takes following variables:
				
				$SINGLE_ATTACHMENT - Name of the attached file. 
				$ENTIRE_EMAIL - Name of the .eml file containing entire email				
				$SENDER - Email sender
				-->
				<oneParam>-Scan</oneParam>
				<oneParam>-ScanType</oneParam>
				<oneParam>3</oneParam>
				<oneParam>-File</oneParam>
				<oneParam>$SINGLE_ATTACHMENT</oneParam>
			</parameters>
		</oneTool>
		
	</ToolSet>

</ExternalTools>

Assigning Score

Xeams will assign a score to email in two conditions:

1. By parsing the exit code of the external process. This is done by specifying the exitCode parameter in ExternalTool.xml file.
2. By parsing the standard output

Step 2 - Modifying Profile_XXX.xml file

Adding a custom filter Profile_XXX.xml file with the following contents.

<customFilter>
	<className>com.synametrics.xeams.rulesengine.custom.ExternalTool</className>
	<weight>100</weight> <!-- assign a weight -->
	<enabled>true</enabled>
	<origin>1</origin>
	<lastModified>1066309746000</lastModified> <!-- represents the date this rule was added -->
</customFilter>