Skip to main content

updateCustomRule

You can use this method to edit any existing custom exclusion or detection rule by referencing its Rule ID.

Parameters

Parameter

Description

Included in request

Type

Values

ruleId

The ID of the rule to be updated.

Mandatory

String

No additional requirements.

type

The type of the rule to be updated.

Mandatory for detection rules, optional for exclusion rules

Integer

Possible values:

  • 1 - Detection

  • 2 - Exclusion

Default value: 2.

name

The rule’s new name

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 new 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 new 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.

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 sensors:

      • The Azure AD sensor

      • The Google Cloud Platform sensor

      • The Office 365 sensor

      • The Google Workspace sensor

      • The AWS sensor

  • 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 sensors:

      • The Azure AD sensor

      • The Office 365 sensor

      • The Google Workspace sensor

  • application

    Important

    Requires a license that provides at least one of these sensors:

    • The Azure AD sensor

    • The Office 365 sensor

  • key vault

    Important

    Requires a license providing the Azure Cloud sensor.

  • role

    Important

    Requires a license that provides at least one of these sensors:

    • The Atlassian Cloud sensor

    • The Azure AD sensor

    • The Azure Cloud sensor

    • The Google Workspace sensor

    • The Google Cloud Platform sensor

    • The AWS sensor

  • policy

    Important

    Requires a license that provides at least one of these sensors:

    • The Azure AD sensor

    • The AWS sensor

    • The Google Cloud Platform sensor

    • The Office 365 sensor

  • sharing link

    Important

    Requires a license providing the Office 365 sensor.

  • url

    Important

    Requires a license that provides at least one of these sensors:

    • The Office 365 sensor

    • The Google Workspace sensor

  • ssh key

    Important

    Requires a license providing the AWS sensor.

  • launch template

    Important

    Requires a license providing the AWS sensor.

  • service principal

    Important

    Requires a license that provides at least one of these sensors:

    • The Google Workspace sensor

    • The Google Cloud Platform sensor

    • The Azure AD sensor

  • user group

    Important

    Requires a license that provides at least one of these sensors:

    • The Azure AD sensor

    • The Atlassian Cloud sensor

    • The Google Workspace sensor

    • The AWS sensor

  • automation account

    Important

    Requires a license providing the Azure Cloud sensor.

  • automation account hook

    Important

    Requires a license providing the Azure Cloud sensor.

  • certificate authority

    Important

    Requires a license that provides at least one of these sensors:

    • The Azure AD sensor

    • The AWS sensor

  • api

  • bucket

    Important

    Requires a license providing the AWS sensor.

  • jira project

    Important

    Requires a license providing the Atlassian Cloud sensor.

  • confluence page

    Important

    Requires a license providing the Atlassian Cloud sensor.

Possible values available only for custom exclusion rules:

  • flow

    Important

    Requires a license providing the Office 365 sensor.

  • 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

Attribute

Type

Description

result

Boolean

Returns true when the custom rule is updated successfully. Otherwise it returns false.

Example

Request

{
    "params": {
        "ruleId": "61827b8036492c2fc0718722",
        "type": 1,
        "name": "Detection Rule via API",
        "description": "description test API",
        "tags": ["test", "api", "demo"],
        "settings": {
            "status": 1,
            "severity": 1,
            "target": "connection",
            "criteriaList": [
                {
                    "field": "Connection.DestinationPort",
                    "relation": "is",
                    "value": "25691"
                },
                {
                    "field": "Connection.Process.Name",
                    "relation": "contains",
                    "value": "./network1"
                },
                {
                    "field": "Connection.SourcePort",
                    "relation": "any",
                    "value": [
                        "22",
                        "23",
                        "24"
                    ]
                }
            ],
            "automaticActions": [
                {
                    "type": 4,
                    "enabled": true,
                    "settings": {
                        "includeParent": false,
                        "includeChildren": true
                    }
                }
            ]
        },
        "targets": {
            "companiesIds": [
                "61827b8036492c2fc0718722",
                "61827b8036492c2fc0718724"
            ]
        }
    },
    "jsonrpc": "2.0",
    "method": "updateCustomRule",
    "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810"
}

Response

{
    "id": "301f7b05-ec02-481b-9ed6-c07b97de2b7b",
    "jsonrpc": "2.0",
    "result": true
}
In this section: