CarbonCLI

The CarbonCLI is a Powershell based module to manage Carbon Black Cloud constructs. Cmdlets are provided for the most common actions to manage sensors, policies, alerts, watchlists, etc.

Requirements

  • At least one Carbon Black Cloud product is required to use this:
    • Endpoint Standard
    • Enterprise EDR
  • Custom API Key
  • Powershell installed (version 7.x)

Carbon Black Cloud Configuration

Custom API Key

The cli requires a Custom API key with the relevant permissions depending on the cmdlet to be used. Check the table below to see what permissionses are need for each cmdlet.

To generate the specific permissions navigate to Carbon Black Cloud and then Settings > API Access > Access Level > Add Access Level. Then to create the API key navigate to Settings > API Access > API Keys.

Cmdlet Action Permissions
Get-CbcAlerts Retrieve alerts READ Alerts > General information > org.alerts
Get-CbcDevice Retrieve devices READ Device > General information > device
Get-CbcFeed Retrieve feeds READ Custom Detections > Feeds > org.feeds
Get-CbcFeedDetails Retrieve feed details READ Custom Detections > Feeds > org.feeds
Get-CbcIoc Retrieve ioc(s) in report READ Custom Detections > Feeds > org.feeds
Get-CbcJob Retrieve the status of an async job READ, CREATE Search > Events > org.search.events
Get-CbcObservation Retrieve observations READ, CREATE Search > Events > org.search.events
Get-CbcObservationDetails Retrieve observation details READ, CREATE Search > Events > org.search.events
Get-CbcPolicy Retrieve policies READ Device > Policy assignment > org.policies
Get-CbcPolicyDetails Retrieve policy details READ Device > Policy assignment > org.policies
Get-CbcProcess Retrieve processes READ, CREATE Search > Events > org.search.events
Get-CbcProcessDetails Retrieve process details READ, CREATE Search > Events > org.search.events
Get-CbcReport Retrieve a report in feed READ Custom Detections > Feeds > org.feeds
Get-CbcWatchlist Retrieve watchlists READ Custom Detections > Watchlists > org.watchlists
New-CbcFeed Create feeds CREATE Custom Detections > Feeds > org.feeds
New-CbcIoc Create iocs CREATE Custom Detections > Feeds > org.feeds
New-CbcReport Create reports CREATE Custom Detections > Feeds > org.feeds
New-CbcWatchlist Create watchlists CREATE Custom Detections > Watchlists > org.watchlists
Receive-CbcJob Retrieve results of an async job READ, CREATE Search > Events > org.search.events
Remove-CbcFeed Remove feeds DELETE Custom Detections > Feeds > org.feeds
Remove-CbcIoc Remove iocs DELETE Custom Detections > Feeds > org.feeds
Remove-CbcReport Remove reports DELETE Custom Detections > Feeds > org.feeds
Remove-CbcWatchlist Remove watchlists DELETE Custom Detections > Watchlists > org.watchlists
Set-CbcAlerts Dismiss alerts EXECUTE Alerts > Close org.alerts.close
Set-CbcDevice Update policies UPDATE Device > Policy assignment > device.policy
Set-CbcDevice Start background scan EXECUTE Device > Background scan > device.bg-scan
Set-CbcDevice Enable/Disable Bypass EXECUTE Device > Bypass > device.bypass
Set-CbcDevice Enable/Disable Quarantine EXECUTE Device > Quarantine > device.quarantine
Set-CbcDevice Update sensor version EXECUTE Device > Sensor kits > org.kits
Set-CbcDevice Uninstall sensor EXECUTE Device > Uninstall > device.uninstall
Set-CbcDevice Deregister sensor DELETE Device > Deregistered > device.deregistered
New-CbcFeed Update feeds metadata UPDATE Custom Detections > Feeds > org.feeds
New-CbcIoc Updates iocs metadata UPDATE Custom Detections > Feeds > org.feeds
New-CbcReport Updates reports metadata UPDATE Custom Detections > Feeds > org.feeds
New-CbcWatchlist Updates watchlists metadata UPDATE Custom Detections > Watchlists > org.watchlists

Installation

From the repo

You can install the CarbonCLI using GitHub following the README.

  1. Clone the repository using SSH or HTTPS

     SSH
 git clone git@github.com:carbonblack/carbon-cli.git

 HTTPS
 git clone https://github.com/carbonblack/carbon-cli.git

  2. Change to the root directory of the project

     cd carbon-cli

  3. Start Powershell

     pwsh

  4. Import the module

     Import-Module ./CarbonCLI/CarbonCLI.psm1

Getting Started

  1. Once you import the module, create a connection or connections to run cmdlets against:

     Connect-CBCServer -Server https://defense.conferdeploy.net/ -Org ABCD1234 -Token ABCDEFGHIJKLMNO123456789/ABCD123456

Note: You need a Custom Key with the proper permissions.

  1. Get help with Carbon Black Cloud CLI cmdlets:

     Get-Help Connect-CBCServer -Full
 Get-Help Get-CBCAlert -Examples

  2. Start using Carbon Black Cloud CLI cmdlets. Below are a few examples showing how to use them:

    a. Get all alerts with minimum severity 5 that are of type CB_ANALYTICS:

     Get-CbcAlert -Severity 5 -Type CB_ANALYTICS

    b. Get all observations for specific alert:

     Get-CbcAlert -Id "c295b8fc-0f5d-7193-3075-0301862c69b7" | Get-CbcObservation

    c. Quarantine all devices that are with os WINDOWS and a specific os version (Windows 10 x64)

     Get-CbcDevice -OS Windows -OSVersion "Windows 10 x64" | Set-CbcDevice -QuarantineEnabled $true

    d. Get all devices with sensor version 3.9.2.2637 and upgrade it to 4.0.1.1358

     Get-CbcDevice -Include @{"sensor_version" = @("3.9.2.2637")} |  Set-CbcDevice -SensorVersion "4.0.1.1358"

  3. Review Demo-Script.ps1 for useful getting-started examples covering the main Carbon Black Cloud concepts.


Last modified on March 26, 2024