clair

command module
Version: v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2015 License: Apache-2.0 Imports: 16 Imported by: 92

README

Clair

Clair is a container vulnerability analysis service. It provides the list of vulnerabilities that threaten each container and can sends notifications whenever new vulnerabilities that affect existing containers are released.

We named the project « Clair », which means in French clear, bright, transparent because we believe that it enables users to have a clear insight into the security of their container infrastructure.

Why should I use Clair?

Clair is a single-binary server that exposes an JSON, HTTP API. It does not require any agent to sit on your containers neither does it need any specific container tweak to be done. It has been designed to perform massive analysis on the Quay.io Container Registry.

Whether you host a container registry, a continuous-integration system, or build dozens to thousands containers, you would benefit from Clair. More generally, if you consider that container security matters (and, honestly, you should), you should give it a shot.

How Clair Detects Vulnerabilities

Clair has been designed to analyze a container layer only once, without running the container. The analysis has to extract all required data to detect the known vulnerabilities which may affect a layer but also any future vulnerabilities.

Detecting vulnerabilities can be achieved by several techniques. One possiblity is to compute hashes of binaries. These are presented on a layer and then compared with a database. However, building this database may become tricky considering the number of different packages and library versions.

To detect vulnerabilities Clair decided to take advantage of package managers, which quickly and comprehensively provide lists of installed binary and source packages. Package lists are extracted for each layer that composes of your container image, the difference between the layer’s package list, and its parent one is stored. Not only is this method storage-efficient, but it also enables us to scan a layer that may be used in many images only once. Coupled with vulnerability databases such as the Debian’s Security Bug Tracker, Clair is able to tell which vulnerabilities threaten a container, and which layer and package introduced them.

Graph

Clair internally uses a graph, which has its model described in the associated doc to store and query data. Below is a non-exhaustive example graph that correspond to the following Dockerfile.

1.  MAINTAINER Quentin Machu <quentin.machu@coreos.com>
2.  FROM ubuntu:trusty
3.  RUN apt−get update && apt−get upgrade −y
4.  EXPOSE 22
5.  CMD ["/usr/sbin/sshd", "-D"]

Example graph

The above image shows five layers represented by the purple nodes, associated with their ids and parents. Because the second layer imports Ubuntu Trusty in the container, Clair can detect the operating system and some packages, in green (we only show one here for the sake of simplicity). The third layer upgrades packages, so the graph reflects that this layer removes the previous version and installs the new one. Finally, the graph knows about a vulnerability, drawn in red, which is fixed by a particular package. Note that two synthetic package versions exist (0 and ∞): they ensure database consistency during parallel modification. ∞ also allows us to define very easily that a vulnerability is not yet fixed; thus, it affects every package version.

Querying this particular graph will tell us that our image is not vulnerable at all because none of the successor versions of its only package fix any vulnerability. However, an image based on the second layer could be vulnerable.

Architecture

Clair is divided into X main modules (which represent Go packages):

  • api defines how users interact with Clair and exposes a documented HTTP API.
  • worker extracts useful informations from layers and store everything in the database.
  • updater periodically updates Clair's vulnerability database from known vulnerability sources.
  • notifier dispatches notifications about vulnerable containers when vulnerabilities are released or updated.
  • database persists layers informations and vulnerabilities in Cayley graph database.
  • health summarizes health checks of every Clair's services.

Multiple backend databases are supported, a testing deployment would use an in-memory storage while a production deployment should use Bolt (single-instance deployment) or PostgreSQL (distributed deployment, probably behind a load-balancer). To learn more about how to run Clair, take a look at the doc.

Detectors & Fetchers

Clair currently supports three operating systems and their package managers, which we believe are the most common ones: Debian (dpkg), Ubuntu (dpkg), CentOS (yum).

Supporting an operating system implies that we are able to extract the operating system's name and version from a layer and the list of package it has. This is done inside the worker/detectors package and extending that is straightforward.

All of this is useless if no vulnerability is known for any of these packages. The updater/fetchers package defines trusted sources of vulnerabilities, how to fetch them and parse them. For now, Clair uses three databases, one for each supported operating system:

Using these distro-specific sources gives us confidence that Clair can take into consideration all the different package implementations and backports without ever reporting anything possibly inaccurate.

Coming Soon

  • Improved performances.
  • Extended detection system
    • More package managers
    • Generic features such as detecting presence/absence of files
    • ...
  • Expose more informations about vulnerability
    • Access vector
    • Acess complexity
    • ...

Documentation

The Go Gopher

There is no documentation for this package.

Source Files

Directories

Path Synopsis
api
Package api provides a RESTful HTTP API, enabling external apps to interact with clair.
Package api provides a RESTful HTTP API, enabling external apps to interact with clair.
jsonhttp
Package jsonhttp provides helper functions to write JSON responses to http.ResponseWriter and read JSON bodies from http.Request.
Package jsonhttp provides helper functions to write JSON responses to http.ResponseWriter and read JSON bodies from http.Request.
logic
Package logic implements all the available API methods.
Package logic implements all the available API methods.
wrappers
Package wrappers contains httprouter.Handle wrappers that are used in the API.
Package wrappers contains httprouter.Handle wrappers that are used in the API.
Package database implements every database models and the functions that manipulate them.
Package database implements every database models and the functions that manipulate them.
Package health defines a standard healthcheck response format and expose a function that summarizes registered healthchecks.
Package health defines a standard healthcheck response format and expose a function that summarizes registered healthchecks.
Package notifier fetches notifications from the database and sends them to the specified remote handler.
Package notifier fetches notifications from the database and sends them to the specified remote handler.
Package updater updates the vulnerability database periodically using the registered vulnerability fetchers.
Package updater updates the vulnerability database periodically using the registered vulnerability fetchers.
fetchers
Package fetchers implements vulnerability fetchers for several sources.
Package fetchers implements vulnerability fetchers for several sources.
Package utils simply defines utility functions and types.
Package utils simply defines utility functions and types.
errors
Package errors defines error types that are used in several modules
Package errors defines error types that are used in several modules
types
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.
detectors
Package detectors exposes functions to register and use container information extractors.
Package detectors exposes functions to register and use container information extractors.
detectors/os
Package os defines OSDetector for several sources.
Package os defines OSDetector for several sources.
detectors/packages
Package packages defines PackagesDetector for several sources.
Package packages defines PackagesDetector for several sources.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL