Vulnerability Static Analysis for Containers
Go
Latest commit 1d6ef94 Jan 4, 2017 @jzelinskie jzelinskie committed on GitHub Merge pull request #302 from jzelinskie/rmimage
README: rm images from repo
Permalink
Failed to load latest commit information.
Documentation docs: split http and json code blocks Dec 7, 2016
api api/v1: fix JSON struct tag misnomer Jan 3, 2017
cmd/clair Add Oracle Linux fetcher to grab and parse OVAL data. Dec 20, 2016
config worker/database: Move upgrade detection logic out of database to worker May 20, 2016
contrib contrib: Catch signals to delete tmp folder in local-analyze-images Apr 25, 2016
database db/pgsql/feature: fix SQL error reporting Jan 3, 2017
ext/versionfmt versionfmt: convert to using constant over literal Jan 3, 2017
notifier Merge pull request #235 from jzelinskie/doc-move Sep 6, 2016
updater Merge pull request #298 from jzelinskie/versions Jan 3, 2017
utils Revert "Merge pull request #199 from openSUSE/feature/opensuse" Dec 19, 2016
vendor pgsql: Replace liamstask/goose by remind101/migrate Nov 11, 2016
worker versionfmt: convert to using constant over literal Jan 3, 2017
.dockerignore Initial commit Nov 13, 2015
.travis.yml travis: add matrix for postgres Dec 4, 2016
CONTRIBUTING.md Initial commit Nov 13, 2015
DCO Initial commit Nov 13, 2015
Dockerfile dockerfile: add git dependency Dec 19, 2016
LICENSE Initial commit Nov 13, 2015
NOTICE Initial commit Nov 13, 2015
README.md README: rm images from repo Jan 4, 2017
ROADMAP.md *: Create a ROADMAP Apr 19, 2016
clair.go database: Allow specifying datastore driver by config May 11, 2016
config.example.yaml Modify URL of libpq documentation (#197) Jun 7, 2016
docker-compose.yml Restart clair until postgres is up Nov 22, 2016
glide.lock pgsql: Replace liamstask/goose by remind101/migrate Nov 11, 2016
glide.yaml pgsql: Replace liamstask/goose by remind101/migrate Nov 11, 2016
grafana.json prometheus: fix grafana's updater notes graph Feb 24, 2016

README.md

Clair

Build Status Docker Repository on Quay Go Report Card GoDoc IRC Channel

Note: The 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.

Clair Logo

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

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

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 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.

Hello Heartbleed

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.

Kubernetes

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

Docker Compose

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/v1.2.4/docker-compose.yml -o $HOME/docker-compose.yml
$ mkdir $HOME/clair_config
$ curl -L https://raw.githubusercontent.com/coreos/clair/v1.2.4/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-compose start clair.

Docker

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/v1.2.4/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:v1.2. -config=/config/config.yaml

Source

To build Clair, you need to latest stable version of Go and a working Go environment. In addition, Clair requires that git, bzr, rpm, and xz be available on the system $PATH.

$ 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

Container images

While container images for every releases are available at quay.io/repository/coreos/clair, container images built on the latest available source code are available at quay.io/repository/coreos/clair-git.

Documentation

The latest stable documentation can be found on the CoreOS website. Documentation for the current branch can be found inside the Documentation directory at the root of the project's source code.

Architecture at a Glance

Simple Clair Diagram

Terminology

  • 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

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; 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

Data Source Data Collected Format License
Debian Security Bug Tracker Debian 6, 7, 8, unstable namespaces dpkg Debian
Ubuntu CVE Tracker Ubuntu 12.04, 12.10, 13.04, 14.04, 14.10, 15.04, 15.10, 16.04 namespaces dpkg GPLv2
Red Hat Security Data CentOS 5, 6, 7 namespaces rpm CVRF
Oracle Linux Security Data Oracle Linux 5, 6, 7 namespaces rpm CVRF
Alpine SecDB Alpine 3.3, Alpine 3.4 namespaces apk MIT
NVD Generic Vulnerability Metadata N/A Public Domain

Customization

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 Boot(*config.Config).

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

Related Links

Talks & Slides

  • Clair: The Container Image Security Analyzer @ ContainerDays Boston 2016 - Event Video Slides
  • Identifying Common Vulnerabilities and Exposures in Containers with Clair @ CoreOS Fest 2016 - Event Video Slides
  • Clair: A Container Image Security Analyzer @ Microservices NYC - Event Video Slides
  • Clair: A Container Image Security Analyzer @ Container Orchestration NYC - Event Video Slides

Projects Integrating with Clair

  • Quay: the first container registry to integrate with Clair
  • Dockyard: an open source container registry with Clair integration
  • Hyperclair: a lightweight command-line tool for working locally with Clair
  • Clair w/ SQS: a container containing Clair and additional processes that integrate Clair with Amazon SQS
  • Klar: a simple command-line integration of Clair and Docker registry, designed to be used in scripts and CI