Fortinet Document Library

Version:


Table of Contents

CarbonBlack Protect Bit9

1.0.2
Copy Link

About the connector

CarbonBlack Protection is a comprehensive endpoint threat protection solution and whitelisting product. Combining a trust-based and policy-driven approach to application control with real-time threat intelligence, Carbon Black Protection continuously monitors and records all endpoints and server activities to prevent, detect, and respond to cyber-threats that evade traditional security defenses.

This document provides information about the CarbonBlack Protection Bit9 connector, which facilitates automated interactions, with a CarbonBlack Protection server using FortiSOAR™ playbooks. Add the CarbonBlack Protection Bit9 connector as a step in FortiSOAR™ playbooks and perform automated operations, such as blocking files and unblocking files on the CarbonBlack Protection server and searching for a particular file across all endpoints.

Version information

Connector Version: 1.0.2

FortiSOAR™ Version Tested on: 4.11.0-1161

CarbonBlack Protection Version Tested on: 8.0.0.2562 P6

Authored By: Fortinet.

Certified: Yes

Release Notes for version 1.0.2

Following enhancements have been made to the CarbonBlack Protection Bit9 Connector in version 1.0.2:

  • Added connector logo.

Installing the connector

For the procedure to install a connector, click here.

Prerequisites to configuring the connector

  • You must have the URL of the CarbonBlack Protection server to which you will connect and perform the automated operations.
  • You must have the API key used to access the CarbonBlack Protection REST API.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, select the CarbonBlack Protection Bit9 connector and click Configure to configure the following parameters:

Parameter Description
Server URL IP address or Hostname URL of the CarbonBlack Protection server to which you will connect and perform the automated operations.
API Key API key that is configured for your account to access the CarbonBlack Protection 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
Unblock File Unblocks a particular file on the CarbonBlack Protection server based on the file hash or file catalog ID that you have specified. unblock_file
Remediation
Block File Blocks a particular file on the CarbonBlack Protection server based on the file hash, file catalog ID, or file name that you have specified. block_file
Containment
Hunt File Searches for a particular file on the CarbonBlack Protection server based on the file hash that you have specified. search_file
Investigation
Get System Information Retrieves details for a particular endpoint from the CarbonBlack Protection server based on the host details that you have specified. get_system_info
Investigation
Get Approval Requests Retrieves details for all approval requests or approval requests based on parameters that you have specified from the CarbonBlack Protection server. get_requests
Investigation
Get Policies Retrieves information for all the policies from the CarbonBlack Protection server. You can optionally filter the results and retrieve information about specific policies based on the input parameters you have specified. get_policies
Investigation
Update Approval Request Updates an approval request on the CarbonBlack Protection server based on the parameters you have specified. update_request
Investigation
Remove File Rule Removes a file rule from the CarbonBlack Protection server based on the filehash you have specified. delete_rule
Remediation

operation: Unblock File

Input parameters

Parameter Description
Create Rule Using Rule to be used to unblock a file. Choose from the following options: Filehash or File Catalog ID.
Value Specify the value of the rule you have selected to unblock a file.
For example, if you select Filehash, then enter the hash value of the file that you want to unblock.
Rule Name (Optional) Name of the rule that is associated with the file you want to unblock.
Apply Against Policy ID(s) (Optional) Single Policy ID or CSV of Policy IDs to which this rule will apply.
Example of CSV of Policy IDs: '1','2','3'
Note: If this is a global rule they '0' applies.
Rule Description (Optional) Description of the rule that is associated with the rule name you have specified.

Output

The output contains the following populated JSON schema:
{
     "platformFlags": "",
     "fileState": "",
     "description": "",
     "createdByUserId": "",
     "fileRuleType": "",
     "name": "",
     "visible": "",
     "dateCreated": "",
     "forceNotInstaller": "",
     "idUnique": "",
     "dateModified": "",
     "createdBy": "",
     "forceInstaller": "",
     "reportOnly": "",
     "origIdUnique": "",
     "modifiedBy": "",
     "reputationApprovalsEnabled": "",
     "hash": "",
     "id": "",
     "fileName": "",
     "clVersion": "",
     "sourceType": "",
     "unifiedFlag": "",
     "unifiedSource": "",
     "policyIds": "",
     "version": "",
     "sourceId": "",
     "lazyApproval": "",
     "modifiedByUserId": "",
     "fileCatalogId": ""
}

operation: Block File

Input parameters

Parameter Description
Create Rule Using Rule to be used to block a file. Choose from the following options: Filehash, File Catalog ID, or File Name.
Value Specify the value of the rule you have selected to block a file.
For example, if you select Filehash, then enter the hash value of the file that you want to block.
Rule Name (Optional) Name of the rule that is associated with the file you want to block.
Apply Against Policy ID(s) (Optional) Single Policy ID or CSV of Policy IDs to which this rule will apply.
Example of CSV of Policy IDs: '1','2','3'
Note: If this is a global rule they '0' applies.
Rule Description (Optional) Description of the rule that is associated with the rule name you have specified.

Output

The output contains the following populated JSON schema:
{
     "platformFlags": "",
     "fileState": "",
     "description": "",
     "createdByUserId": "",
     "fileRuleType": "",
     "name": "",
     "visible": "",
     "dateCreated": "",
     "forceNotInstaller": "",
     "idUnique": "",
     "dateModified": "",
     "createdBy": "",
     "forceInstaller": "",
     "reportOnly": "",
     "origIdUnique": "",
     "modifiedBy": "",
     "reputationApprovalsEnabled": "",
     "hash": "",
     "id": "",
     "fileName": "",
     "clVersion": "",
     "sourceType": "",
     "unifiedFlag": "",
     "unifiedSource": "",
     "policyIds": "",
     "version": "",
     "sourceId": "",
     "lazyApproval": "",
     "modifiedByUserId": "",
     "fileCatalogId": ""
}

operation: Hunt File

Input parameters

Parameter Description
Filehash Hash value of the file that you want to search for on the CarbonBlack Protection server.

Output

The output contains the following populated JSON schema:
{
     "company": "",
     "description": "",
     "publisherState": "",
     "globalStateDetails": "",
     "transactionId": "",
     "publisherId": "",
     "sha1": "",
     "dateModified": "",
     "threat": "",
     "approvedByReputation": "",
     "clVersion": "",
     "fileName": "",
     "nodeType": "",
     "fileType": "",
     "verdict": "",
     "acknowledged": "",
     "reputationAvailable": "",
     "fileState": "",
     "md5": "",
     "fileFlags": "",
     "certificateState": "",
     "trust": "",
     "reputationEnabled": "",
     "publisher": "",
     "stateSource": "",
     "sha256HashType": "",
     "pathName": "",
     "dateCreated": "",
     "effectiveState": "",
     "initialized": "",
     "productVersion": "",
     "sha256": "",
     "trustMessages": "",
     "id": "",
     "certificateId": "",
     "productName": "",
     "dirtyPrevalence": "",
     "unifiedSource": "",
     "installedProgramName": "",
     "fileExtension": "",
     "publisherOrCompany": "",
     "category": "",
     "computerId": "",
     "prevalence": "",
     "fileSize": ""
}

operation: Get System Information

Input parameters

Parameter Description
Host Details Details of the host for which you want to retrieve information from the CarbonBlack Protection server. Choose from the following options: Hostname, IP Address, or Computer ID.
Value Specify the value of the host details you select.
For example, if you select Computer ID, then enter the ID of the computer for which you want to retrieve information from the CarbonBlack Protection server.

Output

The output contains the following populated JSON schema:
{
     "debugDuration": "",
     "connected": "",
     "cbSensorFlags": "",
     "debugFlags": "",
     "description": "",
     "ccFlags": "",
     "SCEPStatus": "",
     "deleted": "",
     "name": "",
     "tamperProtectionActive": "",
     "dateCreated": "",
     "templateCloneCleanupMode": "",
     "agentCacheSize": "",
     "isActive": "",
     "templateComputerId": "",
     "lastRegisterDate": "",
     "processorSpeed": "",
     "templateDate": "",
     "virtualized": "",
     "agentQueueSize": "",
     "macAddress": "",
     "osName": "",
     "policyName": "",
     "processorModel": "",
     "clVersion": "",
     "uninstalled": "",
     "template": "",
     "upgradeStatus": "",
     "prioritized": "",
     "virtualPlatform": "",
     "activeDebugLevel": "",
     "cbSensorVersion": "",
     "templateCloneCleanupTimeScale": "",
     "platformId": "",
     "CLIPassword": "",
     "lastPollDate": "",
     "computerTag": "",
     "automaticPolicy": "",
     "users": "",
     "cbSensorId": "",
     "hasDuplicates": "",
     "machineModel": "",
     "supportedKernel": "",
     "syncFlags": "",
     "tdCount": "",
     "osShortName": "",
     "localApproval": "",
     "agentVersion": "",
     "refreshFlags": "",
     "ccLevel": "",
     "previousPolicyId": "",
     "upgradeErrorTime": "",
     "policyId": "",
     "agentMemoryDumps": "",
     "forceUpgrade": "",
     "enforcementLevel": "",
     "upgradeError": "",
     "processorCount": "",
     "ipAddress": "",
     "hasHealthCheckErrors": "",
     "debugLevel": "",
     "id": "",
     "kernelDebugLevel": "",
     "systemMemoryDumps": "",
     "templateTrackModsOnly": "",
     "policyStatus": "",
     "initPercent": "",
     "policyStatusDetails": "",
     "syncPercent": "",
     "disconnectedEnforcementLevel": "",
     "templateCloneCleanupTime": "",
     "initializing": "",
     "activeDebugFlags": "",
     "upgradeErrorCount": "",
     "activeKernelDebugLevel": "",
     "daysOffline": "",
     "memorySize": ""
}

operation: Get Approval Requests

Input parameters

