Tern is an inspection tool to find the metadata of the packages installed in a container image. The overall operation looks like this:

1. It analyzes the first layer of the container image to collect information like distro type, package format, and package managers.
2. It then executes scripts from the "command library" in a chroot environment to collect information about packages installed in that layer.
3. With that information as a starting point, it continues to analyze the subsequent layers in the container image.
4. Once done, it generates a report of packages with their metadata. Several formats are available. The report, in its default format, provides a layer by layer, explanation of the various software components imported. If a Dockerfile is provided, the report indicates the Dockerfile lines corresponding to each of the file system layers.

Tern gives you a deeper understanding of your container's bill of materials so you can make better decisions about your container based infrastructure, integration and deployment strategies. It's also a good tool if you are curious about the contents of the container images you have built.

If you have a Linux OS you will need a distro with a kernel version >= 4.0 (Ubuntu 16.04 or newer or Fedora 25 or newer are good selections) and will need to install the following requirements:

Docker is the most widely used tool to build and run containers. If you already have Docker installed, you can run Tern by building a container with the Dockerfile provided.

Clone this repository:

git clone https://github.com/tern-tools/tern.git

Build the Docker image (called ternd here). You may need to use sudo:

docker build -f docker/Dockerfile -t ternd .

This will install the latest release of tern using pip.

If you want to build a Docker image containing the latest changes to tern, run:

python setup.py sdist
docker build -f ci/Dockerfile -t ternd .

NOTE: By default, Tern will run with logging turned on. If you would like to silent the terminal output when running the ternd container, make the following change to the Dockerfile ENTRYPOINT before building:

--- a/Dockerfile
+++ b/Dockerfile
-ENTRYPOINT ["tern"]
+ENTRYPOINT ["tern", "-q"]

Run the ternd container image

docker run --rm ternd report -i debian:buster

If you are using this container to analyze Dockerfiles and to use the "lock" feature, then you must volume mount the docker socket. We have a convenience script which will do that for you.

./docker_run.sh ternd "report -i debian:buster" > output.txt

To produce a json report run

./docker_run.sh ternd "report -f json -i debian:buster"

A Tern container can be deployed on Kubernetes as a Job. However, a host mount is required to retrieve the reports. We will describe below how to create a Kubernetes Job within minikube.

Vagrant is a tool to setup an isolated virtual software development environment. If you are using Windows or Mac OSes and want to run Tern from the command line (not in a Docker container) this is the best way to get started as Tern does not run natively in a Mac OS or Windows environment at this time.

Install

If you have a Docker image pulled locally and want to inspect it

tern report -i debian:jessie

The SBOM of packages that are installed in the Docker image and how Tern got this information will be printed to the console. To direct this output to a file, use the -o file_name command line option. If you encounter any errors, please file an issue.

You can provide a Dockerfile to Tern to figure out the Software Bill of Materials and other information. Tern will build the image, analyze it with respect to the Dockerfile and discard the image. This is useful to engineers who are developing a Dockerfile for their app or in a container build and release pipeline.

tern report -d samples/photon_git/Dockerfile

The SBOM of packages you would be shipping if you were to use the given Dockerfile will print to the console. To direct the output to a file, use the -o file_name command line option. Feel free to try this out on the other sample Dockerfiles in the samples directory or on Dockerfiles you may be working with. If it doesn't work for you, please file an issue.

Because of the way Docker builds containers, Dockerfiles are generally not declarative or reflective of what ultimately gets included in the container image that gets produced. Pinning information in your Dockerfile (base OS, packages, etc.) can help create more reproducible container images should your Dockerfile be distributed to other parties. If you have a Dockerfile that you would like to lock to a more reproducible version, Tern can help.

tern lock Dockerfile

The locked Dockerfile will be created in Dockerfile.lock unless an output file is otherwise specified. To specify an output file

tern lock Dockerfile -o output.txt

If the packages are not pinned in the resulting Dockerfile.lock or output file that gets produced, it is because 1) Tern does not know the version of the packages to pin (i.e. unable to get this information from the package manager) or 2) your Dockerfile failed to build. In the case of a failed Dockerfile build, Tern only builds the base image and tries to pin what it can. If you encounter any errors, please file an issue.

Tern provides a handful of different reporting styles that may work better for different applications of distribution, interoperability and comprehension. Understanding these reports will vary slightly between formats, but the information in the different report formats will generally be the same with varying degrees of package metadata detail. In all report formats, information about the version of Tern that generated the report and any applicable extension information will be at the top of the report followed by information about the metadata found in the container, organized sequentially by layer.

The base layer (Layer 1) will provide operating system information on which the container is based, the Dockerfile command that created the layer, the package retrieval method and any packages found in the layer. Note that the operating system information may be different than the container that Tern is generating an SBOM for. For example, the golang container's base OS is actually Debian GNU/Linux 10 (buster). For each subsequent layer in the container, information about the Dockerfile command that created the container layer, any warnings about unrecognized Dockerfile commands, the package retrieval method and package information is provided. If Tern doesn't find any package information in a layer, it will report packages found in the layer as "None". File licenses may also be available in the reports if Tern is run using scancode.

More information about specific reporting formats can be found below and in the tern/classes directory where the properties being reported on are explained in the .py files -- specifically, image_layer.py, package.py, and file_data.py.

The default report Tern produces is a human readable, high-level overview. The object of this report is to give the container developer a deeper understanding of what is installed in a container