Fortinet Document Library

Version:


Table of Contents

CarbonBlack Defense

2.0.0
Copy Link

About the connector

CarbonBlack Defense is an industry-leading, cloud-delivered endpoint security solution that combines next-generation antivirus (NGAV) and endpoint detection and response (EDR) capabilities into a lightweight solution that is fast to deploy and easy to manage.

This document provides information about the CarbonBlack Defense connector, which facilitates automated interactions with CarbonBlack Defense using FortiSOAR™ playbooks. Add the CarbonBlack Defense connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving the status of all devices from CarbonBlack Defense and changing the status of an individual device, by its device ID, on CarbonBlack Defense.

Version information

Connector Version: 2.0.0

Authored By: Fortinet

FortiSOAR™ Version Tested on: 4.12.1-253 

Certified: Yes

Release Notes for version 2.0.0

Following enhancements have been made to the CarbonBlack Defense connector in version 2.0.0:

  • Certified the CarbonBlack Defense connector.
  • Added the following new operations and playbooks:
    • Execute Live Commands - File
    • Execute Live Commands - Process
    • Execute Live Commands - Registry
  • Added Connector ID as a configuration parameter.
  • Added support for creating a new policy or updating an existing policy in CarbonBlack Defense using a policy file you have specified.
  • Updated the Get Devices Status, Find Events, and Find Processes operations as follows:
    • Added Number of records and Start Record From as input parameters of these operations.
    • Removed Page Range from the input parameters of these operations.

Installing the connector

All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:

yum install cyops-connector-carbonblack-defense

For the detailed procedure to install a connector, click here.

Prerequisites to configuring the connector

  • You must have the URL of the Carbon Black Defense server to which you will connect and perform automated operations.
  • You must have the API key and Connector ID using which you can access the Carbon Black Defense REST API.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

Configuring the connector 

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™ , on the connectors page, select the CarbonBlack Defense connector and click Configure to configure the following parameters:

Parameter Description
Server URL IP address or Hostname of the Carbon Black Defense server to which you will connect and perform automated operations.
API Key API key that is provided to you by the Carbon Black Defense administrator to access the Carbon Black Defense REST API.
Connector ID Connector ID that is provided to you by the Carbon Black Defense administrator to access the Carbon Black Defense 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™ release 4.10.0 onwards:

Function Description Annotation and Category
Get Devices Status Retrieves the status of all devices or specific devices from CarbonBlack Defense based on the input search criteria you have specified. search_device
Investigation
Get Device Status Retrieves the status and details for a device from CarbonBlack Defense based on the device ID you have specified. search_device
Investigation
Change Device Status Changes the status for a device on CarbonBlack Defense based on the device ID you have specified.
Note: The current revision of the CarbonBlack Defense API only allows one element to be changed with this call, which is the security policy assigned to the device.
update_device
Investigation
Find Events Retrieves all events or specific events from CarbonBlack Defense based on the input search criteria you have specified. search_event
Investigation
Find Event By ID Retrieves the details for an event from CarbonBlack Defense based on the event ID you have specified. search_event
Investigation
Find Processes Retrieves all processes or specific processes from CarbonBlack Defense based on the input search criteria you have specified. search_process
Investigation
Get Alert Details Retrieves details and all metadata, including a list of all the events associated with the specified alert from CarbonBlack Defense based on the alert ID you have specified. get_alert
Investigation
Get Notifications Retrieves information about all the new notifications from CarbonBlack Defense since the last check-in on CarbonBlack Defense. get_notification
Investigation
Create Policy Creates a new policy in CarbonBlack Defense based on the input parameters or policy file you have specified create_policy
Investigation
Get All Policies Retrieves a list of all policies available in the organization from CarbonBlack Defense. search_policy
Investigation
Get Policy By ID Retrieves the details of a policy from CarbonBlack Defense based on the policy ID you have specified. search_policy
Investigation
Update Policy Updates an existing policy with a new policy in CarbonBlack Defense based on the input parameters or policy file you have specified. update_policy
Investigation
Delete Policy Deletes details of an existing policy from CarbonBlack Defense based on the policy ID you have specified. delete_policy
Miscellaneous
Add Rule To Policy Adds a new rule to an existing policy in CarbonBlack Defense based on the policy ID and information about the rule you have specified. update_policy
Investigation
Update Rule To Policy Updates an existing policy with a new rule in an existing policy in CarbonBlack Defense based on the policy ID, rule ID, and information about the rule you have specified. update_policy
Investigation
Delete Rule From Policy Deletes the details of an existing rule from an existing policy on CarbonBlack Defense based on the policy ID and rule ID you have specified. update_policy
Investigation
Execute Live Commands - File Takes action on remote endpoints in real time. These actions include the ability to list directories, and upload, download, and remove files. execute_commands
Investigation
Execute Live Commands - Process Takes action on remote endpoints in real time. These actions include the ability to dump contents of physical memory, list processes, and execute and terminate processes. execute_commands
Investigation
Execute Live Commands - Registry Takes action on remote endpoints in real time. These actions include the ability to create, retrieve, alter and remove registry entries. execute_commands
Investigation

operation: Get Devices Status

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Hostname Hostname of the device whose status you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified hostnames based on a case-insensitive token search.
CarbonBlack Defense separates hostnames into parts or "tokens" defined by hyphens. So, for example, a hostname of WIN-IA9NQ1GN8OI will be parsed into two tokens: WIN and IA9NQ1GN8OI. Searching for hostName=IA9NQ1GN8OI and hostname=win will both match the hostname WIN-IA9NQ1GN8OI.
Hostname Exact Hostname of the device whose status you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified hostnames based on an exact match.
For example, hostName=WIN-IA9NQ1GN8OI will only return devices with the exact hostname WIN-IA9NQ1GN8OI but not a host named win-IA9NQ1GN8OI.
Owner Name Owner Name of the device whose status you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified owner name based on a case-insensitive token search.
Owner Name Exact Owner Name of the device whose status you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified owner name based on an exact match and a case-sensitive token search.
IP Address External or internal IP address of the device whose status you want to retrieve from CarbonBlack Defense.
Start Record From Used for pagination. Specify the first record number that you want to the CarbonBlack Defense API to return for this operation.
Number of Records Used for pagination. Specify the maximum number of records that you want to the CarbonBlack Defense API to return for this operation.

Output

The output contains the following populated JSON schema:

     "totalResults": "", 
     "success": "", 
     "results": [ 
         { 
             "uninstallCode": "", 
             "lastExternalIpAddress": "", 
             "organizationName": "", 
             "scanLastCompleteTime": "", 
             "assignedToName": "", 
             "lastInternalIpAddress": "", 
             "lastShutdownTime": "", 
             "passiveMode": "", 
             "testId": "", 
             "lastResetTime": "", 
             "avProductVersion": "", 
             "avVdfVersion": "", 
             "virtualizationProvider": "", 
             "loginUserName": "", 
             "targetPriorityType": "", 
             "uninstalledTime": "", 
             "sensorStates": [], 
             "policyName": "", 
             "sensorOutOfDate": "", 
             "createTime": "", 
             "email": "", 
             "vdiBaseDevice": "", 
             "deviceMetaDataItemList": "", 
             "rootedBySensor": "", 
             "scanLastActionTime": "", 
             "macAddress": "", 
             "deviceType": "", 
             "organizationId": "", 
             "adGroupId": "", 
             "windowsPlatform": "", 
             "virtualMachine": "", 
             "firstName": "", 
             "lastLocation": "", 
             "rootedBySensorTime": "", 
             "avEngine": "", 
             "linuxKernelVersion": "", 
             "scanStatus": "", 
             "avStatus": [], 
             "avAveVersion": "", 
             "registeredTime": "", 
             "avMaster": "", 
             "policyOverride": false, 
             "lastName": "", 
             "activationCodeExpiryTime": "", 
             "avLastScanTime": "", 
             "originEventHash": "", 
             "rootedByAnalyticsTime": "", 
             "messages": "", 
             "lastContact": "", 
             "deviceId": "", 
             "name": "", 
             "sensorVersion": "", 
             "activationCode": "", 
             "lastReportedTime": "", 
             "lastDevicePolicyChangedTime": "", 
             "encodedActivationCode": "", 
             "assignedToId": "", 
             "deviceOwnerId": "", 
             "avPackVersion": "", 
             "firstVirusActivityTime": "", 
             "quarantined": "", 
             "deviceSessionId": "", 
             "lastDevicePolicyRequestedTime": "", 
             "middleName": "", 
             "policyId": "", 
             "rootedByAnalytics": "", 
             "currentSensorPolicyName": "", 
             "status": "", 
             "avUpdateServers": "", 
             "deregisteredTime": "", 
             "lastPolicyUpdatedTime": "", 
             "osVersion": "", 
             "deviceGuid": "", 
             "lastVirusActivityTime": "" 
         } 
     ], 
     "message": "", 
     "latestTime": "", 
     "elapsed": "" 
}

operation: Get Device Status

Input parameters

Parameter Description
Device ID ID of the device whose details and status you want to retrieve from CarbonBlack Defense.

Output

The output contains the following populated JSON schema:

     "message": "", 
     "deviceInfo": { 
         "uninstallCode": "", 
         "lastPolicyChangedTime": "", 
         "lastExternalIpAddress": "", 
         "organizationName": "", 
         "adGroupId": "", 
         "lastInternalIpAddress": "", 
         "lastShutdownTime": "", 
         "passiveMode": "", 
         "status": "", 
         "lastResetTime": "", 
         "windowsPlatform": "", 
         "virtualizationProvider": "", 
         "lastPolicyRequestedTime": "", 
         "loginUserName": "", 
         "avStatus": [], 
         "organizationId": "", 
         "uninstalledTime": "", 
         "rootedByAnalyticsTime": "", 
         "sensorStates": [], 
         "policyName": "", 
         "sensorOutOfDate": "", 
         "assignedToName": "", 
         "email": "", 
         "rootedByAnalytics": "", 
         "rootedBySensor": "", 
         "macAddress": "", 
         "targetPriorityType": "", 
         "scanLastCompleteTime": "", 
         "activationCode": "", 
         "virtualMachine": "", 
         "name": "", 
         "firstName": "", 
         "lastLocation": "", 
         "rootedBySensorTime": "", 
         "blades": "", 
         "avEngine": "", 
         "linuxKernelVersion": "", 
         "scanStatus": "", 
         "createTime": "", 
         "scanLastActionTime": "", 
         "registeredTime": "", 
         "avMaster": "", 
         "policyOverride": "", 
         "lastName": "", 
         "avLastScanTime": "", 
         "deviceType": "", 
         "messages": "", 
         "lastContact": "", 
         "deviceId": "", 
         "testId": "", 
         "sensorVersion": "", 
         "deviceSessionId": "", 
         "quarantined": "", 
         "apcEnabled": "", 
         "lastReportedTime": "", 
         "assignedToId": "", 
         "deviceOwnerId": "", 
         "avUpdateServers": "", 
         "vdiBaseDevice": "", 
         "middleName": "", 
         "policyId": "", 
         "currentSensorPolicyName": "", 
         "updateVersion": "", 
         "firstVirusActivityTime": "", 
         "osVersion": "", 
         "deviceGuid": "", 
         "lastVirusActivityTime": "" 
     }, 
     "success": "" 
}

operation: Change Device Status

Input parameters

Parameter Description
Device ID ID of the device whose associated security policy you want to change on CarbonBlack Defense.
Update Security Policy Assigned to Device by: Security policy that you want to change on CarbonBlack Defense and which is assigned to the specified device. You can specify the security policy by either specifying the Policy ID or the Policy Name.
If you choose Policy ID, then you must specify the following parameters:
  • Policy ID: ID of the security policy that is assigned to the specified device and which you want to change.
If you choose Policy Name, then you must specify the following parameters:
  • Policy Name: Name of the security policy that is assigned to the specified device and which you want to change.

Output

The output contains the following populated JSON schema:



     "message": "", 
     "deviceInfo": { 
         "organizationName": "", 
         "lastContact": "", 
         "scanLastCompleteTime": "", 
         "lastInternalIpAddress": "", 
         "lastShutdownTime": "", 
         "passiveMode": "", 
         "testId": "", 
         "lastResetTime": "", 
         "policyName": "", 
         "sensorOutOfDate": "", 
         "avStatus": [], 
         "targetPriorityType": "", 
         "status": "", 
         "policyId": "", 
         "rootedByAnalyticsTime": "", 
         "assignedToName": "", 
         "email": "", 
         "rootedByAnalytics": "", 
         "rootedBySensor": "", 
         "assignedToId": "", 
         "organizationId": "", 
         "activationCode": "", 
         "uninstalledTime": "", 
         "firstName": "", 
         "lastLocation": "", 
         "id": "", 
         "rootedBySensorTime": "", 
         "avEngine": "", 
         "linuxKernelVersion": "", 
         "scanStatus": "", 
         "createTime": "", 
         "scanLastActionTime": "", 
         "registeredTime": "", 
         "avMaster": "", 
         "lastName": "", 
         "avLastScanTime": "", 
         "deviceType": "", 
         "messages": "", 
         "lastExternalIpAddress": "", 
         "deviceId": "", 
         "name": "", 
         "sensorVersion": "", 
         "deviceSessionId": "", 
         "lastReportedTime": "", 
         "quarantined": "", 
         "deviceOwnerId": "", 
         "avUpdateServers": "", 
         "middleName": "", 
         "sensorStates": [], 
         "vdiBaseDevice": "", 
         "windowsPlatform": "", 
         "firstVirusActivityTime": "", 
         "updateVersion": "", 
         "osVersion": "", 
         "deviceGuid": "", 
         "lastVirusActivityTime": "" 
     }, 
     "success": "" 
}

operation: Find Events

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned. 

Parameter Description
Hostname Hostname of the device whose events you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified hostnames based on a case-insensitive token search.
CarbonBlack Defense separates hostnames into parts or "tokens" defined by hyphens. So, for example, a hostname of WIN-IA9NQ1GN8OI will be parsed into two tokens: WIN and IA9NQ1GN8OI. Searching for hostName=IA9NQ1GN8OI and hostname=win will both match the hostname WIN-IA9NQ1GN8OI.
Hostname Exact Hostname of the device whose events you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified hostnames based on an exact match.
For example, hostName=WIN-IA9NQ1GN8OI will only return devices with the exact hostname WIN-IA9NQ1GN8OI but not a host named win-IA9NQ1GN8OI.
Owner Name Owner Name of the device whose events you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified owner name based on a case-insensitive token search.
Owner Name Exact Owner Name of the device whose events you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified owner name based on an exact match and a case-sensitive token search.
IP Address External or internal IP address of the device whose events you want to retrieve from CarbonBlack Defense.
Filehash Value of the SHA 256 filehash whose associated process has generated events that you want to retrieve from CarbonBlack Defense.
Note: The filehash value must be lowercase.
Application Name Name of the application (for example, googleupdate.exe.) whose associated process has generated events that you want to retrieve from CarbonBlack Defense.
Note: The application name must be lowercase.
Event Type Type of event that you want to retrieve from CarbonBlack Defense. You can select the event type, such as Network, File_Create, Registry_Access, etc. from the drop-down list.
Search Window Relative time frame within which events are generated in CarbonBlack Defense. This operation filters events and retrieves only those events that have been generated within the relative time frame that you have specified.
You can enter the search window, such as 3h, which represents the past three hours.
Note: By default, the search window is set to 1 day. Also, note that events prior to the last 30 days might not be available due to retention policies.
Start Record From Used for pagination. Specify the first record number that you want to the CarbonBlack Defense API to return for this operation.
Number of Records Used for pagination. Specify the maximum number of records that you want to the CarbonBlack Defense API to return for this operation.

Output

The output contains the following populated JSON schema:

     "totalResults": "", 
     "success": "", 
     "results": [ 
         { 
             "selectedApp": { 
                 "reputationProperty": "", 
                 "applicationName": "", 
                 "effectiveReputation": "", 
                 "sha256Hash": "", 
                 "virusSubCategory": "", 
                 "virusCategory": "", 
                 "md5Hash": "", 
                 "effectiveReputationSource": "", 
                 "applicationPath": "", 
                 "virusName": "" 
             }, 
             "securityEventCode": "", 
             "shortDescription": "", 
             "threatIndicators": [], 
             "createTime": "", 
             "alertScore": "", 
             "longDescription": "", 
             "netFlow": { 
                 "peerSiteReputation": "", 
                 "destAddress": "", 
                 "service": "", 
                 "peerIpAddress": "", 
                 "destPort": "", 
                 "sourceAddress": "", 
                 "peerFqdn": "", 
                 "peerLocation": { 
                     "city": "", 
                     "areaCode": "", 
                     "metroCode": "", 
                     "countryName": "", 
                     "countryCode": "", 
                     "region": "", 
                     "postalCode": "", 
                     "latitude": "", 
                     "dmaCode": "", 
                     "longitude": "" 
                 }, 
                 "peerIpV4Address": "", 
                 "sourcePort": "" 
             }, 
             "registryValue": "", 
             "attackStage": "", 
             "eventId": "", 
             "targetApp": { 
                 "reputationProperty": "", 
                 "applicationName": "", 
                 "effectiveReputation": "", 
                 "sha256Hash": "", 
                 "virusSubCategory": "", 
                 "virusCategory": "", 
                 "md5Hash": "", 
                 "effectiveReputationSource": "", 
                 "applicationPath": "", 
                 "virusName": "" 
             }, 
             "parentApp": { 
                 "reputationProperty": "", 
                 "applicationName": "", 
                 "effectiveReputation": "", 
                 "sha256Hash": "", 
                 "virusSubCategory": "", 
                 "virusCategory": "", 
                 "md5Hash": "", 
                 "effectiveReputationSource": "", 
                 "applicationPath": "", 
                 "virusName": "" 
             }, 
             "eventTime": "", 
             "eventType": "", 
             "incidentId": "", 
             "processDetails": { 
                 "fullUserName": "", 
                 "parentPid": "", 
                 "targetCommandLine": "", 
                 "userName": "", 
                 "processId": "", 
                 "interpreterName": "", 
                 "targetPid": "", 
                 "commandLine": "", 
                 "parentName": "", 
                 "interpreterHash": "", 
                 "privatePid": "", 
                 "name": "", 
                 "parentCommandLine": "", 
                 "parentPrivatePid": "", 
                 "milisSinceProcessStart": "", 
                 "targetPrivatePid": "", 
                 "targetName": "" 
             }, 
             "alertCategory": "", 
             "deviceDetails": { 
                 "targetPriorityCode": "", 
                 "deviceOwnerName": "", 
                 "email": "", 
                 "deviceIpV4Address": "", 
                 "deviceIpAddress": "", 
                 "deviceLocation": { 
                     "city": "", 
                     "areaCode": "", 
                     "metroCode": "", 
                     "countryName": "", 
                     "countryCode": "", 
                     "region": "", 
                     "postalCode": "", 
                     "latitude": "", 
                     "dmaCode": "", 
                     "longitude": "" 
                 }, 
                 "deviceVersion": "", 
                 "policyId": "", 
                 "deviceHostName": "", 
                 "deviceType": "", 
                 "deviceName": "", 
                 "agentLocation": "", 
                 "deviceId": "", 
                 "policyName": "", 
                 "targetPriorityType": "" 
             } 
         } 
     ], 
     "message": "", 
     "latestTime": "", 
     "elapsed": "" 
}

operation: Find Event By ID

Input parameters

Parameter Description
Event ID ID of the event whose details you want to retrieve from CarbonBlack Defense.

Output

The output contains the following populated JSON schema:

     "eventInfo": { 
         "selectedApp": { 
             "reputationProperty": "", 
             "applicationName": "", 
             "effectiveReputationSource": "", 
             "sha256Hash": "", 
             "virusSubCategory": "", 
             "virusCategory": "", 
             "md5Hash": "", 
             "effectiveReputation": "", 
             "applicationPath": "", 
             "virusName": "" 
         }, 
         "securityEventCode": "", 
         "shortDescription": "", 
         "threatIndicators": [], 
         "createTime": "", 
         "alertScore": "", 
         "longDescription": "", 
         "netFlow": { 
             "peerSiteReputation": "", 
             "destAddress": "", 
             "service": "", 
             "peerIpAddress": "", 
             "destPort": "", 
             "sourceAddress": "", 
             "peerFqdn": "", 
             "peerLocation": { 
                 "city": "", 
                 "areaCode": "", 
                 "metroCode": "", 
                 "countryName": "", 
                 "countryCode": "", 
                 "region": "", 
                 "postalCode": "", 
                 "latitude": "", 
                 "dmaCode": "", 
                 "longitude": "" 
             }, 
             "peerIpV4Address": "", 
             "sourcePort": "" 
         }, 
         "registryValue": "", 
         "attackStage": "", 
         "eventId": "", 
         "targetApp": { 
             "reputationProperty": "", 
             "applicationName": "", 
             "effectiveReputationSource": "", 
             "sha256Hash": "", 
             "virusSubCategory": "", 
             "virusCategory": "", 
             "md5Hash": "", 
             "effectiveReputation": "", 
             "applicationPath": "", 
             "virusName": "" 
         }, 
         "parentApp": { 
             "reputationProperty": "", 
             "applicationName": "", 
             "effectiveReputationSource": "", 
             "sha256Hash": "", 
             "virusSubCategory": "", 
             "virusCategory": "", 
             "md5Hash": "", 
             "effectiveReputation": "", 
             "applicationPath": "", 
             "virusName": "" 
         }, 
         "eventTime": "", 
         "eventType": "", 
         "incidentId": "", 
         "processDetails": { 
             "fullUserName": "", 
             "parentPid": "", 
             "targetCommandLine": "", 
             "userName": "", 
             "processId": "", 
             "interpreterName": "", 
             "targetPid": "", 
             "commandLine": "", 
             "parentName": "", 
             "interpreterHash": "", 
             "privatePid": "", 
             "name": "", 
             "parentCommandLine": "", 
             "parentPrivatePid": "", 
             "milisSinceProcessStart": "", 
             "targetPrivatePid": "", 
             "targetName": "" 
         }, 
         "alertCategory": "", 
         "deviceDetails": { 
             "targetPriorityCode": "", 
             "deviceOwnerName": "", 
             "email": "", 
             "deviceIpV4Address": "", 
             "deviceIpAddress": "", 
             "agentLocation": "", 
             "deviceVersion": "", 
             "policyId": "", 
             "deviceHostName": "", 
             "deviceType": "", 
             "deviceName": "", 
             "deviceLocation": { 
                 "city": "", 
                 "areaCode": "", 
                 "metroCode": "", 
                 "countryName": "", 
                 "countryCode": "", 
                 "region": "", 
                 "postalCode": "", 
                 "latitude": "", 
                 "dmaCode": "", 
                 "longitude": "" 
             }, 
             "deviceId": "", 
      &nbsnbsp;      "policyName": "", 
             "targetPriorityType": "" 
         } 
     }, 
     "message": "", 
     "success": "" 
}

operation: Find Processes

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied. and an unfiltered list is returned.

Parameter Description
Hostname Exact Hostname of the device whose processes you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified hostnames based on an exact match.
For example, hostName=WIN-IA9NQ1GN8OI will only return devices with the exact hostname WIN-IA9NQ1GN8OI but not a host named win-IA9NQ1GN8OI.
Owner Name Owner Name of the device whose processes you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified owner name based on a case-insensitive token search.
Owner Name Exact Owner Name of the device whose processes you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified owner name based on an exact match and a case-sensitive token search.
IP Address External or internal IP address of the devices whose processes you want to retrieve from CarbonBlack Defense.
Search Window Relative time frame within which processes are generated in CarbonBlack Defense. This operation filters events and retrieves only those processes that have been generated within the relative time frame that you have specified.
You can select the search window, such as 3h for the past three hours.
Note: By default, the search window is set to 1 day. Also, note that events prior to the last 30 days might not be available due to retention policies.
Start Record From Used for pagination. Specify the first record number that you want to the CarbonBlack Defense API to return for this operation.
Number of Records Used for pagination. Specify the maximum number of records that you want to the CarbonBlack Defense API to return for this operation.

Output

The output contains the following populated JSON schema:

     "totalResults": "", 
     "success": "", 
     "results": [ 
         { 
             "sha256Hash": "", 
             "applicationName": "", 
             "processId": "", 
             "privatePid": "", 
             "numEvents": "", 
             "applicationPath": "" 
         } 
     ], 
     "message": "", 
     "latestTime": "", 
     "elapsed": "" 
}

operation: Get Alert Details

Input parameters

Parameter Description
Alert ID ID of the alert whose details and associated event metadata you want to retrieve from CarbonBlack Defense.

Output

The output contains the following populated JSON schema:

     "deviceInfo": { 
         "linuxKernelVersion": "", 
         "scanStatus": "", 
         "avStatus": [], 
         "scanLastActionTime": "", 
         "adGroupId": "", 
         "registeredTime": "", 
         "policyOverride": "", 
         "adGroupName": "", 
         "avLastScanTime": "", 
         "deviceType": "", 
         "deviceName": "", 
         "assignedToName": "", 
         "deviceId": "", 
         "policyName": "", 
         "status": "", 
         "assignedToId": "", 
         "policyId": "", 
         "sensorVersion": "", 
         "userName": "", 
         "success": "", 
         "importance": "", 
         "loginUserName": "", 
         "sensorStates": "", 
         "scanLastCompleteTime": "", 
         "message": "", 
         "deregisteredTime": "", 
         "osVersion": "", 
         "avEngine": "" 
     }, 
     "success": true, 
     "threatInfo": { 
         "indicators": [ 
             { 
                 "sha256Hash": "", 
                 "indicatorName": "", 
                 "applicationName": "" 
             } 
         ], 
         "incidentId": "", 
         "time": "", 
         "summary": "", 
         "threatId": "", 
         "threatScore": "" 
     }, 
     "events": [ 
         { 
             "parentPid": "", 
             "processMd5Hash": "", 
             "userName": "", 
             "processId": "", 
             "parentHash": "", 
             "longDescription": "", 
             "policyState": "", 
             "eventId": "", 
             "parentName": "", 
             "killChainStatus": "", 
             "eventTime": "", 
             "eventType": "", 
             "threatIndicators": [], 
             "commandLine": "", 
             "parentCommandLine": "", 
             "processHash": "", 
             "parentPPid": "", 
             "applicationPath": "", 
             "processPPid": "" 
         } 
     ], 
     "message": "Success", 
     "orgId": "" 
}

operation: Get Notifications

Input parameters

None.

Output

The output contains the following populated JSON schema:

     "eventId": "", 
     "policyAction": { 
         "reputation": "", 
         "sha256Hash": "", 
         "action": "", 
         "applicationName": "" 
     }, 
     "eventDescription": "", 
     "eventTime": "", 
     "deviceInfo": { 
         "deviceHostName": "", 
         "deviceType": "", 
         "deviceName": "", 
         "email": "", 
         "deviceId": "", 
         "groupName": "", 
         "internalIpAddress": "", 
         "externalIpAddress": "", 
         "targetPriorityType": "", 
         "targetPriorityCode": "", 
         "deviceVersion": "" 
     }, 
     "ruleName": "", 
     "type": "", 
     "url": "" 
}

operation: Create Policy

Input parameters

Parameter Description
Create Policy Choose the option for creating the policy in CarbonBlack Defense. You can choose from the following options: Using Parameters or Using File.
If you choose Using File, then you must specify the following parameters:
  • CyOPs Attachment IRI: Specify the FortiSOAR™ Attachment IRI that is used to access the file directly from the FortiSOAR™ `Attachments` module. This should be the policy file that you want to import into CarbonBlack Defense.  
If you choose Using Parameters, then you must specify the following parameters:
  • Description: Description of the policy that you want to create in CarbonBlack Defense.
  • Name: One-line name of the policy that you want to create in CarbonBlack Defense.
  • Priority Level: Priority that you want to set for the policy, which you want to create in CarbonBlack Defense. You can choose the priority of the policy between High, Medium, and Low from the Priority Level drop-down list.
  • Policy Details: JSON object that contains the policy details that you want to create in CarbonBlack Defense.
    Note: You can retrieve a policy using the "Get Policy By ID" operation from your instance to determine the allowable values for your instance. See the policy key from response.

Output

The output contains the following populated JSON schema:

     "policyId": "", 
     "message": "", 
     "success": "" 
}

operation: Get All Policies

Input parameters

None.

Output

The output contains the following populated JSON schema:

     "results": [ 
         { 
             "policy": { 
                 "avSettings": { 
                     "features": [ 
                         { 
                             "enabled": "", 
                             "name": "" 
                         } 
                     ], 
                     "apc": { 
                         "maxExeDelay": "", 
                         "enabled": "", 
                         "riskLevel": "", 
                         "maxFileSize": "" 
                     }, 
                     "onDemandScan": { 
                         "schedule": { 
                             "recoveryScanIfMissed": "", 
                             "days": "", 
                             "rangeHours": "", 
                             "startHour": "" 
                         }, 
                         "scanCdDvd": "", 
                         "scanUsb": "", 
                         "profile": "" 
                     }, 
                     "signatureUpdate": { 
                         "schedule": { 
                             "fullIntervalHours": "", 
                             "initialRandomDelayHours": "", 
                             "intervalHours": "" 
                         } 
                     }, 
                     "onAccessScan": { 
                         "profile": "" 
                     }, 
                     "updateServers": { 
                         "servers": [ 
                             { 
                                 "server": [], 
                                 "flags": "", 
                                 "regId": "" 
                             } 
                         ], 
                         "serversForOffSiteDevices": [] 
                     } 
                 }, 
                 "sensorSettings": [ 
                     { 
                         "value": "", 
                         "name": "" 
                     } 
                 ], 
                 "directoryActionRules": [], 
                 "id": "", 
                 "knownBadHashAutoDeleteDelayMs": "", 
                 "rules": [ 
                     { 
                         "operation": "", 
                         "required": "", 
                         "application": { 
                             "value": "", 
                             "type": "" 
                         }, 
                         "id": "", 
                         "action": "" 
                     } 
                 ] 
             }, 
             "latestRevision": "", 
             "name": "", 
             "priorityLevel": "", 
             "systemPolicy": "", 
             "description": "", 
             "id": "", 
             "version": "" 
         } 
     ], 
     "message": "", 
     "success": "" 
}

operation: Get Policy By ID

Input parameters

Parameter Description
Policy ID ID of the policy whose details you want to retrieve from CarbonBlack Defense.

Output

The output contains the following populated JSON schema:

     "policyInfo": { 
         "policy": { 
             "avSettings": { 
                 "features": [ 
                     { 
                         "enabled": "", 
                         "name": "" 
                     } 
                 ], 
                 "apc": { 
                     "maxExeDelay": "", 
                     "enabled": "", 
                     "riskLevel": "", 
                     "maxFileSize": "" 
                 }, 
                 "onDemandScan": { 
                     "schedule": { 
                         "recoveryScanIfMissed": "", 
                         "days": "", 
                         "rangeHours": "", 
                         "startHour": "" 
                     }, 
                     "scanCdDvd": "", 
                     "scanUsb": "", 
                     "profile": "" 
                 }, 
                 "signatureUpdate": { 
                     "schedule": { 
                         "fullIntervalHours": "", 
                         "initialRandomDelayHours": "", 
                         "intervalHours": "" 
                     } 
                 }, 
                 "onAccessScan": { 
                     "profile": "" 
                 }, 
                 "updateServers": { 
                     "servers": [ 
                         { 
                             "server": [], 
                             "flags": "", 
                             "regId": "" 
                         } 
                     ], 
                     "serversForOffSiteDevices": [] 
                 } 
             }, 
             "sensorSettings": [ 
                 { 
                     "value": "", 
                     "name": "" 
                 } 
             ], 
             "directoryActionRules": [], 
             "id": "", 
             "knownBadHashAutoDeleteDelayMs": "", 
             "rules": [] 
         }, 
         "latestRevision": "", 
         "name": "", 
         "priorityLevel": "", 
         "systemPolicy": "", 
         "description": "", 
         "id": "", 
         "version": "" 
     }, 
     "message": "", 
     "success": "" 
}

operation: Update Policy

Input parameters

Parameter Description
Policy ID ID of the policy that you want to update in CarbonBlack Defense.
Update Policy Choose the option for updating an existing policy in CarbonBlack Defense. You can choose from the following options: Using Parameters or Using File.
If you choose Using File, then you must specify the following parameters:
  • CyOPs Attachment IRI: Specify the FortiSOAR™ Attachment IRI that is used to access the file directly from the FortiSOAR™ `Attachments` module. This should be the policy file that you want to import into CarbonBlack Defense.  
If you choose Using Parameters, then you must specify the following parameters:
  • Description: Description of the policy that you want to update in CarbonBlack Defense.
  • Name: One-line name of the policy that you want to update in CarbonBlack Defense.
  • Priority Level: Priority that you want to set for the policy, which you want to update in CarbonBlack Defense. You can choose the priority of the policy between High, Medium, and Low from the Priority Level drop-down list.
  • Policy Details: JSON object that contains the policy details that you want to update in CarbonBlack Defense.

Output

The output contains the following populated JSON schema:

     "message": "", 
     "success": "" 
}

operation: Delete Policy

Input parameters

Parameter Description
Policy ID ID of the policy whose details you want to delete from CarbonBlack Defense.

Output

The output contains the following populated JSON schema:
{
     "message": "",
     "success": ""
}

operation: Add Rule To Policy

Input parameters

Parameter Description
Policy ID ID of an existing policy in CarbonBlack Defense to which you want to add a rule.
Rule Info Fields that you want to add to the existing policy in CarbonBlack Defense. You must add field information in the JSON format.

Output

The output contains the following populated JSON schema:

     "ruleId": "", 
     "message": "", 
     "success": "" 
}

operation: Update Rule in Policy

Input parameters

Parameter Description
Policy ID ID of an existing policy in CarbonBlack Defense in which you want to update a rule.
Rule ID ID of the rule that you want to update in CarbonBlack Defense.
Rule Info Fields that you want to update in the existing rule and policy in CarbonBlack Defense. You must add field information in the JSON format.

Output

The output contains the following populated JSON schema:
{
     "message": "",
     "success": ""
}

operation: Delete Rule from Policy

Input parameters

Parameter Description
Policy ID ID of an existing policy in CarbonBlack Defense from which you want to delete a rule.
Rule ID ID of the rule whose details you want to delete from CarbonBlack Defense.

Output

The output contains the following populated JSON schema:
{
     "message": "",
     "success": ""
}

operation: Execute Live Commands - File

Input parameters

Parameter Description
Device/Sensor ID ID of the device or Sensor used to establish the live response session.
Command to Execute Command that you want to execute on the remote endpoints. You can choose from the following options: List Directory, Get File, Put File, or Delete File.
If you choose List Directory, then you must specify the following parameters:
  • Directory Path: Filter specifying the directory path or listing.
If you choose Get File, then you must specify the following parameters:
  • File Path: Source path of the file that you want to retrieve.
If you choose Put File, then you must specify the following parameters:
  • Destination File Path: Destination Path of the file, i.e., the path where you want to save the file on CarbonBlack Defense. 
  • CyOPs Attachment IRI: Specify the FortiSOAR™ Attachment IRI that is used to access the file directly from the FortiSOAR™ `Attachments` module. This should be the file that you want to import into CarbonBlack Defense.  
If you choose Delete File, then you must specify the following parameters:
  • File Path: Source path of the file that you want to delete from CarbonBlack Defense.

Output

The output contains the following populated JSON schema based on the command you have selected.

For the List Directory command:

{
"result_code": "",
"result_desc": "",
"result_type": "",
"username": "",
"status": "",
"files": [
{
"alternate_name": "",
     "last_write_time": "",
"create_time": "",
"size": "",
"filename": "",
"last_access_time": "",
"attributes": [
]
}
],
"name": "",
"id": "",
"obj": {
"name": "",
"object": ""
},
"creation_time": "",
"completion_time": ""
 }

For the Get File command:

{
"@id": "",
"@type": "",
"type": "",
"name": "",
"modifyDate": "",
"file": {
"@id": "",
"size": "",
"file": {
"@type": ""
},
"filename": "",
"metadata": "",
"owners": [
],
"uploadDate": "",
"@type": "",
"mimeType": "",
"@context": ""
}
}

For the Put File command:

{
"completion_time": "",
"status": "",
"username": "",
"result_code": "",
"name": "",
"result_desc": "",
"creation_time": "",
"obj": {
"file_id": "",
"object": "",
"name": "",
"chunkNumber": ""
},
"id": "",
"file_id": "",
"result_type": ""
}

For the Delete File command:

{
"creation_time": "",
"id": "",
"result_code": "",
"status": "",
"result_desc": "",
"name": "",
"obj": {
"name": "",
"object": ""
},
"username": "",
"completion_time": "",
"result_type": ""
}

operation: Execute Live Commands - Process

Input parameters

Parameter Description
Device/Sensor ID ID of the device or Sensor used to establish the live response session.
Command to execute Command that you want to execute on the remote endpoints. You can choose from the following options: Create Process, List Process, Kill Process, or Memory Dump.
If you choose Create Process, then you must specify the following parameters:
  • Executable's Path: Path and command line of the executable.
  • Working Directory: (Optional) Working directory of the executable.
  • Output File: (Optional) Name and path of the file used to capture STDERR and STDOUT.
  • Wait to Complete Execution: Select this option, i.e., set it to True if you want to wait for the process to complete execution before reporting the result. By default, it is set to False.
No input is required for the List Process command.
If you choose Kill Process, then you must specify the following parameters:
  • Process ID: ID of the process you want to kill on CarbonBlack Defense.
If you choose Memory Dump, then you must specify the following parameters:
  • Location to Store the Memory Dump: Path to save the resulting memory dump on the endpoint.
  • Compress Resulting Memory Dump: Select this option i.e. set it to True, if you want to compress the resulting memory dump. By default, it is set to False.

Output

The output contains the following populated JSON schema based on the command you have selected.

For the Create Process command:

{
"result_code": "",
"status": "",
"result_type": "",
"pid": "",
"obj": {
"name": "",
"object": "",
"working_directory": "",
"wait": ""
},
"creation_time": "",
"completion_time": "",
"name": "",
"result_desc": "",
"username": "",
"id": "",
"return_code": ""
}

For the List Process command:

{
"result_code": "",
"result_desc": "",
"result_type": "",
"username": "null",
"processes": [
{
"command_line": "",
"path": "",
"sid": "",
"parent_create_time": "",
"username": "",
"create_time": "",
"pid": "",
"parent": ""
}
],
"status": "",
"name": "",
"id": "",
"obj": {
"name": ""
},
"creation_time": "",
"completion_time": ""
}

For the Kill Process command:

{
"result_code": "",
"result_desc": "",
"result_type": "",
"username": "",
"status": "",
"name": "",
"id": "",
"obj": {
"name": "",
"object": ""
},
"creation_time": "",
"completion_time": ""
}

For the Memory Dump command:

{
"result_code": "",
"result_desc": "",
"result_type": "",
"username": "",
"status": "",
"name": "",
"id": "",
"obj": {
"compress": "",
"object": ""
},
"creation_time": "",
"completion_time": "",
"return_code":"",
"compressing":"",
"complete":"",
"percentdone": "",
"dumping": ""
}

operation: Execute Live Commands - Registry

Input parameters

Parameter Description
Device/Sensor ID ID of the device or Sensor used to establish the live response session.
Command to execute Command that you want to execute on the remote endpoints.  You can choose from the following options: Create Key, Enumerate Key, Delete Key, Query Value, Set Value, or Delete Value.
If you choose Create Key, which is used to create a new registry, then you must specify the following parameters:
  • Key Path: Path where you want to create the registry key.
If you choose Enumerate Key, which is used to enumerate subkeys and values of the specified registry key, then you must specify the following parameters:
  • Key Path: Path of the registry key that you want to query.
If you choose Delete Key, which is used to delete a registry key, then you must specify the following parameters:
  • Key Path: Path from where you want to delete the registry key.
If you choose Query Value, which is used to return the associated value of the specified registry key, then you must specify the following parameters:
  • Key-Value Pair: Key-Value pair based on which you want to query the registry keys.
If you choose Set Value, which is used to set a registry value of the specified registry key, then you must specify the following parameters:
  • Key-Value Pair: Key-Value pair that you want to set for the registry keys.
  • Data to set for value
  • Value Type: Type of value to be set for the registry keys, such as REG_SZ, REG_DWORD, REG_QWORD, etc.
  • Overwrite: Specify whether to overwrite the value of the registry key if it already exists.
If you choose Delete Value, which is used to delete a registry value, then you must specify the following parameters:
  • Key Path: Path from where you want to delete the registry value.

Output

The output contains the following populated JSON schema based on the command you have selected.

For the Create Key command:

{
"creation_time": "",
"id": "",
"result_desc": "",
"result_code": "",
"completion_time": "",
"status": "",
"username": "",
"obj": {
"hive": "",
"key": "",
"object": "",
"name": ""
},
"name": "",
"result_type": ""
}
For the Enumerate Key command:
{
"username": "",
"id": "",
"result_code": "",
"status": "",
"obj": {
"hive": "",
"key": "",
"object": "",
"name": ""
},
"completion_time": "",
"sub_keys": [],
"values": [],
"creation_time": "",
"result_type": "",
"result_desc": "",
"name": ""
}

For the Delete Key command:

{
"creation_time": "",
"id": "",
"result_desc": "",
"result_code": "",
"completion_time": "",
"status": "",
"username": "",
"obj": {
"hive": "",
"key": "",
"object": "",
"name": ""
},
"name": "",
"result_type": ""
}

For the Query Value command:

{
"creation_time": "",
"id": "",
"result_desc": "",
"result_code": "",
"completion_time": "",
"status": "",
"username": "",
"value": {
"value_type": "",
"value_name": "",
"value_data": ""
},
"obj": {
"hive": "",
"key": "",
"value_name": "",
"object": "",
"name": ""
},
"name": "",
"result_type": ""
 }

For the Set Value command:

{
"creation_time": "",
"id": "",
"result_desc": "",
"result_code": "",
"completion_time": "",
"status": "",
"username": "",
"obj": {
"overwrite": "",
"hive": "",
"key": "",
"value_name": "",
"object": "",
"value_data": "",
"name": "",
"value_type": ""
},
"name": "",
"result_type": ""
 }

For the Delete Value command:

{
"creation_time": "",
"id": "",
"result_desc": "",
"result_code": "",
"completion_time": "",
"status": "",
"username": "",
"obj": {
"hive": "",
"key": "",
"value_name": "",
"object": "",
"name": ""
},
"name": "",
"result_type": ""
 }

Included playbooks

The Sample - CarbonBlack Defense - 2.0.0 playbook collection comes bundled with the CarbonBlack Defense connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the CarbonBlack Defense connector.

  • Add Rule To Policy
  • Change Device Status
  • Create Policy
  • Delete Policy
  • Delete Rule from Policy
  • Execute Live Commands - File
  • Execute Live Commands - Process
  • Execute Live Commands - Registry
  • Find Event By ID
  • Find Events
  • Find Processes
  • Get Alert Details
  • Get All Policies
  • Get Devices Status
  • Get Device Status
  • Get Notifications
  • Get Policy By ID
  • Update Policy
  • Update Rule in Policy

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 connector upgrade and delete.

About the connector

CarbonBlack Defense is an industry-leading, cloud-delivered endpoint security solution that combines next-generation antivirus (NGAV) and endpoint detection and response (EDR) capabilities into a lightweight solution that is fast to deploy and easy to manage.

This document provides information about the CarbonBlack Defense connector, which facilitates automated interactions with CarbonBlack Defense using FortiSOAR™ playbooks. Add the CarbonBlack Defense connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving the status of all devices from CarbonBlack Defense and changing the status of an individual device, by its device ID, on CarbonBlack Defense.

Version information

Connector Version: 2.0.0

Authored By: Fortinet

FortiSOAR™ Version Tested on: 4.12.1-253 

Certified: Yes

Release Notes for version 2.0.0

Following enhancements have been made to the CarbonBlack Defense connector in version 2.0.0:

Installing the connector

All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:

yum install cyops-connector-carbonblack-defense

For the detailed procedure to install a connector, click here.

Prerequisites to configuring the connector

Configuring the connector 

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™ , on the connectors page, select the CarbonBlack Defense connector and click Configure to configure the following parameters:

Parameter Description
Server URL IP address or Hostname of the Carbon Black Defense server to which you will connect and perform automated operations.
API Key API key that is provided to you by the Carbon Black Defense administrator to access the Carbon Black Defense REST API.
Connector ID Connector ID that is provided to you by the Carbon Black Defense administrator to access the Carbon Black Defense 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™ release 4.10.0 onwards:

Function Description Annotation and Category
Get Devices Status Retrieves the status of all devices or specific devices from CarbonBlack Defense based on the input search criteria you have specified. search_device
Investigation
Get Device Status Retrieves the status and details for a device from CarbonBlack Defense based on the device ID you have specified. search_device
Investigation
Change Device Status Changes the status for a device on CarbonBlack Defense based on the device ID you have specified.
Note: The current revision of the CarbonBlack Defense API only allows one element to be changed with this call, which is the security policy assigned to the device.
update_device
Investigation
Find Events Retrieves all events or specific events from CarbonBlack Defense based on the input search criteria you have specified. search_event
Investigation
Find Event By ID Retrieves the details for an event from CarbonBlack Defense based on the event ID you have specified. search_event
Investigation
Find Processes Retrieves all processes or specific processes from CarbonBlack Defense based on the input search criteria you have specified. search_process
Investigation
Get Alert Details Retrieves details and all metadata, including a list of all the events associated with the specified alert from CarbonBlack Defense based on the alert ID you have specified. get_alert
Investigation
Get Notifications Retrieves information about all the new notifications from CarbonBlack Defense since the last check-in on CarbonBlack Defense. get_notification
Investigation
Create Policy Creates a new policy in CarbonBlack Defense based on the input parameters or policy file you have specified create_policy
Investigation
Get All Policies Retrieves a list of all policies available in the organization from CarbonBlack Defense. search_policy
Investigation
Get Policy By ID Retrieves the details of a policy from CarbonBlack Defense based on the policy ID you have specified. search_policy
Investigation
Update Policy Updates an existing policy with a new policy in CarbonBlack Defense based on the input parameters or policy file you have specified. update_policy
Investigation
Delete Policy Deletes details of an existing policy from CarbonBlack Defense based on the policy ID you have specified. delete_policy
Miscellaneous
Add Rule To Policy Adds a new rule to an existing policy in CarbonBlack Defense based on the policy ID and information about the rule you have specified. update_policy
Investigation
Update Rule To Policy Updates an existing policy with a new rule in an existing policy in CarbonBlack Defense based on the policy ID, rule ID, and information about the rule you have specified. update_policy
Investigation
Delete Rule From Policy Deletes the details of an existing rule from an existing policy on CarbonBlack Defense based on the policy ID and rule ID you have specified. update_policy
Investigation
Execute Live Commands - File Takes action on remote endpoints in real time. These actions include the ability to list directories, and upload, download, and remove files. execute_commands
Investigation
Execute Live Commands - Process Takes action on remote endpoints in real time. These actions include the ability to dump contents of physical memory, list processes, and execute and terminate processes. execute_commands
Investigation
Execute Live Commands - Registry Takes action on remote endpoints in real time. These actions include the ability to create, retrieve, alter and remove registry entries. execute_commands
Investigation

operation: Get Devices Status

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Hostname Hostname of the device whose status you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified hostnames based on a case-insensitive token search.
CarbonBlack Defense separates hostnames into parts or "tokens" defined by hyphens. So, for example, a hostname of WIN-IA9NQ1GN8OI will be parsed into two tokens: WIN and IA9NQ1GN8OI. Searching for hostName=IA9NQ1GN8OI and hostname=win will both match the hostname WIN-IA9NQ1GN8OI.
Hostname Exact Hostname of the device whose status you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified hostnames based on an exact match.
For example, hostName=WIN-IA9NQ1GN8OI will only return devices with the exact hostname WIN-IA9NQ1GN8OI but not a host named win-IA9NQ1GN8OI.
Owner Name Owner Name of the device whose status you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified owner name based on a case-insensitive token search.
Owner Name Exact Owner Name of the device whose status you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified owner name based on an exact match and a case-sensitive token search.
IP Address External or internal IP address of the device whose status you want to retrieve from CarbonBlack Defense.
Start Record From Used for pagination. Specify the first record number that you want to the CarbonBlack Defense API to return for this operation.
Number of Records Used for pagination. Specify the maximum number of records that you want to the CarbonBlack Defense API to return for this operation.

Output

The output contains the following populated JSON schema:

     "totalResults": "", 
     "success": "", 
     "results": [ 
         { 
             "uninstallCode": "", 
             "lastExternalIpAddress": "", 
             "organizationName": "", 
             "scanLastCompleteTime": "", 
             "assignedToName": "", 
             "lastInternalIpAddress": "", 
             "lastShutdownTime": "", 
             "passiveMode": "", 
             "testId": "", 
             "lastResetTime": "", 
             "avProductVersion": "", 
             "avVdfVersion": "", 
             "virtualizationProvider": "", 
             "loginUserName": "", 
             "targetPriorityType": "", 
             "uninstalledTime": "", 
             "sensorStates": [], 
             "policyName": "", 
             "sensorOutOfDate": "", 
             "createTime": "", 
             "email": "", 
             "vdiBaseDevice": "", 
             "deviceMetaDataItemList": "", 
             "rootedBySensor": "", 
             "scanLastActionTime": "", 
             "macAddress": "", 
             "deviceType": "", 
             "organizationId": "", 
             "adGroupId": "", 
             "windowsPlatform": "", 
             "virtualMachine": "", 
             "firstName": "", 
             "lastLocation": "", 
             "rootedBySensorTime": "", 
             "avEngine": "", 
             "linuxKernelVersion": "", 
             "scanStatus": "", 
             "avStatus": [], 
             "avAveVersion": "", 
             "registeredTime": "", 
             "avMaster": "", 
             "policyOverride": false, 
             "lastName": "", 
             "activationCodeExpiryTime": "", 
             "avLastScanTime": "", 
             "originEventHash": "", 
             "rootedByAnalyticsTime": "", 
             "messages": "", 
             "lastContact": "", 
             "deviceId": "", 
             "name": "", 
             "sensorVersion": "", 
             "activationCode": "", 
             "lastReportedTime": "", 
             "lastDevicePolicyChangedTime": "", 
             "encodedActivationCode": "", 
             "assignedToId": "", 
             "deviceOwnerId": "", 
             "avPackVersion": "", 
             "firstVirusActivityTime": "", 
             "quarantined": "", 
             "deviceSessionId": "", 
             "lastDevicePolicyRequestedTime": "", 
             "middleName": "", 
             "policyId": "", 
             "rootedByAnalytics": "", 
             "currentSensorPolicyName": "", 
             "status": "", 
             "avUpdateServers": "", 
             "deregisteredTime": "", 
             "lastPolicyUpdatedTime": "", 
             "osVersion": "", 
             "deviceGuid": "", 
             "lastVirusActivityTime": "" 
         } 
     ], 
     "message": "", 
     "latestTime": "", 
     "elapsed": "" 
}

operation: Get Device Status

Input parameters

Parameter Description
Device ID ID of the device whose details and status you want to retrieve from CarbonBlack Defense.

Output

The output contains the following populated JSON schema:

     "message": "", 
     "deviceInfo": { 
         "uninstallCode": "", 
         "lastPolicyChangedTime": "", 
         "lastExternalIpAddress": "", 
         "organizationName": "", 
         "adGroupId": "", 
         "lastInternalIpAddress": "", 
         "lastShutdownTime": "", 
         "passiveMode": "", 
         "status": "", 
         "lastResetTime": "", 
         "windowsPlatform": "", 
         "virtualizationProvider": "", 
         "lastPolicyRequestedTime": "", 
         "loginUserName": "", 
         "avStatus": [], 
         "organizationId": "", 
         "uninstalledTime": "", 
         "rootedByAnalyticsTime": "", 
         "sensorStates": [], 
         "policyName": "", 
         "sensorOutOfDate": "", 
         "assignedToName": "", 
         "email": "", 
         "rootedByAnalytics": "", 
         "rootedBySensor": "", 
         "macAddress": "", 
         "targetPriorityType": "", 
         "scanLastCompleteTime": "", 
         "activationCode": "", 
         "virtualMachine": "", 
         "name": "", 
         "firstName": "", 
         "lastLocation": "", 
         "rootedBySensorTime": "", 
         "blades": "", 
         "avEngine": "", 
         "linuxKernelVersion": "", 
         "scanStatus": "", 
         "createTime": "", 
         "scanLastActionTime": "", 
         "registeredTime": "", 
         "avMaster": "", 
         "policyOverride": "", 
         "lastName": "", 
         "avLastScanTime": "", 
         "deviceType": "", 
         "messages": "", 
         "lastContact": "", 
         "deviceId": "", 
         "testId": "", 
         "sensorVersion": "", 
         "deviceSessionId": "", 
         "quarantined": "", 
         "apcEnabled": "", 
         "lastReportedTime": "", 
         "assignedToId": "", 
         "deviceOwnerId": "", 
         "avUpdateServers": "", 
         "vdiBaseDevice": "", 
         "middleName": "", 
         "policyId": "", 
         "currentSensorPolicyName": "", 
         "updateVersion": "", 
         "firstVirusActivityTime": "", 
         "osVersion": "", 
         "deviceGuid": "", 
         "lastVirusActivityTime": "" 
     }, 
     "success": "" 
}

operation: Change Device Status

Input parameters

Parameter Description
Device ID ID of the device whose associated security policy you want to change on CarbonBlack Defense.
Update Security Policy Assigned to Device by: Security policy that you want to change on CarbonBlack Defense and which is assigned to the specified device. You can specify the security policy by either specifying the Policy ID or the Policy Name.
If you choose Policy ID, then you must specify the following parameters:
  • Policy ID: ID of the security policy that is assigned to the specified device and which you want to change.
If you choose Policy Name, then you must specify the following parameters:
  • Policy Name: Name of the security policy that is assigned to the specified device and which you want to change.

Output

The output contains the following populated JSON schema:



     "message": "", 
     "deviceInfo": { 
         "organizationName": "", 
         "lastContact": "", 
         "scanLastCompleteTime": "", 
         "lastInternalIpAddress": "", 
         "lastShutdownTime": "", 
         "passiveMode": "", 
         "testId": "", 
         "lastResetTime": "", 
         "policyName": "", 
         "sensorOutOfDate": "", 
         "avStatus": [], 
         "targetPriorityType": "", 
         "status": "", 
         "policyId": "", 
         "rootedByAnalyticsTime": "", 
         "assignedToName": "", 
         "email": "", 
         "rootedByAnalytics": "", 
         "rootedBySensor": "", 
         "assignedToId": "", 
         "organizationId": "", 
         "activationCode": "", 
         "uninstalledTime": "", 
         "firstName": "", 
         "lastLocation": "", 
         "id": "", 
         "rootedBySensorTime": "", 
         "avEngine": "", 
         "linuxKernelVersion": "", 
         "scanStatus": "", 
         "createTime": "", 
         "scanLastActionTime": "", 
         "registeredTime": "", 
         "avMaster": "", 
         "lastName": "", 
         "avLastScanTime": "", 
         "deviceType": "", 
         "messages": "", 
         "lastExternalIpAddress": "", 
         "deviceId": "", 
         "name": "", 
         "sensorVersion": "", 
         "deviceSessionId": "", 
         "lastReportedTime": "", 
         "quarantined": "", 
         "deviceOwnerId": "", 
         "avUpdateServers": "", 
         "middleName": "", 
         "sensorStates": [], 
         "vdiBaseDevice": "", 
         "windowsPlatform": "", 
         "firstVirusActivityTime": "", 
         "updateVersion": "", 
         "osVersion": "", 
         "deviceGuid": "", 
         "lastVirusActivityTime": "" 
     }, 
     "success": "" 
}

operation: Find Events

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned. 

Parameter Description
Hostname Hostname of the device whose events you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified hostnames based on a case-insensitive token search.
CarbonBlack Defense separates hostnames into parts or "tokens" defined by hyphens. So, for example, a hostname of WIN-IA9NQ1GN8OI will be parsed into two tokens: WIN and IA9NQ1GN8OI. Searching for hostName=IA9NQ1GN8OI and hostname=win will both match the hostname WIN-IA9NQ1GN8OI.
Hostname Exact Hostname of the device whose events you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified hostnames based on an exact match.
For example, hostName=WIN-IA9NQ1GN8OI will only return devices with the exact hostname WIN-IA9NQ1GN8OI but not a host named win-IA9NQ1GN8OI.
Owner Name Owner Name of the device whose events you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified owner name based on a case-insensitive token search.
Owner Name Exact Owner Name of the device whose events you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified owner name based on an exact match and a case-sensitive token search.
IP Address External or internal IP address of the device whose events you want to retrieve from CarbonBlack Defense.
Filehash Value of the SHA 256 filehash whose associated process has generated events that you want to retrieve from CarbonBlack Defense.
Note: The filehash value must be lowercase.
Application Name Name of the application (for example, googleupdate.exe.) whose associated process has generated events that you want to retrieve from CarbonBlack Defense.
Note: The application name must be lowercase.
Event Type Type of event that you want to retrieve from CarbonBlack Defense. You can select the event type, such as Network, File_Create, Registry_Access, etc. from the drop-down list.
Search Window Relative time frame within which events are generated in CarbonBlack Defense. This operation filters events and retrieves only those events that have been generated within the relative time frame that you have specified.
You can enter the search window, such as 3h, which represents the past three hours.
Note: By default, the search window is set to 1 day. Also, note that events prior to the last 30 days might not be available due to retention policies.
Start Record From Used for pagination. Specify the first record number that you want to the CarbonBlack Defense API to return for this operation.
Number of Records Used for pagination. Specify the maximum number of records that you want to the CarbonBlack Defense API to return for this operation.

Output

The output contains the following populated JSON schema:

     "totalResults": "", 
     "success": "", 
     "results": [ 
         { 
             "selectedApp": { 
                 "reputationProperty": "", 
                 "applicationName": "", 
                 "effectiveReputation": "", 
                 "sha256Hash": "", 
                 "virusSubCategory": "", 
                 "virusCategory": "", 
                 "md5Hash": "", 
                 "effectiveReputationSource": "", 
                 "applicationPath": "", 
                 "virusName": "" 
             }, 
             "securityEventCode": "", 
             "shortDescription": "", 
             "threatIndicators": [], 
             "createTime": "", 
             "alertScore": "", 
             "longDescription": "", 
             "netFlow": { 
                 "peerSiteReputation": "", 
                 "destAddress": "", 
                 "service": "", 
                 "peerIpAddress": "", 
                 "destPort": "", 
                 "sourceAddress": "", 
                 "peerFqdn": "", 
                 "peerLocation": { 
                     "city": "", 
                     "areaCode": "", 
                     "metroCode": "", 
                     "countryName": "", 
                     "countryCode": "", 
                     "region": "", 
                     "postalCode": "", 
                     "latitude": "", 
                     "dmaCode": "", 
                     "longitude": "" 
                 }, 
                 "peerIpV4Address": "", 
                 "sourcePort": "" 
             }, 
             "registryValue": "", 
             "attackStage": "", 
             "eventId": "", 
             "targetApp": { 
                 "reputationProperty": "", 
                 "applicationName": "", 
                 "effectiveReputation": "", 
                 "sha256Hash": "", 
                 "virusSubCategory": "", 
                 "virusCategory": "", 
                 "md5Hash": "", 
                 "effectiveReputationSource": "", 
                 "applicationPath": "", 
                 "virusName": "" 
             }, 
             "parentApp": { 
                 "reputationProperty": "", 
                 "applicationName": "", 
                 "effectiveReputation": "", 
                 "sha256Hash": "", 
                 "virusSubCategory": "", 
                 "virusCategory": "", 
                 "md5Hash": "", 
                 "effectiveReputationSource": "", 
                 "applicationPath": "", 
                 "virusName": "" 
             }, 
             "eventTime": "", 
             "eventType": "", 
             "incidentId": "", 
             "processDetails": { 
                 "fullUserName": "", 
                 "parentPid": "", 
                 "targetCommandLine": "", 
                 "userName": "", 
                 "processId": "", 
                 "interpreterName": "", 
                 "targetPid": "", 
                 "commandLine": "", 
                 "parentName": "", 
                 "interpreterHash": "", 
                 "privatePid": "", 
                 "name": "", 
                 "parentCommandLine": "", 
                 "parentPrivatePid": "", 
                 "milisSinceProcessStart": "", 
                 "targetPrivatePid": "", 
                 "targetName": "" 
             }, 
             "alertCategory": "", 
             "deviceDetails": { 
                 "targetPriorityCode": "", 
                 "deviceOwnerName": "", 
                 "email": "", 
                 "deviceIpV4Address": "", 
                 "deviceIpAddress": "", 
                 "deviceLocation": { 
                     "city": "", 
                     "areaCode": "", 
                     "metroCode": "", 
                     "countryName": "", 
                     "countryCode": "", 
                     "region": "", 
                     "postalCode": "", 
                     "latitude": "", 
                     "dmaCode": "", 
                     "longitude": "" 
                 }, 
                 "deviceVersion": "", 
                 "policyId": "", 
                 "deviceHostName": "", 
                 "deviceType": "", 
                 "deviceName": "", 
                 "agentLocation": "", 
                 "deviceId": "", 
                 "policyName": "", 
                 "targetPriorityType": "" 
             } 
         } 
     ], 
     "message": "", 
     "latestTime": "", 
     "elapsed": "" 
}

operation: Find Event By ID

Input parameters

Parameter Description
Event ID ID of the event whose details you want to retrieve from CarbonBlack Defense.

Output

The output contains the following populated JSON schema:

     "eventInfo": { 
         "selectedApp": { 
             "reputationProperty": "", 
             "applicationName": "", 
             "effectiveReputationSource": "", 
             "sha256Hash": "", 
             "virusSubCategory": "", 
             "virusCategory": "", 
             "md5Hash": "", 
             "effectiveReputation": "", 
             "applicationPath": "", 
             "virusName": "" 
         }, 
         "securityEventCode": "", 
         "shortDescription": "", 
         "threatIndicators": [], 
         "createTime": "", 
         "alertScore": "", 
         "longDescription": "", 
         "netFlow": { 
             "peerSiteReputation": "", 
             "destAddress": "", 
             "service": "", 
             "peerIpAddress": "", 
             "destPort": "", 
             "sourceAddress": "", 
             "peerFqdn": "", 
             "peerLocation": { 
                 "city": "", 
                 "areaCode": "", 
                 "metroCode": "", 
                 "countryName": "", 
                 "countryCode": "", 
                 "region": "", 
                 "postalCode": "", 
                 "latitude": "", 
                 "dmaCode": "", 
                 "longitude": "" 
             }, 
             "peerIpV4Address": "", 
             "sourcePort": "" 
         }, 
         "registryValue": "", 
         "attackStage": "", 
         "eventId": "", 
         "targetApp": { 
             "reputationProperty": "", 
             "applicationName": "", 
             "effectiveReputationSource": "", 
             "sha256Hash": "", 
             "virusSubCategory": "", 
             "virusCategory": "", 
             "md5Hash": "", 
             "effectiveReputation": "", 
             "applicationPath": "", 
             "virusName": "" 
         }, 
         "parentApp": { 
             "reputationProperty": "", 
             "applicationName": "", 
             "effectiveReputationSource": "", 
             "sha256Hash": "", 
             "virusSubCategory": "", 
             "virusCategory": "", 
             "md5Hash": "", 
             "effectiveReputation": "", 
             "applicationPath": "", 
             "virusName": "" 
         }, 
         "eventTime": "", 
         "eventType": "", 
         "incidentId": "", 
         "processDetails": { 
             "fullUserName": "", 
             "parentPid": "", 
             "targetCommandLine": "", 
             "userName": "", 
             "processId": "", 
             "interpreterName": "", 
             "targetPid": "", 
             "commandLine": "", 
             "parentName": "", 
             "interpreterHash": "", 
             "privatePid": "", 
             "name": "", 
             "parentCommandLine": "", 
             "parentPrivatePid": "", 
             "milisSinceProcessStart": "", 
             "targetPrivatePid": "", 
             "targetName": "" 
         }, 
         "alertCategory": "", 
         "deviceDetails": { 
             "targetPriorityCode": "", 
             "deviceOwnerName": "", 
             "email": "", 
             "deviceIpV4Address": "", 
             "deviceIpAddress": "", 
             "agentLocation": "", 
             "deviceVersion": "", 
             "policyId": "", 
             "deviceHostName": "", 
             "deviceType": "", 
             "deviceName": "", 
             "deviceLocation": { 
                 "city": "", 
                 "areaCode": "", 
                 "metroCode": "", 
                 "countryName": "", 
                 "countryCode": "", 
                 "region": "", 
                 "postalCode": "", 
                 "latitude": "", 
                 "dmaCode": "", 
                 "longitude": "" 
             }, 
             "deviceId": "", 
      &nbsnbsp;      "policyName": "", 
             "targetPriorityType": "" 
         } 
     }, 
     "message": "", 
     "success": "" 
}

operation: Find Processes

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied. and an unfiltered list is returned.

Parameter Description
Hostname Exact Hostname of the device whose processes you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified hostnames based on an exact match.
For example, hostName=WIN-IA9NQ1GN8OI will only return devices with the exact hostname WIN-IA9NQ1GN8OI but not a host named win-IA9NQ1GN8OI.
Owner Name Owner Name of the device whose processes you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified owner name based on a case-insensitive token search.
Owner Name Exact Owner Name of the device whose processes you want to retrieve from CarbonBlack Defense. The operation filters the results on the specified owner name based on an exact match and a case-sensitive token search.
IP Address External or internal IP address of the devices whose processes you want to retrieve from CarbonBlack Defense.
Search Window Relative time frame within which processes are generated in CarbonBlack Defense. This operation filters events and retrieves only those processes that have been generated within the relative time frame that you have specified.
You can select the search window, such as 3h for the past three hours.
Note: By default, the search window is set to 1 day. Also, note that events prior to the last 30 days might not be available due to retention policies.
Start Record From Used for pagination. Specify the first record number that you want to the CarbonBlack Defense API to return for this operation.
Number of Records Used for pagination. Specify the maximum number of records that you want to the CarbonBlack Defense API to return for this operation.

Output

The output contains the following populated JSON schema:

     "totalResults": "", 
     "success": "", 
     "results": [ 
         { 
             "sha256Hash": "", 
             "applicationName": "", 
             "processId": "", 
             "privatePid": "", 
             "numEvents": "", 
             "applicationPath": "" 
         } 
     ], 
     "message": "", 
     "latestTime": "", 
     "elapsed": "" 
}

operation: Get Alert Details

Input parameters

Parameter Description
Alert ID ID of the alert whose details and associated event metadata you want to retrieve from CarbonBlack Defense.

Output

The output contains the following populated JSON schema:

     "deviceInfo": { 
         "linuxKernelVersion": "", 
         "scanStatus": "", 
         "avStatus": [], 
         "scanLastActionTime": "", 
         "adGroupId": "", 
         "registeredTime": "", 
         "policyOverride": "", 
         "adGroupName": "", 
         "avLastScanTime": "", 
         "deviceType": "", 
         "deviceName": "", 
         "assignedToName": "", 
         "deviceId": "", 
         "policyName": "", 
         "status": "", 
         "assignedToId": "", 
         "policyId": "", 
         "sensorVersion": "", 
         "userName": "", 
         "success": "", 
         "importance": "", 
         "loginUserName": "", 
         "sensorStates": "", 
         "scanLastCompleteTime": "", 
         "message": "", 
         "deregisteredTime": "", 
         "osVersion": "", 
         "avEngine": "" 
     }, 
     "success": true, 
     "threatInfo": { 
         "indicators": [ 
             { 
                 "sha256Hash": "", 
                 "indicatorName": "", 
                 "applicationName": "" 
             } 
         ], 
         "incidentId": "", 
         "time": "", 
         "summary": "", 
         "threatId": "", 
         "threatScore": "" 
     }, 
     "events": [ 
         { 
             "parentPid": "", 
             "processMd5Hash": "", 
             "userName": "", 
             "processId": "", 
             "parentHash": "", 
             "longDescription": "", 
             "policyState": "", 
             "eventId": "", 
             "parentName": "", 
             "killChainStatus": "", 
             "eventTime": "", 
             "eventType": "", 
             "threatIndicators": [], 
             "commandLine": "", 
             "parentCommandLine": "", 
             "processHash": "", 
             "parentPPid": "", 
             "applicationPath": "", 
             "processPPid": "" 
         } 
     ], 
     "message": "Success", 
     "orgId": "" 
}

operation: Get Notifications

Input parameters

None.

Output

The output contains the following populated JSON schema:

     "eventId": "", 
     "policyAction": { 
         "reputation": "", 
         "sha256Hash": "", 
         "action": "", 
         "applicationName": "" 
     }, 
     "eventDescription": "", 
     "eventTime": "", 
     "deviceInfo": { 
         "deviceHostName": "", 
         "deviceType": "", 
         "deviceName": "", 
         "email": "", 
         "deviceId": "", 
         "groupName": "", 
         "internalIpAddress": "", 
         "externalIpAddress": "", 
         "targetPriorityType": "", 
         "targetPriorityCode": "", 
         "deviceVersion": "" 
     }, 
     "ruleName": "", 
     "type": "", 
     "url": "" 
}

operation: Create Policy

Input parameters

Parameter Description
Create Policy Choose the option for creating the policy in CarbonBlack Defense. You can choose from the following options: Using Parameters or Using File.
If you choose Using File, then you must specify the following parameters:
  • CyOPs Attachment IRI: Specify the FortiSOAR™ Attachment IRI that is used to access the file directly from the FortiSOAR™ `Attachments` module. This should be the policy file that you want to import into CarbonBlack Defense.  
If you choose Using Parameters, then you must specify the following parameters:
  • Description: Description of the policy that you want to create in CarbonBlack Defense.
  • Name: One-line name of the policy that you want to create in CarbonBlack Defense.
  • Priority Level: Priority that you want to set for the policy, which you want to create in CarbonBlack Defense. You can choose the priority of the policy between High, Medium, and Low from the Priority Level drop-down list.
  • Policy Details: JSON object that contains the policy details that you want to create in CarbonBlack Defense.
    Note: You can retrieve a policy using the "Get Policy By ID" operation from your instance to determine the allowable values for your instance. See the policy key from response.

Output

The output contains the following populated JSON schema:

     "policyId": "", 
     "message": "", 
     "success": "" 
}

operation: Get All Policies

Input parameters

None.

Output

The output contains the following populated JSON schema:

     "results": [ 
         { 
             "policy": { 
                 "avSettings": { 
                     "features": [ 
                         { 
                             "enabled": "", 
                             "name": "" 
                         } 
                     ], 
                     "apc": { 
                         "maxExeDelay": "", 
                         "enabled": "", 
                         "riskLevel": "", 
                         "maxFileSize": "" 
                     }, 
                     "onDemandScan": { 
                         "schedule": { 
                             "recoveryScanIfMissed": "", 
                             "days": "", 
                             "rangeHours": "", 
                             "startHour": "" 
                         }, 
                         "scanCdDvd": "", 
                         "scanUsb": "", 
                         "profile": "" 
                     }, 
                     "signatureUpdate": { 
                         "schedule": { 
                             "fullIntervalHours": "", 
                             "initialRandomDelayHours": "", 
                             "intervalHours": "" 
                         } 
                     }, 
                     "onAccessScan": { 
                         "profile": "" 
                     }, 
                     "updateServers": { 
                         "servers": [ 
                             { 
                                 "server": [], 
                                 "flags": "", 
                                 "regId": "" 
                             } 
                         ], 
                         "serversForOffSiteDevices": [] 
                     } 
                 }, 
                 "sensorSettings": [ 
                     { 
                         "value": "", 
                         "name": "" 
                     } 
                 ], 
                 "directoryActionRules": [], 
                 "id": "", 
                 "knownBadHashAutoDeleteDelayMs": "", 
                 "rules": [ 
                     { 
                         "operation": "", 
                         "required": "", 
                         "application": { 
                             "value": "", 
                             "type": "" 
                         }, 
                         "id": "", 
                         "action": "" 
                     } 
                 ] 
             }, 
             "latestRevision": "", 
             "name": "", 
             "priorityLevel": "", 
             "systemPolicy": "", 
             "description": "", 
             "id": "", 
             "version": "" 
         } 
     ], 
     "message": "", 
     "success": "" 
}

operation: Get Policy By ID

Input parameters

Parameter Description
Policy ID ID of the policy whose details you want to retrieve from CarbonBlack Defense.

Output

The output contains the following populated JSON schema:

     "policyInfo": { 
         "policy": { 
             "avSettings": { 
                 "features": [ 
                     { 
                         "enabled": "", 
                         "name": "" 
                     } 
                 ], 
                 "apc": { 
                     "maxExeDelay": "", 
                     "enabled": "", 
                     "riskLevel": "", 
                     "maxFileSize": "" 
                 }, 
                 "onDemandScan": { 
                     "schedule": { 
                         "recoveryScanIfMissed": "", 
                         "days": "", 
                         "rangeHours": "", 
                         "startHour": "" 
                     }, 
                     "scanCdDvd": "", 
                     "scanUsb": "", 
                     "profile": "" 
                 }, 
                 "signatureUpdate": { 
                     "schedule": { 
                         "fullIntervalHours": "", 
                         "initialRandomDelayHours": "", 
                         "intervalHours": "" 
                     } 
                 }, 
                 "onAccessScan": { 
                     "profile": "" 
                 }, 
                 "updateServers": { 
                     "servers": [ 
                         { 
                             "server": [], 
                             "flags": "", 
                             "regId": "" 
                         } 
                     ], 
                     "serversForOffSiteDevices": [] 
                 } 
             }, 
             "sensorSettings": [ 
                 { 
                     "value": "", 
                     "name": "" 
                 } 
             ], 
             "directoryActionRules": [], 
             "id": "", 
             "knownBadHashAutoDeleteDelayMs": "", 
             "rules": [] 
         }, 
         "latestRevision": "", 
         "name": "", 
         "priorityLevel": "", 
         "systemPolicy": "", 
         "description": "", 
         "id": "", 
         "version": "" 
     }, 
     "message": "", 
     "success": "" 
}

operation: Update Policy

Input parameters

Parameter Description
Policy ID ID of the policy that you want to update in CarbonBlack Defense.
Update Policy Choose the option for updating an existing policy in CarbonBlack Defense. You can choose from the following options: Using Parameters or Using File.
If you choose Using File, then you must specify the following parameters:
  • CyOPs Attachment IRI: Specify the FortiSOAR™ Attachment IRI that is used to access the file directly from the FortiSOAR™ `Attachments` module. This should be the policy file that you want to import into CarbonBlack Defense.  
If you choose Using Parameters, then you must specify the following parameters:
  • Description: Description of the policy that you want to update in CarbonBlack Defense.
  • Name: One-line name of the policy that you want to update in CarbonBlack Defense.
  • Priority Level: Priority that you want to set for the policy, which you want to update in CarbonBlack Defense. You can choose the priority of the policy between High, Medium, and Low from the Priority Level drop-down list.
  • Policy Details: JSON object that contains the policy details that you want to update in CarbonBlack Defense.

Output

The output contains the following populated JSON schema:

     "message": "", 
     "success": "" 
}

operation: Delete Policy

Input parameters

Parameter Description
Policy ID ID of the policy whose details you want to delete from CarbonBlack Defense.

Output

The output contains the following populated JSON schema:
{
     "message": "",
     "success": ""
}

operation: Add Rule To Policy

Input parameters

Parameter Description
Policy ID ID of an existing policy in CarbonBlack Defense to which you want to add a rule.
Rule Info Fields that you want to add to the existing policy in CarbonBlack Defense. You must add field information in the JSON format.

Output

The output contains the following populated JSON schema:

     "ruleId": "", 
     "message": "", 
     "success": "" 
}

operation: Update Rule in Policy

Input parameters

Parameter Description
Policy ID ID of an existing policy in CarbonBlack Defense in which you want to update a rule.
Rule ID ID of the rule that you want to update in CarbonBlack Defense.
Rule Info Fields that you want to update in the existing rule and policy in CarbonBlack Defense. You must add field information in the JSON format.

Output

The output contains the following populated JSON schema:
{
     "message": "",
     "success": ""
}

operation: Delete Rule from Policy

Input parameters

Parameter Description
Policy ID ID of an existing policy in CarbonBlack Defense from which you want to delete a rule.
Rule ID ID of the rule whose details you want to delete from CarbonBlack Defense.

Output

The output contains the following populated JSON schema:
{
     "message": "",
     "success": ""
}

operation: Execute Live Commands - File

Input parameters

Parameter Description
Device/Sensor ID ID of the device or Sensor used to establish the live response session.
Command to Execute Command that you want to execute on the remote endpoints. You can choose from the following options: List Directory, Get File, Put File, or Delete File.
If you choose List Directory, then you must specify the following parameters:
  • Directory Path: Filter specifying the directory path or listing.
If you choose Get File, then you must specify the following parameters:
  • File Path: Source path of the file that you want to retrieve.
If you choose Put File, then you must specify the following parameters:
  • Destination File Path: Destination Path of the file, i.e., the path where you want to save the file on CarbonBlack Defense. 
  • CyOPs Attachment IRI: Specify the FortiSOAR™ Attachment IRI that is used to access the file directly from the FortiSOAR™ `Attachments` module. This should be the file that you want to import into CarbonBlack Defense.  
If you choose Delete File, then you must specify the following parameters:
  • File Path: Source path of the file that you want to delete from CarbonBlack Defense.

Output

The output contains the following populated JSON schema based on the command you have selected.

For the List Directory command:

{
"result_code": "",
"result_desc": "",
"result_type": "",
"username": "",
"status": "",
"files": [
{
"alternate_name": "",
     "last_write_time": "",
"create_time": "",
"size": "",
"filename": "",
"last_access_time": "",
"attributes": [
]
}
],
"name": "",
"id": "",
"obj": {
"name": "",
"object": ""
},
"creation_time": "",
"completion_time": ""
 }

For the Get File command:

{
"@id": "",
"@type": "",
"type": "",
"name": "",
"modifyDate": "",
"file": {
"@id": "",
"size": "",
"file": {
"@type": ""
},
"filename": "",
"metadata": "",
"owners": [
],
"uploadDate": "",
"@type": "",
"mimeType": "",
"@context": ""
}
}

For the Put File command:

{
"completion_time": "",
"status": "",
"username": "",
"result_code": "",
"name": "",
"result_desc": "",
"creation_time": "",
"obj": {
"file_id": "",
"object": "",
"name": "",
"chunkNumber": ""
},
"id": "",
"file_id": "",
"result_type": ""
}

For the Delete File command:

{
"creation_time": "",
"id": "",
"result_code": "",
"status": "",
"result_desc": "",
"name": "",
"obj": {
"name": "",
"object": ""
},
"username": "",
"completion_time": "",
"result_type": ""
}

operation: Execute Live Commands - Process

Input parameters

Parameter Description
Device/Sensor ID ID of the device or Sensor used to establish the live response session.
Command to execute Command that you want to execute on the remote endpoints. You can choose from the following options: Create Process, List Process, Kill Process, or Memory Dump.
If you choose Create Process, then you must specify the following parameters:
  • Executable's Path: Path and command line of the executable.
  • Working Directory: (Optional) Working directory of the executable.
  • Output File: (Optional) Name and path of the file used to capture STDERR and STDOUT.
  • Wait to Complete Execution: Select this option, i.e., set it to True if you want to wait for the process to complete execution before reporting the result. By default, it is set to False.
No input is required for the List Process command.
If you choose Kill Process, then you must specify the following parameters:
  • Process ID: ID of the process you want to kill on CarbonBlack Defense.
If you choose Memory Dump, then you must specify the following parameters:
  • Location to Store the Memory Dump: Path to save the resulting memory dump on the endpoint.
  • Compress Resulting Memory Dump: Select this option i.e. set it to True, if you want to compress the resulting memory dump. By default, it is set to False.

Output

The output contains the following populated JSON schema based on the command you have selected.

For the Create Process command:

{
"result_code": "",
"status": "",
"result_type": "",
"pid": "",
"obj": {
"name": "",
"object": "",
"working_directory": "",
"wait": ""
},
"creation_time": "",
"completion_time": "",
"name": "",
"result_desc": "",
"username": "",
"id": "",
"return_code": ""
}

For the List Process command:

{
"result_code": "",
"result_desc": "",
"result_type": "",
"username": "null",
"processes": [
{
"command_line": "",
"path": "",
"sid": "",
"parent_create_time": "",
"username": "",
"create_time": "",
"pid": "",
"parent": ""
}
],
"status": "",
"name": "",
"id": "",
"obj": {
"name": ""
},
"creation_time": "",
"completion_time": ""
}

For the Kill Process command:

{
"result_code": "",
"result_desc": "",
"result_type": "",
"username": "",
"status": "",
"name": "",
"id": "",
"obj": {
"name": "",
"object": ""
},
"creation_time": "",
"completion_time": ""
}

For the Memory Dump command:

{
"result_code": "",
"result_desc": "",
"result_type": "",
"username": "",
"status": "",
"name": "",
"id": "",
"obj": {
"compress": "",
"object": ""
},
"creation_time": "",
"completion_time": "",
"return_code":"",
"compressing":"",
"complete":"",
"percentdone": "",
"dumping": ""
}

operation: Execute Live Commands - Registry

Input parameters

Parameter Description
Device/Sensor ID ID of the device or Sensor used to establish the live response session.
Command to execute Command that you want to execute on the remote endpoints.  You can choose from the following options: Create Key, Enumerate Key, Delete Key, Query Value, Set Value, or Delete Value.
If you choose Create Key, which is used to create a new registry, then you must specify the following parameters:
  • Key Path: Path where you want to create the registry key.
If you choose Enumerate Key, which is used to enumerate subkeys and values of the specified registry key, then you must specify the following parameters:
  • Key Path: Path of the registry key that you want to query.
If you choose Delete Key, which is used to delete a registry key, then you must specify the following parameters:
  • Key Path: Path from where you want to delete the registry key.
If you choose Query Value, which is used to return the associated value of the specified registry key, then you must specify the following parameters:
  • Key-Value Pair: Key-Value pair based on which you want to query the registry keys.
If you choose Set Value, which is used to set a registry value of the specified registry key, then you must specify the following parameters:
  • Key-Value Pair: Key-Value pair that you want to set for the registry keys.
  • Data to set for value
  • Value Type: Type of value to be set for the registry keys, such as REG_SZ, REG_DWORD, REG_QWORD, etc.
  • Overwrite: Specify whether to overwrite the value of the registry key if it already exists.
If you choose Delete Value, which is used to delete a registry value, then you must specify the following parameters:
  • Key Path: Path from where you want to delete the registry value.

Output

The output contains the following populated JSON schema based on the command you have selected.

For the Create Key command:

{
"creation_time": "",
"id": "",
"result_desc": "",
"result_code": "",
"completion_time": "",
"status": "",
"username": "",
"obj": {
"hive": "",
"key": "",
"object": "",
"name": ""
},
"name": "",
"result_type": ""
}
For the Enumerate Key command:
{
"username": "",
"id": "",
"result_code": "",
"status": "",
"obj": {
"hive": "",
"key": "",
"object": "",
"name": ""
},
"completion_time": "",
"sub_keys": [],
"values": [],
"creation_time": "",
"result_type": "",
"result_desc": "",
"name": ""
}

For the Delete Key command:

{
"creation_time": "",
"id": "",
"result_desc": "",
"result_code": "",
"completion_time": "",
"status": "",
"username": "",
"obj": {
"hive": "",
"key": "",
"object": "",
"name": ""
},
"name": "",
"result_type": ""
}

For the Query Value command:

{
"creation_time": "",
"id": "",
"result_desc": "",
"result_code": "",
"completion_time": "",
"status": "",
"username": "",
"value": {
"value_type": "",
"value_name": "",
"value_data": ""
},
"obj": {
"hive": "",
"key": "",
"value_name": "",
"object": "",
"name": ""
},
"name": "",
"result_type": ""
 }

For the Set Value command:

{
"creation_time": "",
"id": "",
"result_desc": "",
"result_code": "",
"completion_time": "",
"status": "",
"username": "",
"obj": {
"overwrite": "",
"hive": "",
"key": "",
"value_name": "",
"object": "",
"value_data": "",
"name": "",
"value_type": ""
},
"name": "",
"result_type": ""
 }

For the Delete Value command:

{
"creation_time": "",
"id": "",
"result_desc": "",
"result_code": "",
"completion_time": "",
"status": "",
"username": "",
"obj": {
"hive": "",
"key": "",
"value_name": "",
"object": "",
"name": ""
},
"name": "",
"result_type": ""
 }

Included playbooks

The Sample - CarbonBlack Defense - 2.0.0 playbook collection comes bundled with the CarbonBlack Defense connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the CarbonBlack Defense connector.

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 connector upgrade and delete.