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 item belongs to.

Optional

String

Must be a valid company ID that the user has access to managing.

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

type

The type of rule to create.

Optional

Number

Possible values:

  • 1 - Detection

  • 2 - Exclusion

name

The name of the rule to be created.

Mandatory

String

No additional requirements.

description

The description of the rule.

Optional

String

No additional requirements.

tags

The list of associated tags.

Optional

Array of Strings

No additional requirements.

settings

Contains the settings associated to the rule.

Mandatory

Object

Refer to settings.

returnRuleId

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

Boolean

Optional

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.

Objects

settings

Parameter

Description

Included in request

Type

Values

status

Indicates if the rule is active.

Mandatory

Integer

Possible values:

  • 0 - inactive.

  • 1 - active.

severity

Indicates the severity of the incident that will be created.

Mandatory

Integer

Possible values:

  • 1 - Low

  • 2 - Medium

  • 3 - High

target

Indicates the type of entity you want to target.

Mandatory

String

Possible values:

  • process

  • file

  • connection

  • registry

criteriaList

Contains the criteria on which the rule is based. You can add multiple objects.

Mandatory

Array of Objects

Each object contains the following settings:

  • field - The type of entity the condition applies to.

  • relation - The relationship between the values provided in the field and value parameters, which is needed for the condition to be met.

  • value - A custom value to compare against the value of the entity specified in the field parameter.

Note

For more information on the possible values of criteria list objects, refer to ???

filters

Specifies the details of the exclusions to be implemented for this rule.

Optional

Array of Objects

Each object contains the following settings:

  • field - The type of entity the exclusion applies to. Currently, only the value detection is supported. For this reason, add only one entry in the array.

  • value - A custom value used to compare against the entity specified in the field parameter.

    Note

    For more information on the possible values of the objects in the criteria list, refer to ???

automaticActions

Indicates if and which automatic response actions are enabled for EDR incidents created as a result of this rule.

The actions are only compatible with EDR incidents.

Optional

Array of Objects

Each object contains the following settings:

  • type - Indicates the type of automatic action assigned to the rule.

    Possible values:

    • 1 - Isolate

    • 2 - Collect investigation package

    • 3 - Add to Sandbox

      This option is available only if target is 1 or 2, or if the field setting under the criteriaList object contains a creation process rule (for connections and registries).

    • 4 - Kill process

      This option is available only if target is 1, or if the field setting under the criteriaList object contains a creation process rule (for files, connections and registries).

    • 5 - Scan

    • 6 - Quarantine

      This option is available only if target is 1 or 2, or if the field setting under the criteriaList object contains a creation process rule (for connections and registries).

    • 7 - Risk scan

  • enabled - If true, the action specified by the type setting is enabled for the incidents created as a result of this rule.

  • settings - This object allows you to further customize the automatic action and is available only for specific action types.

    Possible values:

    • If type is 4 (Kill process):

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

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

    • If type is 5 (Scan):

      • 1 - Quick scan

      • 2 - Full scan

    • If type is 6 (Quarantine) and target is 1, or if the field setting under the criteriaList object contains a creation process rule (for files, connections and registries):

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

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

Companies using a Bitdefender EDR subscription or a GravityZone EDR Cloud license do not have access to automatic actions.

Detections and exclusions

Detection (type =1)

Exclusion (type=2)

Display Name

Target

Field

Technology

Relation

Validator

No

Yes

Alert name

N/A

detection

Both

is

Yes

Yes

Name

process

Process.Name

EDR

is |contains| any

string

Yes

Yes

Path

process

Process.Path

EDR

is |contains| any

string

Yes

Yes

Full Path Name

process

Process.FullPathName

EDR

is |contains| any

string

Yes

Yes

Command Line

process

Process.CommandLine

EDR

is |contains| any

string

Yes

Yes

Parent Name

process

Process.Parent.Name

EDR

is |contains| any

string

Yes

Yes

Parent Path

process

Process.Parent.Path

EDR

is |contains| any

string

Yes

Yes

Paret Full Path Name

process

Process.Parent.FullPathName

EDR

is |contains| any

string

Yes

Yes

Parent Command Line

process

Process.Parent.CommandLine

EDR

is |contains| any

string

No

Yes

File.Name

process

Process.User

EDR

is |contains| any

string

No

Yes

File.Path

process

Process.MD5

EDR

is |contains| any

string

No

Yes

SHA256

process

Process.SHA2

EDR

is | contains | any

string

Yes

Yes

Name

file

File.Name

Both

is | contains | any

string

Yes

Yes

Path

file

File.Path

Both

is | contains | any

string

Yes

Yes

Full Path Name

file

File.FullPathName

Both

is |contains| any

string

Yes

Yes

Creation Process Name

file

File.CreatedBy.Name

EDR

is |contains| any

string

Yes

Yes

Creation Process Path

file

File.CreatedBy.Path

EDR

is |contains| any

string

Yes

Yes

Creation Process Full Path Name

file

File.CreatedBy.FullPathName

EDR

is |contains| any

string

Yes

Yes

Creation Process Command Line

file

File.CreatedBy.CommandLine

EDR

is |contains| any

string

No

Yes

Operation

file

File.Operation

Note

This field must contain this exact value: create, read, write, move, rename, copy.

EDR

is | any

string

No

Yes

MD5

file

File.MD5

XDR

is | contains | any

string

No

Yes

SHA256

file

File.SHA256

XDR

is | contains | any

string

No

Yes

Url

file

File.Url

XDR

is | contains | any

string

No

Yes

Creation process user

file

File.CreatedBy.User

EDR

is | contains | any

string

Yes

Yes

Source IP

connection

Connection.SourceIP

Both

is |contains| any

valid IP

Yes

Yes

Destination IP

connection

Connection.DestinationIP

Both

is |contains| any

valid IP

Yes

Yes

Source Port

connection

Connection.SourcePort

EDR

is |contains| any

integer between 0 and 65,535

Yes

Yes

Destination Port

connection

Connection.DestinationPort

EDR

is |contains| any

integer between 0 and 65,535

Yes

Yes

Creation Process Name

connection

Connection.Process.Name

EDR

is |contains| any

string

Yes

Yes

Creation Process Path

connection

Connection.Process.Path

EDR

is |contains| any

string

Yes

Yes

Creation Process Full Path Name

connection

Connection.Process.FullPathName

EDR

is |contains| any

string

Yes

Yes

Creation Process Command Line

connection

Connection.Process.CommandLine

EDR

is |contains| any

string

No

Yes

Creation process user

connection

Connection.Process.User

EDR

is |contains| any

string

No

Yes

Url

connection

Connection.URL

EDR

is | contains | any

string

No

Yes

HTTP user

connection

Connection.HTTPUser

EDR

is | contains | any

string

No

Yes

HTTP downloaded file

connection

Connection.HTTPDownloadedFile

EDR

is | contains | any

string

No

Yes

HTTP uploaded file

connection

Connection.HTTPUploadedFile

EDR

is | contains | any

string

No

Yes

FTP user

connection

Connection.FTPUser

EDR

is | contains | any

string

No

Yes

SMB domain

connection

Connection.SMBDomain

EDR

is | contains | any

string

No

Yes

SMB share path

connection

Connection.SMBSharePath

EDR

is | contains | any

string

No

Yes

SMB user

connection

Connection.SMBUser

EDR

is | contains | any

string

No

Yes

SSH user

connection

Connection.SSHUser

EDR

is | contains | any

string

No

Yes

WMI exec query

connection

Connection.WMIExecQuery

EDR

is | contains | any

string

No

Yes

Telnet user

connection

Connection.TelnetUser

EDR

is | contains | any

string

No

Yes

File remote operation

connection

Connection.FileRemoteOperation

Note

This field must contain this exact value: create, rem_delete, read, write, move.

EDR

is | any

string

No

Yes

File remote path

connection

Connection.FileRemotePath

EDR

is | contains | any

string

No

Yes

File name

connection

Connection.File.Name

XDR

is | contains | any

string

No

Yes

Email subject

connection

Connection.Email.Subject

XDR

is | contains | any

string

No

Yes

Application name

connection

Connection.Application.Name

XDR

is | contains | any

string

No

Yes

Key vault name

connection

Connection.KeyVault.Name

XDR

is | contains | any

string

No

Yes

Role name

connection

Connection.Role.Name

XDR

is | contains | any

string

No

Yes

Policy name

connection

Connection.Policy.Name

XDR

is | contains | any

string

No

Yes

Sharing link name

connection

Connection.SharingLink.Name

XDR

is | contains | any

string

No

Yes

Flow name

connection

Connection.Flow.Name

XDR

is | contains | any

string

No

Yes

URL name

connection

Connection.Url.Name

XDR

is | contains | any

string

No

Yes

SSH key name

connection

Connection.SshKey.Name

XDR

is | contains | any

string

No

Yes

Launch template name

connection

Connection.LaunchTemplate.Name

XDR

is | contains | any

string

No

Yes

Service principal name

connection

Connection.ServicePrincipal.Name

XDR

is | contains | any

string

No

Yes

User group name

connection

Connection.UserGroup.Name

XDR

is | contains | any

string

No

Yes

Automation account name

connection

Connection.AutomationAccount.Name

XDR

is | contains | any

string

No

Yes

Automation account hook name

connection

Connection.AutomationAccountHook.Name

XDR

is | contains | any

string

No

Yes

Api name

connection

Connection.Api.Name

XDR

is | contains | any

string

No

Yes

Certificate authority name

connection

Connection.CertificateAuthority.Name

XDR

is | contains | any

string

No

Yes

Bucket name

connection

Connection.Bucket.Name

XDR

is | contains | any

string

No

Yes

Source user

connection

Connection.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

connection

Connection.DestinationUser

XDR

is | contains | any

string

Yes

No

Key

registry

Registry.Key

EDR

is | contains | any

string

Yes

No

Value

registry

Registry.Value

EDR

is | contains | any

string

No

No

Creation Process Name

registry

Registry.CreatedBy.Name

EDR

is |contains| any

string

Yes

No

Creation Process Path

registry

Registry.CreatedBy.Path

EDR

is |contains| any

string

Yes

No

Creation Process Full Path Name

registry

Registry.CreatedBy.FullPathName

EDR

is |contains| any

string

Yes

No

Creation Process Command Line

registry

Registry.CreatedBy.CommandLine

EDR

is |contains| any

string

No

Yes

Name

user connection

UserLogin.Name

EDR

is | contains | any

string

No

Yes

Source user

user connection

UserLogin.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

user connection

UserLogin.DestinationUser

XDR

is | contains | any

string

No

Yes

Domain

user connection

UserLogin.Domain

EDR

is | contains | any

string

No

Yes

File name

user connection

UserLogin.File.Name

XDR

is | contains | any

string

No

Yes

Email subject

user connection

UserLogin.Email.Subject

XDR

is | contains | any

string

No

Yes

Application name

user connection

UserLogin.Application.Name

XDR

is | contains | any

string

No

Yes

Key vault name

user connection

UserLogin.KeyVault.Name

XDR

is | contains | any

string

No

Yes

Role name

user connection

UserLogin.Role.Name

XDR

is | contains | any

string

No

Yes

Policy name

user connection

UserLogin.Policy.Name

XDR

is | contains | any

string

No

Yes

Sharing link name

user connection

UserLogin.SharingLink.Name

XDR

is | contains | any

string

No

Yes

Flow name

user connection

UserLogin.Flow.Name

XDR

is | contains | any

string

No

Yes

URL name

user connection

UserLogin.Url.Name

XDR

is | contains | any

string

No

Yes

SSH key name

user connection

UserLogin.SshKey.Name

XDR

is | contains | any

string

No

Yes

Launch template name

user connection

UserLogin.LaunchTemplate.Name

XDR

is | contains | any

string

No

Yes

Service principal name

user connection

UserLogin.ServicePrincipal.Name

XDR

is | contains | any

string

No

Yes

User group name

user connection

UserLogin.UserGroup.Name

XDR

is | contains | any

string

No

Yes

Automation account name

user connection

UserLogin.AutomationAccount.Name

XDR

is | contains | any

string

No

Yes

Automation account hook name

user connection

UserLogin.AutomationAccountHook.Name

XDR

is | contains | any

string

No

Yes

Api name

user connection

UserLogin.Api.Name

XDR

is | contains | any

string

No

Yes

Certificate authority name

user connection

UserLogin.CertificateAuthority.Name

XDR

is | contains | any

string

No

Yes

Bucket name

user connection

UserLogin.Bucket.Name

XDR

is | contains | any

string

No

Yes

Source IP

user connection

UserLogin.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

user connection

UserLogin.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Subject

email

Email.Subject

Both

is | contains | any

string

No

Yes

Sender

email

Email.Sender

Both

is | contains | any

string

No

Yes

Receiver

email

Email.Receivers

Both

is | contains | any

string

No

Yes

Attachment

email

Email.Attachments

Both

is | contains | any

string

No

Yes

Url

email

Email.Url

XDR

is | contains | any

string

No

Yes

Name

application

Application.Name

XDR

is | contains | any

string

No

Yes

Id

application

Application.Id

XDR

is | contains | any

string

No

Yes

Application address

application

Application.Address

XDR

is | contains | any

string

No

Yes

Source user

application

Application.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

application

Application.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

application

Application.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

application

Application.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Name

key vault

KeyVault.Name

XDR

is | contains | any

string

No

Yes

Source user

key vault

KeyVault.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

key vault

KeyVault.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

key vault

KeyVault.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

key vault

KeyVault.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Name

role

Role.Name

XDR

is | contains | any

string

No

Yes

Id

role

