Configure Custom Respond Server Alert NormalizationConfigure 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:
- 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.
- Populate The normalizedAlert object with the custom meta values that are not covered in the basic parsing logic:
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
(Configure) > Esa Rules > Settings > Meta Key References.
The normalized object also has an embedded events object, which is an array.
- 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.
