Clair

Clair is an open-source static analysis tool for finding vulnerabilities in container images.

Developed by Red Hat (originally CoreOS), Clair parses OCI and Docker image layers and matches discovered packages against vulnerability databases covering 9+ Linux distributions.

Red Hat Quay and Quay.io container registries use Clair as their scanning backend. 11k GitHub stars, 117 contributors.

How does Clair scan container images?

Clair scans container images through a three-part pipeline: indexing, matching, and notifications. This architecture separates image analysis from vulnerability correlation, allowing Clair to re-evaluate previously scanned images against newly discovered CVEs without re-indexing.

During indexing, Clair fetches container image layers, examines their contents, and identifies installed packages, language runtimes, and distributions. The output is an IndexReport.

Because OCI uses content-addressed layers, Clair skips any layer it has already indexed.

During matching, Clair checks indexed packages against vulnerability databases that update continuously in the background. Every match request returns results based on the latest security data.

Distribution-specific updaters paired with matchers determine how vulnerabilities relate to specific packages.

The notification service watches for newly discovered vulnerabilities that affect previously indexed manifests and fires alerts through configured webhooks.

What vulnerability databases does Clair use?

Clair pulls vulnerability data from 9+ distribution-specific sources plus the NVD for severity enrichment:

Each updater polls its source periodically — typically hourly — so vulnerability reports stay current without manual intervention. Clair v4 also added support for language-ecosystem advisories (Python, Java, JavaScript, Go) through the Pyup.io and GitHub Advisory Database feeds, which extends matching beyond OS packages into application dependencies bundled in the image.

If an Alpine package vulnerability does not yet have CVSS data in NVD, Clair surfaces it as “Unknown” severity until enrichment catches up. This is a known quirk of Alpine SecDB rather than a Clair limitation, and it shows up most often on the day a fresh CVE drops.

Architecture

Clair v4 wraps the ClairCore library, which handles distribution detection, vulnerability source integration, and layer indexing. ClairCore can be used on its own for custom scanning implementations; Clair adds the HTTP API and orchestration on top.

Written in Go, Clair exposes a REST API for submitting manifests and retrieving vulnerability reports. It stores state in PostgreSQL and can run as a single combined process or as separate indexer, matcher, and notifier services for scale.

Clair v4 is structured as four cooperating microservices: an indexer that fetches and parses image layers, a matcher that compares indexed packages against vulnerability data, a notifier that fires webhooks when previously scanned manifests gain new CVE matches, and a frontend that exposes the REST/gRPC API. All four can run combined in a single process for small deployments or split across nodes for scale.

If you are reading older tutorials, note that Clair v2 (the original architecture) is deprecated. v2 used a different push model and PostgreSQL schema, and most third-party blog posts still reference it. The current API surface is v4 and the migration path between them is one-way — there is no in-place upgrade. If you inherit a v2 deployment, plan for a clean v4 install backed by a fresh PostgreSQL database.

How do you deploy Clair in production?

Production deployments fall into two patterns. The Helm chart in quay/clair-charts is the path of least resistance for Kubernetes — it provisions the indexer, matcher, notifier, frontend, and a PostgreSQL StatefulSet in one manifest. For non-Kubernetes infrastructure, the official docker-compose.yaml runs the same components on a single host.

Database sizing depends on how many distinct image manifests you index. A typical production cluster scanning 1,000-5,000 images per day stabilizes at 50-100 GB of PostgreSQL state; large registries (50,000+ images) can hit 500 GB or more once the vulnerability matrix is fully populated.

Registry integration is native for Red Hat Quay and Quay.io — Clair receives push webhooks automatically. For other registries (Harbor, JFrog Artifactory, ECR), you wire scanning either through the registry’s own webhook plugin or via a polling job that calls the Clair REST API on each new image push. The matcher API supports mTLS for inter-service authentication, which matters in zero-trust K8s environments.

When should you use Clair?

Clair is best suited for organizations that need server-side vulnerability scanning integrated with their container registry workflow.

It is the right choice if you already run Red Hat Quay or Quay.io, or if you are building custom registry infrastructure that needs an API-driven scanning backend.

The REST API design works well for automated pipelines that scan images on push.

Limitations: Clair only does container image scanning. It does not support filesystem, IaC, or source code scanning.

Alpine SecDB does not include severity information, so Alpine-based image vulnerabilities show as “Unknown” severity until NVD enrichment adds CVSS data.

Clair requires PostgreSQL and is operationally heavier than CLI-based scanners like Trivy or Grype .

How does Clair compare to Trivy, Grype, and Anchore?

Clair, Trivy , Grype , and Anchore are the four open-source container vulnerability scanners that come up in nearly every shortlist. They look interchangeable from a feature checklist, but the operational stories are very different.

Trivy is the most popular today (34k+ GitHub stars). It ships as a single binary with a CLI-first workflow, scans container images, filesystems, IaC, code, and Kubernetes clusters, and generates SBOMs. Trivy is the default pick for solo developers and CI pipelines that just want one command.

Grype , backed by Anchore, is SBOM-first by design and pairs naturally with Syft for image inventorying. It runs as a CLI like Trivy but emphasizes the SBOM-driven workflow — generate an SBOM once, re-evaluate it against new CVE data without re-scanning.

Anchore (the Engine and Enterprise products) takes a policy-first stance. It is built for compliance teams that need codified rules around what is allowed in production, with attestation, allowlist, and gating workflows out of the box.

Clair is the registry-integrated option. It runs as a service rather than a CLI, exposes a REST API, and is the deepest fit when you operate Red Hat Quay or build registry infrastructure that scans images on push. The trade-off is operational weight: PostgreSQL, microservices, no built-in CLI. For ad-hoc scans, third-party wrappers like arminc/clair-scanner exist, but they are community projects rather than first-party tooling.

For a broader view of container security options, see the container security tools category page.

Frequently Asked Questions