Introduction to VMware Carbon Black Cloud API and PowerShell
This blog post gives an introduction to utilizing the power of the VMware Carbon Black Cloud API using PowerShell. This includes setting up the API ID and secret key, and some PowerShell examples to gather data and execute actions.
Prerequisites
Before continuing, I assume you already have the following in place.
- A running VMware Carbon Black Cloud environment
- At least one endpoint with the Carbon Black Sensor installed
- A machine with PowerShell
Creating the API ID and Secret Key
Before we utilize the VMware Carbon Black Cloud (CBC) API, it is required to create an API ID and secret key. This will allow access to specified items and information within VMware CBC. To specify which items and information is allowed to be accessed, we need to create an Access Level first.
Login to VMware CBC.
On the left hand side, go to Settings and then API Access.
Click Access Levels.
Click Add Access Level.
Give the new Access Level a Name and a Description. In this blog post we are going to request general device information and execute a quarantine request, therefore we need the Device – General information – Read permissions and the Device – Quarantine – Execute permissions. Once configured, click Save.
A full list with Access Level permissions can be found here.
Click API Keys.
Click Add API Key.
Give the new API Key a Name. For Access Level type select Custom. For Custom Access Level select the one you created in the previous step. Click Save.
A window will appear that provides you the API ID and API Secret Key. Write down both, because they are required later on.
Getting in action with PowerShell
Now it’s time to get our hands dirty with PowerShell, so open up your favorite PowerShell interface (ISE, Windows Terminal, etc.).
Authentication
VMware CBC API access requires authentication using the API Secret Key and API ID, which we wrote down earlier on.
Let’s put both of them in their respective variable.
Organization Key
Besides the API Secret Key and API ID, we need the Organization Key (a.k.a. ORG KEY). This is used in the URI to access the correct environment.
To lookup the Organization Key, go to Settings and then API Access.
Write down the ORG KEY.
Let’s put the ORG KEY in its variable.
CBC Region Host Name
The host name required for accessing the VMware CBC API depends on the region your environment is hosted. The full list with host names can be found here.
Search Devices
In this section we are focusing on searching devices and retrieving device information, and what is needed to do that with PowerShell.
VMware CBC provides various URIs for looking up information and executing actions. This full list can be found in the VMware CBC API Reference.
The URI we need for searching devices and retrieving device information is https://[host name]/appservices/v6/orgs/[ORG KEY]/devices/search.
Let’s put the Host Name in another variable in PowerShell.
Let’s construct the header that is required for VMware CBC API authentication.
Let’s construct the body that determines the criteria while searching devices. In this example we are searching for the device with the name DESKTOP-ENOKSHN.
Other criteria can be used to search for specific items and information. Examples can be found in the VMware CBC API Reference.
Now that we have all the required variables/information configures, it’s time to invoke the request to the VMware CBC API. We do this by using the Invoke-WebRequest cmdlet and using the POST method. Another thing we do is convert the body to proper JSON format to make sure the VMware CBC API accepts it.
By looking at the StatusCode and StatusDescription, we see that the request was successful.
We also see that one device is found matching the search criteria.
The response is in JSON format. This can easily be converted to make it more usable within PowerShell.
The $DATA variable contains two sub elements, numfound and results. Within results, you will find sub elements that contain information regarding the device.
For instance, $DATA.results.name returns the name of the device, $DATA.results.id returns the id of the device, and $DATA.results.sensorversion returns the version of the VMware CBC Sensor the device is running.
For a full list of sub elements, simply use $DATA.results | fl.
Quarantine a Device
In this section we are focussing on quarantining a device utilizing the VMware CBC API with PowerShell. This device is the same one from the previous example.
The URI we need to quarantine a device is https://[host name]/appservices/v6/orgs/[ORG KEY]/deviceactions.
The API Key, API ID, ORG KEY, Host Name, and Header we created in the previous example remain as is.
We need to construct a new Body to quarantine the device. In this example we will do it directly in JSON format to give you an idea on how to do that as well. We are using the Device ID we gathered from the previous example, which is 5725168 in this case.
The “toggle”: “ON” option, specifies that quarantine must be switched ON for the device.
The current status of the device is that it is currently not in quarantine.
So we have the Header, we have the Body, and we have the URI. Now, let’s give it a go.
When we look at the StatusCode of the response, we see that it displays 204, which is the expected return code for successfully invoking the request.
After a couple of seconds we can see that the device is put in quarantine.
Conclusion
I hope this blog post gave you an idea of what you can do with the VMware CBC API and PowerShell, and how to do it. In the end, the magic is all in your own creativity and what you want to achieve ;-).
If you have any questions or comments, please reach out on Twitter or LinkedIn.
