Clair — Container Image Vulnerability Scanner

Introduction

Clair is an open-source project by Red Hat (Quay) that performs static vulnerability analysis on container images. It indexes the contents of OCI and Docker images and matches installed packages against known vulnerability databases to produce actionable security reports.

What Clair Does

• Indexes container image layers to inventory installed OS packages
• Matches package versions against CVE databases from multiple distributions
• Serves a REST and gRPC API for integration with container registries
• Supports vulnerability data from Debian, Ubuntu, RHEL, Alpine, SUSE, and Oracle
• Generates structured vulnerability reports with severity and fix information

Architecture Overview

Clair v4 uses a microservices-inspired design with two main components: the indexer and the matcher. The indexer fetches image manifests and layers, extracts package information, and stores it in PostgreSQL. The matcher periodically updates vulnerability data from upstream security trackers and correlates it against indexed packages. A notifier component can alert external systems when new vulnerabilities affect previously scanned images.

Self-Hosting & Configuration

• Deploy Clair alongside a PostgreSQL database using Docker Compose or Kubernetes
• Configure via a YAML file specifying database connection, HTTP/gRPC listen addresses, and updater sources
• Integrate with Quay, Harbor, or other registries that support pluggable scanners
• Use clairctl to submit image manifests and retrieve reports from the command line
• Schedule periodic updater runs to keep vulnerability databases current

Key Features

• Multi-distribution vulnerability database aggregation with automatic updates
• Layer-aware indexing that deduplicates packages across shared base images
• Notification webhooks when new CVEs affect already-scanned images
• Designed for registry-scale scanning with parallel indexing workers
• gRPC API for high-throughput programmatic access

Comparison with Similar Tools

• Trivy — standalone all-in-one scanner; Clair is designed as a registry-integrated service
• Grype — CLI vulnerability scanner by Anchore; Clair provides a persistent server with notification support
• Snyk Container — commercial SaaS scanner; Clair is fully open source and self-hosted
• Docker Scout — Docker-integrated advisory service; Clair operates independently of Docker Hub
• Cosign/Sigstore — focuses on image signing and provenance; Clair focuses on vulnerability detection

FAQ

Q: Does Clair scan application dependencies like npm or pip packages? A: Clair primarily scans OS-level packages. For application-level dependency scanning, pair it with tools like Grype or Trivy.

Q: Can Clair run without a database? A: No. Clair requires PostgreSQL to store indexed image data and vulnerability information.

Q: How often is vulnerability data updated? A: By default, Clair fetches updates from upstream security trackers every few hours. The interval is configurable.

Q: Is Clair used in production registries? A: Yes. Clair is the default vulnerability scanner for Red Hat Quay and integrates with Harbor and other registries.

Sources

• https://github.com/quay/clair
• https://quay.github.io/clair/