Update a Custom Detection Rule
Endpoint URL: https://<your server>/rest/v2/customRules/decisionFeature/update
Endpoint URI: v2/customRules/decisionFeature/update
Action: POST
Updates an existing custom detection rule.
Note
Custom Detection Rules can be created via API but should be created only once 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 |
|---|---|---|
id |
Integer |
The unique identifier for 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:
|
autoRemediationActions |
Array |
An array containing details on the automatic remediation actions to perform when a Malop is generated from this custom detection rule. Automatic remediation is currently not supported, but this is a required object for this request. |
killProcess |
Boolean |
Indicates whether or not to kill the process found as the root cause of a Malop generated from this custom detection rule. Set the value of this parameter to false as automatic remediation actions are not currently supported. |
quarantineFile |
Boolean |
Indicates whether or not to quarantine a file found as the root cause of a Malop generated from this custom detection rule. Set the value of this parameter to false as automatic remediation actions are not currently supported. |
isolateMachine |
Boolean |
Indicates whether or not to isolate a machine associated with a Malop generated from this custom detection rule. Set the value of this parameter to false as automatic remediation actions are not currently supported. |
autoRemediationStatu |
Enum |
The status of the automatic remediation actions specified in this request. Set this value to Active to ensure this request works appropriately. Note that automatic remediation actions are not currently supported. |
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. If you want to disable a rule, set this value to false. |
userName |
String |
The Cybereason user name for the user updating the rule. |
creationTime |
Integer |
The timestamp (in epoch) when the rule was created. |
updateTime |
Integer |
The timestamp (in epoch) when you update the rule. |
lastTriggerTime |
Integer |
The timestamp (in epoch) when the rule last triggered a Malop. |
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 detailing the failure of the update operation
Important Response Fields
Important information is found in these fields:
rules object: An object containing a list of all custom detection rules active in the platform.
id parameter: The unique identifier the Cybereason platform uses for the custom detection rule.
name parameter: The name of the custom detection rule.
rootCause parameter: The Element identified as the root cause for any Malops generated by the custom detection rule.
malopDetectionType parameter: The type of detection set for Malops generated by the custom detection rule.
rule object: An object containing details on a specific custom detection rule.
elementType parameter: The Element used as the starting Element in the rule.
filters object: The object containing the objects used to filter the specified Element.
facetName parameter: The name of the Feature used to filter the Element.
values parameter: The value used with the facetName parameter.
children object: The object containing details on Elements linked to the first Element in the custom rule.
connectionFeature parameter: The Feature that connects the Elements in a chain used in the custom rule.
enabled parameter: Indicates if the custom detection rule is enabled.
Example: Update a custom detection rule
Request
curl --request POST \
--url https://12.34.56.78/rest/v2/customRules/decisionFeature/update \
--header 'Content-Type:application/json' \
--data '{
"id":"1582038865368"
"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.
{
"id":1580246401162,
"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/update"
api_url = base_url + endpoint_url
# These variables create the request parts.
id = 1580246401162
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({"id":id,"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
}