yushizehuohuo-gif/agent-policy-lens

# Agent Policy Lens 🔍

一个零依赖的 CLI 工具，能在 AI agent 和 MCP 权限给你带来“惊喜”之前，将它们盘点出来。
_{零依赖 CLI 工具 — 在 AI Agent 和 MCP 权限变成安全隐患之前，先把它们列出来。}

Demo GIF — coming soon / 演示 GIF 即将添加

``` npx agent-policy-lens . ``` ## 为什么需要它 AI 编程工具正在成为开发环境的一部分，但它们的权限分散在多种配置格式中，Code review 时很容易遗漏： - 一个 MCP server 可以接收一个仓库路径**以及**一个 API token - 一个 package 脚本可以通过管道将远程安装程序注入 shell - 一个 agent 指令文件可以使自动审批变得常态化 - 一个 `.env` 文件可能不小心将一个演示变成了凭证泄露 AI 编程工具正在成为开发环境的一部分，但它们的权限分散在多种配置格式中，Code review 时很容易遗漏。 在这些配置变成不可见的背景噪音之前，该工具为团队提供了一份统一的、可 diff 的“agent 权限清单”。 ## 演示 ``` npx agent-policy-lens examples/unsafe-repo ``` ``` Agent Policy Lens Root: examples/unsafe-repo Scanned files: 4 Surfaces: 5 Findings: 10 (critical=2, high=8) Highest risk: CRITICAL Findings 1. [CRITICAL] REMOTE_INSTALLER_PIPE .mcp.json:13 Remote script is piped into a shell Fix: Pin and verify downloaded artifacts before execution. 2. [CRITICAL] REMOTE_INSTALLER_PIPE package.json:3 Remote script is piped into a shell 3. [HIGH] PLAINTEXT_REMOTE_AGENT .cursor/mcp.json:4 Agent endpoint uses plaintext HTTP 4. [HIGH] SECRET_ENV_GRANTED .cursor/mcp.json:6 Secret-like environment variable is granted to an agent 5. [HIGH] UNPINNED_PACKAGE_RUNNER .mcp.json:5 Agent uses an unpinned package runner 6. [HIGH] BROAD_FILESYSTEM_ACCESS .mcp.json:6 Agent can read a broad filesystem path 7. [HIGH] SECRET_ENV_GRANTED .mcp.json:8 Secret-like environment variable is granted to an agent 8. [HIGH] SHELL_COMMAND_AGENT .mcp.json:12 Agent starts through an unrestricted shell 9. [HIGH] AUTO_APPROVE_ENABLED .mcp.json:14 Agent approvals appear to be automatic 10. [HIGH] INSTRUCTION_AUTO_APPROVE CLAUDE.md:3 Instruction asks for automatic approval ``` 一次扫描就能发现：远程脚本通过管道注入 shell、明文 HTTP agent endpoint、授予 agent 的 secret、未锁定的 runner、宽泛的文件系统访问，以及自动审批——涵盖了 MCP 配置、指令文件和 package 脚本。 一次扫描就能发现：远程脚本管道注入、明文 HTTP agent 端点、secret 泄露给 agent、未锁定包管理器、宽泛文件系统访问、自动审批。 ## 检测范围 | 类别 | 文件 | |----------|-------| | MCP 配置 | `.mcp.json`, `mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `claude_desktop_config.json` | | Agent 指令 | `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules` | | Copilot 指令 | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md` | | 环境变量文件 | `.env*` | | Package 脚本 | 与 agent 相关的 `package.json` 脚本 | 它会标记以下模式 / 检测以下模式： - 🚨 通过管道注入 shell 的远程脚本 — `curl ... | bash` - 📦 未固定版本的 runtime package runner — `npx`, `uvx`, `pipx` 没有锁定版本 - 📂 宽泛的文件系统访问权限 — `/`, `C:\`, `$HOME`, `%USERPROFILE%` - 🔑 授予 agent 的类似 secret 的环境变量 - 👁️ 提交的配置中可能包含活动的 secret（OpenAI, Anthropic, GitHub, AWS keys） - 🌐 明文远程 agent endpoint — 使用了 `http://` 而不是 `https://` - ⚡ 自动审批或绕过安全限制的指令 ## 安装说明 ``` npm install -g agent-policy-lens ``` 或者不安装直接运行： ``` npx agent-policy-lens . ``` **零依赖。** 除了 Node.js ≥ 20 之外什么都不需要。 **零依赖。** 除了 Node.js ≥ 20 之外什么都不需要。 ## 使用 ``` agent-policy-lens [path] [options] # 短别名： aplens [path] [options] ``` ### 选项 | 选项 | 描述 | |--------|-------------| | `--format ` | 输出格式。默认值：`table` | | `--out ` | 将输出写入文件 | | `--fail-on ` | 当最高风险达到此级别时，退出码为 2 | | `--include-home` | 同时检查已知的全局 agent 配置路径 | | `--max-depth ` | 目录遍历深度。默认值：`6` | | `-h, --help` | 显示帮助信息 | ### 常用命令 ``` # 快速扫描 agent-policy-lens . # 用于 PR 的 Markdown 报告 agent-policy-lens . --format markdown --out agent-policy-report.md # 如果存在 high+ 发现则阻止 CI agent-policy-lens . --fail-on high # 包含 global configs + JSON for bots agent-policy-lens . --include-home --format json ``` ## 输出格式 | 格式 | 最适合 | |--------|----------| | `table`（默认） | 终端人类阅读 · 终端人类阅读 | | `markdown` | PR 产物、GitHub 评论 · PR 产物 | | `json` | 自动化机器人、CI pipeline · 自动化管道 | ``` agent-policy-lens . --format markdown --out agent-policy-report.md ``` ## CI 集成 添加此 workflow 以扫描每个 PR： ``` name: Agent Policy Lens on: pull_request: push: branches: [main] jobs: scan-agent-policy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 22 - run: npx agent-policy-lens . --format markdown --out agent-policy-report.md --fail-on high - uses: actions/upload-artifact@v4 if: always() with: name: agent-policy-report path: agent-policy-report.md ``` ## 规则理念 Agent Policy Lens 是有意设计的具有强烈主见且易于解释的工具。它**不**主张每一项发现都是漏洞。它只是指出了在 review 时值得用人类语言去确认的权限面： - 这个 agent 接收了什么？ - 它能执行什么？ - 它能读取或写入哪些路径？ - 哪个网络 endpoint 能看到上下文？ - 这种行为是否已固定且可重现？ 请参阅 [docs/rules.md](docs/rules.md) 获取完整的规则集。 ## 为什么零依赖 - **可审计** — 每一行代码都在这个仓库里。没有需要信任的供应链。 - **快** — `npx agent-policy-lens .` 一秒内完成。 - **CI 原生** — 除了 Node.js 之外不需要安装步骤。可以在所有 runner 上运行。 - **安全** — 安全工具本身不应该依赖 500 个你没审查过的包。 **可审计** — 所有代码都在这个仓库里，没有需要信任的供应链。 **快** — `npx agent-policy-lens .` 一秒内完成。 **CI 原生** — 不需要额外安装，所有 runner 都能跑。 **安全** — 安全工具本身不应该依赖 500 个你没审查过的包。 ## Roadmap - [ ] 用于 GitHub code scanning 的 SARIF 输出 - [ ] 仓库 baseline 支持（使用 `.agent-policy-lens.json` 记录已接受的风险） - [ ] 支持更多全局配置格式（Codex, Claude, Cursor, Windsurf, VS Code） - [ ] 一流的 MCP server allowlist - [ ] PR 评论模式（将发现直接发布到 PR） - [ ] Pre-commit hook ## 开发 ``` npm test node src/cli.js examples/unsafe-repo node src/cli.js examples/safe-repo ``` ## 相关资源 - [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) — 本工具旨在帮助提升安全性的协议 - [Hermes Agent Guide](https://github.com/yushizehuohuo-gif/hermes-agent-guide) — 适用于 Windows 的 AGENTS.md 最佳实践 - [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/) — 更广泛的 LLM 安全背景 ## License MIT © [SHIZE YU (HuoHuoOvO)](https://github.com/yushizehuohuo-gif)

_{发现 bug？缺少检测？提交一个 issue}

标签：AI安全, Chat Copilot, GNU通用公共许可证, MCP协议, MITM代理, Node.js, StruQ, Web报告查看器, 代码审查, 文档结构分析, 暗色界面, 权限管理, 模型越狱, 自定义脚本