Carbon Black Cloud V2

LAST UPDATED: 03/15/2024

Overview

VMware Carbon Black Cloud provides solutions such as endpoint detection and response (EDR), advanced threat hunting, and vulnerability management. D3 SOAR is providing REST operations to function with VMware Carbon Black Cloud. This integration is the D3's newly designed 2nd Version of the Carbon Black Cloud.

D3 SOAR is providing REST operations to function with Carbon Black Cloud V2.

Carbon Black Cloud V2 is available for use in:

D3 SOAR	V12.7.241+
Category	SIEM & XDR
Deployment Options	Option II, Option IV

Known Limitations

For a detailed breakdown of the specific rate limits, including the number of requests allowed within a given time frame and the response codes you might encounter when a limit is exceeded, please refer to VMware's official documentation.

Connection

To connect to Carbon Black Cloud V2 from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Default
Server URL	The server URL used to access VMware Carbon Black Cloud.	https://*****.net
Identity Manager	The identity management solution you use to manage identity and authorization. In order to determine your identity manager, please refer to https://developer.carbonblack.com/reference/carbon-black-cloud/authentication/#determine-the-identity-manager. If not specified, the default identity manager is Carbon Black Cloud(CBC).	Carbon Black Cloud(CBC)
Carbon Black Cloud(CBC)
API ID	The API ID to authenticate the API connection for Carbon Black Cloud(CBC) identity manager. Please refer to Step 1C: Generate API ID and API Secret Key for how to create API Key in Carbon Black Cloud(CBC).	*****
API Secret	The API Secret to authenticate the API connection for Carbon Black Cloud(CBC) identity manager.	ABCD********6789
Organization Key	Organization Key. Organization Key can be obtained in your product console under Settings > API Access > API Keys.	7D****GN
VMware Cloud Services Platform(CSP)
APP ID	The APP ID to authenticate the API connection for VMware Cloud Services Platform(CSP). Please refer to OAuth Access Control - Carbon Black Developer Network about how to create an OAuth APP in VMware Cloud Services Platform(CSP).	K3bp****M7u4
APP Secret	The APP Secret to authenticate the API connection for VMware Cloud Services Platform(CSP).	ABCD********6789
Organization Key	Organization Key. Organization Key can be obtained in your product console under Settings > API Access > API Keys.	7D****GN

Permission Requirements

Each endpoint in the Carbon Black Cloud V2 API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command	CBC		CSP
Command	Permission (.notation name)	Operation(s)	Permission (.notation name)
Block Hashes	org.reputations	CREATE + READ	_API.Applications:org.Reputations.CREATE
Disable Bypass	device.bypass	EXECUTE	_API.Device:device.Bypass.EXECUTE
Download Files	ubs.org.file	Read	_API.Unified.Binary.Store:ubs.Org.File:READ
Enable Bypass	device.bypass	EXECUTE	_API.Device:device.Bypass.EXECUTE
Fetch Event (Fetching Observation Event Type = Observation row1 Fetching Alerts Event Type = Alert row2)	org.search.events	CREATE + READ	_API.Search:org.Events.READ, _API.Search:org.Events.CREATE
	org.alerts	READ	_API.Alerts:org.Alerts:READ
Quarantine Devices	device.quarantine	EXECUTE	_API.Device:device.Quarantine.EXECUTE
Unblock Hashes	org.reputations	READ + DELETE	_API.Applications:org.Reputations:READ, _API.Applications:org.Reputations:DELETE
Unquarantine Devices	device.quarantine	EXECUTE	_API.Device:device.Quarantine.EXECUTE
Unwhitelist Hashes	org.reputations	READ + DELETE	_API.Applications:org.Reputations:READ _API.Applications:org.Reputations:DELETE
Update Device Policy	device.policy	UPDATE	_API.Device:device.Policy.UPDATE
Whitelist Hashes	org.reputations	CREATE	_API.Applications:org.Reputations:CREATE
Test Connection	Any, but at least assign one permission

Configuring Carbon Black Cloud V2 to Work with D3 SOAR

CBC: API

Create Access Levels

To access the data in your Carbon Black Cloud integrations through APIs, you must determine the appropriate access level for your API. Refer to VMware's documentation step-by-step instructions.

Applying an Access Level to an API Key

Apply the custom access level to an API key. Refer to VMware's documentation step-by-step instructions. Copy and save the API key after configuration, it will be required to build the integration connection in D3 SOAR.

After completing your setup, you can find the Organization Key on the API Access page. The Token (API Secret Key) and App ID are available when you create the key. You will need this information when building a connector in D3 SOAR.

CSP: APP

Refer to OAuth Access Control - Carbon Black Developer Network for more information about configuring an OAuth app in CSP.

Configuring D3 SOAR to Work with Carbon Black Cloud V2

Log in to D3 SOAR.
Find the Carbon Black Cloud V2 integration.

a. Navigate to Configuration on the top header menu.

b. Click on the Integration icon on the left sidebar.

c. Type Carbon Black Cloud V2 in the search box to find the integration, then click it to select it.

d. Click + Connection, on the right side of the Connections section. A new connection window will appear.

Configure the following fields to create a connection to Carbon Black Cloud V2.

a. Connection Name: The desired name for the connection.

b. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.

c. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.

d. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.

e. Description (Optional): Add your desired description for the connection.

f. Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.

g. Configure User Permissions: Defines which users have access to the connection.

h. Active: Check the tick box to ensure the connection is available for use.

i. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.

Identity Manager: Carbon Black Cloud (CBC)

1. Input the server URL used to access VMware Carbon Black Cloud.

2. Select Carbon Black Cloud (CBC).

3. Input the API ID.

4. Input the API Secret.

5. Input the Organization Key.

Identity Manager: VMware Cloud Services Platform (CSP)

1. Input the server URL used to access VMware Carbon Black Cloud.

2. Select VMware Cloud Services Platform (CSP).

3. Input the API ID.

4. Input the API Secret.

5. Input the Organization Key.

j. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
k. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.

To set up a connection health check, check the Connection Health Check tick box. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.

Test the connection.

a. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.

b. Click OK to close the alert window.

c. Click + Add to create and add the configured connection.

Commands

Carbon Black Cloud V2 includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Carbon Black Cloud V2 API, please refer to the following API references:

Alert API: Alerts API - Carbon Black Developer Network
UBS File API: Unified Binary Store REST API Reference - Carbon Black Developer Network
EnrichedEvent API migration to Observation API: Enriched Events API Migration

READER NOTE

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Carbon Black Cloud V2 to Work with D3 SOAR for details.

Note for Time-related parameters

The input format of time-related parameters may vary based on your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:

Navigate to Configuration Application Settings. Select Date/Time Format.
Choose your desired date and time format.

After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.

Block Hashes

Blocks specified applications by adding their SHA256 hashes to the Reputation Banned list.

Input

Input Parameter	Required/Optional	Description	Example
SHA256 Hashes	Required	The SHA256 hashes of the applications to block.	[ "*****" ]
File Names	Optional	The application names associated with the given SHA256 hashes. Note: Ensure to match each file name with its corresponding SHA256 hash value by placing them at the same index in their respective lists. For example, if the SHA256 hash list is ["SHA256Hash-1", "SHA256Hash-2"], then the file name list should align as ["FileName-1", "FileName-2"]. To omit a file name, insert an empty string ("") at the relevant position in the list; for example, with a hash list ["SHA256Hash-1", "SHA256Hash-2", "SHA256Hash-3"], the corresponding file name list might be ["FileName-1", "", "FileName-3"]. If you choose not to associate any file names with the SHA256 hashes, simply leave the parameter empty.	[ "*****.exe" ]
Descriptions	Optional	The descriptions for the SHA256 hashes to be blocked. Note: Ensure to match each description with its corresponding SHA256 hash value by placing them at the same index in their respective lists. For example, if the SHA256 hash list is ["SHA256Hash-1", "SHA256Hash-2"], then the description should align as ["Description-1", "Description-2"]. If you choose not to associate any descriptions with the SHA256 hashes, simply leave the parameter empty.	[ "An override for a sha256 hash 1031A" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "results": [
        {
            "id": "*****",
            "created_by": "*****",
            "create_time": "2023-10-31T17:07:44.592Z",
            "override_list": "BLACK_LIST",
            "override_type": "SHA256",
            "description": "An override for a sha256 hash 1031A",
            "source": "APP",
            "source_ref": null,
            "sha256_hash": "*****",
            "filename": "*****.exe"
        }
    ]
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "OverrideIDs": [
      "*****"
    ],
    "SHA256Hashes": [
      "*****"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

results

{'id': '*****', 'created_by': '*****', 'create_time': '2023-10-31T17:07:44.592Z', 'override_list': 'BLACK_LIST', 'override_type': 'SHA256', 'description': 'An override for a sha256 hash 1031A', 'source': 'APP', 'source_ref': None, 'sha256_hash': '*****', 'filename': '*****.exe'}

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Block Hashes failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Carbon Black Cloud V2 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Validation failed for argument [1].

Error Sample Data

Block Hashes failed.

Status Code: 400.

Message: Validation failed for argument [1].

Disable Bypass

Disables bypass on the specified devices.

READER NOTE

To locate device IDs in Carbon Black Cloud, go to the sidebar and select Inventory, then Endpoints. Select an endpoint from the list.

The device ID can be found under the INVESTIGATE section.

Input

Input Parameter	Required/Optional	Description	Example
Device IDs	Required	The IDs of the device to disable bypass.	[ ***** ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "device_id": [
        *****
    ],
    "Message": "Disable Bypass action is created"
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

device_id	*****
Message	Disable Bypass action is created

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Disable Bypass failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Carbon Black Cloud V2 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: NOT_FOUND device_id(s) : [xxx].

Error Sample Data

Disable Bypass failed.

Status Code: 404.

Message: NOT_FOUND device_id(s) : [xxx].

Download Files

Downloads files by their SHA256 hash values. Currently, this feature is compatible with the Windows CBC sensor and supports the Unified Binary Store (UBS). As such, all downloadable files in UBS are Windows Portable Executable (PE) files.

READER NOTE

The parameter SHA-256s is required to run this command.

Run the Fetch Event command to obtain SHA-256 hashes. SHA-256 hashes can be found in the returned raw data, at the path $.results[*].process_sha256. Note that this SHA value is visible only when the Event Type is set to "Alert". Additionally, SHA-256 hashes from external sources are not usable. The hashes must be obtained using the Fetch Event command for the purpose of downloading files.

Input

Input Parameter	Required/Optional	Description	Example
SHA-256s	Required	The SHA256 hash values of the files to download. SHA256 hash values can be obtained using the Fetch Event command.	[ "*****" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "results": [
        {
            "id": "*****",
            "created_by": "*****",
            "create_time": "2023-10-31T17:07:44.592Z",
            "override_list": "BLACK_LIST",
            "override_type": "SHA256",
            "description": "An override for a sha256 hash 1031A",
            "source": "APP",
            "source_ref": null,
            "sha256_hash": "*****",
            "filename": "*****.exe"
        }
    ]
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "FileNames ": [
      "*****"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

found	{'sha256': '***', 'fileId': '570', 'fileName': '*.zip', 'url': 'https://.**.com/*'}
not_found	[]
error	[]

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Download Files failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Carbon Black Cloud V2 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid sha256s: xxx.

Error Sample Data

Download Files failed.

Status Code: 400.

Message: Invalid sha256s: xxx.

Enable Bypass

Enable bypass on the specified devices.

READER NOTE

To locate device IDs in Carbon Black Cloud, go to the sidebar and select Inventory, then Endpoints. Select an endpoint from the list.

The device ID can be found under the INVESTIGATE section.

Input

Input Parameter	Required/Optional	Description	Example
Device IDs	Required	The IDs of the devices to enable bypass.	[ ***** ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "device_id": [
        *****
    ],
    "Message": "Enable Bypass action is created"
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

device_id	*****
Message	Enable Bypass action is created

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Enable Bypass failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Carbon Black Cloud V2 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: NOT_FOUND device_id(s) : [xxx].

Error Sample Data

Enable Bypass failed.

Status Code: 404.

Message: NOT_FOUND device_id(s) : [xxx].

Fetch Event

Returns event(s) from the Carbon Black Cloud platform based on specified criteria. You can select to fetch alerts or observations.

READER NOTE

If no input parameters are defined, the command retrieves alerts from the past month, up to a maximum of 500.
The Start Time and End Time parameters you specify will organize the results based on two different timestamps: "backend_update_timestamp" and "user_update_timestamp" for Alerts, and "backend_timestamp" for Observations.
If the command doesn't find any matching filters, it will still run successfully but will return no results.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Optional	The start time of the range to fetch events in UTC time. Note: This parameter is relevant for both "Alert" and "Observation" event types. For the "Alert" event type, the relevant time fields are "backend_update_timestamp" and "user_update_timestamp." For the "Observation" event type, the applicable time field is "backend_timestamp. If a start time is not explicitly stated, it defaults to 30 days before the specified end time.	2023-04-01 00:00
End Time	Optional	The end time of the range to fetch events in UTC time. Note: This parameter is relevant for both "Alert" and "Observation" event types. For the "Alert" event type, the relevant time fields are "backend_update_timestamp" and "user_update_timestamp." For the "Observation" event type, the applicable time field is "backend_timestamp. If not specified, the default end time is the current time.	2023-04-15 00:00
Event Type	Optional	The type of event (i.e. Alert or Observation) to retrieve. The default value will be Alert if no event type is specified.	Alert
Number of Event(s) Fetched	Optional	The maximum number of events to retrieve, with a valid range from 1 to 10,000. For results exceeding 10,000, use additional filters to narrowresult down the data. If this parameter is not defined, the default value is set to 500. This parameter is applicable to both "Alert" and "Observation" event types.	10
Query	Optional	The Lucene format query to filter results. You have the option to use either "Query", "Criteria", or both. If both are used, only results that meet both conditions will be shown. For filtering Alert event types, it's advisable to consult the Search Fields - Alerts - Carbon Black Developer Network section in Carbon Black Cloud's documentation. For instance, a search might look like this: device_username:"*@*." AND process_name:windows_update_status.ps1. For Observation event types, refer to Search Fields - Investigate - Carbon Black Developer Network. An example of a query for this could be: process_name:svchost.exe AND device_name:vinventa-cb1**.	device_username:"***@*." AND process_name:windows_update_status.ps1
Criteria	Optional	The JSON object containing the required values in the returned search results. You must specify either "Query" or "Criteria'"', or both. When both are used, results matching both parameters are returned. For "Alert" event types, refer to Search Fields - Alerts - Carbon Black Developer Network from Carbon Black Cloud's documentation. For "Observation" event types, refer to Search Fields - Investigate - Carbon Black Developer Network.	{ "minimum_severity": 2, "device_os": [ "WINDOWS" ] }
Tolerance Scope	Optional	The tolerance scope (in minutes) for the query to fetch events between the specified start and end time to avoid event loss or fetch failure. The events will be fetched between {Start Time - Tolerance Scope, End Time}. The default value is 0.	0
Get Alert Observations	Optional	The Fetch Event command ingests alert observations. The default value of this field is False. This parameter only applies to the Alert event type.	True

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

eventType: Alert
{
    "results": [
        {
            "eventType": "alert",
            "org_key": "*****",
            "alert_url": "defense.conferdeploy.net/alerts?s[c][query_string]=id:d9fbbb83-e216-420f-f555-665a360187f7&orgKey=7DESJ9GN",
            "id": "******",
            "type": "CB_ANALYTICS",
            "backend_timestamp": "2023-10-19T02:44:27.226Z",
            "user_update_timestamp": null,
            "backend_update_timestamp": "2023-10-19T02:44:27.226Z",
            "detection_timestamp": "2023-10-19T02:44:02.439Z",
            "first_event_timestamp": "2023-10-19T02:43:58.550Z",
            "last_event_timestamp": "2023-10-19T02:43:58.550Z",
            "severity": 2,
            "reason": "The application windows_update_status.ps1 invoked another application (powershell.exe). A Deny Policy Action was applied.",
            "reason_code": "T_POL_TERM_CHILD :  (powershell.exe)",
            "threat_id": "*****",
            "primary_event_id": "*****",
            "policy_applied": "APPLIED",
            "run_state": "RAN",
            "sensor_action": "TERMINATE",
            "workflow": {
                "change_timestamp": "2023-10-19T02:44:27.226Z",
                "changed_by_type": "SYSTEM",
                "changed_by": "*****",
                "closure_reason": "NO_REASON",
                "status": "OPEN"
            },
            "determination": {
                "change_timestamp": "2023-10-19T02:44:27.226Z",
                "value": "NONE",
                "changed_by_type": "SYSTEM",
                "changed_by": "******"
            },
            "tags": null,
            "alert_notes_present": false,
            "threat_notes_present": false,
            "asset_id": null,
            "is_updated": false,
            "device_id": ***,
            "device_name": "CORP\\*****-****",
            "device_uem_id": "",
            "device_target_value": "LOW",
            "device_policy": "Tines-Policy",
            "device_policy_id": *****,
            "device_os": "WINDOWS",
            "device_os_version": "Windows Server 2019 x64",
            "device_username": "test@example.io",
            "device_location": "OFFSITE",
            "device_external_ip": "5.2.3.4",
            "device_internal_ip": "1.1.1.1",
            "mdr_alert": false,
            "mdr_alert_notes_present": false,
            "mdr_threat_notes_present": false,
            "ttps": [
                "*****",
                "*****",
                "*****"
            ],
            "attack_tactic": "*****",
            "process_guid": "7*****",
            "process_pid": *****,
            "process_name": "c:\\program files\\******",
            "process_sha256": "******",
            "process_md5": "*****",
            "process_effective_reputation": "ADAPTIVE_WHITE_LIST",
            "process_reputation": "NOT_LISTED",
            "process_cmdline": "\"powershell.exe\" -NonInteractive -ExecutionPolicy AllSigned -File \"C:\\Program files\\Amazon\\SkyLight\\scripts\\windows_update_status.ps1\" -scriptId windows_update_status.ps1 CheckStatus",
            "process_username": "NT *****\\******",
            "process_issuer": [],
            "process_publisher": [],
            "parent_guid": "******",
            "parent_pid": *****,
            "parent_name": "c:\\program files\\******",
            "parent_sha256": "******",
            "parent_md5": "",
            "parent_effective_reputation": "LOCAL_WHITE",
            "parent_reputation": "NOT_LISTED",
            "parent_cmdline": "",
            "parent_username": "NT *****\\*****",
            "childproc_guid": "******",
            "childproc_name": "c:\\windows\\*****\\windowspowershell\\v1.0\\powershell.exe",
            "childproc_sha256": "*****",
            "childproc_md5": "",
            "childproc_effective_reputation": "TRUSTED_WHITE_LIST",
            "childproc_username": "NT *****\\*****",
            "childproc_cmdline": "\"C:\\Windows\\*****\\WindowsPowerShell\\v1.0\\powershell.exe\" (New-Object -ComObject Microsoft.Update.AutoUpdate).DetectNow() ",
            "blocked_name": "c:\\windows\\*****\\windowspowershell\\v1.0\\powershell.exe",
            "blocked_sha256": "*****",
            "blocked_md5": "",
            "blocked_effective_reputation": "TRUSTED_WHITE_LIST",
            "Observations": [
                {
                    "alert_category": [
                        "THREAT"
                    ],
                    "alert_id": [
                        "*****"
                    ],
                    "backend_timestamp": "2023-10-19T02:44:18.729Z",
                    "blocked_effective_reputation": "TRUSTED_WHITE_LIST",
                    "blocked_hash": [
                        "*****"
                    ],
                    "blocked_name": "c:\\windows\\*****\\windowspowershell\\v1.0\\powershell.exe",
                    "childproc_cmdline": "\"C:\\Windows\\*****\\WindowsPowerShell\\v1.0\\powershell.exe\" (New-Object -ComObject Microsoft.Update.AutoUpdate).DetectNow() ",
                    "childproc_cmdline_length": 124,
                    "childproc_effective_reputation": "TRUSTED_WHITE_LIST",
                    "childproc_effective_reputation_source": "CLOUD",
                    "childproc_guid": "7*****",
                    "childproc_hash": [
                        "*****"
                    ],
                    "childproc_issuer": [
                        "Microsoft Windows Production PCA 2011"
                    ],
                    "childproc_name": "c:\\windows\\*****\\windowspowershell\\v1.0\\powershell.exe",
                    "childproc_pid": *****,
                    "childproc_publisher": [
                        "Microsoft Windows"
                    ],
                    "childproc_publisher_state": [
                        "FILE_SIGNATURE_STATE_VERIFIED",
                        "FILE_SIGNATURE_STATE_SIGNED"
                    ],
                    "childproc_reputation": "TRUSTED_WHITE_LIST",
                    "childproc_username": "NT *****\\SYSTEM",
                    "device_external_ip": "2.2.2.2",
                    "device_group_id": 0,
                    "device_id": *****,
                    "device_installed_by": "test@example.io",
                    "device_internal_ip": "1.1.1.1",
                    "device_location": "OFFSITE",
                    "device_name": "******",
                    "device_os": "WINDOWS",
                    "device_os_version": "Windows Server 2019 x64",
                    "device_policy": "tines-policy",
                    "device_policy_id": *****,
                    "device_target_priority": "LOW",
                    "device_timestamp": "2023-10-19T02:43:58.550Z",
                    "document_guid": "*****",
                    "enriched": true,
                    "enriched_event_type": "CREATE_PROCESS",
                    "event_attack_stage": [
                        "INSTALL_RUN"
                    ],
                    "event_description": "The script \"<share><link hash=\"****\">C:\\program files\\amazon\\skylight\\scripts\\windows_update_status.ps1</link></share>\" invoked the application \"<share><link hash=\"de96a6e69944335375dc1ac238336066889d9ffc7d73628ef4fe1b1b160ab32c\">C:\\windows\\system32\\windowspowershell\\v1.0\\powershell.exe</link></share>\". The operation was <accent>blocked</accent> and the application <accent>terminated by Carbon Black</accent>.",
                    "event_id": "*****",
                    "event_type": "*****",
                    "ingress_time": 1697683451771,
                    "legacy": true,
                    "observation_description": "The application windows_update_status.ps1 invoked another application (powershell.exe). A Deny Policy Action was applied.",
                    "observation_id": "*****:*****",
                    "observation_type": "CB_ANALYTICS",
                    "org_id": "*****",
                    "parent_effective_reputation": "LOCAL_WHITE",
                    "parent_effective_reputation_source": "PRE_EXISTING",
                    "parent_guid": "*****",
                    "parent_hash": [
                        "******"
                    ],
                    "parent_name": "c:\\program files\\amazon\\skylight\\skylightworkspaceconfigservice.exe",
                    "parent_pid": 3096,
                    "parent_reputation": "NOT_LISTED",
                    "parent_username": "NT *****\\SYSTEM",
                    "process_cmdline": [
                        "\"powershell.exe\" -NonInteractive -ExecutionPolicy AllSigned -File \"C:\\Program files\\Amazon\\SkyLight\\scripts\\windows_update_status.ps1\" -scriptId windows_update_status.ps1 CheckStatus"
                    ],
                    "process_cmdline_length": [
                        182
                    ],
                    "process_effective_reputation": "ADAPTIVE_WHITE_LIST",
                    "process_effective_reputation_source": "CLOUD",
                    "process_guid": "*****",
                    "process_hash": [
                        "*****",
                        "*****"
                    ],
                    "process_loaded_script_hash": [
                        "*****"
                    ],
                    "process_loaded_script_name": [
                        "c:\\program files\\*****"
                    ],
                    "process_name": "c:\\program files\\*****",
                    "process_pid": [
                        4044
                    ],
                    "process_reputation": "NOT_LISTED",
                    "process_sha256": "*****",
                    "process_start_time": "2023-10-19T02:43:56.079Z",
                    "process_username": [
                        "NT *****\\*****"
                    ],
                    "sensor_action": [
                        "TERMINATE"
                    ],
                    "ttp": [
                        "*****",
                        "*****",
                        "POLICY_DENY"
                    ]
                }
            ]
        }
    ],
    "num_found": 2,
    "num_available": 2
}
eventType: Observation (details)
{
    "results": [
        {
            "eventType": "observation",
            "backend_timestamp": "2024-02-27T19:04:56.131Z",
            "crossproc_action": "ACTION_API_CALL",
            "crossproc_api": "OpenProcess",
            "crossproc_cmdline": "\"powershell.exe\" -f C:\\*****\\cleanup.ps1",
            "crossproc_cmdline_length": 49,
            "crossproc_effective_reputation": "TRUSTED_WHITE_LIST",
            "crossproc_effective_reputation_source": "CLOUD",
            "crossproc_guid": "*****",
            "crossproc_hash": [
                "*****"
            ],
            "crossproc_name": "c:\\windows\\*****\\windowspowershell\\v1.0\\powershell.exe",
            "crossproc_pid": *****,
            "crossproc_publisher_state": [
                "FILE_SIGNATURE_STATE_NOT_SIGNED"
            ],
            "crossproc_reputation": "TRUSTED_WHITE_LIST",
            "crossproc_target": false,
            "crossproc_username": "NT *****\\*****",
            "device_external_ip": "1.1.1.1",
            "device_group_id": 0,
            "device_id": *****,
            "device_installed_by": "test@example.com",
            "device_internal_ip": "1.1.1.1",
            "device_location": "OFFSITE",
            "device_name": "ukcxc\\*****-01",
            "device_os": "WINDOWS",
            "device_os_version": "Server 2012 R2 x64",
            "device_policy": "default",
            "device_policy_id": *****,
            "device_sensor_version": "3.9.1.2464",
            "device_target_priority": "MEDIUM",
            "device_timestamp": "2024-02-27T19:03:54.914Z",
            "document_guid": "*****",
            "enriched": true,
            "enriched_event_type": "SYSTEM_API_CALL",
            "event_description": "The application \"<share><link hash=\"*****\">c:\\windows\\system32\\conhost.exe</link></share>\" attempted to open the process \"c:\\windows\\system32\\windowspowershell\\v1.0\\powershell.exe\", by calling the function \"OpenProcess\". The operation was successful.",
            "event_id": "*****",
            "event_threat_score": [
                0
            ],
            "event_type": "crossproc",
            "ingress_time": 1709060678423,
            "legacy": true,
            "observation_description": "The application \"<share><link hash=\"*****\">c:\\windows\\system32\\conhost.exe</link></share>\" attempted to open the process \"c:\\windows\\system32\\windowspowershell\\v1.0\\powershell.exe\", by calling the function \"OpenProcess\". The operation was successful.",
            "observation_id": "*****",
            "observation_type": "CONTEXTUAL_ACTIVITY",
            "org_id": "*****",
            "parent_effective_reputation": "TRUSTED_WHITE_LIST",
            "parent_effective_reputation_source": "CLOUD",
            "parent_guid": "*****",
            "parent_hash": [
                "*****"
            ],
            "parent_name": "c:\\windows\\*****\\windowspowershell\\v1.0\\powershell.exe",
            "parent_pid": 3912,
            "parent_publisher_state": [
                "FILE_SIGNATURE_STATE_NOT_SIGNED"
            ],
            "parent_reputation": "TRUSTED_WHITE_LIST",
            "parent_username": "NT *****\\SYSTEM",
            "process_cmdline": [
                "\\??\\C:\\Windows\\system32\\conhost.exe 0xffffffff"
            ],
            "process_cmdline_length": [
                46
            ],
            "process_effective_reputation": "TRUSTED_WHITE_LIST",
            "process_effective_reputation_source": "CLOUD",
            "process_guid": "*****",
            "process_hash": [
                "*****",
                "*****"
            ],
            "process_issuer": [
                "Microsoft Windows Production PCA 2011"
            ],
            "process_name": "c:\\windows\\system32\\conhost.exe",
            "process_pid": [
                4648
            ],
            "process_publisher": [
                "Microsoft Windows"
            ],
            "process_publisher_state": [
                "FILE_SIGNATURE_STATE_VERIFIED",
                "FILE_SIGNATURE_STATE_SIGNED"
            ],
            "process_reputation": "TRUSTED_WHITE_LIST",
            "process_sha256": "*****",
            "process_start_time": "2024-02-27T19:03:50.561Z",
            "process_user_id": "S-*****",
            "process_username": [
                "NT *****\\*****"
            ],
            "ttp": [
                "*****",
                "****"
            ]
        }
    ],
    "num_found": 1,
    "num_available": 1,
    "approximate_unaggregated": 1,
    "num_aggregated": 1,
    "contacted": 47,
    "completed": 47,
    "message": ""
}

Return Data

Indicates one of the possible command execution states: Successful, Successful with No Event Data, or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No sample data

Fetch Event Field Mapping

Please note that Fetch Event commands require event field mapping. Field mapping plays a key role in the data normalization process part of the event pipeline. Field mapping converts the original data fields from the different providers to the D3 fields which are standardized by the D3 Model. Please refer to Event and Incident Intake Field Mapping for details.

To customize field mapping, click + Add Field and add the custom field of your choice. You can also remove built-in field mappings by clicking x. Please note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.

As a system integration, the Carbon Black Cloud V2 integration has some pre-configured field mappings for default field mapping.

As a system integration, the ArcSight Enterprise Security Manager integration has some pre-configured field mappings for default field mapping.

Default Event Source
- The Default Event Source is the default set of field mappings that are applied when this fetch event command is executed. For out-of-the-box integrations, you will find a set of field mapping provided by the system. The default event source has a “Main Event JSON Path” (i.e., $.results) that is used to extract a batch of events from the response raw data. Click Edit Event Source to view the “Main Event JSON Path”.
- Main Event JSON Path: $.results
  The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...’]) should be used to separate child elements in JSON arrays.
Event Source for Alerts Event

Configures the field mapping which are specific to the alert-related events. If a source field in the field mapping is not found, the corresponding field mapping will be ignored. As the data of the alert-related events have a character that the value of the eventType field is alert, the alert-related events can be defined by the Search String: {$.eventType}=alert. Click Edit Event Source to view the Search String.

Event Source for Observation Event

Configures the field mapping which are specific to the observation-related events. If a source field in the field mapping is not found, the corresponding field mapping will be ignored. As the data of the alert-related events have a character that the value of the eventType field is observation, the observation-related events can be defined by the Search String: {$.eventType}=observation. Click Edit Event Source to view the Search String.

The pre-configured field mappings are detailed below:

Field Name	Source Field
Default Event Source (Main Event JSON Path: $.results)
Event Source for Alerts Event (Search String:{$.eventType}=alert) The search string format is {jsonpath}=value. If the value of the eventType key is alert in the event object under raw data, then the alert-related events will use the field mapping below.
Event code	.id
Event Type	.type
Start Time	.detection_timestamp
Description	.reason
Severity	.severity
Primary Event ID	.primary_event_id
Threat event ID	.threat_id
Hostname	.device_name
Status	.workflow.status
Sensor Action	.sensor_action
Run State	.run_state
Determination	.determination.value
Tag	.tags
Operating system	.device_os_version
Username	.device_username
Reason Code	.reason_code
Process Name	.process_name
Process Hash SHA256	.process_sha256
Process GUID	.process_guid
Process command line	.process_cmdline
Process ID	.process_pid
Parent process name	.parent_name
Parent Process Hash SHA256	.parent_sha256
Parent process GUID	.parent_guid
Parent process commandline	.parent_cmdline
Parent process ID	.parent_pid
Child Process Name	.childproc_name
Child Process Hash SHA256	.childproc_sha256
Child Process GUID	.childproc_guid
Child Process Commandline	.childproc_cmdline
Blocked Process Name	.blocked_sha256
Blocked Process Reputation	.blocked_effective_reputation
Tactics	.attack_tactic
Techniques	.ttps
Device ID	.device_id
Device Internal IP	.device_internal_ip
Device External IP	.device_external_ip
Device priority	.device_target_value
First Activity Time	.first_event_timestamp
Last Activity Time	.last_event_timestamp
Event Source for Observation Event (Search String: {$.eventType}=observation) The search string format is {jsonpath}=value. If the value of the eventType key is observation in the event object under raw data, then the observation-related events will use the field mapping below.
Unique Event Key	.observation_id
Event Type	.event_type
Start Time	.detection_timestamp
Description	.observation_description
Observation Type	.observation_type
Enriched Event Type	.enriched_event_type
Hostname	.device_name
Process Name	.process_name
Process Hash	.process_hash
Process GUID	.process_guid
Process ID	.process_pid
Parent process GUID	.parent_guid
Parent process ID	.parent_pid
Device ID	.device_id
Device Group ID	.device_group_id
Process Username	.process_username

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Event failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Carbon Black Cloud V2 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Unauthorized. Please check D3Error object in RawData for more details.

Error Sample Data

Fetch Event failed.

Status Code: 401.

Message: Unauthorized. Please check D3Error object in RawData for more details.

Quarantine Devices

Quarantines the specified device(s).

READER NOTE

To locate device IDs in Carbon Black Cloud, go to the sidebar and select Inventory, then Endpoints. Select an endpoint from the list.

The device ID can be found under the INVESTIGATE section.

Input

Input Parameter	Required/Optional	Description	Example
Device IDs	Required	The IDs of the devices to quarantine.	[ ***** ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "device_id": [
        *****
    ],
    "Message": "Quarantine action is created"
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error messageprocess_name:win
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

device_id	*****
Message	Quarantine action is created

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Quarantine Devices failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Carbon Black Cloud V2 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: NOT_FOUND, device_id(s) : [xxx].

Error Sample Data

Quarantine Devices failed.

Status Code: 404.

Message: NOT_FOUND, device_id(s) : [xxx].

Unblock Hashes

Unblocks specified applications by adding their SHA256 hashes to the Reputation Banned list.

READER NOTE

The input SHA256 hashes must be previously blocked in order to proceed with unblocking.

Input

Input Parameter	Required/Optional	Description	Example
SHA256 Hashes	Required	The SHA256 hashes of the applications to unblock.	[ "*****" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "num_found": 1,
    "results": [
        {
            "id": "*****",
            "created_by": "*****",
            "create_time": "2023-11-01T19:47:59.844Z",
            "override_list": "BLACK_LIST",
            "override_type": "SHA256",
            "description": "An override for a sha256 hash 1031A",
            "source": "APP",
            "source_ref": null,
            "sha256_hash": "*****",
            "filename": "*****.exe",
            "status": "removed"
        }
    ]
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No sample data

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Unblock Hashes failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Carbon Black Cloud V2 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: No result data when getting SHA256's OverrideID, one of the SHA256s may not exist, not in banned list or is incorrect.

Error Sample Data

Unblock Hashes failed.

Status Code: 404.

Message: No result data when getting SHA256's OverrideID, one of the SHA256s may not exist, not in banned list or is incorrect.

Unquarantine Devices

Unquarantines the specified device(s).

READER NOTE

To locate device IDs in Carbon Black Cloud, go to the sidebar and select Inventory, then Endpoints. Select an endpoint from the list.

The device ID can be found under the INVESTIGATE section.

Input

Input Parameter	Required/Optional	Description	Example
Device IDs	Required	The IDs of the devices to unquarantine.	[ ***** ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "device_id": [
        *****
    ],
    "Message": "Unquarantine action is created"
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

device_id	*****
Message	Unquarantine action is created

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Unquarantine Devices failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Carbon Black Cloud V2 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The value for parameter (Device IDs) is invalid.

Error Sample Data

Unquarantine Devices failed.

Status Code: 400.

Message: The value for parameter (Device IDs) is invalid.

Unwhitelist Hashes

Removes the specified applications of the given SHA256 hashes from the Reputation Approved List.

READER NOTE

The input SHA256 hashes must be previously whitelisted in order to proceed with unwhitelisting.

Input

Input Parameter	Required/Optional	Description	Example
SHA256 Hashes	Required	The SHA256 hashes of the applications to unwhitelist.	[ "*****" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "num_found": 1,
    "results": [
        {
            "id": "*****",
            "created_by": "*****",
            "create_time": "2023-11-16T20:33:47.654Z",
            "override_list": "WHITE_LIST",
            "override_type": "SHA256",
            "description": "Whitelist hash 1116A",
            "source": "APP",
            "source_ref": null,
            "sha256_hash": "*****",
            "filename": "*****.exe",
            "status": "removed"
        }
    ]
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

num_found	1
results	{'id': '***', 'created_by': '*', 'create_time': '2023-11-16T20:33:47.654Z', 'override_list': 'WHITE_LIST', 'override_type': 'SHA256', 'description': 'Whitelist hash 1116A', 'source': 'APP', 'source_ref': None, 'sha256_hash': '*', 'filename': '***.exe', 'status': 'removed'}

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Unwhitelist Hashes failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Carbon Black Cloud V2 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: No result data when getting SHA256's OverrideID, one of the SHA256s may not exist or is incorrect.

Error Sample Data

Unwhitelist Hashes failed.

Status Code: 400.

Message: No result data when getting SHA256's OverrideID, one of the SHA256s may not exist or is incorrect.

Update Device Policy

Updates device policies by device IDs.

READER NOTE

The Policy ID parameter is required to run this command.
- Run the Fetch Incident command to obtain Policy IDs. Policy IDs can be found in the returned raw data, at the path $.results[*].device_policy_id.
To locate device IDs in Carbon Black Cloud, go to the sidebar and select Inventory, then Endpoints. Select an endpoint from the list.

The device ID can be found under the INVESTIGATE section.

Input

Input Parameter	Required/Optional	Description	Example
Device IDs	Required	The IDs of the devices to update policies.	[ ***** ]
Policy ID	Required	The ID of the policy to update the devices to.	*****

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "device_id": [
        *****
    ],
    "Message": "Update Policy action is created"
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

device_id	*****
Message	Update Policy action is created

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Update Device Policy failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Carbon Black Cloud V2 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Unauthorized. Please check D3Error object in RawData for more details.

Error Sample Data

Update Device Policy failed.

Status Code: 401.

Message: Unauthorized. Please check D3Error object in RawData for more details.

Whitelist Hashes

Adds the specified applications of the given SHA256 hashes from the Reputation Approved List.

READER NOTE

Ensure the number of SHA256 hashes, file names, and descriptions are equal. You can omit file names and descriptions, but if included, their numbers must match the hashes. For example, for two hashes, provide either no file names and descriptions or two of each. A mismatch triggers the: "File Names or Descriptions parameter's length do not match with SHA256 Hashes parameter" error message.

Input

Input Parameter	Required/Optional	Description	Example
SHA256 Hashes	Required	The SHA256 hashes of the applications to whitelist.	[ "*****" ]
File Names	Optional	The application names associated with the given SHA256 hashes. Note: Ensure to match each file name with its corresponding SHA256 hash value by placing them at the same index in their respective lists. For example, if the SHA256 hash list is ["SHA256Hash-1", "SHA256Hash-2"], then the file name list should align as ["FileName-1", "FileName-2"].	[ "*****.exe" ]
Descriptions	Optional	The descriptions for the SHA256 hashes to be blocked. Note: Ensure to match each description with its corresponding SHA256 hash value by placing them at the same index in their respective lists. For example, if the SHA256 hash list is ["SHA256Hash-1", "SHA256Hash-2"], then the description should align as ["Description-1", "Description-2"].	[ "Whitelist hash 1116A" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "results": [
        {
            "id": "*****",
            "created_by": "*****",
            "create_time": "2023-11-16T20:20:21.969Z",
            "override_list": "WHITE_LIST",
            "override_type": "SHA256",
            "description": "Whitelist hash 1116A",
            "source": "APP",
            "source_ref": null,
            "sha256_hash": "*****",
            "filename": "*****.exe"
        }
    ]
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "OverrideIDs": ["*****"],
    "SHA256Hashes": ["*****"]
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

results

{'id': '*****', 'created_by': 'I86YEZ9RA4', 'create_time': '2023-11-16T20:20:21.969Z', 'override_list': 'WHITE_LIST', 'override_type': 'SHA256', 'description': 'Whitelist hash 1116A', 'source': 'APP', 'source_ref': None, 'sha256_hash': '*****', 'filename': '*****.exe'}

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Whitelist Hashes failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Carbon Black Cloud V2 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Validation failed for argument [1].

Error Sample Data

Whitelist Hashes failed.

Status Code: 400.

Message: Validation failed for argument [1].

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

SAMPLE DATA

CODE

Successful

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Carbon Black Cloud V2 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Unauthorized. Please check D3Error object in RawData for more details.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 401.

Message: Unauthorized. Please check D3Error object in RawData for more details.