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.

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

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

Resources

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)

Request 
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)

Request 
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)

Request 
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": "DevRel Core Prevention",
  "org_key": "ABCD1234",
  "priority_level": "MEDIUM",
  "position": 25,
  "is_system": false,
  "description": "Example Prevention Policy",
  "auto_deregister_inactive_vdi_interval_ms": 0,
  "auto_deregister_inactive_vm_workloads_interval_ms": 0,
  "update_time": 1692887089783,
  "av_settings": {
    "avira_protection_cloud": {
      "enabled": true,
      "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": {
        "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": 863,
      "required": false,
      "action": "TERMINATE",
      "application": {
        "type": "REPUTATION",
        "value": "ADAPTIVE_WHITE_LIST"
      },
      "operation": "RANSOM"
    }
  ],
  "directory_action_rules": [],
  "sensor_settings": [
    {
      "name": "ALLOW_UNINSTALL",
      "value": "true"
    },
    {
      "name": "SHOW_UI",
      "value": "false"
    },
    {
      "name": "ALLOW_INLINE_BLOCKING",
      "value": "true"
    }
  ],
  "rule_configs": [
    {
      "id": "88b19232-abcd123-48ef-a198-2a75a282de5d",
      "name": "Privilege Escalation",
      "description": "Addresses behaviors that indicate a threat actor has gained elevated access via a bug or misconfiguration within an operating system, and leverages the detection of TTPs/behaviors to prevent such activity.",
      "inherited_from": "psc:region",
      "category": "core_prevention",
      "parameters": {
        "WindowsAssignmentMode": "BLOCK"
      }
    },
    {
      "id": "1c03d653-abcd123-4adc-81a1-04b17b6cbffc",
      "name": "Event Exclusions",
      "description": "Allows customers to exclude specific processes and process events from reporting to CBC",
      "inherited_from": "psc:region",
      "category": "bypass",
      "parameters": {},
      "exclusions": {
        "windows": [
          {
            "id": 2383,
            "criteria": [
              {
                "id": 2582,
                "type": "initiator_process",
                "attributes": [
                  {
                    "id": 16187,
                    "name": "process_sha256",
                    "values": [
                      "48192cf2d88511e4ca0601b9686611b6fb44816f159991f576242c2"
                    ]
                  }
                ]
              },
              {
                "id": 2583,
                "type": "operation",
                "attributes": [
                  {
                    "id": 16188,
                    "name": "operation_type",
                    "values": [
                      "ALL"
                    ]
                  }
                ]
              }
            ],
            "comments": "test",
            "type": "REPORTING",
            "apply_to_descendent_processes": false,
            "created_by": "test@vmware.com",
            "created_at": "2023-08-18T09:09:59.128Z",
            "modified_by": "test@vmware.com",
            "modified_at": "2023-08-18T09:09:59.128Z"
          },
          {
            "id": 2136,
            "criteria": [
              {
                "id": 2247,
                "type": "initiator_process",
                "attributes": [
                  {
                    "id": 16185,
                    "name": "process_sha256",
                    "values": [
                      "48192cf2d88511e4ca0601b9686644816f159e8a627b16991f576242c2"
                    ]
                  }
                ]
              },
              {
                "id": 2248,
                "type": "operation",
                "attributes": [
                  {
                    "id": 16186,
                    "name": "operation_type",
                    "values": [
                      "ALL"
                    ]
                  }
                ]
              }
            ],
            "comments": "testing API response",
            "type": "REPORTING",
            "apply_to_descendent_processes": false,
            "created_by": "test@carbonblack.com",
            "created_at": "2023-08-04T19:50:58.628Z",
            "modified_by": "test@carbonblack.com",
            "modified_at": "2023-08-04T19:50:58.628Z"
        ]
      }
    }
  ],
  "sensor_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)

Request 
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)

Request 
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.

Get Policies Order by Rank

Retrieve the order of policies based on their ranking within a specified 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)

Request 
GET {cbc-hostname}/policyservice/v1/orgs/{org_key}/policies_order


Response Codes

Code Description Content-Type Content
200 OK application/json Example response below
400 Bad Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
GET https://defense.conferdeploy.net/policyservice/v1/orgs/{org_key}/policies_order
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
  "policies": [
    {
      "id": 6056,
      "name": "Advanced",
      "position": 1
    },
    {
      "id": 19238141,
      "name": "Test policy",
      "position": 2
    },
    {
      "id": 6055,
      "name": "Standard",
      "position": 3
    }
  ],
  "total_count": 3
}
To download or review the Carbon Black Cloud Postman collection, click here.

