MA: Create Custom Alert in CEF Format

This topic provides instructions for creating custom alerts in Common Event Format (CEF) to send to a service that ingests events as CEF.

This is an advanced configuration task, which requires sufficient knowledge to manually edit the configuration file: /var/lib/rsamalware/spectrum/conf/malwareCEFDictionaryConfiguration.xml. Before editing the file, you must stop the Malware Analysis service in the operating system. The CEF Alert becomes active when you restart the Malware Analysis service.

The CEF Template

To send events to a service ingesting events as CEF, Security Analytics runs them through a configuration file that serves as a CEF template before feeding the events to a correlation technology. You can tune the configuration file, which specifies the sequence and mapping of syslog fields in each alert.

The following example syslog message shows the new CEF fields in the extensions section of the alert (following the last '|' in the alert). Each field can be configured to indicate the sequence (described in the Example section below). Fields can be excluded entirely from the alert via a configuration setting.

Example

The configuration file can be used to dictate which fields appear in the resulting alert as well as the label associated with each field and the order in which the data fields appear. The configuration file is comprised of one or more XML MalwareCefExtension blocks as shown in the example below. The ordering of these blocks in the configuration file implies the order of the data fields in the CEF alert.

In the example below, the CEF alert would include two data fields, ip.src followed by ip.dst. The customKey is used to indicate the labeling of the data field in the alert. This allows the user to choose a custom label in order to force the alerting format to better match the expectations of the alert consumer. In other words, the format can be tuned to prevent unwanted changes to an existing alert parser. Lastly, the isDisplay setting determines if the field is included in the alert output. This allows the user to turn off data fields without having to physically delete the MalwareCefExtension block from the configuration.

<config>

<malwareExtensionList>

<com.netwitness.malware.core.cef.MalwareCefExtension>

<customKey>ip.src</customKey>

<malwareKey>ip.src</malwareKey>

<isDisplay>true</isDisplay>

</com.netwitness.malware.core.cef.MalwareCefExtension>

<com.netwitness.malware.core.cef.MalwareCefExtension>

<customKey>ip.dst</customKey>

<malwareKey>ip.dst</malwareKey>

<isDisplay>true</isDisplay>

</com.netwitness.malware.core.cef.MalwareCefExtension>

</malwareExtensionList>

</config>

At the end of the configuration file are three additional settings that can be used to further tune the alert format. They are as follows:

Setting

Description

includesUnknownMeta

This true or false setting indicates if unknown data elements are included in the resulting alert. Any NextGen session meta can be considered for inclusion into a CEF alert.

Because additional session meta can be introduced via authoring new NextGen parsers, meta that is not contained in the default configuration may be encountered. You can set includesUnknownMeta to true to include the unknown meta in the alert and label it using the NextGen meta key name. To force a custom key for the unknown meta, you must edit this file and add a new MalwareCefExtension to the dictionary.

To omit unknown meta from the alert, set includesUnknownMeta to false.

displayNulls

This true or false setting indicates if values that are set to null are included in the alert. If displayNulls is set to false, the null value fields are omitted even if their MalwareCefExtension isDisplay property is turned on. This allows dynamic formatting of alerts to exclude null fields.

valueIfNull

This true or false setting allows you to specify a string placeholder (n/a by default) to be used as the value for any null valued fields. If displayNulls is set to true, then null valued fields are included in the alerts. Their value is set to the value specified in valueIfNull.

The following represents the default CEF configuration file. The default configuration file includes all default NextGen session meta.