CI/CD 扫描任务驱动（CI Scan Driver）

May 7, 2026 · View on GitHub

目的

用于在 CI/CD 中以“独立入口”驱动 KunLun-M 扫描，并生成稳定的 JSON 报告文件，同时按阈值返回明确的退出码以实现门禁。

该入口不会改变现有 python kunlun.py scan ... 的默认行为。

仓库内必须存在至少一条规则文件：rules/**/CVI_*.py
若只有 rules/*.template 而没有任何 CVI_*.py，CI 驱动会直接失败并写出 error JSON（避免“看似通过但实际没有跑规则”的假阴性）
规则与 tamper 的机制与目录结构见 rules.md 与 tamper.md

安装依赖：

python -m pip install -r requirements.txt

建议 Python 版本：3.11+（以 requirements.txt 与 GitHub Actions 示例为准）。

运行扫描（生成报告文件，按阈值失败）：

python tools/ci_scan.py --target . --output artifacts/kunlun-ci.json --fail-on high

--target：扫描目标路径（默认 .）
--output：报告输出路径（默认 artifacts/kunlun-ci.json）
--fail-on：失败阈值：none|low|medium|high|critical（默认读取环境变量 KUNLUN_FAIL_ON，否则 none）
--include-unconfirm：是否包含未确认漏洞（默认读取 KUNLUN_INCLUDE_UNCONFIRM）
--with-vendor / --without-vendor：是否启用 SCA（依赖漏洞）扫描（默认读取 KUNLUN_WITH_VENDOR，默认关闭）
--rule：指定规则 ID（逗号分隔），例如 1000,1001
--language：指定语言（逗号分隔）
--blackpath：黑名单路径（逗号分隔）
--tamper：拓展插件（tamper）名称
--unprecom：关闭预编译（更快但能力下降）
--settings-module：CI 专用 settings（默认 Kunlun_M.settings_ci）

输出文件为稳定 JSON，结构如下：

meta
- target：扫描目标
- task_id / project_id：内部任务与项目 ID（CI settings 下使用隔离的 SQLite）
- started_at / finished_at
- fail_on / include_unconfirm / with_vendor / settings_module
summary
- total：漏洞条数
- by_severity：按 critical/high/medium/low 统计
- max_severity：none|low|medium|high|critical
vulnerabilities[]
- cvi_id / rule_name / severity / language
- file：命中位置（通常为 path:line）
- result_type / source_code / is_unconfirm
exit
- code：0|1|2
- reason：ok|threshold_reached|exception

运行后直接失败，JSON 里提示 no rules found under rules/**/CVI_*.py？
- 说明当前工作区没有任何规则文件（只有模板或规则未被分发）。需要补齐 rules/<language>/CVI_<id>.py 后再跑扫描。
扫描目标不存在但 CI 没有失败？
- 使用 tools/ci_scan.py 会在 target 不存在时返回 1 并写出 error JSON；请确保 CI job 的执行命令是 python tools/ci_scan.py ... 而不是只调用 kunlun.py scan ...
需要提前执行 python kunlun.py config load 吗？
- 不需要。CI 驱动会直接从 rules/**/CVI_*.py 加载规则元信息用于报告展示，并使用 settings_ci.py 的 SQLite 自动迁移初始化
扫描后仓库里出现了新的空目录（例如 rules/text/）？
- 如果目标目录里包含大量非代码文件（txt、md 等），语言识别可能会带出对应“语言目录名”，而引擎会尝试为缺失的规则语言目录创建占位目录。CI 中建议显式指定扫描语言（例如 --language php,javascript），并配合 --blackpath vendor,node_modules 降低噪声与副作用。