Help us learn about your current experience with the documentation. Take the survey.

运行时容器扫描

Tier: Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

支持的架构

在 GitLab agent for Kubernetes 16.10.0 及更高版本和 GitLab agent Helm Chart 1.25.0 及更高版本中，运行时容器扫描（OCS）支持 linux/arm64 和 linux/amd64 架构。对于早期版本，仅支持 linux/amd64。

启用运行时容器扫描

您可以使用 OCS 扫描集群中的容器镜像以发现安全漏洞。在 GitLab agent for Kubernetes 16.9 及更高版本中，OCS 使用围绕 Trivy 的 wrapper image 来扫描镜像漏洞。在 GitLab 16.9 之前，OCS 直接使用 Trivy 镜像。

OCS 可以通过使用 agent config 或项目的扫描执行策略来配置定时运行。

如果同时配置了 agent config 和 scan execution policies，则 scan execution policy 的配置优先。

通过 agent 配置启用

要通过 agent 配置启用对 Kubernetes 集群中镜像的扫描，请在您的 agent 配置中添加一个 container_scanning 配置块，其中包含一个 cadence 字段，该字段包含一个 CRON 表达式，用于指定扫描的运行时间。

container_scanning:
  cadence: '0 0 * * *' # 每天在 00:00（Kubernetes 集群时间）运行

cadence 字段是必需的。GitLab 支持 cadence 字段中的以下类型的 CRON 语法：

每天在指定的小时运行一次，例如：0 18 * * *
每周在指定的日期和指定的小时运行一次，例如：0 13 * * 0

如果我们在实现中使用的 cron 支持，CRON 语法的其他元素可能在 cadence 字段中有效，但 GitLab 不正式测试或支持它们。

CRON 表达式使用 Kubernetes-agent pod 的系统时间在 UTC 中进行评估。

默认情况下，运行时容器扫描不会扫描任何工作负载的漏洞。您可以设置带有 namespaces 字段的 vulnerability_report 块，用于选择要扫描的命名空间。例如，如果您只想扫描 default、kube-system 命名空间，可以使用以下配置：

container_scanning:
  cadence: '0 0 * * *'
  vulnerability_report:
    namespaces:
      - default
      - kube-system

对于每个目标命名空间，默认情况下会扫描以下工作负载资源中的所有镜像：

Pod
ReplicaSet
ReplicationController
StatefulSet
DaemonSet
CronJob
Job

这可以通过配置 Trivy Kubernetes 资源检测进行自定义。

通过扫描执行策略启用

要通过扫描执行策略启用对 Kubernetes 集群中镜像的扫描，使用扫描执行策略编辑器创建一个新的计划规则。

Kubernetes agent 必须在您的集群中运行才能扫描正在运行的容器镜像

运行时容器扫描独立于 GitLab 管道运行。它完全自动化并由 Kubernetes Agent 管理，该代理在扫描执行策略中配置的计划时间启动新扫描。代理在您的集群中创建一个专用的 Job 来执行扫描并将发现报告回 GitLab。

以下是一个启用 Kubernetes agent 所附加集群内运行时容器扫描的策略示例：

- name: Enforce Container Scanning in cluster connected through my-gitlab-agent for default and kube-system namespaces
  enabled: true
  rules:
  - type: schedule
    cadence: '0 10 * * *'
    agents:
      <agent-name>:
        namespaces:
        - 'default'
        - 'kube-system'
  actions:
  - scan: container_scanning

计划规则的键包括：

cadence（必需）：扫描运行的 CRON 表达式
agents:<agent-name>（必需）：用于扫描的 agent 名称
agents:<agent-name>:namespaces（必需）：要扫描的 Kubernetes 命名空间。

如果我们在实现中使用的 cron 支持，CRON 语法的其他元素可能在 cadence 字段中有效，但 GitLab 不正式测试或支持它们。

CRON 表达式使用 Kubernetes-agent pod 的系统时间在 UTC 中进行评估。

您可以在扫描执行策略文档中查看完整的架构。

多集群配置的 OCS 漏洞解决

为确保 OCS 的漏洞跟踪准确，您应该为每个集群创建一个启用了 OCS 的独立 GitLab 项目。如果您有多个集群，请确保每个集群使用一个项目。

OCS 通过将当前扫描的漏洞与先前检测到的漏洞进行比较，来解决在每次扫描后不再在集群中发现的漏洞。先前扫描中存在但当前扫描中不再存在的任何漏洞都会在 GitLab 项目中被解决。

如果多个集群配置在同一个项目中，一个集群（例如项目 A）中的 OCS 扫描将解决另一个集群（例如项目 B）先前检测到的漏洞，导致错误的漏洞报告。

配置扫描器资源需求

默认情况下，扫描器 pod 的默认资源需求为：

requests:
  cpu: 100m
  memory: 100Mi
  ephemeral_storage: 1Gi
limits:
  cpu: 500m
  memory: 500Mi
  ephemeral_storage: 3Gi

