ci-guard-mcp

ci-guard-mcp

一个本地审计引擎。提供 CLI、GitHub Action 和四个 MCP 工具。

在合并前发现有风险的 GitHub 工作流、未记录的环境变量、可能的凭据以及相互冲突的依赖配置。审计结果可确定、只读，且无需将源代码发送到服务。仅有两个运行时依赖：yaml 和 ignore。

在本地运行

需要 Node.js 20 或更高版本。索引扫描和已跟踪文件选择需要 Git。

# Run directly with npx:
npx ci-guard-mcp scan . --fail-on warn
npx ci-guard-mcp scan . --sandbox
npx ci-guard-mcp scan . --no-git
npx ci-guard-mcp scan . --format json
npx ci-guard-mcp scan . --format sarif > findings.sarif
npx ci-guard-mcp scan . --auditor workflows --auditor lockfile
npx ci-guard-mcp scan . --auditor secrets --staged
npx ci-guard-mcp scan . --auditor secrets --include-ignored

# Or from a local source checkout:
npm ci --ignore-scripts
npm run build
node dist/cli.js scan .

退出代码：0 表示低于阈值，1 表示发现项达到或超过阈值，2 表示参数无效、配置错误或 I/O 故障。默认值为 --fail-on error；warn 也会在出现警告时失败。信息类发现项不会导致扫描失败。输出格式为 text、json、sarif 和 github。--root PATH 等同于位置参数中的扫描目录。--include-ignored 会审计已跟踪文件，即使它们符合 .gitignore 规则（例如，在添加 .gitignore 之前提交的 .env）。--help 会列出所有标志。

暂存模式仅用于检测密钥：它会读取整个已更改的索引 blob，包括重命名或新增的文件，因此未暂存的编辑无法掩盖已暂存的凭据。该模式会应用索引中的忽略规则，并跳过删除项、符号链接和子模块。其他审计需要整个仓库的上下文，因此不能与 --staged 一起使用。

GitHub Action

本仓库发布后，请使用经过审查的完整提交 SHA 替换 FULL_COMMIT_SHA：

name: Repository audit
on: [push, pull_request]
permissions:
  contents: read
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      - uses: carelessdept/ci-guard-mcp@FULL_COMMIT_SHA
        id: guard
        with:
          path: .
          fail-on: warn

输入：path（默认值为 .）、fail-on（error 或 warn，默认值为 error）。输出：errors、warnings、findings，均为十进制计数。在评估发现项阈值之前，系统会写入输出和 Markdown 作业摘要。发现项会转换为经过转义的工作流注释；审计失败时，Action 会以状态码 1 退出。运行故障以状态码 2 退出，且不会声称计数完整。

此组合式 Action 会将锁定的构建依赖安装到运行器临时目录，并禁用生命周期脚本，然后运行已编译的 CLI。它需要访问 npm registry、Bash，以及与 actions/setup-node@v4 兼容的运行器。不会安装或执行被扫描仓库的依赖和脚本。自审计工作流会运行本地 Action 并验证其输出。上传到代码扫描服务时，请单独使用 --format sarif 运行 CLI；Action 本身不会上传报告，也不会请求写入权限。

MCP 服务

stdio 服务使用以换行符分隔的 JSON-RPC 2.0，协商 MCP 版本 2025-11-25、2025-06-18、2025-03-26 和 2024-11-05，并实现初始化、ping、工具发现、工具调用和静默通知。客户端必须在初始化后发送 notifications/initialized。无需网络传输或凭据。

发布到 npm 后的 MCP 客户端配置示例：

{
  "mcpServers": {
    "ci-guard": {
      "command": "npx",
      "args": ["--yes", "ci-guard-mcp", "--mcp", "--root", "/absolute/path/to/repository"]
    }
  }
}

对于源码检出，请使用 "command": "node" 和 "args": ["/absolute/path/to/ci-guard-mcp/dist/cli.js", "--mcp", "--root", "/absolute/path/to/repository"]。

工具	行为	参数
scan_repo	全部四项审计	path?: string、includeIgnored?: boolean
check_env_drift	环境和部署漂移	path?: string
audit_github_workflows	工作流安全	path?: string
check_secret_leaks	脱敏凭据发现结果	path?: string、staged?: boolean、includeIgnored?: boolean

路径会在启动根目录内解析；拒绝遍历到父目录，以及指向根目录之外的符号链接。响应包含文本 JSON，以及内容相同的 structuredContent 报告。无效的工具参数会导致 JSON-RPC 错误；执行失败时使用 isError: true。标准输出仅包含协议消息。超过 1 MiB 的帧会被拒绝，服务会从下一处换行符开始恢复。请求会串行处理，以确保内存使用和顺序可预测；扫描完成后才会处理下一个排队请求，因此取消通知不会中断正在进行的审计。

审计规则

规则	严重性	检测内容
workflow/pwn-request	错误	使用事件派生的 PR 头部 ref／仓库进行 pull_request_target／GitLab MR 检出
workflow/script-injection	错误	在 run／script 中直接插入 GitHub 事件／头部 ref 或 GitLab MR／提交表达式
workflow/secret-exfiltration	错误	在 run 脚本中直接插入 ${{ secrets.* }} 或 ${{ toJSON(secrets) }}
workflow/unpinned-action	警告	远程操作、可复用工作流或 GitLab include／component／image 未使用不可变 SHA／sha256 摘要
workflow/missing-permissions	警告	缺少顶层 permissions
workflow/invalid-yaml	错误	工作流 YAML 格式错误、键重复或文档不是映射
env/undocumented	警告	.env.example／.env.template 中未列出的字面量源代码引用
env/dead-template	信息	未检测到源代码或部署用途的模板声明
env/invalid-compose	错误	Compose YAML 格式错误
secret/aws、secret/github、secret/stripe、secret/openai、secret/anthropic、secret/slack、secret/private-key	错误	可识别的凭据格式／私钥标头
secret/high-entropy	错误	凭据类名称对应的高熵带引号赋值
lockfile/conflict	错误	同一目录中存在多个可识别的包管理器锁文件
lockfile/insecure-http	错误	文本锁文件中的 HTTP URL
lockfile/unbounded-version	警告	依赖部分中的 *、latest 及指向它们的 npm 别名
lockfile/invalid-package	错误	无效的 JSON 包清单
scan/skipped-file	警告	超出配置大小限制的文件

环境变量模式支持 process.env.X、方括号语法、import.meta.env.X、Python os.environ[...]／.get(...)／os.getenv(...)、Go os.Getenv(...) 以及 Rust std::env::var(...)／env::var(...)。模板和声明会在整个扫描根目录中汇总。Docker ENV 和 Compose environment 条目会被视为使用方；如果源代码引用了仅用于部署的变量，仍须为其编写文档。提取源代码引用时会排除测试／夹具文件。

密钥检测使用已知前缀和上下文熵（至少 24 个字符，Shannon 熵 ≥4.3 位／字符）。发现结果、SARIF 或 MCP 结果中绝不会包含值和源代码片段。在 Git 根目录中，常规密钥审计会读取已跟踪的工作区文件；未跟踪文件会被跳过。没有 Git 时，则会扫描所有符合条件的文件。其他审计器会包含未跟踪文件。默认遵循 .gitignore 和嵌套忽略规则（传入 --include-ignored 或 includeIgnored: true，可强制扫描与 .gitignore 匹配的已跟踪文件），同时也会排除内置的依赖／构建目录。符号链接和包含 NUL 字符的二进制文件会被跳过。

配置

使用 .ciguardrc.json 或 package.json 中的 ciguard 对象。rc 文件优先级更高。遇到未知键和无效类型时会明确报错。数组会替换默认值，而非与默认值合并。ignore 和 secretIgnore 中的模式使用相对于扫描根目录的 gitignore 语法。

{
  "ignore": ["generated/"],
  "allowActions": ["actions/*"],
  "ignoreEnv": ["NODE_ENV", "CI", "PATH", "HOME"],
  "secretIgnore": ["test/", "tests/", "__tests__/", "fixtures/", "__fixtures__/", "*.test.*", "*.spec.*", ".env.example", ".env.template"],
  "disabledRules": [],
  "maxFileBytes": 1048576
}

默认情况下，allowActions 为空：官方操作也必须使用不可变固定版本。显式设置 actions/* 可允许使用可变的官方引用，也可列出精确标识，例如 actions/checkout。maxFileBytes 接受 1 KiB–16 MiB；超大文本文件会产生警告，且无法通过 disabledRules 禁用。本仓库自身的配置会排除 docs/，因为首页包含说明性示例，并将 GitHub 的两个运行时输出变量加入 ignoreEnv。

SDK

import { scan, formatSarif } from 'ci-guard-mcp';
const report = await scan({ root: '/path/to/repo', auditors: ['workflows', 'secrets'] });
console.log(report.summary);
const sarif = formatSarif(report);

命名的审计器函数接受 { files: [{ path, content }], config }，用于内存集成。SDK 的 config 会覆盖文件配置。报告包含版本、发现项、计数和扫描的文件；不包含时间戳或绝对根路径，因此可以稳定地进行快照比较。filesScanned 统计收集到的符合条件的文本文件，包括与所选审计器无关的文件。

边界和限制

这是基于静态启发式规则的审计器，并非安全性证明，也不检查凭据是否有效。它不会执行代码、解析计算得出的环境变量名称、跨文件跟踪调用、检查 Git 历史、解密文件、审计远程可复用工作流的正文，也不会分析依赖项漏洞。YAML 工作流检查会检查本地结构化步骤和作业级可复用工作流引用。经由中间表达式或文件传递的事件派生值可能绕过直接插值检查。字面环境变量模式可能匹配注释示例或字符串。无效模板提示仅供参考，因为无法获知外部使用者和动态读取。

默认的密钥排除规则有意减少测试和模板中的误报；将 secretIgnore 替换为 [] 可扩大覆盖范围。看起来真实的合成令牌仍可能被报告，而未知、熵较低或经过编码的凭据可能被漏掉。常规扫描中，受 Git 跟踪但被 .gitignore 忽略的文件不会纳入扫描，除非传入 --include-ignored（includeIgnored: true）。二进制锁文件会作为二进制内容跳过。不会推断特定软件包的环境作用域；如需检查独立的漂移情况，请单独扫描软件包目录。仓库配置被视为可信的本地策略，因此请在拉取请求中审查配置和忽略规则的变更。请勿将 MCP 启动根目录用作抵御并发恶意本地进程的操作系统级沙箱。

开发和发布

npm ci --ignore-scripts
npm run check
node dist/cli.js scan --fail-on warn
npm pack --dry-run

CI 会在 Linux、macOS 和 Windows 上，使用 Node 20 和 22 运行测试、类型检查、构建和软件包检查。回归测试请参阅 CONTRIBUTING.md，披露事宜请参阅 SECURITY.md。

采用 MIT 许可。通过可复现的报告、聚焦的变更和有记录的限制，保持开放维护。

协议参考：MCP stdio、SARIF 2.1.0。