Chapter 2. Clair concepts

2.1. Clair in practice

A Clair analysis is broken down into three distinct parts: indexing, matching, and notification.

2.1.1. Indexing

Clair’s indexer service plays a crucial role in understanding the makeup of a container image. In Clair, container image representations called "manifests." Manifests are used to comprehend the contents of the image’s layers. To streamline this process, Clair takes advantage of the fact that Open Container Initiative (OCI) manifests and layers are designed for content addressing, reducing repetitive tasks.

During indexing, a manifest that represents a container image is taken and broken down into its essential components. The indexer’s job is to uncover the image’s contained packages, its origin distribution, and the package repositories it relies on. This valuable information is then recorded and stored within Clair’s database. The insights gathered during indexing serve as the basis for generating a comprehensive vulnerability report. This report can be seamlessly transferred to a matcher node for further analysis and action, helping users make informed decisions about their container images' security.

The IndexReport is stored in Clair’s database. It can be fed to a matcher node to compute the vulnerability report.

2.1.2. Matching

With Clair, a matcher node is responsible for matching vulnerabilities to a provided index report.

Matchers are responsible for keeping the database of vulnerabilities up to date. Matchers run a set of updaters, which periodically probe their data sources for new content. New vulnerabilities are stored in the database when they are discovered.

The matcher API is designed to always provide the most recent vulnerability report when queried. The vulnerability report summarizes both a manifest’s content and any vulnerabilities affecting the content.

New vulnerabilities are stored in the database when they are discovered.

The matcher API is designed to be used often. It is designed to always provide the most recent VulnerabilityReport when queried. The VulnerabilityReport summarizes both a manifest’s content and any vulnerabilities affecting the content.

2.1.3. Notifier service

Clair uses a notifier service that keeps track of new security database updates and informs users if new or removed vulnerabilities affect an indexed manifest.

When the notifier becomes aware of new vulnerabilities affecting a previously indexed manifest, it uses the configured methods in your config.yaml file to issue notifications about the new changes. Returned notifications express the most severe vulnerability discovered because of the change. This avoids creating excessive notifications for the same security database update.

When a user receives a notification, it issues a new request against the matcher to receive an up to date vulnerability report.

You can subscribe to notifications through the following mechanics:

Webhook delivery
AMQP delivery
STOMP delivery

Configuring the notifier is done through the Clair YAML configuration file.

2.2. Clair authentication

In its current iteration, Clair v4 (Clair) handles authentication internally.

Note

Previous versions of Clair used JWT Proxy to gate authentication.

Authentication is configured by specifying configuration objects underneath the auth key of the configuration. Multiple authentication configurations might be present, but they are used preferentially in the following order:

PSK. With this authentication configuration, Clair implements JWT-based authentication using a pre-shared key.
Configuration. For example:
```
auth:
  psk:
    key: >-
      MDQ4ODBlNDAtNDc0ZC00MWUxLThhMzAtOTk0MzEwMGQwYTMxCg==
    iss: 'issuer'
```
In this configuration the auth field requires two parameters: iss, which is the issuer to validate all incoming requests, and key, which is a base64 coded symmetric key for validating the requests.

2.3. Clair updaters

Clair uses Go packages called updaters that contain the logic of fetching and parsing different vulnerability databases.

Updaters are usually paired with a matcher to interpret if, and how, any vulnerability is related to a package. Administrators might want to update the vulnerability database less frequently, or not import vulnerabilities from databases that they know will not be used.

2.4. Information about Clair updaters

The following table provides details about each Clair updater, including the configuration parameter, a brief description, relevant URLs, and the associated components that they interact with. This list is not exhaustive, and some servers might issue redirects, while certain request URLs are dynamically constructed to ensure accurate vulnerability data retrieval.

For Clair, each updater is responsible for fetching and parsing vulnerability data related to a specific package type or distribution. For example, the Debian updater focuses on Debian-based Linux distributions, while the AWS updater focuses on vulnerabilities specific to Amazon Web Services' Linux distributions. Understanding the package type is important for vulnerability management because different package types might have unique security concerns and require specific updates and patches.

