Running

Considerations when running on Windows

Run from Synopsys Detect version 6.6.0 or later, or run the Black Duck Docker Inspector .jar file directly

The following is only a consideration if you are not running Black Duck Docker Inspector from Synopsys Detect.

When executing Black Duck Docker Inspector directly on Linx or Mac, you can use the Black Duck Docker Inspector bash script blackduck-docker-inspector.sh that:

  1. Downloads (if necessary) the latest Black Duck Docker Inspector .jar file, and
  2. Executes it with the arguments you have provided.

There is no equivalent script for Windows, so on Windows you must download the Black Duck Docker Inspector .jar and execute it directly.

Download the Black Duck Docker Inspector .jar file from the Synopsys artifactory server.

To execute the Black Duck Docker Inspector .jar:

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

Docker file sharing settings

Black Duck Docker Inspector requires the ability to share directories with the image inspector containers. It shares a directory with image inspector containers by mounting it as a volume. You will need to configure your Docker settings to enable this file sharing. The simplest way to do this is to add your home directory as a sharable directory on the Docker settings Resources > FILE SHARING screen.

The shared directories are created under the value of property shared.dir.local.path, so if you change the directory that property points to, be sure your Docker file sharing settings enable sharing of that directory.

Docker restrictions

Docker on Windows has restrictions that impact Black Duck Docker Inspector:

  1. Docker can be configured to pull either Linix images, or Windows images. You can see how your Docker installation is configured by looking at the OSType value in the output of the docker info command. If Docker is configured for Linix images, it cannot pull Windows images, and vice versa. The command to change Docker's OSType value appears in the Docker Desktop menu. Refer to Docker documentation for more information.
  2. When pulling Windows images, Docker requires (a) that the architecture of the pulled image matches the architecture of your machine, and (b) that the Windows version of the pulled image is a close match to the Windows version of your machine.

It is a good practice to make sure you can pull the target image using the docker pull command from the command line. If Docker cannot pull the image, then Black Duck Docker Inspector won't be able to either. If you cannot pull the image from the command line, consider both of the potential issues mentioned above.`

Running the latest version (Linux/Mac only)

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 that you are always running 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}

Running a specific version (Linux/Mac only)

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

export DOCKER_INSPECTOR_VERSION={version}
./blackduck-docker-inspector.sh {Black Duck 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.sh is that it ensures that you always run the latest version of Black Duck Docker Inspector. However, sometimes it is better to run the .jar directly.

You can download any version of the Black Duck 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 following Java command to run it:

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

Inspecting an image by image repo:tag

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

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

Or:

java -jar blackduck-docker-inspector-{version}.jar --docker.image={repo}:{tag}

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

Inspecting an image saved to a .tar file

To run Black Duck 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, Black Duck Docker Inspector can only inspect one of them. You can specify the image 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

Inspecting a local image by image ID

When inspecting a local image, you have the option of specifying the image by its ID. First, get the image ID from the IMAGE ID column of the output of the docker images command. Then use the docker.image.id property to pass the image ID to Black Duck Docker Inspector:

./blackduck-docker-inspector.sh --docker.image.id={image ID}

The method only works for local images.