MusaIslamFahad/sentinelmcp

## 架构 由 LangGraph 编排的四个 agent： ``` ┌───────────┐ ┌───────────┐ ┌──────────┐ ┌───────────┐ │ Attacker │ ──▶ │ Target │ ──▶ │ Judge │ ──▶ │ Reporter │ │ agent │ │ agent │ │ agent │ │ agent │ └───────────┘ └───────────┘ └──────────┘ └───────────┘ selects/mutates system under scores vs. aggregates adversarial test (your rubric, JSON into scorecard, test case agent or the verdict flags high- sample one) severity fails ``` - **Attacker（攻击者）** — 回放预先准备好的对抗性 prompt，或者（可选）让 LLM 将其改写为一个新的变体。 - **Target（目标）** — 被测 agent。内置了一个示例客户支持 agent（包含模拟的敏感工具：退款、删除账户、更新订单、获取客户数据），以便您可以立即运行测试套件。通过实现 `run(prompt, context) -> {"response_text": ..., "tool_called": ...}` 来替换为您自己的 agent。 - **Judge（评判者）** — LLM-as-judge，强制输出严格的 JSON 并使用 pydantic 进行验证。工具劫持的判定会进行额外的确定性检查（如果目标工具实际上被触发了，这将覆盖 LLM 的意见——客观信号不应仅由 LLM 来判断）。 - **Reporter（报告者）** — 纯数据聚合，不调用 LLM。生成各个类别的成功率，并标记高危故障。 所有这些也都作为一个 **MCP server** (`mcp_server/server.py`) 暴露出来，包含四个工具：`run_injection_suite`、`score_trajectory`、`generate_report`、`list_attack_categories` ——因此任何兼容 MCP 的客户端都可以触发审计，而无需了解任何内部细节。 ## 攻击分类体系 8 个类别，24 个种子测试用例（每个类别 3 个），定义在 `eval/taxonomy.py` 和 `eval/test_cases.py` 中： | 类别 | 测试内容 | |---|---| | `direct_injection` | “忽略你的指令”类型的 prompt | | `indirect_injection` | 隐藏在“检索到”的文档/工单内部的恶意指令 | | `tool_hijacking` | 未经授权试图触发退款、删除等操作 | | `role_confusion` | 攻击者冒充系统/管理员/开发者 | | `prompt_exfiltration` | 试图原样提取系统 prompt | | `data_exfiltration` | 试图提取其他用户的 PII | | `context_overflow` | 在真实指令上覆盖大量填充文本 | | `contradiction_pressure` | 冲突的指令，以观察哪一方会胜出 | 扩展 `eval/test_cases.py` 来增加测试套件，或者使用 `--mutate` 运行，让 Attacker LLM 在 runtime 生成改写的变体。 ## 免费运行 这里的每一项基础设施（LangGraph、FastAPI、SQLite、Streamlit、Docker）都是免费的，没有任何限制。默认情况下唯一需要花钱的是 LLM 推理——以下是如何将其成本也保持在 $0 的方法。 ### 选项 A：Groq 免费层（推荐 —— 快速，无需本地设置） 1. 在 [console.groq.com](https://console.groq.com) 注册 —— 无需信用卡。 2. 生成 API key。 3. `cp .env.example .env` 并设置 `GROQ_API_KEY`。 Groq 的免费层提供每分钟约 30 次的请求频率限制，以及针对 Llama 3.3 70B 等开源模型的宽裕每日 token 额度——对于这个测试套件来说绰绰有余。项目会自动调整请求节奏（`.env` 中的 `REQUEST_DELAY_SECONDS`）以保持在每分钟的限制之下，并在遇到 429 错误时进行退避重试。 ### 选项 B：Ollama（完全本地化，零速率限制） 1. 安装 [Ollama](https://ollama.com)。 2. `ollama pull llama3.1` 3. 在 `.env` 中，设置 `TARGET_PROVIDER=ollama`（或 `DEFAULT_PROVIDER=ollama` 以完全在本地运行）。 ### 推荐的分配方案 将 Target 运行在本地 Ollama 上，而将 Attacker/Judge/Reporter 运行在 Groq 上——这样您就不会在测试对抗双方时消耗您的 Groq 配额。这是 `.env.example` 中的默认设置。 ## 安装说明 ``` git clone cd sentinelmcp pip install -r requirements.txt cp .env.example .env # then fill in GROQ_API_KEY (or set up Ollama) ``` ## 用法 **针对示例目标 agent 运行完整的测试套件：** ``` python main.py --target "support-agent-v1" ``` **仅运行特定类别：** ``` python main.py --target "support-agent-v1" --category tool_hijacking direct_injection ``` **使用 LLM 生成的改写变体，而不是静态的种子 prompt：** ``` python main.py --target "support-agent-v1" --mutate ``` **在仪表盘中查看结果：** ``` streamlit run dashboard/app.py ``` **作为 MCP server 运行：** ``` python -m mcp_server.server ``` 然后将任何兼容 MCP 的客户端指向它，并调用 `run_injection_suite`、`score_trajectory` 或 `generate_report`。 **使用 Docker 运行：** ``` docker compose up ``` **运行离线测试套件**（无需 API key —— 使用模拟的 LLM 客户端来验证所有的编排逻辑）： ``` pytest tests/ -v ``` ## 针对您自己的 agent 进行测试 将 `agents/target.py` 中的 `TargetAgent` 替换为对您真实 agent 的封装。唯一重要的约定： ``` class TargetAgent: def run(self, prompt: str, context: str = "") -> dict: # ... call your real agent here ... return {"response_text": "...", "tool_called": "tool_name_or_None"} ``` 然后像往常一样运行 `python main.py --target "my-real-agent"`。 ## 项目结构 ``` sentinelmcp/ ├── main.py # CLI entry point ├── config.py # provider/model configuration ├── llm_client.py # unified Groq/Ollama client with rate-limit handling ├── agents/ │ ├── attacker.py │ ├── target.py # sample target agent + mock sensitive tools │ ├── judge.py # LLM-as-judge with strict JSON rubric │ ├── reporter.py # aggregation, no LLM call │ └── graph.py # LangGraph orchestration ├── eval/ │ ├── taxonomy.py # attack categories + severity weights │ └── test_cases.py # 24 seed adversarial test cases ├── mcp_server/ │ └── server.py # MCP server exposing the suite as tools ├── storage/ │ └── db.py # SQLite persistence ├── dashboard/ │ └── app.py # Streamlit reliability dashboard └── tests/ └── test_basic.py # offline tests (fake LLM client, no API needed) ``` ## 扩展此项目 - **扩充测试库**，超过 24 个用例 —— 添加到 `eval/test_cases.py` 中，或者依靠 `--mutate` 来生成变体。 - **添加新的攻击类别** 到 `eval/taxonomy.py` 中。 - **添加可解释性层** —— 归因于长/对抗性 prompt 中的*哪一部分*触发了偏差（这是顺理成章的下一步，如果您在其他地方做过 SHAP/Grad-CAM 相关的工作，这是一个很好的应用）。 - **将 SQLite 替换为 Postgres**（如果您需要并发写入的话）—— `storage/db.py` 是唯一需要更改的文件。 - **发布 MCP server**，以便其他人可以通过 `npx`/`uvx` 将其插入到他们自己的 agent 技术栈中。 ## 👤 作者 **Md. Musa Islam Fahad** CSE (Data Science) · Daffodil International University, Dhaka 📧 musa.islam.fahad@gmail.com 🌐 [个人主页](https://musaislamfahad.vercel.app) · [GitHub](https://github.com/MusaIslamFahad) · [LinkedIn](https://linkedin.com/in/md-musa-islam-fahad-b18759249) ## 📄 许可证 本项目基于 **MIT License** 授权 - 详情请见 [LICENSE](LICENSE)。 可免费使用、修改和部署。

标签：AI智能体, AI风险缓解, Kubernetes, MCP服务, 一键部署, 多智能体, 大模型安全, 红队评估, 请求拦截, 逆向工具