Clair is an open-source, API-driven static analysis engine designed to inspect container images layer-by-layer for known security vulnerabilities (CVEs).

It acts as the security brain for Red Hat Quay and seamlessly integrates with OpenShift Container Platform (OCP) to automate container security audits right inside your cluster.

1. How Clair Analyzes Images

Rather than running a container and monitoring its active behavior (dynamic analysis), Clair performs static analysis. It breaks down image layers without ever executing the code.

The process is split into three distinct microservice stages:

Plaintext

 ┌──────────────┐      Extracts packages     ┌──────────────┐
 │ 1. Indexer   │ ─────────────────────────► │ IndexReport  │ (Manifest Blueprint)
 └──────────────┘                            └──────┬───────┘
                                                    │
                                                    ▼
 ┌──────────────┐      Matches CVE data      ┌──────────────┐
 │ 2. Matcher   │ ◄───────────────────────── │ Vulnerability│ (Compares with Databases)
 └──────┬───────┘                            │    Feeds     │
        │                                    └──────────────┘
        ▼
 ┌──────────────┐      Dispatches alerts
 │ 3. Notifier  │ ─────────────────────────► Webhooks / UI Notifications
 └──────────────┘

1. Indexing: The Indexer scans the filesystem layers of an OCI or Docker container manifest. It identifies the base operating system (e.g., RHEL, Alpine, Ubuntu) and inventories every installed package, language-specific library, and file system dependency. This inventory is saved as an IndexReport.
2. Matching: The Matcher takes the IndexReport and correlates its packages against its local database of known vulnerabilities. Clair continuously pulls security advisories from upstream sources, including:
   • Red Hat Enterprise Linux (RHEL) OVAL feeds.
   • OSV (Open Source Vulnerability) databases for language-specific package ecosystems (Go, Java, Python, Ruby).
   • Debian, Ubuntu, Alpine, and AWS security trackers.
3. Notification: The Notifier watches for changes in vulnerability feeds. If a zero-day exploit is published today for a package you pushed to your registry last week, the Notifier matches the new CVE to your existing IndexReport and proactively fires an alert or webhook.

2. Integrating Clair with OpenShift (The OCP View)

In an OpenShift environment, Clair’s insights are brought directly into the platform’s native administration interface using the Quay Container Security Operator (CSO).

Plaintext

 ┌──────────────────────┐   Watches Pods    ┌──────────────────────────┐
 │  Kubernetes Pods     │ ────────────────► │ Container Security       │
 │  (Running in OCP)    │                   │ Operator (CSO)           │
 └──────────────────────┘                   └────────────┬─────────────┘
                                                         │ queries
                                                         ▼
                                            ┌──────────────────────────┐
                                            │    Red Hat Quay + Clair  │
                                            └──────────────────────────┘

The Security Operator Workflow

When you deploy the Container Security Operator on OpenShift:

• The CSO watches all active namespaces for running Pods.
• It extracts the image registry paths of those pods and queries your Quay registry’s Clair API.
• If Clair has flagged vulnerabilities in those running images, the CSO generates a cluster-scoped ImageManifestVuln custom resource.
• Developers and SREs can view the severity, CVSS scores, and remediation steps directly inside the OpenShift Web Console under the Image Manifest Vulnerabilities dashboard—meaning you do not have to leave OpenShift to check your registry’s security status.

3. Advanced Strategy: Clair in Air-Gapped (Disconnected) Environments

For secure, private, or governmental OCP clusters with no outbound internet access, Clair cannot reach the public Red Hat or OSV servers to update its vulnerability databases.

To solve this, Red Hat provides a tool called clairctl.

An administrator on a machine with internet access uses clairctl to export the latest database updates into an offline bundle. This bundle is then transferred via a secure gateway (or physical media) into the disconnected OpenShift environment and imported directly into Clair’s local database instance to keep the air-gapped security system completely up-to-date.

For a deeper technical walkthrough of how the scanner handles image layers, updates database CVE indexes, and surfaces reporting data, you can watch Deep Dive into Image Vulnerability Scanning Using Clair. This video goes into detail about the structural scanning process and what results to expect in a production deployment.