numericSumProfiledFeature Analytics Rule JSON Configuration

As you define a numericSumProfiledFeature analytics rule, review the structure and required fields for a numericSumProfiledFeature analytics rule.

Let's look at an example JSON configuration for a numericSumProfiledFeature analytics rule:

{
    "version":"1",
    "ruleDefinitions": [
        {
            "templateId": "DM-NumSP-EMR-Bytes-DU-Bytes",
            "name": "Abnormal amount of bytes received in incoming emails for this user",
            "description": "An abnormal amount of bytes have been received in incoming emails for this user.",
            "applicableEvents": [
                {
                    "activity_type": "email-receive",
                    "outcome": "success"
                }
            ],
            "detectionReason": "Abnormal amount (${trigger.numeric_value}) of bytes received in incoming emails for ${entity.user.dest}",
            "type": "numericSumProfiledFeature",
            "mitre": [
                {
                    "techniqueKey": "T1566",
                    "technique": "Phishing",
                    "tactic": "Initial Access",
                    "tacticKey": "TA0001"
                }
            ],
            "useCases": [
                "Phishing"
            ],
            "scopeValue": "EntityId('type: User && direction: Dest')",
            "featureValue": "bytes",
            "trainOnCondition": "exists(bytes, vendor)",
            "actOnCondition": "true",
            "anomalyThreshold": "90 days",
            "checkScopeMaturity": "true",
            "maturityThreshold": "14 days",
            "windowDuration": "1 day",
            "windowPeriod": "12 hours",
            "logBase": 2,
            "minOrderOfMagnitude": 17.0,
            "query": "(activity_type = \"email-receive\" AND outcome = \"success\") AND (dest_user_entity_id = \"${trigger.scope_value}\") AND (NOT bytes = null)",
            "familyId": "email-receive-activity",
            "ruleGroupId": "emailr-bytes-sum-magnitude-group"
        }
    }
}

An analytics rule is a JSON object that includes two mandatory fields: version and ruleDefinitions.

version indicates the layout version. It tracks the layout version if there are any updates to the layout or the New-Scale Security Operations Platform. Currently, the version is 1.

ruleDefinitions contains one or more rule definitions. The value of ruleDefinitions is an array. The array contains an object, and each object is a rule definition. The rule definition contains the fields that define an analytics rule and how it functions. Some fields are mandatory for the analytics rule to function while other fields are optional.

Ensure you include all necessary fields for your analytics rule to work as you expect and ensure all field values meet the requirements for a numericSumProfiledFeature rule:

Field	Description	Mandatory or Optional	Value Requirements
templateId	A unique identifier associated with the analytics rule.	Mandatory	Must be a string Maximum 128 characters For custom analytics rules, we recommend that you prefix the ID with C_.
name	The analytics rule name.	Mandatory	Must be a string Maximum 256 characters
description	A description of the analytics rule.	Optional	Must be a string Maximum 1024 characters
applicableEvents	The type of events the analytics rule evaluates.	Mandatory	Must be an array of objects. Each object is a condition an event must meet for the analytics rule to evaluate the event. Conditions define the Common Information Model (CIM) fields an event must contain for the analytics rule to evaluate the event. There is an or relationship between conditions; an event must meet at least one of, not all, the conditions for the analytics rule to evaluate the event. If an event doesn't meet any of the conditions, the analytics rule doesn't evaluate the event.
detectionReason	A dynamic name describing the rule and why it triggered on a specific event. It elaborates on the `name` field and adds detail specific to the specific event on which it triggered. It is displayed in Threat Center detections:	Mandatory	Must be a string Maximum 256 characters To customize the `detectionReason` to the event on which it triggered, insert dynamic variables for events, triggers, and entities: To insert a dynamic variable for an event, use the syntax `${event.field_name}`. To insert a dynamic variable for a trigger, use the syntax c`${trigger.fieldname}` To insert a dynamic variable for an entity, use the syntax `${entity.attribute_name}`
type	The analytics rule type.	Mandatory	Must be the string `"numericSumProfiledFeature"`
mitre	The MITRE ATT&CK^® tactics and techniques associated with the analytics rule.	Optional	Must be an array of objects. Each object represents an ATT&CK technique and corresponding tactic. Each object must contain the following keys and their values: `techniqueKey` `technique` `tactic` `tacticKey` The value of `techniqueKey` must be an existing ATT&CK technique ID. It must correspond with the value of `technique`. The value of `technique` must be an existing ATT&CK technique name. It must correspond with the value of `techniqueKey`. The value of `tactic` must be an existing ATT&CK tactic name. It must correspond with the value of `tacticKey`. The value of `tacticKey` must be an existing ATT&CK tactic ID. It must correspond with the value of `tactic`.
useCases	Exabeam use case associated with the analytics rule.	Optional	Must be an array of strings. Each string must be an existing Exabeam use case: Abnormal Authentication & Access Account Manipulation Audit Tampering Brute Force Attack Cloud Data Protection Compromised Credentials Cryptomining Data Access Data Exfiltration Data Leak Destruction of Data Evasion Lateral Movement Malware Phishing Physical Security Privilege Abuse Privilege Escalation Privileged Activity Ransomware Workforce Protection
scopeValue	The event field on which the model for the analytics rule trains; typically an object or entity.	Mandatory	Must be a string Must be different from the value of `featureValue` Must use valid expression syntax
featureValue	The event field on which the model for the analytics rule trains for the scopeValue. For example, if scopeValue is hostname and featureValue is process, the model trains on the behavior of processes executed on hostnames.	Mandatory	Must be a string Must be different from the value of `scopeValue`
trainOnCondition	The events on which the analytics rule trains.	Mandatory	Must be a string If the analytics rule trains on all events, string is `"true"` If the analytics rule triggers on specific events, string is an expression that defines the events on which the analytics rule trains. Ensure you use valid expression syntax.
actOnCondition	A high-level filter for the events on which the analytics rule triggers.	Mandatory	Must be a string If the analytics rule triggers on all events, string is `"true"` If the analytics rule triggers on specific events, string is an expression that defines the events on which the analytics rule triggers. Ensure you use valid expression syntax.
scoreUnless	A list of analytics rules. If any analytics rule in the list triggers, the given analytics rule doesn't trigger.	Optional	Must be an array of strings Each string must be an analytics rule `templateID`.
anomalyThreshold	The period of time the model for the analytics rule remembers and trains on an observed data point. After this period, the model forgets the data point and the analytics rule can trigger on the data point again.	Mandatory	Must be a string; for example, `"90 days"` Must be a minimum of 1 day and maximum of 120 days
checkScopeMaturity	Whether the rule should learn more about the entities defined in `scopeValue` before triggering. Ensures the associated model has a good baseline for normal behavior.	Optional	Must be a boolean value If true, you must include
maturityThreshold	The duration of the training period for `checkScopeMaturity`.	Optional	Must be a string; for example, `"14 days"`
countPer	What of the `scopeValue` the analytics rule counts. For example, you can use `countPer` to specify that the analytics rule counts the number of logins to a specific endpoint per user. In this case, `countPer` is a specific endpoint and `scopeValue` is a user entity. You use `countPer` as an additional `scopeValue` and to add more complexity to what the analytics rule counts.	Optional	Must be a string String is an expression that defines what of the `scopeValue` the analytics rule counts. Expression must follow valid syntax.
windowDuration	The duration of the summing period.	Mandatory	Must be a string; for example, `"1 day"`
windowPeriod	How often the rule evaluates events during the period defined in `windowDuration`; for example, every 12 hours.	Mandatory	Must be a string; for example, `"12 hours"` Must be a minimum of 12 hours and maximum of 45 days
logBase	The log base value used to calculate the minimum count of a given behavior considered anomalous in relation to a previous trigger. The analytics engine uses an exponential function to determine when the count of a given behavior is considered anomalous. With an exponential function, the count of a given behavior must be ever increasing to be considered anomalous. For example, let's say the analytics rule counts number of emails a user sends. The analytics rule triggers when a user sends 10 emails. If the user sends 12 emails, you may not want the analytics rule to trigger again because 12 emails is not unusual compared to 10 emails. However, if the user sends 30 emails, you may consider this behavior anomalous, and you may want the analytics rule to trigger again. `logBase` defines the next time the analytics rule triggers in relation to a previous trigger. In this example, if the `logBase` is 2, then the analytics rule triggers when at least two, four, eight, 16, 32 and so forth emails are sent; if the `logBase` is 6, then the analytics rule triggers when at least six, 36, 216, and 1,296 and so forth emails are sent. With a higher `logBase` value, the count must be ever higher for the analytics rule to trigger, the analytics rule triggers less often, and there is less chance of false positives. With a lower `logBase` value, the analytics rule triggers more often but there is a higher chance of false positives.	Mandatory	Must be a double data type (double-precision floating-point)
minOrderOfMagnitude	The count of a given behavior up to which the analytics rule considers normal and never triggers, as a factor of the `logBase` value. For example, let's say the analytics rule counts number of emails a user sends. If the `minOrderofMagnitude` is 3, and `logBase` is 2, the analytics rule doesn't trigger until the user sends eight or more emails.	Mandatory	Must be an integer Must be a minimum of 1 and maximum of 4
query	A query that retrieves the specific events that triggered the analytics rule. In many cases, `query` retrieves the same events defined under `applicableEvents`. The events retrieved using `query` are shown in the Threat Center Threat Timeline, under View All Logs:	Mandatory	Must be a string Must use valid expression syntax
familyId	The analytics rule family to which the rule belongs.	Mandatory	Must be a string Must refer to the ID of an existing analytics rule family
ruleGroupId	The analytics rule group to which the rule belongs.	Mandatory	Must be a string Must refer to the ID of an existing analytics rule group The analytics rule group must belong under the analytics rule family specified in the familyId field.

Threat Detection ManagementThreat Detection Management Guide

Table of ContentsTable of Contents

numericSumProfiledFeature Analytics Rule JSON Configuration