VMWare Carbon Black Cloud

the vmware carbon black cloud connector enables seamless integration with swimlane turbine, providing automated actions such as device searches, alert management, and sensor device updates within the security infrastructure vmware carbon black cloud is a comprehensive endpoint security platform that provides organizations with advanced threat detection and response capabilities this connector enables swimlane turbine users to automate critical security operations such as device quarantine, alert management, and vulnerability searches by integrating with vmware carbon black cloud, users can streamline their security workflows, rapidly respond to threats, and enhance their overall security posture without the need for manual intervention prerequisites to effectively utilize the vmware carbon black cloud connector for turbine, ensure you have the following prerequisites http basic authentication with the following parameters url endpoint url for the vmware carbon black cloud api api id unique identifier for api access api secret secret key associated with the api id for authentication capabilities the swimlane vmware carbon black cloud connector has the following capabilities bypass device delete sensor device dismiss alerts get alert by id get alerts get device by id quarantine or unquarantine device search devices search specific device vulnerabilities set background scan for device uninstall sensor device update alert update device policy using the schema following are the definitions for each field, default values, whether it is required, searchable and/or tokenized you can also see accepted values and routes supported per each field possible alert types icons indicate the alert types a field is valid for cb analytics these fields are part of a cb analytics alert type container runtime these fields are part of a container runtime alert type watchlist these fields are part of a watchlist alert type device control these fields are part of a device control alert type host based firewall these fields are part of a host based firewall alert type intrusion detection system these fields are part of a intrusion detection system alert type facet these fields can be used for returning most prevalent values note for fields where the alert types supported column contains no entries, this means this field is available only to mdr customers platform api platform apis are available to all carbon black cloud customers platform api documentation https //developer carbonblack com/reference/carbon black cloud/platform apis https //developer carbonblack com/reference/carbon black cloud/platform apis authentication the x auth token authentication method uses the api id and secret directly in the call to the carbon black cloud apis for more information https //developer carbonblack com/reference/carbon black cloud/authentication https //developer carbonblack com/reference/carbon black cloud/authentication this is a valid curl request some values need to be replaced with yours curl https //defense conferdeploy net/appservices/v6/orgs/abcd1234/devices/ search \\ x post \\ h 'x auth token abcdefghijklmno123456789/abcd123456' \\ h 'content type application/json' \\ d '{"criteria" {"id" \[ "1234567" ]}}' this is the same request with the variables named follow the information on how to create them $ curl {cbc hostname}/{api service category}/{api path} \\ x post \\ h 'x auth token {api secret}/{api id}' \\ h 'content type application/json' \\ d '{{request body}}' create an api key this is like adding a user to a system and setting their access level, except you are granting access to your application or script instead of a user to create an api key, go to settings > api access > api keys tab in the carbon black cloud console select add api key from the far right give the api key a unique name, and select the appropriate access level provided in the table above if you select custom, you will need to choose the access level you created in the prior section • choose a name to clearly distinguish the api from your organization’s other api keys example event forwarder test key • access level types of api , live response and siem are deprecated see the migration guides for details of how to move to new apis hit save, and you will be provided with your api key credentials • api secret key • api id if your api key already exists, you can view your credentials by opening the actions dropdown and selecting api credentials this will reveal your api secret key and api id • if your system becomes compromised, you can generate a new secret key here (this is like changing the password for your application or script) api documentation devices api documentation link https //developer carbonblack com/reference/carbon black cloud/platform/latest/devices apivulnerability assessment api documentation link https //developer carbonblack com/reference/carbon black cloud/platform/latest/vulnerability assessment configurations http basic authentication authenticates using username and password configuration parameters parameter description type required url a url to the target host string required username username string required password password string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions bypass device sets a bypass flag on a device in vmware carbon black cloud using the device id and specified action type endpoint url /appservices/v6/orgs/{{org key}}/device actions method post input argument name type required description org key string required parameter for bypass device action type string required type of the resource device id array optional unique identifier options object optional parameter for bypass device toggle string optional parameter for bypass device output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 204, "response headers" {}, "reason" "ok", "json body" {} } ] delete sensor device removes a sensor device from vmware carbon black cloud by using the device's id and an action type endpoint url /sensor update service/v3/orgs/{{org key}}/jobs/{{job id}} method delete input argument name type required description org key string required parameter for delete sensor device job id string required unique identifier action type string required type of the resource device id array optional unique identifier output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" {} } ] dismiss alerts mark future alerts linked to a threat id as dismissed in vmware carbon black cloud, utilizing org key and alert id endpoint url /appservices/v6/orgs/{{org key}}/alerts/{{alert id}}/workflow method post input argument name type required description org key string required parameter for dismiss alerts alert id string required unique identifier state string required parameter for dismiss alerts comment string optional parameter for dismiss alerts remediation state string optional parameter for dismiss alerts output parameter type description status code number http status code of the response reason string response reason phrase state string output field state remediation string output field remediation last update time string time value comment string output field comment changed by string output field changed by example \[ { "status code" 200, "response headers" {}, "reason" "string", "json body" { "state" "dismissed", "remediation" "nothing", "last update time" "2020 09 14t15 02 04 620z", "comment" "this is an example", "changed by" "a569s6yyre" } } ] get alert by id retrieve detailed information for a specific alert in vmware carbon black cloud using the provided alert id and organization key endpoint url /api/alerts/v7/orgs/{{org key}}/alerts/{{id}} method get input argument name type required description org key string required parameter for get alert by id id string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase org key string output field org key alert url string url endpoint for the request id string unique identifier type string type of the resource backend timestamp string output field backend timestamp user update timestamp object output field user update timestamp backend update timestamp string output field backend update timestamp detection timestamp string output field detection timestamp first event timestamp string output field first event timestamp last event timestamp string output field last event timestamp severity number output field severity reason code string response reason phrase threat id string unique identifier primary event id string unique identifier policy applied string output field policy applied run state string output field run state sensor action string output field sensor action workflow object output field workflow change timestamp string output field change timestamp changed by type string type of the resource changed by string output field changed by closure reason string response reason phrase status string status value example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "org key" "abcd1234", "alert url" "https //defense conferdeploy net/alerts?s\[c]\[query string]=id 52fa009d e2d1 4118 ", "id" "12ab345cd6 e2d1 4118 8a8d 04f521ae66aa", "type" "watchlist", "backend timestamp" "2023 04 14t21 30 40 570z", "user update timestamp" null, "backend update timestamp" "2023 04 14t21 30 40 570z", "detection timestamp" "2023 04 14t21 27 14 719z", "first event timestamp" "2023 04 14t21 21 42 193z", "last event timestamp" "2023 04 14t21 21 42 193z", "severity" 8, "reason" "process infdefaultinstall exe was detected by the report \\"defense evasion sign ", "reason code" "05696200 88e6 3691 a1e3 8d9a64dbc24e 7828aec8 8502 3a43 ae68 41b5050dab5b", "threat id" "0569620088e6669121e38d9a64dbc24e", "primary event id" " 7rlzfhcsgwksrf55b 4ig 0" } } ] get alerts retrieve alerts from vmware carbon black cloud using specified query, criteria, and exclusions requires an 'org key' path parameter endpoint url /api/alerts/v7/orgs/{{org key}}/alerts/ search method post input argument name type required description org key string required parameter for get alerts query string optional a lucene formatted query using the alert search fields time range object optional a time range filter on backend timestamp defaults to "range" with value " 2w" start string optional parameter for get alerts end string optional parameter for get alerts range string optional parameter for get alerts criteria object optional parameter for get alerts minimum severity number optional parameter for get alerts device os array optional parameter for get alerts exclusions object optional parameter for get alerts type array optional type of the resource device os version array optional parameter for get alerts start number optional parameter for get alerts rows number optional parameter for get alerts sort array optional parameter for get alerts field string optional parameter for get alerts order string optional parameter for get alerts output parameter type description status code number http status code of the response reason string response reason phrase results array result of the operation org key string output field org key alert url string url endpoint for the request id string unique identifier type string type of the resource backend timestamp string output field backend timestamp user update timestamp object output field user update timestamp backend update timestamp string output field backend update timestamp detection timestamp string output field detection timestamp first event timestamp string output field first event timestamp last event timestamp string output field last event timestamp severity number output field severity reason string response reason phrase reason code string response reason phrase threat id string unique identifier primary event id string unique identifier policy applied string output field policy applied run state string output field run state sensor action string output field sensor action workflow object output field workflow change timestamp string output field change timestamp changed by type string type of the resource changed by string output field changed by example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "results" \[], "num found" 123, "num available" 123 } } ] get device by id retrieve details for a specific device from vmware carbon black cloud using the provided organization key and device id endpoint url /appservices/v6/orgs/{{org key}}/devices/{{device id}} method get input argument name type required description org key string required parameter for get device by id device id string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase activation code object output field activation code activation code expiry time string time value ad group id number unique identifier appliance name object name of the resource appliance uuid object unique identifier auto scaling group name object name of the resource av ave version string output field av ave version av engine string output field av engine av last scan time object time value av master boolean output field av master av pack version string output field av pack version av product version string output field av product version av status array status value av update servers object output field av update servers av vdf version string output field av vdf version base device object output field base device cloud provider account id object unique identifier cloud provider resource id object unique identifier cloud provider tags object unique identifier cluster name object name of the resource current sensor policy name string name of the resource datacenter name object response data deployment type string type of the resource example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "activation code" null, "activation code expiry time" "2022 07 11t06 53 06 190z", "ad group id" 0, "appliance name" null, "appliance uuid" null, "auto scaling group name" null, "av ave version" "8 3 64 172", "av engine" "4 15 1 560 ave 8 3 64 172\ avpack 8 5 2 64\ vdf 8 19 20 4\ vdfdate 20220711", "av last scan time" null, "av master" false, "av pack version" "8 5 2 64", "av product version" "4 15 1 560", "av status" \[], "av update servers" null, "av vdf version" "8 19 20 4" } } ] quarantine or unquarantine device isolate or reconnect a device in vmware carbon black cloud by specifying 'org key' and 'action type' endpoint url /appservices/v6/orgs/{{org key}}/device actions method post input argument name type required description org key string required organisation key action type string required action to perform on selected devices device id array optional list of devices to perform action on either device id or search is required search object optional a device search device actions will be performed on the result set of this search criteria object optional parameter for quarantine or unquarantine device exclusions object optional parameter for quarantine or unquarantine device query string optional parameter for quarantine or unquarantine device options object optional parameter for quarantine or unquarantine device toggle string optional determines whether to enable or disable the action auto assign boolean optional when true, devices will be automatically assigned to the policy configured with their associated asset group or use the default policy if no asset group is associated auto assignment will remove any existing manual override sensor version object optional devices will be updated to the specified sensor version based on the device's sensor kit type policy id number optional devices will have a manual override to this policy id output parameter type description status code number http status code of the response reason string response reason phrase response text string output field response text example \[ { "status code" 204, "response headers" { "date" "thu, 01 aug 2024 04 33 23 gmt", "connection" "keep alive", "cache control" "no cache, no store, max age=0, must revalidate", "expires" "0", "pragma" "no cache", "set cookie" "jsessionid=903f464982690571ec30ee48716a77c8; path=/appservices; secure; httponly", "x content type options" "nosniff", "x frame options" "deny", "x xss protection" "1; mode=block" }, "reason" "no content", "response text" "" } ] search devices locate devices within a specified organization in vmware carbon black cloud using the provided org key endpoint url /appservices/v6/orgs/{{org key}}/devices/ search method post input argument name type required description org key string required parameter for search devices criteria object optional criteria is an object that represents values that must be in the results ad distinguished name array optional name of the resource ad domain array optional parameter for search devices ad group id array optional unique identifier ad org unit array optional parameter for search devices auto scaling group name array optional name of the resource base device boolean optional parameter for search devices cloud provider account id string optional unique identifier cloud provider managed identity array optional unique identifier cloud provider network array optional unique identifier cloud provider resource group array optional unique identifier cloud provider resource id array optional unique identifier cloud provider scale group array optional unique identifier cloud provider tags array optional unique identifier cluster name array optional name of the resource compliance status array optional status value datacenter name array optional response data deployment type array optional type of the resource esx host name array optional name of the resource golden device id array optional unique identifier golden device status array optional status value asset group id array optional unique identifier asset group name array optional name of the resource host based firewall status array optional status value output parameter type description status code number http status code of the response reason string response reason phrase num found number output field num found results array result of the operation activation code object output field activation code activation code expiry time string time value ad domain object output field ad domain ad group id number unique identifier ad org unit object output field ad org unit appliance name object name of the resource appliance uuid object unique identifier auto scaling group name object name of the resource av ave version string output field av ave version av engine string output field av engine av last scan time object time value av master boolean output field av master av pack version string output field av pack version av product version string output field av product version av status array status value av update servers object output field av update servers av vdf version string output field av vdf version base device object output field base device cloud provider account id object unique identifier cloud provider resource id object unique identifier cloud provider tags array unique identifier example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "num found" 1, "results" \[] } } ] search specific device vulnerabilities retrieve vulnerability information for a specific device in vmware carbon black cloud using the organization key and device id endpoint url /vulnerability/assessment/api/v1/orgs/{{org key}}/devices/{{device id}}/vulnerabilities/ search method post input argument name type required description org key string required filter down to a single organization device id string required unique identifier dataforexport boolean optional whether to send detailed data for export if not set to true, vuln info will be null query string optional query to search vulnerability list rows number optional for pagination, how many results to return per page maximum value is 1000 start number optional for pagination, where to start retrieving results from criteria object optional criteria is an object that represents values that must be in the results sort array optional sort is a collection of sort parameters that specify a field and order to sort the results only one sort can be specified at this time field string optional parameter for search specific device vulnerabilities order string optional parameter for search specific device vulnerabilities output parameter type description status code number http status code of the response reason string response reason phrase num found number output field num found results array result of the operation os product id string unique identifier category string output field category os info object output field os info os type string type of the resource os name string name of the resource os version string output field os version os arch string output field os arch product info object output field product info vendor string output field vendor product string output field product version string output field version release string output field release arch string output field arch vuln info object output field vuln info cve id string unique identifier cve description string output field cve description risk meter score number score value severity string output field severity fixed by string output field fixed by solution object output field solution created at string output field created at example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "num found" 123, "results" \[] } } ] set background scan for device configures background scan settings on a device in vmware carbon black cloud using the device id and specified action type endpoint url /appservices/v6/orgs/{{org key}}/device actions method post input argument name type required description org key string required parameter for set background scan for device action type string required type of the resource device id array optional unique identifier options object optional parameter for set background scan for device toggle string optional parameter for set background scan for device output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 204, "response headers" {}, "reason" "successful device action creation", "json body" {} } ] uninstall sensor device initiates the uninstallation of a sensor on a device by using the device id and organization key in vmware carbon black cloud endpoint url /appservices/v6/orgs/{{org key}}/device actions method post input argument name type required description org key string required parameter for uninstall sensor device action type string required type of the resource device id array required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase response text string output field response text example \[ { "status code" 204, "response headers" { "date" "mon, 18 mar 2024 10 38 47 gmt", "connection" "keep alive", "cache control" "no cache, no store, max age=0, must revalidate", "expires" "0", "pragma" "no cache", "set cookie" "jsessionid=a54f220267aaefa2f8a7f2b702152306; path=/appservices; secure; httponly", "x content type options" "nosniff", "x frame options" "deny", "x xss protection" "1; mode=block" }, "reason" "no content", "response text" "" } ] update alert performs an asynchronous update of alerts in vmware carbon black cloud using the 'org key' path parameter endpoint url /api/alerts/v7/orgs/{{org key}}/alerts/workflow method post input argument name type required description org key string required parameter for update alert query string optional parameter for update alert time range object optional parameter for update alert start string optional parameter for update alert end string optional parameter for update alert range string optional parameter for update alert criteria string optional parameter for update alert exclusions string optional parameter for update alert determination string optional parameter for update alert closure reason string optional response reason phrase status string optional status value note string optional parameter for update alert output parameter type description status code number http status code of the response reason string response reason phrase request id string unique identifier example \[ { "status code" 204, "response headers" {}, "reason" "ok", "json body" { "request id" "5372752" } } ] update device policy updates an existing device policy in vmware carbon black cloud using the provided organization key and policy id endpoint url /policyservice/v1/orgs/{{org key}}/policies/{{policy id}} method put input argument name type required description org key string required parameter for update device policy policy id string required unique identifier id number optional unique identifier name string optional name of the resource org key string optional parameter for update device policy priority level string optional parameter for update device policy position number optional parameter for update device policy is system boolean optional parameter for update device policy description string optional parameter for update device policy auto deregister inactive vdi interval ms number optional parameter for update device policy auto delete known bad hashes delay object optional parameter for update device policy av settings object optional parameter for update device policy avira protection cloud object optional parameter for update device policy enabled boolean optional parameter for update device policy max exe delay number optional parameter for update device policy max file size number optional parameter for update device policy risk level number optional parameter for update device policy on access scan object optional parameter for update device policy enabled boolean optional parameter for update device policy mode string optional parameter for update device policy on demand scan object optional parameter for update device policy enabled boolean optional parameter for update device policy profile string optional parameter for update device policy schedule object optional parameter for update device policy days object optional parameter for update device policy output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier name string name of the resource org key string output field org key priority level string output field priority level position number output field position is system boolean output field is system description string output field description auto deregister inactive vdi interval ms number output field auto deregister inactive vdi interval ms auto delete known bad hashes delay object output field auto delete known bad hashes delay av settings object output field av settings avira protection cloud object output field avira protection cloud enabled boolean output field enabled max exe delay number output field max exe delay max file size number output field max file size risk level number output field risk level on access scan object output field on access scan enabled boolean output field enabled mode string output field mode on demand scan object output field on demand scan enabled boolean output field enabled profile string output field profile schedule object output field schedule days object output field days example \[ { "status code" 204, "response headers" {}, "reason" "ok", "json 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 f ", "auto deregister inactive vdi interval ms" 0, "auto delete known bad hashes delay" null, "av settings" {}, "rules" \[], "directory action rules" \[], "sensor settings" \[], "managed detection response permissions" {}, "version" null } } ] response headers header description example cache control directives for caching mechanisms no cache, no store, max age=0, must revalidate connection http response header connection keep alive content encoding http response header content encoding gzip content type the media type of the resource application/json date the date and time at which the message was originated fri, 07 jun 2024 08 36 38 gmt expires the date/time after which the response is considered stale 0 pragma http response header pragma no cache requestid http response header requestid 77fcfadb1471584ad917f590f10d040a set cookie http response header set cookie jsessionid=a54f220267aaefa2f8a7f2b702152306; path=/appservices; secure; httponly transfer encoding http response header transfer encoding chunked vary http response header vary accept encoding x content type options http response header x content type options nosniff x frame options http response header x frame options deny x xss protection http response header x xss protection 0 notes set background scan for device action not supported on devices of os type linux update alerts action bulk update alerts workflow this is an async operation that updates all alerts that match the search criteria of the request first call this route to start the update job the response contains a request id use this in the job details route to check the progress of the operation when the job is complete, all alerts matching the criteria will have the updates applied use the alert search request to view updated records search devices action has the criteria please refer to https //developer carbonblack com/reference/carbon black cloud/platform/latest/devices api/#search devices https //developer carbonblack com/reference/carbon black cloud/platform/latest/devices api/#search devices search specific device vulnerabilities action has the criteria please refer to https //developer carbonblack com/reference/carbon black cloud/platform/latest/vulnerability assessment/#search specific device vulnerabilities https //developer carbonblack com/reference/carbon black cloud/platform/latest/vulnerability assessment/#search specific device vulnerabilities get alerts action for criteria and exclusions objects data in request body please refer to https //developer carbonblack com/reference/carbon black cloud/platform/latest/alert search fields https //developer carbonblack com/reference/carbon black cloud/platform/latest/alert search fields for more information on get alerts api please refer to https //developer carbonblack com/reference/carbon black cloud/platform/latest/alerts api/#find alerts https //developer carbonblack com/reference/carbon black cloud/platform/latest/alerts api/#find alerts