Skip to main content

createCustomRule

Method to create a custom rule.

Parameters

Parameter

Description

Included in request

Type

Values

companyId

The ID of the company the custom rule will belong to.

Optional

String

Must be the valid ID of a company that you manage.

Default value: The ID of the company the API key used to make the request.

type

The type of the rule to be created.

Optional

Integer

Possible values:

  • 1 - Detection

  • 2 - Exclusion

Default value: 2.

name

The name of the rule to be created.

Mandatory

String

This parameter cannot begin with a whitespace character, cannot include the characters <, >, ', or ", and must be no longer than 128 characters.

Also, it cannot be duplicated within the same company.

description

The description of the rule.

Optional

String

This parameter cannot begin with a whitespace character, cannot include the characters <, >, ', or ", and must be no longer than 1024 characters.

tags

The list of associated rule tags.

Optional

Array of Strings

Each string must:

  • Not contain <, >, ', or "

  • Be at least 2 characters long and no longer than 128 characters

  • Not start with a whitespace character

  • Be unique in the array

settings

Contains the settings associated with the rule.

Mandatory

Object

Refer to settings.

returnRuleId

Indicates if the request will return the ID of the new rule.

Optional

Boolean

Possible values:

  • true, will return the ID of the newly created rule, if the request is successful.

  • false, will not return the ID of the newly created rule. Instead, it will return a Boolean value.

Default value: false.

targets

Contains companiesIds, which lists the IDs of the companies to which the custom rule applies.

Optional

Object

Refer to targets.

General parameters

These are common parameters, available across all public API methods:

Parameter

Description

Included in request

Type

Values

id

This parameter adds an identifier to the request, linking it to its corresponding response.

The target replies with the same value in the response, allowing easy call tracking.

Mandatory

String

No additional requirements.

method

The name of the method you are using to send the request.

Mandatory

String

Must be a valid method name.

jsonrpc

The version of JSON-RPC used by the request and the response.

Mandatory

String

Possible values:

  • "2.0"

params

An object containing the configuration of the request.

Mandatory

Object

No additional requirements.

Objects

settings

Name

Description

Included in request

Type

Values

status

Indicates if the rule is active.

Optional

Integer

Possible values:

  • 0 - Inactive

  • 1 - Active

Default value: 1.

severity

Indicates the severity of the alerts that will be generated.

Mandatory for detection rules; not applicable to exclusion rules.

Integer

Possible values:

  • 1 - Low

  • 2 - Medium

  • 3 - High

target

Indicates the type of the target entity.

Mandatory

String

Possible values for custom exclusion and detection rules:

  • process

  • file

    Important

    Requires at least one of the following license types:

    • A license with EDR

    • A license that provides at least one of these sensor types:

      • Productivity sensors

      • Cloud sensors

      • Identity sensors

  • connection

  • registry

    Important

    Requires a license with EDR.

  • user connection

  • email

    Important

    Requires at least one of the following license types:

    • A license with EDR

    • A license that provides at least one of these sensor types:

      • Productivity sensors

      • Cloud sensors

      • Identity sensors

  • application

    Important

    Requires a license that provides at least one of these sensor types:

    • Productivity sensors

    • Identity sensors

  • key vault

    Important

    Requires a license providing Cloud sensors.

  • role

    Important

    Requires a license that provides at least one of these sensor types:

    • Productivity sensors

    • Cloud sensors

    • Business Applications sensors

    • Identity sensors

  • policy

    Important

    Requires a license that provides at least one of these sensor types:

    • Productivity sensors

    • Cloud sensors

    • Identity sensors

  • sharing link

    Important

    Requires a license providing Productivity sensors.

  • url

    Important

    Requires a license providing Productivity sensors.

  • ssh key

    Important

    Requires a license providing Cloud sensors.

  • launch template

    Important

    Requires a license providing Cloud sensors.

  • service principal

    Important

    Requires a license that provides at least one of these sensor types:

    • Productivity sensors

    • Cloud sensors

    • Identity sensors

  • user group

    Important

    Requires a license that provides at least one of these sensor types:

    • Productivity sensors

    • Business Applications sensors

    • Identity sensors

  • automation account

    Important

    Requires a license providing Cloud sensors.

  • automation account hook

    Important

    Requires a license providing Cloud sensors.

  • certificate authority

    Important

    Requires a license that provides at least one of these sensor types:

    • Cloud sensors

    • Identity sensors

  • api

  • bucket

    Important

    Requires a license providing Cloud sensors.

  • jira project

    Important

    Requires a license providing Business Applications sensors.

  • confluence page

    Important

    Requires a license providing Business Applications sensors.

Possible values available only for custom exclusion rules:

  • flow

    Important

    Requires a license providing Productivity sensors.

  • bitbucket repository

    Important

    Requires the Atlassian Cloud sensor.

criteriaList

Defines the rule by listing the exclusion or detection sub-rules that the specified target must match.

Important

This parameter does not include definitions related to the detection field. They must be configured under the filters parameter.

Mandatory

Array of Objects

Each object contains the following settings:

  • field (String) - The entity attribute (criterion) to which the condition applies.

  • relation (String) - The required relationship between the field and the value for the condition to be met.

  • value - A custom value against which the value of the field parameter is compared.

Note

For information on the possible values of criteriaList objects, refer to Detection and exclusion criteria.

filters

Contains the exclusion or detection sub-rules related to the detection field.

Optional

Array of Objects

Important

It is an array containing a single object, as only one detection filter can be used per rule.

