Policy Service API


Overview

Policies are where users go to manage their security posture in their organization. Choose one of VMware Carbon Black’s predefined policies as a starting point, and tune its default prevention settings as you see fit in your environment. Often times, users may need to add exceptions for special programs in their environment that perform anomalous behavior. Similarly, users may want to explicitly block certain programs from executing in their environment. Users can leverage the Policies API to achieve all types of policy and sensor setting adjustments.

Key Features

  • Create or modify policies
  • Manage prevention rules on existing policies
  • Adjust sensor settings

Use Cases

  • Add Blocking and Isolation or Permission rules to prevent ransomware-like behavior
  • Adjust the frequency and intensity of signature updates and the local scanner
  • Modify certain sensor behaviors via the sensor settings

Note: To enable USB Device blocking for a policy see Device Control Blocks

Requirements

  • At least one Carbon Black Cloud product
  • Carbon Black Cloud Endpoint Standard to use preventative policy rules

Authentication

Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.


Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • Policy: {cbc-hostname}/policyservice/v1/orgs/{org_key}/policies/

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Policies > Policies > org.policies, allow permission to CREATE, READ, UPDATE, DELETE

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.


Cloud Services Platform Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with OAuth Access Control; API access is controlled using OAuth apps or User API Tokens. This is currently limited to the UK Point of Presence and AWS GovCloud (US).

Environment
Available on Prod UK and AWS GovCloud (US). Full list of environments is available here; Use the Carbon Black Cloud Console URL from Cloud Services Platform, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • Policy: {cbc-hostname}/policyservice/v1/orgs/{org_key}/policies/

Access Level
Before you create your OAuth App, you need to create a custom Role with the following permissions under IDENTITY & ACCESS MANAGEMENT > Roles > VMware Carbon Black Cloud:
  • _API.Policies:org.Policies, allow permission to CREATE, READ, UPDATE AND DELETE

API Authentication
The Cloud Services Platform supports several authentication options, Access Token, API Token, and for backward compatibility, X-Auth-Token. To learn about the differences or how to use the authentication methods see the Authentication Guide.


API Calls

Policies

Create Policy

Create a new policy for protecting endpoints and workloads.

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies CREATE Majority of environments
VMware Cloud Services Platform _API.Policies:org.Policies:create N/A - included in permission name Prod UK and AWS GovCloud (US)

Requests

POST {cbc-hostname}/policyservice/v1/orgs/{org_key}/policies

Request Body 