Parameter Description
Status Status of the approval requests for which you want to retrieve details from the CarbonBlack Protection server. Choose from the following options: Submitted, Open, Closed, or Escalated.
Computer Name Name of the computer from which you want to retrieve the details of approval requests.
Computer ID ID of the computer from which you want to retrieve the details of approval requests.
Approval Request ID ID of the approval request for which you want to retrieve details.
File Catalog ID ID of the file catalog that is associated with the approval requests for which you want to retrieve details.
Policy ID ID of the policy on the computer at the time the approval requests for which you want to retrieve details arrived on the CarbonBlack Protection server.
Requestor Name of the user who created the approval requests for which you want to retrieve details.
Request Type Type of the approval requests for which you want to retrieve details from the CarbonBlack Protection server. Choose from the following options: Approval or Justification.
Priority Priority of the approval requests for which you want to retrieve details from the CarbonBlack Protection server. Choose from the following options: High, Medium, or Low.
Filename Name of the file on the agent that is associated with the approval request for which you want to retrieve details.
File Path Path of the file on the agent that is associated with the approval request for which you want to retrieve details.
Process Full Path Full path of the process that the agent that is associated with the approval request for which you want to retrieve details
Created After Date Date/Time after which approval requests were created for which you want to retrieve details.
Modified After Date Date/Time after which approval requests were last modified for which you want to retrieve details.
Sort By Sort the approval requests that are retrieved from the CarbonBlack Protection server based on this option. Choose from the following options: Approval Request ID, File Catalog ID, By Associated Installer File Catalog ID, By Associated Process Catalog ID, Computer ID, Computer Name, By Request Creation Date, By Request Created User, By Request Modification Date, By Request Modified User, Enforcement Level, By Request Resolution, Request Type, By Request Comment, By Requestor Email, Request Priority, Resolver Comment, Request Status, Policy ID, By Multiple Blocks, By Filename, By File Path, Parent Process , File Path, Custom Rule ID, Count of Duplicate Approval Request, Count of Duplicate Related Approval Request, Request Platform(OS), Publisher Reputation, Custom Rule Type, Installer Full Path, Parent Process Filename Only, Parent Process File Path (Without Filename), Response Email Time, or Full Filepath.
Offset in Query Results Index of the first item that this operation should return.
Maximum Number of Results Maximum number of approval requests that this operation should return.
Foreign Key Fields to Expand Foreign key fields that you want to expand on.

Note: All the above parameters are optional. If you do not specify any parameter, then details of all approval requests will be retrieved from the CarbonBlack Protection server.

Output

The output contains the following populated JSON schema:
{
     "file": "",
     "publisherReputation": "",
     "processFileCatalogId": "",
     "customRuleId": "",
     "computerId": "",
     "requestType": "",
     "customRuleType": "",
     "dateCreated": "",
     "requestorEmail": "",
     "duplicates": "",
     "dateModified": "",
     "createdBy": "",
     "multipleBlocks": "",
     "installerFileCatalogId": "",
     "pathName": "",
     "modifiedBy": "",
     "resolutionComments": "",
     "processName": "",
     "id": "",
     "fileName": "",
     "process": "",
     "processPath": "",
     "status": "",
     "enforcementLevel": "",
     "platform": "",
     "installer": "",
     "resolution": "",
     "computerName": "",
     "fileCatalogId": "",
     "related": "",
     "priority": "",
     "policyId": "",
     "modifiedByUserId": "",
     "requestorComments": "",
     "responseMailSent": "",
     "createdByUserId": ""
}

operation: Get Policies

Input parameters

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

Parameter Description
Policy ID ID of the policy for which you want to retrieve details from the CarbonBlack Protection server.
Name Name of the policy for which you want to retrieve details from the CarbonBlack Protection server.
Description Description of the policy for which you want to retrieve details from the CarbonBlack Protection server.
Package Name Name of the installer package of the policy for which you want to retrieve details from the CarbonBlack Protection server.
Enforcement Level Enforcement level of policies. Retrieve policies from the CarbonBlack Protection server based on the enforcement level defined in the policies.
You can choose from the following options: High (Block Unapproved), Medium (Prompt Unapproved), Low (Monitor Unapproved), None (Visibility), or None (Disabled).
Disconnected Enforcement Level Disconnected enforcement level of policies. Retrieve policies from the CarbonBlack Protection server based on the disconnected enforcement level defined in the policies.
You can choose from the following options: High (Block Unapproved), Medium (Prompt Unapproved), Low (Monitor Unapproved), None (Visibility), or None (Disabled).
Help Desk URL Help Desk URL for Notifiers defined in policies. Retrieve policies from the CarbonBlack Protection server based on the Help Desk URL defined in the policies.
Image URL Image Logo URL for Notifiers defined in policies. Retrieve policies from the CarbonBlack Protection server based on the Image URL defined in the policies.
Modified After Date DateTime when policies are modified. Retrieve those policies from the CarbonBlack Protection server that are modified after the DateTime you have specified.
Created After Date DateTime when policies are created. Retrieve those policies from the CarbonBlack Protection server that are created after the DateTime you have specified.
Read Only Specify whether policies to be retrieved from the CarbonBlack Protection server should be read-only or not.
You can choose from the following options: True or False. If you choose True, then only those policies that are read-only are retrieved from the CarbonBlack Protection server.
Hidden Specify whether policies to be retrieved from the CarbonBlack Protection server should be hidden or not.
You can choose from the following options: True or False. If you choose True, then only those policies that are hidden are retrieved from the CarbonBlack Protection server.
Automatic Specify whether policies to be retrieved from the CarbonBlack Protection server should have AD mapping enabled or not.
You can choose from the following options: True or False. If you choose True, then only those policies that have AD mapping enabled are retrieved from the CarbonBlack Protection server.
Load Agent In Safe Mode Specify whether policies to be retrieved from the CarbonBlack Protection server should have the agents gets loaded when the machine is booted in “safe mode” parameter enabled or not.
You can choose from the following options: True or False. If you choose True, then only those policies that have the agents gets loaded when the machine is booted in “safe mode” parameter enabled are retrieved from the CarbonBlack Protection server.
Reputation Enabled Specify whether policies to be retrieved from the CarbonBlack Protection server should have reputation approvals enabled or not.
You can choose from the following options: True or False. If you choose True, then only those policies that have reputation approvals enabled are retrieved from the CarbonBlack Protection server.
File Tracking Enabled Specify whether policies to be retrieved from the CarbonBlack Protection server should have file tracking enabled or not.
You can choose from the following options: True or False. If you choose True, then only those policies that have file tracking enabled are retrieved from the CarbonBlack Protection server.
Custom Logo Specify whether policies to be retrieved from the CarbonBlack Protection server should have notifiers that use custom logos or not.
You can choose from the following options: True or False. If you choose True, then only those policies in which notifiers use custom logos are retrieved from the CarbonBlack Protection server.
Automatic Approval On Transition Specify whether policies to be retrieved from the CarbonBlack Protection server should have the agent automatically locally approve files when transitioning into High Enforcement parameter enabled or not.
You can choose from the following options: True or False. If you choose True, then only those policies that have the agent automatically locally approve files when transitioning into High Enforcement parameter enabled are retrieved from the CarbonBlack Protection server.
Allow Agent Upgrades Specify whether policies to be retrieved from the CarbonBlack Protection server should have the allow agent upgrades parameter enabled or not.
You can choose from the following options: True or False. If you choose True, then only those policies that have the allow agent upgrades parameter enabled are retrieved from the CarbonBlack Protection server.
Max CL Version Maximum target CL version of agents of policy based on which to retrieve details from the CarbonBlack Protection server.
Offset in Query Results Index of the first item that this operation should return.
Maximum Number of Results Maximum number of policies that this operation should return.

Output

The output contains the following populated JSON schema:
{
     "loadAgentInSafeMode": "",
     "description": "",
     "hidden": "",
     "name": "",
     "reputationEnabled": "",
     "dateCreated": "",
     "customLogo": "",
     "dateModified": "",
     "atEnforcementComputers": "",
     "clVersionMax": "",
     "enforcementLevel": "",
     "packageName": "",
     "totalComputers": "",
     "helpDeskUrl": "",
     "id": "",
     "imageUrl": "",
     "readOnly": "",
     "fileTrackingEnabled": "",
     "connectedComputers": "",
     "allowAgentUpgrades": "",
     "disconnectedEnforcementLevel": "",
     "createdByUserId": "",
     "automaticApprovalsOnTransition": "",
     "automatic": "",
     "modifiedByUserId": ""
}

operation: Update Approval Request

Input parameters

 

Parameter Description
Approval Request ID ID of the approval request that you want to update on the CarbonBlack Protection server.
Status Status of the approval request that you want to update on the CarbonBlack Protection server. Choose from the following options: New, Open, Closed, or Escalated.
Resolution Resolution of the approval request that you want to update on the CarbonBlack Protection server. Choose from the following options: Not Resolved, Rejected, Resolved - Approved, Resolved - Rule Change, Resolved - Installer, Resolved - Updater, Resolved - Publisher, or Resolved - Other.
Comments (Optional) Comments that you want to enter for the approval request that you want to update on the CarbonBlack Protection server.
Requestor Email (Optional) Email ID of the requestor who is updating the approval request on the CarbonBlack Protection server.

Output

The output contains the following populated JSON schema:
{
     "file": "",
     "publisherReputation": "",
     "processFileCatalogId": "",
     "customRuleId": "",
     "computerId": "",
     "requestType": "",
     "customRuleType": "",
     "dateCreated": "",
     "requestorEmail": "",
     "duplicates": "",
     "dateModified": "",
     "createdBy": "",
     "multipleBlocks": "",
     "installerFileCatalogId": "",
     "pathName": "",
     "modifiedBy": "",
     "resolutionComments": "",
     "processName": "",
     "id": "",
     "fileName": "",
     "process": "",
     "processPath": "",
     "status": "",
     "enforcementLevel": "",
     "platform": "",
     "installer": "",
     "resolution": "",
     "computerName": "",
     "fileCatalogId": "",
     "related": "",
     "priority": "",
     "policyId": "",
     "modifiedByUserId": "",
     "requestorComments": "",
     "responseMailSent": "",
     "createdByUserId": ""
}

operation: Remove File Rule

Input parameters

Parameter Description
Filehash Hash value of the file that you want to remove from the CarbonBlack Protection server.

Output

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

Included playbooks

The Sample-CarbonBlack Protection Bit9 - 1.0.2 playbook collection comes bundled with the CarbonBlack Protection Bit9 connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the CarbonBlack Protection Bit9 connector.

  • Block File
  • Get Approval Request
  • Get Policies
  • Get System Information
  • Hunt File
  • Remove File Rule
  • Unblock File
  • Update Approval Request

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 Protection is a comprehensive endpoint threat protection solution and whitelisting product. Combining a trust-based and policy-driven approach to application control with real-time threat intelligence, Carbon Black Protection continuously monitors and records all endpoints and server activities to prevent, detect, and respond to cyber-threats that evade traditional security defenses.

This document provides information about the CarbonBlack Protection Bit9 connector, which facilitates automated interactions, with a CarbonBlack Protection server using FortiSOAR™ playbooks. Add the CarbonBlack Protection Bit9 connector as a step in FortiSOAR™ playbooks and perform automated operations, such as blocking files and unblocking files on the CarbonBlack Protection server and searching for a particular file across all endpoints.

Version information

Connector Version: 1.0.2

FortiSOAR™ Version Tested on: 4.11.0-1161

CarbonBlack Protection Version Tested on: 8.0.0.2562 P6

Authored By: Fortinet.

Certified: Yes

Release Notes for version 1.0.2

Following enhancements have been made to the CarbonBlack Protection Bit9 Connector in version 1.0.2:

Installing the connector

For the procedure to install a connector, click here.

Prerequisites to configuring the connector

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, select the CarbonBlack Protection Bit9 connector and click Configure to configure the following parameters:

Parameter Description
Server URL IP address or Hostname URL of the CarbonBlack Protection server to which you will connect and perform the automated operations.
API Key API key that is configured for your account to access the CarbonBlack Protection 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
Unblock File Unblocks a particular file on the CarbonBlack Protection server based on the file hash or file catalog ID that you have specified. unblock_file
Remediation
Block File Blocks a particular file on the CarbonBlack Protection server based on the file hash, file catalog ID, or file name that you have specified. block_file
Containment
Hunt File Searches for a particular file on the CarbonBlack Protection server based on the file hash that you have specified. search_file
Investigation
Get System Information Retrieves details for a particular endpoint from the CarbonBlack Protection server based on the host details that you have specified. get_system_info
Investigation
Get Approval Requests Retrieves details for all approval requests or approval requests based on parameters that you have specified from the CarbonBlack Protection server. get_requests
Investigation
Get Policies Retrieves information for all the policies from the CarbonBlack Protection server. You can optionally filter the results and retrieve information about specific policies based on the input parameters you have specified. get_policies
Investigation
Update Approval Request Updates an approval request on the CarbonBlack Protection server based on the parameters you have specified. update_request
Investigation
Remove File Rule Removes a file rule from the CarbonBlack Protection server based on the filehash you have specified. delete_rule
Remediation

operation: Unblock File

Input parameters

Parameter Description
Create Rule Using Rule to be used to unblock a file. Choose from the following options: Filehash or File Catalog ID.
Value Specify the value of the rule you have selected to unblock a file.
For example, if you select Filehash, then enter the hash value of the file that you want to unblock.
Rule Name (Optional) Name of the rule that is associated with the file you want to unblock.
Apply Against Policy ID(s) (Optional) Single Policy ID or CSV of Policy IDs to which this rule will apply.
Example of CSV of Policy IDs: '1','2','3'
Note: If this is a global rule they '0' applies.
Rule Description (Optional) Description of the rule that is associated with the rule name you have specified.

Output

The output contains the following populated JSON schema:
{
     "platformFlags": "",
     "fileState": "",
     "description": "",
     "createdByUserId": "",
     "fileRuleType": "",
     "name": "",
     "visible": "",
     "dateCreated": "",
     "forceNotInstaller": "",
     "idUnique": "",
     "dateModified": "",
     "createdBy": "",
     "forceInstaller": "",
     "reportOnly": "",
     "origIdUnique": "",
     "modifiedBy": "",
     "reputationApprovalsEnabled": "",
     "hash": "",
     "id": "",
     "fileName": "",
     "clVersion": "",
     "sourceType": "",
     "unifiedFlag": "",
     "unifiedSource": "",
     "policyIds": "",
     "version": "",
     "sourceId": "",
     "lazyApproval": "",
     "modifiedByUserId": "",
     "fileCatalogId": ""
}

operation: Block File

Input parameters

Parameter Description
Create Rule Using Rule to be used to block a file. Choose from the following options: Filehash, File Catalog ID, or File Name.
Value Specify the value of the rule you have selected to block a file.
For example, if you select Filehash, then enter the hash value of the file that you want to block.
Rule Name (Optional) Name of the rule that is associated with the file you want to block.
Apply Against Policy ID(s) (Optional) Single Policy ID or CSV of Policy IDs to which this rule will apply.
Example of CSV of Policy IDs: '1','2','3'
Note: If this is a global rule they '0' applies.
Rule Description (Optional) Description of the rule that is associated with the rule name you have specified.

Output

The output contains the following populated JSON schema:
{
     "platformFlags": "",
     "fileState": "",
     "description": "",
     "createdByUserId": "",
     "fileRuleType": "",
     "name": "",
     "visible": "",
     "dateCreated": "",
     "forceNotInstaller": "",
     "idUnique": "",
     "dateModified": "",
     "createdBy": "",
     "forceInstaller": "",
     "reportOnly": "",
     "origIdUnique": "",
     "modifiedBy": "",
     "reputationApprovalsEnabled": "",
     "hash": "",
     "id": "",
     "fileName": "",
     "clVersion": "",
     "sourceType": "",
     "unifiedFlag": "",
     "unifiedSource": "",
     "policyIds": "",
     "version": "",
     "sourceId": "",
     "lazyApproval": "",
     "modifiedByUserId": "",
     "fileCatalogId": ""
}

operation: Hunt File

Input parameters

Parameter Description
Filehash Hash value of the file that you want to search for on the CarbonBlack Protection server.

Output

The output contains the following populated JSON schema:
{
     "company": "",
     "description": "",
     "publisherState": "",
     "globalStateDetails": "",
     "transactionId": "",
     "publisherId": "",
     "sha1": "",
     "dateModified": "",
     "threat": "",
     "approvedByReputation": "",
     "clVersion": "",
     "fileName": "",
     "nodeType": "",
     "fileType": "",
     "verdict": "",
     "acknowledged": "",
     "reputationAvailable": "",
     "fileState": "",
     "md5": "",
     "fileFlags": "",
     "certificateState": "",
     "trust": "",
     "reputationEnabled": "",
     "publisher": "",
     "stateSource": "",
     "sha256HashType": "",
     "pathName": "",
     "dateCreated": "",
     "effectiveState": "",
     "initialized": "",
     "productVersion": "",
     "sha256": "",
     "trustMessages": "",
     "id": "",
     "certificateId": "",
     "productName": "",
     "dirtyPrevalence": "",
     "unifiedSource": "",
     "installedProgramName": "",
     "fileExtension": "",
     "publisherOrCompany": "",
     "category": "",
     "computerId": "",
     "prevalence": "",
     "fileSize": ""
}

operation: Get System Information

Input parameters

Parameter Description
Host Details Details of the host for which you want to retrieve information from the CarbonBlack Protection server. Choose from the following options: Hostname, IP Address, or Computer ID.
Value Specify the value of the host details you select.
For example, if you select Computer ID, then enter the ID of the computer for which you want to retrieve information from the CarbonBlack Protection server.

Output

The output contains the following populated JSON schema:
{
     "debugDuration": "",
     "connected": "",
     "cbSensorFlags": "",
     "debugFlags": "",
     "description": "",
     "ccFlags": "",
     "SCEPStatus": "",
     "deleted": "",
     "name": "",
     "tamperProtectionActive": "",
     "dateCreated": "",
     "templateCloneCleanupMode": "",
     "agentCacheSize": "",
     "isActive": "",
     "templateComputerId": "",
     "lastRegisterDate": "",
     "processorSpeed": "",
     "templateDate": "",
     "virtualized": "",
     "agentQueueSize": "",
     "macAddress": "",
     "osName": "",
     "policyName": "",
     "processorModel": "",
     "clVersion": "",
     "uninstalled": "",
     "template": "",
     "upgradeStatus": "",
     "prioritized": "",
     "virtualPlatform": "",
     "activeDebugLevel": "",
     "cbSensorVersion": "",
     "templateCloneCleanupTimeScale": "",
     "platformId": "",
     "CLIPassword": "",
     "lastPollDate": "",
     "computerTag": "",
     "automaticPolicy": "",
     "users": "",
     "cbSensorId": "",
     "hasDuplicates": "",
     "machineModel": "",
     "supportedKernel": "",
     "syncFlags": "",
     "tdCount": "",
     "osShortName": "",
     "localApproval": "",
     "agentVersion": "",
     "refreshFlags": "",
     "ccLevel": "",
     "previousPolicyId": "",
     "upgradeErrorTime": "",
     "policyId": "",
     "agentMemoryDumps": "",
     "forceUpgrade": "",
     "enforcementLevel": "",
     "upgradeError": "",
     "processorCount": "",
     "ipAddress": "",
     "hasHealthCheckErrors": "",
     "debugLevel": "",
     "id": "",
     "kernelDebugLevel": "",
     "systemMemoryDumps": "",
     "templateTrackModsOnly": "",
     "policyStatus": "",
     "initPercent": "",
     "policyStatusDetails": "",
     "syncPercent": "",
     "disconnectedEnforcementLevel": "",
     "templateCloneCleanupTime": "",
     "initializing": "",
     "activeDebugFlags": "",
     "upgradeErrorCount": "",
     "activeKernelDebugLevel": "",
     "daysOffline": "",
     "memorySize": ""
}

operation: Get Approval Requests

Input parameters

