ed1thub/PhishSense

# PhishSense PhishSense 是一个使用 Gemini 支持的 AI 生成评分和解释的 FastAPI Web 应用，具备基于规则的回退机制以保障可靠性。 ## 功能 - 使用 AI 风险评估对邮件进行 0 到 100 分的评分 - 将风险标记为低、中或高 - 显示检测到的红色警告标志 - 建议安全的下一操作 - 以 Gemini 为主提供流畅的英文解释，并在 Gemini 短暂故障或 503 时使用本地回退 - 验证用户输入并对无效负载返回字段级别的 422 错误 - 对分析请求应用每客户端速率限制 - 支持可选的管理员模式，并配备经过身份验证的操作端点 - 持久化分析历史记录（默认使用 SQLite）供管理员审查 - 提供针对桌面和移动屏幕优化的现代化响应式 Web UI ## 技术栈 - Python、FastAPI、Uvicorn - HTML、CSS、JavaScript - Google Gen AI SDK（Gemini） ## 快速开始 ``` git clone https://github.com/ed1thub/PhishSense.git cd PhishSense python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt ``` 在项目根目录创建 `.env` 文件： ``` GEMINI_API_KEY=your_gemini_api_key_here ``` 本地运行： ``` uvicorn app.main:app --reload ``` 打开 `http://127.0.0.1:8000`。 运行测试： ``` python -m pytest -q ``` ## 配置 ### 核心设置 - `GEMINI_API_KEY`：用于 AI 解释生成和主要 AI 体验的 Gemini API 密钥 - `PHISHSENSE_GEMINI_MODEL`：Gemini 模型名称（默认：`gemini-2.5-flash`） - `PHISHSENSE_LOG_LEVEL`：后端日志级别（默认：`INFO`） - `PHISHSENSE_APP_NAME`：FastAPI 应用标题，显示在 OpenAPI 文档中 - `PHISHSENSE_RATE_LIMIT_ENABLED`：启用或禁用 `POST /analyze` 的 API 速率限制（默认：`true`） - `PHISHSENSE_RATE_LIMIT_REQUESTS`：每个客户端在时间窗口内允许的最大请求数（默认：`60`） - `PHISHSENSE_RATE_LIMIT_WINDOW_SECONDS`：速率限制窗口秒数（默认：`60`） - `PHISHSENSE_ADMIN_MODE_ENABLED`：启用安全的管理端点访问（默认：`false`） - `PHISHSENSE_ADMIN_USERNAME`：`/admin` 的 HTTP 基本认证用户名 - `PHISHSENSE_ADMIN_PASSWORD`：`/admin` 的 HTTP 基本认证密码 - `PHISHSENSE_HISTORY_ENABLED`：启用保存分析历史（默认：`true`） - `PHISHSENSE_HISTORY_DB_PATH`：保存分析的 SQLite 数据库路径（默认：`phishsense_history.db`） - `PHISHSENSE_HISTORY_MAX_RESULTS`：管理员历史记录列表中返回的最大历史行数（默认：`100`） ### 评分规则配置 - 设置 `PHISHSENSE_RULES_FILE` 为 YAML 文件，或编辑 [app/scoring_rules/rules.yaml](app/scoring_rules/rules.yaml#L1) - 使用环境变量（如 `PHISHSENSE_URGENT_PATTERNS`、`PHISHSENSE_SCORE_CAP` 或 `PHISHSENSE_HIGH_RISK_THRESHOLD`）覆盖单个值 ## API ### POST /analyze 请求体： - `sender`（可选） - `subject`（可选） - `body`（必需） - `url`（可选，必须以 `http://` 或 `https://` 开头） 响应包含： - `score` - `risk_level` - `red_flags` - `rule_hits`（回退解释性详情，当使用基于规则的备份时） - `ai_explanation`（Gemini 输出；出现暂时性 Gemini 错误或故障时使用本地回退） - `recommended_action` 每个 `rule_hits` 项目包含： - `rule_id` - `signal` - `points` - `confidence`（0.0 到 1.0） - `explanation` 验证行为： - 无效输入返回 HTTP 422 - 响应包含带有字段特定错误消息的 `detail` 条目 速率限制行为： - `POST /analyze` 按客户端 IP 进行速率限制 - 超过限制将返回 HTTP 429，并附带 `Retry-After` 和 `retry_after_seconds` 管理员模式行为： - 除非 `PHISHSENSE_ADMIN_MODE_ENABLED=true`，否则 `GET /admin` 隐藏 - 启用后，`/admin` 需要 HTTP 基本认证 - `GET /admin/history` 返回最近保存的分析 - `GET /admin/history/{id}` 返回特定的保存分析条目 历史记录行为： - 当 `PHISHSENSE_HISTORY_ENABLED=true` 时保存分析 - 默认存储为位于 `PHISHSENSE_HISTORY_DB_PATH` 的 SQLite 数据库 ## 项目结构 - [app/main.py](app/main.py)：FastAPI 应用和 `/analyze` 端点 - [app/scoring_rules](app/scoring_rules)：模块化评分引擎和规则配置 - [app/ai_analysis.py](app/ai_analysis.py)：AI 解释生成与安全回退 - [app/settings.py](app/settings.py)：集中化环境/设置加载器 - [app/logging_config.py](app/logging_config.py)：日志引导 - [app/rate_limit.py](app/rate_limit.py)：内存请求节流 - [app/security.py](app/security.py)：管理员身份验证依赖项 - [app/history_store.py](app/history_store.py)：SQLite 分析历史持久化 - [app/templates/index.html](app/templates/index.html)：`/` 的主 Web UI 模板 - [static/style.css](static/style.css)：响应式设计系统和视觉样式 - [static/app.js](static/app.js)：前端交互、验证显示和 API 渲染 - [tests](tests)：评分、验证和设置测试 ## Render 部署 - 构建命令：`pip install -r requirements.txt` - 启动命令：`uvicorn app.main:app --host 0.0.0.0 --port $PORT` - 必需环境变量：`GEMINI_API_KEY`（启用主要的 Gemini 支持解释） ## 学生项目声明 本项目仅用于教育和作品集用途。 - 它不是生产级别的安全产品。 - 结果仅供参考，可能包含误报或漏报。 - 请始终通过官方渠道验证高风险消息。 ## 文档 - 完整技术文档：[DEVELOPER_README.md](DEVELOPER_README.md) - 项目结构指南：[PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) - 部署说明：[DEPLOYMENT.md](DEPLOYMENT.md) ## 许可证 本项目根据 MIT 许可证授权。参见 [LICENSE](LICENSE)。

标签：AI安全, AMSI绕过, API安全, API密钥检测, AV绕过, Chat Copilot, CMS安全, CSS, DLL 劫持, FastAPI, HTML, JavaScript, JSON输出, Python, SEO, SQLite, Uvicorn, 前端, 反钓鱼, 响应式UI, 多模态安全, 大语言模型, 威胁检测, 持久化存储, 数据可视化, 无后门, 生成式AI, 移动端优化, 管理员模式, 索引, 红队指标, 输入验证, 逆向工具, 邮件安全, 钓鱼检测, 风险评分