Tawheed30/phishing-email-analyzer

# 钓鱼邮件分析器         一款使用 Claude AI 分析原始邮件中钓鱼指标的全栈 Web 应用。粘贴任何原始邮件（headers + body），几秒钟内即可收到结构化的威胁报告，包含判定结论、置信度评分、IOC、MITRE ATT&CK 映射以及 SOC 就绪的建议。 ## 快速开始 ``` # 克隆并进入项目 git clone && cd phishing-email-analyzer # 安装 backend 依赖 cd backend && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt # 配置你的 Anthropic API key echo "ANTHROPIC_API_KEY=sk-ant-..." > .env # 启动 backend API uvicorn app.main:app --reload --port 8000 # 在一个新的 terminal 中，启动 frontend cd frontend && npm install && npm run dev ``` 打开 [http://localhost:5173](http://localhost:5173) — UI 已准备就绪。 ## 技术栈 | 层级 | 技术 | 用途 | |---------------|-----------------------------------------|-----------------------------------------------| | 前端 | React 18 + TypeScript + Vite | 具有快速 HMR 开发体验的 SPA | | 样式 | Tailwind CSS（暗黑赛博主题） | 实用优先的响应式设计 | | 后端 | FastAPI + Python 3.11 | 带有自动 OpenAPI 文档的异步 REST API | | AI 引擎 | Anthropic Claude (`claude-sonnet-4-5`) | 威胁分析和结构化 JSON 输出 | | 数据校验 | Pydantic v2 | 强制执行请求/响应 schema | | 限流 | slowapi 0.1.9 | `/analyze` 上每个 IP 10 req/min | | 邮件解析器 | Python stdlib `email` 模块 | RFC 2822 header 和 body 提取 | | 测试 | pytest-asyncio + Vitest + RTL | 跨后端和前端的 137 个测试 | ## API 参考 ### `POST /analyze` 分析原始邮件并返回结构化的威胁报告。 **请求** ``` { "raw_email": "From: ceo@evil-domain.com\nTo: cfo@company.com\n\nPlease wire $50,000 immediately." } ``` | 字段 | 类型 | 约束 | |-------------|--------|--------------------------------------| | `raw_email` | string | 10 – 500,000 字符（去除首尾空格后） | **响应 `200 OK`** ``` { "verdict": "phishing", "confidence": 94, "summary": "High-confidence BEC wire fraud attempt impersonating executive.", "red_flags": [ "SPF authentication failed", "Reply-To mismatch detected", "Urgency language: 'immediately'" ], "iocs": [ { "type": "email", "value": "ceo@evil-domain.com", "context": "Spoofed sender address mimicking executive" } ], "mitre_ttps": [ { "technique_id": "T1566.002", "technique_name": "Spearphishing Link", "tactic": "Initial Access" } ], "recommendations": [ "Quarantine and block sender domain evil-domain.com", "Alert CFO and finance team", "Report to IT security" ], "analyst_notes": "Classic BEC pattern: executive impersonation + wire transfer urgency.", "processing_time_ms": 1842, "parsed_email": { "...": "full parsed fields" } } ``` **错误响应** | 状态 | 原因 | |--------|--------------------------------------------| | `422` | 输入为空、太短或超过 500KB | | `429` | 超出速率限制（每个 IP 10 req/min） | | `503` | Anthropic API 不可用 | ### `GET /health` ``` { "status": "ok", "version": "5.0.0", "timestamp": "2025-06-05T14:32:00.000Z", "api_key_configured": true } ``` ## 部署 ### 前端 → Vercel ``` npm i -g vercel vercel --prod # run from project root — vercel.json points at frontend/ ``` **Vercel 环境变量** (`Settings → Environment Variables`)： | 变量 | 值 | |---|---| | `VITE_API_URL` | `https://your-backend.up.railway.app` | ### 后端 → Railway 1. 在 [railway.app](https://railway.app) 创建一个新项目 → **Deploy from GitHub repo** 2. 将 **Root Directory** 设置为 `backend` 3. Railway 会通过 `railway.toml` 自动检测 Python 并运行 `uvicorn` **Railway 环境变量** (`Variables` 标签页)： | 变量 | 值 | |---|---| | `ANTHROPIC_API_KEY` | `sk-ant-...`（你的真实密钥） | | `ALLOWED_ORIGINS` | `https://your-project.vercel.app` | 两者都部署完成后，在 Vercel 上将 `VITE_API_URL` 设置为 Railway 后端 URL，并重新部署前端。 ## 专为 SOC 分析员打造 此工具可加速钓鱼调查的分流（triage）阶段： **大规模分流** — 直接从您的邮件客户端或 SIEM 告警中粘贴可疑邮件。AI 会解析身份验证标头（SPF/DKIM/DMARC），提取所有 URL 和附件，并在 2 秒内标记显示名称不匹配的情况。 **结构化威胁情报** — 每次分析都会输出机器可读的 IOC（IP、域名、URL、电子邮件地址），并将对手行为映射到 MITRE ATT&CK 技术 — 随时准备导入您的威胁情报平台或事件报告。 **分析员交接就绪** — “Copy Report” 按钮可将完整分析格式化为纯文本，针对邮件会话、工单系统（Jira、ServiceNow）或 Slack 进行了优化。不再需要手动提取字段。 **历史记录与比较** — 会话中将保留最后 5 次分析，以便您可以比较同一活动的变体或重新检查之前的样本，而无需重新提交。 **典型用例：** - 一线 SOC 分析员对终端用户报告的钓鱼邮件进行分流 - 威胁狩猎：快速识别来自 SIEM 告警的可疑邮件特征 - 安全意识培训：向非技术人员展示钓鱼指标 - 事件响应：在活跃的 BEC（商业电子邮件妥协）调查期间从电子邮件中提取 IOC ## 项目结构 ``` phishing-email-analyzer/ ├── backend/ │ ├── app/ │ │ ├── main.py # FastAPI app, middleware, structured logging │ │ ├── limiter.py # slowapi rate limiter (env-configurable) │ │ ├── models/schemas.py # Pydantic request/response models │ │ ├── routers/analyze.py # POST /analyze endpoint │ │ ├── services/ │ │ │ ├── email_parser.py # RFC 2822 parser (auth headers, IOC extraction) │ │ │ └── ai_analyzer.py # Claude AI integration │ │ └── prompts/system.txt # AI system prompt for threat analysis │ ├── tests/ # 70 pytest tests │ └── requirements.txt ├── frontend/ │ ├── src/ │ │ ├── components/ # 10 React components (dark cyber UI) │ │ ├── hooks/useAnalyzer.ts # State machine: analyze, retry, history │ │ ├── services/api.ts # Typed fetch wrapper │ │ └── types/index.ts # TypeScript interfaces │ └── src/__tests__/ # 67 Vitest tests └── README.md ``` ## 环境变量 | 变量 | 默认值 | 描述 | |----------------------|-------------|----------------------------------------| | `ANTHROPIC_API_KEY` | 必填 | 您的 Anthropic API 密钥 | | `ANALYZE_RATE_LIMIT` | `10/minute` | /analyze 的 slowapi 速率限制字符串 | ## 运行测试 ``` # Backend（70 个测试） cd backend && source .venv/bin/activate && pytest tests/ -v # Frontend（67 个测试） cd frontend && npm test ``` 总计：**137 个测试** — 包括单元测试、集成测试和组件测试。 ## 许可证 MIT

标签：AV绕过, FastAPI, React, Syscalls, 人工智能, 威胁情报, 安全规则引擎, 安全运营, 开发者工具, 扫描框架, 用户模式Hook绕过, 钓鱼邮件分析