Parameter Description
Status Status of the approval requests for which you want to retrieve details from the CarbonBlack Protection server. Choose from the following options: Submitted, Open, Closed, or Escalated.
Computer Name Name of the computer from which you want to retrieve the details of approval requests.
Computer ID ID of the computer from which you want to retrieve the details of approval requests.
Approval Request ID ID of the approval request for which you want to retrieve details.
File Catalog ID ID of the file catalog that is associated with the approval requests for which you want to retrieve details.
Policy ID ID of the policy on the computer at the time the approval requests for which you want to retrieve details arrived on the CarbonBlack Protection server.
Requestor Name of the user who created the approval requests for which you want to retrieve details.
Request Type Type of the approval requests for which you want to retrieve details from the CarbonBlack Protection server. Choose from the following options: Approval or Justification.
Priority Priority of the approval requests for which you want to retrieve details from the CarbonBlack Protection server. Choose from the following options: High, Medium, or Low.
Filename Name of the file on the agent that is associated with the approval request for which you want to retrieve details.
File Path Path of the file on the agent that is associated with the approval request for which you want to retrieve details.
Process Full Path Full path of the process that the agent that is associated with the approval request for which you want to retrieve details
Created After Date Date/Time after which approval requests were created for which you want to retrieve details.
Modified After Date Date/Time after which approval requests were last modified for which you want to retrieve details.
Sort By Sort the approval requests that are retrieved from the CarbonBlack Protection server based on this option. Choose from the following options: Approval Request ID, File Catalog ID, By Associated Installer File Catalog ID, By Associated Process Catalog ID, Computer ID, Computer Name, By Request Creation Date, By Request Created User, By Request Modification Date, By Request Modified User, Enforcement Level, By Request Resolution, Request Type, By Request Comment, By Requestor Email, Request Priority, Resolver Comment, Request Status, Policy ID, By Multiple Blocks, By Filename, By File Path, Parent Process , File Path, Custom Rule ID, Count of Duplicate Approval Request, Count of Duplicate Related Approval Request, Request Platform(OS), Publisher Reputation, Custom Rule Type, Installer Full Path, Parent Process Filename Only, Parent Process File Path (Without Filename), Response Email Time, or Full Filepath.
Offset in Query Results Index of the first item that this operation should return.
Maximum Number of Results Maximum number of approval requests that this operation should return.
Foreign Key Fields to Expand Foreign key fields that you want to expand on.

Note: All the above parameters are optional. If you do not specify any parameter, then details of all approval requests will be retrieved from the CarbonBlack Protection server.

Output

The output contains the following populated JSON schema:
{
     "file": "",
     "publisherReputation": "",
     "processFileCatalogId": "",
     "customRuleId": "",
     "computerId": "",
     "requestType": "",
     "customRuleType": "",
     "dateCreated": "",
     "requestorEmail": "",
     "duplicates": "",
     "dateModified": "",
     "createdBy": "",
     "multipleBlocks": "",
     "installerFileCatalogId": "",
     "pathName": "",
     "modifiedBy": "",
     "resolutionComments": "",
     "processName": "",
     "id": "",
     "fileName": "",
     "process": "",
     "processPath": "",
     "status": "",
     "enforcementLevel": "",
     "platform": "",
     "installer": "",
     "resolution": "",
     "computerName": "",
     "fileCatalogId": "",
     "related": "",
     "priority": "",
     "policyId": "",
     "modifiedByUserId": "",
     "requestorComments": "",
     "responseMailSent": "",
     "createdByUserId": ""
}

operation: Get Policies

Input parameters

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

