Rule annotation
Rule annotation helps to document rule behavior and is used by the Nuix Adaptive Security application when displaying data for rule matches.
Comments
Any line starting with the number sign (#), as shown in the following example, is treated as a comment by the rule compiler.
#
# Task modified from cmdline (process artifact)
#
alert when process.state == PROCESS_STARTED and
strcmp(getbasename(process.path),"schtasks.exe",false) and
strstr(process.cmdline,"/change",false);
Key-value pair data
Rule groups and individual rules can have lists of key-value pair data associated with them. This allows for a richer annotation of rules than comments alone can provide. The key-value pair data is returned to the server when a rule match occurs. These values are used by the Nuix Adaptive Security application for various purposes (display, sorting, and searching).
Key-value pair data specified at the rule group level is inherited by rules in that rule group. The syntax for specifying key-value pair data at the rule group level looks like the following:
rulegroup example (<key> = "<value>", ...)
where key is an alphanumeric string that must begin with an alphabetic character and the value is any quoted-string value. The syntax for specifying key/value pair data at the rule level looks like the following:
rule (<key>="<value>", ...) { <action> when <expression> ; }
The rule compiler places no restrictions on the length or contents of the values; however, several key names carry significance to the Nuix Adaptive Security application.
The key name platform is used to associate a rule to a particular platform. Currently the values “windows” and “macOS” are recognized. The use of the platform keyword allows rules targeted for different platforms to exist in the same rule file. When compiling rules, the combination of the platform keyword and the platform target chosen in the Nuix Adaptive Security application determines whether the rule will be compiled. If no platform key name is specified, the rule is assumed to be valid for all platforms and compilation will be attempted for any platform target.
The following key names carry significance when displaying alert data:
Name
Description
Severity
Category
Author
Type
The values associated with these key names are prominently displayed in the Alerts pane of the Nuix Adaptive Security application. View all other key names associated with a matched rule in the Nuix Adaptive Security application Alerts pane by clicking “Rule Metadata Other”. In addition, the use of the category keyword with a case-sensitive value of “Threat-Hunting” will cause the associated alert data to display under the Threat Hunting data source in the Guided Investigations section of the Investigate pane module in the Nuix Adaptive Security application. The use of the severity keyword with values (case sensitive) of “Critical”, “Medium”, or “Low” are used in the Dashboard module in the Nuix Adaptive Security application in the event summary display.
Rules inherit key-value pair data from their enclosing rule group. For example, when the alert rule matches, the key-value pairs returned will be author="Nuix", type=”Persistence”, name="Task modified", and description=” The command line…”.
rulegroup Task_Scheduling
(author="Nuix",
type="Persistence")
{
rule
(name="Task modified",
description="""
The command line "schtasks.exe /change" was executed. If successful
this will result in the modification of an existing scheduled task
on the endpoint. Task scheduling may be associated with persistence
techniques used by malware and insiders.""")
{
alert when process.state == PROCESS_STARTED and
strcmp(getbasename(process.path),"schtasks.exe",false) and
strstr(process.cmdline,"/change",false);
}
}
A key name and value specified in the rule group can also be overridden within the rule itself. For example, when the alert rule matches, the value returned for author will be “Bob” and not “Nuix”, as shown in the following example:
rulegroup Task_Scheduling
(author="Nuix",
type="Persistence")
{
rule
(author="Bob",
name="Task modified",
description="""
The command line "schtasks.exe /change" was executed. If successful
this will result in the modification of an existing scheduled task
on the endpoint. Task scheduling may be associated with persistence
techniques used by malware and insiders.""")
{
alert when process.state == PROCESS_STARTED and
strcmp(getbasename(process.path),"schtasks.exe",false) and
strstr(process.cmdline,"/change",false);
}
}
Each key name should be specified only once within a particular rule group key-value pair list or individual rule key-value pair list. If a key name is reused within a list, a warning is issued by the compiler and the first definition is used. The following rule uses the key name of author twice.
rule (author="Alice", author="Bob") {...}
The compiler generates the following warning message for this rule:
warning 0x00020023: "test.txt" line 3, second instance of metadata
keyword "AUTHOR" with value "Bob" ignored
Rule comments can be used in conjunction with key-value pairs as shown in the following example:
rulegroup Task_Scheduling
(author="Nuix",
type="Persistence")
{
#
# Task modified from cmdline (process artifact)
#
rule
(name="Task modified",
description="""
The command line "schtasks.exe /change" was executed. If successful this will result in the modification of an existing scheduled task on the endpoint. Task scheduling may be associated with persistence techniques used by malware and insiders.""")
{
alert when process.state == PROCESS_STARTED and
strcmp(getbasename(process.path),"schtasks.exe",false) and
strstr(process.cmdline,"/change", false);
}
}