quay/clair: static vulnerability analysis for OCI and Docker images

What Clair does and who it is for

Clair is an open source project for the static analysis of vulnerabilities in application containers, and the README names OCI and Docker image formats as the supported inputs. The name comes from the French term for clear, bright, transparent, which is the stated goal: a more transparent view of the security of container-based infrastructure.

The design assumes you have your own client. The README says clients use the Clair API to index their container images and can then match against known vulnerabilities. That is a different shape from a scanner you point at an image and read a report from. Clair is the service; something else drives it. If you maintain a container registry, a CI system, or an internal platform where images are built and stored, Clair is the piece that answers whether those images contain known vulnerable packages. If you are a developer who wants to type one command and see a table of CVEs, Clair is not that product.

The indexer, matcher and notifier split

The repository layout shows the split directly: top-level directories include indexer/, matcher/, notifier/, httptransport/, initialize/ and middleware/, with cmd/ holding the entry points. This is not one process doing everything. Indexing and matching are separate services that share a database.

The data flow implied by those components is: a client submits an image manifest to the indexer, the indexer fetches and analyses the image layers and records what it found, vulnerability data is loaded into the same database by updaters, and the matcher compares the indexed contents against that data and returns matches. The notifier exists to push notifications when new vulnerability data changes the result for an already-indexed image, which matters because a scan result is only valid for the vulnerability data present at the time it ran.

That separation has a practical consequence. The docker-compose.yaml in the repository defines indexer and matcher as two services built from the same image, distinguished only by the CLAIR_MODE environment variable set to "indexer" or "matcher". Both depend on clair-database and both mount ./local-dev/clair at /etc/clair read-only. You can scale indexing and matching independently, and you can run them on different machines. You also have to keep them pointed at the same database, which is the failure mode this architecture invites.

Installing Clair and running a first index

The README warns that the main branch may be in an unstable or even broken state during development and directs users to releases rather than the main branch for stable binaries. Start from a release.

The repository ships a docker-compose.yaml intended for local development. It defines the clair-database service using the postgres image, sets POSTGRES_HOST_AUTH_METHOD to trust, and binds ./local-dev/clair/init.sql into the container. The indexer and matcher services run the Go image, mount ./local-dev/clair into /etc/clair, and start with this command, which runs the binary from source with a configuration file:

go run . -conf /etc/clair/${CLAIR_CONFIG:-config.yaml}

The working directory for that command is /src/cmd/clair, and the source tree is mounted at /src. The config file name defaults to config.yaml and can be overridden with the CLAIR_CONFIG environment variable. The repository also provides config.yaml.sample at the top level, which is the file to copy and edit before the service will start with your own database credentials.

If you build the image yourself, the Dockerfile uses quay.io/projectquay/golang as the build stage, takes GO_VERSION as a build argument defaulting to 1.25, and cross-compiles with go build rather than go install. It also accepts a CLAIR_VERSION build argument; the Dockerfile's own message says setting it overrides the reported version and that this hook will go away in the future.

For a first real use, the API is the entry point. The README states that clients use the Clair API to index images and then match them. Expect to authenticate, submit a manifest, poll or wait for indexing to complete, then request the vulnerability report. The book at quay.github.io/clair/ is where the README says the architecture and operation documentation lives, and the exact endpoint shapes are there rather than in the README.

Where Clair is the wrong tool

Clair has no documented command-line scan mode. Nothing in the README describes running a binary against an image path and printing results. If your workflow is a developer running a scanner on a laptop before pushing, Clair forces you to stand up PostgreSQL, an indexer, a matcher, and a client that speaks the API. That is a large amount of infrastructure for a one-off question.

The second limitation is that Clair is a matcher, not a source of truth about vulnerabilities. It compares indexed package data against vulnerability data loaded into its database. If the updaters have not run, or a distribution's advisory feed is not covered, the matcher returns no findings, and an empty result is indistinguishable from a clean image to a client that does not check updater status. The README does not document what the API returns when vulnerability data is stale or absent.

The third is version discipline. The go.mod pins github.com/quay/clair/config at v1.4.3 and github.com/quay/claircore at v1.6.0, and the module path is github.com/quay/clair/v4. Configuration and the core analysis library are separate modules with their own release cadence, so a config file that worked with one Clair release can fail schema validation on another. The README does not document a rollback procedure for a database migration, and the repository includes a migrate dependency (github.com/remind101/migrate), which implies schema migrations are part of upgrades.

How Clair differs from Trivy and Grype

Trivy and Grype are the obvious alternatives, and the difference is architectural rather than a matter of detection quality. Both are distributed primarily as command-line scanners: you point them at an image reference or a filesystem, they fetch or use a local vulnerability database, and they print a report. They can be embedded in CI with a single step and no server.

Clair inverts that. It is a long-running service with a database, split into an indexer and a matcher, with a notifier for change events. The advantage of that shape is that indexing work is done once per image and reused across every subsequent vulnerability data update, and that the notifier can tell you when a previously clean image becomes affected. A CLI scanner has to re-scan to answer the same question, and it has no memory of what it saw last time.

The cost is operational. A CLI scanner has no database to back up, no migration to run, and no service to keep healthy. Clair has all three. If your environment already runs PostgreSQL and you need to track image state over time across a fleet, the Clair model fits. If you need a scan in a build step with nothing else running, a CLI scanner is the shorter path.

Licence, upgrades and maintenance cost

Clair is under the Apache 2.0 license, per the README and the LICENSE file. Apache 2.0 includes an express patent grant and permits commercial use and modification; it also requires that you preserve notices. The repository carries a NOTICE file, which is the file Apache 2.0 expects you to propagate. This is not legal advice, and if you redistribute Clair inside a product, have counsel review the NOTICE handling.

Upgrade cost is dominated by two things: the database schema and the config schema. The migrate dependency suggests migrations run as part of the upgrade path, and the pinned config module version means the config file is validated against a specific schema. The CHANGELOG.md at the repository root is the place to check what changed between releases. Release cadence is uneven: v4.7.4 in May 2024, v4.8.0 in October 2024, and v4.9.0 in December 2025. The last push to the repository was on 2026-09-18, so the project is not archived and the main branch is receiving commits, but the README's own warning about main being unstable still applies, and release binaries remain the recommended path.

Running cost is real. You are operating PostgreSQL, at least one indexer, at least one matcher, and optionally a notifier, plus whatever client drives the API. The docker-compose.yaml also pulls in a long list of observability services (Prometheus, Grafana, Jaeger, Pyroscope, pgAdmin, RabbitMQ, Redis, Traefik, skopeo) for the development environment, which is convenient locally but should not be mistaken for the production footprint.

Editorial conclusion

Adopt Clair if you already run a registry or CI pipeline and want an API you can drive yourself, with indexing and matching scaled as separate services. Do not adopt it if you want a single binary that scans an image from the command line: Clair exposes no such mode, and the README points clients at the API instead. Before committing, verify that your config.yaml matches the config schema version pinned by github.com/quay/clair/config, and confirm which updaters are enabled, because a matcher without vulnerability data will return empty result sets rather than an error.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. quay/clair on GitHub
4. README
5. Releases