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.

API 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>",
  "rule_configs": [ {} ]
}

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

Examples

Request 
POST https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
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,
    "rule_configs": []
}
Response 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,
    "rule_configs": []
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Policy Summaries

Get an overview of the policies available in the organization

API 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

Examples

Request 
GET https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/summary
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "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
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Policy Details

Get a policy’s details by id

API 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

Examples

Request 
GET https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response 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,
    "rule_configs": []
}
To download or review the Carbon Black Cloud Postman collection, click here.

Update Policy

Modify an existing policy

API 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>",
  "rule_configs": [ {} ]
}

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

Examples

Request 
PUT https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
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,
    "rule_configs": []
}
Response 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,
    "rule_configs": []
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Policy

Delete an existing policy.

Note: You cannot delete predefined policies.

API 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

Examples

Request 
DELETE https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
No Content
To download or review the Carbon Black Cloud Postman collection, click here.

Rules

Add Policy Rule

Create a new permission or prevention rule in a policy

API 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

Examples

Request 
POST https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rules
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "required": false,
    "action": "TERMINATE",
    "application": {
        "type": "REPUTATION",
        "value": "SUSPECT_MALWARE"
    },
    "operation": "RUN"
}
Response Body 
{
    "id": 3,
    "required": false,
    "action": "TERMINATE",
    "application": {
        "type": "REPUTATION",
        "value": "SUSPECT_MALWARE"
    },
    "operation": "RUN"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Update Policy Rule

Update an existing permission or prevention rule in a policy

API 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

Examples

Request 
PUT https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rules/3
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "id": 3,
    "required": false,
    "action": "DENY",
    "application": {
        "type": "REPUTATION",
        "value": "SUSPECT_MALWARE"
    },
    "operation": "RUN"
}
Response Body 
{
    "id": 3,
    "required": false,
    "action": "DENY",
    "application": {
        "type": "REPUTATION",
        "value": "SUSPECT_MALWARE"
    },
    "operation": "RUN"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Policy Rule

Delete an existing permission or prevention rule in a policy

API 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

Examples

Request 
DELETE https://defense.conferdeploy.netpolicyservice/v1/orgs/ABCD1234/policies/4920125/rules/3
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
No Content
To download or review the Carbon Black Cloud Postman collection, click here.

Bulk Modify Policy Rules

Copy or modify a permission or prevention rule into multiple policies

API 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

Examples

Request 
POST https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/rules/changes
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
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 Body 
{
    "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
}
To download or review the Carbon Black Cloud Postman collection, click here.

Rule Configs

A Rule Config is a new type of setting within policy that allows users to make adjustments to Carbon Black-defined rules.

Presentation

List all the supported rule configs and their parameters and presentation.

API 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}/configs/presentation

Response

Code Description Content-Type Content
200 Successfully fetched rule config presentation 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

Examples

Request 
GET https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/configs/presentation
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "configs": [
        {
            "id": "ac67fa14-f6be-4df9-93f2-6de0dbd96061",
            "name": "Credential Theft",
            "description": "Addresses threat actors obtaining credentials and relies on detecting the malicious use of TTPs/behaviors that indicate such activity.",
            "presentation": {
                "name": "cred_theft.name",
                "category": "core-prevention",
                "description": [
                    "cred_theft.description"
                ],
                "platforms": [
                    {
                        "platform": "WINDOWS",
                        "header": "cred_theft.windows.heading",
                        "subHeader": [
                            "cred_theft.windows.sub_heading"
                        ],
                        "actions": [
                            {
                                "component": "assignment-mode-selector",
                                "parameter": "WindowsAssignmentMode"
                            }
                        ]
                    }
                ]
            },
            "parameters": [
                {
                    "default": "BLOCK",
                    "name": "WindowsAssignmentMode",
                    "description": "Used to change assignment mode to PREVENT or BLOCK",
                    "recommended": "BLOCK",
                    "validations": [
                        {
                            "type": "enum",
                            "values": [
                                "REPORT",
                                "BLOCK"
                            ]
                        }
                    ]
                }
            ]
        }
        ... Truncated ...
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Parameter Schema

Fetch the schema definition for the dynamic parameters for a rule config.

API 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}/rule_configs/{rule_config_id}/parameters/schema

Response

Code Description Content-Type Content
200 Successfully fetched parameter schema 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

Examples

Request 
GET https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/ac67fa14-f6be-4df9-93f2-6de0dbd96061/parameters/schema
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "type": "object",
    "properties": {
        "WindowsAssignmentMode": {
            "default": "BLOCK",
            "description": "Used to change assignment mode to PREVENT or BLOCK",
            "type": "string",
            "enum": [
                "REPORT",
                "BLOCK"
            ]
        }
    }
}
To download or review the Carbon Black Cloud Postman collection, click here.

Lookup

Fetch the rule config configuration from a triggered alert.

Note: The Alerts V6 API provides the rule_id and rule_category_id in the reason_code with the format "reason_code": "rule_category_id:rule_id" e.g. reason_code:"78F50A65-EC30-4A20-8328-A523BDA82217:8E54DD2E-6857-442A-898D-62603286095C".

API 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}/rule_configs/rules/{rule_id}

Path Schema

Field Definition Data Type Values
policy_id The policy id from an alert String
rule_id The rule id from an alert String

Query Schema

Field Definition Data Type Values
rule_category_id The rule category id from an alert String
rule_config_id The rule config id that corresponds to the rule id in the path String
Note: Either 'rule_category_id' or 'rule_config_id' **must** be specified.

Response

Code Description Content-Type Content
200 Successfully fetched rule config 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

Examples

Request 
GET https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/rules/2aaae8b8-469c-4658-b576-0d4001974073?rule_config_id=df181779-f623-415d-879e-91c40246535d
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "id": "2aaae8b8-469c-4658-b576-0d4001974073",
    "name": "Block google ping",
    "properties": {
        "action": "BLOCK_ALERT",
        "application_path": "*",
        "direction": "IN",
        "enabled": true,
        "local_ip_address": "*",
        "local_port_ranges": "*",
        "name": "ICMP_Outbound",
        "protocol": "ICMP",
        "remote_ip_address": "*",
        "remote_port_ranges": "*",
        "rule_access_check_guid": "e8220ab3-f27f-4ffb-8000-fe02e261a211",
        "rule_inbound_event_check_guid": "2aaae8b8-469c-4658-b576-0d4001974073",
        "rule_outbound_event_check_guid": "c9dc86c3-2571-4009-bd83-4fe8bf6097b1",
        "rule_group_name": "Block google ping",
        "test_mode": false
    },
    "test_mode": false,
    "rule_config_id": "df181779-f623-415d-879e-91c40246535d",
    "rule_config_version": 21,
    "rule_config_category": "host_based_firewall",
    "is_archived": false
}
To download or review the Carbon Black Cloud Postman collection, click here.

Rule Config - Core Prevention

The Carbon Black Threat Analysis Unit (TAU) publishes high-fidelity prevention rules called Core Prevention to 3.6+ Windows sensors. These rules protect customers from a variety of different types of late-breaking, high-impact attacks without the need for customers to change policy configurations.

Despite the high-fidelity and low false positive rate of these preventions, we recognize customers sometimes have business-critical assets that perform certain behaviors and trigger false positives. Core Prevention controls provide customers with configuration options to set TAU-published prevention categories to Alert Only if necessary within their policies. Core Prevention Rule Configs have the option of Alert Only and Alert and Block.

Get Core Prevention Rule Configs

Fetch configured Core Prevention rule configs.

API 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}/rule_configs/core_prevention

Response

Code Description Content-Type Content
200 Successfully fetched core prevention rule configs 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

Examples

Request 
GET https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/core_prevention
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "results": [
        {
            "id": "ac67fa14-f6be-4df9-93f2-6de0dbd96061",
            "name": "Credential Theft",
            "description": "Addresses threat actors obtaining credentials and relies on detecting the malicious use of TTPs/behaviors that indicate such activity.",
            "inherited_from": "psc:region",
            "category": "core_prevention",
            "parameters": {
                "WindowsAssignmentMode": "BLOCK"
            }
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Update Core Prevention Rule Configs

Update parameters for core prevention rule configs.

API 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}/rule_configs/core_prevention

Request Body 

[
  {
    "id": "<string>",
    "parameters": {
      "WindowsAssignmentMode": "<string>"
    }
  }
]

Body Schema

Field Definition Data Type Values
id Rule config id String
parameters.WindowsAssignmentMode Used to change assignment mode to REPORT or BLOCK String BLOCK, REPORT

Response

Code Description Content-Type Content
200 Successfully updated core prevention rule configs 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

Examples

Request 
PUT https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/core_prevention
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
[
  {
    "id": "ac67fa14-f6be-4df9-93f2-6de0dbd96061",
    "parameters": {
      "WindowsAssignmentMode": "BLOCK"
    }
  },
  {
    "id": "4d9d0361-4ab4-4cb8-aaab-474bde6c3229",
    "parameters": {
      "WindowsAssignmentMode": "BLOCK"
    }
  }
]
Response Body 
{
  "successful": [
    {
      "id": "ac67fa14-f6be-4df9-93f2-6de0dbd96061",
      "name": "Credential Theft",
      "description": "Addresses threat actors obtaining credentials and relies on detecting the malicious use of TTPs/behaviors that indicate such activity.",
      "inherited_from": "psc:region",
      "category": "core_prevention",
      "parameters": {
        "WindowsAssignmentMode": "BLOCK"
      }
    }
  ],
  "failed": [
      {
          "id": "4d9d0361-4ab4-4cb8-aaab-474bde6c3229",
          "error_code": "BUNDLE_NOT_FOUND",
          "message": "Rule config with GUID 4d9d0361-4ab4-4cb8-aaab-474bde6c3229 not found"
      }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Core Prevention Rule Configs

Reset all core prevention rule configs to TAU recommended default BLOCK.

API 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}/rule_configs/core_prevention

Response

Code Description Content-Type Content
204 Successfully reset core prevention rule configs 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

Examples

Request 
DELETE https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/core_prevention
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
No Content
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Specific Core Prevention Rule Config

Reset a specific core prevention rule config to TAU recommended default BLOCK.

API 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}/rule_configs/core_prevention/{rule_config_id}

Response

Code Description Content-Type Content
204 Successfully reset core prevention rule config 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

Examples

Request 
DELETE https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/core_prevention/ac67fa14-f6be-4df9-93f2-6de0dbd96061
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
No Content
To download or review the Carbon Black Cloud Postman collection, click here.

Rule Config - Host-Based Firewall

Carbon Black Cloud delivers a Host-based Firewall solution that addresses the protection of an asset based on rules that govern network and application behavior. These rules take specified actions based on observed behavior. Multiple rules can form a policy, and these policies are applied to assets.

Note: The Carbon Black Cloud Host-based Firewall feature requires the Windows sensor v3.9+.

A firewall rule is composed of an action and an object. Available actions are:

  • Allow: Allows the network traffic
  • Block: Blocks the network traffic
  • Block and Alert: Blocks the network traffic and sends an alert to the Alerts page

Firewall rules are based on evaluation of the following types of objects:

  • Local (client computer) and remote (computer that communicates with the client computer)
  • IP address and subnet ranges
  • Port or port ranges
  • Protocol (TCP, UDP, ICMP)
  • Direction (inbound and outbound)
  • Application, determined by file path
Note: The local host is always the local client computer and the remote host is always a remote computer that is positioned elsewhere on the network. This expression of the host relationship is independent of the direction of traffic.

Existing sensor conditions can impact the enforcement of rules. For example, the sensor can be in bypass mode or quarantine, or applications can be blocked. Carbon Black Cloud Host-based Firewall maintains the intended action of the rule as specified by the user, although the rule can take a different actual action when it is enforced based on the sensor condition. The following table describes these cases.

Sensor Mode Intended Action Actual Action Summary
Quarantine Allow or Block Block except to Carbon Black Cloud Quarantine block rules override Host-based Firewall rules.
Bypass Allow or Block Allow Because the sensor is in bypass mode, the Host-based Firewall rule is ineffective.
Prevention policy - block Allow or Block Block Blocked connections to and from the application take precedence over Host-based Firewall rules.

Get Host-Based Firewall

Fetch host-based firewall rule configs.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies.READ 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}/rule_configs/host_based_firewall

Response

Code Description Content-Type Content
200 Successfully fetched host-based firewall rule configs 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

Examples

Request 
GET https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/host_based_firewall
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
  "results": [
    {
      "id": "df181779-f623-415d-879e-91c40246535d",
      "name": "Host-Based Firewall",
      "description": "These are the Host-Based Firewall Rules which will be executed by the sensor.",
      "category": "host_based_firewall",
      "parameters": {
        "enable_host_based_firewall": true,
        "default_rule": {
          "name": "Default Action",
          "description": "Block/Allow all traffic",
          "action": "ALLOW"
        },
        "rule_groups": [
          {
            "name": "Block access to dark web",
            "description": "Block access to dark web description",
            "rules": [
              {
                "local_ip_address": "192.168.1.1",
                "remote_ip_address": "2.2.2.2",
                "remote_port_ranges": "443",
                "local_port_ranges": "8443",
                "action": "BLOCK",
                "direction": "OUT",
                "protocol": "TCP",
                "test_mode": false,
                "application_path": "C:\\Program Files\\myapp1",
                "enabled": true
              }
            ]
          }
        ]
      }
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Update Host-Based Firewall

Update parameters for host-based firewall rule configs.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.firewall.rules UPDATE Majority of environments
VMware Cloud Services Platform _API.Host.Based.Firewall:org.firewall.rules: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}/rule_configs/host_based_firewall

Request Body 

[
  {
    "id": "<string>",
    "parameters": {
      "enable_host_based_firewall": <boolean>,
      "default_rule": {
        "name": "<string>",
        "description": "<string>",
        "action": "<string>"
      },
      "rule_groups": [
        {
          "name": "<string>",
          "description": "<string>",
          "rules": [
            {
              "local_ip_address": "<string>",
              "remote_ip_address": "<string>",
              "remote_port_ranges": "<string>",
              "local_port_ranges": "<string>",
              "action": "<string>",
              "direction": "<string>",
              "protocol": "<string>",
              "test_mode": <booleab>,
              "application_path": "<string>",
              "enabled": <boolean>
            }
          ]
        }
      ]
    }
  }
]

Body Schema

See Host-Based Firewall

Response

Code Description Content-Type Content
200 Successfully updated host-based firewall rule configs 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

Examples

Request 
PUT https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/host_based_firewall
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
[
  {
    "id": "df181779-f623-415d-879e-91c40246535d",
    "parameters": {
      "enable_host_based_firewall": true,
      "default_rule": {
        "name": "Default Action",
        "description": "Block/Allow all traffic",
        "action": "ALLOW"
      },
      "rule_groups": [
        {
          "name": "Block access to dark web",
          "description": "Block access to dark web description",
          "rules": [
            {
              "local_ip_address": "192.168.1.1",
              "remote_ip_address": "2.2.2.2",
              "remote_port_ranges": "443",
              "local_port_ranges": "8443",
              "action": "BLOCK",
              "direction": "OUT",
              "protocol": "TCP",
              "test_mode": false,
              "application_path": "C:\\Program Files\\myapp1",
              "enabled": true
            }
          ]
        }
      ]
    }
  }
]
Response Body 
{
  "successful": [
    {
      "id": "df181779-f623-415d-879e-91c40246535d",
      "name": "Host-Based Firewall",
      "description": "These are the Host-Based Firewall Rules which will be executed by the sensor.",
      "category": "host_based_firewall",
      "parameters": {
        "enable_host_based_firewall": true,
        "default_rule": {
          "name": "Default Action",
          "description": "Block/Allow all traffic",
          "action": "ALLOW"
        },
        "rule_groups": [
          {
            "name": "Block access to dark web",
            "description": "Block access to dark web description",
            "rules": [
              {
                "local_ip_address": "192.168.1.1",
                "remote_ip_address": "2.2.2.2",
                "remote_port_ranges": "443",
                "local_port_ranges": "8443",
                "action": "BLOCK",
                "direction": "OUT",
                "protocol": "TCP",
                "test_mode": false,
                "application_path": "C:\\Program Files\\myapp1",
                "enabled": true
              }
            ]
          }
        ]
      }
    }
  ],
  "failed": []
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Host-Based Firewall

Reset all host-based firewall rule configs.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.firewall.rules DELETE Majority of environments
VMware Cloud Services Platform _API.Host.Based.Firewall:org.firewall.rules: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}/rule_configs/host_based_firewall

Response

Code Description Content-Type Content
204 Successfully reset host-based firewall rule configs 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

Examples

Request 
DELETE https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/host_based_firewall
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
No Content
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Specific Host-Based Firewall

Reset a specific host-based firewall rule config.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.firewall.rules DELETE Majority of environments
VMware Cloud Services Platform _API.Host.Based.Firewall:org.firewall.rules: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}/rule_configs/host_based_firewall/{rule_config_id}

Response

Code Description Content-Type Content
204 Successfully reset host-based firewall rule config 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

Examples

Request 
DELETE https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/host_based_firewall/ac67fa14-f6be-4df9-93f2-6de0dbd96061
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
No Content
To download or review the Carbon Black Cloud Postman collection, click here.

Copy Host-Based Firewall

Copy parameters for host-based firewall rule configs to another policy.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.firewall.rules UPDATE Majority of environments
VMware Cloud Services Platform _API.Host.Based.Firewall:org.firewall.rules: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}/rule_configs/host_based_firewall/_copy

Request Body 

