Create detection rule set

Create a new detection rule set. Detection rule sets can require a large number of fields and unique IDs to function properly. It is recommended to make a GET request to '/rulesets/v2/default' to obtain a properly formatted template prior to submitting a POST request described below. 

Service endpoint

/rulesets/v2

Optional query string parameters

—

Example

https://protectapi.cylance.com/rulesets/v2

Method

HTTP/1.1 POST

Request headers
  • Accept: application/json
  • Authorization: Bearer JWT Token returned by Auth API with the opticsruleset:create scope encoded

Request

JSON 
{
    "name": "Test Rule Set",
    "description": "Test Detection Rule Set",
    "notification_message": "",
    "category": "Custom",
    "rules": [
        {
            "detection_rule_id": "008ece50-49af-472a-b0d8-3c3700883738",
            "detection_rule_version": 1,
            "detection_name": "Gatekeeper Bypass (MITRE)",
            "detection_description": "Detects on usage to bypass Gatekeeper",
            "category": "Custom",
            "severity": "Low",
            "operating_systems": [
                {
                    "Name": "macOS"
                }
            ],
            "date_added": "2018-11-20T17:58:49Z",
            "enabled": false,
            "notification_enabled": false,
            "responses": [
                {
                    "template_id": "9686d82e-1b1d-45a9-977a-cf86f1063b15",
                    "response_id": "c6a26a8b-edce-4a68-8e18-4d16df74e455",
                    "response_rule_version": 1,
                    "description": "DisplayNotification",
                    "value": {},
                    "enabled": false,
                    "created": "2018-11-20T17:58:49Z"
                }
            ],
            "exceptions": [
                {
                    "exception_id": "",
                    "enabled": ,
                    "name": ""
                }
            ],
            "playbooks": [
                ""
            ]
        }
    ]
}

Response

Please see the Response status codes for more information.

Response JSON schema

Field Name Description

name

This is the name of the detection rule set.

description

This is the description of the detection rule set.

notification_message

This is the message to display on the endpoint when a detection rule is triggered.

id

This is the unique ID of the detection rule set.

last_modified

This is the timestamp (in UTC) of the last time that the detection rule set was modified.

modified_by

This is an object detailing the last user to modify the detection rule. It includes the following fields:

  • id: This is the unique ID of the user who modified the detection rule.
  • login: This is the email address of the user who modified the detection rule.

rules

This is a list of detection rule objects and their associated response actions, detection exceptions, and package playbooks.

detection_rule_id

This is the unique ID of the detection rule.

detection_rule_version

This is the version of the detection rule.

detection_name

This is the name of the detection rule.

detection_description

This is the description of the detection rule set.

category

This is the category of the detection rule.

severity

This is the severity assigned to the detection rule. Possible values are:

  • High
  • Medium
  • Low
  • Informational

operating_systems

This is an object detailing the operating systems to which the detection rule can be applied. It will include the "name" field. This can consist of:

  • "Windows"
  • "MacOS"

date_added

This is the timestamp (in UTC) when the detection rule was added to the tenant.

enabled

This determines whether or not a detection rule is enabled in the detection rule set. When viewing the content of a detection rule set, this should always be set to 'true'.

notification_enabled

This determines whether or not the message defined in the 'notification_message' field should display on the device when the detection rule is triggered.

To enable display desktop notification on device using the API, set notification_enabled and DisplayDesktopNotification to "true". To disable, set both to "false". The DisplayDesktopNotification setting enables or disables the feature. The notification_enabled setting affects the display desktop notification on device checkbox in the console as enabled (checked) or disabled (unchecked).

responses

This is a list of response objects for each response action enabled for a particular detection rule. Each object will include the following fields:

  • template_id: This is the ID of the response template to use (this is provided by Endpoint Defense).
  • response_rule_id: This is the ID of the response rule to enable (this is provided by Endpoint Defense).
  • response_rule_version: This is the version of the response rule to enable (this is provided by Endpoint Defense).
  • description: This is the description/name of the response rule.
  • value: This is a currently unused field.
  • enabled: This will always be 'true' when viewing a detection rule set.
  • created: This is the date that the response rule was added to the tenant.

exceptions

This is a list of exception rule objects that should be applied to the detection rule. Each object will include the following fields:

  • exception_id: This is the unique ID of the exception rule.
  • enabled: This will always be 'true' when viewing a detection rule set.
  • name: This is the name of the exception rule.

playbooks

This is a list of package playbook unique IDs that will be executed when the detection rule is triggered on the device.