[!IMPORTANT] KubeClarity 已被弃用，由 openclarity/openclarity 接替。

查看发布声明了解更多信息。

此项目不再接收更新。我们建议您迁移。

KubeClarity 是一个用于检测和管理容器镜像和文件系统的软件物料清单 (SBOM) 及漏洞的工具。它扫描运行时 K8s 集群和 CI/CD 管道，以增强软件供应链安全性。

目录

• 为何？
  • SBOM 和漏洞检测挑战
  • 解决方案
• 功能
  • 集成的 SBOM 生成器和漏洞扫描器
• 架构
• 开始使用
  • KubeClarity 后端
    • 使用 Helm 安装
    • 使用 Helm 卸载
    • 在本地构建并运行（含演示数据）
  • CLI
    • 安装
    • SBOM 生成
    • 漏洞扫描
    • 导出结果至 KubeClarity 后端
• 高级配置
  • 使用本地 docker 镜像作为输入生成 SBOM
  • 使用本地 docker 镜像作为输入进行漏洞扫描
  • CLI 的私有仓库支持
  • K8s 运行时扫描的私有仓库支持
  • 跨不同 CI/CD 阶段合并 SBOM 和漏洞
  • 输出不同的 SBOM 格式
  • CLI 的远程扫描器服务器
• 限制
• 路线图
• 贡献
• 许可证

为何？

SBOM 和漏洞检测挑战

• 有效的漏洞扫描需要准确的软件物料清单 (SBOM) 检测：
  • 多种编程语言和包管理器
  • 多种操作系统发行版
  • 包依赖信息通常在构建时被剥离
• 哪个是最好的扫描器/SBOM 分析器？
• 我们应该扫描什么：Git 仓库、构建产物、容器镜像还是运行时？
• 每个扫描器/分析器都有自己的格式——如何比较结果？
• 如何管理已发现的 SBOM 和漏洞？
• 我的应用如何受到新发现漏洞的影响？

解决方案

• 将漏洞扫描分为两个阶段：
  • 内容分析以生成 SBOM
  • 扫描 SBOM 以发现漏洞
• 创建一个可插拔的基础设施以：
  • 并行运行多个内容分析器
  • 并行运行多个漏洞扫描器
• 使用 KubeClarity CLI 扫描并合并不同 CI 阶段之间的结果
• 运行时 K8s 扫描以检测部署后发现的漏洞
• 将扫描的资源（镜像/目录）分组到定义的应用下，以便导航对象树依赖关系（应用、资源、包、漏洞）

功能

• 仪表盘
  • 按严重程度划分的可修复漏洞
  • 前5个易受攻击的元素（应用、资源、包）
  • 新漏洞趋势
  • 按许可证类型统计的包数量
  • 按编程语言统计的包数量
  • 通用计数器
• 应用
  • 在 K8s 运行时中自动检测应用
  • 创建/编辑/删除应用
  • 对于每个应用，导航到相关的：
    • 资源（镜像/目录）
    • 包
    • 漏洞
    • 资源使用的许可证
• 应用资源（镜像/目录）
  • 对于每个资源，导航到相关的：
    • 应用
    • 包
    • 漏洞
• 包
  • 对于每个包，导航到相关的：
    • 应用
    • 可链接的资源列表及检测到的 SBOM 分析器
    • 漏洞
• 漏洞
  • 对于每个漏洞，导航到相关的：
    • 应用
    • 资源
    • 检测扫描器列表
• K8s 运行时扫描
  • 按需或定时扫描
  • 自动检测目标命名空间
  • 按受影响元素（应用、资源、包、漏洞）的扫描进度和结果导航
  • CIS Docker 基准测试
• CLI（CI/CD）
  • 使用多个集成的分析器（Syft、cyclonedx-gomod）生成 SBOM
  • 使用多个集成的扫描器（Grype、Dependency-track）对 SBOM/镜像/目录进行漏洞扫描
  • 跨不同 CI/CD 阶段合并 SBOM 和漏洞
  • 将结果导出到 KubeClarity 后端
• API
  • KubeClarity 的 API 可在此处找到

集成的 SBOM 生成器和漏洞扫描器

KubeClarity 内容分析器集成了以下 SBOM 生成器：

• Syft
• Cyclonedx-gomod
• Trivy

KubeClarity 漏洞扫描器集成了以下扫描器：

• Grype
• Dependency-Track
• Trivy

架构

开始使用

KubeClarity 后端

使用 Helm 安装：

1. 添加 Helm 仓库 ```shell helm repo add kubeclarity https://openclarity.github.io/kubeclarity

   root@kitploit:~

2. 保存 KubeClarity 默认 chart 值

   root@kitploit:~

   helm show values kubeclarity/kubeclarity > values.yaml
   

3. 检查 values.yaml 中的配置，并根据需要更新所需的值。 要启用和配置支持的 SBOM 生成器和漏洞扫描器，请检查 Helm values 中 "vulnerability-scanner" 部分下的 "analyzer" 和 "scanner" 配置。

4. 使用 Helm 部署 KubeClarity ```shell helm install --values values.yaml --create-namespace kubeclarity kubeclarity/kubeclarity -n kubeclarity

   root@kitploit:~

或用于兼容 OpenShift Restricted SCC 的安装： ```shell helm install --values values.yaml --create-namespace kubeclarity kubeclarity/kubeclarity -n kubeclarity --set global.openShiftRestricted=true
--set kubeclarity-postgresql.securityContext.enabled=false --set kubeclarity-postgresql.containerSecurityContext.enabled=false
--set kubeclarity-postgresql.volumePermissions.enabled=true --set kubeclarity-postgresql.volumePermissions.securityContext.runAsUser="auto"
--set kubeclarity-postgresql.shmVolume.chmod.enabled=false

3. 将端口转发到KubeClarity UI:   ```shell
kubectl port-forward -n kubeclarity svc/kubeclarity-kubeclarity 9999:8080

4. 在浏览器中打开 KubeClarity UI：http://localhost:9999/

注意
KubeClarity 需要以下 K8s 权限：

权限	原因
读取 CREDS_SECRET_NAMESPACE（默认：kubeclarity）中的 secret

使用 Helm 卸载：

1. Helm 卸载 ```shell helm uninstall kubeclarity -n kubeclarity

   root@kitploit:~

2. 清理资源

   默认情况下，Helm 不会删除 StatefulSets 的 PVC 和 PV。运行以下命令可以全部删除：

   root@kitploit:~

   kubectl delete pvc -l app.kubernetes.io/instance=kubeclarity -n kubeclarity
   

使用演示数据在本地构建和运行

1. 构建 UI 和 后端，并在本地启动后端（两种方式）：

   1. 使用 Docker：
      1. 构建 UI 和 后端（镜像标签通过 VERSION 设置）：
         root@kitploit:~

         VERSION=test make docker-backend
         

      2. 使用演示数据运行后端：
         root@kitploit:~

         docker run -p 8080:8080 -e FAKE_RUNTIME_SCANNER=true -e FAKE_DATA=true -e ENABLE_DB_INFO_LOGS=true -e DATABASE_DRIVER=LOCAL ghcr.io/openclarity/kubeclarity:test run
         

   2. 本地构建：
      1. 构建 UI 和 后端
         root@kitploit:~

         make ui && make backend
         

      2. 复制构建好的站点：
         root@kitploit:~

         cp -r ./ui/build ./site
         

      3. 使用演示数据在本地运行后端：
         root@kitploit:~

         FAKE_RUNTIME_SCANNER=true DATABASE_DRIVER=LOCAL FAKE_DATA=true ENABLE_DB_INFO_LOGS=true ./backend/bin/backend run
         

2. 在浏览器中打开 KubeClarity UI：http://localhost:8080/

CLI

KubeClarity 包含一个 CLI 工具，可以在本地运行，特别适用于 CI/CD 流水线。它允许分析镜像和目录以生成 SBOM，并扫描其中的漏洞。结果可以导出到 KubeClarity 后端。

Installation

SBOM 生成

用法：``` kubeclarity-cli analyze <image/directory name> --input-type <dir|file|image(default)> -o

示例：```
kubeclarity-cli analyze --input-type image nginx:latest -o nginx.sbom

Optionally a list of the content analyzers to use can be configured using the ANALYZER_LIST env variable seperated by a space (e.g ANALYZER_LIST="<analyzer 1 name> <analyzer 2 name>")

Example:``` ANALYZER_LIST="syft gomod" kubeclarity-cli analyze --input-type image nginx:latest -o nginx.sbom

### 漏洞扫描

用法：```
kubeclarity-cli scan <image/sbom/directoty/file name> --input-type <sbom|dir|file|image(default)> -f <output file>

示例：``` kubeclarity-cli scan nginx.sbom --input-type sbom

可选地，可以通过 `SCANNERS_LIST` 环境变量配置要使用的漏洞扫描器列表，用空格分隔（例如 `SCANNERS_LIST="<Scanner1 name> <Scanner2 name>"`）

示例：```
SCANNERS_LIST="grype trivy" kubeclarity-cli scan nginx.sbom --input-type sbom

导出结果到 KubeClarity 后端

要将 CLI 结果导出到 KubeClarity 后端，需要使用由 KubeClarity 后端定义的应用程序 ID。 应用程序 ID 可以在 UI 的应用程序屏幕中找到，或通过 KubeClarity API 获取。

导出 SBOM```

The SBOM can be exported to KubeClarity backend by setting the BACKEND_HOST env variable and the -e flag.

Note: Until TLS is supported, BACKEND_DISABLE_TLS=true should be set.

BACKEND_HOST= BACKEND_DISABLE_TLS=true kubeclarity-cli analyze --application-id -e -o

For example:

BACKEND_HOST=localhost:9999 BACKEND_DISABLE_TLS=true kubeclarity-cli analyze nginx:latest --application-id 23452f9c-6e31-5845-bf53-6566b81a2906 -e -o nginx.sbom

#### 导出漏洞扫描结果```
# The vulnerability scan result can be exported to KubeClarity backend by setting the BACKEND_HOST env variable and the -e flag.
# Note: Until TLS is supported, BACKEND_DISABLE_TLS=true should be set.

BACKEND_HOST=<KubeClarity backend address> BACKEND_DISABLE_TLS=true kubeclarity-cli scan <image> --application-id <application ID> -e

# For example:
SCANNERS_LIST="grype" BACKEND_HOST=localhost:9999 BACKEND_DISABLE_TLS=true kubeclarity-cli scan nginx.sbom --input-type sbom  --application-id 23452f9c-6e31-5845-bf53-6566b81a2906 -e

高级配置

使用本地 Docker 镜像作为输入的 SBOM 生成```

Local docker images can be analyzed using the LOCAL_IMAGE_SCAN env variable

For example:

LOCAL_IMAGE_SCAN=true kubeclarity-cli analyze nginx:latest -o nginx.sbom

## 使用本地Docker镜像作为输入进行漏洞扫描```
# Local docker images can be scanned using the LOCAL_IMAGE_SCAN env variable

# For example:
LOCAL_IMAGE_SCAN=true kubeclarity-cli scan nginx.sbom

Private registry support For CLI

KubeClarity cli可以读取一个存储私有仓库凭据的配置文件。

示例配置文件中的仓库部分：``` registry: auths: - authority: <registry 1> username: <username for registry 1> password: <password for registry 1> - authority: <registry 2> token: <token for registry 2>

无权威的注册表配置示例：（在这种情况下，这些凭据将用于所有注册表）```
registry:
  auths:
    - username: <username>
      password: <password>

指定CLI配置文件```

The default config path is $HOME/.kubeclarity or it can be specified by --config command line flag.

kubeclarity <scan/analyze> --config

For example:

kubeclarity scan registry/nginx:private --config $HOME/own-kubeclarity-config

## Private registries support for K8s runtime scan

Kubeclarity 使用 google/go-containerregistry 的 [k8schain](https://github.com/google/go-containerregistry/tree/main/pkg/authn/k8schain#k8schain) 进行注册表身份验证。
如果 k8schain 无法发现必要的服务凭据，则可以通过下面描述的密钥来定义它们。

此外，如果服务凭据不在 "kubeclarity" 命名空间中，请将 CREDS_SECRET_NAMESPACE 设置为 kubeclarity 部署。
使用 helm [charts](https://github.com/openclarity/kubeclarity/blob/HEAD/charts) 时，CREDS_SECRET_NAMESPACE 会被设置为安装 kubeclarity 的发布命名空间。

### Amazon ECR

创建一个具有 `AmazonEC2ContainerRegistryFullAccess` 权限的 [AWS IAM 用户](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console)。

使用用户凭据（`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、`AWS_DEFAULT_REGION`）创建以下密钥：```
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: ecr-sa
  namespace: kubeclarity
type: Opaque
data:
  AWS_ACCESS_KEY_ID: $(echo -n 'XXXX'| base64 -w0)
  AWS_SECRET_ACCESS_KEY: $(echo -n 'XXXX'| base64 -w0)
  AWS_DEFAULT_REGION: $(echo -n 'XXXX'| base64 -w0)
EOF

注意：

1. Secret 名称必须为 ecr-sa
2. Secret 数据键必须设置为 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 和 AWS_DEFAULT_REGION

Google GCR

使用 Artifact Registry Reader 权限创建一个 Google 服务账号。

使用服务账号 json 文件创建以下 secret``` kubectl -n kubeclarity create secret generic --from-file=sa.json gcr-sa

