jryan5150/gone-phishing

# Gone-Phishing [](LICENSE) [](https://www.python.org/) [](https://fastapi.tiangolo.com/) [](#tests) **一个面向 MSP 的、由 AI 驱动的事件响应计划引擎。** 该引擎接收自由文本的事件描述，通过语义搜索将其与符合 NIST 800-61 标准的预案进行匹配，并生成一个包含角色分配、时间限制以及监管通知要求的行动计划。具备跨四个 LLM 提供商的 BYOM 适配器架构，集成了 ConnectWise + N8N，并包含一个拥有 60 个测试用例的场景语料库。 ## 为什么会有这个项目 当 MSP 的客户遭遇安全事件时 —— 比如点击了钓鱼邮件、检测到勒索软件、凭据被盗用 —— 响应质量完全取决于谁接手了这个工单。NIST 800-61 标准虽然存在，但在应对活跃事件时，没人会去翻开那份长达 79 页的 PDF。监管合规的时间窗口（如 HIPAA 的 60 天，PCI-DSS 的 72 小时，各州的数据泄露法律）非常紧迫且极易错过。ConnectWise 工单只记录了*发生了什么*，却无法指导*下一步该做什么、按什么顺序、由谁来做*。 **核心痛点在于：** 缺乏一个能够连接“报告事件”和“提供带有角色分配和监管期限的有序行动计划”的工具。 这就是你需要的工具，而且它是开源的，任何 MSP 都可以运行它。 ## 工作原理 ``` incident description → ChromaDB semantic search → LLM action plan (NIST-aligned playbooks) (role-assigned + time-bound + regulatory) ``` 1. 将符合 NIST 800-61 标准的预案以 Markdown 格式放入 `playbooks/` 目录 —— 它们会在启动时自动导入 ChromaDB 2. 向 `/api/incident` POST 一段自由文本的事件描述 3. 语义搜索会选择最相关的预案 4. LLM（由你选择 —— Anthropic, OpenAI, Gemini 或本地 Ollama）将生成一个带有角色分配、时间表和监管标记的优先行动清单 5. 在 `/api/chat` 的后续聊天会保留事件上下文，用于解答调查过程中的问题 6. 可选操作：通过内置的 cw-mcp 工具触发 ConnectWise 工单操作，或触发 N8N webhooks 进行升级上报 ## 技术栈 | 层级 | 技术 | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | API | FastAPI (Python 3.11+) | | 向量数据库 | ChromaDB (余弦相似度, sentence-transformers) | | LLM | **BYOM** — Anthropic Claude / OpenAI GPT-4o / Google Gemini / local Ollama (Llama 3.1, Phi-3, 等) | | 聊天 UI | 内置（单文件暗色主题），或 Chainlit，或 Open WebUI，或 Gradio | | 集成 | ConnectWise Manage (通过 [cw-mcp](https://github.com/jryan5150/cw-mcp-server)), N8N webhooks | | 测试 | 60 个 pytest 测试，涵盖 API 契约、集成生命周期、搜索排名、适配器注册表、语料库完整性 | ## 独特之处 **大多数“AI 安全自动化”工具都硬编码了单一的提供商和固定的预案分类体系。本项目则完全反转了这两点：** - **BYOM (自带模型)** —— LLM 是可以替换的。生产环境使用 Claude，开发环境使用 Ollama，合规环境使用任何已获批准的模型。适配器模式强制执行统一的接口；在启动时就会拒绝错误的提供者，而不是在请求时才报错 - **预案是 Markdown，而不是配置文件** —— 将 `.md` 文件放入 `playbooks/`，访问 `/api/ingest`，即可实现搜索。你可以像添加文档一样，用同样的方式添加客户特定的合规预案 - **语义搜索，而非分类** —— 事件描述不需要使用准确的专业词汇。*"用户点击了一个可疑链接，现在他们的 Outlook 正在向联系人发送电子邮件"* 会自动找到凭据泄露和钓鱼相关的预案，无需技术人员事先对事件进行分类 - **包含 2,000 个事件场景语料库** —— 程序化生成，基于 MITRE ATT&CK 种子，可通过 `--seed` 保证输出确定性。可用于沙盘推演、评估数据集、差距分析或演示。该数据拥有对应的生成器 (`scripts/generate_scenarios.py`)，而不是一个神秘的数据团 - **测试验证的是行为，而非语法** —— *"勒索软件查询是否将勒索软件预案排在第一位？"* 是一个测试。*"此函数是否返回 dict？"* 则不是。 - **在开发过程中融入了安全审查** —— 通过 prompt 注入进行的 XSS 攻击（已拦截）、错误消息泄露（已拦截）、速率限制（已添加）、安全响应头（已设置）。历史提交记录展示了完整的审计过程。 ## 快速开始 ``` git clone https://github.com/jryan5150/gone-phishing.git cd gone-phishing # 安装 pip install -r requirements.txt # 配置 cp .env.example .env # 编辑 .env — 至少设置你的 LLM 提供商的 API key # 运行 cd server python app.py # → http://localhost:8100 ``` 服务器在启动时会自动导入预案。打开 `http://localhost:8100` 访问内置的聊天 UI，或使用 `POST /api/incident` 进行编程调用。 ## BYOM — 自带模型 在 `.env` 中设置 `LLM_PROVIDER`： ``` LLM_PROVIDER=anthropic # Claude (default; ANTHROPIC_API_KEY) LLM_PROVIDER=openai # GPT-4o (OPENAI_API_KEY) LLM_PROVIDER=gemini # Gemini 1.5 Pro (GEMINI_API_KEY) LLM_PROVIDER=ollama # Local models (OLLAMA_HOST + OLLAMA_MODEL) ``` 对于 Ollama，请先拉取你的模型：`ollama pull llama3.1:8b`。适配器验证会在启动时进行 —— 错误的提供者名称会迅速报错，而不是在处理第一个事件时才失败。 ## 聊天 UI 选项 | 选项 | 设置 `CHAT_UI=` | 安装 | 说明 | | ---------- | -------------- | ---------------------- | ----------------------------------------------------------- | | 内置 | `builtin` | 无需额外依赖 | 位于 `/` 的单文件暗色主题 UI | | Chainlit | `chainlit` | `pip install chainlit` | 位于 `/chat` 的生产级聊天 UI (挂载到 FastAPI) | | Open WebUI | — | Docker container | 完整的 AI 平台 (通过 API 连接) | | Gradio | — | `pip install gradio` | 快速演示界面 | 查看 [docs/WIRING.md](docs/WIRING.md) 了解每个选项的分步设置。 ## API | 接口 | 方法 | 说明 | | ---------------- | ------ | ------------------------------------ | | `/api/incident` | POST | 提交事件 → 获取行动计划 | | `/api/chat` | POST | 在聊天上下文中的后续问题 | | `/api/search` | POST | 直接的预案语义搜索 | | `/api/playbooks` | GET | 列出所有已导入的预案 | | `/api/ingest` | POST | 重新导入预案文件 | | `/api/health` | GET | 服务器健康状况 (含依赖检查)| ## 项目结构 ``` gone-phishing/ ├── server/ │ ├── app.py # FastAPI server + chat UI mounting │ ├── config.py # Centralised config with startup validation │ ├── vector_store.py # ChromaDB ingestion + semantic search │ ├── llm.py # Action plan generation (provider-agnostic) │ ├── cl_app.py # Chainlit integration (optional) │ │ │ ├── adapters/ # BYOM — Bring Your Own Model │ │ ├── base.py # Abstract adapter interface │ │ ├── anthropic_adapter.py │ │ ├── openai_adapter.py │ │ ├── gemini_adapter.py │ │ └── ollama_adapter.py │ │ │ └── tools/ # MCP tool modules │ ├── irp_tools.py # Core IRP (search, plan, list) │ ├── cw_tools.py # ConnectWise Manage (via cw-mcp) │ └── n8n_tools.py # N8N webhook triggers │ ├── tests/ # 60 tests — API, integration, data, adapters ├── scripts/ │ └── generate_scenarios.py # Procedural scenario generator (pure Python) ├── playbooks/ # Drop .md files here → auto-ingested │ ├── ransomware.md phishing.md data-breach.md bec.md ... ├── web/index.html # Built-in chat UI ├── data/ │ ├── scenarios.json # 2,000 generated incident scenarios │ └── chroma/ # ChromaDB persistence (.gitignored) ├── docs/WIRING.md # Setup: chat UIs, CW MCP, N8N, LLM providers ├── pyproject.toml ├── .env.example └── requirements.txt ``` ## 测试 ``` pip install pytest httpx pytest tests/ -v ``` 跨 5 个模块的 **60 个测试**： | 模块 | 测试数 | 涵盖范围 | | ---------------------- | ----- | ---------------------------------------------------------------------------- | | `test_api.py` | 23 | 接口契约、验证、搜索排名、幂等导入 | | `test_integration.py` | 8 | 完整的请求生命周期、上下文传递、重新导入的安全性、错误传播 | | `test_vector_store.py` | 9 | 分块逻辑、重叠正确性、搜索质量、跳过规则 | | `test_adapters.py` | 5 | BYOM 注册表、未知提供者拒绝、ABC 强制执行 | | `test_scenarios.py` | 15 | 语料库完整性、分布情况、MITRE 覆盖范围、生成器可复现性 | 测试验证的核心行为： - **搜索排名**：勒索软件查询 → 勒索软件预案排名第一（而不是钓鱼攻击） - **多轮对话**：搜索上下文使用最新的用户消息，而不是第一条 - **幂等导入**：重新导入产生完全相同的分块数量 - **错误传播**：LLM 故障 → 包含信息的干净 500 错误，而不是堆栈跟踪 - **数据完整性**：所有搜索结果都包含元数据，没有空内容 - **生成器确定性**：相同的 `--seed` → 产生完全一致的场景输出 ## 场景语料库 `data/scenarios.json` 包含跨 10 个类别的 2,000 个程序化生成的事件场景，这些场景基于 MITRE ATT&CK 技术、真实世界的违规模式和 MSP 特定环境生成。 使用以下命令重新生成： ``` python scripts/generate_scenarios.py --seed 42 --output data/scenarios.json ``` 可用于沙盘推演、LLM 微调/评估数据集、预案差距分析或演示。 ## 添加预案 将任何 `.md` 文件放入 `playbooks/` 并 `POST /api/ingest`。系统会将其分块、嵌入并使其可被搜索。建议的结构： ``` # [事件类型] ## 严重程度指标 - ... ## 遏制步骤 1. ... ## 调查步骤 1. ... ## 通知要求 - HIPAA: ... - State breach laws: ... - PCI-DSS: ... ## 恢复步骤 1. ... ``` 语义匹配器不要求严格遵循此结构 —— 但一致的结构能提高分块质量和搜索相关性。 ## ConnectWise + N8N 集成 IRP 引擎将操作委托给你现有的 **cw-mcp** 服务器进行工单操作，并触发 **N8N** 的 webhooks 进行上报链处理。**两者都是可选的** —— 引擎可以完全独立运行。 如果你所在的 MSP 正在使用 ConnectWise：内置的 `cw_tools.py` 可以读取与事件相关的工单、创建响应计划工单，并随着行动计划的推进更新工单状态。查看 [docs/WIRING.md](docs/WIRING.md) 了解完整配置。 如果你使用 N8N 进行编排：`n8n_tools.py` 中的 webhook 触发器会在计划生成、上报阈值触发和监管截止日期临近时被激活。你可以将它们连接到你的团队正在使用的任何上报链中。 ## 开发历史 本项目是通过 AI 编排的开发方式在公开环境中构建的 —— 在移动端进行头脑风暴和原型设计，然后转移到桌面端进行并行 Agent 执行。每个阶段都交付了一个连贯的切片；下面的提交链接指向了对应的时刻。 | 阶段 | 内容 | 提交 | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | **基础设施** | IRP 引擎，BYOM 适配器，CW MCP 客户端，预案导入，聊天 UI | [`283e870`](../../commit/283e870) | | **代码质量审计** | 修复了配置重复，移除了死代码，单例 ChromaDB 客户端，统一使用 pathlib | [`39d9ec9`](../../commit/39d9ec9) | | **运维强化** | 启动配置验证（缺少密钥时快速失败），包含依赖验证的真实健康检查，符合 CORS 规范 | [`5efcb04`](../../commit/5efcb04) | | **适配器埋点** | 所有 LLM 调用的日志（模型、延迟、token 数），修复了 Gemini SDK 的 bug（system_instruction 位置错误) | [`3581961`](../../commit/3581961) | | **前端安全** | 用 marked.js 替换了正则表达式 markdown，添加了 DOMPurify 以防止通过 LLM 提示注入引发的 XSS | [`7486c92`](../../commit/7486c92) | | **文档清理** | IRP 模板来源的适当归属，去除了泄露的章节编号，移除了不存在功能的文档 | [`5b45e3a`](../../commit/5b45e3a) | | **数据来源** | 程序化场景生成器（纯 Python，带种子，10 个类别，MITRE ATT&CK，20 种勒索软件变体） —— 数据现在有了生成器，不再是神秘的数据团 | [`520b2b5`](../../commit/520b2b5) | | **测试套件** | 60 个测试：API 契约、集成生命周期、搜索排名质量、适配器注册表、语料完整性、生成器确定性 | [`fbc3834`](../../commit/fbc3834) | | **项目结构** | pyproject.toml，规范的包布局，带有测试文档的 README，免费层级 LLM 使用指南 | [`35797cc`](../../commit/35797cc) | | **安全审查** | 速率限制，安全响应头，通用错误消息（无内部细节泄露），XSS 防护 | [`f06ad9b`](../../commit/f06ad9b) | ## 相关工作 - **姊妹案例研究：** [事件响应预案引擎](https://github.com/jryan5150/portfolio/tree/main/case-studies/incident-response-playbook) —— 附带项目背景的完整架构论述 - **MCP 服务器关联项目：** [cw-mcp-server](https://github.com/jryan5150/cw-mcp-server) —— 包含 73 个工具的 ConnectWise Manage MCP 服务器 (由 `cw_tools.py` 调用) - **方法论：** 用于构建项目的 [四层上下文架构](https://github.com/jryan5150/claude-harness-starter) —— 根据变化频率分离的 身份 / 规则 / 记忆 / 项目 层 - **生产运行时同类项目：** esexpress-v2 中的哨兵层 —— 相同的神经科学基础（带有反馈的自适应信任评分），不同的应用体现（安全防御 vs 事件预案引擎） ## 贡献 欢迎提交 Issue 和 PR。特别欢迎以下方向： - 更多符合 NIST 800-61 标准的预案（不同垂直行业 —— 医疗、金融、法律、制造） - 新的 BYOM 适配器（Anthropic Bedrock, Mistral，自定义 OpenAI 兼容接口） - 合规包贡献（特定州的数据泄露通知要求，特定行业的框架） - 测试语料库扩展（更多的 MITRE 技术覆盖，特定行业的场景） 在贡献之前：请阅读 [docs/WIRING.md](docs/WIRING.md) 了解完整的集成面。如果你计划进行重大更改，请先提交 Issue 讨论 —— 以保持讨论公开透明。 ## 许可证 MIT —— 见 [LICENSE](LICENSE)。可自由 Fork。无需署名，但如能注明将不胜感激。 *由 [Jace Ryan](https://github.com/jryan5150) 构建，献给那些厌倦了在凌晨 2 点翻开 NIST 800-61 PDF 的 MSP 从业者。*

标签：AI风险缓解, Anthropic, API服务, AV绕过, BYOM, ChromaDB, CIS基准, ConnectWise, DLL 劫持, FastAPI, FTP漏洞扫描, Gemini, HIPAA, IRP, IT安全, IT管理, LLM, LLM评估, MIT开源许可, MSP, N8N, NIST 800-61, Object Callbacks, Ollama, OpenAI, PCI-DSS, Python, RAG, Unmanaged PE, 人工智能, 内存规避, 凭据泄露, 勒索软件, 合规监管, 向量数据库, 响应计划, 大语言模型, 安全剧本, 安全编排, 安全规则引擎, 安全运营, 托管服务提供商, 扫描框架, 无后门, 用户模式Hook绕过, 系统集成, 网络调试, 网络钓鱼, 自动化, 自带模型, 语义搜索, 逆向工具