clair

package module
Version: v1.0.0-rc1 Latest Latest
Warning

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

Go to latest
Published: Feb 24, 2016 License: Apache-2.0 Imports: 12 Imported by: 92

README

Clair

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

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. New data sources can be added programmatically at compile-time or data can be injected via HTTP API at runtime.

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

Requirements

An instance of PostgreSQL 9.4+ is required. 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.

$ 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

Simple Clair Diagram

Documentation

Documentation can be found in a README.md file located in the directory of the component.

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. 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, images only need to be rescanned when new features are added.

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.

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

Documentation

Overview

Package clair implements the ability to boot Clair with your own imports that can dynamically register additional functionality.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Boot

func Boot(config *config.Config)

Boot starts Clair. By exporting this function, anyone can import their own custom fetchers/updaters into their own package and then call clair.Boot.

Types

This section is empty.

Source Files

Directories

Path Synopsis
api
v1
Package v1 implements the first version of the Clair API.
Package v1 implements the first version of the Clair API.
cmd
contrib
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.
pgsql
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.
notifiers
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.
errors
Package errors defines error types that are used in several modules
Package errors defines error types that are used in several modules
http
Package http provides utility functions for HTTP servers and clients.
Package http provides utility functions for HTTP servers and clients.
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.

Jump to

Keyboard shortcuts

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