第 5 章 Clair 安全扫描程序

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

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

HTTP_PROXY

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

HTTPS_PROXY.

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

SSL_CERT_DIR

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

NO_PROXY

$ export NO_PROXY=<comma_separated_list_of_hosts_and_domains>

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

您还必须确保将标准 Clair URL 添加到代理 allowlist 中：

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 证书。必须是 full-chain 证书。

常规 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 作为值的映射。

索引器配置示例

以下示例显示了 Clair 的假设索引器配置。

索引器配置示例

# ...
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	字符串	决定新安全公告的更新频率。默认值为 `6h`。
.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	字符串数组	为树内 `matchers` 提供配置。
.names	字符串	一个字符串值列表，用于告知匹配者工厂关于启用的匹配者信息。如果值设为 `null`，则运行匹配者的默认列表。以下字符串被接受： alpine-matcher,aws-matcher,debian-matcher,gobin,java-maven,oracle,photon,python,rhel,rhel-container-matcher,ruby,suse,ubuntu-matcher
.config	字符串	提供特定匹配器的配置。由包含子对象的 matcher 名称键的映射，它将提供给 matchers 工厂构造器。例如：

matchers 配置示例

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

matchers 配置示例

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

5.1.7. Clair 更新器配置字段

下表描述了 Clair 更新器组件的配置字段。

表 5.2. 更新器配置字段
字段	类型	描述
Updaters	对象	为匹配者的更新管理器提供配置。
.sets	字符串	一个值列表，告知更新管理器要运行的更新程序。如果值设为 `null`，则默认的更新程序集合运行如下： alpine,aws,clair.cvss,debian,oracle,photon,osv,rhel,rhcc suse,ubuntu 如果留空，则运行零更新器。
.config	字符串	提供特定更新器集的配置。由 updater 集合的名称键，包含将提供给更新器集的子对象。有关每个更新器的子对象列表，请参阅"高级更新器配置"。

更新器配置示例

在以下配置中，仅配置 rhel set。也会定义特定于 rhel updater 的 ignore_unpatched 变量。

更新器配置示例

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

5.1.8. Clair 通知程序配置字段

Clair 的一般通知配置字段如下所示。

字段	类型	描述
notifier	对象	提供 Clair 通知程序节点配置。
.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 notifier 环境。

表 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 交付配置通知程序。 [注意] ==== Clair 不自行声明任何 AMQP 组件。所有尝试使用交换或队列的尝试都只是被动，并且会失败。代理管理员应提前设置交换和队列。====
.amqp.direct	布尔值	如果为 `true`，则通知程序会向配置的 AMQP 代理提供单独的通知（而不是回调）。
.amqp.rollup	整数	当 `amqp.direct` 设为 `true` 时，这个值会通知通知程序在直接发送中发送了多少通知。例如，如果 `direct` 设为 `true`，并且 `amqp.rollup` 设为 `5`，则通知程序在单个 JSON 有效负载中不再提供 5 通知到代理。将值设为 `0` 实际的效果是将其设置为 `1`。
.amqp.exchange	对象	要连接的 AMQP 交换。
.amqp.exchange.name	字符串	要连接的交换的名称。
.amqp.exchange.type	字符串	交换的类型。通常，以下之一： direct,fanout,topic,标头.
.amqp.exchange.durability	布尔值	配置的队列是否持久。
.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 证书的文件系统路径。 [注意] ==== Clair 还允许 `SSL_CERT_DIR`，如 Go `crypto/x509` 软件包所记录。====
.amqp.tls.key	字符串	可以读取 TLS/SSL 私钥的文件系统路径。

AMQP 配置示例

以下示例显示了 Clair 的假设 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 配置字段

以下简单文本介绍的消息协议(STOMP)字段可用于 Clair 通知程序环境。

.stomp	对象	为 STOMP 交付配置通知程序。
.stomp.direct	布尔值	如果为 `true`，则通知程序会向配置的 STOMP 代理提供单独的通知（而非回调）。
.stomp.rollup	整数	如果 `stomp.direct` 设为 `true`，则这个值会限制在单个直接发送中发送的通知数量。例如，如果 `direct` 设置为 `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 的文件系统路径。 [注意] ==== 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 传递码。

STOMP 配置示例

以下示例显示了 Clair 的假设 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	字符串	应用程序 trace 的名称将属于。
.probability	整数	将发生 trace 的可能性。
.jaeger	对象	定义 Jaeger tracing 的值。
.jaeger.agent	对象	定义用于配置发送到 Jaeger 代理的值。
.jaeger.agent.endpoint	字符串	可以在 < `host>:<post` > 语法中提交 trace 的地址。
.jaeger.collector	对象	为配置发送到 Jaeger 收集器定义值。
.jaeger.collector.endpoint	字符串	可以在 < `host>:<post` > 语法中提交 trace 的地址。
.jaeger.collector.username	字符串	Jaeger 用户名。
.jaeger.collector.password	字符串	Jaeger 密码。
.jaeger.service_name	字符串	在 Jaeger 中注册的服务名称。
.jaeger.tags	字符串	用于提供额外的元数据的键值对。
.jaeger.buffer_max	整数	在将内存发送到 Jaeger 后端以进行存储和分析前，可以缓冲的最大 span 数量。

trace 配置示例

以下示例显示了 Clair 的假设跟踪配置。

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 的假设指标配置。

指标配置示例

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

5.1. Clair 配置概述