agent-guards

agent-guards core

Package Guard、Agent Firewall、Payment Guard、Email Guard、Code Guard 和 Agent Web Tools 背后的检测引擎，整合在一个软件包中，在你的机器上运行。

这里的一切都是确定性的：正则规则、已发布的列表和解析器。任何检测路径都不会调用模型，因此相同输入会得出相同判定，每项判定都会标明生成它的规则版本。

运行

npx agent-guards

这会启动一个 MCP stdio 服务，包含全部六款产品的所有工具。无需配置、API 密钥或账号。

npx agent-guards --offline          # local engines only
npx agent-guards --only code-guard  # one product
npx agent-guards --list             # what you get, and which tools need the network
npx agent-guards --disable check_ip,check_password

同一软件包也会安装 guard CLI：

npx --yes --package agent-guards guard scan src/
npx --yes --package agent-guards guard diff
npx --yes --package agent-guards guard stats --json

pre-commit

此仓库为 pre-commit 框架发布了一个暂存差异钩子。它需要 Node 18 或更高版本。将以下内容添加到 .pre-commit-config.yaml：

repos:
  - repo: https://github.com/mlawsonking/MCP
    rev: main  # pin this to a commit SHA in a shared repository
    hooks:
      - id: agent-guards-diff

然后运行 pre-commit install。该钩子只扫描新增行，并使用固定版本检出中的规则。它不会调用模型，也不会将文件内容发送到任何地方。另有一个手动钩子 agent-guards-scan，运行 pre-commit run agent-guards-scan --hook-stage manual 时会扫描整个工作树。

本地与云端，以及区别为何重要

本地工具完全在你的机器上运行。你扫描的文本绝不会离开本机。

本地运行，无需联网	需要网络
提示词注入和 Unicode 混淆扫描	软件包是否存在、发布时间和漏洞（npm、PyPI、OSV）
密钥和 PII 检测，并支持脱敏	制裁名单和诈骗名单筛查（OFAC 名单、拦截名单）
代码和差异扫描	泄露密码查询（Have I Been Pwned）
URL 结构分析	域名年龄、ASN、拦截名单信誉
电子邮件解析、伪造启发式检测、标头读取	SPF/DMARC/MX 记录、一次性域名列表

云端工具会在各自的工具说明中指出它们调用的服务。使用 --offline 时，它们会报告无法进行检查，不会返回判定结果。

这一区别正是整个设计的核心。未执行的检查不等于通过。这个代码库曾经发布过与此相反的行为：四个端点在背后的查询失败或根本没有尝试时，仍回答“未受制裁”“没有已知漏洞”“不是蜜罐”和“安全”。一个明明“不知道”却说“没问题”的安全工具，还不如没有。

它能检测什么，不能检测什么

注入扫描器会匹配已知的指令覆盖、越狱、提示词泄露、数据外传和工具投毒措辞，以及用于隐藏这些内容的 Unicode 技巧：零宽字符、双向文本覆盖、Unicode 标签块、隐藏 CSS、HTML 注释中的指令。这是一个确定性的模式扫描器，不是分类器。新颖的措辞可能绕过检测。任何读过规则的人都能设法规避。它只是一个防护层，并非铜墙铁壁。

密钥扫描器会匹配 22 种凭据格式、通用赋值形式以及 3 种 PII 模式。它不认识的格式中的密钥，或被拆分到多行的密钥，都不会被检测到。它能保证的是，找到的值会从 redacted 输出中移除，而不仅仅是移除旁边的标签。

代码扫描器针对 JS/TS 和 Python，包含 31 条正则规则。它没有解析器、没有数据流分析，也没有污点追踪，因此 exec(cmd) 中使用裸变量不会触发，而 exec("ls " + dir) 会触发。这是有意设定的限制，并且有一项测试对此进行了固定。

制裁筛查涵盖 EVM 格式的 OFAC 地址列表。蜜罐检查仅覆盖 honeypot.is 实际模拟的链。

作为库使用

const guards = require('agent-guards');

guards.injection.scan(untrustedText);      // { risk, score, verdict, findings, rules_version }
guards.secrets.scan(text);                 // { found, verdict, findings, redacted, rules_version }
guards.code.scanDiff(unifiedDiff, 'py');   // findings against new-file line numbers
await guards.safeFetch(url);               // SSRF-guarded: pins the resolved IP, rechecks every hop

只要你要获取一个并非由你选择的 URL，就应该使用 safeFetch。它只解析一次主机名，如果解析结果中有任何地址属于私有地址或环回地址，就会拒绝请求；并且会连接到该确切地址，因此 DNS 重绑定无法通过再次查询来投毒。它会重新检查每一跳重定向，并且绝不复用套接字，因为复用连接会跳过地址固定。

规则更新

规则会过时。地址会被制裁，软件包可能因携带恶意软件而从 npm 下架；如果规则只在你重新安装时才更新，这些情况就不会反映到你的规则中。因此，服务器和 CLI 大约每天会检查一次规则源，确认是否有更新的规则集，并在有更新时应用。

拉取时会发送两项信息：发起请求的界面（cli、plugin、mcp 或 facade），以及你当前使用的规则版本。

GET /api/rules/latest?surface=mcp&have=2026.07.31

不会发送机器 ID、用户 ID、文件名，也不会发送你扫描过的任何内容。规则包使用 Ed25519 签名，并通过编译进此软件包的公钥进行验证，因此由哪个镜像提供都无关紧要。签名、架构或 ReDoS 检查未通过的规则包会被丢弃，并继续使用你已有的规则。规则不会自行回退到较旧版本。

guard update --status     # what is in use, and when it last checked
guard update              # pull now

每个判定都带有 rules_provenance，其值为 bundled 或 feed@<version>，因此你始终可以知道结果是由哪个规则集生成的。

若要关闭更新：使用 --offline、设置 AGENT_GUARDS_NO_FEED=1，或在 ~/.agent-guards/config.json 中设置 {"feed": false}。AGENT_GUARDS_FEED_URL 可用于指定其他地址。关闭更新后，所有功能仍会使用编译进软件包的规则正常运行。

规则包格式、验证步骤以及恶意软件包列表的整理方式，详见 rules/README.md。

测试

npm test

仅运行离线测试套件。任何需要对第三方端点进行断言的测试都需手动运行，因为随机变红的测试套件只会让所有人学会忽略红色失败。

许可证

MIT。