Parameter Description
Policy ID ID of the policy for which you want to retrieve details from the CarbonBlack Protection server.
Name Name of the policy for which you want to retrieve details from the CarbonBlack Protection server.
Description Description of the policy for which you want to retrieve details from the CarbonBlack Protection server.
Package Name Name of the installer package of the policy for which you want to retrieve details from the CarbonBlack Protection server.
Enforcement Level Enforcement level of policies. Retrieve policies from the CarbonBlack Protection server based on the enforcement level defined in the policies.
You can choose from the following options: High (Block Unapproved), Medium (Prompt Unapproved), Low (Monitor Unapproved), None (Visibility), or None (Disabled).
Disconnected Enforcement Level Disconnected enforcement level of policies. Retrieve policies from the CarbonBlack Protection server based on the disconnected enforcement level defined in the policies.
You can choose from the following options: High (Block Unapproved), Medium (Prompt Unapproved), Low (Monitor Unapproved), None (Visibility), or None (Disabled).
Help Desk URL Help Desk URL for Notifiers defined in policies. Retrieve policies from the CarbonBlack Protection server based on the Help Desk URL defined in the policies.
Image URL Image Logo URL for Notifiers defined in policies. Retrieve policies from the CarbonBlack Protection server based on the Image URL defined in the policies.
Modified After Date DateTime when policies are modified. Retrieve those policies from the CarbonBlack Protection server that are modified after the DateTime you have specified.
Created After Date DateTime when policies are created. Retrieve those policies from the CarbonBlack Protection server that are created after the DateTime you have specified.
Read Only Specify whether policies to be retrieved from the CarbonBlack Protection server should be read-only or not.
You can choose from the following options: True or False. If you choose True, then only those policies that are read-only are retrieved from the CarbonBlack Protection server.
Hidden Specify whether policies to be retrieved from the CarbonBlack Protection server should be hidden or not.
You can choose from the following options: True or False. If you choose True, then only those policies that are hidden are retrieved from the CarbonBlack Protection server.
Automatic Specify whether policies to be retrieved from the CarbonBlack Protection server should have AD mapping enabled or not.
You can choose from the following options: True or False. If you choose True, then only those policies that have AD mapping enabled are retrieved from the CarbonBlack Protection server.
Load Agent In Safe Mode Specify whether policies to be retrieved from the CarbonBlack Protection server should have the agents gets loaded when the machine is booted in “safe mode” parameter enabled or not.
You can choose from the following options: True or False. If you choose True, then only those policies that have the agents gets loaded when the machine is booted in “safe mode” parameter enabled are retrieved from the CarbonBlack Protection server.
Reputation Enabled Specify whether policies to be retrieved from the CarbonBlack Protection server should have reputation approvals enabled or not.
You can choose from the following options: True or False. If you choose True, then only those policies that have reputation approvals enabled are retrieved from the CarbonBlack Protection server.
File Tracking Enabled Specify whether policies to be retrieved from the CarbonBlack Protection server should have file tracking enabled or not.
You can choose from the following options: True or False. If you choose True, then only those policies that have file tracking enabled are retrieved from the CarbonBlack Protection server.
Custom Logo Specify whether policies to be retrieved from the CarbonBlack Protection server should have notifiers that use custom logos or not.
You can choose from the following options: True or False. If you choose True, then only those policies in which notifiers use custom logos are retrieved from the CarbonBlack Protection server.
Automatic Approval On Transition Specify whether policies to be retrieved from the CarbonBlack Protection server should have the agent automatically locally approve files when transitioning into High Enforcement parameter enabled or not.
You can choose from the following options: True or False. If you choose True, then only those policies that have the agent automatically locally approve files when transitioning into High Enforcement parameter enabled are retrieved from the CarbonBlack Protection server.
Allow Agent Upgrades Specify whether policies to be retrieved from the CarbonBlack Protection server should have the allow agent upgrades parameter enabled or not.
You can choose from the following options: True or False. If you choose True, then only those policies that have the allow agent upgrades parameter enabled are retrieved from the CarbonBlack Protection server.
Max CL Version Maximum target CL version of agents of policy based on which to retrieve details from the CarbonBlack Protection server.
Offset in Query Results Index of the first item that this operation should return.
Maximum Number of Results Maximum number of policies that this operation should return.

Output

The output contains the following populated JSON schema:
{
     "loadAgentInSafeMode": "",
     "description": "",
     "hidden": "",
     "name": "",
     "reputationEnabled": "",
     "dateCreated": "",
     "customLogo": "",
     "dateModified": "",
     "atEnforcementComputers": "",
     "clVersionMax": "",
     "enforcementLevel": "",
     "packageName": "",
     "totalComputers": "",
     "helpDeskUrl": "",
     "id": "",
     "imageUrl": "",
     "readOnly": "",
     "fileTrackingEnabled": "",
     "connectedComputers": "",
     "allowAgentUpgrades": "",
     "disconnectedEnforcementLevel": "",
     "createdByUserId": "",
     "automaticApprovalsOnTransition": "",
     "automatic": "",
     "modifiedByUserId": ""
}

operation: Update Approval Request

Input parameters

 

Parameter Description
Approval Request ID ID of the approval request that you want to update on the CarbonBlack Protection server.
Status Status of the approval request that you want to update on the CarbonBlack Protection server. Choose from the following options: New, Open, Closed, or Escalated.
Resolution Resolution of the approval request that you want to update on the CarbonBlack Protection server. Choose from the following options: Not Resolved, Rejected, Resolved - Approved, Resolved - Rule Change, Resolved - Installer, Resolved - Updater, Resolved - Publisher, or Resolved - Other.
Comments (Optional) Comments that you want to enter for the approval request that you want to update on the CarbonBlack Protection server.
Requestor Email (Optional) Email ID of the requestor who is updating the approval request on the CarbonBlack Protection server.

Output

The output contains the following populated JSON schema:
{
     "file": "",
     "publisherReputation": "",
     "processFileCatalogId": "",
     "customRuleId": "",
     "computerId": "",
     "requestType": "",
     "customRuleType": "",
     "dateCreated": "",
     "requestorEmail": "",
     "duplicates": "",
     "dateModified": "",
     "createdBy": "",
     "multipleBlocks": "",
     "installerFileCatalogId": "",
     "pathName": "",
     "modifiedBy": "",
     "resolutionComments": "",
     "processName": "",
     "id": "",
     "fileName": "",
     "process": "",
     "processPath": "",
     "status": "",
     "enforcementLevel": "",
     "platform": "",
     "installer": "",
     "resolution": "",
     "computerName": "",
     "fileCatalogId": "",
     "related": "",
     "priority": "",
     "policyId": "",
     "modifiedByUserId": "",
     "requestorComments": "",
     "responseMailSent": "",
     "createdByUserId": ""
}

operation: Remove File Rule

Input parameters

Parameter Description
Filehash Hash value of the file that you want to remove from the CarbonBlack Protection server.

Output

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

Included playbooks

The Sample-CarbonBlack Protection Bit9 - 1.0.2 playbook collection comes bundled with the CarbonBlack Protection Bit9 connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the CarbonBlack Protection Bit9 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.