Configure Custom Respond Server Alert Normalization

Note: This procedure is optional. Administrators can use it to change Respond Server alert normalization.

Analysts who are content experts can create ESA Correlation rules that generate alerts. When a rule is more complex than what can be specified in the ESA Rule Builder, they can write advanced Event Process Language (EPL) rules. After the ESA rules are deployed and the alert criteria is met, ESA Correlation-server forwards the raw alerts to Respond-server.

The schema, meta key selection, and event pattern of the raw alerts are unknown to the Respond-server since they depend on the way the ESA rules are written. In this case, you can customize the logic to parse the raw alert to an acceptable format. The parsing (normalization) logic is written in JavaScript language and NetWitness users who know how to write JavaScript code can customize the Respond normalization script files.

In NetWitness version 11.4 and later, to prevent overwriting future customizations in the Respond normalization scripts, add any custom logic to the custom_normalize_<alert type>.js files. The custom normalization script files have a custom_normalize prefix and are located in the /var/lib/netwitness/respond-server/scripts directory:

data_privacy_map.js
custom_normalize_alerts.js
custom_normalize_core_alerts.js
custom_normalize_ecat_alerts.js
custom_normalize_ma_alerts.js
custom_normalize_ueba_alerts.js
custom_normalize_wtd_alerts.js
utils.js

For Example, the custom_normalize_core_alerts.js is the normalization script used to add custom logic for ESA alerts. This JavaScript file has a normalizeAlert function with the parameters headers, rawAlert, and normalizedAlert. The normalized variable is an immutable copy object which has an embedded object with a list of normalized events. So if you have any custom meta keys configured for the events then you have to iterate through the normalized.events to populate the appropriate meta keys with values from the rawAlert.events object. The following figure shows sample code.

Copy

Sample Custom Normalize Core Alerts Code

normalizeAlert = function (headers, rawAlert, normalizedAlert) {
// normalizedAlert is the immutable copy of ootb normalizer alert, make sure you use
// normalized object to update/set the values in your scripts
var normalized = Object.assign(normalizedAlert);
var custom_events;
if(normalized.events !== undefined) {
custom_events = normalized.events;

} else {
custom_events = new Array([]);

}
for (var i = 0; i < rawAlert.events.length; i++) {
custom_events[i].legalentity=Utils.stringValue(rawAlert.events[i].isgs_legalentity);
custom_events[i].companycode=Utils.stringValue(rawAlert.events[i].isgs_companycode);

}

if(normalized.events === undefined){
normalized.events = custom_events;
}
return normalized;
};

To Configure Custom Respond Server Alert Normalization:

  1. Open the custom_normalize_core_alerts.js file.
Copy

custom_normalize_core_alerts.js

exports.normalizeAlert = function (headers, rawAlert, normalizedAlert) {

// normalizedAlert is the immutable copy of ootb normalizer alert, make sure you use
// normalized object to update/set the values in your scripts
var normalized = Object.assign(normalizedAlert);
// Add custom logic below
return normalized;
};

The normalizedAlert object has been broadcasted, which already comes through the basic parsing logic flow where some of the meta values have been copied to normalizedAlert from headers and rawAlert.

  1. Populate The normalizedAlert object with the custom meta values that are not covered in the basic parsing logic:
    1. Add your custom logic below the line: var normalized = Object.assign(normalizedAlert);

      The headers parameter has very few attributes like:

      headers.severity

      headers.deviceProduct

      The important parameter is rawAlert, which has an embedded events object, which is an array. It is basically the list of events associated with the alert. The events object has all meta keys governed from the Concentrator. Here are some example meta keys:

      event.user_dst

      event.user_src

      event.username

      event.domain_dst

      event.domain_src

      event.host_dst

      event.host_src

      event.analysis_session

      event.analysis_service

      event.analysis_file

      event.agent_id

      event.device_type

      event.category

      event.action

      event.user

      event.owner

      event.port_dst

      event.OS

      event.process_vid_src

      To view the look-up table for meta keys, go to netwitness_configureicon_24x21.png (Configure) > Esa Rules > Settings > Meta Key References.

      The normalized object also has an embedded events object, which is an array.

    2. Iterate through each item of the normalized.events and rawAlert.events and then copy the custom meta attributes from the rawAlert.events to the normalized.events.

The following example shows how to add custom meta keys to the custom_normalize_core_alerts.js file.

Copy

Example of Custom Alert Normalization

exports.normalizeAlert = function (headers, rawAlert, normalizedAlert) {
// normalizedAlert is the immutable copy of ootb normalizer alert, make sure you use
// normalized object to update/set the values in your scripts
var normalized = Object.assign(normalizedAlert);
var custom_events;
if (normalized.events != undefined)
{
custom_events = normalized.events;
}
else
{
custom_events = new Array();
}

// iterate through each item
for (var i = 0; i < rawAlert.events.length; i++)
{
custom_events[i].metaKey1=Utils.stringValue(rawAlert.events[i].rawCustomMetaKey1);
// Utils is a helper module to stringify the object
custom_events[i].metaKey2=Utils.stringValue(rawAlert.events[i].rawCustomMetaKey2);
}

If (normalized.events == undefined)
{
normalized.events = custom_events;
}
return normalized;
};

The metaKey1 and metaKey2 meta keys are now assigned meta keys, which you can view in the NetWitness user interface.

When customizing normalization script files, you can also look at the built-in Respond normalization script files for reference, such as normalize_alerts.js.