How to use Clair to scan Docker images

Tutorial prerequisites

This Clair tutorial focuses on local container scanning as a proof of concept. To follow along, set up:

• an Ubuntu 18.04 host;
• the latest release version of Docker; and
• Docker Compose, a tool to define and run multi-container Docker applications.

Install Docker Compose with the command:

 (sudo apt install docker-compose -y)

The Clair system in this tutorial consists of a PostgreSQL back-end server, a middleware server and an end-user tool -- in our case, clairctl, a command-line interface checking tool. The tutorial uses all these items inside a Docker environment.

System setup

Docker Compose enables us to stand up several discrete Docker images at once and control them as one unit.

From an SSH prompt on the host -- ensure you start in your home directory -- use the following commands in the order listed:

mkdir -p clair/docker-compose-data/clair-config
wget https://raw.githubusercontent.com/jgsqware/clairctl/master/docker-compose.yml --directory-prefix=clair/docker-compose-data/
wget https://raw.github.com/jgsqware/clairctl/master/docker-compose-data/clair-config/config.yml --directory-prefix=clair/clair-config/
cd clair/docker-compose-data

Within the clair-config folder is the Clair server configuration. Once you execute the commands above and check the details, use the following command to start up the process:

       docker-compose up

This will automatically stand up the PostgreSQL database, the Clair middleware server and clairctl as a local command-line scanner. Initially, the database back end will take several minutes to download all the CVE data.

Note: You'll see fatal errors about a failed-to-load configuration -- these are purely cosmetic in terms of our requirements for scanning Docker containers in this tutorial. The URLs we pull down are looking for a Clair config file, but, for simplicity's sake, we use one to keep this tutorial simple and concise. Despite the fatal marker, these errors do not affect the next steps of the process.

After several minutes, the entire system should be ready to scan for vulnerabilities. In another SSH shell, check that all the Docker containers are up and running.

Scan a vulnerable image

At this point, we need a vulnerable image. A few specially made vulnerable images, including Damn Vulnerable Web Application, can test that a scanning tool works as intended. Only use this image to test that Clair works; it is riddled with bugs by design.

To specify this vulnerable image to be scanned, from the Ubuntu server, use the following command:

	docker pull infoslack/dvwa

Once the image has been pulled down, use this command to test it:

	docker-compose exec clairctl clairctl analyze -l infoslack/dvwa

Here, docker-compose exec clairctl tells the Docker environment to execute the following command on Docker container clairctl. The rest of the command details the image to test, which in this example is clairctl analyze -l vulnerables/web-dvwa.

At this point, scan the Docker image for vulnerabilities with Clair. Then, create an HTML report on the scan, as shown in Figure 2. These HTML reports detail the CVEs of the scanned image and give a short synopsis of each vulnerability.

To create a report, use the clairctl command again but specify the report option, as shown below:

	docker-compose exec clairctl clairctl report -l infoslack/dvwa

The reports are written to the reports folder on the Docker host, underneath the docker-compose-data folder. If the Clair Docker instance is on a remote VM, install Lynx, a text web browser, to read the reports on the host. This step means you don't need to copy the files off the VM. Use the command:

	sudo apt install lynx -y

Now, navigate to the reports folder and use the command:

	Lynx "html file to view".html

If desired, use the scp command to copy it across to your desktop. Admins can also set up a web server as an additional component of the Docker Compose group.