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
Download the appropriate for your OS version of
cbctl tool from here.
Access Level: Before you create your API Key, you need to create a “Custom” Access Level:
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
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
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.
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.
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.
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
Note: It is recommended to use YAML rather than JSON since YAML tends to be more user-friendly, especially for configuration files.
cbctl_linux_<version> and corresponding
To pull the official Carbon Black signing key (the name associated with the key will be exactly “bit9build (bit9cs) email@example.com”), 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) <firstname.lastname@example.org>" [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) <email@example.com>" [full]
||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|