{
  "name": "<string>",
  "org_key": "<string>",
  "priority_level": "<string>",
  "position": <long>,
  "is_system": <boolean>,
  "description": "<string>",
  "auto_deregister_inactive_vdi_interval_ms": <long>,
  "auto_delete_known_bad_hashes_delay": <long>,
  "av_settings": {
    "avira_protection_cloud": {
      "enabled": <boolean>,
      "max_exe_delay": <long>,
      "max_file_size": <long>,
      "risk_level": <long>
    },
    "on_access_scan": {
      "enabled": <boolean>,
      "mode": "<string>"
    },
    "on_demand_scan": {
      "enabled": <boolean>,
      "profile": "<string>",
      "schedule": {
        "days": [ "<string>" ],
        "start_hour": <long>,
        "range_hours": <long>,
        "recovery_scan_if_missed": <boolean>
      },
      "scan_usb": "<string>",
      "scan_cd_dvd": "<string>"
    },
    "signature_update": {
      "enabled": <boolean>,
      "schedule": {
        "full_interval_hours": <long>,
        "initial_random_delay_hours": <long>,
        "interval_hours": <long>
      }
    },
    "update_servers": {
      "servers_override": [ "<string>" ],
      "servers_for_onsite_devices": [
        {
          "server": "<string>",
          "preferred": <boolean>
        }
      ],
      "servers_for_offsite_devices": [ "<string>" ]
    }
  },
  "rules": [
    {
      "id": <long>,
      "required": <boolean>,
      "action": "<string>",
      "application": {
        "type": "<string>",
        "value": "<string>"
      },
      "operation": "<string>"
    }
  ],
  "directory_action_rules": [
    {
      "file_upload": <boolean>,
      "protection": <boolean>,
      "path": "<string>"
    }
  ],
  "sensor_settings": [
    {
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "managed_detection_response_permissions": {
    "policy_modification": <boolean>,
    "quarantine": <boolean>
  },
  "version": <long>,
  "message": "<string>",
  "rapid_configs": [ "<string>" ]
}

Body Schema

See Policy Fields

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies

Request Body 

{
    "id": 4920125,
    "name": "Standard",
    "org_key": "ABCD1234",
    "priority_level": "MEDIUM",
    "position": -1,
    "is_system": true,
    "description": "Prevents known malware and reduces false positives. Used as the default policy for all new sensors, unless sensor group criteria is met.",
    "auto_deregister_inactive_vdi_interval_ms": 0,
    "auto_delete_known_bad_hashes_delay": null,
    "av_settings": {
        "avira_protection_cloud": {
            "enabled": false,
            "max_exe_delay": 45,
            "max_file_size": 4,
            "risk_level": 4
        },
        "on_access_scan": {
            "enabled": true,
            "mode": "NORMAL"
        },
        "on_demand_scan": {
            "enabled": true,
            "profile": "NORMAL",
            "schedule": {
                "days": null,
                "start_hour": 0,
                "range_hours": 0,
                "recovery_scan_if_missed": true
            },
            "scan_usb": "AUTOSCAN",
            "scan_cd_dvd": "AUTOSCAN"
        },
        "signature_update": {
            "enabled": true,
            "schedule": {
                "full_interval_hours": 0,
                "initial_random_delay_hours": 4,
                "interval_hours": 4
            }
        },
        "update_servers": {
            "servers_override": [],
            "servers_for_onsite_devices": [
                {
                    "server": "http://updates2.cdc.carbonblack.io/update2",
                    "preferred": false
                }
            ],
            "servers_for_offsite_devices": [
                "http://updates2.cdc.carbonblack.io/update2"
            ]
        }
    },
    "rules": [
        {
            "id": 1,
            "required": false,
            "action": "TERMINATE",
            "application": {
                "type": "REPUTATION",
                "value": "KNOWN_MALWARE"
            },
            "operation": "RUN"
        },
        {
            "id": 2,
            "required": false,
            "action": "TERMINATE",
            "application": {
                "type": "REPUTATION",
                "value": "COMPANY_BLACK_LIST"
            },
            "operation": "RUN"
        }
    ],
    "directory_action_rules": [],
    "sensor_settings": [
        {
            "name": "ALLOW_UNINSTALL",
            "value": "true"
        }
    ],
    "managed_detection_response_permissions": {
      "policy_modification": true,
      "quarantine": true
    },
    "version": null,
    "message": null,
    "rapid_configs": []
}

Response 

{
    "id": 4920125,
    "name": "Standard",
    "org_key": "ABCD1234",
    "priority_level": "MEDIUM",
    "position": -1,
    "is_system": true,
    "description": "Prevents known malware and reduces false positives. Used as the default policy for all new sensors, unless sensor group criteria is met.",
    "auto_deregister_inactive_vdi_interval_ms": 0,
    "auto_delete_known_bad_hashes_delay": null,
    "av_settings": {
        "avira_protection_cloud": {
            "enabled": false,
            "max_exe_delay": 45,
            "max_file_size": 4,
            "risk_level": 4
        },
        "on_access_scan": {
            "enabled": true,
            "mode": "NORMAL"
        },
        "on_demand_scan": {
            "enabled": true,
            "profile": "NORMAL",
            "schedule": {
                "days": null,
                "start_hour": 0,
                "range_hours": 0,
                "recovery_scan_if_missed": true
            },
            "scan_usb": "AUTOSCAN",
            "scan_cd_dvd": "AUTOSCAN"
        },
        "signature_update": {
            "enabled": true,
            "schedule": {
                "full_interval_hours": 0,
                "initial_random_delay_hours": 4,
                "interval_hours": 4
            }
        },
        "update_servers": {
            "servers_override": [],
            "servers_for_onsite_devices": [
                {
                    "server": "http://updates2.cdc.carbonblack.io/update2",
                    "preferred": false
                }
            ],
            "servers_for_offsite_devices": [ "http://updates2.cdc.carbonblack.io/update2" ]
        }
    },
    "rules": [
        {
            "id": 1,
            "required": false,
            "action": "TERMINATE",
            "application": {
                "type": "REPUTATION",
                "value": "KNOWN_MALWARE"
            },
            "operation": "RUN"
        },
        {
            "id": 2,
            "required": false,
            "action": "TERMINATE",
            "application": {
                "type": "REPUTATION",
                "value": "COMPANY_BLACK_LIST"
            },
            "operation": "RUN"
        }
    ],
    "directory_action_rules": [],
    "sensor_settings": [
        {
            "name": "ALLOW_UNINSTALL",
            "value": "true"
        }
    ],
    "managed_detection_response_permissions": {
      "policy_modification": true,
      "quarantine": true
    },
    "version": null,
    "message": null,
    "rapid_configs": []
}

Get Policy Summaries

Get an overview of the policies available in the organization

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies READ Majority of environments
VMware Cloud Services Platform _API.Policies:org.Policies:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Requests

GET {cbc-hostname}/policyservice/v1/orgs/{org_key}/policies/summary

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/summary

Response 

{
    "policies": [
        {
            "id": 4920125,
            "is_system": true,
            "name": "Standard",
            "description": "Prevents known malware and reduces false positives. Used as the default policy for all new sensors, unless sensor group criteria is met.",
            "priority_level": "MEDIUM",
            "position": -1,
            "num_devices": 0
        }
    ]
}

Get Policy Details

Get a policy’s details by id

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies READ Majority of environments
VMware Cloud Services Platform _API.Policies:org.Policies:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Requests

GET {cbc-hostname}/policyservice/v1/orgs/{org_key}/policies/{policy_id}

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125

Response 

{
    "id": 4920125,
    "name": "Standard",
    "org_key": "ABCD1234",
    "priority_level": "MEDIUM",
    "position": -1,
    "is_system": true,
    "description": "Prevents known malware and reduces false positives. Used as the default policy for all new sensors, unless sensor group criteria is met.",
    "auto_deregister_inactive_vdi_interval_ms": 0,
    "auto_delete_known_bad_hashes_delay": null,
    "av_settings": {
        "avira_protection_cloud": {
            "enabled": false,
            "max_exe_delay": 45,
            "max_file_size": 4,
            "risk_level": 4
        },
        "on_access_scan": {
            "enabled": true,
            "mode": "NORMAL"
        },
        "on_demand_scan": {
            "enabled": true,
            "profile": "NORMAL",
            "schedule": {
                "days": null,
                "start_hour": 0,
                "range_hours": 0,
                "recovery_scan_if_missed": true
            },
            "scan_usb": "AUTOSCAN",
            "scan_cd_dvd": "AUTOSCAN"
        },
        "signature_update": {
            "enabled": true,
            "schedule": {
                "full_interval_hours": 0,
                "initial_random_delay_hours": 4,
                "interval_hours": 4
            }
        },
        "update_servers": {
            "servers_override": [],
            "servers_for_onsite_devices": [
                {
                    "server": "http://updates2.cdc.carbonblack.io/update2",
                    "preferred": false
                }
            ],
            "servers_for_offsite_devices": [ "http://updates2.cdc.carbonblack.io/update2" ]
        }
    },
    "rules": [
        {
            "id": 1,
            "required": false,
            "action": "TERMINATE",
            "application": {
                "type": "REPUTATION",
                "value": "KNOWN_MALWARE"
            },
            "operation": "RUN"
        },
        {
            "id": 2,
            "required": false,
            "action": "TERMINATE",
            "application": {
                "type": "REPUTATION",
                "value": "COMPANY_BLACK_LIST"
            },
            "operation": "RUN"
        }
    ],
    "directory_action_rules": [],
    "sensor_settings": [
        {
            "name": "ALLOW_UNINSTALL",
            "value": "true"
        }
    ],
    "managed_detection_response_permissions": {
      "policy_modification": true,
      "quarantine": true
    },
    "version": null,
    "message": null,
    "rapid_configs": []
}

Update Policy

Modify an existing policy

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies UPDATE Majority of environments
VMware Cloud Services Platform _API.Policies:org.Policies:update N/A - included in permission name Prod UK and AWS GovCloud (US)

Requests

PUT {cbc-hostname}/policyservice/v1/orgs/{org_key}/policies/{policy_id}

Request Body 

{
  "id": <long>,
  "name": "<string",
  "org_key": "<string>",
  "priority_level": "<string>",
  "position": <long>,
  "is_system": <boolean>,
  "description": "<string>",
  "auto_deregister_inactive_vdi_interval_ms": <long>,
  "auto_delete_known_bad_hashes_delay": <long>,
  "av_settings": {
    "avira_protection_cloud": {
      "enabled": <boolean>,
      "max_exe_delay": <long>,
      "max_file_size": <long>,
      "risk_level": <long>
    },
    "on_access_scan": {
      "enabled": <boolean>,
      "mode": "<string>"
    },
    "on_demand_scan": {
      "enabled": <boolean>,
      "profile": "<string>",
      "schedule": {
        "days": [ "<string>" ],
        "start_hour": <long>,
        "range_hours": <long>,
        "recovery_scan_if_missed": <boolean>
      },
      "scan_usb": "<string>",
      "scan_cd_dvd": "<string>"
    },
    "signature_update": {
      "enabled": <boolean>,
      "schedule": {
        "full_interval_hours": <long>,
        "initial_random_delay_hours": <long>,
        "interval_hours": <long>
      }
    },
    "update_servers": {
      "servers_override": [ "<string>" ],
      "servers_for_onsite_devices": [
        {
          "server": "<string>",
          "preferred": <boolean>
        }
      ],
      "servers_for_offsite_devices": [ "<string>" ]
    }
  },
  "rules": [
    {
      "id": <long>,
      "required": <boolean>,
      "action": "<string>",
      "application": {
        "type": "<string>",
        "value": "<string>"
      },
      "operation": "<string>"
    }
  ],
  "directory_action_rules": [
    {
      "file_upload": <boolean>,
      "protection": <boolean>,
      "path": "<string>"
    }
  ],
  "sensor_settings": [
    {
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "managed_detection_response_permissions": {
    "policy_modification": <boolean>,
    "quarantine": <boolean>
  },
  "version": <long>,
  "message": "<string>",
  "rapid_configs": [ "<string>" ]
}

Body Schema

See Policy Fields

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

PUT https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125

Request Body 

{
    "id": 4920125,
    "name": "Standard",
    "org_key": "ABCD1234",
    "priority_level": "MEDIUM",
    "position": -1,
    "is_system": true,
    "description": "Prevents known malware and reduces false positives. Used as the default policy for all new sensors, unless sensor group criteria is met.",
    "auto_deregister_inactive_vdi_interval_ms": 0,
    "auto_delete_known_bad_hashes_delay": null,
    "av_settings": {
        "avira_protection_cloud": {
            "enabled": false,
            "max_exe_delay": 45,
            "max_file_size": 4,
            "risk_level": 4
        },
        "on_access_scan": {
            "enabled": true,
            "mode": "NORMAL"
        },
        "on_demand_scan": {
            "enabled": true,
            "profile": "NORMAL",
            "schedule": {
                "days": null,
                "start_hour": 0,
                "range_hours": 0,
                "recovery_scan_if_missed": true
            },
            "scan_usb": "AUTOSCAN",
            "scan_cd_dvd": "AUTOSCAN"
        },
        "signature_update": {
            "enabled": true,
            "schedule": {
                "full_interval_hours": 0,
                "initial_random_delay_hours": 4,
                "interval_hours": 4
            }
        },
        "update_servers": {
            "servers_override": [],
            "servers_for_onsite_devices": [
                {
                    "server": "http://updates2.cdc.carbonblack.io/update2",
                    "preferred": false
                }
            ],
            "servers_for_offsite_devices": [ "http://updates2.cdc.carbonblack.io/update2" ]
        }
    },
    "rules": [
        {
            "id": 1,
            "required": false,
            "action": "TERMINATE",
            "application": {
                "type": "REPUTATION",
                "value": "KNOWN_MALWARE"
            },
            "operation": "RUN"
        },
        {
            "id": 2,
            "required": false,
            "action": "TERMINATE",
            "application": {
                "type": "REPUTATION",
                "value": "COMPANY_BLACK_LIST"
            },
            "operation": "RUN"
        }
    ],
    "directory_action_rules": [],
    "sensor_settings": [
        {
            "name": "ALLOW_UNINSTALL",
            "value": "true"
        }
    ],
    "managed_detection_response_permissions": {
      "policy_modification": true,
      "quarantine": true
    },
    "version": null,
    "message": null,
    "rapid_configs": []
}

Response 

{
    "id": 4920125,
    "name": "Standard",
    "org_key": "ABCD1234",
    "priority_level": "MEDIUM",
    "position": -1,
    "is_system": true,
    "description": "Prevents known malware and reduces false positives. Used as the default policy for all new sensors, unless sensor group criteria is met.",
    "auto_deregister_inactive_vdi_interval_ms": 0,
    "auto_delete_known_bad_hashes_delay": null,
    "av_settings": {
        "avira_protection_cloud": {
            "enabled": false,
            "max_exe_delay": 45,
            "max_file_size": 4,
            "risk_level": 4
        },
        "on_access_scan": {
            "enabled": true,
            "mode": "NORMAL"
        },
        "on_demand_scan": {
            "enabled": true,
            "profile": "NORMAL",
            "schedule": {
                "days": null,
                "start_hour": 0,
                "range_hours": 0,
                "recovery_scan_if_missed": true
            },
            "scan_usb": "AUTOSCAN",
            "scan_cd_dvd": "AUTOSCAN"
        },
        "signature_update": {
            "enabled": true,
            "schedule": {
                "full_interval_hours": 0,
                "initial_random_delay_hours": 4,
                "interval_hours": 4
            }
        },
        "update_servers": {
            "servers_override": [],
            "servers_for_onsite_devices": [
                {
                    "server": "http://updates2.cdc.carbonblack.io/update2",
                    "preferred": false
                }
            ],
            "servers_for_offsite_devices": [ "http://updates2.cdc.carbonblack.io/update2" ]
        }
    },
    "rules": [
        {
            "id": 1,
            "required": false,
            "action": "TERMINATE",
            "application": {
                "type": "REPUTATION",
                "value": "KNOWN_MALWARE"
            },
            "operation": "RUN"
        },
        {
            "id": 2,
            "required": false,
            "action": "TERMINATE",
            "application": {
                "type": "REPUTATION",
                "value": "COMPANY_BLACK_LIST"
            },
            "operation": "RUN"
        }
    ],
    "directory_action_rules": [],
    "sensor_settings": [
        {
            "name": "ALLOW_UNINSTALL",
            "value": "true"
        }
    ],
    "managed_detection_response_permissions": {
      "policy_modification": true,
      "quarantine": true
    },
    "version": null,
    "message": null,
    "rapid_configs": []
}

Delete Policy

Delete an existing policy.

Note: You cannot delete predefined policies.

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies DELETE Majority of environments
VMware Cloud Services Platform _API.Policies:org.Policies:delete N/A - included in permission name Prod UK and AWS GovCloud (US)

Requests

DELETE {cbc-hostname}/policyservice/v1/orgs/{org_key}/policies/{policy_id}

Response

Code Description Content-Type Content
204 Successfully deleted policy application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125

Response 

No Content

Rules

Add Policy Rule

Create a new permission or prevention rule in a policy

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies UPDATE Majority of environments
VMware Cloud Services Platform _API.Policies:org.Policies:update N/A - included in permission name Prod UK and AWS GovCloud (US)

Requests

POST {cbc-hostname}/policyservice/v1/orgs/{org_key}/policies/{policy_id}/rules

Request Body 

{
    "required": <boolean>,
    "action": "<string>",
    "application": {
        "type": "<string>",
        "value": "<string>"
    },
    "operation": "<string>"
}

Body Schema

See Rule Fields

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rules

Request Body 

{
    "required": false,
    "action": "TERMINATE",
    "application": {
        "type": "REPUTATION",
        "value": "SUSPECT_MALWARE"
    },
    "operation": "RUN"
}

Response 

{
    "id": 3,
    "required": false,
    "action": "TERMINATE",
    "application": {
        "type": "REPUTATION",
        "value": "SUSPECT_MALWARE"
    },
    "operation": "RUN"
}

Update Policy Rule

Update an existing permission or prevention rule in a policy

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies UPDATE Majority of environments
VMware Cloud Services Platform _API.Policies:org.Policies:update N/A - included in permission name Prod UK and AWS GovCloud (US)

Requests

PUT {cbc-hostname}/policyservice/v1/orgs/{org_key}/policies/{policy_id}/rules/{rule_id}

Request Body 

{
    "id": <long>,
    "required": <boolean>,
    "action": "<string>",
    "application": {
        "type": "<string>",
        "value": "<string>"
    },
    "operation": "<string>"
}

Body Schema

See Rule Fields

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

PUT https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rules/3

Request Body 

{
    "id": 3,
    "required": false,
    "action": "DENY",
    "application": {
        "type": "REPUTATION",
        "value": "SUSPECT_MALWARE"
    },
    "operation": "RUN"
}

Response 

{
    "id": 3,
    "required": false,
    "action": "DENY",
    "application": {
        "type": "REPUTATION",
        "value": "SUSPECT_MALWARE"
    },
    "operation": "RUN"
}

Delete Policy Rule

Delete an existing permission or prevention rule in a policy

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies UPDATE Majority of environments
VMware Cloud Services Platform _API.Policies:org.Policies:update N/A - included in permission name Prod UK and AWS GovCloud (US)

Requests

DELETE {cbc-hostname}/policyservice/v1/orgs/{org_key}/policies/{policy_id}/rules/{rule_id}

Response

Code Description Content-Type Content
204 Successfully deleted policy rule application/json View example response below
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rules/3

Response 

No Content

Bulk Modify Policy Rules

Copy or modify a permission or prevention rule into multiple policies

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies CREATE Majority of environments
VMware Cloud Services Platform _API.Policies:org.Policies:create N/A - included in permission name Prod UK and AWS GovCloud (US)

Requests

POST {cbc-hostname}/policyservice/v1/orgs/{org_key}/policies/rules/changes

Request Body 

{
  "target_policy_ids": [
    <long>
  ],
  "conflict_resolution_mode": "<string>",
  "changes": [
    {
      "old_rule": {
        "required": <boolean>,
        "action": "<string>",
        "application": {
          "type": "<string>",
          "value": "<string>"
        },
        "operation": "<string>"
      },
      "new_rule": {
        "required": <boolean>,
        "action": "<string>",
        "application": {
          "type": "<string>",
          "value": "<string>"
        },
        "operation": "<string>"
      }
    }
  ]
}

Body Schema

Field Definition Data Type Values
target_policy_ids Destination policies for the rule change Array
conflict_resolution_mode The mechanism to resolve if there is a conflict String DRY_RUN, ABORT, TAKE_NEW, KEEP_OLD
changes The rules to copy or replace Array Changes - see below

Changes:

Field Definition Data Type Values
old_rule The old rule that will be removed or replaced Object Rule
new_rule The new rule that will be added Object Rule
resolution Response Only The resolution that was performed String DRY_RUN, ABORT, TAKE_NEW, KEEP_OLD
state Response Only The difference in state between the old and new rule String APPLIED, CONFLICT, SAFE_TO_APPLY, SAME

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/rules/changes

Request Body 

{
  "target_policy_ids": [
    6527
  ],
  "conflict_resolution_mode": "TAKE_NEW",
  "changes": [
    {   
        "new_rule": {
            "required": true,
            "action": "TERMINATE",
            "application": {
                "type": "REPUTATION",
                "value": "KNOWN_MALWARE"
            },
            "operation": "RUN"
        }
    }
  ]
}

Response 

{
    "target_policy_ids": [
        6527
    ],
    "conflict_resolution_mode": "TAKE_NEW",
    "changes": [
        {
            "new_rule": {
                "id": 0,
                "required": true,
                "action": "TERMINATE",
                "application": {
                    "type": "REPUTATION",
                    "value": "KNOWN_MALWARE"
                },
                "operation": "RUN"
            },
            "policy_id": 6527,
            "state": "APPLIED",
            "resolution": "TAKE_NEW"
        }
    ],
    "failed_policy_ids": [],
    "num_applied": 1,
    "num_conflicts": 0,
    "success": true
}

Fields

Policy

Field Definition Data Type Values
id The policy identifier Long
name Defined name for the policy String
org_key The organization key associated with the console instance String
priority_level The priority level designated for policy String LOW, MEDIUM, HIGH, MISSION_CRITICAL
is_system Indicates that the policy was created by VMware Boolean
description The description of the policy String
auto_deregister_inactive_vdi_interval_ms The time in milliseconds to wait after a VDI is inactive before setting the VDI to a DEREGISTERED state Long
auto_delete_known_bad_hashes_delay Enables the Carbon Black Cloud to automatically delete known malware after a specified time in milliseconds Long
av_settings Anti-Virus settings for endpoints and workloads assigned to the policy Object AV Settings
rules Permission or prevention rules to allow and log behavior, bypass a path entirely, remove impediments for software developers' workstations, or deny/terminate processes and applications based on a blocked or isolated operation. Array Rule
directory_action_rules Rules to deny or allow the deployed sensors to send uploads from specific paths Array Directory Action Rules
sensor_settings Settings to configure sensor behavior and capabilities Array Sensor Settings
managed_detection_response_permissions Permissions for Managed Detection and Response analysts to perform remediations on endpoints and workloads assigned to the policy Object Managed Detection and Response Permissions
version Version of the policy Long
rapid_configs Coming Soon Object See Rapid Configs

AV Settings

Field Definition Data Type Values
avira_protection_cloud Third-party partner settings for unknown reputation binary analysis Object Avira Protection Cloud
on_access_scan Local scan settings Object On Access Scan
on_demand_scan Background scan settings Object On Demand Scan
signature_update Signature pack update settings Object Signature Update
update_servers Servers for updating signatures Object Update Servers

Avira Protection Cloud

Field Definition Data Type Values
enabled Whether unknown reputation binary analysis is enabled Boolean
max_exe_delay CSR only* Time before sending unknown binary for analysis in seconds Long Min: 2
Max: 500
max_file_size CSR only Maximum file size to send for analysis in MB Long Min: 15
Max: 100
risk_level CSR only Risk level to send for analysis Long Min: 0
Max: 7

On Access Scan

Field Definition Data Type Values
enabled Whether local scan is enabled Boolean
mode The local scan mode for new files or all files String NORMAL, AGGRESSIVE

On Demand Scan

Field Definition Data Type Values
enabled Whether background scan is enabled Boolean
profile The background scan mode which limits the maximum number of files scanned per minute. AGGRESSIVE will have CPU, memory and disk I/O impacts String NORMAL, AGGRESSIVE
schedule The schedule for when the one time background scan will be performed Object 
{
  "days": [
    "MONDAY"
  ],
  "start_hour": 11,
  "range_hours": 2,
  "recovery_scan_if_missed": true
}
scan_usb Whether USB devices are scanned String AUTOSCAN, DISABLED
scan_cd_dvd Whether a CD or DVD is scanned String AUTOSCAN, DISABLED

Signature Update

Field Definition Data Type Values
enabled Whether signature updates is enabled boolean
schedule The schedule to update signatures Object 
{
  "full_interval_hours": 0,
  "initial_random_delay_hours": 0,
  "interval_hours": 0
}

Update Servers

Field Definition Data Type Values
servers_override CSR only Update servers to override offsite/onsite settings Array Default: ["http://updates2.cdc.carbonblack.io/update2"]
servers_for_onsite_devices Update servers for internal devices Array 
[
  {
    "server": "string",
    "preferred": true
  }
]
servers_for_offsite_devices Update servers for offsite devices Array

Rule

Field Definition Data Type Values
id The identifier of the rule Long
required Not used Boolean
action The action the sensor will take when an application attempts to perform the selected operation String IGNORE,
ALLOW,
TERMINATE_PROCESS,
TERMINATE_THREAD,
TERMINATE,
DENY
application The path, signature or reputation of the application Object 
{
  "type": "<string>",
  "value": "<string>"
}
Types:
NAME_PATH, SIGNED_BY, REPUTATION

Reputations: ADAPTIVE_WHITE_LIST,
ADWARE,
COMMON_WHITE_LIST,
COMPANY_BLACK_LIST,
COMPANY_WHITE_LIST,
HEURISTIC,
IGNORE,
KNOWN_MALWARE,
LOCAL_WHITE,
NOT_LISTED,
PUP,
RESOLVING,
SUSPECT_MALWARE,
TRUSTED_WHITE_LIST
operation The type of behavior an application is performing String BYPASS_ALL,
BYPASS_API,
INVOKE_SCRIPT,
INVOKE_SYSAPP,
POL_INVOKE_NOT_TRUSTED,
INVOKE_CMD_INTERPRETER,
RANSOM,
NETWORK,
PROCESS_ISOLATION,
CODE_INJECTION,
MEMORY_SCRAPE,
RUN_INMEMORY_CODE,
ESCALATE,
RUN

Directory Action Rules

Field Definition Data Type Values
file_upload Allow the deployed sensor to upload from path Boolean
protection Deny the deployed sensor from uploading at path Boolean
path The path to a file or directory String Wildcards supported: *, **, ?

Sensor Settings

Field Definition Data Type Values
name Name of the sensor setting String
value Value for the sensor setting String

Supported Settings:

Name Description Value
SHOW_UI Whether the sensor should show UI "true", "false"
ALLOW_UNINSTALL Whether the user can uninstall the sensor "true", "false"
ALLOW_UPLOAD Deprecated
QUARANTINE_DEVICE Whether the endpoint or workload should be quarantined or not "true", "false"
ENABLE_FORENSICS Whether to enable forensics on the endpoint or workload "true", "false"
LOGGING_LEVEL Set the logging level to debug "true", "false"
QUARANTINE_DEVICE_MESSAGE Message to display to the user when a endpoint or workload is quarantined String

Default: "Device has been quarantined by your computer administrator."
ENABLE_THREAT_SHARING Enable threat sharing for the policy "true", "false"
SET_SENSOR_MODE Set the sensor mode as passive or active etc Active "0",
Passive "1"
SENSOR_RESET Sensor Reset No Reset "0",
Reset Database "1"
BLOCK_REMOVABLE_MEDIA Block use of removable media on the endpoint or workload "true", "false"
POLICY_ACTION_OVERRIDE Allow user to override policy actions "true", "false"
BACKGROUND_SCAN Whether to perform background scan or not "true", "false"
RATE_LIMIT Rate limit for the sensor in KB/hr String
QUEUE_SIZE Queue size for the sensor in MB String
DROP_CONNECTION_TIME Drop connection time in minutes String
CONNECTION_LIMIT Number of connections / hr String
LEARNING_MODE Learning mode time in hours String
SET_AV_MODE Not used
SCAN_NETWORK_DRIVE Whether to scan network drives "true", "false"
BYPASS_AFTER_RESTART_MINS Number of minutes to keep sensor in bypass after restart String
BYPASS_AFTER_LOGIN_MINS Number of minutes to keep sensor in bypass after login String
HELP_MESSAGE Help message displays on sensor ui String
SHOW_FULL_UI Show full sensor UI "true", "false"
SCAN_EXECUTE_ON_NETWORK_DRIVE Can execute on network drives "true", "false"
DELAY_EXECUTE Delay execute for cloud after local scan "true", "false"
ALLOW_INLINE_BLOCKING Pause binary execution for access decision "true", "false"
PRESERVE_SYSTEM_MEMORY_SCAN Preserve system memory for scan "true", "false"
HASH_MD5 Whether to calculate MD5 hash "true", "false"
SCAN_LARGE_FILE_READ Whether the sensor should scan large files "true", "false"
SECURITY_CENTER_OPT Security Center Opt In "true", "false"
CB_LIVE_RESPONSE Whether Live Response is enabled "true", "false"
UNINSTALL_CODE Whether an uninstall code is needed for sensor uninstall "true", "false"
ALLOW_EXPEDITED_SCAN Permit expedited (higher priority resulting in more CPU usage) background scans "true", "false"
UBS_OPT_IN Whether the sensor is allowed to upload binaries to the Unified Binary Store "true", "false"
DISABLE_MALWARE_SERVICES Disable services before start up that are known as being malware "true", "false"

Managed Detection and Response Permissions

Field Definition Data Type Values
policy_modification Allow MDR team to modify the policy Boolean Default: false
quarantine Allow MDR team to quarantine endpoints and workloads associated with the policy Boolean Default: false

Rapid Configs

A Rapid Config is a new type of setting within policy that allows users to make adjustments to Carbon Black-defined rules. The first Rapid Configs that will be released are called Core Prevention and will expose controls for existing dynamic preventions developed by our Threat Analysis Unit. Modifications can include toggling between “Alert Only” and “Block and Alert” on a per-operating system basis when the configuration applies to multiple operating systems. In a future release, Rapid Configs will support process exceptions and other types of user modifications.

Coming Soon

Last modified on September 6, 2022