第 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 需要添加到代理允许列表中，以确保 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 证书。必须是 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 indexer 配置字段

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

字段	类型	描述
indexer	对象	提供 Clair 索引节点配置。
.airgap	布尔值	为 indexers 和 fetchers 禁用对互联网的 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 matcher 配置字段

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

注意

与 匹配器 配置字段不同。

字段	类型	描述
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 matchers 配置字段

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

注意

与 匹配配置字段 不同。

表 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	字符串	为特定匹配器提供配置。一个映射键是包含子对象的 matcher 名称键，该对象将提供给匹配者工厂构造器。例如：

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	对象	为 matcher 的更新管理器提供配置。
.sets	字符串	一个值列表，告知更新管理器要运行的更新程序。如果值设为 `null`，则默认更新程序将运行以下内容： alpine,aws,clair.cvss,debian,oracle,photon,osv,rhel,rhcc suse,0.11.0- 如果留空，则运行零更新程序。
.config	字符串	为特定更新器集提供配置。由 updater 集名称的映射键包含子对象，该对象将提供给 updater 设置的构造器。有关每个 updater 的子对象列表，请参阅"高级更新器配置"。

updaters 配置示例

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

updaters 配置示例

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

5.1.8. Clair 通知程序配置字段

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

字段	类型	描述
通知程序	对象	提供 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 通知程序环境。

表 5.3. Clair Webhook 字段
.webhook	对象	配置用于 Webhook 发送的通知程序。
.webhook.target	字符串	提供 webhook 的 URL。
.webhook.callback	字符串	可以检索通知的回调 URL。通知 ID 将附加到此 URL 中。这通常是托管 Clair 通知程序的位置。
.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` 时，这个值告知通知要直接发送多少通知。例如，如果 `direct` 设置为 `true`，并且 `amqp.rollup` 设置为 `5`，则通知程序不会在单个 JSON 有效负载向代理中提供 5 个通知。将值设为 `0` 实际的效果是将其设置为 `1`。
.amqp.exchange	对象	要连接的 AMQP 交换。
.amqp.exchange.name	字符串	要连接的交换的名称。
.amqp.exchange.type	字符串	交换的类型。通常，以下之一：直接、发出、主题、标题.
.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	对象	配置 TLS/SSL 连接到 AMQP 代理。
.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`，则该值限制在单个直接发送中发送的通知数量。例如，如果 `direct` 设为 `true`，并且 `滚动` 设置为 `5`，则通知程序不会在单个 JSON 有效负载中向代理发送 5 个通知。将值设为 `0` 实际的效果是将其设置为 `1`。
.stomp.callback	字符串	如果 `stomp.callback` 设置为 `false`，则通知回调中提供的 URL 将发送到代理。此 URL 应指向 Clair 的通知 API 端点。
.stomp.destination	字符串	将通知发送到的 STOMP 目的地。
.stomp.uris	字符串	要以优先级顺序连接到的一个或多个 STOMP 代理的列表。
.stomp.tls	对象	配置 TLS/SSL 连接到 STOMP 代理。
.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 tracing 定义值。
.jaeger.agent	对象	定义用于配置发送到 Jaeger 代理的值。
.jaeger.agent.endpoint	字符串	可提交 trace 的 & `lt;host>:<post` > 语法中的地址。
.jaeger.collector	对象	为配置发送到 Jaeger 收集器定义值。
.jaeger.collector.endpoint	字符串	可提交 trace 的 & `lt;host>:<post` > 语法中的地址。
.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"
# ...

5.1. Clair 配置概述