Endpoint Standard REST API Reference

WARNING: This is a legacy document, please view the latest version here.

The following APIs have been deprecated. They will be deactivated and customers should plan updates to their integrations to use the replacement APIs.

Policy

This API will be deactivated on September 5, 2024.

The integrationServices/v3/policy API has been deprecated and replaced by the platform policyservice/v1 API here.

More information on the new policy service can be found here.

Migration information is available in the Migration Guide.

The Policy API allows users to manage security policies on the Endpoint Standard backend. The API allows you to create, replace, and delete security policies. You can apply these policies to devices using the Device API above.

Required Access Level Type - API

  • If using Carbon Black Cloud identity management, choose the Access Level type “API” when creating the API Key.
  • If using VMware Cloud Services Platform for identity management, assign the permission _ConnectorType.APIto a custom role and assign that custom role to an OAuth App.

Policies in Endpoint Standard are comprised of three components:

  • Policy metadata: Metadata about a policy, including:
    • Policy name (name)
    • Policy description (description)
    • Schema version number (version)
    • Priority Level assigned to endpoints in this policy (priorityLevel)
  • Policy contents: The actual policy, which is included as its own object in the policy key of a policy object
  • Policy rules: A set of rules for the policy, included as the rules subkey in the policy contents above. Rules can be defined to restrict activity by application type (suspected malware, files by pathname, etc.) and the operation that the application attempts to perform (executing itself, scraping memory, injecting code into another process, etc.)

The Policy API allows you create or modify policies, and to add/replace/remove rules on existing policies.

Get List of Policies

GET /integrationServices/v3/policy

