Overview
Sending a notification based on a critical or time-sensitive event seen in your environment is table stakes functionality for any detection platform. Alerting someone in a timely manner is important, but building a custom e-mail that includes relevant, concise information that an analyst can use to determine the appropriate response is just as important. As they work to juggle their daily priorities, they need to know whether an alert requires immediate attention or whether it's something they can filter as a false positive as time permits.
The RSA NetWitness Platform uses Apache FreeMarker template engine to build its notifications, be they e-mail, syslog, or SNMP. For the purposes of this post, I'm going to focus on e-mail notifications as the concepts apply to all notifications, and e-mail is the most complex of the options.
Available Data
The first step is finding out what information you can include in your notification. All of that data can be seen in the Raw Alert section of an Alert in the Respond UI. That Raw Alert is formatted in JSON, and anything in there can be placed into a notification. To find that Raw Alert data, you can go to one of two places.
Location #1:
Location #2:
Example #1: Basic Email
Let's start with a basic example. I want to send an e-mail that includes the name, severity, and time of the Alert, as well as a link to the raw event (network or log) that generated the alert. Here is a snippet of the data from my Raw Alert (the full alert, with addresses changed to protect the innocent, is attached as raw_alert.json):
Under Admin --> System --> Global Notifications, on the Template tab, I add a new template. Give it a name, choose the template type (we're going to select Event Stream Analysis for these), and then paste in the below code (also under example_1.html):
Assuming a severity of 9, that gives an e-mail formatted like this (using Gmail):
Rows 1 - 20 give us a color-coded banner which highlights the severity of the incident. In rows 3 - 6, you can see that we're making a logical check for the severity to determine the background color of the banner. Row 22 (we'll come back to row 21) prints the rule name. Row 23 gives us the time and includes the field, the input format, and the output format. You can even take epoch time and adjust it for your local time zone, but that's another post. Row 25 builds a hyperlink to the raw event that generated the Alert. Keep in mind that by default, notifications will separate large numbers with commas, which is why row 21 is necessary. Without row 21, the notification link (which I highlighted in the e-mail screenshot) would include commas in the sessionid within the URL, which would obviously not work when clicked. Also, you will need to update two portions of the URL specific to your environment:
The [URL_or_IP] is self-explanatory. The [Device_ID] is different for every environment and for every service. If you login to the RSA NetWitness Platform and navigate to the Investigate --> Navigate page and load values, the Device ID will be in the URL string in your browser, and it will correspond to the data source you've selected. In this example, my Broker has a Device ID of 6.
Above, we used https://[URL_or_IP]/investigation/[Device_ID]/reconstruction/[Session_ID]/AUTO. This loads the "Default Session View" that each individual user defined in their Profile --> Preferences --> Investigation settings, which by default is "Best Reconstruction" view for network sessions and the "Raw Log" view for log events. Should you prefer to jump directly to other views, you can use these formats:
- Meta View: https://[URL_or_IP]/investigation/[Device_ID]/reconstruction/[Session_ID]/DETAILS
- Text View: https://[URL_or_IP]/investigation/[Device_ID]/reconstruction/[Session_ID]/TEXT
- Hex View: https://[URL_or_IP]/investigation/[Device_ID]/reconstruction/[Session_ID]/HEX
- Packets View: https://[URL_or_IP]/investigation/[Device_ID]/reconstruction/[Session_ID]/PACKETS
- Web View: https://[URL_or_IP]/investigation/[Device_ID]/reconstruction/[Session_ID]/WEB
- Files View: https://[URL_or_IP]/investigation/[Device_ID]/reconstruction/[Session_ID]/FILES
Great! Now we have a notification.
Example #2: Multiple Values
But what if we have an array of values like analysis_service here:
In order to print those multiple values out, we need do some formatting with a FreeMarker macro. I'm pasting the following onto the bottom of my notification:
Lines 1 - 11 iterate through any meta value that has more than one value and separate them with a comma. Lines 13 - 22 print out Service Analysis with a comma-separated list of values. First, there is a logical test to see if there are any events in the first place. This was taken from the Default SMTP Template (Admin --> System --> Global Notifications --> Templates tab), and can be used to print out every meta key and all of their values. In my case, I altered it (or, well, Joshua Randall did and I stole borrowed it) to only apply to Service Analysis by adding a logical test (lines 16 and 19) and then only printing out that one meta key. Here is what that looks like:
If you would like to print out more than one key, you can add elseif statements like this:
Testing Your Syntax
So what if you want to use some FreeMarker concepts, but you want to see if they'll work before putting them into the RSA NetWitness Platform? Luckily, there is a tester put out by Apache here - https://try.freemarker.apache.org/.
In order to use it on your data, just copy that Raw Alert section from an Alert and paste it into the Data model box shown above. Then paste your FreeMarker code into the Template box and click Evaluate. Keep this in mind: this will not work the same as an RSA NetWitness Platform notification would. If I took the Raw Alert I used for my examples above along with the template I was using, I would not see the output I actually get from the RSA NetWitness Platform. This should ONLY be used to test some basic syntax concepts. For example, printing out UNIX Epoch Time in various formats, adjusted for different time zones, is something this helped me do.
Summary
These concepts - along with some basic HTML formatting - give you the tools to build just about any notification you would want. I also recommend taking a peek at the Default SMTP Template I referenced above to use as a starting point for more advanced formatting. If you do some other interesting things or need help getting a notification to work, please post that in the comments below.
3 Comments
