barvhaim/ThreatXtension

## 概述 **ThreatXtension** 是一款用于 Chrome 浏览器扩展的综合性安全分析工具。它结合了静态分析（SAST）、威胁情报（VirusTotal）以及 AI 驱动评估，帮助安全研究人员、恶意软件分析师和浏览器安全团队识别浏览器扩展中的恶意行为。 ## 功能特性 ### 多层分析 - **权限分析**：对清单权限和主机访问进行风险评估 - **SAST 扫描**：针对银行欺诈、凭证窃取、数据外泄的定制 Semgrep 规则 - **VirusTotal 集成**：对文件哈希值进行声誉检查，覆盖 70 多家反病毒引擎 - **熵分析**：使用香农熵和模式匹配检测混淆/打包代码 - **WebStore 信誉**：用户评分、开发者信息与可信信号 ### AI 驱动的威胁评估 - **执行摘要**：自然语言风险评估与可操作建议 - **多 LLM 支持**：OpenAI、WatsonX、Ollama、RITS - **上下文感知分析**：每个发现均基于扩展完整上下文进行分析 ### 多界面支持 - **Web UI**：React 前端，实时分析仪表盘 - **CLI**：快速的命令行分析，丰富控制台输出 - **REST API**：FastAPI 后端，附带 OpenAPI 文档 - **MCP 服务器**：通过模型上下文协议集成 Claude Desktop ## 快速启动（Docker） 运行 ThreatXtension 最快的方式是使用 Docker。 ``` # 克隆仓库 git clone https://github.com/barvhaim/ThreatXtension.git cd ThreatXtension # 配置环境 cp .env.example .env # 编辑 .env 并添加您的 OPENAI_API_KEY（必需） # 可选添加 VIRUSTOTAL_API_KEY 以获取威胁情报 # 构建并运行 docker compose up --build # 访问应用程序 # Web UI: http://localhost:8007 # API 文档: http://localhost:8007/docs ``` ### Docker 命令 ``` make docker-build # Build container make docker-up # Start container (foreground) make docker-down # Stop container make docker-logs # View logs ``` ### 扫描扩展 **通过 Web UI：** 访问 http://localhost:8007，然后执行以下任一操作： - 粘贴 Chrome Web Store 的网址 - 输入扩展 ID（32 位字符串，例如 `gbbilodpoldeopifonmibfboicpafpjo`） - 上传本地的 `.crx` 或 `.zip` 文件 **通过 API：** ``` # 选项 1：从 Chrome Web Store URL 扫描 curl -X POST http://localhost:8007/api/scan/trigger \ -H "Content-Type: application/json" \ -d '{"url": "https://chromewebstore.google.com/detail/extension-name/extension-id"}' # 选项 2：使用扩展 ID 扫描（从 chrome-stats.com 下载） curl -X POST http://localhost:8007/api/scan/trigger \ -H "Content-Type: application/json" \ -d '{"url": "gbbilodpoldeopifonmibfboicpafpjo"}' # 选项 3：上传并扫描本地文件 curl -X POST http://localhost:8007/api/scan/upload \ -F "file=@/path/to/extension.crx" # 获取结果 curl http://localhost:8007/api/scan/results/{extension_id} ``` ## 安装（本地开发） ### 前置条件 - **Python 3.11+** - **Node.js 20+**（用于前端） - **uv** 包管理器（[安装指南](https://docs.astral.sh/uv/getting-started/installation/)） ### 设置 ``` # 克隆仓库 git clone https://github.com/barvhaim/ThreatXtension.git cd ThreatXtension # 安装 Python 依赖 uv sync # 安装前端依赖 cd frontend && npm install && cd .. # 配置环境 cp .env.example .env # 使用 API 密钥编辑 .env ``` ### 本地运行 ``` # 选项 1：CLI - 从 Chrome Web Store URL 分析 make analyze URL=https://chromewebstore.google.com/detail/example/abcdef # 选项 1b：CLI - 使用扩展 ID 分析 uv run threatxtension analyze --id gbbilodpoldeopifonmibfboicpafpjo # 选项 1c：CLI - 分析本地文件 uv run threatxtension analyze --file /path/to/extension.crx uv run threatxtension analyze --file /path/to/extension.zip # 选项 2：Web UI（在独立终端中运行） make api # Start FastAPI backend (port 8007) make frontend # Start React frontend (port 5173) ``` ## 配置 ### 环境变量 从模板创建 `.env` 文件： ``` cp .env.example .env ``` **必需：** ``` LLM_PROVIDER=openai LLM_MODEL=gpt-4o OPENAI_API_KEY=sk-... ``` **可选：** ``` VIRUSTOTAL_API_KEY=... # For threat intelligence CHROMESTATS_API_KEY=... # For extension ID downloads via chrome-stats.com LANGSMITH_API_KEY=... # For LLM tracing/debugging ``` ### 支持的 LLM 提供商 | 提供商 | LLM_PROVIDER | 推荐模型 | |--------|--------------|----------| | OpenAI | `openai` | `gpt-4o`, `gpt-4-turbo` | | WatsonX（IBM） | `watsonx` | `meta-llama/llama-3-3-70b-instruct` | | Ollama（本地） | `ollama` | `llama3`, `mistral` | | RITS（IBM 研究） | `rits` | `meta-llama/llama-3-3-70b-instruct` | ### 自定义 Semgrep 规则 位于 `src/threatxtension/config/custom_semgrep_rules.yaml`： | 规则 ID | 类别 | 描述 | |---------|------|------| | `banking.form_hijack.submit_intercept` | 表单劫持 | 表单提交拦截 | | `banking.cred_sniff.password_input_hooks` | 凭证窃取 | 密码字段监听器 | | `banking.ext.webrequest.redirect` | 网络劫持 | WebRequest 重定向滥用 | | `banking.exfil.generic_channels` | 数据外泄 | sendBeacon/Image.src 滥用 | | `banking.obfuscation.eval_newfunc` | 代码注入 | eval()/Function() 执行 | 所有规则均包含 MITRE ATT&CK 映射和 CWE 参考。 ## API 参考 | 端点 | 方法 | 描述 | |------|------|------| | `/api/scan/trigger` | POST | 触发扩展扫描 | | `/api/scan/status/{id}` | GET | 检查扫描状态 | | `/api/scan/results/{id}` | GET | 获取完整结果 | | `/api/scan/files/{id}` | GET | 列出提取的文件 | | `/api/scan/file/{id}/{path}` | GET | 获取文件内容 | | `/api/scan/report/{id}` | GET | 生成 PDF 报告 | | `/api/statistics` | GET | 聚合统计 | | `/api/history` | GET | 扫描历史 | | `/health` | GET | 健康检查 | 完整的 API 文档请访问 http://localhost:8007/docs ## Claude Desktop 集成（MCP） ThreatXtension 通过 MCP（模型上下文协议）集成到 Claude Desktop。 **设置步骤：** 1. 编辑 Claude Desktop 配置文件（`~/Library/Application Support/Claude/claude_desktop_config.json`）： ``` { "mcpServers": { "ThreatXtension": { "command": "uv", "args": [ "--directory", "/absolute/path/to/ThreatXtension", "run", "python", "-m", "threatxtension.mcp_server.main" ] } } } ``` 2. 重启 Claude Desktop 3. 询问 Claude：*“分析这个 Chrome 扩展：https://chromewebstore.google.com/detail/...”* ## 架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ ThreatXtension │ ├─────────────────────────────────────────────────────────────┤ │ Interfaces │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ CLI │ │ Web UI │ │ API │ │ MCP │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │ └────────────┴────────────┴────────────┘ │ │ │ │ │ ┌──────────────────────▼──────────────────────┐ │ │ │ LangGraph Workflow │ │ │ │ Download → Parse → Analyze → Summarize │ │ │ └──────────────────────┬──────────────────────┘ │ │ │ │ │ ┌──────────────────────▼──────────────────────┐ │ │ │ Analyzers │ │ │ │ ┌────────────┐ ┌────────────┐ ┌──────────┐ │ │ │ │ │Permissions │ │ SAST │ │ WebStore │ │ │ │ │ └────────────┘ └────────────┘ └──────────┘ │ │ │ │ ┌────────────┐ ┌────────────┐ │ │ │ │ │VirusTotal │ │ Entropy │ │ │ │ │ └────────────┘ └────────────┘ │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────▼──────────────────────┐ │ │ │ LLM Summary Generation │ │ │ │ (OpenAI / WatsonX / Ollama) │ │ │ └─────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## 许可证 本项目采用 MIT 许可证授权 - 详细信息请参见 [LICENSE](LICENSE) 文件。 ## 感谢 - **Semgrep** - 静态分析引擎 - **LangGraph** - 工作流编排 - **VirusTotal** - 威胁情报 - **React + Vite** - 前端框架

专为浏览器安全研究与扩展威胁情报而构建

_{本工具仅限合法的安全研究、恶意软件分析与教育用途。}