The object within the array contains the following settings:

  • field (String) - The entity attribute (criterion) to which the condition applies. The filters parameter accepts only the detection field value.

  • value - The value that the detection field (Alert name) must match.

Note

For information on the detection field, refer to Detection and exclusion criteria.

automaticActions

Indicates the automatic response actions and their enablement status for EDR incidents generated by this rule.

Important

  • Automatic actions are available only for EDR custom detection rules.

  • Bitdefender EDR subscriptions and GravityZone EDR Cloud licenses do not support automatic actions.

Optional for EDR detection rules; not applicable to exclusion rules or XDR detection rules.

Array of Objects

Each object contains the following settings:

  • type (Integer) - The type of automatic action assigned to the rule.

    Possible values:

    • 1 - Isolate

    • 2 - Collect investigation package

    • 3 - Add to Sandbox

      Important

      Available only under one of the following conditions:

      • target is process or file

      • target is connection and criteriaList contains an Object whose field has one of the following values:

        • Connection.Process.Name

        • Connection.Process.Path

        • Connection.Process.FullPathName

        • Connection.Process.CommandLine

      • target is registry and criteriaList contains an Object whose field has one of the following values:

        • Registry.CreatedBy.Name

        • Registry.CreatedBy.Path

        • Registry.CreatedBy.FullPathName

        • Registry.CreatedBy.CommandLine

    • 4 - Kill process

      Important

      Available only under one of the following conditions:

      • target is process

      • target is connection and criteriaList contains an Object whose field has one of the following values:

        • Connection.Process.Name

        • Connection.Process.Path

        • Connection.Process.FullPathName

        • Connection.Process.CommandLine

      • target is registry and criteriaList contains an Object whose field has one of the following values:

        • Registry.CreatedBy.Name

        • Registry.CreatedBy.Path

        • Registry.CreatedBy.FullPathName

        • Registry.CreatedBy.CommandLine

      • target is file and criteriaList contains an Object whose field has one of the following values:

        • File.CreatedBy.Name

        • File.CreatedBy.Path

        • File.CreatedBy.FullPathName

        • File.CreatedBy.CommandLine

    • 5 - Antimalware scan

    • 6 - Quarantine

      Important

      Available only under one of the following conditions:

      • target is process or file

      • target is connection and criteriaList contains an Object whose field has one of the following values:

        • Connection.Process.Name

        • Connection.Process.Path

        • Connection.Process.FullPathName

        • Connection.Process.CommandLine

      • target is registry and criteriaList contains an Object whose field has one of the following values:

        • Registry.CreatedBy.Name

        • Registry.CreatedBy.Path

        • Registry.CreatedBy.FullPathName

        • Registry.CreatedBy.CommandLine

    • 7 - Risk scan

  • enabled (Boolean) - When true, the action specified by type is enabled for incidents generated by this rule.

  • settings (Object) - Allows further customization of the automatic action for specific action types.

    Fields and possible values for each action type:

    • If type is 4:

      • includeParent (Boolean) - If true, the action also applies to the parent of the targeted process.

      • includeChildren (Boolean) - If true, the action also applies to the children of the targeted process.

    • If type is 5, the type (Integer) field is available under settings:

      • 1 - Quick scan

      • 2 - Full scan

    • If type is 6 and one of the following conditions is met:

      • target is process

      • target is connection and criteriaList contains an Object whose field has one of the following values:

        • Connection.Process.Name

        • Connection.Process.Path

        • Connection.Process.FullPathName

        • Connection.Process.CommandLine

      • target is registry and criteriaList contains an Object whose field has one of the following values:

        • Registry.CreatedBy.Name

        • Registry.CreatedBy.Path

        • Registry.CreatedBy.FullPathName

        • Registry.CreatedBy.CommandLine

      • target is file and criteriaList contains an Object whose field has one of the following values:

        • File.CreatedBy.Name

        • File.CreatedBy.Path

        • File.CreatedBy.FullPathName

        • File.CreatedBy.CommandLine

      The following fields are available:

      • includeParent (Boolean) - If true, the action also applies to the parent of the targeted process.

      • includeChildren (Boolean) - If true, the action also applies to the children of the targeted process.

targets

Name

Description

Included in request

Type

Values

companiesIds

The IDs of the companies to which the custom rule applies.

Optional

Array of Strings

Default value: a list with one entry, representing your company ID.

Return value

This method returns either the ID of the newly created rule (String) or a Boolean value which is true if the creation of the custom rule was successful.

Example

Request:

{
     "params": {
         "companyId": "669fa6bb98b4ed9eb90b85b2",
         "type": 1,
         "name": "Detection Rule via API",
         "description": "Detection Rule via API Description",
         "settings": {
             "status": 0,
             "severity": 1,
             "target": "file",
             "automaticActions": [
                 {
                     "type": 1,
                     "enabled": true
                 }  
             ],
             "criteriaList": [
                 {
                     "field": "File.Name",
                     "relation": "is",
                     "value": "abcd"
                 }
             ],
             "filters": [
                 {
                     "field": "detection",
                     "value": "test-api"
                 }
             ]
         },
         "targets": {
            "companiesIds": [
                "61827b8036492c2fc0718722",
                "61827b8036492c2fc0718722"
            ]
        },
        "returnRuleId": true
    },
    "jsonrpc": "2.0",
    "method": "createCustomRule",
    "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810"
}

Response:

{
    "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810",
    "jsonrpc": "2.0",
    "result": "6372b7a3897aaa77ee021642"
}
In this section: