支持控制台（Console）开发人员开始试用联系人

第 5 章 Clair for Red Hat Quay

Clair v4 (Clair)是一个开源应用程序，它利用静态代码分析来解析镜像内容和报告影响内容的漏洞。Clair 与 Red Hat Quay 打包，并可用于独立和 Operator 部署。它可以在高度可扩展的配置中运行，其中组件可根据企业环境单独扩展。

5.1. Clair 配置概述

Clair 由一个结构化的 YAML 文件配置。每个 Clair 节点都需要指定其将在其中运行的模式，以及通过 CLI 标志或环境变量的配置文件的路径。例如： 

$ clair -conf ./path/to/config.yaml -mode indexer

或者 

$ clair -conf ./path/to/config.yaml -mode matcher

以上命令各自使用相同的配置文件启动两个 Clair 节点。一个运行索引功能，另一个则运行匹配的功能。

如果您以 组合 模式运行 Clair，则必须在配置中提供索引器、匹配器和通知程序配置块。

5.1.1. 在代理环境中使用 Clair 的信息

如果需要，可以指定 Go 标准库所遵守的环境变量，例如：

  • HTTP_PROXY 

    $ export http://<user_name>:<password>@<proxy_host>:<proxy_port>

  • HTTPS_PROXY. 

    $ export https://<user_name>:<password>@<proxy_host>:<proxy_port>

  • SSL_CERT_DIR. 

    $ export SSL_CERT_DIR=/<path>/<to>/<ssl>/<certificates>

如果您使用带有 Clair 更新器 URL 的环境中的代理服务器，您必须识别哪些 URL 需要添加到代理允许列表中，以确保 Clair 可以访问它们。例如： osv updater 需要访问 https://osv-vulnerabilities.storage.googleapis.com 来获取生态系统数据转储。在这种情况下，URL 必须添加到代理允许列表中。有关 updater URL 的完整列表，请参阅"Clair updater URL"。

您还必须确保将标准 Clair URL 添加到代理允许列表中：

  • https://search.maven.org/solrsearch/select
  • https://catalog.redhat.com/api/containers/
  • https://access.redhat.com/security/data/metrics/repository-to-cpe.json
  • https://access.redhat.com/security/data/metrics/container-name-repos-map.json

在配置代理服务器时，请考虑启用 Clair 和这些 URL 之间的无缝通信所需的任何身份验证要求或特定的代理设置。通过全面记录并解决这些注意事项，您可以确保在通过代理路由更新器流量的同时，有效处理 Clair 功能。

5.1.2. Clair 配置参考

以下 YAML 显示了一个 Clair 配置示例： 

http_listen_addr: ""
introspection_addr: ""
log_level: ""
tls: {}
indexer:
    connstring: ""
    scanlock_retry: 0
    layer_scan_concurrency: 5
    migrations: false
    scanner: {}
    airgap: false
matcher:
    connstring: ""
    indexer_addr: ""
    migrations: false
    period: ""
    disable_updaters: false
    update_retention: 2
matchers:
    names: nil
    config: nil
updaters:
    sets: nil
    config: nil
notifier:
    connstring: ""
    migrations: false
    indexer_addr: ""
    matcher_addr: ""
    poll_interval: ""
    delivery_interval: ""
    disable_summary: false
    webhook: null
    amqp: null
    stomp: null
auth:
  psk: nil
trace:
    name: ""
    probability: null
    jaeger:
        agent:
            endpoint: ""
        collector:
            endpoint: ""
            username: null
            password: null
        service_name: ""
        tags: nil
        buffer_max: 0
metrics:
    name: ""
    prometheus:
        endpoint: null
    dogstatsd:
        url: ""
注意

为了完整，以上 YAML 文件列出了每个键。使用此配置文件原样将导致一些选项不会正常设置默认值。

5.1.3. Clair 常规字段

下表描述了 Clair 部署可用的常规配置字段。

字段Typhttp_listen_ae描述

http_listen_addr

字符串

配置公开 HTTP API 的位置。

默认： :6060

introspection_addr

字符串

配置 Clair 的指标和健康端点公开的位置。

log_level

字符串

设置日志级别。需要以下字符串之一： debug-color、debug、info、warn、error、fatal、panic

tls

字符串

包含提供 TLS/SSL 和 HTTP/2 的 HTTP API 配置的映射。

.cert

字符串

要使用的 TLS 证书。必须是全链证书。

常规 Clair 字段的配置示例

以下示例显示了 Clair 配置。

常规 Clair 字段的配置示例

# ...
http_listen_addr: 0.0.0.0:6060
introspection_addr: 0.0.0.0:8089
log_level: info
# ...

5.1.4. Clair 索引器配置字段

下表描述了 Clair 的 indexer 组件的配置字段。

字段类型描述

indexer

对象

提供 Clair 索引器节点配置。

.airgap

布尔值

为索引器和获取者禁用对互联网的 HTTP 访问。允许私有 IPv4 和 IPv6 地址。数据库连接不受影响。

.connstring

字符串

Postgres 连接字符串。接受格式为 URL 或 libpq 连接字符串。

.index_report_request_concurrency

整数

速率限制索引报告创建请求的数量。把它设置为 0， 以自动调整此值的大小。设置负值意味着无限。自动大小是可用内核数的倍数。

如果超过并发状态，API 会返回 429 状态代码。

.scanlock_retry

整数

代表秒的正整数。在清单扫描时并发索引器锁定，以避免冲突。这个值调整等待索引器轮询锁定的频率。

.layer_scan_concurrency

整数

正整数限制并发层扫描的数量。Indexers 将同时匹配清单的层。这个值调整索引程序并行扫描的层数。

.migrations

布尔值

索引器节点是否处理迁移到其数据库的迁移。

.scanner

字符串

索引器配置。

扫描程序允许将配置选项传递给层扫描程序。如果设计这样做，扫描程序会将此配置传递给它。

.scanner.dist

字符串

特定扫描程序名称和任意 YAML 作为值的映射。

.scanner.package

字符串

特定扫描程序名称和任意 YAML 作为值的映射。

.scanner.repo

字符串

特定扫描程序名称和任意 YAML 作为值的映射。

indexer 配置示例

以下示例显示了 Clair 的 hypothetical indexer 配置。

indexer 配置示例

# ...
indexer:
  connstring: host=quay-server.example.com port=5433 dbname=clair user=clairuser password=clairpass sslmode=disable
  scanlock_retry: 10
  layer_scan_concurrency: 5
  migrations: true
# ...

5.1.5. Clair 匹配程序配置字段

下表描述了 Clair 的 matcher 组件的配置字段。

注意

与 matchers 配置字段不同。

字段类型描述

matcher

对象

提供 Clair 匹配器节点配置。

.cache_age

字符串

控制用户应提示缓存响应的时间。

.connstring

字符串

Postgres 连接字符串。接受格式为 URL 或 libpq 连接字符串。

.max_conn_pool

整数

限制数据库连接池大小。

Clair 允许自定义连接池大小。这个数字直接设定同时允许的活跃数据库连接的数量。

这个参数将在以后的发行版本中被忽略。用户应该通过连接字符串进行配置。

.indexer_addr

字符串

匹配者联系索引程序来创建漏洞报告。需要此索引器的位置。

默认值为 30m。

.migrations

布尔值

匹配器节点是否处理迁移到其数据库的迁移。

.period

字符串

决定新安全公告的更新频率。

默认值为 30m。

.disable_updaters

布尔值

是否运行后台更新。

Default: False

.update_retention

整数

设置在垃圾回收周期之间保留的更新操作数量。这应该根据数据库大小限制设置为安全 MAX 值。

默认值为 10m。

如果提供小于 0 的值，则禁用垃圾回收。2 是确保可将更新与通知进行比较的最小值。

matcher 配置示例

matcher 配置示例

# ...
matcher:
  connstring: >-
    host=<DB_HOST> port=5432 dbname=<matcher> user=<DB_USER> password=D<B_PASS>
    sslmode=verify-ca sslcert=/etc/clair/ssl/cert.pem sslkey=/etc/clair/ssl/key.pem
    sslrootcert=/etc/clair/ssl/ca.pem
  indexer_addr: http://clair-v4/
  disable_updaters: false
  migrations: true
  period: 6h
  update_retention: 2
# ...

5.1.6. Clair 匹配器配置字段

下表描述了 Clair 的 matchers 组件的配置字段。

注意

与 matcher 配置字段不同。

表 5.1. matchers 配置字段
字段类型描述

matchers

字符串数组

为树内 匹配器提供配置。

.names

字符串

一个字符串值列表，用于告知匹配者工厂关于启用的匹配者信息。如果值设为 null，则默认匹配者列表将运行。以下字符串被接受： alpine-matcher,aws-matcher,debian-matcher,gobin,java-maven,oracle,photon,python, rhel ,rhel -container-matcher,ruby, suse ,suse,ubuntu-matcher

.config

字符串

为特定匹配程序提供配置。

由匹配者名称的键的映射，其中包含将提供给 matchers 工厂构造器的子对象。例如：

matchers 配置示例

以下示例显示了一个假设的 Clair 部署，它只需要 alpine,aws,debian,oracle matchers。

matchers 配置示例

# ...
matchers:
  names:
  - "alpine-matcher"
  - "aws"
  - "debian"
  - "oracle"
# ...

5.1.7. Clair updaters 配置字段

下表描述了 Clair 的 updaters 组件 的配置字段。

表 5.2. 更新器配置字段
字段类型描述

updaters

对象

为匹配器的更新管理器提供配置。

.sets

字符串

一个值列表，告知更新管理器要运行的更新程序。

如果值设为 null，则默认更新程序将运行以下内容： alpine,aws,clair.cvss,debian,oracle,photon,osv,rhel,rhcc suse,0.11.0-

如果留空，则运行零 updaters。

.config

字符串

为特定更新器集提供配置。

由 updater 集名称的键的映射，其中包含将提供给 updater 设置构造器的子对象。有关每个 updater 的子对象列表，请参阅"高级更新器配置"。

updaters 配置示例

在以下配置中，仅配置 rhel 集。也定义了特定于 rhel 更新器的 ignore_unpatched 变量。

updaters 配置示例

# ...
updaters:
  sets:
    - rhel
  config:
    rhel:
      ignore_unpatched: false
# ...

5.1.8. Clair 通知程序配置字段

Clair 的一般通知程序配置字段如下。

字段类型描述

通知程序

对象

提供 Clair notifier 节点配置。

.connstring

字符串

postgres 连接字符串。接受格式为 URL 或 libpq 连接字符串。

.migrations

布尔值

通知节点是否处理迁移到其数据库的迁移。

.indexer_addr

字符串

通知程序联系索引器来创建或获取受漏洞影响的清单。需要此索引器的位置。

.matcher_addr

字符串

通知程序联系一个匹配者来列出更新操作并获取 diffs。这个匹配器的位置是必需的。

.poll_interval

字符串

通知程序查询匹配程序更新操作的频率。

.delivery_interval

字符串

通知程序尝试发送创建的频率，或者以前失败的通知。

.disable_summary

布尔值

控制是否应为每个清单将通知总结到一个。

通知程序配置示例

以下 通知程序 片断用于最小配置。

通知程序配置示例

# ...
notifier:
  connstring: >-
    host=DB_HOST port=5432 dbname=notifier user=DB_USER password=DB_PASS
    sslmode=verify-ca sslcert=/etc/clair/ssl/cert.pem sslkey=/etc/clair/ssl/key.pem
    sslrootcert=/etc/clair/ssl/ca.pem
  indexer_addr: http://clair-v4/
  matcher_addr: http://clair-v4/
  delivery_interval: 5s
  migrations: true
  poll_interval: 15s
  webhook:
    target: "http://webhook/"
    callback: "http://clair-notifier/notifier/api/v1/notifications"
    headers: ""
  amqp: null
  stomp: null
# ...

5.1.8.1. Clair Webhook 配置字段

以下 Webhook 字段可用于 Clair 通知程序环境。

表 5.3. Clair Webhook 字段

.webhook

对象

配置 webhook 交付通知程序。

