SabeehUrRehmanKhan/FYP-MultiChannelPhishingDetection
GitHub: SabeehUrRehmanKhan/FYP-MultiChannelPhishingDetection
一个基于 React 和 FastAPI 的多渠道钓鱼检测与安全意识培训平台，集成了 ML 分类器和模拟演练管理系统。
Stars: 0 | Forks: 0
# PhishGuard 🛡️
## 目录
1. [系统架构](#system-architecture)
2. [快速开始](#quick-start)
3. [后端设置](#backend-setup)
4. [前端设置](#frontend-setup)
5. [Supabase 设置](#supabase-setup)
6. [用户角色与权限](#user-roles--permissions)
7. [管理模拟与活动（管理员指南）](#managing-simulations--activities)
8. [API 参考](#api-reference)
9. [已修复的已知问题（QA 审计）](#qa-audit--fixes)
## 系统架构
```
┌─────────────────────────────────────────────────────────┐
│ Frontend (Vite + React + TypeScript) │
│ LoginPage → Dashboard → History → Simulations → Admin │
│ AuthContext (Supabase JWT) → FastAPI Backend │
└──────────────────────────┬──────────────────────────────┘
│ HTTP / SSE
┌──────────────────────────▼──────────────────────────────┐
│ Backend (FastAPI + Python) │
│ /auth/me /analyze /simulations /activities │
│ /history /feedback /admin /sessions │
└──────────┬───────────────────────────┬───────────────────┘
│ │
┌──────▼──────┐ ┌────────▼────────┐
│ Supabase │ │ Redis Cache │
│ (Postgres │ │ (Rate-limit, │
│ + Auth) │ │ threat cache) │
└─────────────┘ └─────────────────┘
```
### 关键组件
| 层级 | 技术 | 用途 |
|-------|------|---------|
| Frontend | React 18 + Vite + TypeScript | 带有暗黑模式 UI 的 SPA |
| Auth | Supabase Auth (email + Google OAuth) | JWT 会话，邮箱确认 |
| Backend | FastAPI (Python 3.11+) | REST + SSE 分析 API |
| Database | Supabase (PostgreSQL) | 用户资料、分析、模拟、反馈 |
| Cache | Redis | 威胁指标缓存，会话限流 |
| ML Models | Scikit-learn / custom | URL、NLP、网络、语音钓鱼分类器 |
## 快速开始
```
# 1. Clone 并打开
cd e:\phishguard\phishguard
# 2. 启动 backend
cd backend
python -m uvicorn app.main:app --reload --port 8000
# 3. 启动 frontend (单独的 terminal)
cd Frontend/PhishGuard
npm install
npm run dev
```
前端运行在 **http://localhost:5173**
后端 API 文档在 **http://localhost:8000/docs**（仅限开发模式）
## 后端设置
### 依赖要求
```
cd backend
pip install -r requirements.txt
```
### 环境变量 (`backend/.env`)
```
# Supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key # Required for admin ops
# App
APP_ENV=development # development | production
FRONTEND_URL=http://localhost:5173
# Redis
REDIS_URL=redis://localhost:6379
# ML
USE_MOCK_MODELS=true # false = load real .pkl models from ml_models/
```
### 启动服务器
```
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
## 前端设置
### 环境变量 (`Frontend/PhishGuard/.env.local`)
```
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key
VITE_API_URL=http://localhost:8000
```
### 命令
```
npm install # Install dependencies
npm run dev # Development server
npm run build # Production build
npm run preview # Preview production build
```
## Supabase 设置
### 1. 运行 Schema
进入 **Supabase Dashboard → SQL Editor → New Query**，粘贴并运行以下内容：
```
backend/supabase_schema.sql
```
这将创建所有的表、索引、行级安全策略以及自动创建用户资料的触发器。
### 2. 应用 `avatar_url` 迁移
如果你已经运行过 schema，请运行此额外的迁移：
```
-- Add avatar_url and phone columns if not already present
ALTER TABLE profiles ADD COLUMN IF NOT EXISTS avatar_url TEXT;
ALTER TABLE profiles ADD COLUMN IF NOT EXISTS phone TEXT;
-- Update the trigger to capture Google profile picture
CREATE OR REPLACE FUNCTION handle_new_user()
RETURNS TRIGGER AS $$
BEGIN
INSERT INTO profiles (id, email, display_name, avatar_url)
VALUES (
NEW.id, NEW.email,
COALESCE(NEW.raw_user_meta_data->>'full_name', NEW.raw_user_meta_data->>'name', split_part(NEW.email, '@', 1)),
COALESCE(NEW.raw_user_meta_data->>'avatar_url', NEW.raw_user_meta_data->>'picture')
)
ON CONFLICT (id) DO UPDATE SET
display_name = COALESCE(NEW.raw_user_meta_data->>'full_name', profiles.display_name),
avatar_url = COALESCE(NEW.raw_user_meta_data->>'avatar_url', NEW.raw_user_meta_data->>'picture', profiles.avatar_url),
updated_at = NOW();
RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;
```
### 3. 启用 Google OAuth（可选）
- Supabase Dashboard → Auth → Providers → Google → Enable
- 添加你的 Google OAuth Client ID 和 Secret
### 4. 邮箱确认
- Auth → Settings → **Enable email confirmations** ✅（根据你的配置已启用）
- 前端在注册后会显示一个验证横幅 —— 用户必须在登录前进行确认。
### 5. 提升首位管理员
在你的第一个用户注册后，在 SQL Editor 中运行：
```
UPDATE profiles SET role = 'admin' WHERE email = 'your-admin@email.com';
```
## 用户角色与权限
| 角色 | 人员 | 访问权限 |
|------|-----|--------|
| `user` | 所有注册用户的默认角色 | Dashboard、History、Simulations、Threat Intel |
| `moderator` | 受信任的团队成员 | 所有用户权限 + Feedback Queue + Dataset 审查 |
| `admin` | 平台管理员 | 所有权限 + 用户角色管理 + Simulation/Activity CRUD + Stats |
### 提升用户
**选项 A — SQL Editor (Supabase)**：
```
UPDATE profiles SET role = 'moderator' WHERE email = 'user@example.com';
UPDATE profiles SET role = 'admin' WHERE email = 'admin@example.com';
```
**选项 B — 管理员 UI**：
以管理员身份登录 → 管理员侧边栏 → Platform Stats →（`/admin/users` 端点中的用户管理 —— UI 将在下一个冲刺中推出）
## 管理模拟与活动
### 模拟（钓鱼场景）
位于侧边栏：**Admin → Simulations** (`/admin/simulations`)
模拟是真实的钓鱼场景，用户必须将其分类为*钓鱼*或*合法*。
**要创建一个模拟：**
1. 点击 **+ New Simulation**
2. 填写：
- **Title** — 简短名称（例如 "Suspicious PayPal Password Reset"）
- **Type** — `email`、`url`、`sms` 或 `voice`
- **Difficulty** — `beginner`、`intermediate`、`advanced`
- **Sender / From** — 伪造的发件人（例如 `support@paypa1.com`）
- **Subject** — 邮件主题行
- **URL** — 场景中显示的恶意链接
- **Body / Content** — 钓鱼信息文本
- **Explanation** — 在用户提交后显示（教授危险信号）
- **Hints** — 可选提示（每行一个），按需显示
3. 勾选 **Active** 使其对用户可见
4. 点击 **Save**
**内容示例（email 模拟）：**
```
Sender: security-alert@amaz0n.com
Subject: Action Required: Unusual sign-in detected
Body: We detected a sign-in to your Amazon account from a new device.
If this wasn't you, click here immediately to secure your account:
http://amaz0n-secure.net/verify?token=abc123
Hints: - Check the sender domain carefully
- Hover over links before clicking
Explanation: The sender domain is "amaz0n.com" — note the zero instead of 'o'.
The link also goes to a non-Amazon domain. Classic domain spoofing attack.
```
### MCQ 活动（安全意识测验）
位于侧边栏：**Admin → MCQ Activities** (`/admin/activities`)
活动是多项选择知识问答，用于巩固钓鱼防范意识概念。
**要创建一个测验：**
1. 点击 **+ New Activity**
2. 设置 Title、Type（`quiz`/`spot_the_phish`/`fill_blank`）和 Difficulty
3. 对于每个问题：
- 输入问题文本
- 填写 2–4 个答案选项
- 点击正确答案旁边的**单选按钮**
- 添加解释（在结果明细中显示）
4. 点击 **+ Add Question** 以添加更多问题
5. 勾选 **Active** 并点击 **Save Activity**
**问题示例：**
```
Question: Which of the following is a red flag in a phishing email?
Options:
○ The email is from your bank's official domain
◉ The email asks you to click a link to "verify your account immediately" ← correct
○ The email has a proper greeting with your full name
○ The email mentions your recent transaction
Explanation: Urgency language ("immediately") and credential-harvesting links
are hallmark phishing tactics.
```
### 用户进度追踪
所有模拟和活动的完成记录都存储在 `user_progress` 表中，包含：
- 获得的分数
- 提交的答案
- 完成时间戳
用户可以重新尝试活动 —— 只会存储最新的分数（upsert）。
## API 参考
### 认证
| 方法 | 端点 | 认证 | 描述 |
|--------|----------|------|-------------|
| GET | `/auth/me` | Bearer JWT | 获取当前用户资料 |
| PUT | `/auth/me` | Bearer JWT | 更新 display_name / avatar_url |
### 分析
| 方法 | 端点 | 认证 | 描述 |
|--------|----------|------|-------------|
| GET | `/analyze/stream` | Bearer JWT | SSE 流：实时钓鱼分析 |
### 模拟
| 方法 | 端点 | 认证 | 描述 |
|--------|----------|------|-------------|
| GET | `/simulations` | Bearer JWT | 列出活跃的模拟 |
| GET | `/simulations/{id}` | Bearer JWT | 获取单个模拟 |
| POST | `/simulations/{id}/complete` | Bearer JWT | 提交答案，获取分数和解释 |
| GET | `/simulations/activities/list` | Bearer JWT | 列出安全意识活动 |
| GET | `/simulations/activities/{id}` | Bearer JWT | 获取单个活动及其问题 |
| POST | `/simulations/activities/{id}/submit` | Bearer JWT | 提交测验答案 |
| GET | `/simulations/progress/me` | Bearer JWT | 我的完成历史 |
### 管理 — 模拟
| 方法 | 端点 | 认证 | 描述 |
|--------|----------|------|-------------|
| POST | `/simulations/admin/simulations` | Admin JWT | 创建模拟 |
| PUT | `/simulations/admin/simulations/{id}` | Admin JWT | 更新模拟 |
| DELETE | `/simulations/admin/simulations/{id}` | Admin JWT | 停用模拟 |
| POST | `/simulations/admin/activities` | Admin JWT | 创建活动 |
| PUT | `/simulations/admin/activities/{id}` | Admin JWT | 更新活动 |
### 历史
| 方法 | 端点 | 认证 | 描述 |
|--------|----------|------|-------------|
| GET | `/history` | Bearer JWT | 分页的分析历史 |
| GET | `/history/{id}` | Bearer JWT | 带有特征的分析详情 |
### 反馈
| 方法 | 端点 | 认证 | 描述 |
|--------|----------|------|-------------|
| POST | `/feedback` | Bearer JWT | 提交判定修正 |
| GET | `/feedback` | Moderator+ | 列出待处理的反馈 |
| PATCH | `/feedback/{id}/approve` | Moderator+ | 批准并添加到数据集 |
| PATCH | `/feedback/{id}/reject` | Moderator+ | 拒绝反馈 |
### 管理
| 方法 | 端点 | 认证 | 描述 |
|--------|----------|------|-------------|
| GET | `/admin/stats` | Admin | 全平台统计 |
| GET | `/admin/users` | Admin | 列出所有用户 |
| PATCH | `/admin/users/{id}/role` | Admin | 更改用户角色 |
| GET | `/admin/threat-indicators` | Admin | 所有威胁指标 |
| PATCH | `/admin/threat-indicators/{id}/verify` | Admin | 验证/取消验证指标 |
## QA 审计与修复
此版本中识别并修复了以下 bug：
| # | Bug | 状态 |
|---|-----|--------|
| 1 | 注册表单缺少 `display_name` / Full Name 字段 | ✅ 已修复 |
| 2 | 注册后没有邮箱验证横幅 | ✅ 已修复 |
| 3 | `signUpWithEmail` 未将元数据传递给 Supabase | ✅ 已修复 |
| 4 | 用户资料 schema 和 TS 类型中缺少 `avatar_url` | ✅ 已修复 |
| 5 | 没有 `/auth/me` 后端端点（每次加载均返回 404） | ✅ 已修复 |
| 6 | 模拟页面始终为空（API key 不匹配 `simulations` 与 `items`） | ✅ 已修复 |
| 7 | 前端完全缺少 Activities/MCQ 标签页 | ✅ 已修复 |
| 8 | 侧边栏中未显示 Google OAuth 头像 | ✅ 已修复 |
| 9 | 没有用于创建/编辑模拟和活动的管理员 UI | ✅ 已修复 |
### 需要数据库迁移
如果你已经有一个现有数据库，请运行上方 Supabase 设置部分中显示的 `avatar_url` 迁移 SQL。
## 项目结构
```
phishguard/
├── backend/
│ ├── app/
│ │ ├── api/routes/
│ │ │ ├── auth.py ← NEW: /auth/me endpoint
│ │ │ ├── analyze.py SSE streaming analysis
│ │ │ ├── simulations.py Simulations + Activities
│ │ │ ├── admin.py Admin management
│ │ │ ├── history.py
│ │ │ ├── feedback.py
│ │ │ └── dataset.py
│ │ ├── auth/
│ │ │ └── dependencies.py JWT validation + role guards
│ │ ├── schemas/
│ │ │ └── all.py Pydantic models (UserProfile + avatar_url)
│ │ ├── db/supabase_client.py
│ │ ├── cache/redis_client.py
│ │ └── main.py
│ ├── ml_models/ Trained .pkl classifier files
│ ├── supabase_schema.sql Full DB schema + RLS policies
│ └── requirements.txt
│
└── Frontend/PhishGuard/
└── src/
├── contexts/
│ └── AuthContext.tsx ← FIXED: displayName, avatar_url, email confirm
├── pages/
│ ├── LoginPage.tsx ← FIXED: Name field, verification banner
│ ├── SimulationsPage.tsx ← FIXED: Tabbed Simulations + MCQ Activities
│ ├── DashboardPage.tsx
│ ├── HistoryPage.tsx
│ ├── ThreatIntelPage.tsx
│ └── admin/
│ ├── AdminStatsPage.tsx
│ ├── AdminFeedbackPage.tsx
│ ├── AdminDatasetPage.tsx
│ ├── AdminSimulationsPage.tsx ← NEW: Simulation CRUD
│ └── AdminActivitiesPage.tsx ← NEW: MCQ Quiz CRUD
├── components/
│ ├── layout/
│ │ ├── Sidebar.tsx ← FIXED: Shows avatar photo, email, new admin links
│ │ └── AppLayout.tsx
│ └── ui/UIComponents.tsx
└── lib/
├── api.ts ← FIXED: Simulations response adapter
├── supabase.ts ← FIXED: avatar_url in UserProfile type
└── sse.ts
```
*PhishGuard v4.2.0 — QA 发布版*
标签：AV绕过, FastAPI, JWT, PostgreSQL, Python, React, Redis, Supabase, Syscalls, TypeScript, Vite, Web安全, 后端开发, 大学毕业设计, 威胁分析, 安全插件, 搜索引擎查询, 数据库, 无后门, 模拟演练, 测试用例, 管理后台, 系统架构, 缓存, 网络安全, 自动化侦查工具, 蓝队分析, 逆向工具, 钓鱼攻击防护, 隐私保护