VMWare Carbon Black App Control

the vmware carbon black app control connector allows for seamless integration with swimlane turbine, providing automated security orchestration and response capabilities vmware carbon black app control is a leading endpoint security platform that provides comprehensive protection against advanced threats this connector enables swimlane turbine users to automate critical security tasks such as file approvals, rule changes, and threat investigations by integrating with vmware carbon black app control, users can streamline their security operations, enforce compliance, and respond to threats with speed and precision limitations none to date supported versions this vmware carbon black app control connector uses the version 1 api additional docs https //developer carbonblack com/reference/enterprise protection/authentication https //developer carbonblack com/reference/enterprise protection/8 0/rest api prerequisites to effectively utilize the vmware carbon black app control connector with swimlane turbine, ensure you have the following prerequisites api key authentication with the following parameters url the endpoint url for the vmware carbon black app control api api key your personal api key provided by vmware carbon black app control for secure access authentication methods api key authentication url endpoint url for the vmware carbon black app control api api key unique identifier to authenticate with the vmware carbon black app control api that api key confers all rights and capabilities assigned to that user to anyone possessing the api key setup instructions to find a api key corresponding with a particular carbon black app control user account, log into the console as an administrator, then select administration > login accounts find the user in the list then click the “edit” button on the left hand side of the row containing their username this will show the details for the selected user at the bottom of the details page, click the checkbox next to “show api token” in the api section this will reveal the api token associated with the given user if no api token is revealed, click the “generate” button if a new api token was created, it must be saved with the “save” button before it becomes active add this api key to the asset capabilities this vmware carbon black app control connector provides the following capabilities approve file change file rule by hash change publisher state change rule or ban/accept file hash close approval request file upload local file approval lookup file instance query to get user or device details searching or query tickets approve file approves a file in vmware carbon black app control using the file instance id and local state provided change local file instance state required permissions ‘view files’, ‘change local state’ vmware carbon black app control's documentation for this action can be found https //developer carbonblack com/reference/enterprise protection/8 0/rest api/#fileinstance change file rule by hash create or edit a file rule, or change the file state in vmware carbon black app control using a specific hash and policy ids required permissions ‘view files’, ‘manage files’ vmware carbon black app control's documentation for this action can be found https //developer carbonblack com/reference/enterprise protection/8 0/rest api/#filerule change publisher state alters the state of a publisher in vmware carbon black app control using the specified 'id' and 'publisher state' required permissions ‘view software rules pages’, ‘manage publisher rules’ vmware carbon black app control's documentation for this action can be found https //developer carbonblack com/reference/enterprise protection/8 0/rest api/#publisher change rule or ban/accept file hash updates an existing file rule in vmware carbon black app control using the file's hash, desired state, and policy ids required permissions ‘view files’, ‘manage files’ vmware carbon black app control's documentation for this action can be found https //developer carbonblack com/reference/enterprise protection/8 0/rest api/#filerule close approval request closes an approval request in vmware carbon black app control using a specified id and status update required permissions ‘view approval requests’, ‘manage approval requests’ vmware carbon black app control's documentation for this action can be found https //developer carbonblack com/reference/enterprise protection/8 0/rest api/#approvalrequest file upload upload a file to a specified computer within vmware carbon black app control using the computer id required permissions ‘view file uploads’, ‘manage uploads of inventoried files’ vmware carbon black app control's documentation for this action can be found https //developer carbonblack com/reference/enterprise protection/8 0/rest api/#fileupload local file approval approve or change the state of a local file instance in vmware carbon black app control using file id, acknowledgment status, and target computer id required permissions ‘view files and applications’, ‘manage files’ vmware carbon black app control's documentation for this action can be found https //developer carbonblack com/reference/enterprise protection/8 0/rest api/#filecatalog lookup file instance retrieves objects matching specified criteria from vmware carbon black app control required permissions ‘view files’ searching functionality can be found https //developer carbonblack com/reference/enterprise protection/8 0/rest api/#searching vmware carbon black app control's documentation for this action can be found https //developer carbonblack com/reference/enterprise protection/8 0/rest api/#fileinstance query to get user or device details retrieve detailed information on users or devices from vmware carbon black app control required permissions ‘view login accounts and user roles’ searching functionality can be found https //developer carbonblack com/reference/enterprise protection/8 0/rest api/#searching vmware carbon black app control's documentation for this action can be found https //developer carbonblack com/reference/enterprise protection/8 0/rest api/#user searching or query tickets executes a search in vmware carbon black app control to return objects matching specified criteria required permissions ‘view events’ searching functionality can be found https //developer carbonblack com/reference/enterprise protection/8 0/rest api/#searching vmware carbon black app control's documentation for this action can be found https //developer carbonblack com/reference/enterprise protection/8 0/rest api/#event configurations carbon black app control api key authentication authenticates using an api key configuration parameters parameter description type required url a url to the target host string required x auth token api key string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions approve file approves a file in vmware carbon black app control with specified id and local state, updating its status endpoint url /api/bit9platform/v1/fileinstance method post input argument name type required description id number optional unique id of this file instance localstate number optional target local state for the file on the agent can be one of 1=unapproved 2=approved note that changed local state might not be reflected in the object immediately, but only after agent reports new state input example {"json body" {"id" 1,"localstate" 2}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"response headers" {"content length" "140","content type" "application/json","date" "fri, 14 feb 2025 20 37 23 gmt"},"reason" "ok","json body" {}} change file rule by hash create or update a file rule and its state in vmware carbon black app control using the specified hash and policy ids endpoint url /api/bit9platform/v1/filerule method post input argument name type required description hash string optional hash of file to update file state filestate number optional file state for hash, defaults to 3 which is banning the hash 1 = un approve, 2 = approve policyids string optional comma separated list of policy ids to add banned hash to 0 for global rule input example {"json body" {"hash" "64a4f54d6863d59f1121a91554b55e9a","filestate" 3,"policyids" "10,11"}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"response headers" {"content length" "140","content type" "application/json","date" "fri, 14 feb 2025 20 37 23 gmt"},"reason" "ok","json body" {}} change publisher state alters the state of a publisher in vmware carbon black app control using the specified 'id' and 'publisher state' endpoint url /api/bit9platform/v1/publisher/{{id}} method put input argument name type required description path parameters id number required id of publisher to change publisherstate number optional state for this publisher can be one of 1=unapproved, 2=approved, 3=banned, 4=approved by policy, 5=banned by policy input example {"json body" {"publisherstate" 2},"path parameters" {"id" 1}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"response headers" {"content length" "140","content type" "application/json","date" "mon, 17 feb 2025 20 37 23 gmt"},"reason" "ok","json body" {}} change rule or ban/accept file hash updates or sets a file rule status to ban/accept based on the hash in vmware carbon black app control, using the file's id and policy ids endpoint url /api/bit9platform/v1/filerule/{{id}} method put input argument name type required description path parameters id number required id of file rule to create or update filestate number optional file state for hash, defaults to 3 which is banning the hash file state for this rule can be one of 1=unapproved, 2=approved, 3=banned hash string optional hash of file to update file state policyids string optional comma separated list of policy ids to add banned hash to 0 for global rule input example {"json body" {"filestate" "banned","hash" "64a4f54d6863d59f1121a91554b55e9a","policyids" "10,11"},"path parameters" {"id" 1}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"response headers" {"content length" "140","content type" "application/json","date" "wed, 19 feb 2025 20 37 23 gmt"},"reason" "ok","json body" {}} close approval request closes an existing approval request in vmware carbon black app control by setting the status for a given id endpoint url /api/bit9platform/v1/approvalrequest method post input argument name type required description id number optional unique approval request id resolutioncomments string optional comments by request resolver status number optional request status can be one of 1=new, 2=open, 3=closed, 4=escalated prohibited transitions are from any status back to 0 or 1 input example {"json body" {"id" 1,"resolutioncomments" "","status" 3}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"response headers" {"content length" "140","content type" "application/json","date" "tue, 18 feb 2025 20 37 23 gmt"},"reason" "ok","json body" {}} file upload uploads a file to a specified computer in vmware carbon black app control using the provided computer id endpoint url /api/bit9platform/v1/fileupload method post input argument name type required description computerid number optional id of computer from which to upload the file if 0, system will find best computer to get the file from filecatalogid number optional id of filecatalog entry for file to upload priority number optional upload priority in range \[ 2, 2], where 2 is highest priority default priority is 0 uploadstatus number optional status of upload status of upload in progress can be changed to 5 (cancelled) any upload can be changed to 6 (deleted) can be one of 0 = queued, 1 = initiated, 2 = uploading, 3 = completed, 4 = error, 5 = cancelled, 6 = deleted input example {"json body" {"computerid" 2,"filecatalogid" 3,"priority" 2,"uploadstatus" 5}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"response headers" {"content length" "140","content type" "application/json","date" "wed, 19 feb 2025 20 37 23 gmt"},"reason" "ok","json body" {}} local file approval approve or modify the state of a local file on vmware carbon black app control using file id, acknowledgment status, and target computer id endpoint url /api/bit9platform/v1/filecatalog/{{id}} method put input argument name type required description path parameters id number required id of file catalog object parameters acknowledge boolean required new acknowledge flag default value is false parameters changelocalstateforcomputerid number required change local approval state for this computer id parameters newapprovalstate number required the new approval state to change to 1 = unapproved, 2 = approved input example {"parameters" {"acknowledge"\ false,"changelocalstateforcomputerid" 1,"newapprovalstate" 2},"path parameters" {"id" 1}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"response headers" {"content length" "140","content type" "application/json","date" "fri, 14 feb 2025 20 37 23 gmt"},"reason" "ok","json body" {}} lookup file instance retrieves matching objects from vmware carbon black app control based on specified criteria endpoint url /api/bit9platform/v1/fileinstance method get input argument name type required description parameters q array optional query condition (optional multiple query conditions are supported) for more details see readme parameters group string optional field name to group by parameters sort string optional field name to sort by sorting is optional and can be defined with a single attribute \&sort=xyz \[asc desc] there can be only one sorting field default sort order (if omitted) is asc xyz is field name from the result set parameters offset number optional offset in query results parameters limit number optional maximum number of results to return when 0 or not present, all results will be returned when 1, only count will be returned input example {"parameters" {"q" \["filecatalogid 1","computerid 1"],"group" "","sort" "","offset" 0,"limit" 0}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"response headers" {"content length" "140","content type" "application/json","date" "mon, 17 feb 2025 20 37 23 gmt"},"reason" "ok","json body" {}} query to get user or device details retrieve detailed information on users or devices from vmware carbon black app control endpoint url /api/bit9platform/v1/user method get input argument name type required description parameters q array optional query condition (optional multiple query conditions are supported) for more details see readme parameters group string optional field name to group by parameters grouptype string optional field name to sort by sorting is optional and can be defined with a single attribute \&sort=xyz \[asc desc] there can be only one sorting field default sort order (if omitted) is asc xyz is field name from the result set parameters groupstep number optional step for windowed grouping (optional, for time based fields only) parameters sort string optional field name to sort by parameters offset number optional offset in query results parameters limit number optional maximum number of results to return when 0 or not present, all results will be returned when 1, only count will be returned parameters expand array optional foreign key fields to expand input example {"parameters" {"q" \["filecatalogid 1","computerid 1"],"group" "","grouptype" "","groupstep" 2,"sort" "","offset" 0,"limit" 0,"expand" \["emailaddress"]}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"response headers" {"content length" "140","content type" "application/json","date" "wed, 19 feb 2025 20 37 23 gmt"},"reason" "ok","json body" {}} searching or query tickets executes a search in vmware carbon black app control to return objects matching specified criteria endpoint url /api/bit9platform/v1/event method get input argument name type required description parameters q array optional query condition (optional multiple query conditions are supported) for more details see readme parameters group string optional field name to group by parameters sort string optional field name to sort by sorting is optional and can be defined with a single attribute \&sort=xyz \[asc desc] there can be only one sorting field default sort order (if omitted) is asc xyz is field name from the result set parameters offset number optional offset in query results parameters limit number optional maximum number of results to return when 0 or not present, all results will be returned when 1, only count will be returned input example {"parameters" {"q" \["filecatalogid 1","computerid 1"],"group" "","sort" "","offset" 0,"limit" 0}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"response headers" {"content length" "140","content type" "application/json","date" "mon, 17 feb 2025 20 37 23 gmt"},"reason" "ok","json body" {}} response headers header description example content length the length of the response body in bytes 140 content type the media type of the resource application/json date the date and time at which the message was originated mon, 17 feb 2025 20 37 23 gmt