注意：
1. 密钥名称必须为 `gcr-sa`
1. `sa.json` 必须是生成密钥时服务账户 JSON 文件的名称
2. KubeClarity 使用[应用默认凭据](https://developers.google.com/identity/protocols/application-default-credentials)。这些凭据仅在 GCP 中运行 KubeClarity 时有效。

## 跨 CI/CD 阶段的 SBOM 与漏洞合并```
# Additional SBOM will be merged into the final results when '--merge-sbom' is defined during analysis. The input SBOM can be CycloneDX XML or CyclonDX json format.
# For example:
ANALYZER_LIST="syft" kubeclarity-cli analyze nginx:latest -o nginx.sbom --merge-sbom inputsbom.xml

输出不同的SBOM格式

kubeclarity-cli analyze 命令可以根据需要将生成的SBOM格式化为不同格式，以便与另一个系统集成。支持的格式如下：

警告
KubeClarity 在内部处理 CycloneDX 格式，其他格式通过转换得到支持。由于格式之间的不兼容性，转换过程可能造成信息丢失，因此不保证结果输出中包含所有字段/信息。

要将 kubeclarity-cli 配置为使用除默认格式以外的格式，可以使用 ANALYZER_OUTPUT_FORMAT 环境变量，并传入上表中的配置名称：``` ANALYZER_OUTPUT_FORMAT="spdx-json" kubeclarity-cli analyze nginx:latest -o nginx.sbom

## 用于 CLI 的远程扫描器服务器

在运行 kubeclarity CLI 扫描漏洞时，CLI 需要将相关的漏洞数据库下载到 kubeclarity CLI 运行的位置。在 CI/CD 流水线中运行 CLI 会导致每次运行时都下载数据库，浪费时间和带宽。因此，部分支持的扫描器提供了远程模式，由服务器负责数据库管理，并可能负责对工件进行扫描。

> ***注意***
>
> 以下示例针对每个扫描器，但它们可以像非远程模式一样组合在一起运行。

### Trivy

Trivy 扫描器支持使用 Trivy 服务器进行远程模式。Trivy 服务器可以按照此处文档进行部署：[trivy 客户端-服务器模式](https://aquasecurity.github.io/trivy/v0.34/docs/references/modes/client-server/)。安装 Trivy CLI 的说明可在 [trivy 安装](https://aquasecurity.github.io/trivy/v0.34/getting-started/installation/) 中找到。Aqua 团队提供了一个官方容器镜像，可用于在 kubernetes/docker 中运行服务器，我们将在示例中使用该镜像。

要启动服务器：```
docker run -p 8080:8080 --rm aquasec/trivy:0.41.0 server --listen 0.0.0.0:8080

要使用服务器运行扫描：``` SCANNERS_LIST="trivy" SCANNER_TRIVY_SERVER_ADDRESS="http://:8080" ./kubeclarity_cli scan --input-type sbom nginx.sbom

Trivy 服务器还提供基于令牌的身份验证，以防止未经授权使用 Trivy 服务器实例。您可以通过运行带有额外标志的服务器来启用它：```
docker run -p 8080:8080 --rm aquasec/trivy:0.41.0 server --listen 0.0.0.0:8080 --token mytoken

并将令牌传递给扫描器：``` SCANNERS_LIST="trivy" SCANNER_TRIVY_SERVER_ADDRESS="http://:8080" SCANNER_TRIVY_SERVER_TOKEN="mytoken" ./kubeclarity_cli scan --input-type sbom nginx.sbom

### Grype

Grype 支持远程模式，通过使用 [grype-server](https://github.com/portshift/grype-server)，这是一个 RESTful 的 grype 封装，提供了一个接收 SBOM 并返回该 SBOM 的 grype 扫描结果的 API。Grype-server 以容器镜像形式发布，因此可以在 kubernetes 中运行，或通过 docker 独立运行。

要启动服务器：```
docker run -p 9991:9991 --rm gcr.io/eticloud/k8sec/grype-server:v0.1.5

使用服务器运行扫描：``` SCANNERS_LIST="grype" SCANNER_GRYPE_MODE="remote" SCANNER_REMOTE_GRYPE_SERVER_ADDRESS=":9991" SCANNER_REMOTE_GRYPE_SERVER_SCHEMES="https" ./kubeclarity_cli scan --input-type sbom nginx.sbom

如果 Grype 服务器使用 TLS 部署，您可以覆盖默认的 URL 方案，例如：```
SCANNERS_LIST="grype" SCANNER_GRYPE_MODE="remote" SCANNER_REMOTE_GRYPE_SERVER_ADDRESS="<grype server address>:9991" SCANNER_REMOTE_GRYPE_SERVER_SCHEMES="https" ./kubeclarity_cli scan --input-type sbom nginx.sbom

Dependency Track

参见示例配置 此处

限制

1. 支持 Docker 镜像清单 V2，Schema 2（https://docs.docker.com/registry/spec/manifest-v2-2/）。扫描早期版本会失败。

路线图

• 集成更多内容分析器（SBOM 生成器）
• 集成更多漏洞扫描器
• UI 中实现 CIS Docker 基准检查
• 使用 Cosign 进行镜像签名
• 使用 Cosign 和 in-toto 进行 CI/CD 元数据签名和认证（供应链安全）
• 系统设置与用户管理

贡献

欢迎提交 Pull Request 和错误报告。

对于较大的更改，请先在 GitHub 上创建一个 Issue 来讨论您的 提议变更及可能的影响。

更多细节请参阅本项目贡献指南

许可证

Apache 许可证，版本 2.0