Get the list of policies available in your organization. This list of policies include system policies (cannot be deleted or modified) as well as user-created policies (which can be deleted and modified). Each policy is a JSON document containing metadata about the policy and a list of rules. There is a separate rule API that can create, modify, and delete rules inside of a policy in addition to replacing the entire policy through the Policy API.

  • Request (application/json)

      $ curl -H X-Auth-Token:ABCD/1234 \
  https://defense.conferdeploy.net/integrationServices/v3/policy

  • Response 200 (application/json) 

      {
  "message": "Success",
  "results": [
  {
  "latestRevision": 1501850861950,
  "name": "default",
  "priorityLevel": "LOW",
  "version": 2,
  "systemPolicy": true,
  "policy": {
  "rules": [
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "operation": "RUN",
  "required": true,
  "id": 1
  },
  {
  "action": "DENY",
  "application": {
  "type": "NAME_PATH",
  "value": "%SystemDrive%\\Windows\\System32\\notepad2.exe"
  },
  "operation": "RUN",
  "required": false,
  "id": 10
  }
  ],
  "avSettings": {
  "features": [
  {
  "enabled": false,
  "name": "SIGNATURE_UPDATE"
  },
  {
  "enabled": true,
  "name": "ONACCESS_SCAN"
  },
  {
  "enabled": true,
  "name": "ONDEMOND_SCAN"
  }
  ],
  "updateServers": {
  "serversForOffSiteDevices": [
  "http://updates.cdc.carbonblack.io/update"
  ],
  "servers": [
  {
  "regId": null,
  "flags": 0,
  "server": [
  "http://updates.cdc.carbonblack.io/update"
  ]
  }
  ]
  },
  "onDemandScan": {
  "profile": "NORMAL",
  "scanUsb": "AUTOSCAN",
  "scanCdDvd": "AUTOSCAN",
  "schedule": {
  "recoveryScanIfMissed": true,
  "days": null,
  "rangeHours": 0,
  "startHour": 0
  }
  },
  "onAccessScan": {
  "profile": "NORMAL"
  },
  "apc": {
  "maxFileSize": 4,
  "riskLevel": 4,
  "maxExeDelay": 45,
  "enabled": false
  },
  "signatureUpdate": {
  "schedule": {
  "fullIntervalHours": 0,
  "initialRandomDelayHours": 4,
  "intervalHours": 2
  }
  }
  },
  "id": -1,
  "sensorSettings": [
  {
  "name": "SHOW_UI",
  "value": "true"
  },
  {
  "name": "BACKGROUND_SCAN",
  "value": "true"
  },
  {
  "name": "POLICY_ACTION_OVERRIDE",
  "value": "true"
  },
  {
  "name": "QUARANTINE_DEVICE_MESSAGE",
  "value": "Your device has been quarantined by your computer administrator."
  },
  {
  "name": "LOGGING_LEVEL",
  "value": "false"
  },
  {
  "name": "ALLOW_UNINSTALL",
  "value": "true"
  },
  {
  "name": "QUARANTINE_DEVICE",
  "value": "false"
  },
  {
  "name": "RATE_LIMIT",
  "value": "0"
  },
  {
  "name": "CONNECTION_LIMIT",
  "value": "0"
  },
  {
  "name": "QUEUE_SIZE",
  "value": "100"
  },
  {
  "name": "LEARNING_MODE",
  "value": "0"
  },
  {
  "name": "SCAN_NETWORK_DRIVE",
  "value": "true"
  },
  {
  "name": "BYPASS_AFTER_LOGIN_MINS",
  "value": "0"
  },
  {
  "name": "BYPASS_AFTER_RESTART_MINS",
  "value": "0"
  },
  {
  "name": "SCAN_EXECUTE_ON_NETWORK_DRIVE",
  "value": "true"
  },
  {
  "name": "DELAY_EXECUTE",
  "value": "true"
  },
  {
  "name": "PRESERVE_SYSTEM_MEMORY_SCAN",
  "value": "false"
  },
  {
  "name": "HASH_MD5",
  "value": "false"
  },
  {
  "name": "SCAN_LARGE_FILE_READ",
  "value": "false"
  },
  {
  "name": "SHOW_FULL_UI",
  "value": "true"
  },
  {
  "name": "HELP_MESSAGE",
  "value": "CarbonBlack"
  },
  {
  "name": "SECURITY_CENTER_OPT",
  "value": "true"
  },
  {
  "name": "CB_LIVE_RESPONSE",
  "value": "true"
  },
  {
  "name": "UNINSTALL_CODE",
  "value": "false"
  }
  ]
  },
  "id": 1,
  "description": ""
  },
  {
  "latestRevision": 1496342016813,
  "name": "quarantine",
  "priorityLevel": "LOW",
  "version": 2,
  "systemPolicy": true,
  "policy": {
  "directoryActionRules": [],
  "rules": [
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "operation": "RUN",
  "required": true,
  "id": 1
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "COMPANY_BLACK_LIST"
  },
  "operation": "RUN",
  "required": true,
  "id": 2
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "SUSPECT_MALWARE"
  },
  "operation": "NETWORK",
  "required": false,
  "id": 3
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "PUP"
  },
  "operation": "NETWORK",
  "required": false,
  "id": 4
  },
  {
  "action": "ALLOW",
  "application": {
  "type": "REPUTATION",
  "value": "RESOLVING"
  },
  "operation": "RUN",
  "required": false,
  "id": 5
  }
  ],
  "avSettings": {
  "features": [
  {
  "enabled": true,
  "name": "SIGNATURE_UPDATE"
  },
  {
  "enabled": true,
  "name": "ONACCESS_SCAN"
  },
  {
  "enabled": true,
  "name": "ONDEMOND_SCAN"
  }
  ],
  "updateServers": {
  "serversForOffSiteDevices": [
  "http://updates.cdc.carbonblack.io/update"
  ],
  "servers": [
  {
  "regId": null,
  "flags": 0,
  "server": [
  "http://updates.cdc.carbonblack.io/update"
  ]
  }
  ]
  },
  "onDemandScan": {
  "profile": "NORMAL",
  "scanUsb": "AUTOSCAN",
  "scanCdDvd": "AUTOSCAN",
  "schedule": {
  "recoveryScanIfMissed": true,
  "days": null,
  "rangeHours": 8,
  "startHour": 20
  }
  },
  "onAccessScan": {
  "profile": "NORMAL"
  },
  "apc": {
  "maxFileSize": 4,
  "riskLevel": 4,
  "maxExeDelay": 45,
  "enabled": false
  },
  "signatureUpdate": {
  "schedule": {
  "fullIntervalHours": 0,
  "initialRandomDelayHours": 4,
  "intervalHours": 4
  }
  }
  },
  "id": -1,
  "sensorSettings": [
  {
  "name": "SHOW_UI",
  "value": "true"
  },
  {
  "name": "BACKGROUND_SCAN",
  "value": "false"
  },
  {
  "name": "POLICY_ACTION_OVERRIDE",
  "value": "true"
  },
  {
  "name": "QUARANTINE_DEVICE_MESSAGE",
  "value": "Your device has been quarantined by your computer administrator."
  },
  {
  "name": "QUARANTINE_DEVICE",
  "value": "true"
  },
  {
  "name": "LOGGING_LEVEL",
  "value": "false"
  },
  {
  "name": "ALLOW_UNINSTALL",
  "value": "true"
  },
  {
  "name": "SCAN_NETWORK_DRIVE",
  "value": "false"
  },
  {
  "name": "BYPASS_AFTER_LOGIN_MINS",
  "value": "0"
  },
  {
  "name": "BYPASS_AFTER_RESTART_MINS",
  "value": "0"
  },
  {
  "name": "SCAN_EXECUTE_ON_NETWORK_DRIVE",
  "value": "true"
  },
  {
  "name": "DELAY_EXECUTE",
  "value": "false"
  },
  {
  "name": "PRESERVE_SYSTEM_MEMORY_SCAN",
  "value": "false"
  },
  {
  "name": "HASH_MD5",
  "value": "true"
  },
  {
  "name": "SCAN_LARGE_FILE_READ",
  "value": "false"
  },
  {
  "name": "SECURITY_CENTER_OPT",
  "value": "false"
  },
  {
  "name": "CB_LIVE_RESPONSE",
  "value": "false"
  },
  {
  "name": "UNINSTALL_CODE",
  "value": "false"
  }
  ]
  },
  "id": 501,
  "description": ""
  }
  ],
  "success": true
  }

Retrieve Policy by ID

GET /integrationServices/v3/policy/{id}

Retrieve a policy object by ID. The policy object includes the policy metadata, policy details, and associated rules for the policy.

  • Request (application/json)

      $ curl -H X-Auth-Token:ABCD/1234 \
  https://defense.conferdeploy.net/integrationServices/v3/policy/32

  • Response 200 (application/json) 

      {
  "policyInfo" : {
  "id" : 7049,
  "priorityLevel" : "LOW",
  "systemPolicy" : false,
  "latestRevision" : 1505155560455,
  "policy" : {
  "sensorSettings" : [ {
  "name" : "SHOW_UI",
  "value" : "true"
  }, {
  "name" : "BACKGROUND_SCAN",
  "value" : "true"
  }, {
  "name" : "POLICY_ACTION_OVERRIDE",
  "value" : "true"
  }, {
  "name" : "QUARANTINE_DEVICE_MESSAGE",
  "value" : "Your device has been quarantined by your computer administrator."
  }, {
  "name" : "LOGGING_LEVEL",
  "value" : "false"
  }, {
  "name" : "ALLOW_UNINSTALL",
  "value" : "true"
  }, {
  "name" : "QUARANTINE_DEVICE",
  "value" : "false"
  }, {
  "name" : "RATE_LIMIT",
  "value" : "0"
  }, {
  "name" : "CONNECTION_LIMIT",
  "value" : "0"
  }, {
  "name" : "QUEUE_SIZE",
  "value" : "100"
  }, {
  "name" : "LEARNING_MODE",
  "value" : "0"
  }, {
  "name" : "SCAN_NETWORK_DRIVE",
  "value" : "true"
  }, {
  "name" : "BYPASS_AFTER_LOGIN_MINS",
  "value" : "0"
  }, {
  "name" : "BYPASS_AFTER_RESTART_MINS",
  "value" : "0"
  }, {
  "name" : "SCAN_EXECUTE_ON_NETWORK_DRIVE",
  "value" : "true"
  }, {
  "name" : "DELAY_EXECUTE",
  "value" : "true"
  }, {
  "name" : "PRESERVE_SYSTEM_MEMORY_SCAN",
  "value" : "false"
  }, {
  "name" : "HASH_MD5",
  "value" : "false"
  }, {
  "name" : "SCAN_LARGE_FILE_READ",
  "value" : "false"
  }, {
  "name" : "SHOW_FULL_UI",
  "value" : "true"
  }, {
  "name" : "HELP_MESSAGE",
  "value" : "CarbonBlack"
  }, {
  "name" : "SECURITY_CENTER_OPT",
  "value" : "true"
  }, {
  "name" : "CB_LIVE_RESPONSE",
  "value" : "true"
  }, {
  "name" : "UNINSTALL_CODE",
  "value" : "false"
  } ],
  "avSettings" : {
  "updateServers" : {
  "servers" : [ {
  "flags" : 0,
  "regId" : null,
  "server" : [ "http://updates.cdc.carbonblack.io/update" ]
  } ],
  "serversForOffSiteDevices" : [ "http://updates.cdc.carbonblack.io/update" ]
  },
  "apc" : {
  "maxFileSize" : 4,
  "maxExeDelay" : 45,
  "riskLevel" : 4,
  "enabled" : false
  },
  "onAccessScan" : {
  "profile" : "NORMAL"
  },
  "features" : [ {
  "enabled" : false,
  "name" : "SIGNATURE_UPDATE"
  }, {
  "enabled" : true,
  "name" : "ONACCESS_SCAN"
  }, {
  "enabled" : true,
  "name" : "ONDEMAND_SCAN"
  } ],
  "onDemandScan" : {
  "profile" : "NORMAL",
  "scanCdDvd" : "AUTOSCAN",
  "scanUsb" : "AUTOSCAN",
  "schedule" : {
  "days" : null,
  "rangeHours" : 0,
  "startHour" : 0,
  "recoveryScanIfMissed" : true
  }
  },
  "signatureUpdate" : {
  "schedule" : {
  "intervalHours" : 2,
  "fullIntervalHours" : 0,
  "initialRandomDelayHours" : 4
  }
  }
  },
  "directoryActionRules" : [ {
  "actions" : {
  "FILE_UPLOAD" : false,
  "PROTECTION" : false
  },
  "path" : "C:\\FXCM\\**"
  }, {
  "actions" : {
  "FILE_UPLOAD" : true,
  "PROTECTION" : false
  },
  "path" : "sadf"
  }, {
  "actions" : {
  "FILE_UPLOAD" : true,
  "PROTECTION" : false
  },
  "path" : "/Users/**"
  } ],
  "rules" : [ {
  "id" : 1,
  "required" : true,
  "operation" : "RUN",
  "application" : {
  "value" : "KNOWN_MALWARE",
  "type" : "REPUTATION"
  },
  "action" : "DENY"
  }, {
  "id" : 2,
  "required" : true,
  "operation" : "RUN",
  "application" : {
  "value" : "COMPANY_BLACK_LIST",
  "type" : "REPUTATION"
  },
  "action" : "DENY"
  }, {
  "id" : 3,
  "required" : false,
  "operation" : "NETWORK",
  "application" : {
  "value" : "KNOWN_MALWARE",
  "type" : "REPUTATION"
  },
  "action" : "DENY"
  }, {
  "id" : 5,
  "required" : false,
  "operation" : "RANSOM",
  "application" : {
  "value" : "ADAPTIVE_WHITE_LIST",
  "type" : "REPUTATION"
  },
  "action" : "TERMINATE"
  }, {
  "id" : 4,
  "required" : false,
  "operation" : "RANSOM",
  "application" : {
  "value" : "**\\devenv.exe",
  "type" : "NAME_PATH"
  },
  "action" : "IGNORE"
  }, {
  "id" : 10,
  "required" : false,
  "operation" : "RUN",
  "application" : {
  "value" : "%SystemDrive%\\Windows\\System32\\notepad2.exe",
  "type" : "NAME_PATH"
  },
  "action" : "DENY"
  }, {
  "id" : 11,
  "required" : true,
  "operation" : "RANSOM",
  "application" : {
  "value" : "KNOWN_MALWARE",
  "type" : "REPUTATION"
  },
  "action" : "DENY"
  }, {
  "id" : 13,
  "required" : false,
  "operation" : "MEMORY_SCRAPE",
  "application" : {
  "value" : "KNOWN_MALWARE",
  "type" : "REPUTATION"
  },
  "action" : "DENY"
  }, {
  "id" : 14,
  "required" : false,
  "operation" : "CODE_INJECTION",
  "application" : {
  "value" : "KNOWN_MALWARE",
  "type" : "REPUTATION"
  },
  "action" : "DENY"
  }, {
  "id" : 15,
  "required" : false,
  "operation" : "RUN_INMEMORY_CODE",
  "application" : {
  "value" : "KNOWN_MALWARE",
  "type" : "REPUTATION"
  },
  "action" : "DENY"
  }, {
  "id" : 17,
  "required" : false,
  "operation" : "POL_INVOKE_NOT_TRUSTED",
  "application" : {
  "value" : "KNOWN_MALWARE",
  "type" : "REPUTATION"
  },
  "action" : "DENY"
  }, {
  "id" : 18,
  "required" : false,
  "operation" : "INVOKE_CMD_INTERPRETER",
  "application" : {
  "value" : "KNOWN_MALWARE",
  "type" : "REPUTATION"
  },
  "action" : "DENY"
  }, {
  "id" : 20,
  "required" : false,
  "operation" : "INVOKE_SCRIPT",
  "application" : {
  "value" : "KNOWN_MALWARE",
  "type" : "REPUTATION"
  },
  "action" : "DENY"
  }, {
  "id" : 22,
  "required" : false,
  "operation" : "RUN",
  "application" : {
  "value" : "RESOLVING",
  "type" : "REPUTATION"
  },
  "action" : "DENY"
  }, {
  "id" : 23,
  "required" : false,
  "operation" : "RUN",
  "application" : {
  "value" : "PUP",
  "type" : "REPUTATION"
  },
  "action" : "DENY"
  }, {
  "id" : 24,
  "required" : false,
  "operation" : "RUN",
  "application" : {
  "value" : "SUSPECT_MALWARE",
  "type" : "REPUTATION"
  },
  "action" : "DENY"
  }, {
  "id" : 25,
  "required" : false,
  "operation" : "NETWORK",
  "application" : {
  "value" : "ADAPTIVE_WHITE_LIST",
  "type" : "REPUTATION"
  },
  "action" : "DENY"
  }, {
  "id" : 26,
  "required" : false,
  "operation" : "INVOKE_SCRIPT",
  "application" : {
  "value" : "c:\\test\\**",
  "type" : "NAME_PATH"
  },
  "action" : "ALLOW"
  } ],
  "id" : -1
  },
  "version" : 2,
  "name" : "documentation test 2",
  "description" : "test policy for documentation"
  },
  "success" : true,
  "message" : "Success"
  }

