Clair

Clair is an open source project for the static analysis of vulnerabilities in AppC and Docker containers.

Clair imports vulnerability data from a known set of sources and indexes the contents of container images in order to produce a list of vulnerabilities that threaten a container. When vulnerability data changes upstream, Clair can notify an endpoint via a webhook. This notification includes the ability for the endpoint to access the previous state and new state of the vulnerability and the images they affect. Clair can be programmatically extended with new data sources or data injected directly via API.

Clair enables a more transparent view of the security of container-based infrastructure. Thus, the project was named Clair after the French term which translates to clear, bright, transparent.

Common Use Cases

Manual Auditing

You're building an application and want to depend on a third-party container image that you found by searching the internet. To make sure that you do not knowingly introduce a new vulnerability into your production service, you decide to scan the container for vulnerabilities. You docker pull the container to your development machine and start an instance of Clair. Once it finishes updating, you use the local image image analysis tool to analyze the container. You realize this container is vulnerable to many critical CVEs, so you decide to use another one.

Container Registry Integration

Your company has a continuous-integration pipeline and you want to stop deployments if they introduce a dangerous vulnerability. A developer merges some code into the master branch of your codebase. The first step of your continuous-integration pipeline automates the testing and building of your container and pushes a new container to your container registry. Your container registry notifies Clair and Clair proceeds to download and index the images for the new container. Clair detects some vulnerabilities and sends a webhook to your continuous deployment tool to prevent this vulnerable build from seeing the light of day.

Hello Heartbleed

Requirements

Clair requires an instance of PostgreSQL 9.4+. All instructions assume the user has already setup this instance. During the first run, Clair will bootstrap its database with vulnerability data from its data sources. This can take several minutes.

Docker

The easiest way to get an instance of Clair running is to simply pull down the latest copy from Quay.

$ mkdir $HOME/clair_config
$ curl -L https://raw.githubusercontent.com/coreos/clair/config.example.yaml -o $HOME/clair_config/config.yaml
$ $EDITOR $HOME/clair_config/config.yaml # Add the URI for your postgres database
$ docker run quay.io/coreos/clair -p 6060-6061:6060-6061 -v $HOME/clair_config:/config -config=config.yaml

Source

To build Clair, you need to latest stable version of Go and a working Go environment.

$ mkdir -p $PWD/clair/src/github.com/coreos
$ git clone git@github.com:coreos/clair.git $PWD/clair/src/github.com/coreos/clair
$ export GOPATH=$PWD/clair
$ cd $PWD/clair/src/github.com/coreos/clair
$ go install ./cmd/clair
$ $EDITOR config.yaml # Add the URI for your postgres database
$ ./$GOBIN/clair -config=config.yaml

Architecture

At a glance

Vulnerability Analysis

There are two major ways to perform analysis of programs: Static Analysis and Dynamic Analysis. Clair has been designed to perform static analysis. Thus, Clair does not execute containers nor does it require execution alongside running containers. Rather, Clair inspects the filesystem of the container image and attempts to index features into a database. Features are anything that when present could be an indication of a vulnerability (e.g. the presence of a file or an installed software package). By indexing the features of an image into the database, Clair can query for affected images when new vulnerabilities get introduced without rescanning any images.

Data Sources

Data Source	Versions	Format
Debian Security Bug Tracker	6, 7, 8, unstable	dpkg
Ubuntu CVE Tracker	12.04, 12.10, 13.04, 14.04, 14.10, 15.04, 15.10, 16.04	dpkg
Red Hat Security Data	5, 6, 7	rpm

Custom Data Sources

In addition to the default data sources, Clair has been designed in a way that allows extension without forking the project. Fetchers, which are Go packages that implement the fetching of upstream vulnerability data, are registered in init() similar to drivers for Go's standard database/sql package. A fetcher can live in its own repository and custom versions of clair can contain a small patch that adds the import statements of the desired fetchers in main.go.

Related Links

• Talk and Slides @ ContainerDays NYC 2015
• Quay: the first container registry to integrate with Clair
• Dockyard: an open source container registry with Clair integration