About the connector
VMware Carbon Black EDR captures information about events and data records for every endpoint and offers you the ability to respond and remediate attacks in real-time, stopping active attacks and repairing the damage quickly.
This document provides information about the VMware Carbon Black EDR connector, which facilitates automated interactions, with a VMware Carbon Black EDR server using FortiSOAR™ playbooks. Add the VMware Carbon Black EDR connector as a step in FortiSOAR™ playbooks and perform automated operations, such as isolating endpoints, getting information about files, and automatically getting details of a process running on an endpoint and blocking a particular MD5 hash, which provides you the ability to investigate and contain a file-based incident in a fully automated manner.
Note: CarbonBlack Response has been rebranded to VMware Carbon Black EDR. For older versions of this connector, see the CarbonBlack Response documentation.
Version information
Connector Version: 2.0.2
Authored By: Community
Certified: No
Release Notes for version 2.0.2
The following enhancements have been made to the VMware Carbon Black EDR in version 2.0.2:
- Rebranded CarbonBlack Response to VMware Carbon Black EDR.
- Upgraded the connector dependencies to make this version of the connector compatible with Python 3.9.
Installing the connector
Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root user to install connectors from an SSH session:
yum install cyops-connector-carbonblack-response
Prerequisites to configuring the connector
- You must have the IP address or Hostname URL of the VMware Carbon Black EDR server to which you will connect and perform the automated operations and the API key used to access the VMware Carbon Black EDR API.
- The FortiSOAR™ server should have outbound connectivity to port 443 on the VMware Carbon Black EDR server.
Minimum Permissions Required
Configuring the connector
For the procedure to configure a connector, click here.
Configuration parameters
In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the VMware Carbon Black EDR connector card. On the connector popup, click the Configurations tab to enter the required configuration details:
| Parameter |
Description |
| Server URL |
IP address or Hostname URL of the VMware Carbon Black EDR server to which you will connect and perform the automated operations.
If you do not specify the http or https protocol in this field, then by default the https protocol is used. |
| API Key |
API key that is configured for your account to access the VMware Carbon Black EDR REST API. |
| Verify SSL |
Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True. |
Actions supported by the connector
The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™:
| Function |
Description |
Annotation and Category |
| Get Sensor(s) Information |
Retrieves details about all sensors (endpoints) or specific sensor(s) from the VMware Carbon Black EDR server, based on the input parameters you have specified. |
get_endpoint_info
Investigation |
| Isolate Sensor |
Isolates sensor(s) on the VMware Carbon Black EDR server based on Hostname, IP Address, Process Name, or Filehash(MD5) you have specified. |
isolate_endpoint
Containment |
| Remove Isolation |
Removes isolation on the sensor(s) from the VMware Carbon Black EDR server based on Hostname, IP Address, Process Name, or Filehash(MD5) you have specified. |
unisolate_endpoint
Remediation |
| Get All Processes |
Retrieves a list of all running processes along with their details from the VMware Carbon Black EDR server, based on the sensor details you have specified. |
get_processes
Investigation |
| Get Process Connections |
Retrieves a list of connections for a specific sensor and process from the VMware Carbon Black EDR server, based on the sensor and process details you have specified. |
get_network_connections
Investigation |
| Terminate Process |
Terminates a process running on an endpoint on the VMware Carbon Black EDR server, based on the sensor and process details you have specified. |
terminate_process
Investigation |
| Get File Information |
Retrieves information about a file from the VMware Carbon Black EDR server, based on the filehash you have specified. |
get_file_info
Investigation |
| Hunt File |
Hunts for a file and retrieves details for that file from the VMware Carbon Black EDR server, based on the file type and filehash you have specified. |
hunt_file
Investigation |
| Get All Block Hashes |
Retrieves a list of all blacklisted filehashes and their details from the VMware Carbon Black EDR server. |
get_hash_blacklist
Investigation |
| Block Hash |
Blocks a particular file on the VMware Carbon Black EDR server, based on the filehash (MD5 only) you have specified. |
block_hash
Containment |
| Unblock Hash |
Unblocks a particular file on the VMware Carbon Black EDR server, based on the filehash (MD5 only) you have specified. |
unblock_hash
Remediation |
| Delete File |
Deletes a particular file from the VMware Carbon Black EDR server, based on the sensor details and file path you have specified. |
delete_file
Containment |
| Run Query |
Runs a search query on the endpoint to retrieve the information of binary or process from the VMware Carbon Black EDR server. |
run_advance_search
Investigation |
| Search Alerts |
Searches for alerts on the VMware Carbon Black EDR server, based on the search query you have specified. |
search_alert
Investigation |
| Update Alert |
Updates the status of an alert on the VMware Carbon Black EDR server, based on the input parameters you have specified. |
update_alert
Investigation |
| Bulk Update Alerts |
Updates the status of multiple alerts on the VMware Carbon Black EDR server, based on the input parameters you have specified. |
update_alert
Investigation |
| Get Watchlist |
Retrieves a list along with its details for all watchlists or specific watchlist (if you have specified the watchlist ID) from the VMware Carbon Black EDR server. |
get_watchlist
Investigation |
operation: Get Sensor(s) Information
Input parameters
| Parameter |
Description |
| Filter Options |
Options based on which the results retrieved from the VMware Carbon Black EDR server will be filtered.
You can choose from the following options:
- All: Retrieves a list along with the details of all the sensors from the VMware Carbon Black EDR server.
- Hostname: Retrieves a list along with the details of all sensors from the VMware Carbon Black EDR server that match the hostname you specify.
- IP Address: Retrieves a list along with the details of all sensors from the VMware Carbon Black EDR server that match the IP address you specify.
- Sensor ID: Retrieves a list along with the details of all sensors from the VMware Carbon Black EDR server that match the Sensor ID you specify.
|
| Value |
Specify the value of the filter option you have selected. If you have selected All do not add any input to this field.
For example, if you select IP Address, then enter the IP address based on which you want to filter the sensor results retrieved from the VMware Carbon Black EDR servers. |
Output
The output contains the following populated JSON schema:
{
"node_id": "",
"display": "",
"emet_telemetry_path": "",
"restart_queued": "",
"supports_isolation": "",
"sensor_uptime": "",
"build_version_string": "",
"registration_time": "",
"cookie": "",
"num_eventlog_bytes": "",
"uninstalled": "",
"boot_id": "",
"emet_version": "",
"systemvolume_free_size": "",
"network_isolation_enabled": "",
"license_expiration": "",
"sensor_health_status": "",
"is_isolating": "",
"computer_dns_name": "",
"emet_dump_flags": "",
"clock_delta": "",
"status": "",
"os_environment_display_string": "",
"emet_is_gpo": "",
"systemvolume_total_size": "",
"next_checkin_time": "",
"id": "",
"computer_sid": "",
"supports_cblr": "",
"supports_2nd_gen_modloads": "",
"num_storefiles_bytes": "",
"build_id": "",
"physical_memory_size": "",
"last_update": "",
"notes": "",
"shard_id": "",
"last_checkin_time": "",
"group_id": "",
"parity_host_id": "",
"emet_report_setting": "",
"sensor_health_message": "",
"uptime": "",
"computer_name": "",
"os_environment_id": "",
"uninstall": "",
"power_state": "",
"os_type": "",
"emet_exploit_action": "",
"emet_process_count": "",
"event_log_flush_time": "",
"network_adapters": ""
}
operation: Isolate Sensor
Input parameters
| Parameter |
Description |
| Input Type |
Options based on which you want to isolate a sensor on the VMware Carbon Black EDR server.
You can choose from the following options:
- Hostname: Name of the host that you want to isolate on the VMware Carbon Black EDR server.
- IP Address: Single IPv4 address of the host that you want to isolate on the VMware Carbon Black EDR server.
- Process Name: Isolate all sensors on the VMware Carbon Black EDR server on which the specified process name exists.
- Filehash: Isolate all sensors on the VMware Carbon Black EDR server on which the specified filehash (MD5) exists.
|
| Value |
Specify the value of the input type you have selected.
For example, if you select IP Address, then enter the IPv4 address of the host that you want to isolate on the VMware Carbon Black EDR server. |
Output
The output contains the following populated JSON schema:
{
"isolated_hosts": []
}
operation: Remove Isolation
Input parameters
| Parameter |
Description |
| Input Type |
Options based on which you want to remove the isolation on the sensor(s) from the VMware Carbon Black EDR server.
You can choose from the following options:
- Hostname: Name of the host whose isolation you want to remove from the VMware Carbon Black EDR server.
- IP Address: Single IPv4 address of the host whose isolation you want to remove from the VMware Carbon Black EDR server.
- Process Name: Remove isolation for all sensors on the VMware Carbon Black EDR server on which the specified process name exists.
- Filehash: Remove isolation for all sensors on the VMware Carbon Black EDR server on which the specified filehash (MD5) exists.
|
| Value |
Specify the value of the input type you have selected.
For example, if you select IP Address, then enter the IPv4 address of the host whose isolation you want to remove from the VMware Carbon Black EDR server. |
Output
The output contains the following populated JSON schema:
{
"unisolated_hosts": []
}
operation: Get All Processes
Input parameters
| Parameter |
Description |
| Sensor Details |
Options based on which you want to retrieve running process information from the VMware Carbon Black EDR server.
You can choose from the following options:
- Hostname: Name of the host for which you want to retrieve process information from the VMware Carbon Black EDR server.
- IP Address: Single IPv4 address of the host for which you want to retrieve process information from the VMware Carbon Black EDR server.
- Sensor ID: ID of the sensor for which you want to retrieve process information from the VMware Carbon Black EDR server.
|
| Value |
Specify the value of the sensor details you have selected.
For example, if you select IP Address, then enter the IPv4 address of the host for which you want to retrieve process information from the VMware Carbon Black EDR server. |
Output
The output contains the following populated JSON schema:
{
"sid": "",
"parent": "",
"pid": "",
"command_line": "",
"path": "",
"create_time": "",
"parent_guid": "",
"proc_guid": "",
"username": ""
}
operation: Get Process Connections
Input parameters
| Parameter |
Description |
| Sensor Details |
Options based on which you want to specify the endpoint for which you want to retrieve process connection information from the VMware Carbon Black EDR server.
You can choose from the following options:
- Hostname: Name of the host for which you want to retrieve process connection information from the VMware Carbon Black EDR server.
- IP Address: Single IPv4 address of the host for which you want to retrieve process connection information from the VMware Carbon Black EDR server.
|
| Value |
Specify the value of the sensor details you have selected.
For example, if you select IP Address, then enter the IPv4 address of the host for which you want to retrieve process connections information from the VMware Carbon Black EDR server |
| Process Details |
Options based on which you want to specify the process for which you want to retrieve process connection information from the VMware Carbon Black EDR server.
You can choose from the following options:
- Process Name: Name of the process for which you want to retrieve process connection information from the VMware Carbon Black EDR server.
- Process ID: ID of the process for which you want to retrieve process connection information from the VMware Carbon Black EDR server.
|
| Value |
Specify the value of the process details you have selected.
For example, if you select Process Name, then enter the name of the process for which you want to get network connections from the VMware Carbon Black EDR server. |
Output
The output contains the following populated JSON schema:
{
"message": "",
"hostname": "",
"connections": [
{
"domain": "",
"pid": "",
"port": "",
"hostname": "",
"process_name": "",
"direction": "",
"protocol": "",
"ip_addr": "",
"event_time": "",
"carbonblack_process_id": ""
}
]
}
operation: Terminate Process
Input parameters
| Parameter |
Description |
| Sensor Details |
Options based on which you want to specify the endpoint on which you want to terminate the process on the VMware Carbon Black EDR server.
You can choose from the following options:
- Hostname: Name of the host for which you want to terminate the process on the VMware Carbon Black EDR server.
- IP Address: Single IPv4 address of the host for which you want to terminate the process on the VMware Carbon Black EDR server.
|
| Value |
Specify the value of the sensor details you have selected.
For example, if you select IP Address, then enter the IPv4 address of the host for which you want to terminate the process on the VMware Carbon Black EDR server |
| Process Details |
Options based on which you want to specify the which process you want to terminate on the VMware Carbon Black EDR server.
You can choose from the following options:
- Process Name: Name of the process that you want to terminate on the VMware Carbon Black EDR server.
- Process ID: ID of the process that you want to terminate on the VMware Carbon Black EDR server.
|
| Value |
Specify the value of the process details you have selected.
For example, if you select Process Name, then enter the name of the process that you want to terminate on the VMware Carbon Black EDR server. |
Output
The output contains the following populated JSON schema:
{
"terminated_process": []
}
operation: Get File Information
Input parameters
| Parameter |
Description |
| Filehash |
Filehash value (MD5 hash value only) for the file for which you want to retrieve information from the VMware Carbon Black EDR server. |
Note: To get a result for this operation, you must provide inputs only in the form of process and binary MD5 hash values.
Output
The output contains the following populated JSON schema:
{
"internal_name": "",
"copied_mod_len": "",
"server_added_timestamp": "",
"digsig_prog_name": "",
"icon": "",
"endpoint": [
""
],
"is_64bit": "",
"md5": "",
"event_partition_id": [],
"observed_filename": [
""
],
"file_version": "",
"original_filename": "",
"timestamp": "",
"last_seen": "",
"file_desc": "",
"facet_id": "",
"product_version": "",
"digsig_result": "",
"signed": "",
"group": [
""
],
"watchlists": [
{
"wid": "",
"value": ""
}
],
"is_executable_image": "",
"product_name": "",
"os_type": "",
"digsig_subject": "",
"digsig_result_code": "",
"company_name": "",
"host_count": "",
"cb_version": "",
"orig_mod_len": "",
"digsig_issuer": ""
}
operation: Hunt File
Input parameters
| Parameter |
Description |
| File Type |
Type of file you want to hunt for on the VMware Carbon Black EDR server.
You can choose from the following options: Process or Binary. |
| Filehash |
Filehash value (MD5 hash value only) for the file for which you want to retrieve information from the VMware Carbon Black EDR server. |
| Start Record From |
(Optional) Returns the result retrieved from the VMware Carbon Black EDR server from the specified number. The default is set to 0. |
| Number of Records |
(Optional) The number of records that you want this operation to return. The default is set to 10. |
Output
The output contains the following populated JSON schema:
{
"highlights": [
{
"name": "",
"ids": []
}
],
"filtered": {},
"comprehensive_search": "",
"incomplete_results": "",
"all_segments": "",
"terms": [
""
],
"tagged_pids": {},
"facets": {},
"total_results": "",
"elapsed": "",
"results": [
{
"modload_count": "",
"parent_unique_id": "",
"regmod_count": "",
"process_name": "",
"sensor_id": "",
"path": "",
"parent_pid": "",
"last_update": "",
"segment_id": "",
"interface_ip": "",
"filtering_known_dlls": "",
"comms_ip": "",
"filemod_count": "",
"terminated": "",
"unique_id": "",
"processblock_count": "",
"process_pid": "",
"crossproc_count": "",
"start": "",
"parent_name": "",
"emet_count": "",
"process_md5": "",
"parent_id": "",
"parent_md5": "",
"group": "",
"netconn_count": "",
"last_server_update": "",
"os_type": "",
"host_type": "",
"cmdline": "",
"username": "",
"hostname": "",
"emet_config": "",
"id": "",
"childproc_count": ""
}
],
"start": ""
}
operation: Get All Block Hashes
Input parameters
None
Output
The output contains the following populated JSON schema:
{
"username": "",
"audit": [
{
"username": "",
"timestamp": "",
"text": "",
"enabled": "",
"user_id": ""
}
],
"text": "",
"md5hash": "",
"block_count": "",
"user_id": "",
"last_block_sensor_id": "",
"enabled": "",
"last_block_time": "",
"timestamp": "",
"last_block_hostname": ""
}
operation: Block Hash
Input parameters
| Parameter |
Description |
| Filehash |
Filehash value (MD5 hash value only) for the file that you want to block on the VMware Carbon Black EDR server. |
Output
The output contains the following populated JSON schema:
{
"result": ""
}
operation: Unblock Hash
Input parameters
| Parameter |
Description |
| Filehash |
Filehash value (MD5 hash value only) for the file that you want to unblock on the VMware Carbon Black EDR server. |
Output
The output contains the following populated JSON schema:
{
"result": ""
}
operation: Delete File
Input parameters
| Parameter |
Description |
| Input Type |
Options based on which you want to delete a file from the VMware Carbon Black EDR server.
You can choose from the following options:
- Hostname: Name of the host on which you want to delete a file from the VMware Carbon Black EDR server.
- IP Address: Single IPv4 address of the host on which you want to delete a file from the VMware Carbon Black EDR server.
- Sensor ID: ID of the sensor on which you want to delete a file from the VMware Carbon Black EDR server.
|
| Value |
Specify the value of the input type you have selected.
For example, if you select IP Address, then enter the IPv4 address of the host on which you want to delete a file from the VMware Carbon Black EDR server. |
| File Path |
The full path of the file that you want to delete from the VMware Carbon Black EDR server. |
Output
The output contains the following populated JSON schema:
{
"status": ""
}
operation: Run Query
Input parameters
| Parameter |
Description |
| Query Type |
Type of query that you want to run on the VMware Carbon Black EDR server.
You can choose from the following options: Process or Binary. |
| CarbonBlack Query |
Query to be run on the VMware Carbon Black EDR server. |
| Start Record From |
(Optional) Returns the result retrieved from the VMware Carbon Black EDR server from the specified number. The default is set to 0. |
| Number of Records |
(Optional) The number of records that you want this operation to return. The default is set to 10. |
Output
The output contains the following populated JSON schema:
{
"highlights": [
{
"name": "",
"ids": []
}
],
"filtered": {},
"comprehensive_search": "",
"incomplete_results": "",
"all_segments": "",
"terms": [],
"tagged_pids": {},
"facets": {},
"total_results": "",
"elapsed": "",
"results": [
{
"modload_count": "",
"regmod_count": "",
"parent_pid": "",
"process_name": "",
"path": "",
"hostname": "",
"parent_unique_id": "",
"process_pid": "",
"filtering_known_dlls": "",
"interface_ip": "",
"terminated": "",
"unique_id": "",
"processblock_count": "",
"crossproc_count": "",
"segment_id": "",
"start": "",
"sensor_id": "",
"filemod_count": "",
"emet_count": "",
"process_md5": "",
"cmdline": "",
"parent_md5": "",
"group": "",
"netconn_count": "",
"os_type": "",
"last_server_update": "",
"parent_name": "",
"host_type": "",
"parent_id": "",
"username": "",
"last_update": "",
"emet_config": "",
"id": "",
"comms_ip": "",
"childproc_count": ""
}
],
"start": ""
}
operation: Search Alerts
Input parameters
| Parameter |
Description |
| CarbonBlack Query |
Custom search query to retrieve alerts from the VMware Carbon Black EDR server. |
| Status |
Status of the alert that you are searching for on the VMware Carbon Black EDR server.
You can select from the following options: All, In Progress, Unresolved, Resolved, and False Positive. |
| Sort By |
Sort the results retrieved from the VMware Carbon Black EDR server based on this option.
You can choose from the following options: Severity, Most Recent, Least Recent, Alert Name Ascending, or Alert Name Descending. |
| Start Record From |
(Optional) Returns the result retrieved from the VMware Carbon Black EDR server from the specified number. The default is set to 0. |
| Number of Records |
(Optional) The number of records that you want this operation to return. The default is set to 10. |
Output
The output contains the following populated JSON schema:
{
"highlights": [],
"filtered": {},
"total_results": "",
"start": "",
"comprehensive_search": "",
"incomplete_results": "",
"elapsed": "",
"results": [
{
"report_score": "",
"modload_count": "",
"regmod_count": "",
"hostname": "",
"md5": "",
"process_path": "",
"alert_severity": "",
"ioc_type": "",
"comms_ip": "",
"unique_id": "",
"process_name": "",
"status": "",
"crossproc_count": "",
"alert_type": "",
"process_id": "",
"sensor_id": "",
"watchlist_name": "",
"filemod_count": "",
"watchlist_id": "",
"_version_": "",
"created_time": "",
"observed_hosts": {
"processCount": "",
"hostnames": [
{
"name": "",
"value": ""
}
],
"numFound": "",
"numDocs": "",
"processTotal": "",
"hostCount": "",
"accurateHostCount": "",
"globalCount": ""
},
"feed_name": "",
"group": "",
"username": "",
"segment_id": "",
"interface_ip": "",
"netconn_count": "",
"os_type": "",
"ioc_attr": "",
"sensor_criticality": "",
"feed_rating": "",
"feed_id": "",
"ioc_confidence": "",
"childproc_count": "",
"process_unique_id": "",
"total_hosts": ""
}
],
"all_segments": "",
"facets": {},
"terms": [
""
]
}
operation: Update Alert
Input parameters
| Parameter |
Description |
| Unique ID |
Unique ID of the alert whose status you want to update on the VMware Carbon Black EDR server. |
| Status |
Status to which you want the specified alert to be updated on the VMware Carbon Black EDR server.
You can choose from the following options: Resolved, In Progress, False Positive, or Unresolved. |
Output
The output contains the following populated JSON schema:
{
"result": ""
}
operation: Bulk Update Alerts
Input parameters
| Parameter |
Description |
| Alert IDs |
Comma-separated list of unique IDs of alerts whose status you want to update on the VMware Carbon Black EDR server. |
| Status |
Status to which you want the specified alerts to be updated on the VMware Carbon Black EDR server.
You can choose from the following options: Resolved, In Progress, False Positive, or Unresolved. |
Output
The output contains the following populated JSON schema:
{
"result": ""
}
operation: Get Watchlist
Input parameters
| Parameter |
Description |
| Watchlist ID |
Unique ID of the watchlist whose details you want to retrieve from the VMware Carbon Black EDR server.
Note: If you do not specify any watchlist ID, then this operation will retrieve a list of all available watchlists from the VMware Carbon Black EDR server. |
Output
The output contains the following populated JSON schema:
{
"last_hit_count": "",
"date_added": "",
"last_hit": "",
"index_type": "",
"total_tags": "",
"description": "",
"total_hits": "",
"name": "",
"readonly": "",
"group_id": "",
"enabled": "",
"id": "",
"search_timestamp": "",
"search_query": ""
}
Included playbooks
The Sample -VMware Carbon Black EDR - 2.0.2 playbook collection comes bundled with the VMware Carbon Black EDR connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the VMware Carbon Black EDR connector.
- Block Hash
- Bulk Update Alerts
- Delete File
- Get All Block Hashes
- Get All Processes
- Get File Information
- Get Process Connections
- Get Sensor(s) Information
- Get Watchlist
- Hunt File
- Isolate Sensor
- Remove Isolation
- Run Query
- Search Alerts
- Terminate Process
- Unblock Hash
- Update Alert
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.