Role.Id

XDR

is | contains | any

string

No

Yes

Source user

role

Role.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

role

Role.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

role

Role.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

role

Role.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Name

policy

Policy.Name

XDR

is | contains | any

string

No

Yes

Id

policy

Policy.Id

XDR

is | contains | any

string

No

Yes

Resource policy type

policy

Policy.ResourcePolicyType

XDR

is | contains | any

string

No

Yes

Source user

policy

Policy.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

policy

Policy.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

policy

Policy.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

policy

Policy.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Name

sharing link

SharingLink.Name

XDR

is | contains | any

string

No

Yes

Url

sharing link

SharingLink.Url

XDR

is | contains | any

string

No

Yes

Source user

sharing link

SharingLink.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

sharing link

SharingLink.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

sharing link

SharingLink.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

sharing link

SharingLink.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Name

flow

Flow.Name

XDR

is | contains | any

string

No

Yes

Id

flow

Flow.Id

XDR

is | contains | any

string

No

Yes

Url

flow

Flow.Url

XDR

is | contains | any

string

No

Yes

Source user

flow

Flow.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

flow

Flow.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

flow

Flow.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

flow

Flow.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Name

flow

Url.Name

XDR

is | contains | any

string

No

Yes

Url

url

Url.Url

XDR

is | contains | any

string

No

Yes

Source user

url

Url.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

url

Url.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

url

Url.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

url

Url.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Name

SSH key

SshKey.Name

XDR

is | contains | any

string

No

Yes

SSH public key

SSH key

SshKey.PublicKey

XDR

is | contains | any

string

No

Yes

Source user

SSH key

SshKey.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

SSH key

SshKey.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

SSH key

SshKey.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

SSH key

SshKey.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Name

launch template

LaunchTemplate.Name

XDR

is | contains | any

string

No

Yes

Id

launch template

LaunchTemplate.Id

XDR

is | contains | any

string

No

Yes

Source user

launch template

LaunchTemplate.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

launch template

LaunchTemplate.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

launch template

LaunchTemplate.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

launch template

LaunchTemplate.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Name

service principal

ServicePrincipal.Name

XDR

is | contains | any

is | contains | any

No

Yes

Id

service principal

ServicePrincipal.Id

XDR

is | contains | any

string

No

Yes

Source user

service principal

ServicePrincipal.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

service principal

ServicePrincipal.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

service principal

ServicePrincipal.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

service principal

ServicePrincipal.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Name

user group

UserGroup.Name

XDR

is | contains | any

string

No

Yes

Id

user group

UserGroup.Id

XDR

is | contains | any

string

No

Yes

Source user

user group

UserGroup.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

user group

UserGroup.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

user group

UserGroup.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

user group

UserGroup.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Name

automation account

AutomationAccount.Name

XDR

is | contains | any

string

No

Yes

Id

automation account

AutomationAccount.Id

XDR

is | contains | any

string

No

Yes

Source user

automation account

AutomationAccount.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

automation account

AutomationAccount.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

automation account

AutomationAccount.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

automation account

AutomationAccount.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Name

automation account hook

AutomationAccountHook.Name

XDR

is | contains | any

string

No

Yes

Id

automation account hook

AutomationAccountHook.Id

XDR

is | contains | any

string

No

Yes

Source user

automation account hook

AutomationAccountHook.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

automation account hook

AutomationAccountHook.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

automation account hook

AutomationAccountHook.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

automation account hook

AutomationAccountHook.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Name

API

Api.Name

XDR

is | contains | any

string

No

Yes

Id

API

Api.Id

XDR

is | contains | any

string

No

Yes

Destination user

API

Api.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

API

Api.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

API

Api.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Name

certificate authority

CertificateAuthority.Name

XDR

is | contains | any

string

No

Yes

Source user

certificate authority

CertificateAuthority.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

certificate authority

CertificateAuthority.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

certificate authority

CertificateAuthority.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

certificate authority

CertificateAuthority.DestinationIP

XDR

is | contains | any

valid IP

No

Yes

Name

bucket

Bucket.Name

XDR

is | contains | any

string

No

Yes

Source user

bucket

Bucket.SourceUser

XDR

is | contains | any

string

No

Yes

Destination user

bucket

Bucket.DestinationUser

XDR

is | contains | any

string

No

Yes

Source IP

bucket

Bucket.SourceIP

XDR

is | contains | any

valid IP

No

Yes

Destination IP

bucket

Bucket.DestinationIP

XDR

is | contains | any

valid IP

Note

The any operator implies an array.

Return value

This method returns the ID of the newly created rule 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"
                     ]
                 }
             ]
         },
         "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: