Security ContentExabeam How Content Works Guide

Table of Contents

Exabeam Persistence and Templates

Persistence refers to saving the existence of a field which has been parsed/enriched in the Mongo database so that it can be used mainly by the Exabeam Advanced Analytics Restful Web Services for display purposes on the UI.

Persisting fields are mandatory for displaying fields associated with events on UI.

Persistence Definition

The default config for persistence can be found in the content_default.conf file (path: martini/config/default directory) under the sections RequiredPersistedEventFields and PersistedEventFields.

RequiredPersistedEventFields specifies the fields that need to be persisted for every event, while PersistedEventFields specifies for each event type the fields that need to be persisted to the database in addition to those listed under RequiredPersistedEventFields.

Persist a Field

If you want to persist a new field associated with an event on the UI, you need to add the new field entry in PersistedEventFields section. For example, if you want to persist a new field "vpn_source_location" associated with vpn-login event which you parsed/enriched, then it has to be added as shown below to PersistedEventFields.

Note

Make sure you define this config in the custom config file (/opt/exabeam/config/custom/custom_exabeam_config.conf), and not by changing the default file.

PersistedEventFields {
----------------------
----------------------
vpn-login = [_id,
  vendor,
  src_ip,
  src_host,
  "GetValue('country_code',src_ip)",
  "GetValue('isp',src_ip)",
  "GetValue('zone_info',dest)",
  src_translated_ip,
  dest_host,
  dest_ip,
  src_network_type,
  realm,
  os,
  vpn_source_location]
----------------------
----------------------
}

When to Use Persistence

You should use persistence to display fields associated with events on the UI.

Suppose you want to display a new field, say vpn_source_location associated with an event type vpn-login on the UI, you need to add the field in Event Template associated with vpn-login event.

Event Template

Event templates are used to display fields associated with an event in the UI. The below shows the event template VpnLoginTemplate, which is used for displaying fields associated with vpn-login in the UI. The below template is used to display fields such as time, user, account, src_ip, src_host, source, getvalue ('country_code', src_ip), getvalue('isp', src_ip), src_translated_ip, dest_host, dest_ip, vendor, realm, and os associated with vpn-login event on the UI.

VPN login event in a Smart Timeline.
VpnLoginTemplate {
    rows = [
        {        
        columns = [
            {
            label = "TIME"
            value = "time|event.time"
            },
            {
            label = "USER"
            value = "user|event.user"
            },
            {
            label = "ACCOUNT"
            value = "user|event.account"
            icon = "AccountSwitch"
            }
        ]
        },
        {
        columns = [
            {
            label = "SOURCE IP"
            value = "asset|event.src_ip"
            },
            {
            label = "SOURCE HOST"
            value = "asset|event.src_host"
            },
            {
            label = "SOURCE"
            value = "default|event.source"
            }
        ]
        },
        {
        columns = [
            {
            label = "COUNTRY"
            value = "location.country|event.getvalue('country_code', src_ip)"
            },
            {
            label = "ISP"
            value = "location.isp|event.getvalue('isp', src_ip)"
            },
            {
            label = "VPN ASSIGNED IP"
            value = "default|event.src_translated_ip"
            }
        ]
        },
        {
        columns = [
            {
            label = "VPN SERVER"
            value = "default|event.dest_host"
            },
            {
            label = "VPN SERVER IP"
            value = "default|event.dest_ip"
            }
        ]
        },
        {
        columns = [
            {
            label = "VPN VENDOR"
            value = "default|event.vendor"
            },
            {
            label = "VPN REALM"
            value = "default|event.realm"
            },
            {
            label = "OS"
            value = "default|event.os"
            }
        ]
        }
    ]
}

Event Templates Definition

The default config for event templates can be found in event_templates_default.conf file (path: tequila/conf/default/ directory). Every event type has an associated template defined and you can find the name of the associated template under the DetailsTemplate parameter entry in EventFormats.

Therefore, if you want the template defined for vpn-login event, you need to search for an entry for vpn-login in EventFormats. You will find the below entry, where the template name VpnLoginTemplate is associated with the DetailsTemplate parameter.

EventFormats {
  -------------------------
  -------------------------
  vpn-login {
    DisplayName = "VPN login"
    Description = "Remote access VPN login attempt either from a public IP address or from an internal network address was successful."
    HeaderTemplate = "VPN login from {location.country|event.getvalue('country_code', src_ip)}"
    DetailsTemplate = "VpnLoginTemplate"
  }
  -------------------------
  -------------------------
}

Then, you need to search for the template name VpnLoginTemplate entry, under Templates, to get the Event Template for vpn-login event as shown below:

Templates {
 -----------------------------
 -----------------------------
VpnLoginTemplate {
  rows = [
    {
      columns = [
        {
          label = "TIME"
          value = "time|event.time"
        },
        {
           label = "USER"
           value = "user|event.user"
        },
        {
           label = "ACCOUNT"
           value = "user|event.account"
           icon = "AccountSwitch"
        }
      ]
  },
  {
     columns = [
     {
        label = ------- 
        value = ------
     }
   ]
  },
  --------------------
  --------------------
}
----------------------
----------------------
}

Add a Field in an Event Template

Let's take an example of adding a new field named vpn_source_location associated with the vpn-login event in its event template. At first, you search for an entry vpn-login in EventFormats in the default config file and you will get an entry for vpn-login, where you then look for DetailsTemplate parameter to find the template name VpnLoginTemplate. Then, you search for VpnLoginTemplate entry under Templates to fetch the event template config as shown in Event Templates Definition.

Note

Make sure you define this config in the custom config file (/opt/exabeam/config/custom/custom_exabeam_config.conf), and not by changing the default file.

There can only be three columns (one field per column) with respect to each row for display purposes. So, if you want to add a new field entry, and there are already three subsections or fields under columns = [ section ], you cannot add a new entry in that particular row. In that case, you need to add a new columns = [ section ] and add an entry. Also, if you see there are only two subsections under columns = [ section ], then you can add your field under that section itself. Let's consider adding vpn_source_location field, and please refer to the below template which illustrates adding this entry into the template:

Templates {
 -----------------------------
 -----------------------------
VpnLoginTemplate {
  rows = [
    {
      columns = [
        {
          label = "TIME"
          value = "time|event.time"
        },
        {
           label = "USER"
           value = "user|event.user"
        },
        {
           label = "ACCOUNT"
           value = "user|event.account"
           icon = "AccountSwitch"
        }
      ]
  },
  --------------------
  --------------------
  {
      columns = [
        {
          label = "VPN SERVER"
          value = "default|event.dest_host"
        },
        {
          label = "VPN SERVER IP"
          value = "default|event.dest_ip"
        },
        {
          label = "VPN SRC LOCATION"
          value = "default|event.vpn_source_location"
        }
           ]
  },
  --------------------
  --------------------
}
----------------------
----------------------
}

As shown in the above case, vpn_source_location was added to columns = [ section ] in which only two entries existed, and which there was an option to add a third entry for a new field.

Please note that the parameter label defines the name of the field displayed on the UI and value parameter should contain the field for which you need the value to be displayed. Most importantly, the field which you want to display has to be persisted as described in the earlier section. If not, you will not be able to display the value for your field. In this case, vpn_source_location has to be persisted in Mongo, and then added to the template in order to display it with respect to the vpn-login event.

Custom Persistence and Templates

In addition to default config parameters. You can update an event template with a custom field by persisting it in MongoDB. Then you need to make changes as discussed below to custom files.

  • If it is persistence, and you want to persist custom field vpn_source_location in MongoDB, then add the below section in your custom config file (/opt/exabeam/config/custom/custom_exabeam_config.conf):

PersistedEventFields {
            vpn-login = [_id,
            vendor,
            src_ip,
            src_host,
            "GetValue('country_code',src_ip)",
            "GetValue('isp',src_ip)",
            "GetValue('zone_info',dest)",
            src_translated_ip,
            dest_host,
            dest_ip,
            src_network_type,
            realm,
            os,
            vpn_source_location]
          }

Note

Do not forget to enclose the entry with PersistedEventFields { } as shown above in the custom config file.

  • For event templates, and you want to display custom field (vpn_source_location) value on the UI, then add the below section in your custom config file (/opt/exabeam/config/tequila/custom/event_templates.conf):

Templates {
           VpnLoginTemplate {
          rows = [
          {
               columns = [
               {
                   label = "TIME"
                   value = "time|event.time"
               },
               {
                   label = "USER"
                   value = "user|event.user"
               },
               {
                   label = "ACCOUNT"
                   value = "user|event.account"
                   icon = "AccountSwitch"
               }
             ]
          },
          --------------------
          --------------------
          {
               columns = [
               { 
                   label = "VPN SERVER"
                   value = "default|event.dest_host"
               },
               {
                   label = "VPN SERVER IP"
                   value = "default|event.dest_ip"
               },
               {
                   label = "VPN SRC LOCATION"
                   value = "default|event.vpn_source_location"
               }
                  ]
          },
          --------------------
          --------------------
       }
     }

Note

Do not forget to enclose the entry with Templates { } as shown above in the custom config file.

Restart Services for Persistence and Templates

  • If you make any updates for persistence and you want to see if a new field value is persisted on MongoDB, you need to restart the analytics engine (exabeam-analytics-stop;exabeam-analytics-start).

  • If you make any updates for event templates and you want to see the changes on UI, you need to restart the web components (web-stop;web-start).

  • If you make updates for persistence and want them displayed on the UI, then you also make updates to event templates, you need to restart both the analytics engine as well as the web components.

Note

It is mandatory for a field to be persisted if it is required to display it on the UI using templates.