Skip to main content

getCustomRulesList

This method retrieves the list of custom rules for a specified company.

Parameters

Parameter

Description

Included in request

Type

Values

companyId

The ID of the company for which to retrieve the list of custom rules.

Optional

String

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

Defaults to the ID of the company associated with the user making the API request.

type

Specifies the type of custom rules to retrieve.

Optional

Integer

Possible values:

  • 1 - Detection

  • 2 - Exclusion

Default value: 2.

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.

Under the params object

page

The results page number.

Optional

Integer

Default value: 1.

perPage

The number of results displayed per page.

Optional

Integer

The upper limit is 1000 items per page.

Default value: 1000.

Return value

Attribute

Type

Description

result

Object

Includes the total number of custom rules, the current page, the total number of available pages, the number of items per page, and a detailed list of custom rules. Refer to result.

Objects

result

Attribute

Type

Description

total

Integer

The total count of custom rules found.

page

Integer

The current page displayed.

perPage

Integer

The number of items per page.

pagesCount

Integer

The total number of available pages.

items

Array of Objects

The detailed list of custom rules.

Each object contains the following settings:

  • id (String) - The ID of the custom rule.

  • name (String) - The name of the custom rule.

  • owner (String) - The username of the user who originally created the rule.

  • description (String) - The description of the custom rule.

  • companyId (String) - The ID of the company the custom rule belongs to.

  • tags (Array of Strings) - The list of associated rule tags.

  • settings (Object) - Contains the settings associated with the custom rule. Refer to settings.

  • targets (Object) - Contains companies, which lists the companies to which the custom rule applies, or companyId, the ID of the company to which the custom rule applies. Refer to targets.

settings

Attribute

Type

Description

Values

status

Integer

Indicates if the rule is active.

Possible values:

  • 0 - Inactive

  • 1 - Active

severity

Integer

Indicates the severity of the alerts determined by the rule.

Possible values:

  • 1 - Low

  • 2 - Medium

  • 3 - High

target

String

Indicates the type of the target entity.

Possible values for custom exclusion rules:

  • process

  • file

  • connection

  • registry

  • user connection

  • email

  • application

  • key vault

  • role

  • policy

  • sharing link

  • url

  • flow

  • ssh key

  • launch template

  • service principal

  • user group

  • automation account

  • automation account hook

  • certificate authority

  • api

  • bucket

  • bitbucket repository

  • jira project

  • confluence page

Possible values for custom detection rules:

  • process

  • file

  • connection

  • registry

criteriaList

Array of Objects

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

Important

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

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 more information on the possible values of criteriaList objects, refer to the Detections and exclusions section of the createCustomRule page.

enableAutomaticActions

Boolean

Indicates whether automatic actions are enabled for the custom rule.

true if automatic actions are enabled for the custom rule, false otherwise.

filters

Array of Objects

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

Each object 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.

automaticActions

Array of Objects

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

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

    • 4 - Kill process

    • 5 - Antimalware scan

    • 6 - Quarantine

    • 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 or 6:

      • 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

targets

Attribute

Type

Description

companies

Array of Objects

The companies to which the custom rule applies.

Each object contains the following settings:

  • name (String) - The name of the company.

  • id (String) - The ID of the company.

companyId

String

The ID of the company to which the custom rule applies.

Example

Request:

{
    "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810",
    "jsonrpc": "2.0",
    "method": "getCustomRulesList",
    "params": {
        "companyId": "697336d571ead2fb3b0af682",
        "type": 1
    }
}

Response:

{
  "id": "0df7568c-59c1-48e0-a31b-18d83e6d9810",
  "jsonrpc": "2.0",
  "result": {
    "total": 2,
    "page": 1,
    "perPage": 30,
    "pagesCount": 1,
    "items": [
      { 
        "id": "697350d9a38792d6380b67a2",
        "name": "customer rule customer",
        "owner": "dada@dada.com",
        "description": "description",
        "companyId": "697336d571ead2fb3b0af682",
        "tags": [
          "dddd"
        ],
        "settings": {
          "status": 1,
          "target": "process",
          "criteriaList": [
            {
              "field": "Process.CommandLine",
              "relation": "is",
              "value": [
                "ddd"
              ]
            }
          ],
          "severity": 3,
          "enableAutomaticActions": true,
          "automaticActions": [
            {
              "type": 1,
              "enabled": false
            },
            {
              "type": 2,
              "enabled": false
            },
            {
              "type": 3,
              "enabled": true
            },
            {
              "type": 4,
              "enabled": true,
              "settings": {
                "includeParent": false,
                "includeChildren": false
              }
            },
            {
              "type": 5,
              "enabled": true,
              "settings": {
                "type": 1
              }
            },
            {
              "type": 6,
              "enabled": false,
              "settings": {
                "includeParentProcess": false,
                "includeChildrenProcesses": false
              }
            },
            {
              "type": 7,
              "enabled": false
            }
          ]
        },
        "targets": {
          "companyId": "697336d571ead2fb3b0af682"
        }
      },
      {
        "id": "69733ac915c88f4ec90a86a2",
        "name": "detection rule customer",
        "owner": "vagrant@bitdefender.com",
        "description": "description",
        "companyId": "69733509887b1b53750f5424",
        "tags": [],
        "settings": {
          "status": 1,
          "target": "process",
          "criteriaList": [
            {
              "field": "Process.CommandLine",
              "relation": "is",
              "value": [
                "comm"
              ]
            }
          ],
          "severity": 3,
          "enableAutomaticActions": true,
          "automaticActions": [
            {
              "type": 1,
              "enabled": false
            },
            {
              "type": 2,
              "enabled": false
            },
            {
              "type": 3,
              "enabled": false
            },
            {
              "type": 4,
              "enabled": true,
              "settings": {
                "includeParent": false,
                "includeChildren": false
              }
            },
            {
              "type": 5,
              "enabled": true,
              "settings": {
                "type": 1
              }
            },
            {
              "type": 6,
              "enabled": true,
              "settings": {
                "includeParentProcess": false,
                "includeChildrenProcesses": false
              }
            },
            {
              "type": 7,
              "enabled": false
            }
          ]
        },
        "targets": {
          "companies": [
            {
              "_id": "69733509887b1b53750f5424",
              "name": "Bitdefender"
            },
            {
              "_id": "697336d571ead2fb3b0af682",
              "name": "comp1"
            },
            {
              "_id": "69734c0c7d05800e210ea512",
              "name": "comp2"
            }
          ]
        }
      }
    ]
  }
}
In this section: