rob-pasc/Innovationsprojekt
GitHub: rob-pasc/Innovationsprojekt
一个基于浏览器的游戏化安全意识培训平台，通过真实的钓鱼模拟 pipeline 和即时补救教学帮助用户识别钓鱼攻击。
Stars: 1 | Forks: 1
# 
DeKoi • 不要中招。
一个基于浏览器的游戏化安全意识平台，通过互动模拟和即时的教学反馈，训练用户识别钓鱼攻击。
## 关于
传统的安全意识培训通常被认为是单调、过于理论化且脱离实际场景的。本平台通过将真实的钓鱼模拟 pipeline 与游戏化的补救训练相结合，弥补了这一空白，让用户体验受控的“抓包！”环节，随后引导他们确切了解自己为何会被欺骗。
核心循环：**管理员（或自动化调度程序）发送个性化钓鱼邮件 → 用户点击诱饵 → 用户被重定向到教育提醒页面 → 标签匹配选择最相关的培训模块 → 用户完成一个小游戏或 SCORM 课程以恢复积分。**
钓鱼活动可以通过管理员仪表板手动触发，也可以由基于 Hangfire 的每日调度程序自动发送。该调度程序使用按组划分的策略来控制时间、难度和模板选择。
## 用户流程
### 新用户引导
1. 用户注册 → 完成简短的引导欢迎界面
2. 审核员在“用户管理”中将他们分配到某个组
3. 填充 `NextPhishingAt` → 用户进入自动化钓鱼轮换队列
### 管理员发送模拟
1. 管理员打开 **Dashboard → Simulations**，选择邮件模板和目标邮箱
2. 后端创建 `PhishingAttempt`，个性化邮件（姓名、代词），注入追踪链接和打开追踪像素，并通过 sender-api 发送
3. 确认面板显示追踪链接和发送时间戳
### 用户上钩钓鱼邮件
1. 用户点击追踪链接 → 扣除 XP，记录 `ClickedAt`，管理员仪表板接收实时 SignalR 通知
2. 用户跳转至提醒页面——展示原始邮件，并突出显示钓鱼手法和 XP 惩罚
3. 平台将模板的标签与最佳可用培训实例进行标签匹配
4. 用户完成培训游戏 → 发放 XP → 尝试标记为 `Remediated`（已补救）
### 自适应钓鱼调度程序
1. 审核员打开 **Dashboard → Phishing Scheduler**，选择一个组
2. 配置策略：频率倍数、难度范围、所需模板标签，或完全禁用该组的钓鱼功能
3. 每日 Hangfire 任务（08:00 UTC）筛选出 `NextPhishingAt ≤ now` 的用户，并为每个用户调度经标签和难度筛选的模板，每个模板都带有随机的发送时间偏移量，从而确保邮件在一天中陆续到达，而不是一次性集中发送
4. 根据用户最近的点击记录和组策略，重新计算每个用户的下次发送间隔
### 管理员创建邮件模板
1. 管理员打开 **Dashboard → Templates**，点击 **New Template**
2. 填写主题、发件人姓名、HTML 正文（包含 `{{TRACKING_LINK}}` 占位符）、钓鱼手法标签以及难度（1–5）
3. 该模板立即可用于手动发送和自动化调度程序
### 审核员创建培训模块
1. 审核员打开 **Dashboard → Training Library**，点击 **New Module → Build from a game type**
2. 从下拉菜单中选择游戏类型（例如：*Phishing Quiz*、*URL Detective*、*Social Engineering Chat*）
3. 填写结构化表单：标题、标签、难度、回合数以及可选的内容过滤器
4. 该模块立即可用于在钓鱼尝试失败后的自动化路径调度，以及独立的库内游玩。（审核员也可以选择 **Upload a SCORM package**，以引入来自外部创作工具的模块。）
### 将培训模块导出至外部 LMS
1. 管理员在 Training Library 中找到一个模块并点击 **Export**
2. 后端解析配置，从 R2 获取 SCORM shell，并将 `config.json` 封装进一个 ZIP 文件
3. 下载的 `.zip` 文件是独立的——可直接上传至 Moodle、Cornerstone、SCORM Cloud 等平台
### 监控实时活动
1. 管理员打开 **Dashboard → Simulations**——**Live Activity** 面板位于发送表单旁
2. 该面板连接到 SignalR hub，并在打开和点击事件到达时实时推送流数据
3. 每个事件卡片显示目标邮箱、模板名称、事件类型和时间戳——无需轮询或刷新页面
### 查看活动统计
1. 管理员或审核员打开 **Dashboard → Statistics**
2. 查看概览指标、活动时间线、模板表现、各组细分数据、用户排行榜、风险概览以及 **培训效能**（培训前后按手法分类的点击率）
3. 将所有数据导出为 CSV 以供离线分析
### 用户从游戏库中游玩
1. 用户打开 **Dashboard → Library** 并浏览可用的培训实例
2. 完成游戏 → 得分和 XP 被记录为独立的 `SaveGame`（不关联任何钓鱼尝试）
### 用户挑战同事 (Phish a Coworker)
1. 升级时，用户将获得一个 **Challenge Token**（最多持有 3 个）
2. 在 **Dashboard → Phish a Coworker** 中，他们使用受限构建器设计诱饵（结构化字段，不支持原始 HTML），并选择目标：一个相互接受的 **friend** 或 **random** 同事（匿名）
3. 发送将消耗一个 token；之后的流程就是标准的钓鱼 pipeline——点击惩罚 → 提醒页面 → 标签匹配的培训
4. 当收件人完成培训后，**发送者将获得按比例发放的额外 XP**——奖励与同事的学习情况挂钩，而不是与他们被骗挂钩
5. 管理员可以在全组织范围内禁用此功能（**Dashboard → Settings**）；任何用户都可以选择退出被作为目标的列表。参见 [`docs/workflows/peer-challenge-lifecycle.md`](docs/workflows/peer-challenge-lifecycle.md)
## 技术栈
| 层级 | 技术 |
| :--- | :--- |
| 前端框架 | React 19 + TypeScript (Vite) |
| 样式设计 | Tailwind CSS 4 + Shadcn UI |
| 状态管理 | Zustand |
| 动画 | Framer Motion |
| 图表 | Recharts |
| 图标 | Lucide React |
| 实时通信 | SignalR (`@microsoft/signalr`) |
| HTTP 客户端 | Axios |
| 表单验证 | React Hook Form + Zod |
| 后端框架 | ASP.NET Core Web API (.NET 10, C#) |
| ORM | Entity Framework Core |
| 数据库 | PostgreSQL |
| 身份验证 | JWT + BCrypt |
| 后台任务 | Hangfire (PostgreSQL 存储) |
| 邮件发送 (开发环境) | Mailpit – 带有浏览器 UI 的本地模拟 SMTP |
| 邮件发送 (生产环境) | 通过 sender-api 在白名单 VPS 上运行的 Postfix |
| 对象存储 | Cloudflare R2 (兼容 S3，用于 SCORM 包) |
| API 文档 | Scalar (OpenAPI) |
## 快速开始
### 前置条件
- [.NET 10 SDK](https://dotnet.microsoft.com/download)
- [Node.js 20+](https://nodejs.org/)
- [Docker](https://www.docker.com/)（用于数据库和本地邮件堆栈）
- Cloudflare R2 存储桶（用于存储 SCORM 包）
### 1. 数据库 (开发环境)
Database 文件夹中的 `docker-compose.yml` 会启动一个 PostgreSQL 17 容器。
`.env.example` 中的默认配置已经与这些凭据相匹配，因此在进行本地开发时
无需进行任何修改。
```
cd backend/Database
docker compose up -d
# PostgreSQL: localhost:5432 (db: innovationsprojekt, user: postgres, password: postgres)
```
### 2. 邮件堆栈 (开发环境)
在运行后端之前，请启动 Mailpit 和 sender-api。所有外发邮件都将被
本地拦截——不会发送到真实的收件箱中。
```
cd backend/MailService
docker compose up -d
# Mailpit Web UI: http://localhost:8025
# sender-api: http://localhost:8080
```
### 3. 后端
```
cd backend/Api
# 复制示例 env 文件（dev 默认值开箱即用）
cp .env.example .env
dotnet restore
dotnet ef database update # apply migrations
dotnet run
# API 可通过 http://localhost:5000 访问
# Scalar UI 可通过 http://localhost:5000/scalar 访问
```
### 4. 前端
```
cd frontend
npm install
# 复制示例 env 文件并填写您的值
cp .env.example .env
npm run dev
# App 可通过 http://localhost:5173 访问
```
### 5. R2 – 上传游戏模块模板
七个培训游戏模块（Phishing Quiz、URL Detective 等）是存储在 Cloudflare R2 中的 SCORM 包。
后端的数据填充程序在首次启动时会自动为每个模板创建数据库行，但实际文件必须单独构建并上传。
#### 5a. 配置 R2
创建一个 Cloudflare R2 存储桶（免费额度足以满足开发需求），生成一个具有 *Object Read & Write* 权限的 API token，
然后在 `backend/Api/.env` 中填写这四个 R2 变量：
```
R2__AccountId=
R2__AccessKeyId=
R2__SecretAccessKey=
R2__BucketName=
```
编辑 `.env` 后请重启后端，以使新凭据生效。
#### 5b. 构建每个模板
`scorm-templates/` 是一个 npm 工作区，因此只需安装一次即可覆盖所有模板：
```
cd scorm-templates
npm install
npm run build --workspaces --if-present
```
每次构建都会在模板目录内生成一个 `dist/` 文件夹。如果要重新构建单个
模板，请使用 `npm run build --workspace `。
#### 5c. 上传到 R2
上传 endpoint (`POST /api/admin/template-scorm/templates/{slug}/upload`) 接受
模板 `dist/` 内容的 ZIP 压缩包，并且需要管理员 JWT。
首先，获取 token（后端数据填充程序会在首次运行时创建管理员账户）：
```
TOKEN=$(curl -s -X POST http://localhost:5000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"admin@Innovationsprojekt.com","password":""}' \
| grep -o '"token":"[^"]*"' | cut -d'"' -f4)
```
然后通过一次操作构建并上传每个模板：
```
for slug in phishing-quiz url-detective social-engineering-chat \
red-flag-spotter office-risk-spotter before-you-click-send data-sorter; do
# ZIP the dist/ contents (not the dist/ folder itself)
(cd scorm-templates/$slug/dist && zip -r /tmp/$slug.zip .)
curl -s -X POST http://localhost:5000/api/admin/template-scorm/templates/$slug/upload \
-H "Authorization: Bearer $TOKEN" \
-F "file=@/tmp/$slug.zip" \
| grep -o '"filesUploaded":[0-9]*'
echo " ← $slug"
done
```
上传成功后，每个模板都会打印出 `"filesUploaded":`。在所有七个模板都
上传完毕后，仪表板中的 Training Library 将完全正常运作，并且
钓鱼警报补救流程可以将用户引导至正确的游戏模块。
## 项目结构
```
├── .github/workflows/ # CI: backend, frontend, SCORM, mail service
├── scripts/ # smoke.sh / smoke.ps1 – end-to-end smoke test
├── backend/
│ ├── Innovationsprojekt.slnx # Solution: Api + Api.Tests
│ ├── Api/ # ASP.NET Core Web API
│ │ ├── Controllers/ # HTTP endpoints
│ │ ├── Domain/ # Entities and domain logic
│ │ ├── Application/ # Services, DTOs, configuration, SignalR hub (Hubs/)
│ │ ├── Infrastructure/ # EF Core, R2 storage, Hangfire, SignalR adapter
│ │ ├── Extensions/ # Grouped DI & startup wiring (Program.cs helpers)
│ │ └── Migrations/ # EF Core migrations
│ ├── Api.Tests/ # xUnit tests (Domain/ = pure-domain tier)
│ ├── Database/ # Local database stack
│ │ └── docker-compose.yml # PostgreSQL
│ └── MailService/ # Local email delivery stack
│ ├── docker-compose.yml # Mailpit + sender-api
│ └── sender-api/ # Node/Express SMTP bridge (+ header validation & tests)
├── frontend/
│ ├── src/
│ │ ├── pages/ # Route-level components
│ │ ├── components/ # Shared UI components
│ │ ├── features/ # Feature-scoped modules (SCORM bridge, etc.)
│ │ ├── layouts/ # Layout wrapper components
│ │ ├── store/ # Zustand state stores
│ │ ├── hooks/ # Custom React hooks
│ │ ├── lib/ # Utilities and domain-sliced API client (api/)
│ │ └── styles/ # Global CSS & Tailwind tokens (globals.css)
│ └── public/
├── scorm-templates/ # npm workspace: SCORM 2004 game modules (React + Vite)
│ ├── package.json # Workspace root (single lockfile for all members)
│ ├── shared/scorm-bridge/ # @dekoi/scorm-bridge – SCORM API + config loader (+ tests)
│ ├── phishing-quiz/ # Multiple-choice phishing email quiz
│ ├── url-detective/ # Click the malicious URL segment
│ ├── social-engineering-chat/# Chat-based social engineering scenarios
│ ├── red-flag-spotter/ # Find every red flag in a full phishing email
│ ├── office-risk-spotter/ # Spot physical and digital risks in an office scene
│ ├── before-you-click-send/ # Decide whether outgoing messages are safe to send
│ └── data-sorter/ # Classify documents into the correct data categories
└── docs/ # Architecture and workflow documentation
├── adr/ # Architecture Decision Records (000–027)
├── architecture/ # Patterns, error handling, entity reference
├── audits/ # Point-in-time audits (security)
├── guides/ # Admin, SCORM catalogue, frontend UI conventions
├── reference/ # Generated reference data (reserved lure paths)
├── systems/ # Email, scheduler, XP, security notes
└── workflows/ # Campaign lifecycle, SCORM template system
```
DeKoi • 不要中招。
一个基于浏览器的游戏化安全意识平台，通过互动模拟和即时的教学反馈，训练用户识别钓鱼攻击。
## 关于
传统的安全意识培训通常被认为是单调、过于理论化且脱离实际场景的。本平台通过将真实的钓鱼模拟 pipeline 与游戏化的补救训练相结合，弥补了这一空白，让用户体验受控的“抓包！”环节，随后引导他们确切了解自己为何会被欺骗。
核心循环：**管理员（或自动化调度程序）发送个性化钓鱼邮件 → 用户点击诱饵 → 用户被重定向到教育提醒页面 → 标签匹配选择最相关的培训模块 → 用户完成一个小游戏或 SCORM 课程以恢复积分。**
钓鱼活动可以通过管理员仪表板手动触发，也可以由基于 Hangfire 的每日调度程序自动发送。该调度程序使用按组划分的策略来控制时间、难度和模板选择。
## 用户流程
### 新用户引导
1. 用户注册 → 完成简短的引导欢迎界面
2. 审核员在“用户管理”中将他们分配到某个组
3. 填充 `NextPhishingAt` → 用户进入自动化钓鱼轮换队列
### 管理员发送模拟
1. 管理员打开 **Dashboard → Simulations**，选择邮件模板和目标邮箱
2. 后端创建 `PhishingAttempt`，个性化邮件（姓名、代词），注入追踪链接和打开追踪像素，并通过 sender-api 发送
3. 确认面板显示追踪链接和发送时间戳
### 用户上钩钓鱼邮件
1. 用户点击追踪链接 → 扣除 XP，记录 `ClickedAt`，管理员仪表板接收实时 SignalR 通知
2. 用户跳转至提醒页面——展示原始邮件，并突出显示钓鱼手法和 XP 惩罚
3. 平台将模板的标签与最佳可用培训实例进行标签匹配
4. 用户完成培训游戏 → 发放 XP → 尝试标记为 `Remediated`（已补救）
### 自适应钓鱼调度程序
1. 审核员打开 **Dashboard → Phishing Scheduler**，选择一个组
2. 配置策略：频率倍数、难度范围、所需模板标签，或完全禁用该组的钓鱼功能
3. 每日 Hangfire 任务（08:00 UTC）筛选出 `NextPhishingAt ≤ now` 的用户，并为每个用户调度经标签和难度筛选的模板，每个模板都带有随机的发送时间偏移量，从而确保邮件在一天中陆续到达，而不是一次性集中发送
4. 根据用户最近的点击记录和组策略，重新计算每个用户的下次发送间隔
### 管理员创建邮件模板
1. 管理员打开 **Dashboard → Templates**，点击 **New Template**
2. 填写主题、发件人姓名、HTML 正文（包含 `{{TRACKING_LINK}}` 占位符）、钓鱼手法标签以及难度（1–5）
3. 该模板立即可用于手动发送和自动化调度程序
### 审核员创建培训模块
1. 审核员打开 **Dashboard → Training Library**，点击 **New Module → Build from a game type**
2. 从下拉菜单中选择游戏类型（例如：*Phishing Quiz*、*URL Detective*、*Social Engineering Chat*）
3. 填写结构化表单：标题、标签、难度、回合数以及可选的内容过滤器
4. 该模块立即可用于在钓鱼尝试失败后的自动化路径调度，以及独立的库内游玩。（审核员也可以选择 **Upload a SCORM package**，以引入来自外部创作工具的模块。）
### 将培训模块导出至外部 LMS
1. 管理员在 Training Library 中找到一个模块并点击 **Export**
2. 后端解析配置，从 R2 获取 SCORM shell，并将 `config.json` 封装进一个 ZIP 文件
3. 下载的 `.zip` 文件是独立的——可直接上传至 Moodle、Cornerstone、SCORM Cloud 等平台
### 监控实时活动
1. 管理员打开 **Dashboard → Simulations**——**Live Activity** 面板位于发送表单旁
2. 该面板连接到 SignalR hub，并在打开和点击事件到达时实时推送流数据
3. 每个事件卡片显示目标邮箱、模板名称、事件类型和时间戳——无需轮询或刷新页面
### 查看活动统计
1. 管理员或审核员打开 **Dashboard → Statistics**
2. 查看概览指标、活动时间线、模板表现、各组细分数据、用户排行榜、风险概览以及 **培训效能**（培训前后按手法分类的点击率）
3. 将所有数据导出为 CSV 以供离线分析
### 用户从游戏库中游玩
1. 用户打开 **Dashboard → Library** 并浏览可用的培训实例
2. 完成游戏 → 得分和 XP 被记录为独立的 `SaveGame`（不关联任何钓鱼尝试）
### 用户挑战同事 (Phish a Coworker)
1. 升级时，用户将获得一个 **Challenge Token**（最多持有 3 个）
2. 在 **Dashboard → Phish a Coworker** 中，他们使用受限构建器设计诱饵（结构化字段，不支持原始 HTML），并选择目标：一个相互接受的 **friend** 或 **random** 同事（匿名）
3. 发送将消耗一个 token；之后的流程就是标准的钓鱼 pipeline——点击惩罚 → 提醒页面 → 标签匹配的培训
4. 当收件人完成培训后，**发送者将获得按比例发放的额外 XP**——奖励与同事的学习情况挂钩，而不是与他们被骗挂钩
5. 管理员可以在全组织范围内禁用此功能（**Dashboard → Settings**）；任何用户都可以选择退出被作为目标的列表。参见 [`docs/workflows/peer-challenge-lifecycle.md`](docs/workflows/peer-challenge-lifecycle.md)
## 技术栈
| 层级 | 技术 |
| :--- | :--- |
| 前端框架 | React 19 + TypeScript (Vite) |
| 样式设计 | Tailwind CSS 4 + Shadcn UI |
| 状态管理 | Zustand |
| 动画 | Framer Motion |
| 图表 | Recharts |
| 图标 | Lucide React |
| 实时通信 | SignalR (`@microsoft/signalr`) |
| HTTP 客户端 | Axios |
| 表单验证 | React Hook Form + Zod |
| 后端框架 | ASP.NET Core Web API (.NET 10, C#) |
| ORM | Entity Framework Core |
| 数据库 | PostgreSQL |
| 身份验证 | JWT + BCrypt |
| 后台任务 | Hangfire (PostgreSQL 存储) |
| 邮件发送 (开发环境) | Mailpit – 带有浏览器 UI 的本地模拟 SMTP |
| 邮件发送 (生产环境) | 通过 sender-api 在白名单 VPS 上运行的 Postfix |
| 对象存储 | Cloudflare R2 (兼容 S3，用于 SCORM 包) |
| API 文档 | Scalar (OpenAPI) |
## 快速开始
### 前置条件
- [.NET 10 SDK](https://dotnet.microsoft.com/download)
- [Node.js 20+](https://nodejs.org/)
- [Docker](https://www.docker.com/)（用于数据库和本地邮件堆栈）
- Cloudflare R2 存储桶（用于存储 SCORM 包）
### 1. 数据库 (开发环境)
Database 文件夹中的 `docker-compose.yml` 会启动一个 PostgreSQL 17 容器。
`.env.example` 中的默认配置已经与这些凭据相匹配，因此在进行本地开发时
无需进行任何修改。
```
cd backend/Database
docker compose up -d
# PostgreSQL: localhost:5432 (db: innovationsprojekt, user: postgres, password: postgres)
```
### 2. 邮件堆栈 (开发环境)
在运行后端之前，请启动 Mailpit 和 sender-api。所有外发邮件都将被
本地拦截——不会发送到真实的收件箱中。
```
cd backend/MailService
docker compose up -d
# Mailpit Web UI: http://localhost:8025
# sender-api: http://localhost:8080
```
### 3. 后端
```
cd backend/Api
# 复制示例 env 文件（dev 默认值开箱即用）
cp .env.example .env
dotnet restore
dotnet ef database update # apply migrations
dotnet run
# API 可通过 http://localhost:5000 访问
# Scalar UI 可通过 http://localhost:5000/scalar 访问
```
### 4. 前端
```
cd frontend
npm install
# 复制示例 env 文件并填写您的值
cp .env.example .env
npm run dev
# App 可通过 http://localhost:5173 访问
```
### 5. R2 – 上传游戏模块模板
七个培训游戏模块（Phishing Quiz、URL Detective 等）是存储在 Cloudflare R2 中的 SCORM 包。
后端的数据填充程序在首次启动时会自动为每个模板创建数据库行，但实际文件必须单独构建并上传。
#### 5a. 配置 R2
创建一个 Cloudflare R2 存储桶（免费额度足以满足开发需求），生成一个具有 *Object Read & Write* 权限的 API token，
然后在 `backend/Api/.env` 中填写这四个 R2 变量：
```
R2__AccountId=标签：Web平台, 安全教育与游戏化, 测试用例, 自动化攻击