.webhook.target

字符串

发送 webhook 的 URL。

.webhook.callback

字符串

检索通知的回调 URL。通知 ID 将附加到此 URL。

这通常是托管 Clair notifier 的位置。

.webhook.headers

字符串

将标头名称与值列表关联的映射。

Webhook 配置示例

Webhook 配置示例

# ...
notifier:
# ...
  webhook:
    target: "http://webhook/"
    callback: "http://clair-notifier/notifier/api/v1/notifications"
# ...

5.1.8.2. Clair amqp 配置字段

以下高级消息队列协议(AMQP)字段可用于 Clair 通知程序环境。

.amqp

对象

配置用于 AMQP 交付的通知。

[NOTE] ==== Clair 不自行声明任何 AMQP 组件。所有尝试使用交换或队列的尝试都是被动的，将失败。代理管理员应提前设置交换和队列。===

.amqp.direct

布尔值

如果为 true，则通知程序会将各个通知（而非回调）提供给配置的 AMQP 代理。

.amqp.rollup

整数

当 amqp.direct 设为 true 时，这个值会告知通知通知在直接发送中发送多少通知。例如，如果 直接 设置为 true，并且 amqp.rollup 设置为 5，则通知程序在单个 JSON 有效负载中为代理提供超过 5 个通知。将值设为 0 实际的效果是将其设置为 1。

.amqp.exchange

对象

要连接的 AMQP 交换。

.amqp.exchange.name

字符串

要连接的交换名称。

.amqp.exchange.type

字符串

交换的类型。通常，以下之一： direct、fanout、topic、Header。

.amqp.exchange.durability

布尔值

配置的队列是 durable。

.amqp.exchange.auto_delete

布尔值

配置的队列是否使用 auto_delete_policy。

.amqp.routing_key

字符串

每个通知的路由键的名称。

.amqp.callback

字符串

如果 amqp.direct 设为 false，则此 URL 在发送到代理的通知回调中提供。此 URL 应该指向 Clair 的通知 API 端点。

.amqp.uris

字符串

要连接的一个或多个 AMQP 代理的列表，按优先级顺序进行。

.amqp.tls

对象

配置到 AMQP 代理的 TLS/SSL 连接。

.amqp.tls.root_ca

字符串

可以读取 root CA 的文件系统路径。

.amqp.tls.cert

字符串

可以读取 TLS/SSL 证书的文件系统路径。

[NOTE] ==== Clair 还允许 SSL_CERT_DIR，如 Go crypto/x509 软件包所记录。====

.amqp.tls.key

字符串

读取 TLS/SSL 私钥的文件系统路径。

AMQP 配置示例

以下示例显示了 Clair 的 hypothetical AMQP 配置。

AMQP 配置示例

# ...
notifier:
# ...
  amqp:
    exchange:
        name: ""
        type: "direct"
        durable: true
        auto_delete: false
    uris: ["amqp://user:pass@host:10000/vhost"]
    direct: false
    routing_key: "notifications"
    callback: "http://clair-notifier/notifier/api/v1/notifications"
    tls:
     root_ca: "optional/path/to/rootca"
     cert: "madatory/path/to/cert"
     key: "madatory/path/to/key"
# ...

5.1.8.3. Clair STOMP 配置字段

Clair 通知程序环境提供了以下简单文本导向型消息协议(STOMP)字段。

.stomp对象为 STOMP 发送配置通知程序。

.stomp.direct

布尔值

如果为 true，则通知程序会向配置的 STOMP 代理提供单独的通知（而非回调）。

.stomp.rollup

整数

如果 stomp.direct 设为 true，则该值限制在单个直接交付中发送的通知数量。例如，如果 直接 设置为 true，并且 rollup 设置为 5，则通知程序在单个 JSON 有效负载中为代理提供超过 5 个通知。将值设为 0 实际的效果是将其设置为 1。

.stomp.callback

字符串

如果 stomp.callback 设为 false，则通知回调中提供的 URL 将发送到代理。此 URL 应该指向 Clair 的通知 API 端点。

.stomp.destination

字符串

要发送通知的 STOMP 目的地。

.stomp.uris

字符串

按顺序连接的一个或多个 STOMP 代理的列表。

.stomp.tls

对象

配置到 STOMP 代理的 TLS/SSL 连接。

.stomp.tls.root_ca

字符串

可以读取 root CA 的文件系统路径。

[NOTE] ==== Clair 还尊重 SSL_CERT_DIR，如 Go crypto/x509 软件包所记录。====

.stomp.tls.cert

字符串

可以读取 TLS/SSL 证书的文件系统路径。

.stomp.tls.key

字符串

读取 TLS/SSL 私钥的文件系统路径。

.stomp.user

字符串

为 STOMP 代理配置登录详情。

.stomp.user.login

字符串

要连接的 STOMP 登录。

.stomp.user.passcode

字符串

要连接的 STOMP passcode。

STOMP 配置示例

以下示例显示了 Clair 的 hypothetical STOMP 配置。

STOMP 配置示例

# ...
notifier:
# ...
  stomp:
    desitnation: "notifications"
    direct: false
    callback: "http://clair-notifier/notifier/api/v1/notifications"
    login:
      login: "username"
      passcode: "passcode"
    tls:
     root_ca: "optional/path/to/rootca"
     cert: "madatory/path/to/cert"
     key: "madatory/path/to/key"
# ...

5.1.9. Clair 授权配置字段

以下授权配置字段可用于 Clair。

字段类型描述

auth

对象

定义 Clair 的外部和服务内 JWT 身份验证。如果定义了多个 auth 机制，Clair 会选择一个。目前，不支持多种机制。

.psk

字符串

定义预共享密钥身份验证。

.psk.key

字符串

所有方签名和验证 JWT 之间分发的共享 base64 编码密钥。

.psk.iss

字符串

用于验证的 JWT 签发者列表。空列表接受 JWT 声明中的任何签发者。

授权配置示例

以下 授权 片断用于最小配置。

授权配置示例

# ...
auth:
  psk:
    key: MTU5YzA4Y2ZkNzJoMQ== 1
    iss: ["quay"]
# ...

5.1.10. Clair trace 配置字段

以下 trace 配置字段可用于 Clair。

字段类型描述

trace

对象

定义基于 OpenTelemetry 的分布式追踪配置。

.name

字符串

应用程序跟踪的名称将属于。

.probability

整数

会发生 trace 的概率。

.jaeger

对象

定义 Jaeger 追踪的值。

.jaeger.agent

对象

定义配置发送到 Jaeger 代理的值。

.jaeger.agent.endpoint

字符串

< host>:<post&gt; 语法中的地址，可以提交 trace。

.jaeger.collector

对象

为配置发送到 Jaeger 收集器定义值。

.jaeger.collector.endpoint

字符串

< host>:<post&gt; 语法中的地址，可以提交 trace。

.jaeger.collector.username

字符串

Jaeger 用户名。

.jaeger.collector.password

字符串

Jaeger 密码。

.jaeger.service_name

字符串

在 Jaeger 中注册的服务名称。

.jaeger.tags

字符串

用于提供额外的元数据的键值对。

.jaeger.buffer_max

整数

在将内存缓冲到 Jaeger 后端前可缓冲的最大 span 数量，以存储和分析。

trace 配置示例

以下示例显示了 Clair 的 hypothetical trace 配置。

trace 配置示例

# ...
trace:
  name: "jaeger"
  probability: 1
  jaeger:
    agent:
      endpoint: "localhost:6831"
    service_name: "clair"
# ...

5.1.11. Clair 指标配置字段

以下指标配置字段可用于 Clair。

字段类型描述

metrics

对象

定义基于 OpenTelemetry 的分布式追踪配置。

.name

字符串

使用的指标的名称。

.prometheus

字符串

配置 Prometheus 指标导出器。

.prometheus.endpoint

字符串

定义提供指标的路径。

指标配置示例

以下示例显示了 Clair 的 hypothetical 指标配置。

指标配置示例

# ...
metrics:
  name: "prometheus"
  prometheus:
    endpoint: "/metricsz"
# ...

Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

© 2024 Red Hat, Inc.