Create a Custom Detection Rule
Endpoint URL: https://<your server>/rest/v2/customRules/decisionFeature/create
Endpoint URI: /v2/customRules/decisionFeature/create
Action: POST
Creates a custom detection rule.
Note
Custom detection rules created via API should be created only after adequate research regarding precision and coverage has been completed. Creating a custom detection rule that is not specific enough can have detrimental impact on retention and overall performance of the environment.
Note
Ensure that you have logged into the Cybereason platform. For details, see Log in with the API.
Request Headers
You must add an Content-Type:application/json header with the request.
Note
If you are using cURL, add the authorization cookie details or the path to the file with cookie details with every request.
Request Body
Input: JSON
Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.
{
"name": "<name>",
"rootCause": "<root cause>",
"malopDetectionType": "<detection type>",
"autoRemediationActions": {
"killProcess": false,
"quarantineFile": false,
"isolateMachine": false
},
"autoRemediationStatus": "Active",
"rule": {
"root": {
"elementType": "<Element>",
"elementTypeTranslation": "<Element name translation>",
"filters": [
{
"facetName": "<Feature name>",
"filterType": "<filter>",
"values": [
"<value>"
]
}
],
"children": [
{
"elementType": "<Element>",
"elementTypeTranslation": "<Element>",
"connectionFeature": "<Connection Feature>",
"connectionFeatureTranslation": "<Feature name translation>",
"reversed": false,
"filters": [
{
"facetName": "<Feature name>",
"filterType": "<filter>",
"values": [
"<value>"
]
}
]
}
]
},
"malopActivityType": "<activity type>"
},
"description": "<description>",
"enabled": true
}
Request Parameters
URL/URI parameters: none
Request Body Parameters: Use the following available fields in the request. Required parameters are noted in bold.
Field |
Type |
Parameter |
|---|---|---|
name |
String |
A name to assign to the custom rule. |
rootCause |
Enum |
The Element which is identified as the root cause in the Malop generated from the custom detection rule. Possible values include:
|
malopDetectionType |
Enum |
The detection type to assign to Malops generated from this custom detection rule. Possible values include:
|
rule |
Array |
An object containing the details of the custom detection rule. |
root |
Array |
An object containing the details of the Element that is the starting Element in the custom detection rule. |
elementType |
Enum |
The Element used as the base of the custom detection rule. Possible values include:
|
elementTypeTranslation |
String |
The name for the Element that displays when viewing the custom detection rule in the Cybereason UI. |
filters |
Array |
An object containing details on Feature filters added for the root Element in the custom detection rule. |
facetName |
String |
The name of the Feature on which to filter the base Element. |
filterType |
Enum |
The filter to use for the specified Feature. The filter to use depends on the Feature type added in the facetName filter. For details, see Apply Operators in Filters. |
values |
String/Integer/Boolean |
The value to use for the specified Feature. The type depends on the individual Feature. |
children |
Array |
An object containing details on additional Elements added after the base Element. If your rule contains only one Element, set the value of this parameter to null. |
connectionFeature |
String |
The name of the Feature that connects the linked Elements. This Feature name corresponds with the name of the linked Element. For details on the Features available to use as connection features, see Supported Features for Linking Elements in a Custom Detection Rule. |
connectionFeatureTranslation |
String |
The name of the linked Element to display when viewing the rule in the Cybereason UI. |
reversed |
Boolean |
Indicates whether the Feature belongs to the first or following Element. Set this value to false. |
malopActivityType |
Enum |
The activity type to assign to Malops generated from this custom detection rule. Possible values include:
|
description |
String |
The description for this custom detection rule. |
enabled |
Boolean |
Indicates whether or not to enable this detection rule upon creation. Set this value to true to automatically enable the rule. |
Response Status Codes
This request can return the following status codes:
200: Success OK
Response Success Schema
The response contains the following fields:
Field |
Type |
Parameter |
|---|---|---|
id |
Integer |
The unique numerical identifier used by Cybereason to identify the custom detection rule. |
name |
String |
A name to assign to the custom rule. |
rootCause |
Enum |
The Element which is identified as the root cause in the Malop generated from the custom detection rule. Possible values include:
|
malopDetectionType |
Enum |
The detection type to assign to Malops generated from this custom detection rule. Possible values include:
|
rule |
Array |
An object containing the details of the custom detection rule. |
root |
Array |
An object containing the details of the Element that is the starting Element in the custom detection rule. |
elementType |
Enum |
The Element used as the base of the custom detection rule. Possible values include:
|
elementTypeTranslation |
String |
The name for the Element that displays when viewing the custom detection rule in the Cybereason UI. |
filters |
Array |
An object containing details on Feature filters added for the root Element in the custom detection rule. |
facetName |
String |
The name of the Feature on which to filter the base Element. |
filterType |
Enum |
The filter to use for the specified Feature. The filter to use depends on the Feature type added in the facetName filter. For details, see Apply Operators in Filters. |
values |
String/Integer/Boolean |
The value to use for the specified Feature. The type depends on the individual Feature. |
children |
Array |
An object containing details on additional Elements added after the base Element. If your rule contains only one Element, set the value of this parameter to null. |
connectionFeature |
String |
The name of the Feature that connects the linked Elements. This Feature name corresponds with the name of the linked Element. |
connectionFeatureTranslation |
String |
The name of the linked Element to display when viewing the rule in the Cybereason UI. |
reversed |
Boolean |
Indicates whether the Feature belongs to the first or following Element. Set this value to false. |
malopActivityType |
Enum |
The activity type to assign to Malops generated from this custom detection rule. Possible values include:
|
description |
String |
The description for this custom detection rule. |
enabled |
Boolean |
Indicates whether or not to enable this detection rule upon creation. Set this value to true to automatically enable the rule. |
userName |
String |
The Cybereason user name for the user that created the custom rule. |
creationTime |
Integer |
The time (in epoch) when the custom detection rule was created. |
updateTime |
Integer |
The time (in epoch) when the custom detection rule was last updated. |
lastTriggerTime |
Integer |
The time (in epoch) when a Malop was generated based on the custom detection rule. |
Response Failure Schema
A message containing details on the creation operation
Important Response Fields
Important information is found in these fields:
id parameter: The unique identifier used by the Cybereason platform for this custom detection rule.
creationTime parameter: The time (in epoch) when the user created the custom detection rule.
There are numerous other fields in the response. However, these fields correspond to the values you set in the request.
Example: Create a custom detection rule
Request
curl --request POST \
--url https://12.34.56.78/rest/v2/customRules/decisionFeature/create \
--header 'Content-Type:application/json' \
--data '{
"name":"Test Rule 1",
"rootCause":"self",
"malopDetectionType":"CUSTOM_RULE",
"autoRemediationActions": {
"killProcess":false,
"quarantineFile":false,
"isolateMachine":false
},
"autoRemediationStatus":"Active",
"rule": {
"root": {
"elementType":"Process",
"elementTypeTranslation":"Process",
"filters": [
{
"facetName":"maliciousUseOfRegsvr32ModuleEvidence",
"filterType":"Equals",
"values":[true]
}
],
"children": [
{
"elementType":"Process",
"elementTypeTranslation":"Process",
"connectionFeature":"parentProcess",
"connectionFeatureTranslation":"Parent process",
"reversed":false,
"filters": [
{
"facetName":"name",
"filterType":"ContainsIgnoreCase",
"values":["msword.exe"]
}
]
}
]
},
"malopActivityType":"MALICIOUS_INFECTION"
},
"description":"Test Rule 1",
"enabled":true
}'
Response
{
"id":1580246401162,
"name":"Test Rule 1",
"rootCause":"self",
"malopDetectionType":"CUSTOM_RULE",
"rule": {
"parentId":1580246401162,
"root": {
"elementType":"Process",
"filters": [
{
"facetName":"maliciousUseOfRegsvr32ModuleEvidence",
"values":[true],
"filterType":"Equals",
"featureTranslation":"Abuse of the Regsvr32 utility module (ATT&CK: Defense Evasion, Execution - Regsvr32)"
}
],
"children":[
{
"connectionFeature":"parentProcess",
"elementType":"Process",
"filters": [
{
"facetName":"name",
"values":["msword.exe"],
"filterType":"ContainsIgnoreCase",
"featureTranslation":"Process name"
}
],
"children":null,
"elementTypeTranslation":"Process",
"connectionFeatureTranslation":"Parent process"
}
],
"elementTypeTranslation":"Process"
},
"malopActivityType":"MALICIOUS_INFECTION"
},
"description":"Test Rule 1",
"enabled":true,
"userName":"[email protected]",
"creationTime":1580246401285,
"updateTime":1580246401285,
"lastTriggerTime":null,
"autoRemediationActions":null,
"autoRemediationStatus":null
}
Request
Use this request body:
Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.
{
"name":"Test Rule 1",
"rootCause":"self",
"malopDetectionType":"CUSTOM_RULE",
"autoRemediationActions": {
"killProcess":false,
"quarantineFile":false,
"isolateMachine":false
},
"autoRemediationStatus":"Active",
"rule": {
"root": {
"elementType":"Process",
"elementTypeTranslation":"Process",
"filters": [
{
"facetName":"maliciousUseOfRegsvr32ModuleEvidence",
"filterType":"Equals",
"values":[true]
}
],
"children": [
{
"elementType":"Process",
"elementTypeTranslation":"Process",
"connectionFeature":"parentProcess",
"connectionFeatureTranslation":"Parent process",
"reversed":false,
"filters": [
{
"facetName":"name",
"filterType":"ContainsIgnoreCase",
"values":["msword.exe"]
}
]
}
]
},
"malopActivityType":"MALICIOUS_INFECTION"
},
"description":"Test Rule 1",
"enabled":true
}
Response
{
"id":1580246401162,
"name":"Test Rule 1",
"rootCause":"self",
"malopDetectionType":"CUSTOM_RULE",
"rule": {
"parentId":1580246401162,
"root": {
"elementType":"Process",
"filters": [
{
"facetName":"maliciousUseOfRegsvr32ModuleEvidence",
"values":[true],
"filterType":"Equals",
"featureTranslation":"Abuse of the Regsvr32 utility module (ATT&CK: Defense Evasion, Execution - Regsvr32)"
}
],
"children":[
{
"connectionFeature":"parentProcess",
"elementType":"Process",
"filters": [
{
"facetName":"name",
"values":["msword.exe"],
"filterType":"ContainsIgnoreCase",
"featureTranslation":"Process name"
}
],
"children":null,
"elementTypeTranslation":"Process",
"connectionFeatureTranslation":"Parent process"
}
],
"elementTypeTranslation":"Process"
},
"malopActivityType":"MALICIOUS_INFECTION"
},
"description":"Test Rule 1",
"enabled":true,
"userName":"[email protected]",
"creationTime":1580246401285,
"updateTime":1580246401285,
"lastTriggerTime":null,
"autoRemediationActions":null,
"autoRemediationStatus":null
}
Request
Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.
import requests
import json
# Login information
username = "[email protected]"
password = "mypassword"
server = "yourserver.com"
port = "443"
data = {
"username": username,
"password": password
}
headers = {"Content-Type": "application/json"}
base_url = "https://" + server + ":" + port
login_url = base_url + "/login.html"
session = requests.session()
login_response = session.post(login_url, data=data, verify=True)
print (login_response.status_code)
print (session.cookies.items())
# Request URL
endpoint_url = "/rest/v2/customRules/decisionFeature/create"
api_url = base_url + endpoint_url
# These variables create the request parts.
rule_name = "Test Rule 1"
root_cause = "self"
detection_type = "CUSTOM_RULE"
root_element = "Process"
root_element_translation = "Process"
root_element_filter = "maliciousUseOfRegsvr32ModuleEvidence"
child_element = "Process"
child_element_translation = "Process"
connection_feature = "parentProcess"
connection_feature_translation = "Parent process"
child_element_filter = "name"
child_element_filter_value = "msword.exe"
activity_type = "MALICIOUS_INFECTION"
description = "Test Rule 1"
rule = json.dumps({"name":rule_name,"rootCause":root_cause,"malopDetectionType":detection_type,"autoRemediationActions":{"killProcess":false,"quarantineFile":false,"isolateMachine":false},"autoRemediationStatus":"Active","rule":{"root":{"elementType":root_element,"elementTypeTranslation":root_element_translation,"filters":[{"facetName":root_element_filter,"filterType":"Equals","values":[True]}],"children": [{"elementType":child_element,"elementTypeTranslation":child_element_translation,"connectionFeature":connection_feature,"connectionFeatureTranslation":connection_feature_translation,"reversed":False,"filters": [{"facetName":child_element_filter,"filterType":"ContainsIgnoreCase","values":[child_element_filter_value]}]}]},"malopActivityType":activity_type},"description":description,"enabled":True})
api_headers = {'Content-Type':'application/json'}
api_response = session.request("POST", api_url, data=rule, headers=api_headers)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Response
{
"id":1580246401162,
"name":"Test Rule 1",
"rootCause":"self",
"malopDetectionType":"CUSTOM_RULE",
"rule": {
"parentId":1580246401162,
"root": {
"elementType":"Process",
"filters": [
{
"facetName":"maliciousUseOfRegsvr32ModuleEvidence",
"values":[true],
"filterType":"Equals",
"featureTranslation":"Abuse of the Regsvr32 utility module (ATT&CK: Defense Evasion, Execution - Regsvr32)"
}
],
"children":[
{
"connectionFeature":"parentProcess",
"elementType":"Process",
"filters": [
{
"facetName":"name",
"values":["msword.exe"],
"filterType":"ContainsIgnoreCase",
"featureTranslation":"Process name"
}
],
"children":null,
"elementTypeTranslation":"Process",
"connectionFeatureTranslation":"Parent process"
}
],
"elementTypeTranslation":"Process"
},
"malopActivityType":"MALICIOUS_INFECTION"
},
"description":"Test Rule 1",
"enabled":true,
"userName":"[email protected]",
"creationTime":1580246401285,
"updateTime":1580246401285,
"lastTriggerTime":null,
"autoRemediationActions":null,
"autoRemediationStatus":null
}