语法手册

1092 字约 4 分钟

本章是 code_scan_config.yml 的字段级完整参考。首次配置建议先阅读快速开始。

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

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

基本结构

.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 字段
`secrets`	安全能力	敏感信息扫描配置
`software-composition-analysis`	安全能力	开源组件扫描配置

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

include 字段

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

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

更多语义（合并规则、安全限制）参见配置文件 · include。

安全能力（capability）

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

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

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

scan 扫描配置

<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 指定的动作。

<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 的路径。必写数组形式，即使只有一个模式
`severity`	string[]	严重等级数组（OR），允许值见下方。必写数组形式，即使只有一个值

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

`then` 动作

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

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

多条规则的求值顺序

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

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

完整示例

.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

下一步

回到快速开始查看更多用例，或配置文件了解 include 细节。