Add a Data Enrichment Source

This topic tells how to add a previously configured enrichment source to a rule. When ESA creates an alert, information from the source gets included in it.

Enrichments provide the ability to include contextual information into correlation logic and alert output. Without enrichments, all information included in an ESA alert is from a Core service. With enrichments, you can request for look ups into a variety of sources and include the results into the outgoing alerts. The following figure illustrates the enrichment feature.

netwitness_enrichment_overview_576x200.png


Enrichment configuration is made up of two logical units:

  • Enrichment Sources – These are data stores of contextual information.
  • Enrichment Connections – These act as connectors between alert meta and source columns.

ESA allows you to make connections between Event Processing Language (EPL) statements and enrichment sources. Once the connections are established, the system joins the selected fields from the alert output with the information in the sources and uses the matching data to enrich the alert that is sent out. ESA can connect with the following sources:

  • Esper Named Windows
  • MaxMindGeoIP Database

Note: The geoIP enrichment source can neither be created nor deleted. It is provided out of the box to the user.

Example Rule with Enrichments

The following example rule illustrates how ESA enrichments can enhance alerts.

@RSAAlert @Name("simple") SELECT * FROM Event(ec_theme='Login Failure')

This rule generates an alert for every logon failure and thus if the following (simplified) event stream is received at ESA:

sessionidec_themeusernameip_srcip_dsthost_dst
1Login Successdshrute23.xx.23x.16
2Login Failurejhalpert23.xx.23x.1631.1x.x9.1x8www.facebook.com

An alert without an enrichment with the following constituent events might be generated in response to the second session:

{
"events": [
{
"username": "jhalpert",
"host_dst": "www.facebook.com",
"ip_dst": "31.1x.x9.1x8",
"sessionid": 2,
"ec_theme": "Login Failure",
"esa_time": 1406148964130,
"ip_src": "23.xx.23x.16"
}
]
}

The JSON output shows all the information available for inclusion into an ESA notification using an appropriate FreeMarker template. For instance, the template expression ${events[0].username} would evalute to jhalpert.

With enrichments, the same deployment, with the same event stream, can generate the alert shown below.

{"events": [
{
"username": "jhalpert",
"host_dst": "www.facebook.com",
"GeoIpLookup": [
{
"city": "Cambridge",
"longitude": -71,
"countryCode": "US",
"areaCode": 617,
"metroCode": 506,
"region": "MA",
"dmaCode": 506,
"ipv4Obj": "/23.xx.23x.16",
"countryName": "United States",
"postalCode": "02142",
"ipv4": "23.xx.23x.16",
"latitude": 42,
"organization": "Verizon Business"
}
],
"orgchart": [
{
"supervisor": "mscott",
"name": "James Halpert",
"extension": 3692,
"location": "Scranton",
"department": "Sales",
"id": "jhalpert"
}
],
"ip_dst": "31.1x.x9.1x8",
"sessionid": 2,
"LoginRegister": [
{
"username": "dshrute",
"ip_src": "23.xx.23x.16"
}
],
"ec_theme": "Login Failure",
"esa_time": 1406155218912,
"ip_src": "23.xx.23x.16"
}
]}

The system pulls contextual data to make the alert more meaningful.

To include the name of the supervisor and the name of the user with the last successful login in the ESA notification, this example includes the following template expressions:
${events[0]["orgchart"][0].supervisor} gives the name of the supervisor of the employee in the alert and ${events[0]["LoginRegister"][0].username} gives the name of the user with the last successful logon from the same ip_src (using a stream based Named Window).