您可以使用 resource_requirements 字段进行自定义。

container_scanning:
  resource_requirements:
    requests:
      cpu: '0.2'
      memory: 200Mi
      ephemeral_storage: 2Gi
    limits:
      cpu: '0.7'
      memory: 700Mi
      ephemeral_storage: 4Gi

当使用小数值表示 CPU 时，请将该值格式化为字符串。

资源需求只能通过 agent 配置设置。如果您通过扫描执行策略启用了运行时容器扫描并需要配置资源需求，您应该通过 agent 配置文件进行配置。
当使用 Google Kubernetes Engine (GKE) 进行 Kubernetes 编排时，临时存储限制值将始终设置为等于请求值。这是由 GKE 强制执行的。

Trivy K8s Wrapper 的自定义仓库

在扫描期间，OCS 使用来自 Trivy K8s Wrapper 仓库的镜像部署 pod，该镜像将 Trivy Kubernetes 生成的漏洞报告传输到 OCS。

如果集群的防火墙限制了访问 Trivy K8s Wrapper 仓库，您可以配置 OCS 从自定义仓库拉取镜像。确保自定义仓库镜像 Trivy K8s Wrapper 仓库以保证兼容性。

container_scanning:
  trivy_k8s_wrapper_image:
    repository: "your-custom-registry/your-image-path"

配置扫描超时

默认情况下，Trivy 扫描在五分钟后超时。agent 本身额外提供 15 分钟来读取链式 configmap 并传输漏洞。

要自定义 Trivy 超时持续时间：

使用 scanner_timeout 字段指定持续时间（以秒为单位）。

例如：

container_scanning:
  scanner_timeout: "3600s" # 60 分钟

配置 Trivy 报告大小

默认情况下，Trivy 报告限制为 100 MB，这对大多数扫描来说足够了。但是，如果您有大量工作负载，可能需要增加限制。

为此：

使用 report_max_size 字段以字节为单位指定限制。

例如：

container_scanning:
  report_max_size: "300000000" # 300 MB

配置 Trivy Kubernetes 资源检测

默认情况下，Trivy 查找以下 Kubernetes 资源类型以发现可扫描的镜像：

Pod
ReplicaSet
ReplicationController
StatefulSet
DaemonSet
CronJob
Job
Deployment

您可以限制 Trivy 发现的 Kubernetes 资源类型，例如只扫描"活动"镜像。

为此：

使用 resource_types 字段指定资源类型：

container_scanning:
  vulnerability_report:
    resource_types:
      - Deployment
      - Pod
      - Job

配置 Trivy 报告工件删除

默认情况下，GitLab agent for Kubernetes 在扫描完成后会删除 Trivy 报告工件。

您可以配置 agent 保留报告工件，以便您可以查看原始状态的报告。

为此：

将 delete_report_artifact 设置为 false：

container_scanning:
  delete_report_artifact: false

查看集群漏洞

要在 GitLab 中查看漏洞信息：

在左侧边栏，选择 Search or go to 并找到包含 agent 配置文件的项目。
选择 Operate > Kubernetes clusters。
选择 Agent 选项卡。
选择一个 agent 以查看集群漏洞。

此信息也可以在运行时漏洞下找到。

您必须至少拥有 Developer 角色。

扫描私有镜像

要扫描私有镜像，扫描器依赖于镜像拉取密钥（直接引用和来自服务账户）来拉取镜像。

已知问题

在 GitLab agent for Kubernetes 16.9 及更高版本中，运行时容器扫描：

处理高达 100 MB 的 Trivy 报告。对于之前的版本，此限制为 10 MB。
当 GitLab agent for Kubernetes 在 fips 模式下运行时被禁用。

故障排除

`Error running Trivy scan. Container terminated reason: OOMKilled`

如果扫描的资源过多或被扫描的镜像很大，OCS 可能会因 OOM 错误而失败。

要解决此问题，配置资源需求以增加可用内存。

`Pod ephemeral local storage usage exceeds the total limit of containers`

对于默认临时存储较低的 Kubernetes 集群，OCS 扫描可能会失败。例如，GKE autopilot 将默认临时存储设置为 1 GB。当扫描包含大镜像的命名空间时，这会成为 OCS 的问题，因为可能没有足够的空间来存储 OCS 所需的所有数据。

要解决此问题，配置资源需求以增加可用临时存储。

另一个表明此问题的消息可能是：OCS Scanning pod evicted due to low resources. Please configure higher resource limits.

`Error running Trivy scan due to context timeout`

如果 Trivy 完成扫描的时间过长，OCS 可能无法完成扫描。默认扫描超时为 5 分钟，agent 额外提供 15 分钟来读取结果并传输漏洞。

要解决此问题，配置扫描器超时以增加可用内存。

`trivy report size limit exceeded`

如果生成的 Trivy 报告大小超过默认最大限制，OCS 可能会失败并出现此错误。

要解决此问题，配置最大 Trivy 报告大小以增加 Trivy 报告的最大允许大小。