Skip to main content

Cyware Orchestrate

VMware Carbon Black Cloud 1.0.0

App Vendor: VMware

App Category: Endpoint Detection and Response

App Version in Orchestrate: 1.0.0

API version: V6

Default Port: 443

About App

The VMware Carbon Black Cloud app in the Orchestrate application allows security teams to integrate with VMware Carbon Black Cloud enterprise application (formerly the Predictive Security Cloud) to secure your endpoints using a single, lightweight agent and an easy-to-use console.

The VMware Carbon Black Cloud app in the Orchestrate application can perform the below listed actions:

Action Name

Description

Execute Device Action

This action can be used to create and execute an action on a device.

Search Devices

This action can be used to search for devices.

Search Alerts

This action can be used to search for Alerts.

Get List of Alert facet

This action can be used to get the list of facet from an Alert.

Get Details of an Alert

This action can be used to get details of an Alert.

Get Details of Device

This action can be used to get details of a specific device.

Prerequisites

All the actions configured in the VMware Carbon Black Cloud app relate to private APIs. VMware Carbon Black Cloud Enterprise subscription is required to access private APIs.

Configuration parameters

The following configuration parameters are required for the VMware Carbon Black Cloud app to communicate with VMware Carbon Black Cloud enterprise application. The parameters can be configured by creating instances in the app.

Parameter

Description

Field Type

Required / Optional

Comments

Cloud Domain

Enter the cloud domain. For example, "defense.tld"

Text

Required

API ID

Enter the API ID for authorization

Password

Required

Role-Based Access Control (RBAC) are specific permission levels assigned to custom API keys to ease access to APIs.

Minimum RBAC permissions required:

  • org.alerts (READ)

  • device (READ, EXECUTE, UPDATE, DELETE)

  • org (READ)

API Secret Key

Enter the API Secret Key for authorization

Password

Required

Role-Based Access Control (RBAC) are specific permission levels assigned to custom API keys to ease access to APIs.

Minimum RBAC permissions required:

  • org.alerts (READ)

  • device(READ, EXECUTE, UPDATE, DELETE)

  • org(READ)

Org Key

Enter the Org Key. For example, “7DESJ9GN

Text

Required

Action: Execute Device Action

This action can be used to create and execute an action on devices.

Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Device ID

Enter the device ID. For example, “$LIST[3419258]”

Any

Required

Action Type

Enter the action type to execute on selected devices.

Text

Required

Allowed values:

  • BACKGROUND_SCAN

  • BYPASS

  • UNINSTALL_SENSOR

  • DELETE_SENSOR

  • QUARANTINE

  • UPDATE_POLICY

  • UPDATE_SENSOR_VERSION

Additional Parameters

Enter additional parameters in the form of key:value pairs.

Key:Value

Required

Additional parameters:

  • search= Device actions will be performed on the result set of this search

  • options.policy_id= Devices will be updated to this policy ID. This is required if action_type is set to “UPDATE_POLICY”

  • options.sensor_version= Devices will be updated to this sensor version. This is required if action_type is set to “UPDATE_SENSOR_VERSION”

  • options.toggle= Determines whether to toggle action. Allowed values are “ON” and “OFF”. This is required if action_type is set to “QUARANTINE”, “BYPASS”, “BACKGROUND_SCAN”

Example Request
[
    {
        “device_id”: ”$LIST[3419258]”,
        “action_type”: “QUARANTINE”,
        "extra_params": 
          {
              “search_query”: “”,
              “criteria”: “status”,
              “start”: “1”,
              “sort.order”: “ASC”,
              “sort.field”: “name”
          }
    }
]
Action: Search Devices

This action can be used to search for devices.

Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Search Query

Enter the query for searching devices.

Text

Optional

Additional Parameters

Enter additional parameters in the form of key:value pairs. By default, the value is set at “start” = 0, “rows” = 10

Key:Value

Optional

Additional parameters:

  • criteria = Map of criteria to filter results. Allowed values are “status”, “os”, “last_contact_time”, “ad_group_id”, “policy_id, id”, “target_priority”.

  • rows = For pagination, the maximum number of rows to return.

  • start = For pagination, begin returning results, starting with this row.

  • sort.field = Sorting preference for sorting fields. Allowed values are “target_priority”, “policy_name”, “name”, “last_contact_time”, “av_pack_version”.

  • sort.order = Sorting order for the field. Allowed values are “ASC”, “DESC”

  • exclusions = A list of sensor versions to exclude from the request results

Example Request
[
    {
        "extra_params": 
          {
              “search_query”: “”,
              “criteria”: “status”,
              “start”: “1”,
              “sort.order”: “ASC”,
              “sort.field”: “name”
          }
    }
]
Action: Search Alerts

This action can be used to search for Alerts.

Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Search Query

Enter the query for searching devices.

Text

Optional

Extra Parameters

Enter additional parameters in the form of key:value pairs. By default, the value is set at “start” = 0, “rows” = 10.

Key:Value

Required

Additional parameters:

  • criteria = Map of criteria to filter results. Allowed values are “target_value”, “not_blocked_threat_category”, “Device_os_version”, “policy_id”, “minimum_severity”, “legacy_alert_id”, “tag”, “id”, “run_state”, “threat_cause_vector”, “device_username”, “threat_id”, “device_id”, “device_os”, “create_time”, “kill_chain_status”, “group_results”, “process_sha256”, “policy_name”, “reputation”, “type”, “category”, “workflow”, “reason_code”, “device_name”, “process_name”, “blocked_threat_category”, “device_location”, “sensor_action”, “policy_applied”.

  • rows = For pagination, the maximum number of rows to return.

  • start = For pagination, begin returning results, starting with this row.

  • sort.field = Sorting preference for sorting fields. Allowed values are “first_event_time”, “last_event_time”, “severity”, “target_value”, =

  • sort.order = Sorting order preference for the field. Allowed values are “ASC”, “DESC”

Example Request
[
    {
        "extra_params": 
          {
              “search_query”: “”,
              “criteria”: “id”,
              “start”: “1”,
              “sort.order”: “ASC”,
              “sort.field”: “severity”
          }
    }
]
Action: Get List of Alert facet

This action can be used to get the list of facet from an Alert.

Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Search Query

Enter the query for searching devices.

Text

Optional

Extra Parameters

Enter additional parameters in the form of key:value pairs. By default, the value is set at “start” = 0, “rows” = 10.

Additional parameters:

  • Criteria = Map of criteria to filter results.

    Allowed values: “threat_id”, “target_value”, “device_id”, “device_os_versions”, “policy_id”, “device_os”, “minimum_severity”, “create_time”, “legacy_alert_id”, “group_results”, “process_sha256”, “policy_name”, “reputation”, “type”, “id”, “category”, “device_username”, “device_name”, “tag”, “workflow”, “process_name”

Example Request
[
    {
        "extra_params": 
          {
              “criteria”: “threat_id”
          }
    }
]
Action: Get Details of an Alert

This action can be used to get details of an Alert.

Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Alert ID

Enter the alert ID. For example, “225219783948647d55b11e9962bf3b07592c207”

Text

Required

Example Request
[
    {
        "alert_id": "3419258"
    }
]
Action: Get Details of Device

This action can be used to get details of a specific device.

Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Device ID

Enter the Device ID. For example, “$LIST[3419258]”

Text

Required

Example Request
[
    {
        "device_id": "3419258"
    }
]