There are two important structures that hold context during event processing, both of which are defined in `factory.js`:
assessment holds detailed information about the event, configuration, and results
test context holds detailed information about the execution of one specific alert.
The assessment structure is returned in response to every generated request. This feature allows for detailed examination of the results and is used extensively in auto-testing. The assessment structure can be enhanced any time as it does include all context pieces related to a processed event. For brevity, some details are stripped from the internal assessment structure before returning it in response: the original event, configurations, structures with generated alerts, list of REDIS operations. (v2alerts.js:okAnswer())
The following textbox shows, by example, what the assessment structure may look like. It is annotated and shortened at many places. The assessment was created using "cpc" auto test group, with session-tracking alerts enabled.
{
"msg": "suspicious event encountered", // human readable result
"assessment": {
"session_dbg": { // session info if a session-tracking alert is enabled
"GX71yin-cstm#attrs.dst_ca_id_472977624": { // key to which a session relates
"key": {
"type": "cstm",
"name": "cstm#attrs.dst_ca_id",
...
},
"session": { // actual session context
// line bellow: session ID (computed from call-id and tags for SIP)
"id": "689CAF98-E2F0-42F2-A475-30507F42E10C-581631089",
"type": "call-end",
"executeFunctionCall": true,
"counter": 1 // number of current sessions for the key
},
"status": "SESSOK_COMPLETED"
},
"hv71yin-cstm#attrs.src_ca_id_2116499352": { // another key for which sessions are tracked
...
},
"dbgenv": { // content of debugging variables -- these can emulate
// event timing, increased processing delay, etc.
"NOW": "1727965958",
"DISABLE_CACHE": "false",
"ANSWER_CONFIG": "false",
"DELAY": "0",
"selLogOn": false
},
"eventType": "call-start", // type of processing event
"tranformationCompleted": true, // flag indicating whether transformation function completed
"isTimer": false, // is this a timer event?
"profiles": { // profiles for all used keys
"cstm#attrs.src_ca_id_2116499352": { // profile ID (internal identified)
"IP": "plain#attrs.src_ca_id#public-SBC-public", // REDIS key for the profile
"domain": "ba86ac2a-7f13-44b3-ba77-4dc29e6f6305#customprofile", // domain id and type of data
// details specific to an alert in a "flattened" representation
// alert id "hv71yin", type "CSTPC"
"CSTPC_hv71yin.counter": 1,
"CSTPC_hv71yin.created": 1727965957,
"CSTPC_hv71yin.max": 1,
"CSTPC_hv71yin.lastModifiedTS": 1727965957,
"timestamp": 1727965957
},
...
},
"evilScore": 100, // highest of the by-key scores
"evilScoreByKey": { // score for respective keys
"cstm#attrs.src_ca_id_2116499352": {
"value": 100, // score
"alertEval": "CSTPC-hv71yin:100" // score tag (to appear in alert event) for all alerts for this key
// (including zero-scored alerts)
},
"scores": [ // all alerts for this event that scored > 0
"CSTPC-hv71yin:100-throttled",
"TMUAA_TMUAA:100-throttled"
],
..
"legitScore": 0, // similarly "positive" score is gathered, overall and by key
"legitScoreByKey": {
"cstm#attrs.dst_ca_id_472977624": {
"value": 0,
"alertEval": "CSTPC-GX71yin:0"
},
...
},
"shallIpBlacklist": false, // set if an alert decided the source IP shall be blacklisted ...
"ipBlacklistReason": "", // ...plus a human-readable text
"shallUriBlacklist": false, // set if an alert decided the source URI shall be blacklisted ...
"uriBlacklistReason": "", // ...plus a human-readable text
"shallIpWhitelist": false, // set if an alert decided the source IP shall be whitelisted ...
"ipWhitelistReason": "", // ...plus a human-readable text
"shallUriWhitelist": false, // set if an alert decided the source URI shall be whitelisted ...
"uriWhitelistReason": "", // ...plus a human-readable text
"series": { // series data collected for some alert types is ...
"cstm#attrs.dst_ca_id_472977624": { // ... organized by keys
"key": {
"type": "cstm",
...
},
"duplicate_policy": "last", // REDIS series configuration
"aggregation_policy": "max",
"data": { // data to be pushed in the series
"GX71yin_pc": [
1
]
}
},
...
},
"timers": [ // array of timers launched by this event
{
"timeslot": "2024-10-03T16:36#timer",
"timestamp": 1727973458,
"IP": "timer-MPX#689CAF98-E2F0-42F2-A475-30507F42E10C-581631089", // timer key
"domain": "ba86ac2a-7f13-44b3-ba77-4dc29e6f6305#timer-MPX#7500", // tenant ID and timer length
"detail_type": "CSTPC#GX71yin#eyJuYW1lIjoiY... ",
"TimeToLive": 1727980658,
"detail": {
"extensible": false,
"sessionId": "689CAF98-E2F0-42F2-A475-30507F42E10C-581631089",
"ephemeralId": false,
"timers": {
"startDate": "2024-10-03T14:32:38.000Z",
"startTimestamp": 1727965958,
"fireDate": "2024-10-03T16:37:38.000Z",
"fireTimestamp": 1727973458,
"coarseDate": "2024-10-03T16:36:38.000Z"
},
"data": { // event that started the timer
"type": "call-start",
"tls-cn": "ba86ac2a-7f13-44b3-ba77-4dc29e6f6305",
"attrs": {
"type": "call-start",
"from-ua": "Loxone",
...
},
"lengthSec": 7500 // timer length
},
...
],
"timerCancels": [], // timer cancellations
"exceededIds": [ // IDs alerts whose conditions were met
"CSTPC#hv71yin",
"CSTPC#hv71yin"
],
"warning": [
"no IP profile ipblack yet", // human-readable hints (processing history)
"alert profile timestamp lastRaisedTS doesnt exist yet",
"alert generation initated: test: CSTPC:hv71yin key: {\"type\":\" ...
...
],
"timestamp": 1727965958,
"militimestamp": 1727965958000,
"tenantId": "ba86ac2a-7f13-44b3-ba77-4dc29e6f6305",
"reason": "CSTPC: 2 >= 2 (pc) CSTPC: 2 >= 2 (PC) ", // reasons for raised alerts
"promises": [ // unprintable structures
{},
{},
{},
{},
{}
],
"listingAgo": {}, // blacklisting/whitelisting status
"blacklisting": {
"ipblack": "NOT_LISTING",
"uriblack": "NOT_LISTING",
"ipwhite": "NOT_LISTING",
"uriwhite": "NOT_LISTING"
},
"alerts": { // total alert statistics by status
"lowscore": 0,
"userSuppressed": 0,
"throttled": 0,
"raised": 2,
"sent": 2,
"unsent": 0,
"blisted": 0,
"ids": [ // elastic alert event ids
"571d0fc0-8194-11ef-85d3-636ddccdf70c",
"571d36d0-8194-11ef-85d3-636ddccdf70c"
]
},
"alertsByStatus": { // breakdown of the statistics by alert ID
"lowscore": {},
"userSuppressed": {},
"throttled": {},
"unsent": {},
"sent": {
"hv71yin": 2
}
},
"processingError": false, // true if an exception encountered
"ignored": false,
"profileUpdateResults": [
{ // detailed results of REDIS profile updates
"redis": [
"OK",
...
...