{
  "target_policy_ids": [
    <integer>
  ],
  "parameters": {
    "rule_groups": [
      {
        "name": "<string>",
        "description": "<string>",
        "rules": [
          {
            "local_ip_address": "<string>",
            "remote_ip_address": "<string>",
            "remote_port_ranges": "<string>",
            "local_port_ranges": "<string>",
            "application_path": "<string>",
            "action": "<string>",
            "direction": "<string>",
            "protocol": "<string>",
            "enabled": <boolean>
          }
        ]
      }
    ]
  }
}

Body Schema

Field Definition Data Type Values
target_policy_ids List of policy ids to copy rule_groups String
parameters.rule_groups rule_groups to copy to specified policies Array See Host-Based Firewall - Rule Groups

Response

Code Description Content-Type Content
200 Successfully copied host-based firewall parameters 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

Examples

Request 
PUT https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/host_based_firewall
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "target_policy_ids": [
    3, 5
  ],
  "parameters": {
    "rule_groups": [
      {
        "name": "Block access to darker web",
        "description": "Block access to dark web",
        "rules": [
          {
            "local_ip_address": "192.168.2.2",
            "remote_ip_address": "22.22.22.22",
            "remote_port_ranges": "443",
            "local_port_ranges": "8443",
            "application_path": "C:\\Program Files\\myapp6",
            "action": "BLOCK",
            "direction": "OUT",
            "protocol": "TCP",
            "enabled": true
          }
        ]
      }
    ]
  }
}
Response Body 
{
  "failed_policy_ids": [
    5
  ],
  "num_applied": 1,
  "message": "string",
  "success": true
}
To download or review the Carbon Black Cloud Postman collection, click here.

Export Rules

Export host-based firewall rule configs.

API 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}/rule_configs/host_based_firewall/rules/_export

Query Schema

Field Definition Data Type Values
format REQUIRED The format to export String csv, json

Response

Code Description Content-Type Content
200 Successfully exported host-based firewall rule configs 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

Examples

Request 
GET https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/host_based_firewall/rules/_export?format=json
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
[
  {
    "policy_name": "default",
    "rule_group_name": "Block access to dark web",
    "rule_group_description": "Block access to dark web",
    "rule_group_rank": "1",
    "rule_group_enabled": "true",
    "rule_rank": "1",
    "rule_enabled": true,
    "action": "BLOCK",
    "application_path": "C:\\Program Files\\myapp1",
    "direction": "OUT",
    "local_ip": "192.168.1.1",
    "local_port": "8443",
    "remote_ip": "2.2.2.2",
    "remote_port": "443",
    "protocol": "TCP"
  }
]
To download or review the Carbon Black Cloud Postman collection, click here.

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
rule_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

Core Prevention

Field Definition Data Type Values
id Id of the core prevention rule config String
name Name of the core prevention rule config String
description Description of the core prevention rule config String
inherited_from The urn of the parent rule config String Default: psc:region
category The rule config category String core_prevention
parameters.WindowsAssignmentMode Used to change assignment mode to REPORT or BLOCK String BLOCK, REPORT

Host-Based Firewall

Field Definition Data Type Values
id Id of the host-based firewall rule config String
name Name of the host-based firewall rule config String
description Description of the host-based firewall rule config String
category The rule config category String host_based_firewall
parameters.enable_host_based_firewall Enable host-based firewall rule config Boolean
parameters.default_rule Default rule to apply Object 
{{
  "name": "Default Action",
  "description": "Block/Allow all traffic",
  "action": "ALLOW"
}

Supported actions: ALLOW, BLOCK, BLOCK_ALERT
parameters.rule_groups List of host-based firewall rules Array See Rule Groups

Host-Based Firewall - Rule Groups

Field Definition Data Type Values
name Name of the rule group String
description Description of the rule group String
rules List of rules in the rule group Object See Rules

Host-Based Firewall - Rule Groups - Rules

Field Definition Data Type Values
action REQUIRED The action to take when rule is hit String ALLOW, BLOCK, BLOCK_ALERT
application_path The application path to limit the rule String Default: *
direction REQUIRED The direction the network request is being made from String IN, OUT, BOTH
enabled REQUIRED Whether the rule is enabled Boolean
protocol REQUIRED The type of network request String TCP, UDP
local_ip_address IPv4 address of the local side of the network connection (stored as dotted decimal) String Default: *
local_port_ranges TCP or UDP port used by the local side of the network connection String Default: *
remote_ip_address REQUIRED IPv4 address of the remote side of the network connection (stored as dotted decimal) String Default: *
remote_port_ranges TCP or UDP port used by the remote side of the network connection String Default: *
test_mode Enables host-based firewall hits without blocking network traffic or generating alerts Boolean
Last modified on February 13, 2023