---
url: /zh/security/syntax-reference.md
description: code_scan_config.yml 字段级完整参考，包括顶层字段、include、扫描配置和 Beta rules 语法。
---
本章是 `code_scan_config.yml` 的字段级完整参考。首次配置建议先阅读[快速开始](./quickstart.md)。

`.scanignore`、`ignoreFrom` 引用的文件和 `paths` 均使用 **gitignore 风格的路径规则**：

* `**` 跨多级目录
* `!` 前缀表示取反（强制包含）

## `.scanignore` 与 `ignoreFrom`

* 可以只配置根目录 `.scanignore`，其规则对所有扫描能力生效。
* 某个能力配置 `ignoreFrom` 后，改用指定文件；其他能力仍使用根目录 `.scanignore`。
* 两个忽略文件不合并。`paths`、`include` 和 `rules` 可同时生效。

## 基本结构

```yaml title=".cnb/security/code_scan_config.yml"
include:
  - .cnb/security/checks/extra.yml

secrets:
  scan:
    ignoreFrom: .cnb/security/scanignore/secrets
    paths:
      - "!secret-files/keep.go"
  rules:
    - name: ignore-test-noise
      when:
        paths: ["**/testdata/**"]
        severity: ["low", "medium"]
      then:
        ignore: true
        reason: "忽略 testdata 目录下的低/中危告警"

software-composition-analysis:
  scan:
    ignoreFrom: .cnb/security/scanignore/sca
```

## 顶层字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `include` | 数组 | 子文件引入，详见[include 字段](#include-字段) |
| `secrets` | 安全能力 | 敏感信息扫描配置 |
| `software-composition-analysis` | 安全能力 | 开源组件扫描配置 |

> 上表是当前对外开放的顶层字段；无法识别的键会被当作错误，以 `validate` 的校验结果为准。

## include 字段

```yaml title=".cnb/security/code_scan_config.yml"
include:
  - <字符串路径>
  - path: <字符串路径>
    ignoreError: <true|false> # 默认 false
```

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `path` | string | ✅ | 相对仓库根目录的子文件路径 |
| `ignoreError` | bool | | 为 `true` 时缺失文件不报错；其它错误仍会报 |

更多语义（合并规则、安全限制）参见[配置文件 · include](./config-file.md)。

## 安全能力（capability）

每个能力块支持以下子键：

```yaml
<capability>:
  scan: { ... } # 扫描配置
  rules: [...] # 处理规则（Beta）
```

> 上表是当前对外开放的子键；无法识别的键会被当作错误，以 `validate` 的校验结果为准。

### scan 扫描配置

```yaml
<capability>:
  scan:
    ignoreFrom: .cnb/security/scanignore/common
    paths:
      - "!secret-files/keep.go"
      - "vendor/**"
```

| 字段 | 类型 | 说明 |
|---|---|---|
| `ignoreFrom` | string | gitignore 风格忽略文件路径（相对仓库根），仅替换当前能力的 `.scanignore` 默认来源 |
| `paths` | string\[] | 额外的 gitignore 风格路径规则。最多 **100** 项。多文件 include 时会追加去重。 |

**`ignoreFrom` 与 `paths` 的关系**：两者最终合并为一个 pattern 集合。
`paths` 中以 `!` 开头的 pattern 可对 `ignoreFrom` 取反，
强制将某些路径重新纳入扫描。

未配置 `ignoreFrom` 时，使用根目录 `.scanignore`（如果存在）。

> **提示**：一旦显式声明 `ignoreFrom`，目标文件**必须存在**，否则报错。
> 若希望“有就用、没有就跳”，改用 `include` + `ignoreError: true` 将这部分配置拆出来。

### rules（Beta）

> ⚠️ **Beta 特性**：`rules` 块及其下的 `when` / `then` 字段为 Beta，
> 字段名与匹配语义可能在后续版本调整。
> 建议在生产配置中谨慎使用，并关注更新日志。

针对单条扫描结果（finding）的处理规则。当 `when` 的所有条件都满足时，应用 `then` 指定的动作。

```yaml
<capability>:
  rules:
    - name: ignore-test-low-severity
      when:
        paths: ["**/test/**"]
        severity: ["low"]
      then:
        ignore: true
        reason: "测试代码中的低危告警，已知不会进生产"
```

#### 规则结构

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `name` | string | ✅ | 规则标识，会出现在审计日志/决策结果中 |
| `when` | 对象 | ✅ | 匹配条件 |
| `then` | 对象 | ✅ | 命中后的动作 |

#### `when` 匹配条件

`when` 内的多个字段是 **AND** 关系（同时满足才命中）。至少需要 1 个条件。

| 字段 | 类型 | 说明 |
|---|---|---|
| `paths` | string\[] | gitignore 风格路径规则数组（OR），匹配 finding 的路径。**必写数组形式**，即使只有一个模式 |
| `severity` | string\[] | 严重等级数组（OR），允许值见下方。**必写数组形式**，即使只有一个值 |

> 示例：`paths` 可配置 `["**/testdata/**", "vendor/**"]` 来忽略测试数据和 vendor 目录。
>
> 严重级别枚举值因能力而异。默认包含 `low`、`medium`、`high`；SCA 能力额外支持 `critical`。

#### `then` 动作

```yaml
then:
  ignore: true
  reason: "原因说明"
```

| 字段 | 类型 | 说明 |
|---|---|---|
| `ignore` | bool | 为 `true` 时抑制（忽略）该 finding |
| `reason` | string | 可读的原因。**当 `ignore: true` 时必填** |

#### 多条规则的求值顺序

同一能力下的多条规则按声明顺序逐一尝试匹配，**第一条命中即生效**，后续规则不再评估。

> **提示**：将更具体的规则写在前面，更宽泛的规则写在后面。

## 完整示例

```yaml title=".cnb/security/code_scan_config.yml"
include:
  - .cnb/security/checks/extra.yml
  - path: .cnb/security/checks/local.yml # 本地可选
    ignoreError: true

secrets:
  scan:
    ignoreFrom: .cnb/security/scanignore/secrets
    paths:
      - "!secret-files/keep.go"
  rules:
    - name: ignore-test-noise # Beta
      when:
        paths: ["**/testdata/**"]
        severity: ["low", "medium"]
      then:
        ignore: true
        reason: "忽略 testdata 目录下的低/中危告警"

software-composition-analysis:
  scan:
    ignoreFrom: .cnb/security/scanignore/sca
```

## 下一步

回到[快速开始](./quickstart.md)查看更多用例，或[配置文件](./config-file.md)了解 include 细节。