Update Policy Ranks

Modify the ranking or positioning of policies within a specified organization.

Rank policies in order of importance. When an asset is assigned more than one policy, the highest-anking policy takes precedence. To see how a change in the rank of a policy or policies will affect assets without modification, use the Preview Policies Rank Change API call.

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)

Request 
PUT {cbc-hostname}/policyservice/v1/orgs/{org_key}/policies_order


Request Body - application/json

{
  "policies": {
    "id": <integer>,
    "position": <integer>
  }
}


Body Schema

Field Definition Data Type Values
policies Object 
{
  "id": <integer>,
  "position": <integer>
}
id Unique identifier of a policy. It is used to specify which policy you want to preview or potentially change the ranking for. Integer N/A
position The desired new position or rank for the policy specified by the “id” parameter. It determines where the policy should be placed in relation to other policies when the ranking change is applied. When an asset is assigned more than one policy, the highest-ranking policy takes precedence. Integer N/A


Response Codes

Code Description Content-Type Content
200 OK application/json Example response below
400 Bad Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
PUT https://defense.conferdeploy.net/policyservice/v1/orgs/{org_key}/policies_order
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "policies": {
    "id": 19238141,
    "position": 1
  }
}
Response Body 
{
  "policies": [
    {
      "id": 6056,
      "position": 2
    },
    {
      "id": 19238141,
      "position": 1
    }
  ]
}
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)

Request 
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)

Request 
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)

Request 
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)

Request 
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)

Request 
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": "0aa2b31a-f938-4cf9-acee-7cf7b810eb79",
      "name": "Background Scan",
      "description": "This rapid config handles DRE rules and sensor settings associated with Background Scan",
      "presentation": {
        "category": "sensor_settings"
      },
      "parameters": []
    },
    {
      "id": "88b19232-7ebb-48ef-a198-2a75a282de5d",
      "name": "Privilege Escalation",
      "description": "Addresses behaviors that indicate a threat actor has gained elevated access via a bug or misconfiguration within an operating system, and leverages the detection of TTPs/behaviors to prevent such activity.",
      "presentation": {
        "name": "privesc.name",
        "category": "core-prevention",
        "description": [
          "privesc.description"
        ],
        "platforms": [
          {
            "platform": "WINDOWS",
            "header": "privesc.windows.heading",
            "subHeader": [
              "privesc.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"
              ]
            }
          ]
        }
      ]
    },
    {
      "id": "c4ed61b3-d5aa-41a9-814f-0f277451532b",
      "name": "Carbon Black Threat Intel",
      "description": "Addresses common and pervasive TTPs used for malicious activity as well as living off the land TTPs/behaviors detected by Carbon Black’s Threat Analysis Unit.",
      "presentation": {
        "name": "cbti.name",
        "category": "core-prevention",
        "description": [
          "cbti.description"
        ],
        "platforms": [
          {
            "platform": "WINDOWS",
            "header": "cbti.windows.heading",
            "subHeader": [
              "cbti.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"
              ]
            }
          ]
        }
      ]
    },
    {
      "id": "1c03d653-eca4-4adc-81a1-04b17b6cbffc",
      "name": "Event Exclusions",
      "description": "Allows customers to exclude specific processes and process events from reporting to CBC",
      "presentation": {
        "name": "process_exclusion.name",
        "category": "bypass",
        "description": [
          "process_exclusion.description"
        ],
        "platforms": [
          {
            "platform": "WINDOWS",
            "exclusions": {
              "criteria": [
                "initiator_process",
                "operations"
              ],
              "additional_attributes": [
                "type",
                "inheritence"
              ]
            }
          }
        ]
      },
      "parameters": []
    }
  ]
}
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)

Request 
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 v7 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)

Request 
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.

As of September 2023, a new functionality to the Core Prevention is available; The Core Prevention Exclusions allows you to create process exclusions based on a variety of attributes related to either the primary or parent process including process path, command line, hash, and certificate. This allows you to hone in on processes with more specificity than before and create exclusions for specific workflows, such as scripting activity leveraging command lines.

Use the Update Core Prevention Rule Configs API call to create or update Core Prevention Exclusions.

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)

