Overview

Help version: 9.4.1

Black Duck Docker Inspector inspects Docker images to discover packages (components). It utilizes the appropriate Linux package manager to provide a list of the packages installed by the package manager, and creates a Black Duck project with a Bill of Materials (BOM) consisting of those packages as components. Because it relies on the Linux package manager as its source, the discovered packages are limited to those installed and managed using the Linux package manager.

Black Duck Docker Inspector can discover package manager-installed components in Linux Docker images that use the DPKG, RPM, or APK package manager database formats.

Black Duck Docker Inspector can inspect non-Linux images (for example, Windows images, and images that contain no operating system), but will discover zero components. This can be useful if the target image container file system that Black Duck Docker Inspector can produce as output is needed for signature scanning.

After running the Black Duck Docker Inspector on an image, navigate to Black Duck to view the BOM created by Black Duck Docker Inspector.

Modes of operation

Black Duck Docker Inspector has two modes:

  • Host mode, for running on a server or virtual machine (VM) where Black Duck Docker Inspector can perform Docker operations using a Docker Engine.
  • Container mode, for running in a container started by Docker, Kubernetes, OpenShift, and others.

Host mode

Host mode (default) is for servers/VMs where Black Duck Docker Inspector can perform Docker operations using a Docker Engine.

In host mode, Black Duck Docker Inspector is a utility that automates the process of using Black Duck to discover security, license, and operational risks associated with Linux-based Docker images. It discovers components using the target Docker image's package manager; therefore, the results are limited to those components (packages) of which the package manager is aware. Black Duck Docker Inspector does this without running the image, so it is safe to run on untrusted images.

Black Duck Docker Inspector can pull the target image; in other words, the Docker image you want to inspect, from a Docker registry such as Docker Hub. Alternatively, you can save an image to a .tar file by using the docker save command. Then, run Black Duck Docker Inspector on the .tar file. Black Duck Docker Inspector supports Docker Image Specification v1.2.0 format .tar files.

Container mode

Container mode is for container orchestration environments; for example, Kubernetes, OpenShift, and others, where Black Duck Docker Inspector runs inside a container where it cannot perform Docker operations. For information on running Black Duck Docker Inspector in container mode, refer to Deploying.

Requirements

Requirements for Black Duck Docker Inspector are:

  • The current version of Black Duck. Visit this page to determine the current version.
  • Linux, MacOS, or Windows 10 Enterprise.
    • On Windows, Black Duck Docker Inspector must be executed from Synopsys Detect version 6.6.0 or later, or by executing the Black Duck Docker Inspector .jar directly. There is no equivalent to blackduck-docker-inspector.sh for Windows.
  • Access to the internet. For information on running without access to the internet, refer to Air Gap mode.
  • Java (JRE) versions 8, 11, or 15.
  • Three available ports for the image inspector services. By default, these ports are 9000, 9001, and 9002.
  • The environment must be set up such that files created by Black Duck Docker Inspector are readable by all. On Linux, this means an appropriate umask value (for example, 002 or 022 would work). On Windows, this means the working directory must be readable by all.
  • Image files passed to Black Duck Docker Inspector via the docker.tar property must be readable by all.
  • Image files passed to Black Duck Docker Inspector via the docker.tar property must be .tar files, and the contents must conform to either of the following image format specifications: 1. Docker Image Specification v1.2.0 (the format produced by the "docker save" command), or 2. Open Container Initiative Image Format Specification.
  • When invoking Black Duck Docker Inspector using blackduck-docker-inspector.sh:
    • curl
    • bash
  • In host mode: access to a Docker Engine versions 17.09 or higher.
  • In container mode: you must start the Black Duck Docker Inspector container that meets the preceding requirements, and three container-based "image inspector" services. All four of these containers must share a mounted volume and be able to reach each other through HTTP GET operations using base URLs that you provide. For more information, refer to Deploying.

Getting started

Invoking from Synopsys Detect

For many users, invoking Black Duck Docker Inspector from Synopsys Detect will be the best option. Synopsys Detect provides the following benefits:

  1. It automatically downloads (if necessary) the latest version of Black Duck Docker Inspector. This is the only way to get this capability on Windows.
  2. It discovers components that Black Duck Docker Inspector is unable to discover by also invoking the Black Duck Signature Scanner on the target image container file system.

Refer to the Synopsys Detect documentation for more information.

Invoking Black Duck Docker Inspector directly

The following command format always fetches and runs the latest version of Black Duck Docker Inspector:

bash <(curl -s https://blackducksoftware.github.io/blackduck-docker-inspector/blackduck-docker-inspector.sh) {Black Duck Docker Inspector arguments}

For example:

bash <(curl -s https://blackducksoftware.github.io/blackduck-docker-inspector/blackduck-docker-inspector.sh) --help
bash <(curl -s https://blackducksoftware.github.io/blackduck-docker-inspector/blackduck-docker-inspector.sh) --upload.bdio=false --docker.image=ubuntu

An alternative is to download and run the latest Black Duck Docker Inspector script:

curl -O  https://blackducksoftware.github.io/blackduck-docker-inspector/blackduck-docker-inspector.sh
chmod +x blackduck-docker-inspector.sh
./blackduck-docker-inspector.sh {Black Duck Docker Inspector arguments}

The advantage of using the Black Duck Docker Inspector script is that it ensures you always run the latest version of the Black Duck Docker Inspector .jar.

Another alternative is to download the Black Duck Docker Inspector .jar (using the script) and run the .jar directly:

bash <(curl -s https://blackducksoftware.github.io/blackduck-docker-inspector/blackduck-docker-inspector.sh) --pulljar
java -jar blackduck-docker-inspector-{version}.jar {Black Duck Docker Inspector arguments}

Passing arguments to Black Duck Docker Inspector

Running Black Duck Docker Inspector typically involves invoking the script or .jar with some command line arguments:

blackduck-docker-inspector.sh {Black Duck Docker Inspector arguments}

Black Duck Docker Inspector command line arguments consist of property assignments. Any supported property can be set by adding to the command line a property assignment of the form:

--{property name}={value}

Alternatively, any supported property can be set by adding to a text file named application.properties in the current directory a line of the form:

{property name}={value}

An application.properties file can contain multiple property assignments.

There are other alternative methods for setting properties. For more information, refer to Running.

Help

Available help topics:

  • overview (this page)
  • architecture
  • running
  • properties
  • advanced
  • deployment
  • troubleshooting
  • releasenotes
  • all

To display a help topic, run Black Duck Docker Inspector with either -h or --help followed by a topic. For example:

-h properties

To display multiple help topics, use a comma-separated list of help topics. For example:

-h overview,properties,running

To display all help topics, use topic all:

-h all

To write help to a file, add --help.output.path={directory or file path}:

-h all --help.output.format=html --help.output.path=.

Help content is output in Markdown format, which can be formatted ("pretty printed") using tools like mdless (https://brettterpstra.com/2015/08/21/mdless-better-markdown-in-terminal/).