Black Duck Docker Inspector

This content was generated by Docker Inspector version: 8.2.2-SNAPSHOT

Overview

Black Duck Docker Inspector inspects Docker images to discover packages (components). It utilizes the appropriate Linux package manager to provide a list of the installed (by the package manager) packages, 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 inspect Linux Docker images that support dpkg, rpm, or apk package manager formats.

After running the Black Duck Docker Inspector on an image, navigate to Black Duck to view the Bill of Materials (BOM) created by Black Duck Docker Inspector.

Modes of operation

Docker Inspector has two modes:

Host mode

Host mode (the default mode) is for Linux machines (and VMs) where Docker Inspector can perform Docker operations via 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. Docker Inspector supports Docker Image Specification v1.2.0 format .tar files.

Container mode

Container mode is for container orchestration environments (Kubernetes, OpenShift, etc.) where Docker Inspector will run inside a container, where it cannot perform Docker operations. For information on running Docker Inspector in container mode, refer to the deployment help topic.

Requirements

Requirements for Black Duck Docker Inspector are:

Getting started

The following command format will always fetch and run the latest version of Docker Inspector:

bash <(curl -s https://blackducksoftware.github.io/blackduck-docker-inspector/blackduck-docker-inspector.sh) {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 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 {Docker Inspector arguments}

The advantage of using the Docker Inspector script is that it will ensure you always run the latest version of the Docker Inspector .jar.

Another alternative is to download the 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 {Docker Inspector arguments}

Passing arguments to Docker Inspector

Usage: blackduck-docker-inspector.sh {Docker Inspector arguments} Docker Inspector 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}

There are other alternative methods for setting properties. For more information, refer to the running help topic.

Help

Available help topics:

To display a help topic, run 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 change the format of the help output to HTML, add --help.output.format=html: -h all --help.output.format=html

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

Architecture

Docker Inspector uses up to three container-based image inspector services (one for each of the supported Linux package manager database formats).

The three image inspector services provide coverage of the three package manager database formats: dpkg, rpm, and apk. By default, Docker Inspector submits its request (to inspect the target image) to the dpkg (ubuntu) image inspector service. Any service will redirect to the appropriate image inspector service if it cannot handle the request itself. For example, if the target image is a Red Hat image, the ubuntu inspector service (which cannot inspect a Red Hat image) will redirect to the centos inspector service (which can). If you know that most of your images have either rpm or apk databases, you can improve performance by configuring Docker Inspector to send requests to the centos (rpm) or alpine (apk) image inspector service using the imageinspector.service.distro.default property.

In host mode (the default), Docker Inspector automatically uses the Docker engine to pull as needed from Docker Hub three images: blackducksoftware/blackduck-imageinspector-alpine, blackducksoftware/blackduck-imageinspector-centos, and blackducksoftware/blackduck-imageinspector-ubuntu. Docker Inspector starts those services as needed, and stops and removes the containers when Docker Inspector exits. It uses a shared volume to share files, such as the target Docker image, between the Docker Inspector utility and the three service containers.

In container mode, you will start the container running Docker Inspector and the three image inspector container-based services such that all four containers share a mounted volume and can communicate with each other via HTTP GET operations using base URLs that you will provide. For information on how to do this, refer to the deployment help topic.

Execution phases

Host mode

In host mode, Docker Inspector performs the following steps on the host:

  1. Pulls and saves the target image to a .tar file (if you passed the image by repo:tag).
  2. Checks to see if the default image inspector service is running. If not, it pulls the image inspector image and starts a container, mounting a shared volume.
  3. Requests the Black Duck input/output (BDIO) file and container file system by sending an HTTP GET request to the image inspector service.

The following steps are performed inside the image inspector container:

  1. Builds the container file system that a container would have if you ran the target image. (It does not run the target image.)
  2. Determines the target image package manager database format, and redirects to a different image inspector service if necessary.
  3. Runs the image inspector's Linux package manager on the target image package manager database to get the list of installed packages.
  4. Produces and returns a BDIO (.jsonld) file consisting of a list of target image packages and, optionally, the container filesystem.

The following steps are performed back on the host when the request to the image inspector service returns:

  1. Uploads the BDIO file to Black Duck (this can be disabled).
  2. Copies the output files to the output directory.
  3. Stops/removes the image inspector container (this can be disabled).

