Skip to main content

createReconfigureClientTask

This method creates a new Reconfigure Agent task. With this task you can choose which modules to install on target agents.

Important

This main section of this article article contains information for the 1.1 version of the method. You can find information for version 1.0 here.

Warning

The networkMonitor module is deprecated. It is recommended to use networkAttackDefense instead.

Parameters

Parameter

Type

Optional

Description

targetIds

Array

No

The endpoint or container IDs, for which you want to reconfigure the agents.

scheduler

Object

Yes

The task scheduler settings. The object contains the following fields:

  • type, an Integer with one of the following values:

    • 1 for immediate run (default)

    • 2 for scheduled

    If type is 1, you can omit the other fields.

  • recurrence, an Integer with one of the following values:

    • 1 for hourly. This value requires everyHour to be set.

    • 2 for daily. This value requires startTime to be set.

    • 3 for weekly. This value requires both everyHour and startTime to be set.

  • everyHour, an Integer between 1 and 23, representing the interval in hours between two task runs.

  • startTime, a string with the following format: HH:mm, representing the hour of the first task run.

  • onWeekDay, an Integer between 1 and 7, where 1 is Monday and 7 is Sunday.

If this parameter is omitted, the task runs immediately.

modules

Object

Yes

The modules to be enabled or disabled. The object contains the following fields:

  • antimalware

  • advancedThreatControl

  • firewall

  • contentControl

  • deviceControl

  • powerUser

  • encryption

  • advancedAntiExploit

  • containerProtection

  • edrSensor

  • patchManagement

  • networkAttackDefense

  • integrityMonitoring

Each field may have the value 1 for enabled, or 0 for disabled. If the module is omitted, it is considered disabled.

scanMode

Object

Yes

The settings for the scanning engines. The object contains the following fields:

  • type, an Integer with one of the following values:

    • 1 for automatic configuration (default)

    • 2 for custom settings. This value requires the computers and vms fields

    If omitted, the default values will be used.

  • vms, an Object described below.

  • computers, an Object described below.

The objects computers and vms have the following fields:

  • main, an Integer with one of the following values:

    • 1 for Central Scanning (with Security Server)

    • 2 for Hybrid Scanning (light engines)

    • 3 for Local Scanning (full engines)

  • fallback, an Integer with one of the following values:

    • 2 for Hybrid Scanning (light engines)

    • 3 for Local Scanning (full engines)

If main has the value 2 or 3, then fallback is not considered.

roles

Object

Yes

The roles to be enabled or disabled on the agent:

  • relay with the following possible values:

    • 1 for enabled

    • 0 for disabled (default)

  • exchange with the following possible values:

    • 1 for enabled

    • 0 for disabled (default)

    This role is available only with a valid Security for Exchange license.

productType

Number

Yes

This parameter determines the operation mode of the security agent. Possible values:

  • 0 - for Detection and prevention mode, default for full endpoint security agents.

  • 3 - for EDR (Report only) mode, default for Bitdefender EDR agents.

For additional information, refer to Parameter info.

Parameter info

  • Bitdefender EDR users can only run tasks that reconfigure target security agents to operate in EDR (Report only) mode; specifying productType is optional.

  • GravityZone BS / ABS / Elite users can only run tasks that reconfigure target security agents to operate in Detection and prevention mode; specifying productType is optional.

  • GravityZone Ultra / Ultra Plus users can reconfigure target security agents to operate in both operation modes.

    • productType must be specified for EDR (Report only) mode reconfiguration.

    • In case of selecting endpoints running different operation modes, if productType is not specified, the EDR (Report only) endpoints will be reconfigured to run in Detection and prevention mode.

  • The EDR (Report only) mode includes by default a set of predefined parameters that will overwrite user-specified options. Predefined parameters:

    • modules

      • edrSensor - true

      • contentControl - true

      • networkAttackDefense - true

      • advancedThreatControl - true

      • other modules - false

    • scanMode - n/a

    • roles.exchange - false

  • The integrityMonitoring module is not available for product type EDR (Report only).

Return value

This method returns an array of parent task ids of the created tasks.

Example

Request:

{
     "params": {
         "targetIds": [
             "5d7244b10ea1de153817c072"
         ],
         "scheduler": {
             "type": 1
         },
         "modules": {
           "advancedThreatControl": 1,
           "firewall": 1,
           "contentControl": 1,
           "deviceControl": 1,
           "powerUser": 1,
           "encryption": 1,
           "advancedAntiExploit": 1,
           "containerProtection": 1,
           "edrSensor": 1,
           "patchManagement": 1,
           
           "networkAttackDefense": 1
           "integrityMonitoring: 1
         },
         "scanMode": {
             "type": 1
         },
         "roles": {
             "relay": 0,
             "exchange": 0
         },
         "productType": 0
     },
     "jsonrpc": "2.0",
     "method": "createReconfigureClientTask",
     "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f"
  }

Response:

{
      "id": "5787b5e36-89a8-4353-88b9-6b7a32e9c87f",
      "jsonrpc":"2.0",
      "result": [
          "652feab6b9684f3ba80685d5",
          "652feab6b9684f3ba80685d4"
      ]
}

Version 1.0

Parameters

Parameter

Type

Optional

Description

targetIds

Array

No

The endpoint or container IDs, for which you want to reconfigure the agents.

scheduler

Object

Yes

The task scheduler settings. The object contains the following fields:

  • type, an Integer with one of the following values:

    • 1 for immediate run (default)

    • 2 for scheduled

    If type is 1, you can omit the other fields.

  • recurrence, an Integer with one of the following values:

    • 1 for hourly. This value requires everyHour to be set.

    • 2 for daily. This value requires startTime to be set.

    • 3 for weekly. This value requires both everyHour and startTime to be set.

  • everyHour, an Integer between 1 and 23, representing the interval in hours between two task runs.

  • startTime, a string with the following format: HH:mm, representing the hour of the first task run.

  • onWeekDay, an Integer between 1 and 7, where 1 is Monday and 7 is Sunday.

If this parameter is omitted, the task runs immediately.

modules

Object

Yes

The modules to be enabled or disabled. The object contains the following fields:

  • antimalware

  • advancedThreatControl

  • firewall

  • contentControl

  • deviceControl

  • powerUser

  • encryption

  • advancedAntiExploit

  • containerProtection

  • edrSensor

  • patchManagement

  • networkAttackDefense

  • integrityMonitoring

Each field may have the value 1 for enabled, or 0 for disabled. If the module is omitted, it is considered disabled.

scanMode

Object

Yes

The settings for the scanning engines. The object contains the following fields:

  • type, an Integer with one of the following values:

    • 1 for automatic configuration (default)

    • 2 for custom settings. This value requires the computers and vms fields

    If omitted, the default values will be used.

  • vms, an Object described below.

  • computers, an Object described below.

The objects computers and vms have the following fields:

  • main, an Integer with one of the following values:

    • 1 for Central Scanning (with Security Server)

    • 2 for Hybrid Scanning (light engines)

    • 3 for Local Scanning (full engines)

  • fallback, an Integer with one of the following values:

    • 2 for Hybrid Scanning (light engines)

    • 3 for Local Scanning (full engines)

If main has the value 2 or 3, then fallback is not considered.

roles

Object

Yes

The roles to be enabled or disabled on the agent:

  • relay with the following possible values:

    • 1 for enabled

    • 0 for disabled (default)

  • exchange with the following possible values:

    • 1 for enabled

    • 0 for disabled (default)

    This role is available only with a valid Security for Exchange license.

productType

Number

Yes

This parameter determines the operation mode of the security agent. Possible values:

  • 0 - for Detection and prevention mode, default for full endpoint security agents.

  • 3 - for EDR (Report only) mode, default for Bitdefender EDR agents.

For additional information, refer to Parameter info.

Parameter info

  • Bitdefender EDR users can only run tasks that reconfigure target security agents to operate in EDR (Report only) mode; specifying productType is optional.

  • GravityZone BS / ABS / Elite users can only run tasks that reconfigure target security agents to operate in Detection and prevention mode; specifying productType is optional.

  • GravityZone Ultra / Ultra Plus users can reconfigure target security agents to operate in both operation modes.

    • productType must be specified for EDR (Report only) mode reconfiguration.

    • In case of selecting endpoints running different operation modes, if productType is not specified, the EDR (Report only) endpoints will be reconfigured to run in Detection and prevention mode.

  • The EDR (Report only) mode includes by default a set of predefined parameters that will overwrite user-specified options. Predefined parameters:

    • modules

      • edrSensor - true

      • contentControl - true

      • networkAttackDefense - true

      • advancedThreatControl - true

      • other modules - false

    • scanMode - n/a

    • roles.exchange - false

  • The integrityMonitoring module is not available for product type EDR (Report only).

Return value

This method returns a Boolean which is True if the reconfigure task was created successfully for at least one target ID.

Example

Request:

  {
     "params": {
         "targetIds": [
             "5d7244b10ea1de153817c072"
         ],
         "scheduler": {
             "type": 1
         },
         "modules": {
           "advancedThreatControl": 1,
           "firewall": 1,
           "contentControl": 1,
           "deviceControl": 1,
           "powerUser": 1,
           "encryption": 1,
           "advancedAntiExploit": 1,
           "containerProtection": 1,
           "edrSensor": 1,
           "patchManagement": 1,
           
           "networkAttackDefense": 1
           "integrityMonitoring: 1
         },
         "scanMode": {
             "type": 1
         },
         "roles": {
             "relay": 0,
             "exchange": 0
         },
         "productType": 0
     },
     "jsonrpc": "2.0",
     "method": "createReconfigureClientTask",
     "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f"
  }

Response:

  {
     "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
     "jsonrpc":"2.0",
     "result": true
  }
In this section: