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.
Connector Version: 2.0.0
Authored By: Fortinet
FortiSOAR™ Version Tested on: 4.12.1-253
Certified: Yes
Following enhancements have been made to the CarbonBlack Defense connector in version 2.0.0:
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.
For the procedure to configure a connector, click here.
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. |
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 |
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. |
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": ""
}
Parameter | Description |
---|---|
Device ID | ID of the device whose details and status you want to retrieve from CarbonBlack Defense. |
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": ""
}
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:
|
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": ""
}
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. |
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": ""
}
Parameter | Description |
---|---|
Event ID | ID of the event whose details you want to retrieve from CarbonBlack Defense. |
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": ""
}
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. |
The output contains the following populated JSON schema:
{
"totalResults": "",
"success": "",
"results": [
{
"sha256Hash": "",
"applicationName": "",
"processId": "",
"privatePid": "",
"numEvents": "",
"applicationPath": ""
}
],
"message": "",
"latestTime": "",
"elapsed": ""
}
Parameter | Description |
---|---|
Alert ID | ID of the alert whose details and associated event metadata you want to retrieve from CarbonBlack Defense. |
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": ""
}
None.
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": ""
}
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:
|
The output contains the following populated JSON schema:
{
"policyId": "",
"message": "",
"success": ""
}
None.
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": ""
}
Parameter | Description |
---|---|
Policy ID | ID of the policy whose details you want to retrieve from CarbonBlack Defense. |
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": ""
}
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:
|
The output contains the following populated JSON schema:
{
"message": "",
"success": ""
}
Parameter | Description |
---|---|
Policy ID | ID of the policy whose details you want to delete from CarbonBlack Defense. |
The output contains the following populated JSON schema:
{
"message": "",
"success": ""
}
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. |
The output contains the following populated JSON schema:
{
"ruleId": "",
"message": "",
"success": ""
}
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. |
The output contains the following populated JSON schema:
{
"message": "",
"success": ""
}
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. |
The output contains the following populated JSON schema:
{
"message": "",
"success": ""
}
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:
|
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": ""
}
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:
If you choose Kill Process, then you must specify the following parameters:
|
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": ""
}
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:
|
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": ""
}
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.
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.
Connector Version: 2.0.0
Authored By: Fortinet
FortiSOAR™ Version Tested on: 4.12.1-253
Certified: Yes
Following enhancements have been made to the CarbonBlack Defense connector in version 2.0.0:
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.
For the procedure to configure a connector, click here.
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. |
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 |
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. |
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": ""
}
Parameter | Description |
---|---|
Device ID | ID of the device whose details and status you want to retrieve from CarbonBlack Defense. |
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": ""
}
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:
|
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": ""
}
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. |
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": ""
}
Parameter | Description |
---|---|
Event ID | ID of the event whose details you want to retrieve from CarbonBlack Defense. |
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": ""
}
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. |
The output contains the following populated JSON schema:
{
"totalResults": "",
"success": "",
"results": [
{
"sha256Hash": "",
"applicationName": "",
"processId": "",
"privatePid": "",
"numEvents": "",
"applicationPath": ""
}
],
"message": "",
"latestTime": "",
"elapsed": ""
}
Parameter | Description |
---|---|
Alert ID | ID of the alert whose details and associated event metadata you want to retrieve from CarbonBlack Defense. |
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": ""
}
None.
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": ""
}
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:
|
The output contains the following populated JSON schema:
{
"policyId": "",
"message": "",
"success": ""
}
None.
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": ""
}
Parameter | Description |
---|---|
Policy ID | ID of the policy whose details you want to retrieve from CarbonBlack Defense. |
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": ""
}
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:
|
The output contains the following populated JSON schema:
{
"message": "",
"success": ""
}
Parameter | Description |
---|---|
Policy ID | ID of the policy whose details you want to delete from CarbonBlack Defense. |
The output contains the following populated JSON schema:
{
"message": "",
"success": ""
}
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. |
The output contains the following populated JSON schema:
{
"ruleId": "",
"message": "",
"success": ""
}
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. |
The output contains the following populated JSON schema:
{
"message": "",
"success": ""
}
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. |
The output contains the following populated JSON schema:
{
"message": "",
"success": ""
}
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:
|
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": ""
}
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:
If you choose Kill Process, then you must specify the following parameters:
|
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": ""
}
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:
|
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": ""
}
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.