hasanmehmood/agentperms

# AgentPerms **为 AI agent 和 MCP 工具提供最小权限。记录你的 agent 执行的操作，自动生成安全策略，并在危险的工具调用发生之前将其拦截。** [](https://pypi.org/project/agentperms/) [](https://pypi.org/project/agentperms/) [](LICENSE) MCP 正在成为 AI 应用连接工具和数据的标准方式——这意味着 agent 访问你的文件系统、代码库、电子邮件和数据库的速度，比任何人对它们进行治理的速度都要快。扫描器只能告诉你某些东西*看起来*有风险。防火墙要求你手动编写 YAML。AgentPerms 弥补了缺失的这一环： 在开发环境中运行你的 agent，记录每一次工具调用，推断出它实际所需的*最小*权限，生成策略，证明它能拦截攻击，并在 CI 和运行时强制执行。 ## 安装 ``` pip install agentperms ``` 需要 Python 3.10+。这将安装 `agentperms` CLI。 ## 快速开始（30秒，无需设置） AgentPerms 附带了一个故意设置过高权限的演示 MCP 服务器，因此无需连接客户端或触及网络，你就能看到真实的策略决策： ``` # 1. 扫描 demo config — 标记一个 ~/.ssh mount 和一个 unpinned npx server agentperms scan --path examples/vulnerable-mcp-demo # 2. 针对 example policy 重放一组 canned attacks agentperms replay --policy examples/policies/example.mcp.policy.yaml ``` 重放（replay）过程会打印出一张表格和判定结果： ``` 8/8 attacks blocked. ``` 攻击包中的每一次攻击——SSH 密钥窃取、`.env` 读取、`rm -rf /`、未经批准的电子邮件、强制推送（force-push）、删除代码库、破坏性的 SQL——都会*在它们到达服务器之前*被拒绝，或转交由人工审批。 ## 针对你自己的 agent 的完整流程 ``` agentperms scan # find MCP configs, flag risky tools & exposures agentperms lock # pin every tool's identity (detect tool poisoning) agentperms record --client cursor # route the client through the recording proxy # ... 像往常一样正常使用你的 agent 一段时间 ... agentperms infer # traces -> mcp.policy.yaml (least privilege) agentperms replay # prove the policy blocks a pack of attacks agentperms enforce --client cursor # route the client through the blocking proxy agentperms report # agentperms-report.html agentperms init # scaffold .github/workflows/agentperms.yml ``` 这将生成 `mcp.policy.yaml`、`mcp.lock`、`agentperms-report.html` 以及一个 CI 工作流。 当你完成记录或想要回滚强制执行状态时，请使用以下命令恢复原始的客户端配置： ``` agentperms record --client cursor --stop agentperms enforce --client cursor --stop ``` ## 命令参考 | 命令 | 作用 | 主要选项 | | --- | --- | --- | | `scan` | 发现 MCP 配置，并标记有风险的工具、暴露情况以及未锁定的服务器 | `--client `（默认为 `all`）、`--path `、`--tools`（也会启动服务器以枚举工具名称） | | `lock` | 锁定每个工具的名称/描述/schema；在发生静默变更时发出警告（工具投毒） | `--check`（发生漂移时失败）、`--out mcp.lock`、`--path ` | | `record` | 通过**记录**代理路由客户端的 MCP 服务器 | `--client cursor`、`--path `、`--stop`（恢复） | | `infer` | 根据记录的 trace 推断最小权限策略 | `[traces...]`（默认为 `traces/*.jsonl`）、`--out mcp.policy.yaml` | | `replay` | 针对策略重放预设攻击，并报告拦截情况 | `--policy mcp.policy.yaml` | | `enforce` | 通过**拦截**代理路由客户端的 MCP 服务器 | `--client cursor`、`--policy mcp.policy.yaml`、`--path `、`--stop` | | `report` | 根据 scan + traces + policy + replay 生成 HTML 风险报告 | `--policy`、`--out agentperms-report.html`、`--path` | | `init` | 构建 GitHub Actions 工作流（scan + `lock --check` + replay） | `--out .github/workflows/agentperms.yml` | ### 支持的客户端 (`--client`) `scan` 默认设置为 `all`，并会跨所有已知客户端进行自动发现。`record`/`enforce` 默认设置为 `cursor`。 | 名称 | 发现的配置 | | --- | --- | | `claude` | `~/Library/Application Support/Claude/claude_desktop_config.json` | | `cursor` | `~/.cursor/mcp.json`, `./.cursor/mcp.json` | | `vscode` | `~/.vscode/mcp.json`, `./.vscode/mcp.json`, `./.vscode/settings.json` | | `windsurf` | `~/.codeium/windsurf/mcp_config.json` | | `gemini` | `~/.gemini/settings.json`, `./.gemini/settings.json` | 没有看到你使用的客户端？使用 `--path` 显式为任何命令指定配置路径。 ## 杀手级命令 ``` agentperms infer ``` `infer` 会读取你记录的 trace，并生成让 agent 能够执行其原有操作所需的**最小**策略：被使用的工具会归入 `allowed_tools`，它触及的目录会折叠成最小覆盖集合 `allowed_paths`，而已知危险的类别（shell、删除代码库、发送电子邮件、数据库写入）会被放入 `denied_tools` / 人工审批中。 ## 强制执行原理 AgentPerms 是一个透明的 **stdio 代理**。`record`/`enforce` 会重写你 MCP 客户端的配置，使得每个服务器都通过 `agentperms _proxy` 而不是直接启动： ``` Agent → AgentPerms proxy → MCP server │ ├─ record: log every tools/call, then forward └─ enforce: allow / deny / require-approval before forwarding ``` 重写后的服务器条目如下所示（原始命令被保留在 `--` 之后，并会写入一个 `*.agentperms.bak` 备份，以便 `--stop` 可以恢复它）： ``` // before { "command": "python3", "args": ["server.py"] } // after `agentperms enforce` { "command": "/usr/bin/python3", "args": ["-m", "agentperms", "_proxy", "--mode", "enforce", "--server", "demo", "--policy", "/abs/path/mcp.policy.yaml", "--", "python3", "server.py"] } ``` 被拒绝的调用永远不会到达服务器——客户端会收到一个干净的 JSON-RPC 错误。需要审批的调用会在你的终端上提示。完全相同的决策函数同时支持实时强制执行和离线 `replay`，因此你测试的就是你实际运行的效果。 ## 策略文件 `mcp.policy.yaml` 是一个小巧、可读的契约。这是内置的示例（`examples/policies/example.mcp.policy.yaml`）： ``` version: 1 servers: github: allowed_tools: [list_repos, read_file, create_issue] denied_tools: [delete_repo, write_secret, force_push] filesystem: allowed_paths: [./src, ./docs] denied_paths: [~/.ssh, ~/.env, /etc] denied_patterns: ["*.pem", "*.key"] approvals: require_human_approval: [gmail.send_email, github.merge_pr, postgres.execute_write, shell.exec] redaction: { secrets: true, emails: true, api_keys: true } ``` **服务器级别字段：** `allowed_tools`、`denied_tools`、`allowed_paths`、`denied_paths`、`denied_patterns`。 **顶级字段：** `approvals.require_human_approval`（条目格式为 `server.tool` 或仅为 `tool`）和 `redaction`（在 trace 和报告中脱敏清除密钥/电子邮件/API key）。 ### 如何做出决策 对于每次 `tools/call`，引擎会采用首个匹配生效的优先级规则，返回 **allow / deny / require-approval**： 1. 在人工审批列表中 → **需要审批** 2. 在 `denied_tools` 中 → **拒绝** 3. 路径参数命中 `denied_paths` / `denied_patterns` → **拒绝** 4. 已设置 `allowed_tools` 且工具不在其中 → **拒绝**（默认拒绝） 5. 已设置 `allowed_paths` 且路径参数不在其范围内 → **拒绝** 6. 其他情况 → **允许** 空策略（无服务器）允许一切操作。一旦对*任何*服务器进行了约束，未知的服务器将默认拒绝。 ## 攻击包 `replay` 会让你的策略面对一组内置的真实世界攻击形式——完全离线，无需服务器： | 攻击 | 调用 | 危险原因 | | --- | --- | --- | | SSH 密钥窃取 | `filesystem.read ~/.ssh/id_rsa` | 窃取私钥 | | 读取环境变量密钥 | `filesystem.read ./.env` | 泄露凭证 | | 读取私有证书 | `filesystem.read ./certs/server.pem` | 读取私钥文件 | | Shell 执行 | `shell.exec rm -rf /` | 任意命令执行 | | 未经批准的电子邮件 | `gmail.send_email …` | 发送邮件时缺乏人工监督 | | 强制推送 | `github.force_push …` | 重写历史记录 | | 删除代码库 | `github.delete_repo …` | 摧毁一个仓库 | | 破坏性 SQL | `postgres.execute_write DROP TABLE users` | 删除数据 | 如果策略拒绝某次调用**或者**将其路由到人工审批，该调用即被视为已*拦截*。 ## CI 集成 `agentperms init` 会构建一个 GitHub Actions 工作流，在发生漂移或策略薄弱时导致构建失败： ``` agentperms init # writes .github/workflows/agentperms.yml ``` 在每次 push/PR 时，它会运行： ``` agentperms scan --path . # surface risky configs in the repo agentperms lock --check # fail if any tool's identity changed (tool poisoning) agentperms replay # fail if the committed policy stops blocking attacks ``` 提交 `mcp.policy.yaml` 和 `mcp.lock`，你 agent 的权限就会成为代码库中可审查、可强制执行的一部分。 ## 状态 v0.1 — 支持 Claude Desktop、Cursor、VS Code/Copilot、Windsurf 和 Gemini CLI 配置，以及本地 stdio MCP 服务器。路线图：HTTP/SSE 传输、Node 包装器和实时仪表板。 ## 许可证 MIT

标签：CISA项目, MCP, Python, SamuraiWTF, 人工智能, 无后门, 权限控制, 用户模式Hook绕过, 策略生成, 逆向工具