Image Scanning CLI

Overview

The 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 --config flag.

Use Cases

  • Catch vulnerabilities before they get deployed

Requirements

  • 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.

Installation

You can use the container image.

Authentication

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

Configuration

cbctl can be configured in multiple ways:

Config file

Place your configuration in a config file. The default place where cbctl will look for this file is ~/.cbctl/.cbctl.yaml. If you want to use a config file that is located in another directory, you can configure that via the --config file.

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

Profiles

cbctl supports working with different configuration profiles.

For example, you might have multiple profiles - one for every environment you use cbctl in.

The profiles are stored in the config file. They can be changed via the --user-profile/-u flag.

The default profile is stored in the active_user_profile field in your config file.

The following config file contains 2 user profiles - cbctl_staging and cbctl_production. The default one is cbctl_staging. 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
Note: The profile names **MUST** start with `cbctl_`.

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.

Quick Start

  1. Download the tool for your desired OS and place it in your PATH to install.
  2. Fill out the config file manually or run cbctl config and follow the steps, providing your SaaS URL and Org key. Then run cbctl auth set to set up your API ID and API key.
  3. 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 json option 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 cbartifactory/cbctl.

For more information on how to use the container check out this page.

Commands

Use the following syntax to run cbctl commands from your terminal window: 

$ cbctl [TYPE] [command] [NAME] [flags]

Command Definition

Name Definition Values
TYPE Specifies the resource type image, k8s-object
command Specifies the operation that you want to perform on one or more resources validate, scan
NAME 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
flags Specifies optional flags Command Structure Table

Examples

$ 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.

Verifying the Linux binary

  1. Download the cbctl_linux_<version> and corresponding cbctl_linux_<version>.asc file.

  2. To pull the official Carbon Black signing key (the name associated with the key will be exactly “bit9build (bit9cs) support@bit9.com”), run: 

    $ gpg --recv-keys 185362D1D591FDFA0C647B58485BB0DF6AC57704

  3. 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) <support@bit9.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) <support@bit9.com>" [full]

Command Structure Table

image

Command Name Flags Description
Packages Image name or id -o output (json/table default table) Generate image packages SBOM
Scan Image name or id -o output (json/table default table)
--cleanup (clean up cache and image after scanning)		 Scan images for known vulnerabilities
Validate Image name or id -b build-step (default: default-build-step from config)
-n namespace (default none)
-o output (json/table default table)
--cleanup (clean up cache and image after scanning)		 Validate Image for policy violations and return a list of violations

k8s-object

Command Name Flags Description
Validate Step name -b build-step (default: default-build-step from config)
-n namespace (default none)
-o output (json/table default table)
-f filename/dir/stdin		 Validate Kubernetes object for policy violations and return a list of violations

Last modified on July 28, 2023