clair

package module
Version: v2.0.0-rc.0+incompatible Latest Latest
Warning

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

Go to latest
Published: Feb 23, 2017 License: Apache-2.0 Imports: 19 Imported by: 92

README

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, a notification can be delivered, and the API queried to provide the previous state and new state of the vulnerability along with the images affected by both. All major components can be extended 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
  • Feature - anything that when present could be an indication of a vulnerability (e.g. the presence of a file or an installed software package)
  • Feature Namespace - a context around features and vulnerabilities (e.g. an operating system)
  • Vulnerability Updater - a Go package that tracks upstream vulnerability data and imports them into Clair
  • Vulnerability Metadata Appender - a Go package that tracks upstream vulnerability metadata and appends them into vulnerabilities managed by 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
NIST 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. Everything extendable is located in the ext directory.

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 own custom main.go, which should then start Clair using Boot(*config.Config).

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

Documentation

Index

Constants

View Source
const (
	// Version (integer) represents the worker version.
	// Increased each time the engine changes.
	Version = 3
)

Variables

View Source
var (
	// ErrUnsupported is the error that should be raised when an OS or package
	// manager is not supported.
	ErrUnsupported = commonerr.NewBadRequestError("worker: OS and/or package manager are not supported")

	// ErrParentUnknown is the error that should be raised when a parent layer
	// has yet to be processed for the current layer.
	ErrParentUnknown = commonerr.NewBadRequestError("worker: parent layer is unknown, it must be processed first")
)

Functions

func ProcessLayer

func ProcessLayer(datastore database.Datastore, imageFormat, name, parentName, path string, headers map[string]string) error

ProcessLayer detects the Namespace of a layer, the features it adds/removes, and then stores everything in the database.

TODO(Quentin-M): We could have a goroutine that looks for layers that have been analyzed with an older engine version and that processes them.

func RunNotifier

func RunNotifier(config *notification.Config, datastore database.Datastore, stopper *stopper.Stopper)

RunNotifier begins a process that checks for new notifications that should be sent out to third parties.

func RunUpdater

func RunUpdater(config *UpdaterConfig, datastore database.Datastore, st *stopper.Stopper)

RunUpdater begins a process that updates the vulnerability database at regular intervals.

Types

type UpdaterConfig

type UpdaterConfig struct {
	Interval time.Duration
}

UpdaterConfig is the configuration for the Updater service.

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.
pgsql/migrations
Package migrations regroups every migrations available to the pgsql database backend.
Package migrations regroups every migrations available to the pgsql database backend.
ext
featurefmt
Package featurefmt exposes functions to dynamically register methods for determining the features present in an image layer.
Package featurefmt exposes functions to dynamically register methods for determining the features present in an image layer.
featurefmt/apk
Package apk implements a featurefmt.Lister for APK packages.
Package apk implements a featurefmt.Lister for APK packages.
featurefmt/dpkg
Package dpkg implements a featurefmt.Lister for dpkg packages.
Package dpkg implements a featurefmt.Lister for dpkg packages.
featurefmt/rpm
Package rpm implements a featurefmt.Lister for rpm packages.
Package rpm implements a featurefmt.Lister for rpm packages.
featurens
Package featurens exposes functions to dynamically register methods for determining a namespace for features present in an image layer.
Package featurens exposes functions to dynamically register methods for determining a namespace for features present in an image layer.
featurens/alpinerelease
Package alpinerelease implements a featurens.Detector for Alpine Linux based container image layers.
Package alpinerelease implements a featurens.Detector for Alpine Linux based container image layers.
featurens/aptsources
Package aptsources implements a featurens.Detector for apt based container image layers.
Package aptsources implements a featurens.Detector for apt based container image layers.
featurens/lsbrelease
Package lsbrelease implements a featurens.Detector for container image layers containing an lsb-release file.
Package lsbrelease implements a featurens.Detector for container image layers containing an lsb-release file.
featurens/osrelease
Package osrelease implements a featurens.Detector for container image layers containing an os-release file.
Package osrelease implements a featurens.Detector for container image layers containing an os-release file.
featurens/redhatrelease
Package redhatrelease implements a featurens.Detector for container image layers containing an redhat-release-like files.
Package redhatrelease implements a featurens.Detector for container image layers containing an redhat-release-like files.
imagefmt
Package imagefmt exposes functions to dynamically register methods to detect different types of container image formats.
Package imagefmt exposes functions to dynamically register methods to detect different types of container image formats.
imagefmt/aci
Package aci implements an imagefmt.Extractor for appc formatted container image layers.
Package aci implements an imagefmt.Extractor for appc formatted container image layers.
imagefmt/docker
Package docker implements an imagefmt.Extractor for docker formatted container image layers.
Package docker implements an imagefmt.Extractor for docker formatted container image layers.
notification
Package notification exposes functions to dynamically register methods to deliver notifications from the Clair database.
Package notification exposes functions to dynamically register methods to deliver notifications from the Clair database.
notification/webhook
Package webhook implements a notification sender for HTTP JSON webhooks.
Package webhook implements a notification sender for HTTP JSON webhooks.
versionfmt
Package versionfmt exposes functions to dynamically register formats used to parse Feature Versions.
Package versionfmt exposes functions to dynamically register formats used to parse Feature Versions.
versionfmt/dpkg
Package dpkg implements a versionfmt.Parser for version numbers used in dpkg based software packages.
Package dpkg implements a versionfmt.Parser for version numbers used in dpkg based software packages.
versionfmt/rpm
Package rpm implements a versionfmt.Parser for version numbers used in rpm based software packages.
Package rpm implements a versionfmt.Parser for version numbers used in rpm based software packages.
vulnmdsrc
Package vulnmdsrc exposes functions to dynamically register vulnerability metadata sources used to update a Clair database.
Package vulnmdsrc exposes functions to dynamically register vulnerability metadata sources used to update a Clair database.
vulnmdsrc/nvd
Package nvd implements a vulnerability metadata appender using the NIST NVD database.
Package nvd implements a vulnerability metadata appender using the NIST NVD database.
vulnsrc
Package vulnsrc exposes functions to dynamically register vulnerability sources used to update a Clair database.
Package vulnsrc exposes functions to dynamically register vulnerability sources used to update a Clair database.
vulnsrc/alpine
Package alpine implements a vulnerability source updater using the alpine-secdb git repository.
Package alpine implements a vulnerability source updater using the alpine-secdb git repository.
vulnsrc/debian
Package debian implements a vulnerability source updater using the Debian Security Tracker.
Package debian implements a vulnerability source updater using the Debian Security Tracker.
vulnsrc/oracle
Package oracle implements a vulnerability source updater using the Oracle Linux OVAL Database.
Package oracle implements a vulnerability source updater using the Oracle Linux OVAL Database.
vulnsrc/rhel
Package rhel implements a vulnerability source updater using the Red Hat Linux OVAL Database.
Package rhel implements a vulnerability source updater using the Red Hat Linux OVAL Database.
vulnsrc/ubuntu
Package ubuntu implements a vulnerability source updater using the Ubuntu CVE Tracker.
Package ubuntu implements a vulnerability source updater using the Ubuntu CVE Tracker.
pkg
commonerr
Package commonerr defines reusable error types common throughout the Clair codebase.
Package commonerr defines reusable error types common throughout the Clair codebase.
tarutil
Package tarutil implements some tar utility functions.
Package tarutil implements some tar utility functions.

Jump to

Keyboard shortcuts

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