Custom Email Notifications with ArcSight ESM

Email notifications from your SIEM can be very useful especially if you have a small team.  The default in ArcSight ESM is to dump every event field into an email.   While better than nothing, the format is hard to read and forces you to search for the information you need to work the event.  Enter custom notification templates. Disclaimer:  This works as of ESM 4.5.  I have not tested it on ESM 5.0.  Would love to hear your experiences!

There are a few of moving parts and I'll go through each below.

  • Rule Actions- You need at least two rule actions.  See screen shot below for an example.
    • Send Notification - Set AckRequired as you wish.   The NotificationMessage is what will ultimately be the subject line of the email.  Resource is where you pick what group of users the email will go to.  This will have to be a group.
    • Set Event Field Actions - This is the secret sauce.  You can technically pick any field name.  I typically use one of the flexString fields to avoid a conflict of that field being used in some other way.  For agentSeverity, it really is up to you and does not affect the email.

  • Notification conf file - This file is in $ARCSIGHT_HOME/config/notification/ and named Email.vm and has logic to help it decide which template to use when sending the notification.  In a clean install of ESM, it only has one option, the default template I mentioned at the top of the post.  It makes decisions based on a particular field.  In this example, it is the flexString1 field shown in the screen shot above and code snippet below.  The decision works from top to bottom using Velocity, so make sure any custom entries are above the default entry.  Add an entry like the one below to the file for each custom template you have.  The #parse field will be the name of the Notification Template File described in the next section.
#if($introspector.getDisplayValue($event, "flexString1") == "malware")
#parse ("Custom-Email-Malware.vm")
#end
  • Notification Template File - This is the file that will literally be a template for the body of the email.  Remember the subject line of the email is set in the Rule Action.    For this example, the template file name is "Custom-Email-Malware.vm".  The file format again uses Velocity and is pretty straight-forward once you have seen one.  See example below.
Description: $introspector.getDisplayValue($event, "name")
Event Time:  $introspector.getDisplayValue($event,"endTime")
--------------------------------------------------------------

User Name:  $introspector.getDisplayValue($event,"sourceUserName") 
IP Address: $introspector.getDisplayValue($event,"sourceAddress") 
Host Name:  $introspector.getDisplayValue($event,"sourceHostName")
Location:   $introspector.getDisplayValue($event,"sourceZoneName")

Target Port: $introspector.getDisplayValue($event,"targetPort")
Event Count: $introspector.getDisplayValue($event,"baseEventCount")

Extra Information (where applicable)
---------------------------------------------------------------
$introspector.getDisplayValue($event,"message")

Description of Event
---------------------------------------------------------------
This computer appears to be infected with malware 

Why this is Important
---------------------------------------------------------------
Malware can take complete control of a computer remotely.

Next Steps
--------------------------------------------------------------
Start the malware infected procedure on this computer.

Note all the field names in both the config file and template file start with a lowercase letter, have no spaces, and each word is capitalized except the first one.  This can bite you if you are not careful.

Good luck!  If you have questions, comments, or suggestions, please leave comments below and I'd be glad to help.