Request 
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": "97a03cc2-5796-4864-b16d-790d06bea20d",
      "name": "Defense Evasion",
      "description": "Addresses common TTPs/behaviors that threat actors use to avoid detection such as uninstalling or disabling security software, obfuscating or encrypting data/scripts and abusing trusted processes to hide and disguise their malicious activity.",
      "inherited_from": "psc:region",
      "category": "core_prevention",
      "parameters": {
        "WindowsAssignmentMode": "BLOCK"
      }
    },
    {
      "id": "8a16234c-9848-473a-a803-f0f0ffaf5f29",
      "name": "Persistence",
      "description": "Addresses common TTPs/behaviors that threat actors use to retain access to systems across restarts, changed credentials, and other interruptions that could cut off their access.",
      "inherited_from": "psc:region",
      "category": "core_prevention",
      "parameters": {
        "WindowsAssignmentMode": "BLOCK"
      },
      "exclusions": {
        "windows": [
          {
            "id": 2441,
            "criteria": [
              {
                "id": 2648,
                "type": "initiator_process",
                "attributes": [
                  {
                    "id": 16817,
                    "name": "process_sha256",
                    "values": [
                      "03feb86ee497e5430c99607a746dc28dc46a3e9be46311dc8f29ef195d93060a"
                    ]
                  }
                ]
              }
            ],
            "comments": "",
            "created_by": "tester@carbonblack.com",
            "created_at": "2023-08-31T14:02:47.530Z",
            "modified_by": "tester@carbonblack.com",
            "modified_at": "2023-08-31T14:02:47.530Z"
          }
        ]
      }
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Update Core Prevention Rule Configs

Update parameters for core prevention rule configs, or create a Core Prevention Exclusion. Create process exclusions based on a variety of attributes related to either the primary or parent process including process path, command line, hash, and certificate.

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)

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

Request Body 

[
  {
    "id": "<string>",
    "parameters": {
      "WindowsAssignmentMode": "<string>"
    },
    "exclusions": {
      "windows": [
        {
          "id": <integer>,
          "criteria": [
            {
              "id": <integer>,
              "type": "<string>",
              "attributes": [
                {
                  "id": <integer>,
                  "name": "<string>",
                  "values": [ "<string>" ]
                }
              ]
            }
          ],
          "comments": "<string>",
          "created_by": "<string>",
          "created_at": "<string>",
          "modified_by": "<string>",
          "modified_at": "<string>"
        }
      ]
    }
  }
]

Body Schema

