master branch may be in an unstable or even broken state during development.
Please use releases instead of the
master branch in order to get stable binaries.
Vulnerability data is continuously imported from a known set of sources and correlated with the indexed contents of container images in order to produce lists of vulnerabilities that threaten a container. When vulnerability data changes upstream, the previous state and new state of the vulnerability along with the images they affect can be sent via webhook to a configured endpoint. All major components can be customized programmatically at compile-time without forking the project.
Our goal is to enable 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
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.
docker pull the container to your development machine and start an instance of Clair.
Once it finishes updating, you use the local 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 which causes the download and indexing of 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.
During the first run, Clair will bootstrap its database with vulnerability data from its data sources. It can take several minutes before the database has been fully populated.
NOTE: These setups are not meant for production workloads, but as a quick way to get started.
An easy way to run Clair is with Kubernetes 1.2+. If you are using the CoreOS Kubernetes single-node instructions for Vagrant you will be able to access the Clair's API at http://172.17.4.99:30060/ after following these instructions.
git clone https://github.com/coreos/clair cd clair/contrib/k8s kubectl create secret generic clairsecret --from-file=./config.yaml kubectl create -f clair-kubernetes.yaml
Another easy way to get an instance of Clair running is to use Docker Compose to run everything locally. This runs a PostgreSQL database insecurely and locally in a container. This method should only be used for testing.
$ curl -L https://raw.githubusercontent.com/coreos/clair/master/docker-compose.yml -o $HOME/docker-compose.yml $ mkdir $HOME/clair_config $ curl -L https://raw.githubusercontent.com/coreos/clair/master/config.example.yaml -o $HOME/clair_config/config.yaml $ $EDITOR $HOME/clair_config/config.yaml # Edit database source to be postgresql://postgres:password@postgres:5432?sslmode=disable $ docker-compose -f $HOME/docker-compose.yml up -d
Docker Compose may start Clair before Postgres which will raise an error.
If this error is raised, manually execute
docker start clair_clair.
This method assumes you already have a PostgreSQL 9.4+ database running. This is the recommended method for production deployments.
$ mkdir $HOME/clair_config $ curl -L https://raw.githubusercontent.com/coreos/clair/master/config.example.yaml -o $HOME/clair_config/config.yaml $ $EDITOR $HOME/clair_config/config.yaml # Add the URI for your postgres database $ docker run -d -p 6060-6061:6060-6061 -v $HOME/clair_config:/config quay.io/coreos/clair -config=/config/config.yaml
$ go get github.com/coreos/clair $ go install github.com/coreos/clair/cmd/clair $ $EDITOR config.yaml # Add the URI for your postgres database $ ./$GOBIN/clair -config=config.yaml
Architecture at a Glance
- Image - a tarball of the contents of a container
- Layer - an appc or Docker image that may or maybe not be dependent on another image
- Detector - a Go package that identifies the content, namespaces and features from a layer
- Namespace - a context around features and vulnerabilities (e.g. an operating system)
- Feature - anything that when present could be an indication of a vulnerability (e.g. the presence of a file or an installed software package)
- Fetcher - a Go package that tracks an upstream vulnerability database and imports them into Clair
There are two major ways to perform analysis of programs: Static Analysis and Dynamic Analysis. Clair has been designed to perform static analysis; containers never need to be executed. Rather, the filesystem of the container image is inspected and features are indexed into a database. By indexing the features of an image into the database, images only need to be rescanned when new detectors are added.
Default Data Sources
|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|
The major components of Clair are all programmatically extensible in the same way Go's standard database/sql package is extensible.
Custom behavior can be accomplished by creating a package that contains a type that implements an interface declared in Clair and registering that interface in init(). To expose the new behavior, unqualified imports to the package must be added in your main.go, which should then start Clair using
The following interfaces can have custom implementations registered via init() at compile time:
Datastore- the backing storage
Notifier- the means by which endpoints are notified of vulnerability changes
Fetcher- the sources of vulnerability data that is automatically imported
MetadataFetcher- the sources of vulnerability metadata that is automatically added to known vulnerabilities
DataDetector- the means by which contents of an image are detected
FeatureDetector- the means by which features are identified from a layer
NamespaceDetector- the means by which a namespace is identified from a layer
Package clair implements the ability to boot Clair with your own imports that can dynamically register additional functionality.
This section is empty.
This section is empty.
This section is empty.
Package v1 implements the first version of the Clair API.
|Package v1 implements the first version of the Clair API.|
Package database defines the Clair's models and a common interface for database implementations.
|Package database defines the Clair's models and a common interface for database implementations.|
Package pgsql implements database.Datastore with PostgreSQL.
|Package pgsql implements database.Datastore with PostgreSQL.|
Package notifier fetches notifications from the database and informs the specified remote handler about their existences, inviting the third party to actively query the API about it.
|Package notifier fetches notifications from the database and informs the specified remote handler about their existences, inviting the third party to actively query the API about it.|
Package notifiers implements several kinds of notifier.Notifier
|Package notifiers implements several kinds of notifier.Notifier|
Package updater updates the vulnerability database periodically using the registered vulnerability fetchers.
|Package updater updates the vulnerability database periodically using the registered vulnerability fetchers.|
Package utils simply defines utility functions and types.
|Package utils simply defines utility functions and types.|
Package errors defines error types that are used in several modules
|Package errors defines error types that are used in several modules|
Package http provides utility functions for HTTP servers and clients.
|Package http provides utility functions for HTTP servers and clients.|
Package types defines useful types that are used in database models.
|Package types defines useful types that are used in database models.|
Package worker implements the logic to extract useful informations from a container layer and store it in the database.
|Package worker implements the logic to extract useful informations from a container layer and store it in the database.|
Package detectors exposes functions to register and use container information extractors.
|Package detectors exposes functions to register and use container information extractors.|