Chapter 2. Clair concepts

Clair treats all manifests and layers as content addressable. In the context of Clair, content addressable means that when a specific manifest is indexed, it is not indexed again unless it is required; this is the same for individual layers.

For example, consider how many images in a registry might use ubuntu:artful as a base layer. If the developers prefer basing their images off of Ubuntu, it could be a large majority of images. Treating the layers and manifests as content addressable means that Clair only fetches and analyzes the base layer one time.

In some cases, Clair should re-index a manifest. For example, when an internal component such as a package scanner is updated, Clair performs the analysis with the new package scanner. Clair has enough information to determine that a component has changed and that the IndexReport might be different the second time, and as a result it re-indexes the manifest.

A client can track Clair’s index_state endpoint to understand when an internal component has changed, and can subsequently issue re-indexes. See the Clair API guide to learn how to view Clair’s API specification.

A remote matcher acts similar to a matcher, however remote matchers use API calls to fetch vulnerability data for a provided IndexReport. Remote matchers are useful when it is impossible to persist data from a given source into the database.

The CRDA remote matcher is responsible for fetching vulnerabilities from Red Hat Code Ready Dependency Analytics (CRDA). By default, this matcher serves 100 requests per minute. The rate limiting can be lifted by requesting a dedicated API key, which is done by submitting the API key request form.

To enable CRDA remote matching, see "Enabling CRDA for Clair".

When you configure the notifier for webhook delivery, you provide the service with the following pieces of information:

When the notifier has determined an updated security database has been changed the affected status of an indexed manifest, it delivers the following JSON body to the configured target:

{
  "notifiction_id": {uuid_string},
  "callback": {url_to_notifications}
}

On receipt, the server can browse to the URL provided in the callback field.

The Clair notifier also supports delivering notifications to an AMQP broker. With AMQP delivery, you can control whether a callback is delivered to the broker or whether notifications are directly delivered to the queue. This allows the developer of the AMQP consumer to determine the logic of notification processing.

The notifier has a testing and development mode that can be enabled with the NOTIFIER_TEST_MODE parameter. This parameter can be set to any value.

When the NOTIFIER_TEST_MODE parameter is set, the notifier begins sending fake notifications to the configured delivery mechanism every poll_interval interval. This provides an easy way to implement and test new or existing deliverers.

The notifier runs in NOTIFIER_TEST_MODE until the environment variable is cleared and the service is restarted.

To delete the notification, you can use the DELETE API call. Deleting a notification ID manually cleans up resources in the notifier. If you do not use the DELETE API call, the notifier waits a predetermined length of time before clearing delivered notifications from its database.

The following sets can be configured with Clair updaters:

Specific sets of updaters can be selected by the sets list. For example:

updaters:
  sets:
    - rhel

If the sets field is not populated, it defaults to using all sets.

To reject an updater from running without disabling an entire set, the filter option can be used.

In the following example, the string is interpreted as a Go regexp package. This rejects any updater with a name that does not match.

updaters:
  filter: '^$'

Configuration for specific updaters can be passed by putting a key underneath the config parameter of the updaters object. The name of an updater might be constructed dynamically, and users should examine logs to ensure updater names are accurate. The specific object that an updater expects should be covered in the updater’s documentation.

In the following example, the rhel updater fetches a manifest from a different location:

updaters:
  config:
    rhel:
      url: https://example.com/mirror/oval/PULP_MANIFEST

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