Clair scanner

Docker containers vulnerability scan

When you work with containers (Docker) you are not only packaging your application but also part of the OS. It is crucial to know what kind of libraries might be vulnerable in your container. One way to find this information is to look at the Docker registry [Hub or Quay.io] security scan. This means your vulnerable image is already on the Docker registry.

What you want is a scan as a part of CI/CD pipeline that stops the Docker image push on vulnerabilities:

Build and test your application
Build the container
Test the container for vulnerabilities
Check the vulnerabilities against allowed ones, if everything is allowed then pass otherwise fail

This straightforward process is not that easy to achieve when using the services like Docker Hub or Quay.io. This is because they work asynchronously which makes it harder to do straightforward CI/CD pipeline.

Clair to the rescue

CoreOS has created an awesome container scan tool called Clair. Clair is also used by Quay.io. What clair does not have is a simple tool that scans your image and compares the vulnerabilities against a whitelist to see if they are approved or not.

This is where clair-scanner comes into place. The clair-scanner does the following:

Scans an image against Clair server
Compares the vulnerabilities against a whitelist
Tells you if there are vulnerabilities that are not in the whitelist and fails
If everything is fine it completes correctly

Clair server or standalone

For the clair-scanner to work, you need a clair server. It is not always convenient to have a dedicated clair server, therefore, I have created a way to run this standalone. See here https://github.com/arminc/clair-local-scan

Credits

The clair-scanner is a copy of the Clair 'analyze-local-images' https://github.com/coreos/analyze-local-images with changes/improvements and addition that checks the vulnerabilities against a whitelist.

Install

clair-scanner is available on Linux, MacOS, and Windows platforms.

Binaries for Linux, Windows, and Mac are available in the releases page.

You can also install from source. To do so you must:

Have go 1.9+ installed
Have dep installed
Clone the repo
Build and install the executable

# Clone the repo
go get -d -u github.com/arminc/clair-scanner
cd $GOPATH/src/github.com/arminc/clair-scanner
# Build and install
make ensure && make installLocal
# Run
clair-scanner -h

Build

clair-scanner is built with Go 1.9 and uses dep as dependencies manager. Use the Makefile to build and install dependencies.

make ensure && make build

Cross compile:

make cross

Run

Example of a container scan, start Clair:

docker run -p 5432:5432 -d --name db arminc/clair-db:2017-09-18
docker run -p 6060:6060 --link db:postgres -d --name clair arminc/clair-local-scan:v2.0.6

Now scan a container, that has a whitelisted CVE (this is on OSX with Docker for Mac):

clair-scanner -w example-alpine.yaml --ip YOUR_LOCAL_IP alpine:3.5

Output:

2017/09/24 11:20:24 [INFO] ▶ Start clair-scanner
2017/09/24 11:20:24 [INFO] ▶ Server listening on port 9279
2017/09/24 11:20:24 [INFO] ▶ Analyzing 693bdf455e7bf0952f8a4539f9f96aa70c489ca239a7dbed0afb481c87cbe131
2017/09/24 11:20:24 [INFO] ▶ Image [alpine:3.5] not vulnerable

Or a container that does not have a whitelisted CVE (this is on OSX with Docker for Mac):

clair-scanner --ip YOUR_LOCAL_IP alpine:3.5

Output:

2017/09/24 11:16:41 [INFO] ▶ Start clair-scanner
2017/09/24 11:16:41 [INFO] ▶ Server listening on port 9279
2017/09/24 11:16:41 [INFO] ▶ Analyzing 693bdf455e7bf0952f8a4539f9f96aa70c489ca239a7dbed0afb481c87cbe131
2017/09/24 11:16:41 [CRIT] ▶ Image contains unapproved vulnerabilities: [CVE-2016-9840 CVE-2016-9841 CVE-2016-9842 CVE-2016-9843]

Help information

$ ./clair-scanner -h

Usage: clair-scanner [OPTIONS] IMAGE

Scan local Docker images for vulnerabilities with Clair

Arguments:
  IMAGE=""     Name of the Docker image to scan

Options:
  -w, --whitelist=""                    Path to the whitelist file
  -t, --threshold="Unknown"             CVE severity threshold. Valid values; 'Defcon1', 'Critical', 'High', 'Medium', 'Low', 'Negligible', 'Unknown'
  -c, --clair="http://127.0.0.1:6060"   Clair URL
  --ip="localhost"                      IP address where clair-scanner is running on
  -l, --log=""                          Log to a file
  --all, --reportAll=true               Display all vulnerabilities, even if they are approved
  -r, --report=""                       Report output file, as JSON
  --exit-when-no-features=false         Exit with status code 5 when no features are found for a particular image

Example whitelist yaml file

This is an example yaml file. You can have an empty file or a mix with only generalwhitelist or images.

generalwhitelist: #Approve CVE for any image
  CVE-2017-6055: XML
  CVE-2017-5586: OpenText
images:
  ubuntu: #Approve CVE only for ubuntu image, regardles of the version. If it is a private registry with a custom port registry:777/ubuntu:tag this won't work due to a bug.
    CVE-2017-5230: Java
    CVE-2017-5230: XSX
  alpine:
    CVE-2017-3261: SE

Troubleshooting

If you get [CRIT] ▶ Could not save Docker image [image:version]: Error response from daemon: reference does not exist, this means that image image:version is not locally present. You should have this image present locally before trying to analyze it (e.g.: docker pull image:version).

Errors like [CRIT] ▶ Could not analyze layer: Clair responded with a failure: Got response 400 with message {"Error":{"Message":"could not find layer"}} indicates that Clair can not retrieve a layer from clair-scanner. This means that you probably specified a wrong IP address in options (--ip). Note that you should use a publicly accessible IP when clair is running in a container, or it wont be able to connect to clair-scanner. If clair is running inside the docker, use the docker0 ip address. You can find the docker0 ip address by running ifconfig docker0 | grep inet

[CRIT] ▶ Could not read Docker image layers: manifest.json is not valid fires when image version is not specified and is required. Try to add :version (.e.g. :latest) after the image name.

[CRIT] ▶ Could not analyze layer: POST to Clair failed Post http://docker:6060/v1/layers: dial tcp: lookup docker on 127.0.0.53:53: no such host indicates that clair server could ne be reached. Double check hostname and port in -c argument, and your clair settings (in clair's docker-compose.yml for instance if you run it this way).

Release

To make a release create a tag and push it

ApollusEHS-OSS/clair-scanner