Image Scanning CLI
cbctl command-line tool is inspired by Kubernetes
kubectl and lets you control your CBC container and Kubernetes workload security. For configuration,
cbctl looks for a file named
config in the
$HOME/.cbctl directory. You can specify other
cbctl config files by setting the
- Catch vulnerabilities before they get deployed
- Carbon Black Cloud Container
- Machine that can run the CLI tool and which has access to the image repository to be scanned.
- API key with appropriate permissions. See Authentication for details.
Download the appropriate for your OS version of
cbctl tool from here.
Alternatively, you can use the container image.
Access Level: Before you create your API Key, you need to create a “Custom” Access Level:
- API Key: When you create your API Key, use the Access Level Type of “Custom”, then select the Access Level you created.
- For the category Workload Management > Scan workload image > “workloads.container.image”, allow permission to CREATE and READ to upload SBOMs and query vulnerability reports
cbctl can be configured in multiple ways:
Place your configuration in a config file.
The default place where cbctl will look for this file is
If you want to use a config file that is located in another directory, you can configure that via the
Sample config file:
active_user_profile: cbctl_default cbctl_default: cb_api_id: ABC123 cb_api_key: ABCDEF-12345678 default_build_step: ci org_key: XYZ987 saas_url: https://defense.conferdeploy.net/containers
cbctl supports working with different configuration profiles.
For example, you might have multiple profiles - one for every environment you use
The profiles are stored in the config file.
They can be changed via the
The default profile is stored in the
active_user_profile field in your config file.
The following config file contains 2 user profiles -
The default one is
If you want to use the other one you need to run
cbctl with the
--user-profile=cbctl_production flag set.
active_user_profile: cbctl_staging cbctl_staging: cb_api_id: ABC123 cb_api_key: ABCDEF-12345678 default_build_step: ci org_key: XYZ987 saas_url: https://defense.conferdeploy.net/containers cbctl_production: cb_api_id: ABC123-PROD cb_api_key: ABCDEF-12345678-PROD default_build_step: ci-prod org_key: XYZ987 saas_url: https://defense.conferdeploy.net/containers
CLI arguments (since v1.5.0)
All the values that are in the config file can be passed as CLI arguments:
$ cbctl image scan python --cb-api-key ABC123 --cb-api-id AB123 --org-key XYZ345 --saas-url https://defense.conferdeploy.net/containers
Environment variables (since v1.5.0)
All the values that are in the config file can be passed as environment variables:
$ CBCTL_CB_API_KEY=ABC123 CBCTL_CB_API_ID=AB123 CBCTL_ORG_KEY=XYZ2345 CBCTL_SAAS_URL=https://defense.conferdeploy.net/containers cbctl image scan python
The values passed as CLI arguments and environment variables will take precedence over these in the config file.
- Download the tool for your desired OS and place it in your PATH to install.
- Fill out the config file manually or run
cbctl configand follow the steps, providing your SaaS URL and Org key. Then run
cbctl auth setto set up your API ID and API key.
- Scan an image by running
cbctl image scan <image tag>This will parse your image, generate its SBOM, upload it to the cloud, and retrieve a table of vulnerabilities, sorted by severity. Be sure to run “docker login” as needed if pulling from a private registry. If needed, you can also use the
-o jsonoption to output the vulnerability table as a JSON object instead, and then pipe the command’s standard output to a file or another tool as desired.
Using the container image
cbctl is also published as a container image.
The repository is
For more information on how to use the container check out this page.
Use the following syntax to run
cbctl commands from your terminal window:
$ cbctl [TYPE] [command] [NAME] [flags]
||Specifies the resource type||image, k8s-object|
||Specifies the operation that you want to perform on one or more resources||
||Specifies the name of the resource. Names are case-sensitive and can be resource full name, a file, or an STDIN using the relevant flag||N/A|
||Specifies optional flags||Command Structure Table|
$ cbctl image validate docker.io/octarinesec/nginx:latest
$ cbctl k8s-object validate -f my_resource.yaml
$ cbctl k8s-object validate -f my_dir
$ cat my_resource.yaml | cbctl workload validate
Verifying the Linux binary
To pull the official Carbon Black signing key (the name associated with the key will be exactly “bit9build (bit9cs) firstname.lastname@example.org”), run:
$ gpg --recv-keys 185362D1D591FDFA0C647B58485BB0DF6AC57704
To perform the signature verification, run:
$ gpg --verify /path/to/cbctl_linux_<version> /path/to/cbctl_linux_<version>.asc
An error message will appear if GPG was unable to verify the signature, but the “happy path” should look like this:
gpg: Signature made Tue Apr 20 01:48:27 2021 PDT gpg: using RSA key 485BB0DF6AC57704 gpg: Good signature from "bit9build (bit9cs) <email@example.com>" [unknown]
GPG will also exit with a non-zero exit code if verification failed, which may be useful for programmatic signature verification.
Note that signature verification like this has the same trust problem that TLS certificates have, but PGP solves it a different way – without a certificate authority (like PKI). This means you can verify the signature, but you must rely on the “web of trust” to also trust our signing key. You can verify signatures using GPG just fine without marking our key as trusted, but you’ll also get a warning that looks like this:
gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: 1853 62D1 D591 FDFA 0C64 7B58 485B B0DF 6AC5 7704
To resolve this warning, you must trust the key. To directly mark the key as trusted, run:
$ gpg --lsign-key 185362D1D591FDFA0C647B58485BB0DF6AC57704
Verification looks like this::
gpg: Signature made Tue Apr 20 01:48:27 2021 PDT gpg: using RSA key 485BB0DF6AC57704 gpg: checking the trustdb gpg: marginals needed: 3 completes needed: 1 trust model: pgp gpg: depth: 0 valid: 3 signed: 1 trust: 0-, 0q, 0n, 0m, 0f, 3u gpg: depth: 1 valid: 1 signed: 0 trust: 1-, 0q, 0n, 0m, 0f, 0u gpg: next trustdb check due at 2022-10-07 gpg: Good signature from "bit9build (bit9cs) <firstname.lastname@example.org>" [full]
Command Structure Table
||Image name or id||
||Generate image packages SBOM|
||Image name or id||
||Scan images for known vulnerabilities|
||Image name or id||
||Validate Image for policy violations and return a list of violations|
||Validate Kubernetes object for policy violations and return a list of violations|
Use this form to give us feedback about this site or any of the documentation.
Last modified on July 28, 2023