Note

If you are using a proxy server in your environment with Clair’s updater URLs, you must identify which URL needs to be added to the proxy allowlist to ensure that Clair can access them unimpeded. Use the following table to add updater URLs to your proxy allowlist.

Table 2.1. Clair updater information
Updater	Description	URLs	Component
`alpine`	The Alpine updater is responsible for fetching and parsing vulnerability data related to packages in Alpine Linux distributions.	`https://secdb.alpinelinux.org/`	Alpine Linux SecDB database
`aws`	The AWS updater is focused on AWS Linux-based packages, ensuring that vulnerability information specific to Amazon Web Services' custom Linux distributions is kept up-to-date.	`http://repo.us-west-2.amazonaws.com/2018.03/updates/x86_64/mirror.list` `https://cdn.amazonlinux.com/2/core/latest/x86_64/mirror.list` `https://cdn.amazonlinux.com/al2023/core/mirrors/latest/x86_64/mirror.list`	Amazon Web Services (AWS) UpdateInfo
`debian`	The Debian updater is essential for tracking vulnerabilities in packages associated with Debian-based Linux distributions.	`https://deb.debian.org/` `https://security-tracker.debian.org/tracker/data/json`	Debian Security Tracker
`clair.cvss`	The Clair Common Vulnerability Scoring System (CVSS) updater focuses on maintaining data about vulnerabilities and their associated CVSS scores. This is not tied to a specific package type but rather to the severity and risk assessment of vulnerabilities in general.	`https://nvd.nist.gov/feeds/json/cve/1.1/`	National Vulnerability Database (NVD) feed for Common Vulnerabilities and Exposures (CVE) data in JSON format
`oracle`	The Oracle updater is dedicated to Oracle Linux packages, maintaining data on vulnerabilities that affect Oracle Linux systems.	`https://linux.oracle.com/security/oval/com.oracle.elsa-*.xml.bz2`	Oracle Oval database
`photon`	The Photon updater deals with packages in VMware Photon OS.	`https://packages.vmware.com/photon/photon_oval_definitions/`	VMware Photon OS oval definitions
`rhel`	The Red Hat Enterprise Linux (RHEL) updater is responsible for maintaining vulnerability data for packages in Red Hat’s Enterprise Linux distribution.	`https://access.redhat.com/security/cve/` `https://access.redhat.com/security/data/oval/v2/PULP_MANIFEST`	Red Hat Enterprise Linux (RHEL) Oval database
`rhcc`	The Red Hat Container Catalog (RHCC) updater is connected to Red Hat’s container images. This updater ensures that vulnerability information related to Red Hat’s containerized software is kept current.	`https://access.redhat.com/security/data/metrics/cvemap.xml`	Resource Handler Configuration Controller (RHCC) database
`suse`	The SUSE updater manages vulnerability information for packages in the SUSE Linux distribution family, including openSUSE, SUSE Enterprise Linux, and others.	`https://support.novell.com/security/oval/`	SUSE Oval database
`ubuntu`	The Ubuntu updater is dedicated to tracking vulnerabilities in packages associated with Ubuntu-based Linux distributions. Ubuntu is a popular distribution in the Linux ecosystem.	`https://security-metadata.canonical.com/oval/com.ubuntu.*.cve.oval.xml` `https://api.launchpad.net/1.0/`	Ubuntu Oval Database
`osv`	The Open Source Vulnerability (OSV) updater specializes in tracking vulnerabilities within open source software components. OSV is a critical resource that provides detailed information about security issues found in various open source projects.	`https://osv-vulnerabilities.storage.googleapis.com/`	Open Source Vulnerabilities database

2.5. Configuring updaters

Updaters can be configured by the updaters.sets key in your clair-config.yaml file.

Important

If the sets field is not populated, it defaults to using all sets. In using all sets, Clair tries to reach the URL or URLs of each updater. If you are using a proxy environment, you must add these URLs to your proxy allowlist.
If updaters are being run automatically within the matcher process, which is the default setting, the period for running updaters is configured under the matcher’s configuration field.

2.5.1. Selecting specific updater sets

Use the following references to select one, or multiple, updaters for your Red Hat Quay deployment.

Configuring Clair for multiple updaters

Multiple specific updaters

#...
updaters:
  sets:
    - alpine
    - aws
    - osv
#...

Configuring Clair for Alpine

Alpine config.yaml example

#...
updaters:
  sets:
    - alpine
#...

Configuring Clair for AWS

AWS config.yaml example

#...
updaters:
  sets:
    - aws
#...

Configuring Clair for Debian

Debian config.yaml example

#...
updaters:
  sets:
    - debian
#...

Configuring Clair for Clair CVSS

Clair CVSS config.yaml example

#...
updaters:
  sets:
    - clair.cvss
#...

Configuring Clair for Oracle

Oracle config.yaml example

#...
updaters:
  sets:
    - oracle
#...

Configuring Clair for Photon

Photon config.yaml example

#...
updaters:
  sets:
    - photon
#...

Configuring Clair for SUSE

SUSE config.yaml example

#...
updaters:
  sets:
    - suse
#...

Configuring Clair for Ubuntu

Ubuntu config.yaml example

#...
updaters:
  sets:
    - ubuntu
#...

Configuring Clair for OSV

OSV config.yaml example

#...
updaters:
  sets:
    - osv
#...

2.5.2. Selecting updater sets for full Red Hat Enterprise Linux (RHEL) coverage

For full coverage of vulnerabilities in Red Hat Enterprise Linux (RHEL), you must use the following updater sets:

rhel. This updater ensures that you have the latest information on the vulnerabilities that affect RHEL.
rhcc. This updater keeps track of vulnerabilities related to Red hat’s container images.
clair.cvss. This updater offers a comprehensive view of the severity and risk assessment of vulnerabilities by providing Common Vulnerabilities and Exposures (CVE) scores.
osv. This updater focuses on tracking vulnerabilities in open-source software components. This updater is recommended due to how common the use of Java and Go are in RHEL products.

RHEL updaters example

#...
updaters:
  sets:
    - rhel
    - rhcc
    - clair.cvss
    - osv
#...

2.5.3. Advanced updater configuration

In some cases, users might want to configure updaters for specific behavior, for example, if you want to allowlist specific ecosystems for the Open Source Vulnerabilities (OSV) updaters.

Advanced updater configuration might be useful for proxy deployments or air gapped deployments. Configuration for specific updaters in these scenarios can be passed by putting a key underneath the config environment variable of the updaters object. Users should examine their Clair logs to double-check names.

The following YAML snippets detail the various settings available to some Clair updater

Important

For more users, advanced updater configuration is unnecessary.

Configuring the alpine updater

#...
updaters:
  sets:
    - apline
  config:
    alpine:
      url: https://secdb.alpinelinux.org/
#...

Configuring the debian updater

#...
updaters:
  sets:
    - debian
  config:
    debian:
      mirror_url: https://deb.debian.org/
      json_url: https://security-tracker.debian.org/tracker/data/json
#...

Configuring the clair.cvss updater

#...
updaters:
  config:
    clair.cvss:
      url: https://nvd.nist.gov/feeds/json/cve/1.1/
#...

Configuring the oracle updater

#...
updaters:
  sets:
    - oracle
  config:
    oracle-2023-updater:
      url:
        - https://linux.oracle.com/security/oval/com.oracle.elsa-2023.xml.bz2
    oracle-2022-updater:
      url:
        - https://linux.oracle.com/security/oval/com.oracle.elsa-2022.xml.bz2
#...

Configuring the photon updater

#...
updaters:
  sets:
    - photon
  config:
    photon:
      url: https://packages.vmware.com/photon/photon_oval_definitions/
#...

Configuring the rhel updater

#...
updaters:
  sets:
    - rhel
  config:
    rhel:
      url: https://access.redhat.com/security/data/oval/v2/PULP_MANIFEST
      ignore_unpatched: true 1
#...

1: Boolean. Whether to include information about vulnerabilities that do not have corresponding patches or updates available.

Configuring the rhcc updater

#...
updaters:
  sets:
    - rhcc
  config:
    rhcc:
      url: https://access.redhat.com/security/data/metrics/cvemap.xml
#...

Configuring the suse updater

#...
updaters:
  sets:
    - suse
  config:
    suse:
      url: https://support.novell.com/security/oval/
#...

Configuring the ubuntu updater

#...
updaters:
  config:
    ubuntu:
      url: https://api.launchpad.net/1.0/
      name: ubuntu
      force: 1
        - name: focal 2
          version: 20.04 3
#...

1: Used to force the inclusion of specific distribution and version details in the resulting UpdaterSet, regardless of their status in the API response. Useful when you want to ensure that particular distributions and versions are consistently included in your updater configuration.
2: Specifies the distribution name that you want to force to be included in the UpdaterSet.
3: Specifies the version of the distribution you want to force into the UpdaterSet.

Configuring the osv updater

#...
updaters:
  sets:
    - osv
  config:
    osv:
      url: https://osv-vulnerabilities.storage.googleapis.com/
      allowlist: 1
        - npm
        - pypi
#...

1: The list of ecosystems to allow. When left unset, all ecosystems are allowed. Must be lowercase. For a list of supported ecosystems, see the documentation for defined ecosystems.

2.5.4. Disabling the Clair Updater component

In some scenarios, users might want to disable the Clair updater component. Disabling updaters is required when running Red Hat Quay in a disconnected environment.

In the following example, Clair updaters are disabled:

#...
matcher:
  disable_updaters: true
#...

2.6. CVE ratings from the National Vulnerability Database

As of Clair v4.2, Common Vulnerability Scoring System (CVSS) enrichment data is now viewable in the Red Hat Quay UI. Additionally, Clair v4.2 adds CVSS scores from the National Vulnerability Database for detected vulnerabilities.

With this change, if the vulnerability has a CVSS score that is within 2 levels of the distribution score, the Red Hat Quay UI present’s the distribution’s score by default. For example:

Clair v4.2 data display

This differs from the previous interface, which would only display the following information:

Clair v4 data display

2.7. Federal Information Processing Standard (FIPS) readiness and compliance

The Federal Information Processing Standard (FIPS) developed by the National Institute of Standards and Technology (NIST) is regarded as the highly regarded for securing and encrypting sensitive data, notably in highly regulated areas such as banking, healthcare, and the public sector. Red Hat Enterprise Linux (RHEL) and OpenShift Container Platform support FIPS by providing a FIPS mode, in which the system only allows usage of specific FIPS-validated cryptographic modules like openssl. This ensures FIPS compliance.

2.7.1. Enabling FIPS compliance

Use the following procedure to enable FIPS compliance on your Red Hat Quay deployment.

Prerequisite

If you are running a standalone deployment of Red Hat Quay, your Red Hat Enterprise Linux (RHEL) deployment is version 8 or later and FIPS-enabled.
If you are deploying Red Hat Quay on OpenShift Container Platform, OpenShift Container Platform is version 4.10 or later.
Your Red Hat Quay version is 3.5.0 or later.
If you are using the Red Hat Quay on OpenShift Container Platform on an IBM Power or IBM Z cluster:
- OpenShift Container Platform version 4.14 or later is required
- Red Hat Quay version 3.10 or later is required
You have administrative privileges for your Red Hat Quay deployment.

Procedure

In your Red Hat Quay config.yaml file, set the FEATURE_FIPS configuration field to true. For example:
```
---
FEATURE_FIPS = true
---
```
With FEATURE_FIPS set to true, Red Hat Quay runs using FIPS-compliant hash functions.