Container mode

In container mode, you start four containers in such a way that they share a mounted volume and can reach each other via HTTP GET operations using base URLs that you provide:

In container mode, you must provide the image in a docker saved .tar file.

Docker Inspector:

  1. Requests the Black Duck input/output (BDIO) file and container file system using HTTP from the default image inspector service using a base URL that you have provided.

The following steps are performed inside the image inspector container:

  1. Builds the container file system that a container would have if you ran the target image. (It does not run the target image.)
  2. Determines the target image package manager database format, and redirects to a different image inspector service if necessary.
  3. Runs the image inspector's Linux package manager on the target image package manager database.
  4. Produces and returns a BDIO (.jsonld) file consisting of a list of target image packages and, optionally, the container filesystem.

The following steps are performed back in the Docker Inspector container when the request to the image inspector service returns:

  1. Uploads the BDIO file to Black Duck (this can be disabled).
  2. Copies the output files to the output directory.

Running Docker Inspector

Running a specific version

By default, blackduck-docker-inspector.sh runs the latest version of Docker Inspector (by downloading, if necessary, and running the latest Docker Inspector .jar). To run a specific version of Docker Inspector instead:

export DOCKER_INSPECTOR_VERSION={version}
./blackduck-docker-inspector.sh {Docker Inspector arguments}

For example:

export DOCKER_INSPECTOR_VERSION=8.1.0
./blackduck-docker-inspector.sh --upload.bdio=false --docker.image=ubuntu:latest

Running the .jar file

The advantage of running blackduck-docker-inspector.jar is that it ensures you alway run the latest version of Docker Inspector. However, sometimes it is better to run the .jar directly.

You can download any version of the Docker Inspector .jar from https://sig-repo.synopsys.com/webapp/#/artifacts/browse/tree/General/bds-integrations-release/com/synopsys/integration/blackduck-docker-inspector.

Use the java command to run it:

java -jar blackduck-docker-inspector-{version}.jar {Docker Inspector arguments}

Inspecting an image by image repo:tag

To run Docker Inspector on Docker image from your local cache or a registry:

./blackduck-docker-inspector.sh --docker.image={repo}:{tag}

If you omit the :{tag}, it will default to :latest.

Inspecting an image saved to a .tar file

To run Docker Inspector on a Docker image .tar file:

docker save -o {name}.tar {repo}:{tag}
./blackduck-docker-inspector.sh --docker.tar={name}.tar

If your tar file contains multiple images, Docker Inspector can only inspect one of them. You can specify which image you want to inspect using --docker.image.repo and --docker.image.tag. For example, to select ubuntu:latest from a .tar file that contains ubuntu:latest and other images:

./blackduck-docker-inspector.sh --docker.tar=multipleimages.tar --docker.image.repo=ubuntu --docker.image.tag=latest

Properties

Advanced topics

Isolating application components

If you are interested in components from the application layers of your image, but not interested in components from the underlying platform layers, you can exclude components from platform layers from the results.

For example, if you build your application on ubuntu:latest (your Dockerfile starts with FROM ubuntu:latest), you can exclude components from the ubuntu layer(s) so that the components generated by Docker Inspector contains only components from your application layers.

First, find the layer ID of the platform's top layer. To do this:

  1. Run the docker inspect command on the base image (in our example this is ubuntu:latest).
  2. Find the last element in the RootFS.Layers array. This is the platform top layer ID. In the following example, this is sha256:b079b3fa8d1b4b30a71a6e81763ed3da1327abaf0680ed3ed9f00ad1d5de5e7c.

Set the value of the Docker Inspector property docker.platform.top.layer.id to the platform top layer ID. For example:

./blackduck-docker-inspector.sh ... --docker.platform.top.layer.id=sha256:b079b3fa8d1b4b30a71a6e81763ed3da1327abaf0680ed3ed9f00ad1d5de5e7c

In this mode, the container file system and/or container file system squashed image produced by Docker Inspector will contain only files added to the image by application layers. If the Black Duck signature scanner is run on this file, it will generate results based only on files found on application layers. This provides the benefit of isolating application components by excluding platform components. However, there may be some loss in match accuracy from the signature scanner because, in this scenario, the signature scanner may be deprived of some contextual information (such as the operating system files that would enable it to determine the Linux distro), and that that may negatively affect it's ability to accurately identify components.

Concurrent execution

You can inspect multiple images in parallel on the same computer when you directly invoke the .jar file. For example:

# Get the latest blackduck-docker-inspector.sh
curl -O  https://blackducksoftware.github.io/blackduck-docker-inspector/blackduck-docker-inspector.sh
chmod +x ./blackduck-docker-inspector.sh

# Determine the current Black Duck Docker Inspector version
inspectorVersion=$(grep "^version=" blackduck-docker-inspector.sh|cut -d'"' -f2)

# Download the latest Black Duck Docker Inspector .jar file to the current dir
./blackduck-docker-inspector.sh --pulljar

# Execute multiple inspections in parallel
java -jar ./blackduck-docker-inspector-${inspectorVersion}.jar --blackduck.url={Black Duck url} --blackduck.username={Black Duck username} --docker.image=alpine:3.5  &
java -jar ./blackduck-docker-inspector-${inspectorVersion}.jar --blackduck.url={Black Duck url} --blackduck.username={Black Duck username} --docker.image=alpine:3.4  &
java -jar ./blackduck-docker-inspector-${inspectorVersion}.jar --blackduck.url={Black Duck url} --blackduck.username={Black Duck username} --docker.image=alpine:3.3  &

Alternative methods for setting property values

Docker Inspector gets its property values from Spring Boot's configuration mechanism. Docker Inspector users can leverage Spring Boot capabilities beyond command line arguments and environment variables (for example: hierarchy of property files, and placeholders) to manage properties in more sophisticated ways.

Passing passwords (etc.) in a more secure way

For greater security, sensitive property values such as passwords can be set via the environment variables using one of the Spring Boot configuration mechanisms mentioned above.

For example, instead of passing --blackduck.password=mypassword on the command line, you can do the following: export BLACKDUCK_PASSWORD=mypassword ./blackduck-docker-inspector.sh --blackduck.url=http://blackduck.mydomain.com:8080/ --blackduck.username=myusername --docker.image=ubuntu:latest

Refer to Spring Boot's configuration mechanism for more information on using this capability.

Air Gap mode

In Black Duck Docker Inspector versions 6.2.0 and higher, Black Duck provides an archive containing all files needed to run Black Duck Docker Inspector without access to the internet. To download the Air Gap archive, run the command:

./blackduck-docker-inspector.sh --pullairgapzip

To create the Docker images from the Air Gap archive required by Black Duck Docker Inspector, run the commands:

unzip blackduck-docker-inspector-{version}-air-gap.zip
docker load -i blackduck-imageinspector-alpine.tar
docker load -i blackduck-imageinspector-centos.tar
docker load -i blackduck-imageinspector-ubuntu.tar

To run in Air Gap mode, use the command:

./blackduck-docker-inspector.sh --upload.bdio=false --jar.path=./blackduck-docker-inspector-{version}.jar --docker.tar={tarfile}

Configuring Docker Inspector for your Docker Engine and Registry

If you invoke Docker Inspector with an image reference (a repo:tag value vs. a .tar file), it uses the docker-java library (https://github.com/docker-java/docker-java) to access the Docker registry to pull the image.

If ?docker pull ? works from the command line, then docker inspector should also be able to pull that image, because docker-java can be configured the same way as the docker command line utility.

But there are also other ways to configure docker-java. Details on how to configure docker-java (and therefore Docker Inspector) for your Docker registry can be found at: https://github.com/docker-java/docker-java#Configuration.

Docker Inspector does not override any of the configuration settings in the code, so all of the other methods (properties, system properties, system environment) are available to you.

If you choose to use environment variables, and you are calling Docker Inspector from Detect, you will need to prefix the environment variable names with "DETECT_DOCKER_PASSTHROUGH_" to instruct detect to pass them on to Docker inspector. So in that scenario, instead of "export SOMENAME=value", use "export DETECT_DOCKER_PASSTHROUGH_SOMENAME=value".

If you choose to use system properties (normally set using java -D), and you are calling Docker Inspector from Detect, you will need to put the properties in a file (e.g. mydockerproperties.properties) and use

--detect.docker.passthrough.system.properties.path=mydockerproperties.properties

to point Docker Inspector to those property settings.

Running Docker Inspector on Open Container Initiative (OCI) images

When given a docker image (--docker.image=repo:tag), Docker Inspector uses the docker-java library equivalent of docker save to save the image to a tar file. In this scenario, Docker Inspector should be able to pull, save, and inspect any image that could be pulled using a "docker pull" command. (Since Docker Inspector uses the docker-java library, the docker client executable does not actually need to be installed on the machine).

When given a saved docker tarfile (--docker.tar=image.tar), Docker Inspector requires a Docker Image Specification v1.2.0 format file. To inspect Open Container Initiative (OCI) format image files, we recommend using skopeo to convert them to Docker Image Specification v1.2.0 files. For example:

skopeo copy oci:alpine-oci docker-archive:alpine-docker.tar

will convert an OCI image directory alpine-oci to a Docker Image Specification v1.2.0 format file alpine-docker.tar that Docker Inspector can process when passed in with the --docker.tar=alpine-docker.tar command line argument.

Inspecting multiple images more efficiently (using host mode)

By default, docker inspector will start, use, and then stop/remove either one or two containerized image inspector services per run (per target image inspected). This may be appropriate when scanning a single image, but when scanning many images, it is highly inefficient.

The scanning of many images can be completed significantly faster by starting the image inspector services once, and running multiple instances of docker inspector so that each one sends requests to the already-running image inspector services.

The following script illustrates how this could be done in a Docker environment:

curl -O https://raw.githubusercontent.com/blackducksoftware/blackduck-docker-inspector/master/deployment/docker/batchedImageInspection.sh

To keep the example simple, this script only starts the alpine image inspector service. In general, you will likely also need to start two more services: the ubuntu image inspector service (for inspecting images built from dpkg-based linux distros), and the centos image inspector service (for inspecting images built from rpm-based linux distros). It doesn't matter which service receives the request; any service will redirect if necessary.

Running Detect on a project directory that exists within a Docker image

When you want to run Detect on a directory that exists within a docker image, you can use the following approach:

  1. Run Detect on the image to generate the container filesystem for the image.
  2. Run Detect on a directory within that container filesystem.

Detect performs these actions without running the image/container.

To see a simple example that illustrates this approach, use the following commands to download these sample files:

curl -O https://raw.githubusercontent.com/blackducksoftware/blackduck-docker-inspector/master/deployment/docker/runDetectInImageDir/runDetectInImageDir.sh
curl -O https://raw.githubusercontent.com/blackducksoftware/blackduck-docker-inspector/master/deployment/docker/runDetectInImageDir/Dockerfile

Please review the script before running it to make sure the side effects (files and directories that it creates) are OK. You'll need to make the script executable before you run it.

Running the signature scanner on a specific directory within a Docker image

If you want to scan (with iScan) a specific directory within an image, here at a very high level is how it could be done:

  1. Run docker inspector on the target image to get the container file system. You could also do this using Detect using --detect.docker.passthrough.* properties. Include the following Docker Inspector properties:
--upload.bdio=false                        # disable BDIO upload
--output.include.containerfilesystem=true  # tell DI to output the container file system
--output.path={your output dir}            # tell DI where to put the output
  1. Locate the container file system in the output dir (*.tar.gz) and untar it
  2. cd into the directory (within the untar?d container file system) that you want to scan.
  3. Invoke detect there.

Excluding files/directories from the returned container file system (which excludes them from Detect's signature scan)

If you want to exclude certain files and/ or directories from the returned file system, you can specify that list of directories with the --output.containerfilesystem.excluded.paths property.

For example, if you are invoking Docker Inspector from Detect, and want Detect to exclude the /etc and /usr/bin directories from the signature scan, you could run Detect like this:

./detect.sh --detect.docker.image=ubuntu:latest --detect.docker.passthrough.output.containerfilesystem.excluded.paths=/etc,/usr/bin

Deploying Docker Inspector

Deployment overview

Black Duck Docker Inspector can be run in either of the following modes:

  1. Host mode, on a Linux machine (or Linux VM) with Docker.
  2. Container mode, inside a container running on an orchestration platform such as Kubernetes, OpenShift, etc.

Each mode is discussed in detail below.

Important notes regarding deployment sample code

The deployment samples provided are intended to possible approaches to the challenges involved in deploying Docker Inspector. They are not intended to be used as-is in production. You should understand the code before you use it. They do not represent the only way to deploy in each environment.

Your deployment approach will be the same whether you are invoking Docker Inspector directly, or invoking it via Detect. Most of the sample deployments use Detect simply because that is the most common use case.

Using host mode on Linux machine (or Linux VM) with Docker

In this scenario, Docker Inspector is a command line utility that automatically pulls/runs and uses container-based services (and cleans them up when it's done). The Docker command, if installed on the machine, can be very useful for troubleshooting, but is not actually required or used by Docker Inspector.

In this mode Docker Inspector does require access to a Docker Engine (very similar to the way the Docker client requires access to a Docker Engine) so it can pull and run Docker images (it uses the https://github.com/docker-java/docker-java library to perform Docker operations via the Docker Engine).

In this mode, Docker Inspector automatically pulls, runs, stops, and removes the container-based image inspector services on which it depends. It accesses the services they provide via HTTP GET operations.

This is the default mode, and the simplest to use.

Using container mode in a container orchestration platform such as Kubernetes, OpenShift, etc.

In this scenario, Docker Inspector is a toolkit consisting of a command line utility (that you will run in one container), plus three container-based services (which you must start). These four containers must: (a) share a mounted volume (either persistent or temporary) that they will use to pass large files between containers, and (b) be able to reach each other via HTTP GET operations using base URLs that you will provide.

Image Inspector Services

Docker Inspector consists of a command line utility (provided in a Java .jar, but sometimes invoked via a bash script) and three image inspector services.

The required Docker operations (if any) are performed by the command line utility, while the image inspector services perform the work of unpacking the target Docker image, extracting the Linux package manager database, and running the Linux package manager against that database in order to extract installed packages and translate them to components (actually externalIds) for Black Duck. If the image inspector service finds in the target image a package manager database that is incompatible with its own package manager utility (this happens when, for example, you run Docker Inspector on an Alpine image, but the request goes to the Ubuntu image inspector service), the image inspector service will redirect the request to the appropriate image inspector service. You can change the default image inspector service to reduce the likelihood of redirects (resulting in shorter execution times). For example, if most of your target images are Alpine you can set imageinspector.service.distro.default to alpine.

The image inspector service containers are downloaded from Docker Hub (blackducksoftware/blackduck-imageinspector-*).

Deployment sample for Kubernetes

Approach: Toolkit

Deployment notes: Each image inspector service runs in a separate pod. The shared volume is a hostPath volume. The containers communicate via service URLs.

Download: curl -O https://raw.githubusercontent.com/blackducksoftware/blackduck-docker-inspector/master/deployment/kubernetes/setup.txt

Deployment sample for OpenShift

Approach: Toolkit

Deployment notes: All image inspector services run in a single pod. The shared volume is an emptyDir volume. The containers communicate via localhost URLs.

Download: curl -O https://raw.githubusercontent.com/blackducksoftware/blackduck-docker-inspector/master/deployment/openshift/setup.txt

Deployment sample for Travis CI

Approach: Toolkit

Deployment notes: Uses the Travis CI docker service. The containers communicate via localhost URLs.

Download: curl -O https://raw.githubusercontent.com/blackducksoftware/blackduck-docker-inspector/master/deployment/travisci/travis.yml

Deployment sample for GitLab CI

Approach: Toolkit

Deployment notes: Uses the GitLab CI shell executor. The containers communicate via localhost URLs.

Download: curl -O https://raw.githubusercontent.com/blackducksoftware/blackduck-docker-inspector/master/deployment/gitlabci/setup.sh

Deployment sample for Circle CI

Approach: Utility

Deployment notes:

Download: curl -O https://raw.githubusercontent.com/blackducksoftware/blackduck-docker-inspector/master/deployment/circleci/config.yml

Deployment sample for Docker, with Detect running in container

Approach: Toolkit

Deployment notes: The containers communicate via localhost URLs.

Download: https://raw.githubusercontent.com/blackducksoftware/blackduck-docker-inspector/master/deployment/docker/runDetectInContainer/setup.sh

Configuring Docker Inspector for your Docker Registry

If you invoke Docker Inspector with an image reference (vs. an image that has been saved to a .tar file), it uses the docker-java library (https://github.com/docker-java/docker-java) to access the Docker registry to pull the image.

If docker pull {targetimage} works from the command line, then docker inspector should also be able to pull that image, because docker-java can be configured the same way as the docker command line utility.

But there are also other ways to configure docker-java. Details on how to configure docker-java (and therefore Docker Inspector) for your Docker registry can be found at: https://github.com/docker-java/docker-java#Configuration.

Docker Inspector does not override any of the configuration settings in the code, so any of the other methods (properties, system properties, system environment) should work.

If you choose to use environment variables, and you are calling Docker Inspector from Detect, you will need to prefix the environment variable names with DETECT_DOCKER_PASSTHROUGH_ to instruct detect to pass them on to Docker inspector. So in that scenario, instead of export SOMENAME=value, use export DETECT_DOCKER_PASSTHROUGH_SOMENAME=value.

If you choose to use system properties (normally set using java -D), and you are calling Docker Inspector from Detect, you will need to put the properties in a file (e.g. mydockerproperties.properties) and use

--detect.docker.passthrough.system.properties.path=mydockerproperties.properties

to point Docker Inspector to those property settings.

Troubleshooting

To troubleshoot issues with Docker Inspector, run with DEBUG logging:

--logging.level.com.synopsys=DEBUG

Here are suggestions related to specific problems:

Problem: When directly invoking the .jar file, an error message displays which reads "Malformed input or input contains unmappable characters."

Possible cause: Your local character encoding does not match the target container file system character encoding.

Solution/workaround: Set the character encoding to UTF-8 when invoking java:

java -Dfile.encoding=UTF-8 ...

Problem: You must run Black Duck Docker Inspector on a non-Linux computer.

Solution/workaround: You may be able to run Black Duck Docker Inspector within a Linux Docker container running on your non-Linux computer using the following process.

Warning: This method involves running a privileged container which will not be acceptable in some environments.

On your non-Linux computer, run:

docker run -it -d --name inspectorhost --privileged blackducksoftware/blackduck-imageinspector-ubuntu:3.0.0
docker attach inspectorhost

Then, in the inspectorhost container, run:

mkdir -p /opt/blackduck/dockerinspector
cd /opt/blackduck/dockerinspector
apt-get update
apt-get install -y apt-transport-https ca-certificates curl software-properties-common default-jre vim
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | apt-key add -
add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
apt-get install -y docker-ce
dockerd --storage-driver=vfs  &
curl -O https://blackducksoftware.github.io/blackduck-docker-inspector/blackduck-docker-inspector.sh; chmod +x blackduck-docker-inspector.sh
dockerd --storage-driver=vfs 2> dockerd_stderr.log > dockerd_stdout.log &
./blackduck-docker-inspector.sh  ...

It's possible that additional steps such as configuration of dockerd, logging into the Docker registry, and others, are required to give Docker running inside the inspectorhost container access to the Docker images that Black Duck Docker Inspector must pull. One way to reduce extra steps is to save the target Docker image as a .tar file on your computer, use docker cp to copy it into the container, and run Black Duck Docker Inspector on that .tar file.

Problem: Property values being set in unexpected ways.

Possible cause: Black Duck Docker Inspector is built using the Spring Boot application framework. Spring Boot provides a variety of ways to set property values. This can produce unexpected results if, for example, you have an environment variable whose name maps to a Black Duck Docker Inspector property name. Refer to the Spring Boot documentation for more details.

Problem: The image inspector service cannot write to the mounted volume; SELinux is enabled

When this happens, the following error may appear in the container log:

Exception thrown while getting image packages: Error inspecting image: /shared/run_.../output/..._containerfilesystem.tar.gz (Permission denied)
...
Caused by: java.io.FileNotFoundException: /opt/blackduck/hub-imageinspector-ws/shared/run_.../output/..._containerfilesystem.tar.gz (Permission denied)

Possible cause: SELinux policy configuration.

Solution/workaround: Add the svirt_sandbox_file_t label to Docker Inspector's shared directory. This enables the Docker Inspector services running in Docker containers to write to it:

sudo chcon -Rt svirt_sandbox_file_t /tmp/blackduck-docker-inspector-files/shared/

Problem: The image inspector service cannot read from the mounted volume

When this happens, the following error may appear in the container log:

Error inspecting image: /shared/run_.../{image}.tar (Permission denied)

Possible cause: The Linux umask value on the machine running Docker Inspector is too restrictive.

Solution/workaround: Set umask to 022 when running Docker Inspector. The cause could be a umask value that prevents read access to the file, or read or execute access to the directory. Docker Inspector requires an umask value that does not remove read permissions from files, and does not remove read or execute permissions from directories. For example, a umask of 022 works.

Problem: Docker Inspector cannot perform any Docker operations because the remote access port is not enabled on the Docker engine

When this happens, the following error may appear in the log:

Error inspecting image: java.io.IOException: Couldn't load native library
Stack trace: javax.ws.rs.ProcessingException: java.io.IOException: Couldn't load native library

In older versions of Docker Inspector (prior to 8.2.0), the logged error was:

Error inspecting image: Could not initialize class org.newsclub.net.unix.NativeUnixSocket
Stack trace: java.lang.NoClassDefFoundError: Could not initialize class org.newsclub.net.unix.NativeUnixSocket

Possible cause: The tcp socket (for remote access) is not enabled on the Docker engine. For more information, refer to the Docker documentation.

Solution/workaround: Follow the instructions in the Docker documentation to open the tcp port on the Docker engine.

Release notes

Version 8.2.1

Resolved issues

Version 8.2.0

New features

Version 8.1.6

Changed feature

Version 8.1.5

Resolved issues

Version 8.1.4

New features

Version 8.1.3

New features

Version 8.1.2

Changed features

Version 8.1.1

Resolved issues

Version 8.1.0

Resolved issues
New features

Version 8.0.2

Resolved issues

Version 8.0.1

Resolved issues
New features

Version 8.0.0

New features
Removed features

Version 7.3.3

Resolved issues

Version 7.3.2

Resolved issues

Version 7.3.1

Resolved issues

Version 7.3.0

New features

Version 7.2.4

Resolved issues

Version 7.2.3

Changed features

Version 7.2.2

Resolved issues

Version 7.2.1

Resolved issues

Version 7.2.0

New features
Resolved issues

Version 7.1.0

Changed features

Version 7.0.1

Resolved issues

Version 7.0.0

Changed features
Resolved issues

Version 6.3.1

Resolved issues

Version 6.3.0

New features

Version 6.2.0

Resolved issues
New features

Version 6.1.0

Resolved issues

Version 6.0.4

Resolved issues

Version 6.0.3

Resolved issues

Version 6.0.2

Resolved issues

Version 6.0.1

Resolved issues
New features

Version 6.0.0

New features
Changed features

Version 5.1.0

New features
Resolved issues

Version 5.0.0

Removed features
Resolved issues

Version 4.4.1

Resolved issues

Version 4.4.0

New features
Resolved issues
Changed features

Version 4.3.2

Resolved issues

Version 4.3.1

Resolved issues

Version 4.3.0

New features

Version 4.2.0

New features

Version 4.1.0

New features

Version 4.0.3

Resolved issues

Version 4.0.2

Resolved issues

Version 4.0.1

Resolved issues

Version 4.0.0

New features
Removed features

Version 3.2.1

Resolved issues

Version 3.2.0

New features

Version 3.1.2

Resolved issues

Version 3.1.1

Resolved issues

Version 3.1.0

New features
Resolved issues

Version 3.0.0

New features
Removed features
Resolved issues

Version 2.1.2

Resolved issues

Version 2.1.1

Resolved issues

Version 2.1.0

New features

Version 2.0.0

Resolved issues

Version 1.2.1

Resolved issues

Version 1.2.0

Resolved issues
Resolved issues causing Hub Docker Inspector to fail when the current directory path or the given .tar file path contained spaces.

Version 1.1.1

Resolved issues

Version 1.1.0

Resolved issues
Known issues

Version 1.0.2

Resolved issues
Known issues

Version 1.0.1

Resolved issues
Known issues

Version 1.0.0

Resolved issues
Known issues

Version 0.1.4

Resolved issues
Known issues

Version 0.1.3

Resolved issues
Known issues

Version 0.1.2

Resolved issues
Known issues

Version 0.1.1

Resolved issues
Known issues

Version 0.1.0

New features
Resolved issues
Known issues

Version 0.0.4

Known issues