---
url: /zh/security/sca-vulnerability.md
description: |
  开源组件漏洞扫描插件（cnbcool/sca-vulnerability）用法， 包括参数说明、质量门禁、日志输出、PR 增量规则和退出码。
---
开源组件漏洞扫描插件比较 Pull Request 的依赖变更，只报告本次新增的漏洞（CVE），
并支持按严重等级设置质量门禁。

## 功能特性

* **增量漏洞扫描**：只检查当前 PR 新增的漏洞；
* **漏洞门禁**：支持按 `low`、`medium`、`high`、`critical` 阻断；
* **修复建议**：输出组件版本、CVE、修复版本和升级建议。

## 插件镜像

```text
cnbcool/sca-vulnerability:latest
```

## 参数说明

插件参数通过 `settings` 传递：

| 参数 | 说明 | 默认 |
|---|---|---|
| `failOnSeverity` | 触发门禁的最低漏洞等级，可选 `low`、`medium`、`high`、`critical`；未配置时仅输出扫描结果，不启用门禁 | 无 |

## 在 CNB 中使用

```yaml title=".cnb.yml"
main:
  pull_request:
    - stages:
        - name: 开源组件漏洞扫描
          image: cnbcool/sca-vulnerability:latest
          settings:
            failOnSeverity: high
```

以上配置会在 PR 新增 High 或 Critical 漏洞时使检查失败；Low 和 Medium 漏洞仍会输出到日志。

### 只扫描不阻断

省略 `failOnSeverity`，即可输出新增漏洞而不启用严重等级门禁：

```yaml title=".cnb.yml"
main:
  pull_request:
    - stages:
        - name: 开源组件漏洞扫描
          image: cnbcool/sca-vulnerability:latest
```

## 输出说明

插件将新增漏洞直接输出到 CI 日志：

```text
go.mod: HIGH CVE-2025-10002
  component: github.com/example/library@v1.2.0
  fixed-version: v1.3.0
  message: example vulnerability
  action: upgrade github.com/example/library to v1.3.0 or later

SCA gate failed: 1 new risk findings, 1 matched gate
```

## 增量规则

* 已存在的同一组件、同一 CVE 不会重复阻断；
* 新增组件或新的 CVE 会形成新增漏洞；
* 删除文件不会产生新增漏洞；
* 内容未变化的文件重命名不会重复产生漏洞。

## 退出码

| 退出码 | 说明 |
|---:|---|
| `0` | 扫描完成，且新增漏洞未命中门禁 |
| `1` | 新增漏洞命中门禁 |
| `2` | 配置错误或扫描失败 |

## 下一步

* [插件总览](./sca-plugins.md) —— 三个插件的整体配置与门禁说明
* [License 扫描](./sca-license.md) —— License 风险门禁
* [SBOM 生成（Delta）](./sca-sbom.md) —— 组件变化清单