Create New Policy

POST /integrationServices/v3/policy

Create a new Policy on the Endpoint Standard backend from a policy JSON string. At this time, there is no comprehensive reference to the options available in the Policy schema, so the best way to use this API is to extract the “policy” key from a policy object (retrieved via the “GET” method above) and use it as a template for the new policy.

The new policy must be contained in a JSON object named policyInfo. The contents of the policyInfo object must be must include the following keys:

  • description: A description of the policy (can be multiple lines)

  • name: A one-line name for the policy (shown in the UI)

  • version: Must be set to “2” for the current policy API

  • priorityLevel: HIGH, MEDIUM or LOW - the priority score associated with sensors assigned to this policy.

  • policy: the JSON object containing the policy details. See examples in the policy key from the policies in the GET request above.

  • Request (application/json)

      $ curl -X POST -H X-Auth-Token:ABCD/1234 -H Content-Type:application/json \
  https://defense.conferdeploy.net/integrationServices/v3/policy -d @policy.txt

    where the policy.txt file contains the following (note that not all options may be available on your specific instance. Retrieve a policy from your instance to determine the allowable values for your instance). 

      {
  "policyInfo": {
  "description": "test policy for documentation",
  "name": "documentation test",
  "policy": {
  "avSettings": {
  "apc": {
  "enabled": false,
  "maxExeDelay": 45,
  "maxFileSize": 4,
  "riskLevel": 4
  },
  "features": [
  {
  "enabled": false,
  "name": "SIGNATURE_UPDATE"
  },
  {
  "enabled": true,
  "name": "ONACCESS_SCAN"
  },
  {
  "enabled": true,
  "name": "ONDEMAND_SCAN"
  }
  ],
  "onAccessScan": {
  "profile": "NORMAL"
  },
  "onDemandScan": {
  "profile": "NORMAL",
  "scanCdDvd": "AUTOSCAN",
  "scanUsb": "AUTOSCAN",
  "schedule": {
  "days": null,
  "rangeHours": 0,
  "recoveryScanIfMissed": true,
  "startHour": 0
  }
  },
  "signatureUpdate": {
  "schedule": {
  "fullIntervalHours": 0,
  "initialRandomDelayHours": 4,
  "intervalHours": 2
  }
  },
  "updateServers": {
  "servers": [
  {
  "flags": 0,
  "regId": null,
  "server": [
  "http://updates.cdc.carbonblack.io/update"
  ]
  }
  ],
  "serversForOffSiteDevices": [
  "http://updates.cdc.carbonblack.io/update"
  ]
  }
  },
  "directoryActionRules": [
  {
  "actions": {
  "FILE_UPLOAD": false,
  "PROTECTION": false
  },
  "path": "C:\\FXCM\\**"
  },
  {
  "actions": {
  "FILE_UPLOAD": true,
  "PROTECTION": false
  },
  "path": "sadf"
  },
  {
  "actions": {
  "FILE_UPLOAD": true,
  "PROTECTION": false
  },
  "path": "/Users/**"
  }
  ],
  "id": -1,
  "rules": [
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 1,
  "operation": "RUN",
  "required": true
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "COMPANY_BLACK_LIST"
  },
  "id": 2,
  "operation": "RUN",
  "required": true
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 3,
  "operation": "NETWORK",
  "required": false
  },
  {
  "action": "TERMINATE",
  "application": {
  "type": "REPUTATION",
  "value": "ADAPTIVE_WHITE_LIST"
  },
  "id": 5,
  "operation": "RANSOM",
  "required": false
  },
  {
  "action": "IGNORE",
  "application": {
  "type": "NAME_PATH",
  "value": "**\\devenv.exe"
  },
  "id": 4,
  "operation": "RANSOM",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "NAME_PATH",
  "value": "%SystemDrive%\\Windows\\System32\\notepad2.exe"
  },
  "id": 10,
  "operation": "RUN",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 11,
  "operation": "RANSOM",
  "required": true
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 13,
  "operation": "MEMORY_SCRAPE",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 14,
  "operation": "CODE_INJECTION",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 15,
  "operation": "RUN_INMEMORY_CODE",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 17,
  "operation": "POL_INVOKE_NOT_TRUSTED",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 18,
  "operation": "INVOKE_CMD_INTERPRETER",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 20,
  "operation": "INVOKE_SCRIPT",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "RESOLVING"
  },
  "id": 22,
  "operation": "RUN",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "PUP"
  },
  "id": 23,
  "operation": "RUN",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "SUSPECT_MALWARE"
  },
  "id": 24,
  "operation": "RUN",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "ADAPTIVE_WHITE_LIST"
  },
  "id": 25,
  "operation": "NETWORK",
  "required": false
  },
  {
  "action": "ALLOW",
  "application": {
  "type": "NAME_PATH",
  "value": "c:\\test\\**"
  },
  "id": 26,
  "operation": "INVOKE_SCRIPT",
  "required": false
  }
  ],
  "sensorSettings": [
  {
  "name": "SHOW_UI",
  "value": "true"
  },
  {
  "name": "BACKGROUND_SCAN",
  "value": "true"
  },
  {
  "name": "POLICY_ACTION_OVERRIDE",
  "value": "true"
  },
  {
  "name": "QUARANTINE_DEVICE_MESSAGE",
  "value": "Your device has been quarantined by your computer administrator."
  },
  {
  "name": "LOGGING_LEVEL",
  "value": "false"
  },
  {
  "name": "ALLOW_UNINSTALL",
  "value": "true"
  },
  {
  "name": "QUARANTINE_DEVICE",
  "value": "false"
  },
  {
  "name": "RATE_LIMIT",
  "value": "0"
  },
  {
  "name": "CONNECTION_LIMIT",
  "value": "0"
  },
  {
  "name": "QUEUE_SIZE",
  "value": "100"
  },
  {
  "name": "LEARNING_MODE",
  "value": "0"
  },
  {
  "name": "SCAN_NETWORK_DRIVE",
  "value": "true"
  },
  {
  "name": "BYPASS_AFTER_LOGIN_MINS",
  "value": "0"
  },
  {
  "name": "BYPASS_AFTER_RESTART_MINS",
  "value": "0"
  },
  {
  "name": "SCAN_EXECUTE_ON_NETWORK_DRIVE",
  "value": "true"
  },
  {
  "name": "DELAY_EXECUTE",
  "value": "true"
  },
  {
  "name": "PRESERVE_SYSTEM_MEMORY_SCAN",
  "value": "false"
  },
  {
  "name": "HASH_MD5",
  "value": "false"
  },
  {
  "name": "SCAN_LARGE_FILE_READ",
  "value": "false"
  },
  {
  "name": "SHOW_FULL_UI",
  "value": "true"
  },
  {
  "name": "HELP_MESSAGE",
  "value": "CarbonBlack"
  },
  {
  "name": "SECURITY_CENTER_OPT",
  "value": "true"
  },
  {
  "name": "CB_LIVE_RESPONSE",
  "value": "true"
  },
  {
  "name": "UNINSTALL_CODE",
  "value": "false"
  }
  ]
  },
  "priorityLevel": "LOW",
  "version": 2
  }
  }

  • Response 200 (application/json) 

      {
  "policyId" : 7047,
  "success" : true,
  "message" : "Success"
  }

