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

所有路径默认采用 **gitignore 风格的 glob 语法**：

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

## 基本结构

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

secrets:
  scan:
    ignoreFrom: .scanignore
    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: .scanignore
```

## 顶层字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `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: .scanignore
    paths:
      - "!secret-files/keep.go"
      - "vendor/**"
```

| 字段 | 类型 | 说明 |
|---|---|---|
| `ignoreFrom` | string | gitignore 风格忽略文件的路径（相对仓库根）。引擎会跳过其中匹配的路径。 |
| `paths` | string\[] | 额外的 gitignore pattern 列表。最多 **100** 项。多文件 include 时会追加去重。 |

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

**默认行为**：未显式配置 `scan`、`ignoreFrom` 或 `paths` 时，对应能力使用平台内置默认扫描范围。需要自定义忽略文件时，再显式配置 `ignoreFrom`。

> **提示**：一旦显式声明 `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 风格 glob 数组（OR），匹配 finding 的路径。例如 `["**/testdata/**", "vendor/**"]`。**必写数组形式**，即使只有一个模式 |
| `severity` | string\[] | 严重等级数组（OR），允许值见下方。**必写数组形式**，即使只有一个值 |

> 严重级别枚举值因能力而异。默认包含 `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: .scanignore
    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: .scanignore
```

## 下一步

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