Sangamesh-dev/SpearSim
GitHub: Sangamesh-dev/SpearSim
这是一个 AI 驱动的钓鱼模拟平台，用于安全培训和 GDPR 合规管理。
Stars: 0 | Forks: 0
https://github.com/user-attachments/assets/9bf20a6c-b421-4383-8ddd-5d6aa9db87d1
# 箭鱼模拟器
基于 FastAPI、React、Groq LLaMA3、SendGrid 和 Supabase 构建。模拟针对您自己组织的真实钓鱼攻击，跟踪行为反应，生成由 AI 驱动的修复建议，并强制执行完全的 GDPR 合规性——所有功能均通过单一平台提供。
[](https://fastapi.tiangolo.com)
[](https://reactjs.org)
[](https://supabase.com)
[](https://groq.com)
[](LICENSE)
## 目录
- [概述](#overview)
- [架构](#architecture)
- [系统流程](#system-flow)
- [功能](#features)
- [GDPR 合规性](#gdpr-compliance)
- [技术栈](#tech-stack)
- [本地设置](#local-setup)
- [环境变量](#environment-variables)
- [API 参考](#api-reference)
- [项目结构](#project-structure)
- [道德使用免责声明](#ethical-use-disclaimer)
## 概述
SpearSim 使安全团队能够针对其自己的员工运行授权的钓鱼模拟。它使用 Groq 提供的 LLaMA3 生成个性化的钓鱼邮件，实时跟踪邮件打开/点击/凭证输入事件，并为任何中招的员工展示一个安全意识培训界面。该平台以隐私优先为构建原则——永不存储真实的员工凭证，所有员工数据均经过假名化处理，并且每一个操作都为了 GDPR 第 30 条合规性而记录在案。
**关键差异化功能：**
- 基于 LLM 的、根据员工角色个性化的鱼叉式钓鱼邮件
- 完整的 GDPR 合规性门控——没有合法依据和签署的 PDF 授权书，模拟活动无法启动
- 实时钓鱼事件跟踪，为每位员工生成风险评分
- 钓鱼揭示后的安全意识培训测验——衡量实际学习效果
- 基于员工行为的、由 AI 生成的个性化修复建议
- 90 天自动数据保留策略，由每日清理 Edge Function 执行
## 架构
## 系统流程
---
## 功能
### 活动管理
- **3 步活动向导** —— 设置、CSV 上传、GDPR 同意与启动
- **活动备注** —— 每个活动的内部上下文字段
- **邮件预览** —— 在发送前生成并审核一封示例钓鱼邮件
- **重发邮件** —— 为尚未互动的员工重试发送
- **删除活动** —— 级联删除所有相关的事件和员工数据
- **标记完成** —— 手动关闭活跃的活动
### LLM 驱动的钓鱼邮件
- 使用 **Groq LLaMA3-70B** 为每位员工生成个性化邮件
- 角色感知内容——给人力资源经理和软件工程师的邮件风格不同
- 5 种场景类型：**IT 支持、人力资源、财务、CEO 欺诈、供应商**
- 3 个难度等级：**低**（明显的危险信号）、**中**（细微的）、**高**（令人信服的）
- 批量生成，对每位员工的失败进行优雅处理
### 实时跟踪
- **打开跟踪** —— 在 `/track/open/{uuid}` 提供 1×1 像素 GIF
- **点击跟踪** —— 重定向端点记录点击，然后转发至安全意识页面
- **凭证跟踪** —— 仅为布尔事件标志，零凭证存储
- **防重复** —— 防重逻辑防止每位员工被重复计数
### 安全意识培训与测验
- 钓鱼揭示后的安全意识屏幕显示特定于场景的**危险信号**
- 揭示屏幕后有一个 **3 个问题的安全意识测验**
- 每个问题单独计分，并提供正确答案反馈
- 测验成绩存储在 `quiz_results` 表中
- 活动仪表板上显示**测验完成率**和**平均分**
### 报告与分析
- **活动报告**，包含打开率、点击率、凭证率、风险评分
- 行业基准比较（32% 基线）
- **每位员工的风险等级** —— 根据采取的行动分为 低 / 中 / 高
- 通过 Groq 为每位员工生成 **AI 驱动的修复建议**
- 员工明细表中可展开的修复建议行
- 可按别名、角色、已打开、已点击、已输入凭证、风险排序的员工表
- 通过 ReportLab 导出 **PDF 报告**
- **CSV 报告**导出，包含完整明细
### 仪表板
- 统计概览——总活动数、活跃活动数、目标员工数、平均风险评分
- 按名称、组织或状态**搜索和筛选**活动
- 带动画加载指示器的**手动刷新**按钮
- **自动刷新**（30 秒）——仅在存在活跃活动时激活，无活跃活动时自动禁用
- **后端离线检测** —— 当后端不可达时显示横幅，暂停轮询
### GDPR 合规性仪表板
- 每个活动的合法依据跟踪
- 删除权——支持别名级别的数据删除，并提供删除收据 PDF
- 保留期限倒计时——当数据将在 < 14 天后过期时显示警告横幅
- 完整的审计日志查看器——分页显示，可按操作类型筛选
- 活跃活动保留期监控器
### 组织管理
- **创建组织弹窗** —— 在创建新活动流程中内联，无需查看 API 文档
- 域名强制执行——CSV 上传会拒绝任何不匹配组织域名的邮件
- 多组织支持
## GDPR 合规性
| 功能 | GDPR 条款 | 实现方式 |
|---|---|---|
| **假名化的 LLM 提示词** | 第 5(1)(f) 条 | 在调用任何 LLM 之前，将真实姓名替换为 `Employee_XXXX` 别名。真实姓名通过 Supabase Vault 加密存储在 `name_map` 中。 |
| **同意门控 + 授权 PDF** | 第 6 条 | 没有合法依据选择、管理员授权确认复选框和 PDF 下载，活动无法启动。 |
| **90 天自动数据保留** | 第 5(1)(e) 条 | 在活动创建时设置 `auto_delete_at`。每日 Supabase Edge Function 删除过期的活动、员工、事件、name_map 条目和测验结果。 |
| **删除权端点** | 第 17 条 | `DELETE /api/gdpr/erase/{alias}` 移除所有员工数据，并生成可下载的删除收据 PDF。 |
| **域名白名单强制执行** | 第 5(1)(b) 条 | CSV 上传会拒绝任何不匹配已注册组织域名的邮件。拒绝操作记录到审计跟踪中。 |
| **仅追加审计日志** | 第 30 条 | 每个操作（创建、启动、上传、删除、导出）均记录操作人邮箱、时间戳、IP 地址。审计日志没有 DELETE 端点。 |
| **零凭证存储** | 第 5(1)(c) 条 | 假登录表单仅记录一个布尔 `cred_entered` 事件标志。凭证不会被存储、传输或记录在任何地方。 |
| **LLM 数据最小化** | 第 5(1)(c) 条 | LLM 提示词仅包含别名和通用角色。不会将姓名、邮箱或部门发送到外部 API。 |
## 技术栈
| 层级 | 技术 | 用途 |
|---|---|---|
| 后端 | FastAPI 0.111 + Python 3.11 | REST API、跟踪端点、活动逻辑 |
| LLM | Groq API (llama-3.3-70b-versatile) | 钓鱼邮件生成、修复建议 |
| 邮件 | SendGrid | 事务性邮件发送 |
| 前端 | React 18 + Vite + Tailwind CSS | 单页应用仪表板和钓鱼页面 |
| 图表 | Recharts | 参与率柱状图 |
| 数据库 | Supabase (PostgreSQL) | 数据存储 + 行级安全性 |
| Edge Functions | Supabase Deno | 每日保留清理定时任务 |
| PDF | ReportLab | 报告和授权 PDF 生成 |
| 认证（计划中） | Supabase Auth | 管理员身份验证 |
## 本地设置
### Docker（推荐）
```
cp backend/.env.example backend/.env
# 填写 backend/.env 中的 API keys
docker compose up --build
```
前端：http://localhost:3000
后端：http://localhost:8000
API 文档：http://localhost:8000/api/docs
### 前提条件
- Python 3.11+
- Node.js 18+
- Supabase 项目
- Groq API 密钥（免费层：[console.groq.com](https://console.groq.com))
- SendGrid API 密钥（免费层：[sendgrid.com](https://sendgrid.com))
### 1. 数据库
在 Supabase SQL 编辑器中运行 `supabase/schema.sql`。然后单独运行测验结果表：
```
CREATE TABLE IF NOT EXISTS quiz_results (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
employee_id UUID NOT NULL REFERENCES employees(id) ON DELETE CASCADE,
campaign_id UUID NOT NULL REFERENCES campaigns(id) ON DELETE CASCADE,
score INTEGER NOT NULL,
answers JSONB,
submitted_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
ALTER TABLE campaigns ADD COLUMN IF NOT EXISTS notes TEXT;
ALTER TABLE employees ADD COLUMN IF NOT EXISTS scenario_override TEXT;
CREATE INDEX IF NOT EXISTS idx_quiz_results_campaign ON quiz_results(campaign_id);
CREATE INDEX IF NOT EXISTS idx_quiz_results_employee ON quiz_results(employee_id);
ALTER TABLE quiz_results ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Authenticated users can manage quiz_results" ON quiz_results FOR ALL TO authenticated USING (true);
CREATE POLICY "Public can insert quiz_results" ON quiz_results FOR INSERT TO anon WITH CHECK (true);
```
部署保留 Edge Function：
```
supabase functions deploy retention-cleanup
```
通过 Supabase 仪表板 → Edge Functions → 定时任务 (`0 0 * * *`) 将其设置为每日执行。
### 2. 后端
```
cd backend
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env # Fill in your API keys
uvicorn app.main:app --reload --port 8000
```
API 文档：[http://localhost:8000/api/docs](http://localhost:8000/api/docs)
### 3. 后台队列（Redis + Celery + Flower）
用于后台异步发送邮件和生成 PDF：
```
# 1. 通过 Docker 启动 Redis
docker run -d -p 6379:6379 redis:5.0.1
# 2. 启动 Celery worker（在 backend 目录中）
celery -A celery_worker worker --loglevel=info
# 3. 启动 Flower 监控面板
celery -A celery_worker flower --port=5555
```
Flower 仪表板：[http://localhost:5555](http://localhost:5555)
*(注意：如果 Redis 未运行或未配置，SpearSim 会优雅地回退到内联同步执行模式)。*
### 4. 前端
```
cd frontend
npm install
npm run dev
```
应用：[http://localhost:3000](http://localhost:3000)
### 5. 快速开始（Windows）
双击项目根目录下的 `start.bat`。它将：
- 检查是否安装了 Python 和 Node.js
- 根据需要创建虚拟环境
- 自动安装所有依赖项
- 在单独的终端窗口中启动后端和前端
- 4 秒后打开浏览器
## 环境变量
### `backend/.env`
| 变量 | 描述 |
|---|---|
| `SUPABASE_URL` | Supabase 项目 URL |
| `SUPABASE_ANON_KEY` | Supabase 公钥 |
| `SUPABASE_SERVICE_ROLE_KEY` | Supabase 私钥（绕过 RLS —— 仅后端使用） |
| `GROQ_API_KEY` | Groq API 密钥 |
| `GROQ_MODEL` | 模型名称（默认：`llama-3.3-70b-versatile`） |
| `SENDGRID_API_KEY` | SendGrid API 密钥 |
| `SENDGRID_FROM_EMAIL` | 已验证的发件人邮箱 |
| `SENDGRID_FROM_NAME` | 发件人显示名称 |
| `APP_BASE_URL` | 用于跟踪链接的后端 URL（例如 `http://localhost:8000`） |
| `FRONTEND_URL` | 用于重定向的前端 URL（例如 `http://localhost:3000`） |
| `SECRET_KEY` | 随机密钥字符串（至少 32 个字符） |
| `ENVIRONMENT` | `development` 或 `production` |
| `ALLOWED_ORIGINS` | 以逗号分隔的 CORS 来源 |
## API 参考
```
Organizations
POST /api/organizations/ Create organisation
GET /api/organizations/ List organisations
Campaigns
POST /api/campaigns/create Create campaign
GET /api/campaigns/ List all campaigns
GET /api/campaigns/{id} Get campaign details
POST /api/campaigns/{id}/consent Update GDPR consent
POST /api/campaigns/{id}/launch Launch campaign (sends emails)
POST /api/campaigns/{id}/complete Mark campaign complete
POST /api/campaigns/{id}/resend Re-send to non-interacting employees
DELETE /api/campaigns/{id} Delete campaign + all related data
GET /api/campaigns/{id}/preview-email Preview LLM-generated email
GET /api/campaigns/{id}/report Get report + AI remediation
GET /api/campaigns/{id}/report/pdf Download PDF report
GET /api/campaigns/{id}/report/csv Download CSV report
Employees
POST /api/employees/upload-csv Upload employee CSV
GET /api/employees/{campaign_id} List employees (alias only)
Tracking
GET /track/open/{uuid} Open pixel (1×1 GIF)
GET /track/click/{uuid} Click tracker → redirect to awareness page
POST /track/cred/{uuid} Credential submission tracker
POST /track/quiz/{uuid} Awareness quiz submission
Phish Page
GET /api/phish/{uuid} Phish page context (red flags, scenario)
GDPR
DELETE /api/gdpr/erase/{alias} Article 17 right to erasure
GET /api/gdpr/erase/{alias}/receipt Download erasure receipt PDF
GET /api/gdpr/audit-logs Paginated audit log
POST /api/gdpr/consent-pdf/{id} Generate authorisation PDF
GET /api/gdpr/active-campaigns Retention dashboard data
```
## 项目结构
```
SpearSim/
├── start.bat # Windows one-click launcher
├── supabase/
│ ├── schema.sql # Full database schema + RLS policies
│ └── functions/
│ └── retention-cleanup/
│ └── index.ts # Daily GDPR data retention Edge Function
├── backend/
│ ├── app/
│ │ ├── main.py # FastAPI app + CORS + router registration
│ │ ├── config.py # Pydantic settings from .env
│ │ ├── database.py # Supabase client factory (anon + admin)
│ │ ├── models.py # All Pydantic request/response models
│ │ ├── utils.py # Shared utilities (alias gen, IP extraction)
│ │ ├── routes/
│ │ │ ├── campaigns.py # Campaign CRUD, launch, resend, delete, reports
│ │ │ ├── employees.py # CSV upload + pseudonymisation
│ │ │ ├── tracking.py # Open/click/cred/quiz tracking
│ │ │ ├── gdpr.py # Erasure, audit logs, consent PDF
│ │ │ └── organizations.py # Organisation management
│ │ └── services/
│ │ ├── llm_service.py # Groq batch email generation + remediation
│ │ ├── email_service.py # SendGrid delivery
│ │ ├── pdf_service.py # ReportLab PDF generation
│ │ └── audit_service.py # Audit logging + action constants
│ ├── requirements.txt
│ └── .env.example
└── frontend/
├── src/
│ ├── App.jsx # React Router setup
│ ├── lib/api.js # Axios API client + interceptors
│ ├── components/
│ │ ├── Layout.jsx # Sidebar navigation
│ │ ├── StatCard.jsx # Metric cards
│ │ ├── StatusBadge.jsx # Campaign status pill
│ │ ├── RiskBadge.jsx # Employee risk level badge
│ │ ├── LoadingSpinner.jsx # Loading state
│ │ └── EmptyState.jsx # Empty list state
│ └── pages/
│ ├── Dashboard.jsx # Campaign overview + search/filter
│ ├── NewCampaign.jsx # 3-step creation wizard + org modal
│ ├── CampaignDetail.jsx # Report, chart, employee breakdown
│ ├── Compliance.jsx # GDPR audit log + erasure dashboard
│ └── PhishPage.jsx # Fake login → awareness screen + quiz
├── package.json
└── vite.config.js # Vite dev server + API proxy
```
## CSV 格式
按此格式上传员工 CSV：
```
email,role,name,scenario
alice@company.com,Software Engineer,Alice Smith,IT Support
bob@company.com,HR Manager,,HR
charlie@company.com,Finance Analyst,Charlie Brown,Finance
```
- `email` —— 必填，必须匹配组织域名
- `role` —— 必填，用于 LLM 提示词进行个性化
- `name` —— 可选，加密存储，永不发送给 LLM
- `scenario` —— 可选，覆盖每位员工的活动默认场景
## 道德使用免责声明
SpearSim 专为在操作员拥有明确权限进行此类模拟的组织内进行**授权的安全意识培训**而设计。
**此工具必须仅在以下情况下使用：**
- 具有适当的组织授权
- 在有效的 GDPR 合法依据下
- 存有已签署的授权 PDF
- 仅针对属于您自己组织域名的邮箱地址
**此工具绝不可用于：**
- 在没有明确授权的情况下针对个人或组织
- 捕获、存储或传输真实凭证
- 用于任何恶意、欺骗或未经授权的目的
滥用此工具可能违反计算机欺诈法律、数据保护法规和雇佣法。
## 作者
由 [Sangamesh Girish Dandin](https://linkedin.com/in/sangamesh-girish-dandin-553b45247) 构建——爱尔兰国立学院人工智能硕士研究生，专攻 AI 安全。
GitHub：[@Sangamesh-dev](https://github.com/Sangamesh-dev) · 别名：**n0xvector**
标签：AI驱动安全, FastAPI框架, GDPR合规, Groq LLM, LLM生成内容, React前端, SendGrid邮件服务, Supabase数据库, 反取证, 合规报告, 安全测试, 安全演练, 安全评估, 实时点击跟踪, 攻击性安全, 数据隐私保护, 测试用例, 网络安全, 自动化安全评估, 自定义脚本, 行为监控, 请求拦截, 隐私保护