Update Existing Policy

PUT /integrationServices/v3/policy/{id}

Update an existing policy with a new policy.

The new policy must be contained in a JSON object named policyInfo. The contents of the policyInfo object must be must include the following keys:

  • description: A description of the policy (can be multiple lines)

  • name: A one-line name for the policy (shown in the UI)

  • version: Must be set to “2” for the current policy API

  • priorityLevel: HIGH, MEDIUM or LOW - the priority score associated with sensors assigned to this policy.

  • policy: the JSON object containing the policy details. See examples in the policy key from the policies in the GET request above.

  • id: The ID of the policy to replace. This ID must match the ID in the request URL.

  • Request (application/json)

      $ curl -X PUT -H X-Auth-Token:ABCD/1234 -H Content-Type:application/json \
  https://defense.conferdeploy.net/integrationServices/v3/policy/7049 -d @policy.txt

    where the policy.txt file contains the following (note that not all options may be available on your specific instance. Retrieve a policy from your instance to determine the allowable values for your instance). 

      {
  "policyInfo": {
  "description": "test policy for documentation",
  "name": "documentation test",
  "id": 7049,
  "policy": {
  "avSettings": {
  "apc": {
  "enabled": false,
  "maxExeDelay": 45,
  "maxFileSize": 4,
  "riskLevel": 4
  },
  "features": [
  {
  "enabled": false,
  "name": "SIGNATURE_UPDATE"
  },
  {
  "enabled": true,
  "name": "ONACCESS_SCAN"
  },
  {
  "enabled": true,
  "name": "ONDEMAND_SCAN"
  }
  ],
  "onAccessScan": {
  "profile": "NORMAL"
  },
  "onDemandScan": {
  "profile": "NORMAL",
  "scanCdDvd": "AUTOSCAN",
  "scanUsb": "AUTOSCAN",
  "schedule": {
  "days": null,
  "rangeHours": 0,
  "recoveryScanIfMissed": true,
  "startHour": 0
  }
  },
  "signatureUpdate": {
  "schedule": {
  "fullIntervalHours": 0,
  "initialRandomDelayHours": 4,
  "intervalHours": 2
  }
  },
  "updateServers": {
  "servers": [
  {
  "flags": 0,
  "regId": null,
  "server": [
  "http://updates.cdc.carbonblack.io/update"
  ]
  }
  ],
  "serversForOffSiteDevices": [
  "http://updates.cdc.carbonblack.io/update"
  ]
  }
  },
  "directoryActionRules": [
  {
  "actions": {
  "FILE_UPLOAD": false,
  "PROTECTION": false
  },
  "path": "C:\\FXCM\\**"
  },
  {
  "actions": {
  "FILE_UPLOAD": true,
  "PROTECTION": false
  },
  "path": "sadf"
  },
  {
  "actions": {
  "FILE_UPLOAD": true,
  "PROTECTION": false
  },
  "path": "/Users/**"
  }
  ],
  "id": -1,
  "rules": [
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 1,
  "operation": "RUN",
  "required": true
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "COMPANY_BLACK_LIST"
  },
  "id": 2,
  "operation": "RUN",
  "required": true
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 3,
  "operation": "NETWORK",
  "required": false
  },
  {
  "action": "TERMINATE",
  "application": {
  "type": "REPUTATION",
  "value": "ADAPTIVE_WHITE_LIST"
  },
  "id": 5,
  "operation": "RANSOM",
  "required": false
  },
  {
  "action": "IGNORE",
  "application": {
  "type": "NAME_PATH",
  "value": "**\\devenv.exe"
  },
  "id": 4,
  "operation": "RANSOM",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "NAME_PATH",
  "value": "%SystemDrive%\\Windows\\System32\\notepad2.exe"
  },
  "id": 10,
  "operation": "RUN",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 11,
  "operation": "RANSOM",
  "required": true
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 13,
  "operation": "MEMORY_SCRAPE",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 14,
  "operation": "CODE_INJECTION",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 15,
  "operation": "RUN_INMEMORY_CODE",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 17,
  "operation": "POL_INVOKE_NOT_TRUSTED",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 18,
  "operation": "INVOKE_CMD_INTERPRETER",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "KNOWN_MALWARE"
  },
  "id": 20,
  "operation": "INVOKE_SCRIPT",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "RESOLVING"
  },
  "id": 22,
  "operation": "RUN",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "PUP"
  },
  "id": 23,
  "operation": "RUN",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "SUSPECT_MALWARE"
  },
  "id": 24,
  "operation": "RUN",
  "required": false
  },
  {
  "action": "DENY",
  "application": {
  "type": "REPUTATION",
  "value": "ADAPTIVE_WHITE_LIST"
  },
  "id": 25,
  "operation": "NETWORK",
  "required": false
  },
  {
  "action": "ALLOW",
  "application": {
  "type": "NAME_PATH",
  "value": "c:\\test\\**"
  },
  "id": 26,
  "operation": "INVOKE_SCRIPT",
  "required": false
  }
  ],
  "sensorSettings": [
  {
  "name": "SHOW_UI",
  "value": "true"
  },
  {
  "name": "BACKGROUND_SCAN",
  "value": "true"
  },
  {
  "name": "POLICY_ACTION_OVERRIDE",
  "value": "true"
  },
  {
  "name": "QUARANTINE_DEVICE_MESSAGE",
  "value": "Your device has been quarantined by your computer administrator."
  },
  {
  "name": "LOGGING_LEVEL",
  "value": "false"
  },
  {
  "name": "ALLOW_UNINSTALL",
  "value": "true"
  },
  {
  "name": "QUARANTINE_DEVICE",
  "value": "false"
  },
  {
  "name": "RATE_LIMIT",
  "value": "0"
  },
  {
  "name": "CONNECTION_LIMIT",
  "value": "0"
  },
  {
  "name": "QUEUE_SIZE",
  "value": "100"
  },
  {
  "name": "LEARNING_MODE",
  "value": "0"
  },
  {
  "name": "SCAN_NETWORK_DRIVE",
  "value": "true"
  },
  {
  "name": "BYPASS_AFTER_LOGIN_MINS",
  "value": "0"
  },
  {
  "name": "BYPASS_AFTER_RESTART_MINS",
  "value": "0"
  },
  {
  "name": "SCAN_EXECUTE_ON_NETWORK_DRIVE",
  "value": "true"
  },
  {
  "name": "DELAY_EXECUTE",
  "value": "true"
  },
  {
  "name": "PRESERVE_SYSTEM_MEMORY_SCAN",
  "value": "false"
  },
  {
  "name": "HASH_MD5",
  "value": "false"
  },
  {
  "name": "SCAN_LARGE_FILE_READ",
  "value": "false"
  },
  {
  "name": "SHOW_FULL_UI",
  "value": "true"
  },
  {
  "name": "HELP_MESSAGE",
  "value": "CarbonBlack"
  },
  {
  "name": "SECURITY_CENTER_OPT",
  "value": "true"
  },
  {
  "name": "CB_LIVE_RESPONSE",
  "value": "true"
  },
  {
  "name": "UNINSTALL_CODE",
  "value": "false"
  }
  ]
  },
  "priorityLevel": "LOW",
  "version": 2
  }
  }