Field Definition Data Type Values
id Unique identifier for the rule config. String N/A
WindowsAssignmentMode Used to change assignment mode to REPORT or BLOCK. String BLOCK, REPORT
exclusions Object containing Windows exclusions. Object
exclusions.windows Array of Windows exclusion objects. Array
exclusions.windows.id Unique identifier for the exclusion rule. Integer N/A
exclusions.windows.criteria Array of criteria for the exclusion rule. Array
exclusions.windows.criteria.id Unique identifier for the criterion. Integer N/A
exclusions.windows.criteria.type Type of the criterion. String initiator_process
exclusions.windows.criteria.attributes Array of criterion attributes. Array
exclusions.windows.criteria.attributes.id Unique identifier for the attribute. Integer N/A
exclusions.windows.criteria.attributes.name Name of the attribute. String process_cmdline, process_sha256, parent_cmdline, parent_name, parent_sha256, parent_signature, process_signature, process_name
exclusions.windows.criteria.attributes.values Array of values for the attribute. Array N/A
exclusions.windows.comments Comments related to the exclusion rule. String N/A
exclusions.windows.created_by Creator of the exclusion rule. String N/A
exclusions.windows.created_at Timestamp of creation for the exclusion rule. String ISO8601 timestamp
exclusions.windows.modified_by Modifier of the exclusion rule. String N/A
exclusions.windows.modified_at Timestamp of modification for the exclusion rule. String ISO8601 timestamp

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": "8a16234c-9848-473a-a803-f0f0ffaf5f29",
    "parameters": {
      "WindowsAssignmentMode": "BLOCK"
    },
    "exclusions": {
      "windows": [
        {
          "id": 2441,
          "criteria": [
            {
              "id": 2648,
              "type": "initiator_process",
              "attributes": [
                {
                  "id": 16815,
                  "name": "process_sha256",
                  "values": [
                    "03feb86ee497e5430c99607a746dc28dc46a3e9be46311dc8f29ef195d93060a"
                  ]
                }
              ]
            }
          ],
          "comments": "",
          "created_by": "tester@carbonblack.com",
          "created_at": "2023-08-31T14:02:47.530Z",
          "modified_by": "tester@carbonblack.com",
          "modified_at": "2023-08-31T14:02:47.530Z"
        },
        {
          "id": 2442,
          "criteria": [
            {
              "id": 2649,
              "type": "initiator_process",
              "attributes": [
                {
                  "id": 16816,
                  "name": "process_sha256",
                  "values": [
                    "03feb86ee497e5430c99607a746dc28dc46a3e9be46311dc8f29ef195d93060a"
                  ]
                }
              ]
            }
          ],
          "comments": "Test Exclusion",
          "created_by": "tester@carbonblack.com",
          "created_at": "2023-09-01T07:25:33.558Z",
          "modified_by": "tester@carbonblack.com",
          "modified_at": "2023-09-01T07:25:33.558Z"
        },
        {
          "criteria": [
            {
              "type": "initiator_process",
              "attributes": [
                {
                  "name": "process_sha256",
                  "values": [
                    "03feb86ee497e5430c99607a746dc28dc46a3e9be46311dc8f29ef195d93060a"
                  ]
                }
              ]
            }
          ],
          "comments": "test exclusion"
        }
      ]
    }
  }
]
Response Body 
{
  "successful": [
    {
      "id": "8a16234c-9848-473a-a803-f0f0ffaf5f29",
      "name": "Persistence",
      "description": "Addresses common TTPs/behaviors that threat actors use to retain access to systems across restarts, changed credentials, and other interruptions that could cut off their access.",
      "inherited_from": "psc:region",
      "category": "core_prevention",
      "parameters": {
        "WindowsAssignmentMode": "BLOCK"
      },
      "exclusions": {
        "windows": [
          {
            "id": 2441,
            "criteria": [
              {
                "id": 2648,
                "type": "initiator_process",
                "attributes": [
                  {
                    "id": 16817,
                    "name": "process_sha256",
                    "values": [
                      "03feb86ee497e5430c99607a746dc28dc46a3e9be46311dc8f29ef195d93060a"
                    ]
                  }
                ]
              }
            ],
            "comments": "",
            "created_by": "tester@carbonblack.com",
            "created_at": "2023-08-31T14:02:47.530Z",
            "modified_by": "tester@carbonblack.com",
            "modified_at": "2023-08-31T14:02:47.530Z"
          },
          {
            "id": 2442,
            "criteria": [
              {
                "id": 2649,
                "type": "initiator_process",
                "attributes": [
                  {
                    "id": 16818,
                    "name": "process_sha256",
                    "values": [
                      "03feb86ee497e5430c99607a746dc28dc46a3e9be46311dc8f29ef195d93060a"
                    ]
                  }
                ]
              }
            ],
            "comments": "Test Exclusion",
            "created_by": "tester@carbonblack.com",
            "created_at": "2023-09-01T07:25:33.558Z",
            "modified_by": "tester@carbonblack.com",
            "modified_at": "2023-09-01T07:25:33.558Z"
          },
          {
            "id": 2443,
            "criteria": [
              {
                "id": 2650,
                "type": "initiator_process",
                "attributes": [
                  {
                    "id": 16819,
                    "name": "process_sha256",
                    "values": [
                      "03feb86ee497e5430c99607a746dc28dc46a3e9be46311dc8f29ef195d93060a"
                    ]
                  }
                ]
              }
            ],
            "comments": "test exclusion",
            "created_by": "tester@carbonblack.com",
            "created_at": "2023-09-01T07:26:14.354Z",
            "modified_by": "tester@carbonblack.com",
            "modified_at": "2023-09-01T07:26:14.354Z"
          }
        ]
      }
    }
  ],
  "failed": []
}
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)

Request 
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)

Request 
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 - Data Collection

The data collection rule configs provide increased control over what data is uploaded to the Carbon Black Cloud. This enables you to configure what you need and optimize for deployments where performance is more important.

Get Data Collection Rule Configs

Fetch configured Data Collection 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)

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

Response

Code Description Content-Type Content
200 Successfully fetched core prevention rule configs application/json View example response below
400 Bad Request application/json 
{
    "error_code": "NO_RELEASED_VERSION_FOUND",
    "message": "No released version found for rule config 0 for scope psc:policy:7DESJ9GN:6525"
}
401 Unauthorized application/json 
{
    "success": false,
    "message": "User is not authenticated"
}
403 Forbidden application/json 
{
    "error_code": "FORBIDDEN",
    "message": "Access is denied"
}
500 Internal Server Error application/json 
{
    "error_code": "INTERNAL_SERVER_ERROR",
    "message": "An internal server error has occurred"
}

Examples

Request 
GET https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/data_collection
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "results": [
        {
            "id": "91c919da-fb90-4e63-9eac-506255b0a0d0",
            "name": "Authentication Events",
            "description": "Authentication Events",
            "inherited_from": "",
            "category": "data_collection",
            "parameters": {
                "enable_auth_events": true
            }
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Update Data Collection Rule Configs

Update parameters for data collection rule configs. The supported parameters will differ depending on the rule config, the parameters can be looked up using Parameter Schema

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)

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

Request Body 

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

Body Schema

Field Definition Data Type Values
id Rule config id String
parameters.enable_auth_events Used to enable the auth event data collection rule config Boolean

Response

Code Description Content-Type Content
200 Successfully updated core prevention rule configs application/json View example response below
400 Bad Request application/json 
{
    "error_code": "NO_RELEASED_VERSION_FOUND",
    "message": "No released version found for rule config 0 for scope psc:policy:7DESJ9GN:6525"
}
401 Unauthorized application/json 
{
    "success": false,
    "message": "User is not authenticated"
}
403 Forbidden application/json 
{
    "error_code": "FORBIDDEN",
    "message": "Access is denied"
}
500 Internal Server Error application/json 
{
    "error_code": "INTERNAL_SERVER_ERROR",
    "message": "An internal server error has occurred"
}

Examples

Request 
PUT https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/data_collection
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
[
    {
        "id": "91c919da-fb90-4e63-9eac-506255b0a0d0",
        "parameters": {
            "enable_auth_events": true
        }
    },
    {
        "id": "6aa056b4-625a-48a7-b6f9-8c253baa454d",
        "parameters": {
            "enabled": false
        }
    }
]
Response Body 
{
    "successful": [
        {
            "id": "91c919da-fb90-4e63-9eac-506255b0a0d0",
            "name": "Authentication Events",
            "description": "Authentication Events",
            "inherited_from": "",
            "category": "data_collection",
            "parameters": {
                "enable_auth_events": true
            }
        }
    ],
    "failed": [
        {
            "id": "6aa056b4-625a-48a7-b6f9-8c253baa454d",
            "error_code": "BUNDLE_NOT_FOUND",
            "message": "Rule config with GUID 6aa056b4-625a-48a7-b6f9-8c253baa454d not found"
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Data Collection Rule Configs

Reset all data collection rule configs.

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)

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

Response

Code Description Content-Type Content
204 Successfully reset core prevention rule configs application/json View example response below
400 Bad Request application/json 
{
    "error_code": "NO_RELEASED_VERSION_FOUND",
    "message": "No released version found for rule config 0 for scope psc:policy:7DESJ9GN:6525"
}
401 Unauthorized application/json 
{
    "success": false,
    "message": "User is not authenticated"
}
403 Forbidden application/json 
{
    "error_code": "FORBIDDEN",
    "message": "Access is denied"
}
500 Internal Server Error application/json 
{
    "error_code": "INTERNAL_SERVER_ERROR",
    "message": "An internal server error has occurred"
}

Examples

Request 
DELETE https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/data_collection
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 Data Collection Rule Config

Reset a specific data collection rule config.

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)

Request 
DELETE {cbc-hostname}/policyservice/v1/orgs/{org_key}/policies/{policy_id}/rule_configs/data_collection/{rule_config_id}

Response

Code Description Content-Type Content
204 Successfully reset core prevention rule config application/json View example response below
400 Bad Request application/json 
{
    "error_code": "NO_RELEASED_VERSION_FOUND",
    "message": "No released version found for rule config 0 for scope psc:policy:ABCD1234:6525"
}
401 Unauthorized application/json 
{
    "success": false,
    "message": "User is not authenticated"
}
403 Forbidden application/json 
{
    "error_code": "FORBIDDEN",
    "message": "Access is denied"
}
500 Internal Server Error application/json 
{
    "error_code": "INTERNAL_SERVER_ERROR",
    "message": "An internal server error has occurred"
}

Examples

Request 
DELETE https://defense.conferdeploy.net/policyservice/v1/orgs/ABCD1234/policies/4920125/rule_configs/data_collection/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)

Request 
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)

Request 
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": <boolean>,
              "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)

Request 
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)

Request 
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)

Request 
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)

Request 
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 A setting within policy that allows users to make adjustments to Carbon Black-defined rules. Typically used through a specialization such as Rule Config - Data Collection. 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, bypass
parameters.WindowsAssignmentMode Used to change assignment mode to REPORT or BLOCK String BLOCK, REPORT

Data Collection

Field Definition Data Type Values
id Id of the data collection rule config String
name Name of the data collection rule config String
description Description of the data collection rule config String
inherited_from The urn of the parent rule config String Default: psc:region
category The rule config category String data_collection
parameters.enable_auth_events Used to enable auth event collection Boolean

Note: The parameters will differ depending on the data collection rule config, use Parameter Schema for more information.


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

Give Feedback

Use this form to give us feedback about this site or any of the documentation.


Last modified on November 27, 2023