OpsecForge

opsecforge-mcp

面向 Claude Code、Codex 和 Cursor 等 AI 编码 Agent 的本地 MCP 服务（stdio）。它有助于避免机密进入模型上下文：Agent 传入文件路径或环境变量名称，操作在你的机器上执行，返回的只有脱敏结果或派生结果。

• 不会向任何远程服务发送数据。此服务不会发出网络请求。
• 无需账户或 API 密钥，也没有遥测。
• 源代码：github.com/cyberdroid2077/opsecforge-tools（MIT）。它复用了为 opsecforge.com 上的浏览器工具提供支持的同一套经过测试的代码。

依赖此工具之前，请先阅读以下限制。 脱敏采用启发式方法，Claude Code 钩子只是尽力提供保护，并非沙箱；Codex 和 Cursor 则完全没有钩子。

安装

需要 Node.js 20 或更高版本。

Claude Code：插件（推荐：MCP 服务 + 防护钩子 + 技能）

/plugin marketplace add cyberdroid2077/opsecforge-tools
/plugin install opsecforge@opsecforge

插件会添加以下三项：

1. MCP 服务（npx -y [email protected]），公开为 mcp__plugin_opsecforge_opsecforge__*；
2. 一个 PreToolUse 钩子，用于阻止可能直接读取 .env、*.pem、*.key、id_rsa*、id_ed25519*、credentials、*.p12 等文件的 Read、Grep 和 Bash 调用，并提示模型改用 redact_file（允许读取 .env.example、.env.sample、.env.template 和 *.pub）；
3. 一项技能，告诉 Agent 何时使用哪个工具。

钩子的 onFailure: "block" 设置需要较新的 Claude Code 版本（根据钩子文档，为 v2.1.295 或更高版本）。在较旧版本中，超时的钩子可能会被跳过，而不是阻止操作。

Claude Code：仅 MCP 服务

claude mcp add opsecforge -- npx -y opsecforge-mcp

Codex

添加到 ~/.codex/config.toml：

[mcp_servers.opsecforge]
command = "npx"
args = ["-y", "opsecforge-mcp"]

（或者执行 codex mcp add opsecforge -- npx -y opsecforge-mcp。）

Cursor

添加到 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）：

{
  "mcpServers": {
    "opsecforge": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "opsecforge-mcp"]
    }
  }
}

工具读取的环境变量

verify_webhook 和 inspect_jwt 会按名称从环境变量读取机密。该变量必须存在于 MCP 服务进程的环境中。请在启动 Agent 的 shell 中导出该变量，或在客户端的服务配置中添加 env 条目。不要将机密粘贴到聊天中，也不要提交机密。

可选的加固措施：将 OPSECFORGE_MCP_ROOTS 设置为以路径分隔符分隔的目录列表（例如 /home/me/projects），文件工具将拒绝访问这些目录之外的路径。

工具

所有工具均为只读，在本地运行，并会返回易于理解的错误，而不会导致服务崩溃。

redact_file({ path })

读取本地文本文件，并将机密替换为 [REDACTED] 后返回，同时提供发现项摘要：类型、数量和行号（对应原始文件）。绝不返回原始值，也不会显示值的任何部分。响应开头会说明原始值没有离开本机，也没有传到模型。

仅接受常规文件（不接受目录、管道或设备），大小不得超过 1 MiB；更大的文件会返回明确的错误消息。拒绝处理二进制文件。可检测的内容包括：私钥块（包括未闭合的私钥块，会从 BEGIN 开始屏蔽至文本末尾）、敏感命名字段（password、token、secret、*_KEY 等）、Authorization／Cookie／API 密钥标头、URL 凭据、AWS、Stripe、GitHub、GitLab、Slack、Google、OpenAI、Anthropic 和 SendGrid 密钥格式，以及 JWT 格式字符串。

scan_secrets({ paths?, staged? })

提交前检查。扫描文件或目录（paths），和／或仅扫描 git diff --cached 中新增的行（staged: true）。会列出 file:line、机密类型和屏蔽后的预览：对于 20 个字符或更长的值，显示前 4 个字符；否则只显示 …。绝不返回原始值。目录扫描会跳过 .git、node_modules、构建输出和符号链接；最多读取 2000 个文件，每个文件不超过 1 MiB，并跳过二进制文件。

redact_text({ text })

对 Agent已经拥有的文本进行脱敏，例如在将日志粘贴到问题或工单之前。该文本已经位于模型上下文中；此工具无法将其从上下文中移除。它只会生成一份更安全的副本，供对外分享。若要从一开始就避免机密进入上下文，请使用 redact_file 并提供路径。

verify_webhook({ provider, body_path, secret_env, signature, algorithm?, tolerance_seconds? })

离线验证 github（X-Hub-Signature-256）、stripe（Stripe-Signature）或 generic HMAC（hex 或 base64，sha1/sha256/sha512）签名。

• 密钥仅从 secret_env 指定的环境变量中读取。没有明文密钥参数；任何未知参数（例如 secret）都会被拒绝并附上说明，且不会回显其值。
• 正文会从 body_path 以原始字节形式读取（最多 10 MiB）。请按收到时的原样保存。
• 返回匹配 / 不匹配结果及诊断信息：签名标头格式是否正确；Stripe 时间戳的年龄以及是否超出容差范围（默认为 300 s）；正文是否看起来经过重新格式化（它会测试移除或添加末尾换行符、CRLF/LF 转换、移除 BOM，以及将 JSON 压缩或美化打印后，签名是否会匹配）；密钥周围是否有空白字符或引号；是否错误地使用 Stripe API 密钥代替所需的 whsec_ 签名密钥。
• 它绝不会返回密钥或计算出的签名。

inspect_jwt({ token_env?, token? })

解码 JWT 并返回标头、声明、时间声明状态（exp、nbf、iat、auth_time）和风险提示：alg: none、无法离线验证的 HMAC 算法、缺少 exp，以及 jku/jwk/x5u 标头。解码不等于验证：此工具没有密钥，也绝不会检查签名。优先使用 token_env（变量名），以免原始令牌经过模型；token 参数中的内容已经位于上下文中。名称看起来像机密的字段所对应的声明值会被遮蔽，但无论如何，返回的声明都会进入上下文。

file_checksum({ path, algorithm, expected? })

计算本地文件的 SHA-256 或 SHA-512 校验和（最多 32 MiB），并可选择与预期值进行比较（接受 <hex>、sha256:<hex> 和 sha256sum 输出）。匹配只能证明该文件与预期值的来源一致。

诚实说明局限

• 此钩子只是尽力而为的防护措施，并非沙盒。 它会解析工具调用的文本，但无法阻止脚本间接读取机密文件（例如打开 .env 的 python app.py、make、docker compose config），也无法阻止对包含 .env 的目录运行 grep -r、使用 shell 变量或命令输出作为文件名的命令（cat "$FILE"、find . -name .env | xargs cat），或语言运行时在程序内部执行的任何操作。请将其视为一道减速带，用来拦截常见的意外情况。

• 若要加强保护，请结合 Claude Code 自身的控制措施：在其沙盒中运行，并在 settings.json 中为机密路径添加 Read 拒绝规则（请查看权限文档，了解准确的模式语法），例如：

  { "permissions": { "deny": ["Read(./.env)", "Read(./.env.local)", "Read(**/*.pem)", "Read(~/.ssh/**)"] } }
  

  拒绝规则也存在漏洞，且可能触发提示或误报；请先测试。

• 脱敏采用启发式方法，可能会漏掉机密信息。 它可以识别常见格式和看起来像机密信息的字段名，但无法识别自定义令牌格式、正文中的机密信息、经过 base64 编码的值，或以不常见方式跨行拆分的机密信息。分享结果前请先检查，并将干净的结果理解为“未匹配到内容”，而不是“其中没有机密信息”。它也可能误删无害的值（误报）。

• 每个 MCP 工具的参数和结果都会经过模型。 因此这些工具会接收路径和变量名。使用 token 的 redact_text 和 inspect_jwt 无法阻止你交给它们的内容进入上下文。

• Codex 和 Cursor 没有与 Claude Code PreToolUse 钩子等效的机制。 在这些客户端中，工具仅起辅助作用：只有 Agent 选择调用它们，而不是直接读取文件时，它们才能提供帮助。请同时使用各客户端自身的权限和沙盒设置。

• 脱敏后的输出仍会包含所有未匹配到的内容（主机名、用户名、内部 URL、个人数据）。

• scan_secrets 不能替代 CI 中使用的、规则集持续维护的专用扫描器。

• 如果机密信息已经进入模型上下文、日志或提交记录，请轮换它。

了解更多

这些检查的浏览器本地版本及其背景介绍均可在 opsecforge.com 上找到：

• Env 文件清理器 和 分享前如何清理 .env 文件
• Webhook 调试器 和 使用 HMAC-SHA256 验证 Webhook 签名
• JWT 解码器 和 JWT 漏洞与安全验证
• 哈希与文件校验和生成器 和 哈希生成器与数据完整性
• 环境变量安全与机密管理
• AI Agent 凭证安全

许可证

MIT