Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 8. Clair in disconnected environments

Clair supports disconnected environments where your Red Hat Quay deployment has no direct internet access. You can use the clairctl tool to transfer vulnerability database updates from an open host to your isolated environment, enabling Clair to scan images without internet connectivity.

Clair uses a set of components called updaters to handle the fetching and parsing of data from various vulnerability databases. Updaters are set up by default to pull vulnerability data directly from the internet and work for immediate use.

Note

Currently, Clair enrichment data is CVSS data. Enrichment data is currently unsupported in disconnected environments.

For more information about Clair updaters, see "Clair updaters".

To install the clairctl command line utility for disconnected OpenShift Container Platform deployments, you can extract the tool from a running Clair pod and set its execution permissions. This lets you use clairctl to manage vulnerability database updates in disconnected environments.

Procedure

  1. Install the clairctl program for a Clair deployment in an OpenShift Container Platform cluster by entering the following command: 

    $ oc -n quay-enterprise exec example-registry-clair-app-64dd48f866-6ptgw -- cat /usr/bin/clairctl > clairctl
    Note

    Unofficially, the clairctl tool can be downloaded

  2. Set the permissions of the clairctl file so that it can be executed and run by the user, for example: 

    $ chmod u+x ./clairctl

To configure Clair for disconnected environments on OpenShift Container Platform, you can retrieve and decode the Clair configuration secret, then update the clair-config.yaml file to set disable_updaters and airgap parameters to True. This prepares Clair to work without direct internet access.

Prerequisites

  • You have installed the clairctl command line utility tool.

Procedure

  1. Enter the following command to retrieve and decode the configuration secret, and then save it to a Clair configuration YAML: 

    $ oc get secret -n quay-enterprise example-registry-clair-config-secret  -o "jsonpath={$.data['config\.yaml']}" | base64 -d > clair-config.yaml

  2. Update the clair-config.yaml file so that the disable_updaters and airgap parameters are set to True, for example: 

    # ...
indexer:
  airgap: true
# ...
matcher:
  disable_updaters: true
# ...

To export vulnerability database updates from a connected Clair instance for use in disconnected environments, you can use the clairctl tool with your configuration file to export the updaters bundle. This creates a bundle file that you can transfer to your isolated environment.

Prerequisites

  • You have installed the clairctl command line utility tool.
  • You have retrieved and decoded the Clair configuration secret, and saved it to a Clair config.yaml file.
  • The disable_updaters and airgap parameters are set to True in your Clair config.yaml file.

Procedure

  • From a Clair instance that has access to the internet, use the clairctl CLI tool with your configuration file to export the updaters bundle. For example: 

    $ ./clairctl --config ./config.yaml export-updaters updates.gz

To configure access to the Clair database in your disconnected OpenShift Container Platform cluster, you can determine the database service, forward the database port, and update your Clair config.yaml file to use localhost. This lets you import the updaters bundle into the database using the clairctl tool.

Prerequisites

  • You have installed the clairctl command line utility tool.
  • You have retrieved and decoded the Clair configuration secret, and saved it to a Clair config.yaml file.
  • The disable_updaters and airgap parameters are set to True in your Clair config.yaml file.
  • You have exported the updaters bundle from a Clair instance that has access to the internet.

Procedure

  1. Determine your Clair database service by using the oc CLI tool, for example: 

    $ oc get svc -n quay-enterprise

    Example output

    NAME                                  TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)                             AGE
example-registry-clair-app            ClusterIP      172.30.224.93    <none>        80/TCP,8089/TCP                     4d21h
example-registry-clair-postgres       ClusterIP      172.30.246.88    <none>        5432/TCP                            4d21h
...

  2. Forward the Clair database port so that it is accessible from the local machine. For example: 

    $ oc port-forward -n quay-enterprise service/example-registry-clair-postgres 5432:5432

  3. Update your Clair config.yaml file, for example: 

    indexer:
    connstring: host=localhost port=5432 dbname=postgres user=postgres password=postgres sslmode=disable
    layer_scan_concurrency: 5
    migrations: true
    scanlock_retry: 10
    airgap: true
    scanner:
      repo:
        rhel-repository-scanner:
          repo2cpe_mapping_file: /data/repository-to-cpe.json
      package:
        rhel_containerscanner:
          name2repos_mapping_file: /data/container-name-repos-map.json

    where:

    connstring:: Specifies the connection string for the database.

    rhel-repository-scanner:: Specifies the repository scanner configuration.

    rhel_containerscanner:: Specifies the container scanner configuration.

To import vulnerability database updates into your disconnected OpenShift Container Platform cluster, you can use the clairctl tool with your Clair configuration file to import the updaters bundle. This populates the Clair database with vulnerability data so Clair can scan images without internet access.

Prerequisites

  • You have installed the clairctl command line utility tool.
  • You have retrieved and decoded the Clair configuration secret, and saved it to a Clair config.yaml file.
  • The disable_updaters and airgap parameters are set to True in your Clair config.yaml file.
  • You have exported the updaters bundle from a Clair instance that has access to the internet.
  • You have transferred the updaters bundle into your disconnected environment.

Procedure

  • Use the clairctl CLI tool to import the updaters bundle into the Clair database that is deployed by OpenShift Container Platform. For example: 

    $ ./clairctl --config ./clair-config.yaml import-updaters updates.gz

To install the clairctl command line utility for a self-managed Clair deployment on OpenShift Container Platform, you can copy the tool from a Clair container using podman and set its execution permissions. This lets you use clairctl to manage vulnerability database updates in disconnected environments.

Procedure

  1. Install the clairctl program for a self-managed Clair deployment by using the podman cp command, for example: 

    $ sudo podman cp clairv4:/usr/bin/clairctl ./clairctl

  2. Set the permissions of the clairctl file so that it can be executed and run by the user, for example: 

    $ chmod u+x ./clairctl

To deploy a self-managed Clair container for disconnected OpenShift Container Platform clusters, you can create a configuration directory, configure a Clair configuration file with disable_updaters enabled, and start the container using podman. This lets you run Clair independently in environments without direct internet access.

Prerequisites

  • You have installed the clairctl command line utility tool.

Procedure

  1. Create a folder for your Clair configuration file, for example: 

    $ mkdir /etc/clairv4/config/

  2. Create a Clair configuration file with the disable_updaters parameter set to True, for example: 

    ---
indexer:
  airgap: true
---
matcher:
  disable_updaters: true
---

  3. Start Clair by using the container image, mounting in the configuration from the file you created: 

    $ sudo podman run -it --rm --name clairv4 \
-p 8081:8081 -p 8088:8088 \
-e CLAIR_CONF=/clair/config.yaml \
-e CLAIR_MODE=combo \
-v /etc/clairv4/config:/clair:Z \
registry.redhat.io/quay/clair-rhel8:v3.15.4

To export vulnerability database updates from a connected self-managed Clair instance for use in disconnected environments, you can use the clairctl tool with your configuration file to export the updaters bundle. This creates a bundle file that you can transfer to your isolated environment.

Prerequisites

  • You have installed the clairctl command line utility tool.
  • You have deployed Clair.
  • The disable_updaters and airgap parameters are set to True in your Clair config.yaml file.

Procedure

  • From a Clair instance that has access to the internet, use the clairctl CLI tool with your configuration file to export the updaters bundle. For example: 

    $ ./clairctl --config ./config.yaml export-updaters updates.gz

To configure access to the Clair database in your disconnected OpenShift Container Platform cluster for a self-managed deployment, you can determine the database service, forward the database port, and update your Clair config.yaml file to use localhost. This lets you import the updaters bundle into the database using the clairctl tool.

Prerequisites

  • You have installed the clairctl command line utility tool.
  • You have deployed Clair.
  • The disable_updaters and airgap parameters are set to True in your Clair config.yaml file.
  • You have exported the updaters bundle from a Clair instance that has access to the internet.

Procedure

  1. Determine your Clair database service by using the oc CLI tool, for example: 

    $ oc get svc -n quay-enterprise

    Example output

    NAME                                  TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)                             AGE
example-registry-clair-app            ClusterIP      172.30.224.93    <none>        80/TCP,8089/TCP                     4d21h
example-registry-clair-postgres       ClusterIP      172.30.246.88    <none>        5432/TCP                            4d21h
...

  2. Forward the Clair database port so that it is accessible from the local machine. For example: 

    $ oc port-forward -n quay-enterprise service/example-registry-clair-postgres 5432:5432

  3. Update your Clair config.yaml file, for example: 

    indexer:
    connstring: host=localhost port=5432 dbname=postgres user=postgres password=postgres sslmode=disable
    layer_scan_concurrency: 5
    migrations: true
    scanlock_retry: 10
    airgap: true
    scanner:
      repo:
        rhel-repository-scanner:
          repo2cpe_mapping_file: /data/repository-to-cpe.json
      package:
        rhel_containerscanner:
          name2repos_mapping_file: /data/container-name-repos-map.json

    where:

    connstring:: Specifies the connection string for the database.

    rhel-repository-scanner:: Specifies the repository scanner configuration.

    rhel_containerscanner:: Specifies the container scanner configuration.

To import vulnerability database updates into your disconnected OpenShift Container Platform cluster for a self-managed deployment, you can use the clairctl tool with your Clair configuration file to import the updaters bundle. This populates the Clair database with vulnerability data so Clair can scan images without internet access.

Prerequisites

  • You have installed the clairctl command line utility tool.
  • You have deployed Clair.
  • The disable_updaters and airgap parameters are set to True in your Clair config.yaml file.
  • You have exported the updaters bundle from a Clair instance that has access to the internet.
  • You have transferred the updaters bundle into your disconnected environment.

Procedure

  • Use the clairctl CLI tool to import the updaters bundle into the Clair database that is deployed by OpenShift Container Platform: 

    $ ./clairctl --config ./clair-config.yaml import-updaters updates.gz

8.3. Common Product Enumeration mapping in Clair
Copy link

Clair uses Common Product Enumeration (CPE) mapping files to map RPM packages to security data for accurate vulnerability scanning of Red Hat Enterprise Linux (RHEL) container images. Understanding how Clair utilizes these files ensures that your vulnerability reports remain accurate and comprehensive.

The scanner requires the CPE file to be present and accessible to process RPM packages properly. If these files are missing or inaccessible, RPM packages installed in the container image are skipped during the scanning process.

By default, the Clair indexer includes the repos2cpe and names2repos data files within the Clair container. This allows you to reference local paths such as /data/repository-to-cpe.json without additional external configuration.

Important

While Red Hat Product Security updates CPE files regularly, the versions bundled within the Clair container are only updated during Red Hat Quay releases. This can lead to temporary discrepancies between the latest security data and the versions bundled with your current installation.

Additional resources

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top