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 cbctcl 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

Download the appropriate for your OS version of cbctl tool from here.

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

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.

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
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 April 28, 2021