第 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 的位置。
默认: |
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 | 整数 |
速率限制索引报告创建请求的数量。把它设置为
如果超过并发状态,API 会返回 |
.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 | 字符串 | 匹配者联系索引程序来创建漏洞报告。需要此索引器的位置。
默认值为 |
.migrations | 布尔值 | 匹配器节点是否处理迁移到其数据库的迁移。 |
.period | 字符串 | 决定新安全公告的更新频率。
默认值为 |
.disable_updaters | 布尔值 | 是否运行后台更新。
Default: |
.update_retention | 整数 | 设置在垃圾回收周期之间保留的更新操作数量。这应该根据数据库大小限制设置为安全 MAX 值。
默认值为
如果提供小于 |
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
配置字段不同。
字段 | 类型 | 描述 |
---|---|---|
matchers | 字符串数组 |
为树内 |
.names | 字符串 |
一个字符串值列表,用于告知匹配者工厂关于启用的匹配者信息。如果值设为 |
.config | 字符串 | 为特定匹配程序提供配置。 由匹配者名称的键的映射,其中包含将提供给 matchers 工厂构造器的子对象。例如: |
matchers 配置示例
以下示例显示了一个假设的 Clair 部署,它只需要 alpine
,aws
,debian
,oracle
matchers。
matchers 配置示例
# ... matchers: names: - "alpine-matcher" - "aws" - "debian" - "oracle" # ...
5.1.7. Clair updaters 配置字段
下表描述了 Clair 的 updaters 组件 的配置字段
。
字段 | 类型 | 描述 |
---|---|---|
updaters | 对象 | 为匹配器的更新管理器提供配置。 |
.sets | 字符串 | 一个值列表,告知更新管理器要运行的更新程序。
如果值设为 如果留空,则运行零 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 通知程序环境。
.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 | 布尔值 |
如果为 |
.amqp.rollup | 整数 |
当 |
.amqp.exchange | 对象 | 要连接的 AMQP 交换。 |
.amqp.exchange.name | 字符串 | 要连接的交换名称。 |
.amqp.exchange.type | 字符串 | 交换的类型。通常,以下之一: direct、fanout、topic、Header。 |
.amqp.exchange.durability | 布尔值 | 配置的队列是 durable。 |
.amqp.exchange.auto_delete | 布尔值 |
配置的队列是否使用 |
.amqp.routing_key | 字符串 | 每个通知的路由键的名称。 |
.amqp.callback | 字符串 |
如果 |
.amqp.uris | 字符串 | 要连接的一个或多个 AMQP 代理的列表,按优先级顺序进行。 |
.amqp.tls | 对象 | 配置到 AMQP 代理的 TLS/SSL 连接。 |
.amqp.tls.root_ca | 字符串 | 可以读取 root CA 的文件系统路径。 |
.amqp.tls.cert | 字符串 | 可以读取 TLS/SSL 证书的文件系统路径。
[NOTE] ==== Clair 还允许 |
.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 | 布尔值 |
如果为 |
.stomp.rollup | 整数 |
如果 |
.stomp.callback | 字符串 |
如果 |
.stomp.destination | 字符串 | 要发送通知的 STOMP 目的地。 |
.stomp.uris | 字符串 | 按顺序连接的一个或多个 STOMP 代理的列表。 |
.stomp.tls | 对象 | 配置到 STOMP 代理的 TLS/SSL 连接。 |
.stomp.tls.root_ca | 字符串 | 可以读取 root CA 的文件系统路径。
[NOTE] ==== Clair 还尊重 |
.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 身份验证。如果定义了多个 |
.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 | 字符串 |
< |
.jaeger.collector | 对象 | 为配置发送到 Jaeger 收集器定义值。 |
.jaeger.collector.endpoint | 字符串 |
< |
.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" # ...