Fortinet Document Library

Version:


Table of Contents

CarbonBlack Defense

1.0.1
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: 1.0.1

Authored By: Fortinet

Certified: No

Release Notes for version 1.0.1

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

  • Added the logo for the CarbonBlack Defense connector. 

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.

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.
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 from CarbonBlack Defense. search_device
Investigation
Get Device Status Retrieves the status and details for a device that you have specified by its device ID from CarbonBlack Defense. search_device
Investigation
Change Device Status Changes the status for a device that you have specified by its device ID on CarbonBlack Defense. update_device
Miscellaneous
Find Events Retrieves all events that match the input search criterion that you have specified from CarbonBlack Defense. search_event
Investigation
Find Event By ID Retrieves the details for an event that you have specified by its event ID from CarbonBlack Defense. search_event
Investigation
Find Processes Retrieves information for all processes that match the input search criterion that you have specified from CarbonBlack Defense. search_process
Investigation
Get Alert Details Retrieves details and all metadata, including a list of all the events associated with the alert, for an alert that you have specified by its alert ID from CarbonBlack Defense. get_alert
Investigation
Get Notifications Retrieves information about new notifications since the last check-in from CarbonBlack Defense. get_notification
Investigation
Create Policy Creates a new policy in CarbonBlack Defense. create_policy
Miscellaneous
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 that you have specified by its policy ID from CarbonBlack Defense. search_policy
Investigation
Update Policy Updates an existing policy with a new policy on CarbonBlack Defense. update_policy
Investigation
Delete Policy Deletes an existing policy from CarbonBlack Defense. delete_policy
Miscellaneous
Add Rule To Policy Adds a new rule to an existing policy on CarbonBlack Defense. update_policy
Investigation
Update Rule To Policy Updates an existing rule with a new rule in an existing policy on CarbonBlack Defense. update_policy
Investigation
Delete Rule From Policy Deletes an existing rule from an existing policy on CarbonBlack Defense. update_policy
Investigation

operation: Get Devices Status

Input parameters

Parameter Description
Hostname Filter on 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 Filter on the exact hostname. For example, hostName=WIN-IA9NQ1GN8OI will only return devices with the exact hostname WIN-IA9NQ1GN8OI but not a host named win-IA9NQ1GN8OI.
Owner Name Filter on owner name. This field is case-insensitive.
Owner Name Exact Filter on owner name. This field is case-sensitive.
IP Address Filter on devices with a given external or internal IP address.
Page Range This is for the paging functionality. You can specify the page range i.e range of return result that you want the CarbonBlack Defense Server to render. By default, this is set to 0 -10.

Output

The output contains the following populated JSON schema:
{
     "lastShutdownTime": "",
     "deviceOwnerId": "",
     "email": "",
     "avLastScanTime": "",
     "targetPriorityType": "",
     "deviceType": "",
     "avStatus": [],
     "createTime": "",
     "linuxKernelVersion": "",
     "activationCode": "",
     "policyName": "",
     "registeredTime": "",
     "scanLastCompleteTime": "",
     "testId": "",
     "organizationName": "",
     "quarantined": "",
     "policyId": "",
     "lastContact": "",
     "firstVirusActivityTime": "",
     "firstName": "",
     "name": "",
     "status": "",
     "osVersion": "",
     "lastReportedTime": "",
     "rootedBySensor": "",
     "deviceId": "",
     "lastResetTime": "",
     "sensorVersion": "",
     "sensorStates": [],
     "lastExternalIpAddress": "",
     "activationCodeExpiryTime": "",
     "passiveMode": "",
     "scanLastActionTime": "",
     "lastVirusActivityTime": "",
     "organizationId": "",
     "rootedByAnalytics": "",
     "lastLocation": "",
     "scanStatus": ""
}

operation: Get Device Status

Input parameters

Parameter Description
Device ID The ID of the device of which details need to be fetched.

Output

The output contains the following populated JSON schema:
{
     "lastShutdownTime": "",
     "deviceOwnerId": "",
     "email": "",
     "avLastScanTime": "",
     "targetPriorityType": "",
     "deviceType": "",
     "avStatus": [],
     "createTime": "",
     "linuxKernelVersion": "",
     "activationCode": "",
     "policyName": "",
     "registeredTime": "",
     "scanLastCompleteTime": "",
     "testId": "",
     "organizationName": "",
     "quarantined": "",
     "policyId": "",
     "lastContact": "",
     "firstVirusActivityTime": "",
     "firstName": "",
     "name": "",
     "status": "",
     "osVersion": "",
     "lastReportedTime": "",
     "rootedBySensor": "",
     "deviceId": "",
     "lastResetTime": "",
     "sensorVersion": "",
     "sensorStates": [],
     "lastExternalIpAddress": "",
     "activationCodeExpiryTime": "",
     "passiveMode": "",
     "scanLastActionTime": "",
     "lastVirusActivityTime": "",
     "organizationId": "",
     "rootedByAnalytics": "",
     "lastLocation": "",
     "scanStatus": ""
}

operation: Change Device Status

Input parameters

Parameter Description
Device ID The ID of the device of which details need to be fetched.
Policy ID The requested security policy can be indicated as a policy ID.
Policy Name OR The requested security policy can be indicated as a policy name.

Output

The output contains the following populated JSON schema:
{
     "lastShutdownTime": "",
     "deviceOwnerId": "",
     "email": "",
     "avLastScanTime": "",
     "targetPriorityType": "",
     "deviceType": "",
     "avStatus": [],
     "createTime": "",
     "linuxKernelVersion": "",
     "activationCode": "",
     "policyName": "",
     "registeredTime": "",
     "scanLastCompleteTime": "",
     "testId": "",
     "organizationName": "",
     "quarantined": "",
     "policyId": "",
     "lastContact": "",
     "firstVirusActivityTime": "",
     "firstName": "",
     "name": "",
     "status": "",
     "osVersion": "",
     "lastReportedTime": "",
     "rootedBySensor": "",
     "deviceId": "",
     "lastResetTime": "",
     "sensorVersion": "",
     "sensorStates": [],
     "lastExternalIpAddress": "",
     "activationCodeExpiryTime": "",
     "passiveMode": "",
     "scanLastActionTime": "",
     "lastVirusActivityTime": "",
     "organizationId": "",
     "rootedByAnalytics": "",
     "lastLocation": "",
     "scanStatus": ""
}

operation: Find Events

Input parameters

Parameter Description
Hostname Filter on 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 Filter on the exact hostname. For example, hostName=WIN-IA9NQ1GN8OI will only return devices with the exact hostname WIN-IA9NQ1GN8OI but not a host named win-IA9NQ1GN8OI.
Owner Name Filter on owner name. This field is case-insensitive.
Owner Name Exact Filter on owner name. This field is case-sensitive.
IP Address Filter on devices with a given external or internal IP address.
Filehash Filter on events generated by a process with the given SHA-256 hash. Note that this hash must be lowercase.
Application Name Filter on events generated by a process with the given application name (for example, googleupdate.exe. Note that this name must be lowercase)
Event Type Filter on events with a given event type. Select the event from the drop-down list.
Search Window Filter on events generated within a given relative time frame. Note that the default is one day if a search Window is not specified. Note that events may not be available past 30 days due to retention policies. Example values are: 4d for the past four days 2w for the past two weeks
Page Range This is for the paging functionality. You can specify the page range i.e range of return result that you want the CarbonBlack Defense Server to render. By default, this is set to 0 -10.

Output

The output contains the following populated JSON schema:
{
     "deviceSecurityEventCode": "",
     "shortDescription": "",
     "eventTime": "",
     "targetHash": {
         "virusName": "",
         "sha256Hash": "",
         "applicationPath": "",
         "md5Hash": "",
         "effectiveReputation": "",
         "virusSubCategory": "",
         "reputationProperty": "",
         "applicationName": "",
         "virusCategory": "",
         "effectiveReputationSource": ""
     },
     "longDescription": "",
     "createTime": "",
     "registryValue": "",
     "eventType": "",
     "securityEventCode": "",
     "netFlow": {
         "destPort": "",
         "peerLocation": "",
         "peerIpAddress": "",
         "destAddress": "",
         "service": "",
         "sourceAddress": "",
         "peerIpV4Address": "",
         "peerSiteReputation": "",
         "peerFqdn": "",
         "sourcePort": ""
     },
     "threatIndicators": [],
     "killChainStatus": "",
     "threatScore": "",
     "syslogLevel": "",
     "deviceDetails": {
         "groupName": "",
         "email": "",
         "targetPriorityCode": "",
         "targetPriorityType": "",
         "deviceType": "",
         "deviceId": "",
         "deviceHostName": "",
         "deviceIpAddress": "",
         "deviceVersion": "",
         "deviceLocation": {
             "metroCode": "",
             "dmaCode": "",
             "areaCode": "",
             "postalCode": "",
             "countryCode": "",
             "region": "",
             "latitude": "",
             "city": "",
             "countryName": "",
             "longitude": ""
         },
         "deviceIpV4Address": "",
         "agentLocation": "",
         "deviceOwnerName": "",
         "deviceName": ""
     },
     "processDetails": {
         "targetPid": "",
         "processId": "",
         "parentPid": "",
         "milisSinceProcessStart": "",
         "targetPrivatePid": "",
         "parentCommandLine": "",
         "parentName": "",
         "userName": "",
         "fullUserName": "",
         "interpreterName": "",
         "privatePid": "",
         "name": "",
         "targetName": "",
         "parentPrivatePid": "",
         "interpreterHash": "",
         "targetCommandLine": ""
     },
     "eventId": "",
     "orgDetails": {
         "organizationId": "",
         "organizationName": "",
         "organizationType": ""
     },
     "processHash": {
         "virusName": "",
         "sha256Hash": "",
         "applicationPath": "",
         "md5Hash": "",
         "effectiveReputation": "",
         "virusSubCategory": "",
         "reputationProperty": "",
         "applicationName": "",
         "virusCategory": "",
         "effectiveReputationSource": ""
     },
     "parentHash": {
         "virusName": "",
         "sha256Hash": "",
         "applicationPath": "",
         "md5Hash": "",
         "effectiveReputation": "",
         "virusSubCategory": "",
         "reputationProperty": "",
         "applicationName": "",
         "virusCategory": "",
         "effectiveReputationSource": ""
     }
}

operation: Find Event By ID

Input parameters

Parameter Description
Event ID The ID of the event that needs to be searched.

Output

The output contains the following populated JSON schema:
{
     "deviceSecurityEventCode": "",
     "shortDescription": "",
     "eventTime": "",
     "targetHash": {
         "virusName": "",
         "sha256Hash": "",
         "applicationPath": "",
         "md5Hash": "",
         "effectiveReputation": "",
         "virusSubCategory": "",
         "reputationProperty": "",
         "applicationName": "",
         "virusCategory": "",
         "effectiveReputationSource": ""
     },
     "longDescription": "",
     "createTime": "",
     "registryValue": "",
     "eventType": "",
     "securityEventCode": "",
     "netFlow": {
         "destPort": "",
         "peerLocation": "",
         "peerIpAddress": "",
         "destAddress": "",
         "service": "",
         "sourceAddress": "",
         "peerIpV4Address": "",
         "peerSiteReputation": "",
         "peerFqdn": "",
         "sourcePort": ""
     },
     "threatIndicators": [],
     "killChainStatus": "",
     "threatScore": "",
     "syslogLevel": "",
     "deviceDetails": {
         "groupName": "",
         "email": "",
         "targetPriorityCode": "",
         "targetPriorityType": "",
         "deviceType": "",
         "deviceId": "",
         "deviceHostName": "",
         "deviceIpAddress": "",
         "deviceVersion": "",
         "deviceLocation": {
             "metroCode": "",
             "dmaCode": "",
             "areaCode": "",
             "postalCode": "",
             "countryCode": "",
             "region": "",
             "latitude": "",
             "city": "",
             "countryName": "",
             "longitude": ""
         },
         "deviceIpV4Address": "",
         "agentLocation": "",
         "deviceOwnerName": "",
         "deviceName": ""
     },
     "processDetails": {
         "targetPid": "",
         "processId": "",
         "parentPid": "",
         "milisSinceProcessStart": "",
         "targetPrivatePid": "",
         "parentCommandLine": "",
         "parentName": "",
         "userName": "",
         "fullUserName": "",
         "interpreterName": "",
         "privatePid": "",
         "name": "",
         "targetName": "",
         "parentPrivatePid": "",
         "interpreterHash": "",
         "targetCommandLine": ""
     },
     "eventId": "",
     "orgDetails": {
         "organizationId": "",
         "organizationName": "",
         "organizationType": ""
     },
     "processHash": {
         "virusName": "",
         "sha256Hash": "",
         "applicationPath": "",
         "md5Hash": "",
         "effectiveReputation": "",
         "virusSubCategory": "",
         "reputationProperty": "",
         "applicationName": "",
         "virusCategory": "",
         "effectiveReputationSource": ""
     },
     "parentHash": {
         "virusName": "",
         "sha256Hash": "",
         "applicationPath": "",
         "md5Hash": "",
         "effectiveReputation": "",
         "virusSubCategory": "",
         "reputationProperty": "",
         "applicationName": "",
         "virusCategory": "",
         "effectiveReputationSource": ""
     }
}

operation: Find Processes

Input parameters

Parameter Description
Hostname Exact Filter on the exact hostname. For example, hostName=WIN-IA9NQ1GN8OI will only return devices with the exact hostname WIN-IA9NQ1GN8OI but not a host named win-IA9NQ1GN8OI.
Owner Name Filter on owner name. This field is case-insensitive.
Owner Name Exact Filter on owner name. This field is case-sensitive.
IP Address Filter on devices with a given external or internal IP address.
Search Window Filter on events generated within a given relative time frame. Note that the default is one day if a search Window is not specified. Note that events may not be available past 30 days due to retention policies. Example values are: 4d for the past four days and 2w for the past two weeks
Page Range This is for the paging functionality. You can specify the page range i.e range of return result that you want the CarbonBlack Defense Server to render. By default, this is set to 0 -10.

Output

The output contains the following populated JSON schema:
{
     "sha256Hash": "",
     "applicationPath": "",
     "processId": "",
     "numEvents": "",
     "applicationName": "",
     "privatePid": ""
}

operation: Get Alert Details

Input parameters

Parameter Description
Alert ID The ID of the alert of which details needs to be fetched.

Output

The output contains the following populated JSON schema:


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

operation: Get Notifications

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "url": "",
     "type": "",
     "eventDescription": "",
     "eventTime": "",
     "policyAction": {
         "sha256Hash": "",
         "applicationName": "",
         "action": "",
         "reputation": ""
     },
     "eventId": "",
     "deviceInfo": {
         "groupName": "",
         "internalIpAddress": "",
         "email": "",
         "deviceVersion": "",
         "deviceName": "",
         "targetPriorityType": "",
         "deviceType": "",
         "deviceId": "",
         "deviceHostName": "",
         "externalIpAddress": "",
         "targetPriorityCode": ""
     },
     "ruleName": ""
}

operation: Create Policy

Input parameters

Parameter Description
Description A description of the policy.
Name A one-line name for the policy.
Priority Level Priority of the policy. You can choose the priority of the policy between High, Medium, and Low from the Priority drop-down list.
Policy The JSON object containing the policy details.

Output

The output contains the following populated JSON schema:
{
     "policyId": ""
}

operation: Get All Policies

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "description": "",
     "systemPolicy": "",
     "policy": {
         "avSettings": {
             "apc": {
                 "maxExeDelay": "",
                 "maxFileSize": "",
                 "riskLevel": "",
                 "enabled": ""
             },
             "updateServers": {
                 "servers": [
                     {
                         "server": []
                     }
                 ],
                 "serversForOffSiteDevices": []
             },
             "onDemandScan": {
                 "scanUsb": "",
                 "profile": "",
                 "scanCdDvd": ""
             },
             "onAccessScan": {
                 "profile": ""
             },
             "features": [
                 {
                     "enabled": "",
                     "name": ""
                 }
             ],
             "signatureUpdate": {
                 "schedule": {
                     "intervalHours": "",
                     "initialRandomDelayHours": "",
                     "fullIntervalHours": ""
                 }
             }
         },
         "id": "",
         "rules": [
             {
                 "operation": "",
                 "required": "",
                 "id": "",
                 "action": "",
                 "application": {
                     "type": "",
                     "value": ""
                 }
             }
         ]
     },
     "name": "",
     "latestRevision": "",
     "id": "",
     "priorityLevel": "",
     "version": ""
}

operation: Get Policy By ID

Input parameters

Parameter Description
Policy ID The ID of the Policy of which details need to be fetched.

Output

The output contains the following populated JSON schema:
{
     "description": "",
     "systemPolicy": "",
     "policy": {
         "avSettings": {
             "apc": {
                 "maxExeDelay": "",
                 "maxFileSize": "",
                 "riskLevel": "",
                 "enabled": ""
             },
             "updateServers": {
                 "servers": [
                     {
                         "server": []
                     }
                 ],
                 "serversForOffSiteDevices": []
             },
             "onDemandScan": {
                 "scanUsb": "",
                 "profile": "",
                 "scanCdDvd": ""
             },
             "onAccessScan": {
                 "profile": ""
             },
             "features": [
                 {
                     "enabled": "",
                     "name": ""
                 }
             ],
             "signatureUpdate": {
                 "schedule": {
                     "intervalHours": "",
                     "initialRandomDelayHours": "",
                     "fullIntervalHours": ""
                 }
             }
         },
         "id": "",
         "rules": [
             {
                 "operation": "",
                 "required": "",
                 "id": "",
                 "action": "",
                 "application": {
                     "type": "",
                     "value": ""
                 }
             }
         ]
     },
     "name": "",
     "latestRevision": "",
     "id": "",
     "priorityLevel": "",
     "version": ""
}

operation: Update Policy

Input parameters

Parameter Description
Policy ID The ID of the policy to be updated.
Description A description of the policy.
Name A one-line name for the policy.
Priority Level The priority score associated with sensors assigned to this policy.
Policy The JSON object containing the policy details.

Output

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

operation: Delete Policy

Input parameters

Parameter Description
Policy ID The ID of the Policy of which details need to be deleted.

Output

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

operation: Add Rule To Policy

Input parameters

Parameter Description
Policy ID The ID of the Policy of which details need to be deleted.
Rule Info Specify fields to be added in Policy in JSON format.

Output

The output contains the following populated JSON schema:
{
     "ruleId": ""
}

operation: Update Rule in Policy

Input parameters

Parameter Description
Policy ID The ID of the Policy of which details need to be deleted.
Rule ID The ID of the rule of which details need to be deleted.
Rule Info Specify fields to be updated in Policy in JSON format.

Output

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

operation: Delete Rule from Policy

Input parameters

Parameter Description
Policy ID The ID of the Policy of which details need to be deleted.
Rule ID The ID of the rule of which details need to be deleted.

Output

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

Included playbooks

The Sample - CarbonBlack Defense - 1.0.1 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
  • 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: 1.0.1

Authored By: Fortinet

Certified: No

Release Notes for version 1.0.1

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

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.

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.
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 from CarbonBlack Defense. search_device
Investigation
Get Device Status Retrieves the status and details for a device that you have specified by its device ID from CarbonBlack Defense. search_device
Investigation
Change Device Status Changes the status for a device that you have specified by its device ID on CarbonBlack Defense. update_device
Miscellaneous
Find Events Retrieves all events that match the input search criterion that you have specified from CarbonBlack Defense. search_event
Investigation
Find Event By ID Retrieves the details for an event that you have specified by its event ID from CarbonBlack Defense. search_event
Investigation
Find Processes Retrieves information for all processes that match the input search criterion that you have specified from CarbonBlack Defense. search_process
Investigation
Get Alert Details Retrieves details and all metadata, including a list of all the events associated with the alert, for an alert that you have specified by its alert ID from CarbonBlack Defense. get_alert
Investigation
Get Notifications Retrieves information about new notifications since the last check-in from CarbonBlack Defense. get_notification
Investigation
Create Policy Creates a new policy in CarbonBlack Defense. create_policy
Miscellaneous
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 that you have specified by its policy ID from CarbonBlack Defense. search_policy
Investigation
Update Policy Updates an existing policy with a new policy on CarbonBlack Defense. update_policy
Investigation
Delete Policy Deletes an existing policy from CarbonBlack Defense. delete_policy
Miscellaneous
Add Rule To Policy Adds a new rule to an existing policy on CarbonBlack Defense. update_policy
Investigation
Update Rule To Policy Updates an existing rule with a new rule in an existing policy on CarbonBlack Defense. update_policy
Investigation
Delete Rule From Policy Deletes an existing rule from an existing policy on CarbonBlack Defense. update_policy
Investigation

operation: Get Devices Status

Input parameters

Parameter Description
Hostname Filter on 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 Filter on the exact hostname. For example, hostName=WIN-IA9NQ1GN8OI will only return devices with the exact hostname WIN-IA9NQ1GN8OI but not a host named win-IA9NQ1GN8OI.
Owner Name Filter on owner name. This field is case-insensitive.
Owner Name Exact Filter on owner name. This field is case-sensitive.
IP Address Filter on devices with a given external or internal IP address.
Page Range This is for the paging functionality. You can specify the page range i.e range of return result that you want the CarbonBlack Defense Server to render. By default, this is set to 0 -10.

Output

The output contains the following populated JSON schema:
{
     "lastShutdownTime": "",
     "deviceOwnerId": "",
     "email": "",
     "avLastScanTime": "",
     "targetPriorityType": "",
     "deviceType": "",
     "avStatus": [],
     "createTime": "",
     "linuxKernelVersion": "",
     "activationCode": "",
     "policyName": "",
     "registeredTime": "",
     "scanLastCompleteTime": "",
     "testId": "",
     "organizationName": "",
     "quarantined": "",
     "policyId": "",
     "lastContact": "",
     "firstVirusActivityTime": "",
     "firstName": "",
     "name": "",
     "status": "",
     "osVersion": "",
     "lastReportedTime": "",
     "rootedBySensor": "",
     "deviceId": "",
     "lastResetTime": "",
     "sensorVersion": "",
     "sensorStates": [],
     "lastExternalIpAddress": "",
     "activationCodeExpiryTime": "",
     "passiveMode": "",
     "scanLastActionTime": "",
     "lastVirusActivityTime": "",
     "organizationId": "",
     "rootedByAnalytics": "",
     "lastLocation": "",
     "scanStatus": ""
}

operation: Get Device Status

Input parameters

Parameter Description
Device ID The ID of the device of which details need to be fetched.

Output

The output contains the following populated JSON schema:
{
     "lastShutdownTime": "",
     "deviceOwnerId": "",
     "email": "",
     "avLastScanTime": "",
     "targetPriorityType": "",
     "deviceType": "",
     "avStatus": [],
     "createTime": "",
     "linuxKernelVersion": "",
     "activationCode": "",
     "policyName": "",
     "registeredTime": "",
     "scanLastCompleteTime": "",
     "testId": "",
     "organizationName": "",
     "quarantined": "",
     "policyId": "",
     "lastContact": "",
     "firstVirusActivityTime": "",
     "firstName": "",
     "name": "",
     "status": "",
     "osVersion": "",
     "lastReportedTime": "",
     "rootedBySensor": "",
     "deviceId": "",
     "lastResetTime": "",
     "sensorVersion": "",
     "sensorStates": [],
     "lastExternalIpAddress": "",
     "activationCodeExpiryTime": "",
     "passiveMode": "",
     "scanLastActionTime": "",
     "lastVirusActivityTime": "",
     "organizationId": "",
     "rootedByAnalytics": "",
     "lastLocation": "",
     "scanStatus": ""
}

operation: Change Device Status

Input parameters

Parameter Description
Device ID The ID of the device of which details need to be fetched.
Policy ID The requested security policy can be indicated as a policy ID.
Policy Name OR The requested security policy can be indicated as a policy name.

Output

The output contains the following populated JSON schema:
{
     "lastShutdownTime": "",
     "deviceOwnerId": "",
     "email": "",
     "avLastScanTime": "",
     "targetPriorityType": "",
     "deviceType": "",
     "avStatus": [],
     "createTime": "",
     "linuxKernelVersion": "",
     "activationCode": "",
     "policyName": "",
     "registeredTime": "",
     "scanLastCompleteTime": "",
     "testId": "",
     "organizationName": "",
     "quarantined": "",
     "policyId": "",
     "lastContact": "",
     "firstVirusActivityTime": "",
     "firstName": "",
     "name": "",
     "status": "",
     "osVersion": "",
     "lastReportedTime": "",
     "rootedBySensor": "",
     "deviceId": "",
     "lastResetTime": "",
     "sensorVersion": "",
     "sensorStates": [],
     "lastExternalIpAddress": "",
     "activationCodeExpiryTime": "",
     "passiveMode": "",
     "scanLastActionTime": "",
     "lastVirusActivityTime": "",
     "organizationId": "",
     "rootedByAnalytics": "",
     "lastLocation": "",
     "scanStatus": ""
}

operation: Find Events

Input parameters

Parameter Description
Hostname Filter on 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 Filter on the exact hostname. For example, hostName=WIN-IA9NQ1GN8OI will only return devices with the exact hostname WIN-IA9NQ1GN8OI but not a host named win-IA9NQ1GN8OI.
Owner Name Filter on owner name. This field is case-insensitive.
Owner Name Exact Filter on owner name. This field is case-sensitive.
IP Address Filter on devices with a given external or internal IP address.
Filehash Filter on events generated by a process with the given SHA-256 hash. Note that this hash must be lowercase.
Application Name Filter on events generated by a process with the given application name (for example, googleupdate.exe. Note that this name must be lowercase)
Event Type Filter on events with a given event type. Select the event from the drop-down list.
Search Window Filter on events generated within a given relative time frame. Note that the default is one day if a search Window is not specified. Note that events may not be available past 30 days due to retention policies. Example values are: 4d for the past four days 2w for the past two weeks
Page Range This is for the paging functionality. You can specify the page range i.e range of return result that you want the CarbonBlack Defense Server to render. By default, this is set to 0 -10.

Output

The output contains the following populated JSON schema:
{
     "deviceSecurityEventCode": "",
     "shortDescription": "",
     "eventTime": "",
     "targetHash": {
         "virusName": "",
         "sha256Hash": "",
         "applicationPath": "",
         "md5Hash": "",
         "effectiveReputation": "",
         "virusSubCategory": "",
         "reputationProperty": "",
         "applicationName": "",
         "virusCategory": "",
         "effectiveReputationSource": ""
     },
     "longDescription": "",
     "createTime": "",
     "registryValue": "",
     "eventType": "",
     "securityEventCode": "",
     "netFlow": {
         "destPort": "",
         "peerLocation": "",
         "peerIpAddress": "",
         "destAddress": "",
         "service": "",
         "sourceAddress": "",
         "peerIpV4Address": "",
         "peerSiteReputation": "",
         "peerFqdn": "",
         "sourcePort": ""
     },
     "threatIndicators": [],
     "killChainStatus": "",
     "threatScore": "",
     "syslogLevel": "",
     "deviceDetails": {
         "groupName": "",
         "email": "",
         "targetPriorityCode": "",
         "targetPriorityType": "",
         "deviceType": "",
         "deviceId": "",
         "deviceHostName": "",
         "deviceIpAddress": "",
         "deviceVersion": "",
         "deviceLocation": {
             "metroCode": "",
             "dmaCode": "",
             "areaCode": "",
             "postalCode": "",
             "countryCode": "",
             "region": "",
             "latitude": "",
             "city": "",
             "countryName": "",
             "longitude": ""
         },
         "deviceIpV4Address": "",
         "agentLocation": "",
         "deviceOwnerName": "",
         "deviceName": ""
     },
     "processDetails": {
         "targetPid": "",
         "processId": "",
         "parentPid": "",
         "milisSinceProcessStart": "",
         "targetPrivatePid": "",
         "parentCommandLine": "",
         "parentName": "",
         "userName": "",
         "fullUserName": "",
         "interpreterName": "",
         "privatePid": "",
         "name": "",
         "targetName": "",
         "parentPrivatePid": "",
         "interpreterHash": "",
         "targetCommandLine": ""
     },
     "eventId": "",
     "orgDetails": {
         "organizationId": "",
         "organizationName": "",
         "organizationType": ""
     },
     "processHash": {
         "virusName": "",
         "sha256Hash": "",
         "applicationPath": "",
         "md5Hash": "",
         "effectiveReputation": "",
         "virusSubCategory": "",
         "reputationProperty": "",
         "applicationName": "",
         "virusCategory": "",
         "effectiveReputationSource": ""
     },
     "parentHash": {
         "virusName": "",
         "sha256Hash": "",
         "applicationPath": "",
         "md5Hash": "",
         "effectiveReputation": "",
         "virusSubCategory": "",
         "reputationProperty": "",
         "applicationName": "",
         "virusCategory": "",
         "effectiveReputationSource": ""
     }
}

operation: Find Event By ID

Input parameters

Parameter Description
Event ID The ID of the event that needs to be searched.

Output

The output contains the following populated JSON schema:
{
     "deviceSecurityEventCode": "",
     "shortDescription": "",
     "eventTime": "",
     "targetHash": {
         "virusName": "",
         "sha256Hash": "",
         "applicationPath": "",
         "md5Hash": "",
         "effectiveReputation": "",
         "virusSubCategory": "",
         "reputationProperty": "",
         "applicationName": "",
         "virusCategory": "",
         "effectiveReputationSource": ""
     },
     "longDescription": "",
     "createTime": "",
     "registryValue": "",
     "eventType": "",
     "securityEventCode": "",
     "netFlow": {
         "destPort": "",
         "peerLocation": "",
         "peerIpAddress": "",
         "destAddress": "",
         "service": "",
         "sourceAddress": "",
         "peerIpV4Address": "",
         "peerSiteReputation": "",
         "peerFqdn": "",
         "sourcePort": ""
     },
     "threatIndicators": [],
     "killChainStatus": "",
     "threatScore": "",
     "syslogLevel": "",
     "deviceDetails": {
         "groupName": "",
         "email": "",
         "targetPriorityCode": "",
         "targetPriorityType": "",
         "deviceType": "",
         "deviceId": "",
         "deviceHostName": "",
         "deviceIpAddress": "",
         "deviceVersion": "",
         "deviceLocation": {
             "metroCode": "",
             "dmaCode": "",
             "areaCode": "",
             "postalCode": "",
             "countryCode": "",
             "region": "",
             "latitude": "",
             "city": "",
             "countryName": "",
             "longitude": ""
         },
         "deviceIpV4Address": "",
         "agentLocation": "",
         "deviceOwnerName": "",
         "deviceName": ""
     },
     "processDetails": {
         "targetPid": "",
         "processId": "",
         "parentPid": "",
         "milisSinceProcessStart": "",
         "targetPrivatePid": "",
         "parentCommandLine": "",
         "parentName": "",
         "userName": "",
         "fullUserName": "",
         "interpreterName": "",
         "privatePid": "",
         "name": "",
         "targetName": "",
         "parentPrivatePid": "",
         "interpreterHash": "",
         "targetCommandLine": ""
     },
     "eventId": "",
     "orgDetails": {
         "organizationId": "",
         "organizationName": "",
         "organizationType": ""
     },
     "processHash": {
         "virusName": "",
         "sha256Hash": "",
         "applicationPath": "",
         "md5Hash": "",
         "effectiveReputation": "",
         "virusSubCategory": "",
         "reputationProperty": "",
         "applicationName": "",
         "virusCategory": "",
         "effectiveReputationSource": ""
     },
     "parentHash": {
         "virusName": "",
         "sha256Hash": "",
         "applicationPath": "",
         "md5Hash": "",
         "effectiveReputation": "",
         "virusSubCategory": "",
         "reputationProperty": "",
         "applicationName": "",
         "virusCategory": "",
         "effectiveReputationSource": ""
     }
}

operation: Find Processes

Input parameters

Parameter Description
Hostname Exact Filter on the exact hostname. For example, hostName=WIN-IA9NQ1GN8OI will only return devices with the exact hostname WIN-IA9NQ1GN8OI but not a host named win-IA9NQ1GN8OI.
Owner Name Filter on owner name. This field is case-insensitive.
Owner Name Exact Filter on owner name. This field is case-sensitive.
IP Address Filter on devices with a given external or internal IP address.
Search Window Filter on events generated within a given relative time frame. Note that the default is one day if a search Window is not specified. Note that events may not be available past 30 days due to retention policies. Example values are: 4d for the past four days and 2w for the past two weeks
Page Range This is for the paging functionality. You can specify the page range i.e range of return result that you want the CarbonBlack Defense Server to render. By default, this is set to 0 -10.

Output

The output contains the following populated JSON schema:
{
     "sha256Hash": "",
     "applicationPath": "",
     "processId": "",
     "numEvents": "",
     "applicationName": "",
     "privatePid": ""
}

operation: Get Alert Details

Input parameters

Parameter Description
Alert ID The ID of the alert of which details needs to be fetched.

Output

The output contains the following populated JSON schema:


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

operation: Get Notifications

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "url": "",
     "type": "",
     "eventDescription": "",
     "eventTime": "",
     "policyAction": {
         "sha256Hash": "",
         "applicationName": "",
         "action": "",
         "reputation": ""
     },
     "eventId": "",
     "deviceInfo": {
         "groupName": "",
         "internalIpAddress": "",
         "email": "",
         "deviceVersion": "",
         "deviceName": "",
         "targetPriorityType": "",
         "deviceType": "",
         "deviceId": "",
         "deviceHostName": "",
         "externalIpAddress": "",
         "targetPriorityCode": ""
     },
     "ruleName": ""
}

operation: Create Policy

Input parameters

Parameter Description
Description A description of the policy.
Name A one-line name for the policy.
Priority Level Priority of the policy. You can choose the priority of the policy between High, Medium, and Low from the Priority drop-down list.
Policy The JSON object containing the policy details.

Output

The output contains the following populated JSON schema:
{
     "policyId": ""
}

operation: Get All Policies

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "description": "",
     "systemPolicy": "",
     "policy": {
         "avSettings": {
             "apc": {
                 "maxExeDelay": "",
                 "maxFileSize": "",
                 "riskLevel": "",
                 "enabled": ""
             },
             "updateServers": {
                 "servers": [
                     {
                         "server": []
                     }
                 ],
                 "serversForOffSiteDevices": []
             },
             "onDemandScan": {
                 "scanUsb": "",
                 "profile": "",
                 "scanCdDvd": ""
             },
             "onAccessScan": {
                 "profile": ""
             },
             "features": [
                 {
                     "enabled": "",
                     "name": ""
                 }
             ],
             "signatureUpdate": {
                 "schedule": {
                     "intervalHours": "",
                     "initialRandomDelayHours": "",
                     "fullIntervalHours": ""
                 }
             }
         },
         "id": "",
         "rules": [
             {
                 "operation": "",
                 "required": "",
                 "id": "",
                 "action": "",
                 "application": {
                     "type": "",
                     "value": ""
                 }
             }
         ]
     },
     "name": "",
     "latestRevision": "",
     "id": "",
     "priorityLevel": "",
     "version": ""
}

operation: Get Policy By ID

Input parameters

Parameter Description
Policy ID The ID of the Policy of which details need to be fetched.

Output

The output contains the following populated JSON schema:
{
     "description": "",
     "systemPolicy": "",
     "policy": {
         "avSettings": {
             "apc": {
                 "maxExeDelay": "",
                 "maxFileSize": "",
                 "riskLevel": "",
                 "enabled": ""
             },
             "updateServers": {
                 "servers": [
                     {
                         "server": []
                     }
                 ],
                 "serversForOffSiteDevices": []
             },
             "onDemandScan": {
                 "scanUsb": "",
                 "profile": "",
                 "scanCdDvd": ""
             },
             "onAccessScan": {
                 "profile": ""
             },
             "features": [
                 {
                     "enabled": "",
                     "name": ""
                 }
             ],
             "signatureUpdate": {
                 "schedule": {
                     "intervalHours": "",
                     "initialRandomDelayHours": "",
                     "fullIntervalHours": ""
                 }
             }
         },
         "id": "",
         "rules": [
             {
                 "operation": "",
                 "required": "",
                 "id": "",
                 "action": "",
                 "application": {
                     "type": "",
                     "value": ""
                 }
             }
         ]
     },
     "name": "",
     "latestRevision": "",
     "id": "",
     "priorityLevel": "",
     "version": ""
}

operation: Update Policy

Input parameters

Parameter Description
Policy ID The ID of the policy to be updated.
Description A description of the policy.
Name A one-line name for the policy.
Priority Level The priority score associated with sensors assigned to this policy.
Policy The JSON object containing the policy details.

Output

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

operation: Delete Policy

Input parameters

Parameter Description
Policy ID The ID of the Policy of which details need to be deleted.

Output

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

operation: Add Rule To Policy

Input parameters

Parameter Description
Policy ID The ID of the Policy of which details need to be deleted.
Rule Info Specify fields to be added in Policy in JSON format.

Output

The output contains the following populated JSON schema:
{
     "ruleId": ""
}

operation: Update Rule in Policy

Input parameters

Parameter Description
Policy ID The ID of the Policy of which details need to be deleted.
Rule ID The ID of the rule of which details need to be deleted.
Rule Info Specify fields to be updated in Policy in JSON format.

Output

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

operation: Delete Rule from Policy

Input parameters

Parameter Description
Policy ID The ID of the Policy of which details need to be deleted.
Rule ID The ID of the rule of which details need to be deleted.

Output

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

Included playbooks

The Sample - CarbonBlack Defense - 1.0.1 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.