The goal of this document is to list the most common integration use cases for a SOAR (Security Orchestration, Automation, and Response). While many of the use cases are security focused, there is overlap into the IT Operations space as well.
All API requests can be performed on the hostname URLs specified per environment see Construct your Request in the Authentication guide.
There is no longer a need to use api-
URLs for any Carbon Black Cloud APIs.
There are 4 types of API keys:
Custom
: Role Based Authentication; based on “Access Levels” which provide granular CRUD permissions
API
: Used by legacy Endpoint Standard APIs for Audit Logs and Policy Management
SIEM
: Used only for Notifications
LiveResponse
: Additive to key type “API”, provides access to the Live Response API
The Data Forwarder is the recommended method to stream Endpoint Events and/or Alerts to the SIEM, SOAR, or Data Lake solution.
For customers and partners unable to use the Data Forwarder due to the AWS S3 requirement, the Alerts API can be used to get alerts from Carbon Black Cloud. See the VMware Carbon Black Cloud Alert Export Best Practices guide for recommended implementation details.
SOAR actions can generally be broken into three categories:
Context
(get more information about what happened)Remediation
(mitigate the threat)Orchestration
(coordinate the workflow)Assets are referenced by a few names throughout Carbon Black Cloud. Throughout CY21-CY22, these names will likely converge in the UI and APIs to asset
Endpoint
: A conventional compute instance – such as a laptop, server, or VDI instanceDevice
: Often used interchangeably with Endpoint
External Device
: A USB device, the subject of the Endpoint Standard capability Device Control
Workload
: vSphere based virtual machineSensor
: The Carbon Black Cloud agent, runs on an endpoint or workload
Asset
: A placeholder used for anything that’s not a workload, endpoint, or container. Sometimes used as the super-set of inventory.Get the most up to date metadata of a specific process. Very useful for process & cmdline information following a watchlist hit.
org.search.events CREATE, READ
Get the enriched events associated with an Analytics alert, which includes critical alert triage information such as the process cmdline. Find all external network connections made from a specific endpoint. Find all endpoints that have seen a specific registry key modification.
org.search.events CREATE, READ
Identify if the malicious process is still running
device READ
, org.liveresponse.session CREATE, READ, UPDATE, DELETE
, org.liveresponse.process READ
Find and get the full contents of a suspicious MS Office or Powershell file that executed on an endpoint
device READ
, org.liveresponse.session CREATE, READ, UPDATE, DELETE
, org.liveresponse.file READ
Get the latest information about an endpoint, including the state, OS, sensor version, and last check-in
device READ
Fetch a potentially malicious binary and send to a sandbox for analysis
ubs.org.file READ
Get more information about possible binary impersonation. If CBC reports a well known windows system executable with an unknown reputation, get the hash’s metadata like publisher, size, signature
ubs.org.sha256 READ
Following a Mimikatz alert, get security Windows Event Logs to determine recent authentications (I.e. which accounts may have been compromised). Determine which endpoints do not have a specific Windows KB installed and may be vulnerable to the threat you’re investigating. Determine which endpoints have a vulnerable Chrome extension installed
livequery.manage CREATE, READ
Get relevant endpoint events of a watchlist hit. This is very resource intensive for CBC and should be used sparingly
org.search.events READ
Find all endpoints where a certain process (by name or hash) has executed. Find all processes by reputation (NOT_LISTED, KNOWN_MALWARE, etc.)
org.search.events CREATE, READ
List the files, including metadata such as size and last write time directly from the endpoint.
device READ
, org.liveresponse.session CREATE, READ, UPDATE, DELETE
, org.liveresponse.file READ
Get the vulnerabilities (CVEs) and their risks/exploitability identified for a given endpoint
vulnerabilityAssessment.data READ
Given a vulnerability (CVE) identify which endpoints are vulnerable
vulnerabilityAssessment.data READ
Identify if a specific registry key has been set
device READ
, org.liveresponse.session CREATE, READ, UPDATE, DELETE
, org.liveresponse.registry READ
Get information about an external usb device (such as which endpoints it’s been seen on) by vendor, product, and/or serial number
external-device.manage READ
Get a snapshot of a running process before killing it to identify IT issues or analyze malware
device READ
, org.liveresponse.session CREATE, READ, UPDATE, DELETE
, org.liveresponse.memdump READ
Kill a malicious process if it’s still running
device READ
, org.liveresponse.session CREATE, READ, UPDATE, DELETE
, org.liveresponse.process READ, DELETE
Delete a malicious file on an endpoint
device READ
, org.liveresponse.session CREATE, READ, UPDATE, DELETE
, org.liveresponse.file READ, DELETE
When the endpoint is suspected to be compromised, isolate it so that the only network communication allowed is with Carbon Black Cloud
device.quaratine EXECUTE
Ensure a malicious process cannot be executed again across your environment
org.reputations CREATE
Move the endpoint to a more restrictive policy (e.g. one that does not allow powershell or any unknown processes to execute). Move the asset to a policy that has LiveResponse enabled, required for LiveResponse actions.
device.policy UPDATE
Upload and execute a Powershell file on a windows endpoint to gather data or update configuration. Can be combined with the Context Get a file from an endpoint
if the script generates an output file.
device READ
, org.liveresponse.session CREATE, READ, UPDATE, DELETE
, org.liveresponse.file CREATE, READ
, org.liveresponse.process EXECUTE
Add a suspicious file hash to the watchlist (and receive an alert if its ever seen again)
org.watchlists UPDATE
Add a suspicious file hash to the feed (and receive an alert if its ever seen again); ideal for MSSP/IR partners who publish feeds to their customers
org.feeds CREATE, UPDATE
Ignore a false-positive IoC so that it does not introduce future noise
org.watchlists UPDATE
Approve a specific external USB device by vendor, product, and serial number
external-device.manage CREATE
Endpoint should no longer be monitored, but may need to in the future
device.bypass EXECUTE
Remove the registry key used by ransomware to reset the desktop background
device READ
, org.liveresponse.session CREATE, READ, UPDATE, DELETE
, org.liveresponse.registry CREATE, READ, UPDATE, DELETE
Turn off alerting for a noisy watchlist to reduce future alert fatigue
org.watchlists DELETE
Recommendations allow Analysts to tune Carbon Black Cloud, eliminating false positives. For a given alert, identify if there are any associated recommendations (such as add the hash to the approved list). Allow the analyst to approve or reject these recommendations
org.recommendations CREATE, READ, DELETE
Add a process path to the “allow” rules
If the endpoint is sensitive to high-CPU, disable background scanning
device.bg-scan EXECUTE
Endpoint should no longer be monitored, permanently
device.uninstall EXECUTE
Sensor is out of date
org.kit EXECUTE
Dismiss the alert in Carbon Black Cloud with comments; if an analyst looks in the CBC console, they will no longer see that alert and mistakenly triage it.
org.alerts.dismiss EXECUTE
If this specific threat is not relevant for the environment, prevent it from being triggered in the future across any device
org.alerts.dismiss EXECUTE
Add a comment to provide context, in the case someone looks at the alert in the CBC Console
org.alerts.notes CREATE
Notes:
Platform
denotes an API accessible to any Carbon Black Cloud customer regardless of whether they have Endpoint Standard, Enterprise EDR, or a package such as Endpoint Advanced and Endpoint EnterpriseLiveResponse
API Key type was deprecated in favor of more granular RBAC permissions. The Live Response v3 API is deprecated and deactivation is being planned.Currently, every tenant in Carbon Black Cloud requires a separate API key. If your solution supports multitenancy and partners may have multiple Carbon Black Cloud customers, consider supporting multi-tenancy in the SOAR configuration, such as:
org_key
(from the alert, or whatever data set kicked off the SOAR workflow) to automatically choose the correct org keyRoadmap: Organizations setup as MSSPs in Carbon Black Cloud will be able to create an API key that works for each of their child tenants. Many APIs require the child tenant org key to be passed in the request URI. This could simplify the configuration for orgs setup as multi-tenant in Carbon Black Cloud.
Once you’ve identified which actions from the table above, identify the associated input metadata. This likely includes (but is not limited to):
org_key
device_id
process_guid
hash (sha256)
Ensure these fields are parsed from the alert, endpoint event, or other data sources and available to an analyst for automated or ad-hoc workflow creation.
Python developers should use the CBC SDK:
Be sure to configure the integration_name
parameter. Instructions on where to configure the parameter can be found here.
If your integration uses CBAPI, we strongly recommend upgrading to CBC SDK for Carbon Black Cloud integrations. No new functionality will be introduced to CBAPI. For instructions on migrating see here.
If you are not using the Python CBC SDK, set the user agent to help identify your script or application. This ensures that in the future if an API has been deprecated, we can proactively reach out and help you migrate to the supported routes.
Our recommended format is: <integrationName>/<integrationVersion> <languageName>/<languageVersion>
For example: ContosoSOAR/1.3 Powershell/6.0.0
Workflows are chains of actions that are linked together, often to gather context and remediate a specific type of incident.
Note: This section is a living document. If you have SOAR workflow or playbook suggestions, please reach out to the Developer Relations team.
Kick off the Malware workflow when CBC Endpoint Standard generates an alert of type CB Analytics
that contains any of the following:
T_RUN_MALWARE
, T_RUN_VIRUS
, T_REP_VIRUS
RUN_BLACKLIST_APP
, RUN_MALWARE_APP
, DETECTED_MALWARE_APP
, MALWARE_DROP
, COMPANY_BLACKLIST
, DETECTED_BLACKLIST_APP
The Malware workflow may look something like this:
run_state = DID_NOT_RUN
, this indicates CBC will alert on malware detected on disk
run_state = RAN
, the malware at least attempted to run
sensor_action
field of the Analytics alertList running processes on endpoint
Kill process on endpoint
Search for processes by query
Search for processes by query
with a query like filemod_name:malware.exeSearch for process events by process GUID and (optional) event query
event_type:netconn
and limiting the timeframe to around the alert for longer-running processesSearch for processes by query
where the query specifies the netconn_ipv4, netconn_ipv6, or netconn_domain fieldsQuarantine (or Unquarantine) an endpoint
Get endpoint info
Update the endpoint policy
Add (or remove) an IoC from a Watchlist
Get endpoint info
Update the endpoint policy
Kill process on endpoint
Delete file on endpoint
Ban (or unban) Process Hash
Add a note to an alert
Update the endpoint policy
Dismiss an alert (with or without a comment)
When an analyst receives an alert generated by Carbon Black Cloud Endpoint Standard (NGAV) that could indicate credential theft, such as memory scraping of a system process, their next questions are likely:
This is often an extension of the Malware workflow above, but can be identified with TTPs such as READ_SECURITY_DATA
, DUMP_PROCESS_MEMORY
, and MITRE_T1003_OS_CREDENTIAL_DUMP
.
Submit LiveQuery Run
with query SELECT * from logged_in_users
Submit LiveQuery Run
with query SELECT * FROM windows_eventlog WHERE channel = 'Security' AND eventid in (4624, 4625, 4647)
A Device Control alert occurs when an unapproved external USB device is inserted into a protected endpoint and blocked.
USB device
USB device
(or similar models) been seen on other endpoints?USB device
.The Recommendations capability provides context around actions customers can take to reduce false positive alerts in their environment.
threat_id
, which will identify the top alerts by typeGet Alert Recommendations
action to identify if there are any recommendations associated with these alertsSOAR workflow to create ticket for devices with CRITICAL CVEs