ismaellaya/SpearHead

Multi-Agent System for Spear Phishing Research & Defense

## 概述 **SpearHead** 是一个研究平台，它使用**多智能体架构**、LLM 和**Neo4j 知识图谱**，自动化完整的 OSINT 到钓鱼邮件生命周期。专门的智能体在一个 pipeline 中协作，以收集情报、描绘目标特征，并生成逼真的社会工程学模拟——使蓝队和安全研究人员能够测试并改进他们的防御。 ### 使用场景 | 模式 | 描述 | |------|-------------| | `academic` | 大学 / 机构网络安全研究 | | `red_team` | 在签署工作说明书授权下的渗透测试 | | `blue_team` | 使用逼真的钓鱼样本进行 SOC 分析师培训 | | `awareness` | 通过模拟钓鱼演练进行员工教育 | | `threat_intel` | 用于威胁建模的社会工程学 TTP 分析 | ## 架构 ``` Dashboard (Next.js :3000) └─ REST + WebSocket ──► FastAPI (src/api.py :8000) ├─ Background thread ──► run_pipeline() │ ├─ ScoutAgent — OSINT collection (10+ sources) │ ├─ ProfilerAgent — Entity extraction → Neo4j graph │ ├─ AttackAgent — RAG from graph → phishing emails (LLM) │ ├─ ReviewerAgent — Quality scoring & detector analysis │ └─ ReportingAgent — HTML/PDF report [Pro] └─ SpearDetector — Standalone email analysis endpoint ``` ## 功能 ### 智能体 - **ScoutAgent** — 跨越 10 多个来源的 OSINT：Google/DuckDuckGo（HTML 后端）、GitHub、Wayback Machine、WHOIS、DNS、crt.sh、Hunter.io、HIBP 和 Apify（Instagram、TikTok）。温度：`0.3`。 - **ProfilerAgent** — 将实体（人员、邮箱、公司、网站、位置、主题、用户名等）提取到 Neo4j 图谱中；从组织域名推断邮箱地址模式；使用 OSINT 证据丰富节点；尊重先前运行的注释。温度：`0.1`。 - **AttackAgent** — 通过 Graph RAG 使用 3 种说服角度（权威、好感、机会）为每个目标生成最多 3 个鱼叉式钓鱼变体。温度：`0.85`。 - **ReviewerAgent** — 对真实度进行 0-10 的评分，识别检测向量，并提供改进的主题/正文。温度：`0.2`。 ### 仪表盘 - 实时 WebSocket 日志控制台，支持搜索（Ctrl+F）和 2000 条记录上限 - 交互式力导向 + 径向知识图谱 - 多选模式：拖动选择节点，然后批量删除 - 图谱导出：PNG 屏幕截图、CSV（节点 + 边的压缩包）或 GEXF（兼容 Gephi） - 节点注释：已确认 / 误报 / 需要复核（持久化存储在 Neo4j 中） - 注释过滤器：显示全部 / 已确认 / 需要复核 / 误报 - 置信度过滤器：全部 / 中等及以上 (MED+) / 高 (HIGH)（Person 节点始终可见） - 直接从任何图谱节点生成邮件（右键点击 → 生成邮件） - 并排变体比较（最多 3 个攻击角度） - 委托上下文面板：组织名称、类型、已知域名、范围备注 - 深度搜索切换开关，用于扩展 OSINT 深度 - 取消 pipeline 按钮（尽力而为，在批次中处理下一个目标之前停止） - 运行历史记录，支持搜索、PDF 下载 [Pro] 和 HTML 报告查看器 - 独立的邮件钓鱼分析器（Entropy 或 AI 模式） - 全屏模式、标签切换、径向布局和缩略图 ### LLM 提供商 | 提供商 | Key 变量 | 模型变量 | 默认模型 | |----------|-------------|----------------|---------------| | Ollama (本地) | `OLLAMA_BASE_URL` | `OLLAMA_MODEL` | `llama3` | | Google Gemini | `GEMINI_API_KEY` | `GEMINI_MODEL` | `gemini-2.0-flash` | | Anthropic Claude | `ANTHROPIC_API_KEY` | `ANTHROPIC_MODEL` | `claude-sonnet-4-6` | | OpenAI | `OPENAI_API_KEY` | `OPENAI_MODEL` | `gpt-4o` | 将 `LLM_PROVIDER` 设置为 `local`、`gemini`、`claude` 或 `openai`。遇到瞬时错误时，LLM 最多重试 3 次，退避时间分别为 1 秒 / 5 秒 / 15 秒。 ### OSINT 工具 | 工具 | 需要的 Key | 发现内容 | |------|-------------|---------------| | Google / DuckDuckGo | — | 网络档案、工作履历、提及记录、会议演讲 | | GitHub | `GITHUB_TOKEN`（可选，5000 次请求/小时 vs 60次） | 公开仓库、编程语言、主题、个人简介 | | Wayback Machine | — | 存档的 URL（仅限域名目标） | | WHOIS | — | 域名注册人、注册商、日期（仅限域名目标） | | DNS | — | MX、TXT (SPF/DMARC)、A 记录（仅限域名目标） | | crt.sh | — | 通过证书透明度发现的子域名（仅限域名目标） | | HIBP（域名） | — | 组织域名的数据泄露——无需 Key | | HIBP（邮箱） | `HIBP_API_KEY`（可选，付费） | 个人邮箱泄露及粘贴查找 | | Hunter.io | `HUNTER_API_KEY`（可选，每月免费 25 次） | 企业邮箱地址和模式 | | Apify | `APIFY_API_TOKEN`（可选） | Instagram + TikTok 档案 | ## 项目结构 ``` SpearHead/ ├── src/ │ ├── agents/ # Pipeline agents │ │ ├── scout_agent.py │ │ ├── profiler_agent.py │ │ ├── attack_agent.py │ │ ├── reviewer_agent.py │ │ └── base_agent.py │ ├── core/ # Shared infrastructure │ │ ├── config.py # .env loader │ │ ├── graph_db.py # Neo4j abstraction with injection protection │ │ ├── llm_provider.py # Multi-provider LLM interface + retry │ │ ├── logger.py # WebSocket-forwarding logger │ │ ├── use_case.py # Use-case registry & prompt context │ │ └── exceptions.py # Typed exception hierarchy │ ├── tools/ # OSINT integrations │ │ ├── google_search.py │ │ ├── github_osint.py │ │ ├── hunter_search.py │ │ ├── wayback_search.py │ │ ├── whois_search.py │ │ ├── dns_lookup.py │ │ ├── crt_search.py │ │ ├── hibp_search.py │ │ └── apify_search.py │ ├── defenses/ │ │ └── detector.py # SpearDetector (entropy + keyword + AI) │ ├── api.py # FastAPI app + all REST/WS endpoints │ └── main_pipeline.py # Pipeline orchestrator ├── models/Prompts/ # LLM system prompts (YAML) ├── dashboard/ # Next.js operational dashboard (port 3000) ├── landing/ # Next.js marketing site (standalone repo) ├── results/ # Pipeline output (JSON, HTML, checkpoints) ├── docker-compose.yml # Neo4j container (also used by full-stack Compose) ├── Dockerfile # Backend image ├── requirements.txt └── .env.example ``` ## 开始使用 ### 前置条件 - **选项 A (Docker)：** Docker Desktop —— 无需其他任何要求。 - **选项 B (手动)：** Python 3.10+，Node.js 20+，Docker Desktop（用于 Neo4j）。 - 一个 LLM：本地运行的 Ollama，或者 Gemini / Claude / OpenAI 的 API Key。 ### 选项 A — Docker Compose（推荐） 最快的运行方式。主机上无需安装 Python venv 或 Node.js。 ``` git clone https://github.com/ismaellaya/SpearHead.git cd SpearAI cp .env.example .env # 编辑 .env — 设置 GEMINI_API_KEY 或调整 OLLAMA_BASE_URL docker compose up --build ``` 所有三个服务将同时启动。一旦服务健康，请打开 `http://localhost:3000`。 ``` # 停止（数据保存在 ./data/neo4j 和 ./results 中） docker compose down # 清除包括图数据在内的所有内容 docker compose down -v ``` ### 选项 B — 手动 ``` # 1. Clone git clone https://github.com/ismaellaya/SpearHead.git cd SpearAI cp .env.example .env # 2. Python 环境 python -m venv .venv source .venv/bin/activate # Linux / macOS .venv\Scripts\activate # Windows PowerShell pip install -r requirements.txt # 3. Neo4j (bolt://localhost:7687, web UI 位于 http://localhost:7474) docker-compose up -d # 4. Backend (http://localhost:8000) python -m uvicorn src.api:app --reload --host 0.0.0.0 --port 8000 # 5. Dashboard (http://localhost:3000) cd dashboard && npm install && npm run dev ``` ### 配置 将 `.env.example` 复制到 `.env` 并填写相应的值： ``` # ── Neo4j (Docker Compose 会自动覆盖 NEO4J_URI) NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=changeme # ── LLM Provider — 选择其一：local | gemini | claude | openai LLM_PROVIDER=gemini OLLAMA_BASE_URL=http://localhost:11434 OLLAMA_MODEL=llama3 GEMINI_API_KEY= GEMINI_MODEL=gemini-2.0-flash ANTHROPIC_API_KEY= ANTHROPIC_MODEL=claude-sonnet-4-6 OPENAI_API_KEY= OPENAI_MODEL=gpt-4o # ── Use case（首次运行时通过 Setup Screen 自动设置） # 可选值：academic | red_team | blue_team | awareness | threat_intel # USE_CASE= # ── 可选的 OSINT 工具（也可在运行时从 Settings 中设置） GITHUB_TOKEN= # Raises GitHub rate limit from 60 to 5 000 req/h HUNTER_API_KEY= # Hunter.io email finder (25 searches/month free) APIFY_API_TOKEN= # Apify social scraping — Instagram & TikTok profiles APIFY_ENABLED=true # Set to false to disable Apify without removing the key HIBP_API_KEY= # HIBP individual email lookup (paid key — $3.50/mo) ``` ## 首次运行 1. 打开 `http://localhost:3000`。 2. **设置屏幕** 将会出现 —— 选择您的使用场景（学术、红队、蓝队、安全意识、威胁情报）。这将自动保存到 `.env` 中，并在每个 LLM prompt 中注入适当的授权框架。 3. 主仪表盘加载。 ## 使用说明 1. 在侧边栏的文本框中输入一个或多个目标（人员姓名、邮箱地址或域名 —— 每次运行最多 10 个）。 2. 在括号中添加上下文提示以消除常见姓名的歧义： John Smith (CTO at Acme Corp based in Madrid) alice.johnson@corp.com (IT Security engineer at Corp Ltd) 3. 可选择填写 **委托上下文** 面板（组织名称、类型、已知域名、范围备注）。 4. 选择一个 pipeline 模式和攻击变体角度的数量（1-3）。 5. 点击 **运行 Pipeline** 并观察智能体控制台和知识图谱实时更新。 6. 完成后点击 **查看结果** 以查看生成的邮件及其评分和点评。 ### Pipeline 模式 | 模式 | 智能体 | 输出 | |------|--------|--------| | `full` | Scout → Profiler → Attack → Reviewer → Reporting | 邮件 + 图谱 + 报告 | | `search` | Scout → Profiler | 仅图谱（无邮件） | | `deep_search` | Scout（扩展深度） → Profiler | 更多 OSINT + 图谱 | ### 最佳实践 **对新目标的首次运行** —— 启用深度搜索并添加消除歧义的提示。在委托上下文中填写已知域名以激活 WHOIS/DNS/crt.sh 流程和邮箱模式推断。 **减少误报** —— 使用具体的消除歧义提示（职位 + 公司 + 城市），在委托上下文中设置 `scope_notes`，并使用置信度过滤器 (HIGH) 优先审查可靠的核心部分。 **注释** —— 右键点击任何节点 → 注释，以将节点标记为 `confirmed`（已确认，绿色）、`false_positive`（误报，红色）或 `needs_review`（需要复核，琥珀色）。这些设置将持久化存储在 Neo4j 中，并会被后续的 pipeline 运行所尊重：误报节点永远不会重新链接到 Person 节点，并且会被排除在 AttackAgent RAG 上下文之外。 **在新的委托之前** —— 导出图谱（FileDown → GEXF）以进行离线 Gephi 分析，然后使用 **设置 → 危险区域 → 清空数据库**（需要确认）以重新开始。 ### 恢复中断的运行 在每个完成的阶段之后都会保存检查点。通过以下方式从上一个检查点恢复： ``` POST /resume-pipeline/{run_id} ``` ## API 参考（关键 endpoint） | 方法 | Endpoint | 描述 | 速率限制 | |--------|----------|-------------|-----------| | `GET` | `/health` | 服务状态（Neo4j、LLM、Pro 功能） | — | | `GET` | `/setup-status` | 首次运行设置状态 + 可用使用场景 | — | | `POST` | `/setup` | 将选定的使用场景保存到 `.env` | — | | `POST` | `/run-pipeline` | 启动 pipeline（支持批量目标） | 5次/分钟 | | `POST` | `/resume-pipeline/{run_id}` | 从检查点恢复 | 5次/分钟 | | `POST` | `/cancel-pipeline` | 请求取消正在运行的 pipeline | — | | `GET` | `/pipeline-status` | 当前阶段 + 日志快照 | — | | `WS` | `/ws/logs` | 实时日志、状态和批处理进度 | — | | `GET/POST` | `/graph-data` | 完整图谱（节点 + 边） | — | | `POST` | `/run-query` | 执行 Cypher 查询（最多 2000 个字符） | 20次/分钟 | | `GET` | `/analytics` | 图谱指标：中心度、密度、组件 | — | | `POST` | `/analyze-email` | 独立钓鱼检测 | 10次/分钟 | | `POST` | `/generate-email/{node_id}` | 从图谱节点生成邮件 | — | | `POST` | `/nodes/{node_id}/annotate` | 注释节点 | — | | `PUT` | `/nodes/{node_id}` | 更新节点属性 | — | | `DELETE` | `/nodes/{node_id}` | 删除节点及所有关系 | — | | `POST` | `/nodes` | 创建 (MERGE) 一个新节点 | — | | `GET` | `/export-graph` | 导出为 CSV 压缩包或 GEXF (`?format=csv\|gexf`) | — | | `GET` | `/history` | 列出已保存的 pipeline 结果 | — | | `GET` | `/config/tools` | 配置了哪些可选的 API Key | — | | `POST` | `/config/tools` | 在运行时更新 OSINT API Key | — | | `POST` | `/config/tools/test` | 验证已配置的 Key（GitHub、Hunter.io、HIBP） | — | 交互式文档可在 `http://localhost:8000/docs` (Swagger UI) 获取。 **示例 —— 启动一个 pipeline：** ``` curl -X POST http://localhost:8000/run-pipeline \ -H "Content-Type: application/json" \ -d '{ "targets": ["Alice Smith (Marketing at Acme Corp)"], "mode": "full", "variations_count": 2, "detection_method": "entropy", "org_context": { "org_name": "Acme Corp", "org_type": "corporation", "known_domains": ["acme.com"], "scope_notes": "Authorized red team — signed SoW ref #2024-RT-001" } }' ``` ## SpearDetector 用于在不运行完整 pipeline 的情况下分析可疑邮件的独立模块。 ``` POST /analyze-email Content-Type: application/json {"content": "", "method": "entropy"} # method: entropy | ai ``` | 方法 | 工作原理 | 需要的 API Key | |--------|-------------|----------------| | `entropy` | 香农熵、多语言关键词匹配、链接检查、URL 重定向链 | 否 | | `ai` | 基于 LLM 的语义钓鱼模式检测 | 是（已配置的 LLM） | 速率限制：每分钟 10 次分析。 ## Pro 功能 **SpearHead Pro** 包 (`spearhead-pro`) 新增： - **HTML 报告生成** —— 每次完整 pipeline 运行会生成带有完整样式的报告：封面、资源使用情况（每个阶段的 token 数量 + 美元成本）、侦察摘要、实体图谱统计、所有带有评分和点评的生成邮件，以及缓解措施。 - **PDF 导出** —— 基于 Playwright/Chromium 的 A4 PDF 渲染；可从历史记录面板访问。 免费层级包含所有的智能体、仪表盘、知识图谱、SpearDetector、CSV/GEXF 导出、JSON 结果、运行历史记录以及所有的 OSINT 工具。 ``` # 购买后，安装 .whl 文件 pip install spearhead_pro-1.0.0-py3-none-any.whl # 验证 — /health 将显示 reports_available: true python -c "from spearhead_pro import ReportingAgent; print('Pro installed')" ``` ## 故障排除 **Neo4j 未连接** —— 运行 `docker-compose up -d` 并验证 `http://localhost:7474` 的 Web UI（凭据：`neo4j / `changeme`）。pipeline 在没有 Neo4j 的情况下会继续执行，但结果不会被持久化。 **LLM 未响应** —— 对于 Ollama：验证模型是否已拉取（`ollama pull llama3`）。对于云提供商：在 `.env` 或 设置 → LLM 配置 中检查您的 API Key。LLM 最多重试 3 次（1秒 / 5秒 / 15秒）。 **DuckDuckGo 未返回结果** —— DuckDuckGo 会对频繁的查询进行速率限制。在两次运行之间等待 30-60 秒。尝试简化目标姓名或禁用深度搜索。 **Windows 编码错误 (cp1252)** —— 在 cmd/PowerShell 中运行 `chcp 65001`，或在您的环境中设置 `PYTHONUTF8=1`。所有源文件均包含 `# -*- coding: utf-8 -*-`。 **Apify 未返回任何内容** —— 验证是否设置了 `APIFY_API_TOKEN` 并且在 设置 → OSINT 工具 中启用了 Apify。结果取决于目标档案在 Instagram/TikTok 上的可见性设置。 ## 许可证 在 [MIT 许可证](LICENSE) 下分发。© Ismael Laya

标签：DLL 劫持, ESC4, ESC8, OSINT, 多智能体, 大语言模型, 实时处理, 社会工程学, 请求拦截, 逆向工具, 鱼叉式网络钓鱼