一个仓库可能在你打开文件夹的瞬间就让你的编码代理运行代码。GuardSkill 会在你打开之前检查这一点。
npx guardskill .
只读。无网络调用、无遥测、无配置、无账户、无依赖。它读取 git 配置和钩子脚本,打印所发现的内容,然后退出。
编码代理在打开项目时,会通过运行普通的 git 命令——git status、git diff——来收集上下文。Git 从仓库自身的 .git/config 读取设置,而其中大约二十多项设置会指定一个供 git 执行的程序。把一条命令放进 core.fsmonitor,它就会在你输入任何内容之前,以你的权限、在任何沙箱之外运行。
两项公开研究让这一点变得具体:
.git/config 不会通过克隆传输。仓库必须以文件形式到达,且其 .git 目录已经包含在内——一个 zip 包、一个共享驱动器、一个同步文件夹、一个 USB 盘、一个解压归档的代理。(Manifold Security,The Hacker News)@github/copilot 1.0.43 中通过强制 safe.bareRepository=explicit 修复。(GitHub Advisory)两份报告中推荐的用户侧缓解措施相同:在用代理打开目录之前检查 git 配置。 在整个目录树上手动执行这项工作很繁琐。此工具只需一秒钟即可完成。
git 攻击向量有一个可取之处:仓库必须以文件形式到达,因为克隆不会携带 .git/config。代理设置则没有这样的要求。.mcp.json、.claude/settings.json 或 .vscode/mcp.json 是普通的受跟踪文件——它像其他文件一样随 git clone 到达——编码代理在打开项目时会读取它。MCP 服务器条目指定一个程序,代理就会启动它;钩子指定一条命令,代理就会在某个事件上运行它;权限设置可以关闭代理先询问你的那一步。
这些配置在实践中被配置得有多仔细,有一个外部数字值得参考。Bloomberry 在 2026 年 2 月测量了 1,412 个公司托管的 MCP 服务器,发现 38.7% 完全没有身份验证,而六个月前是 425 个服务器。那些是公共端点,而不是你仓库中的服务器定义——属于不同的群体——但这是同一个生态系统,它说明了这些配置得到了多少关注。(Bloomberry)
还有一点值得直白说明,而不给出具体数字:“有人发现它”和“有人利用它”之间的差距正在缩小,因为发现和利用越来越多地由同一套自动化机制完成。这是打开目录前先检查的理由,而不是对报告中任何特定行感到恐慌的理由——这就是为什么 GuardSkill 不会为单个发现附加利用时间声明。它无法知道。
代理可能拾取的每一个 git 配置,而不仅仅是显而易见的那个:项目自身的 .git、任何作为内容到达的嵌套 .git、任何隐藏在子目录中的裸仓库、子模块或链接工作树留下的 .git 文件、config.worktree、每个 .git/modules/<name>/config,以及任何通过 include.path 引入且位于树内的文件。
仓库可以随附的 agent 设置文件:树中任意位置的 .mcp.json、.claude/settings.json 和 settings.local.json、.vscode/mcp.json、.cursor/mcp.json、.gemini/settings.json、.windsurf/mcp.json。这两类文件在一次目录树遍历中即可全部发现;第二类不会带来额外开销。
完整列表按 key 逐项列出,每项都标注了来源和覆盖状态,见 rules/git-exec-keys-inventory.md。如果该清单与规则集出现偏差,测试就会失败,因此这份列表是可审计的,而非一厢情愿的声明。概括如下:
| 类别 | 检查项 |
|---|---|
| 在普通命令上运行 | core.fsmonitor、core.pager、pager.<cmd>、core.editor、sequence.editor、diff.external、core.askPass、core.alternateRefsCommand |
| 在网络操作上运行 | core.sshCommand、core.gitProxy、remote.<n>.uploadPack / receivePack、uploadpack.packObjectsHook |
通过 .gitattributes 运行 | filter.<d>.clean / .smudge / .process、diff.<d>.textconv、merge.<d>.driver |
| 按需运行 | mergetool / difftool / browser / guitool / man 的 .cmd、credential.helper、gpg.program、trailer.<t>.command、任何会调用 shell 或用 -c 重新进入 git 的 alias.* |
| 后续引入设置 | include.path、includeIf.*.path(会被跟随并检查)、init.templateDir |
| 会执行代码的传输方式 | protocol.allow、使用 ext:: 的 remote 和 submodule URL |
| 钩子 | core.hooksPath、.git/hooks 中的活动脚本、会下载或解码代码的钩子脚本、作为符号链接的钩子脚本 |
| 结构 | 树中的裸仓库、未注册为 submodule 的嵌套 .git 目录、大小写不同的 .git 目录 |
有四个 key 被有意排除在范围之外,每个都在清单中给出了理由:sendemail.smtpServer、instaweb.httpd、ssh.variant 以及 HTTP 代理设置。正因如此,本 README 列出的是它检查的内容,而不是声称覆盖了某一整类漏洞——只有当那一列完全为空时,这种声称才成立。
第二类检查有自己的清单 rules/agent-settings-inventory.md,背后同样有漂移测试。
| 检查项 | 严重级别 |
|---|---|
从 PATH 启动的 MCP 服务器(npx、uvx、node、docker) | low——信息性。大多数 MCP 服务器就是这样配置的 |
| 命令是树内的路径,或某个参数指向树内的文件 | high |
命令是 shell、会下载并运行代码,或位于 /tmp 或隐藏目录中 | critical |
声明了远程服务器,但 headers 或 env 中没有任何凭据材料 | medium |
| 在 agent 事件上运行命令的钩子 | 与上述相同的分级——npx prettier --write 是信息性的,来自树内的脚本是 high,shell 管道是 critical |
请求跳过审批步骤(bypassPermissions) | high,且发现项会说明客户端实际会如何处理它 |
| 扫描器无法识别的服务器条目形态 | medium——无法理解不等于不存在 |
permissions.allow 中的通配符 | high |
| 形似凭据的值 | high |
如果你自己的项目随附了自己的 MCP 服务器,该条目会以 high 级别报告——GuardSkill 无法区分仓库是你自己写的还是别人交给你的。请使用 --fail-on critical,或用 --exclude 排除该路径。
反过来:对于别人交给你的目录树,请用 --fail-on low 扫描。 以 npx -y @attacker/mcp-helper 启动的服务器按设计就是信息性的——命令本身很普通,整个攻击都藏在包名里,而按名称判断一个包属于注册表信誉问题,需要联网。默认阈值不会因此失败。该默认值是为 CI 中你自己的仓库调校的;而一个交付来的目录是另一回事,值得使用更低的阈值并亲自读一遍列表。
acceptEdits 和 plan 不会被报告。文档明确说明了 acceptEdits 允许什么——读取、文件编辑和常见文件系统命令,而 Bash 和网络仍会提示——因此将其称为审批绕过在事实上是错误的,而且它是最常用的设置之一。
有意不检查的内容: 远程 MCP 服务器是否实际需要身份验证。这只能通过连接来回答,而此工具不进行任何网络连接。mcp-remote-no-auth 发现报告的是文件所声明的内容,并在其自身文本中说明了这一点。
npx guardskill . # scan the current project
npx guardskill ~/code/some-project # scan a specific path
npx guardskill . --json # machine-readable
npx guardskill . --out report.md # also write a Markdown report
npx guardskill . --fail-on critical # only fail the build on critical findings
npx guardskill . --allow-incomplete # accept a partial walk
npx guardskill . --exclude test/fixtures
npx guardskill . --sarif-out results.sarif # for GitHub code scanning
或者安装一次:npm install -g guardskill,然后运行 guardskill .。
从克隆的仓库运行时,入口点是 node bin/guardskill.js。src/ 是一个库——直接运行它不会做任何事,这是有意为之:第一个候选发布版本中出现的 bug 是一个 CLI 守护了自身的执行,却因 npm 的 bin 符号链接而丢失了该守护。现在只有已发布的二进制文件才会启动扫描,并且有一个打包测试在三个平台上驱动它。
这是两个不同的答案,工具会同时报告两者。JSON 中的 status 表示发现了什么。退出码 表示在你设定的阈值下,这是否严重到足以判定失败。
status | 含义 |
|---|---|
CLEAN | 零发现,且整棵树都被检查过 |
FINDINGS | 至少有一个发现,任意严重级别——包括低于你阈值的发现 |
INCOMPLETE | 没有发现,但树的一部分未被检查 |
ERROR | 扫描未运行 |
| 退出码 | 含义 |
|---|---|
0 | 没有达到或超过 --fail-on 的发现,且整棵树都被检查过 |
1 | 存在达到或超过 --fail-on(默认:high)的发现 |
2 | 扫描无法运行:路径错误、选项错误、规则集无效 |
3 | 树的一部分未被检查——遍历被截断、符号链接被拒绝、包含项位于树外 |
因此,一个有一个中等级别发现且使用默认阈值的仓库会报告 status: FINDINGS 并以 0 退出。这种组合是有意为之:退出码 0 是策略层面的答案,而读取 JSON 的消费者在做出决定之前仍然必须能够看到发现了什么。CLEAN 意味着零发现,仅此而已。
--fail-on 只移动严重级别阈值,仅此而已——它绝不会从报告中移除任何发现。完整性又是另一个独立的维度:不完整的扫描会失败,除非你传入 --allow-incomplete,因为“我们没有检查那里”与“那里什么都没有”并不相同。
使用 --json 时,失败也会以 JSON 形式作答:一个包含相同字段的错误文档,status: "ERROR"、scanned: false,原因放在 reason 中,这样将输出管道接入解析器的消费者得到的是诊断信息而不是解析错误。人类可读的原因也会输出到 stderr。
在 CI 中:
- name: Check for git execution vectors
run: npx guardskill . --fail-on high
或者作为一个操作,它会为你固定版本:
- uses: soemoescode/[email protected]
with:
fail-on: high # critical, high, medium or low
exclude: test/fixtures # comma-separated, optional
借助 SARIF,发现项不再只是一个红色叉号,而是成为仓库自身代码扫描视图中的行,并显示每个发现项对应的文件、行号和状态:
- uses: soemoescode/[email protected]
with:
sarif-file: guardskill.sarif
fail-on: critical # let the Security tab carry the rest
continue-on-error: true
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: guardskill.sarif
每个规则在每个文件中最多列出 50 条发现,其余部分则汇总为一条发现计入总数——否则,一个包含数千个相同问题的设置文件会生成 GitHub 拒绝接受的 SARIF 文档,进而导致 Security 标签页完全不显示任何内容。
--sarif 将同一文档写入 stdout,而 --sarif-out <file> 则将其与可读报告一并写出,而非替代可读报告。严重性映射是明确声明的,而非猜测:critical 和 high 映射为 error,medium 映射为 warning,low 映射为 note,而 security-severity——GitHub 用于排序的数值——则根据这同样的四个级别推导得出。GuardSkill 不计算 CVSS 评分,若从某一评分填充该字段,则等于作出其无法支撑的断言。不完整的扫描同样会被传递,作为运行中的工具通知:一个对其中一半从未被打开的目录树悄然不显示任何内容的 Security 标签页,与对其以 0 退出码结束是同样的失败。
JSON 输出携带 schemaVersion: 1。字段将在版本 1 内新增;现有字段的含义不会改变。
示例输出:
GuardSkill - git execution-vector scan (read-only)
Path: /Users/dev/clients/handover-package
Git configurations inspected: 3 Directories walked: 412