配置文件

1005 字约 3 分钟

本章介绍配置文件的整体结构、文件位置，以及如何用 include 拆分管理。

文件位置

文件	位置	必需
`code_scan_config.yml`	`<repo-root>/.cnb/security/code_scan_config.yml`	否
`.scanignore`	仓库内任意路径（在配置中显式声明）	否
`include` 子文件	仓库内任意路径	否

未提供 code_scan_config.yml 时，平台使用内置默认配置，扫描照常进行。

顶层结构

.cnb/security/code_scan_config.yml
# 0~N 个子文件，按顺序合并
include:
  - <relative path>
  - path: <relative path> # 对象形式，可容忍缺失
    ignoreError: true

# 各能力块（任意子集；未声明的能力沿用平台默认）
secrets:
  # ...
software-composition-analysis:
  # ...

每个能力块的形状一致：

<capability>:
  scan: # 扫描范围
    ignoreFrom: <path>
    paths:
      - <gitignore pattern>
  rules: # 告警处理规则（Beta）
    - name: <id>
      when:
        # ...
      then:
        # ...

重要提示：顶层常用的键是 include / secrets / software-composition-analysis；无法识别的键会被当作错误，请以 validate 的校验结果为准。

include：把配置拆开维护

路径解析

所有 include 路径相对仓库根目录解析——无论它出现在 code_scan_config.yml 还是某个被 include 的子文件中：

.cnb/security/code_scan_config.yml
include:
  - .cnb/security/checks/secrets.yml

.cnb/security/checks/secrets.yml
include:
  - .cnb/security/checks/secrets-extra.yml # ✅ 仍以仓库根为基准

容忍可选的子文件

字符串形式下，子文件缺失会报错。若希望"文件存在则加载，不存在则跳过"，使用对象形式并设置 ignoreError: true：

.cnb/security/code_scan_config.yml
include:
  - { path: .cnb/security/checks/local-overrides.yml, ignoreError: true }

提示：ignoreError 只忽略文件不存在的情况；解析错误、循环引用、路径越界等仍会报错。

合并规则

code_scan_config.yml 与所有被 include 的子文件最终会合并成一份配置。不同能力之间互不干扰；同一能力下的字段按以下规则合并：

字段类型	合并行为
标量（`ignoreFrom`）	后出现的覆盖前面的
数组（`paths`、`rules`）	追加合并，顺序为低→高优先级

优先级（低 → 高）：

include[0] < include[1] < ... < include[N-1] < 本地 code_scan_config.yml

本地值覆盖 include：标量字段若本地与 include 都写了，本地值生效。
include 内部的顺序：较早 include 的优先级更低，后写的覆盖先写的。

注意数组的覆盖行为：数组字段不存在"覆盖"，所有来源的元素按低→高顺序追加。这对 gitignore 的取反规则很重要——本地写的 !pattern 必须排在 include 值之后才能生效。

示例

.cnb/security/code_scan_config.yml
# 本地配置，最高优先级
include:
  - .cnb/security/checks/secrets.yml
secrets:
  scan:
    ignoreFrom: .scanignore-local # 本地标量
    paths: ["!keep-local.go"] # 本地数组

.cnb/security/checks/secrets.yml
secrets:
  scan:
    ignoreFrom: .scanignore-included
    paths: ["vendor/**"]

合并结果：

secrets:
  scan:
    ignoreFrom: .scanignore-local # 本地赢
    paths: ["vendor/**", "!keep-local.go"] # 追加，本地在后

安全限制

include 路径必须相对且不能逃逸出仓库根目录（不允许 ../..）。
不允许绝对路径、不允许 URL、不支持跨仓库引用。
不允许符号链接——即便目标在仓库内也会报错。
单次解析最多 50 个文件（含递归）。
不允许循环 include（A → B → A 报错）。

用 validate 插件自检

validate 用来在提交前确认配置是否正确。退出码 0 表示配置合法，非 0 表示存在问题（日志中会列出每条问题及其行号）。

在 CNB 流水线里调用（推荐）

在仓库的 .cnb.yml 里加一个插件任务，PR 阶段就能拦住坏配置：

.cnb.yml
main:
  pull_request:
    - stages:
        - name: validate code scan config
          image: cnbcool/code-security-config
          args:
            - validate

args 会追加到插件镜像的入口命令之后，等价于执行 code-security-config validate。
默认读取 .cnb/security/code_scan_config.yml。
配置放在其它位置时，用 args: [validate, --config, <仓库内相对路径>] 指定。
校验失败时该任务以非 0 退出码结束，流水线随之失败，日志里能看到每条问题及行号。

在本地调用

code-security-config validate                              # 读取 .cnb/security/code_scan_config.yml
code-security-config validate --config path/to/code_scan_config.yml

下一步

语法手册 —— 字段级完整参考。