> For the complete documentation index, see [llms.txt](https://tccli-agent.gitbook.io/tccli/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tccli-agent.gitbook.io/tccli/v2/tcr-rong-qi-jing-xiang-fu-wu/signing/cve-whitelist.md).

# 漏洞扫描与阻断白名单

> 命名空间级漏洞扫描配置：自动扫描、阻断等级、CVE 白名单。在创建/修改命名空间时设置。 官方文档: [容器镜像安全扫描](https://cloud.tencent.com/document/product/1141/48185)

## 是什么

TCR 企业版命名空间支持镜像漏洞扫描。`IsAutoScan` 控制自动扫描，`IsPreventVUL`+`Severity` 控制阻断（达到等级的漏洞推送时阻断），`CVEWhitelistItems` 是白名单（命中则不阻断）。

## 触发条件

* 命名空间下镜像需安全合规（阻断高危漏洞推送）
* 某些 CVE 经评估可接受（如仅影响其他 OS），需豁免阻断

## 准备工作

### 环境检查

```bash
tccli --version
# expected: tccli 版本号

# 确认实例存在且 Running
tccli tcr DescribeInstances --region <REGION> --Registryids '["<REGISTRY_ID>"]'
# expected: Registries[0].Status = "Running"
```

> `Severity` 取值 `low`/`medium`/`high`（`CreateNamespace`/`ModifyNamespace` 可选参数；规格能力以控制台与实际 API 响应为准）。

## 操作步骤

### 创建命名空间时配置扫描与白名单

```bash
tccli tcr CreateNamespace --region <REGION> \
  --RegistryId "<REGISTRY_ID>" \
  --NamespaceName "<NAMESPACE>" \
  --IsPublic false \
  --IsAutoScan true \
  --IsPreventVUL true \
  --Severity medium \
  --CVEWhitelistItems '[{"CVEID":"CVE-2024-12345"},{"CVEID":"CVE-2024-67890"}]'
# expected: { "RequestId": "..." }
```

| 参数                  | 说明                                            |
| ------------------- | --------------------------------------------- |
| `IsAutoScan`        | `true` 自动扫描新推送镜像；`false` 手动触发                 |
| `IsPreventVUL`      | `true` 达到 `Severity` 等级的漏洞阻断推送；`false` 仅告警不阻断 |
| `Severity`          | 阻断等级：`low`（所有阻断）/`medium`/`high`（仅高危阻断）       |
| `CVEWhitelistItems` | 白名单 CVE 列表，命中则不阻断                             |

> `CVEWhitelistItems` 结构见 [共享字段](https://tccli-agent.gitbook.io/tccli/v2/tcr-rong-qi-jing-xiang-fu-wu/signing/pages/EsOWX7JWK5SJthwch0UX#cvewhitelistitem-漏洞白名单)。

### 修改已有命名空间的扫描配置

```bash
tccli tcr ModifyNamespace --region <REGION> \
  --RegistryId "<REGISTRY_ID>" \
  --NamespaceName "<NAMESPACE>" \
  --IsAutoScan true \
  --IsPreventVUL true \
  --Severity high \
  --CVEWhitelistItems '[{"CVEID":"CVE-2024-12345"}]'
# expected: { "RequestId": "..." }
```

> `ModifyNamespace` 覆盖更新 `CVEWhitelistItems`（非增量），改前先查询当前白名单。

### 验证

```bash
tccli tcr DescribeNamespaces --region <REGION> \
  --RegistryId "<REGISTRY_ID>" --NamespaceName "<NAMESPACE>" \
  --filter "NamespaceList[?Name=='<NAMESPACE>'].{name:Name,autoscan:AutoScan,prevent:PreventVUL,sev:Severity,whitelist:CVEWhitelistItems}" --output json
# expected: autoscan=true, prevent=true, sev 与最近一次 Create/Modify 的 Severity 一致，whitelist 含配置的 CVE（响应字段是 AutoScan/PreventVUL/Severity，非 IsAutoScan/IsPreventVUL）
```

## 回滚

> 误加白名单: ModifyNamespace 传空 CVEWhitelistItems 覆盖清空

***

## 故障恢复

### 推送被阻断

```bash
# 查镜像基本信息 (漏洞详情在 TCR 控制台「镜像安全」页)
tccli tcr DescribeImages --region <REGION> \
  --RegistryId "<REGISTRY_ID>" --NamespaceName "<NAMESPACE>" --RepositoryName "<REPO>"
# expected: ImageInfoList[] 含 ImageVersion/Digest/Size/UpdateTime（无 Tag/ImageId 字段）
```

> 漏洞详情（CVE 列表+严重等级）在 TCR 控制台「镜像安全」查看，TCCLI 暂无查漏洞详情的 Action。

* 评估漏洞是否可接受 → 可接受则加 `CVEWhitelistItems` 豁免
* 不可接受 → 修复镜像（升级基础镜像版本）后重新推送

### 误加白名单

```bash
# 移除某 CVE: 用不含该 CVE 的列表覆盖
tccli tcr ModifyNamespace --region <REGION> \
  --RegistryId "<REGISTRY_ID>" --NamespaceName "<NAMESPACE>" \
  --CVEWhitelistItems '[]'
# expected: { "RequestId": "..." }（白名单清空，重新阻断）
```

## 收尾确认

```bash
# Filters 仅支持标签 Name=Tags（tagKey:tagVal）；按命名空间名筛选用 --NamespaceName
tccli tcr DescribeNamespaces --region <REGION> --RegistryId "<REGISTRY_ID>" \
  --NamespaceName "<NAMESPACE>" \
  --filter "NamespaceList[?Name=='<NAMESPACE>'].{name:Name,autoscan:AutoScan,prevent:PreventVUL,sev:Severity,whitelist:length(CVEWhitelistItems)}" --output json
# expected: 扫描配置生效 + whitelist 数量与预期一致
```

## 下一步

* [镜像签名](/tccli/v2/tcr-rong-qi-jing-xiang-fu-wu/signing.md) — 防篡改（与漏洞阻断互补）
* [不可变标签](/tccli/v2/tcr-rong-qi-jing-xiang-fu-wu/index-2/immutable-tags.md) — 防覆盖
* [共享字段](/tccli/v2/tcr-rong-qi-jing-xiang-fu-wu/shared-fields.md) — CVEWhitelistItem 结构


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://tccli-agent.gitbook.io/tccli/v2/tcr-rong-qi-jing-xiang-fu-wu/signing/cve-whitelist.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.