Delete Policy

DELETE /integrationServices/v3/policy/{id}

Delete a policy from the Endpoint Standard backend. This API may return an error if devices are actively assigned to the policy id requested for deletion.

  • Request (application/json)

      $ curl -X DELETE -H X-Auth-Token:ABCD/1234  \
  https://defense.conferdeploy.net/integrationServices/v3/policy/7047

  • Response 200 (application/json) 

      {
  "success" : true,
  "message" : "Success"
  }

Add Rule to Existing Policy

POST /integrationServices/v3/policy/{id}/rule

Add a new rule to an existing policy. Wrap the new rule definition into a JSON object under the key ruleInfo.

  • Request (application/json)

      $ curl -X POST -H X-Auth-Token:ABCD/1234 -H Content-Type:application/json \
  https://defense.conferdeploy.net/integrationServices/v3/policy/7049/rule \
  -d '{"ruleInfo": {"action": "DENY", "application": {"type": "REPUTATION", "value": "COMPANY_BLACK_LIST"}, "operation": "RANSOM", "required": true, "id": 1}}'

  • Response 200 (application/json) 

      {
  "ruleId" : 29,
  "success" : true,
  "message" : "Success"
  }

Remove Rule from Existing Policy

DELETE /integrationServices/v3/policy/{id}/rule/{rule_id}

Removes a rule from an existing policy.

  • Request (application/json)

      $ curl -X DELETE -H X-Auth-Token:ABCD/1234 -H Content-Type:application/json \
  https://defense.conferdeploy.net/integrationServices/v3/policy/7049/rule/29

  • Response 200 (application/json) 

      {
  "success" : true,
  "message" : "Success"
  }

Update Existing Rule

PUT /integrationServices/v3/policy/{id}/rule/{rule_id}

Update an existing rule with a new rule. Note that the rule_id in the URL must match the id included in the ruleInfo payload passed to this API.

  • Request (application/json)

      $ curl -X PUT -H X-Auth-Token:ABCD/1234 -H Content-Type:application/json \
  https://defense.conferdeploy.net/integrationServices/v3/policy/7049/rule/32 \
  -d '{"ruleInfo": {"action": "DENY", "application": {"type": "REPUTATION", "value": "COMPANY_BLACK_LIST"}, "operation": "RANSOM", "required": false, "id": 32}}'

  • Response 200 (application/json) 

      {
  "success" : true,
  "message" : "Success"
  }

Notifications

The planned deactivation for this API is on October 31, 2024.

The integrationServices/v3/notification API has been deprecated and replaced by the platform Alerts v7 API or the Data Forwarder - Alerts Schema 2.0.0

Migration information is available in the Migration Guide.

Notifications API allows consumers to get alert and policy action notifications that a connector is subscribed to.

Required Access Level Type - SIEM

  • If using Carbon Black Cloud identity management, choose the Access Level type “SIEM” when creating the API Key.
  • If using VMware Cloud Services Platform for identity management, assign the permission _ConnectorType.SIEMto a custom role and assign that custom role to an OAuth App.
Note: Only CB Analytics and Watchlist alert notifications can be retrieved through the notifications API.


Note: Observed Alerts become Observations in the Alerts v7 API, so SIEM Notification rules that previously included Observed Alerts will no longer emit them.

Note: This API is not available in the AWS GovCloud (US) environment. Instead, we recommend the Data Forwarder or Alerts API.

New integrations should use one of the following to receive all available data:

Get Notifications

GET /integrationServices/v3/notification

Get new notifications since last checkin. The connector must be subscribed to at least one notification rule to get notifications.

Note that once a notification has been delivered, it will not be delivered again. There is also a retention limit of seven days for notifications via this endpoint. Any notifications not consumed within seven days will no longer be available. Customers using this endpoint must poll frequently enough to retrieve their notifications within that window, or utilize one of the other mechanisms available to retrieve this data:

  • Use the Data Forwarder to stream alerts or events to your own S3 bucket, where you can control retention.
  • Use the Alerts v7 API to search up to 180 days of historical alert data.

The API key associated with the request to the Notifications API must be of the “SIEM” Access Level type - “API” Access Level types will return a HTTP 401 Unauthorized when attempting to access the notifications API.

Every SIEM key type can be subscribed to a different set of notifications in the product. Therefore, each SIEM key type will have a different “view” of the notifications available. Each SIEM key is considered separate from the others, and even if both are subscribed to the same set of notifications, the notifications will be delivered to both – retrieving a notification from one SIEM key will not automatically “remove” it from the view of the other SIEM key.

  • Request (application/json)

      $ curl -H X-Auth-Token:ABCD/1234 \
  https://defense.conferdeploy.net/integrationServices/v3/notification

  • Response 200 (application/json) 

    {
    "notifications": [
        {
            "policyAction": {
                "sha256Hash": "2552332222112552332222112552332222112552332222112552332222112552",
                "action": "TERMINATE",
                "reputation": "KNOWN_MALWARE",
                "applicationName": "firefox.exe"
            },
            "type": "POLICY_ACTION",
            "eventTime": 1423163263482,
            "eventId": "EV1",
            "url": "http://carbonblack.com/ui#device/100/hash/2552332222112552332222112552332222112552332222112552332222112552/app/firefox.exe/keyword/terminate policy action",
            "deviceInfo": {
                "deviceType": "WINDOWS",
                "email": "tester@carbonblack.com",
                "deviceId": 100,
                "deviceName": "testers-pc",
                "deviceHostName": null,
                "deviceVersion": "7 SP1",
                "targetPriorityType": "HIGH",
                "targetPriorityCode": 0,
                "internalIpAddress": "55.33.22.11",
                "groupName": "Executives",
                "externalIpAddress": "255.233.222.211"
            },
            "eventDescription": "Policy action 1",
            "ruleName": "Alert Rule 1"
        },
        {
            "threatInfo": {
                "time": 1423163263501,
                "indicators": [
                    {
                        "sha256Hash": "aafafafafafafafafafafafafafafafafafafa7347878",
                        "indicatorName": "BUFFER_OVERFLOW",
                        "applicationName": "chrome.exe"
                    },
                    {
                        "sha256Hash": "ddfdhjhjdfjdfjdhjfdjfhjdfhjdhfjdhfjdhfjdh7347878",
                        "indicatorName": "INJECT_CODE",
                        "applicationName": "firefox.exe"
                    }
                ],
                "summary": "Threat Summary 23",
                "score": 8,
                "incidentId": "ABCDEF"
            },
            "type": "THREAT",
            "eventTime": 1423163263501,
            "eventId": "EV2",
            "url": "http://carbonblack.com/ui#device/100/incident/ABCDEF",
            "deviceInfo": {
                "deviceType": "WINDOWS",
                "email": "tester@carbonblack.com",
                "deviceId": 100,
                "deviceName": "testers-pc",
                "deviceHostName": null,
                "deviceVersion": "7 SP1",
                "targetPriorityType": "HIGH",
                "targetPriorityCode": 0,
                "internalIpAddress": "55.33.22.11",
                "groupName": "Executives",
                "externalIpAddress": "255.233.222.211"
            },
            "eventDescription": "time|Threat summary 23|score",
            "ruleName": "Alert Rule 2"
        }
    ],
    "message": "Success",
    "success": true
}

Deactivated

The following APIs have been deactivated and are no longer available. Replacement APIs must be used to receive this data.

Find Events

This API was deactivated on January 31st 2022.

Please use the Observations API instead.

GET /integrationServices/v3/event

Retrieves all events matching the input search criteria.

Get details for a Specific Event

This API was deactivated on January 31st 2022.

Please use the Observations API instead.

GET /integrationServices/v3/event/{id}

Retrieve details for an individual event given the event ID (eventId).

Find Processes

This API was deactivated on January 31st 2022.

Please use the Processes Search API instead.

GET /integrationServices/v3/process

Find processes associated with a specific indicator or IP address filter.

Get Details on Alert

This API was deactivated on January 31st 2022.

Please use the Alerts API instead.

GET /integrationServices/v3/alert/{id}

Get details on the events that led to an alert. This includes retrieving metadata around the alert as well as a list of all the events associated with the alert.


Last modified on January 8, 2024