n0xnull/BlueForge

## 🧩 问题背景 大多数“网络安全竞赛”工具要么只支持攻击（CTF flag， 攻击靶场），要么给组织者带来了一堆手工活：必须有人拿着 检查表到处走动，SSH 登录到每一台 VM，并手工对加固步骤进行 评分。分数在事后几分钟或几小时才能出来，而参赛者对他们 实际上修复了什么得不到任何实时反馈。 **BlueForge** 是一个**防御性**（蓝队 / 系统加固） 竞赛平台，相比红队 CTF，它更接近于 CyberPatriot。 参赛者会获得一台故意留下漏洞的 Ubuntu VM 和一个时间限制； 每一次真实的修复 —— SSH 加固、启用防火墙、移除恶意账户、 清理后门 —— 都会被轻量级 agent 自动检测到，并 在几秒钟内反映到公开的排行榜上，完全不需要人工评分。 ## ✨ 主要功能 - 🎯 **三个难度级别** — 简单（6 项检查）· 中等（11 项）· 困难（15 项）， 由组织者在每次会话中选择，每个级别都有其默认的持续时间。 - ⚖️ **公平且有据可查** — Baseline & Evidence（基准与证据）系统会在注册/开始/停止时为每台 VM 生成快照，因此在 START *之前* 修复检查项不会得分（堵住了“提前修复”的漏洞），并且每一分都是可审计的。 - ⚡ **真正的实时评分** — 排行榜轮询 + Supabase Realtime，管理 控制台会自动刷新参赛者状态，并且 agent 的时钟偏差 修正意味着，即使克隆的 VM 系统时钟 出现错误，分数也能持续传输（见 [`docs/REVIEW-AND-CONCEPT-v2.md`](docs/REVIEW-AND-CONCEPT-v2.md) §2.1）—— 不再需要等待手动刷新 VMware/Ubuntu 时钟。 - 🧩 **模块化检查** — 只需将 `manifest.yaml` + `check.py` 拖入 `agent/checks/` 即可添加新的加固检查项；评分引擎永远 不需要更改（插件式）。 - 🖥️ **零配置的参赛者体验** — agent 作为一个 kiosk 配套应用程序提供（pywebview，带有浏览器 kiosk 后备方案），会在 VM 启动时自动启动：参赛者无需接触终端即可看到注册信息、实时分数和剩余时间。 - 🔒 **签名且具有弹性的网络** — HMAC 签名的 agent↔server 流量， 指数退避，以及存储转发队列，确保竞赛期间不稳定的网络 绝不会悄无声息地丢失分数。 - 🆓 **100% 免费技术栈** — Vercel（Web）+ Supabase（Postgres/Realtime/Auth） + 纯 Python agent。运行竞赛无需任何付费服务。 ## 🖼️ 截图 ## 💻 系统要求 | | 组织者（Web） | 参赛者（每台 VM） | |---|---|---| | 托管 | 免费的 Vercel + Supabase 项目 | — | | OS | — | Ubuntu (20.04–26.04)，通过 `image/build/provision.sh` 进行配置 | | Runtime | Node.js 20+（仅用于开发/构建 — Vercel 在云端构建） | Python 3.10+，root 权限（读取 `/etc/shadow` 等） | | 网络 | 公共 HTTPS endpoint（Vercel） | 连接到该 endpoint 的出站 HTTPS — agent 仅*向外轮询*，因此在 NAT 后也能正常工作 | ## 🚀 快速开始 ### 1. 数据库 (Supabase) 1. 在 [supabase.com](https://supabase.com) 创建一个免费项目。 2. 在 **SQL Editor** 中，依次运行 `db/schema.sql` 和 `db/seed/difficulties.sql`。 3. 记下你的 **Project URL**、**anon key** 和 **service_role key**（Settings → API）。 ### 2. Web 门户 (Next.js) ``` cd web cp .env.example .env.local # fill in Supabase creds + AGENT_HMAC_SECRET npm install npm run dev # http://localhost:3000 ``` 部署到 Vercel：导入仓库 → 将根目录设置为 `web/` → 填入 环境变量。 ### 3. Agent（在每台参赛者的 Ubuntu VM 内） ``` cd agent cp config.example.yaml config.yaml # set portal_url to your deployed web URL pip install -r requirements.txt sudo python3 main.py # open http://localhost:9090 to register ``` 或者启动 kiosk 配套应用程序，而不是直接运行 bare agent： `python3 kiosk.py`（关于在 VM 启动时自动启动，请参阅 [`docs/kiosk-setup.md`](docs/kiosk-setup.md)）。 ### 4. 运行竞赛 1. 在 **`/admin`** 上：创建一个会话，选择难度（简单/中等/困难），获取 **session code**。 2. 参赛者使用该 code 在 `localhost:9090` 进行注册。 3. 组织者点击 **START** → 每个 agent 同时开始评分 → **`/`** 上显示实时分数。 4. **STOP** 冻结分数 → 导出结果。 ## 🎛️ 各组件功能 | 组件 | 功能描述 | |---|---| | `agent/` | Python agent — 运行检查、计算分数、签名并发送结果、提供本地 kiosk UI | | `web/app/api/v1/*` | 签名的 agent 对接 API — 注册、状态、分数、心跳、快照、时钟同步 | | `web/app/page.tsx` | 公开的实时排行榜 | | `web/app/admin/page.tsx` | 组织者控制台 — 会话、参赛者、开始/暂停/停止、取消资格 | | `db/` | Postgres schema + 种子数据（难度、检查项）+ `leaderboard` 视图 | | `image/build/provision.sh` | 将 15 个预设漏洞植入基础 Ubuntu VM | ## ⚙️ 工作原理 ``` [ participant VM: blueforge-agent ] --HTTPS (polling, signed)--> [ Next.js /v1 API ] | [ Supabase: Postgres + Realtime ] | [ Web: live Leaderboard + Admin console ] ``` agent 位于 NAT 之后，仅*向外轮询* — 服务器永远不需要 直接访问参赛者的 VM。每个评分周期：与 服务器同步时钟（无需手动修复时钟） → 获取竞赛状态 → 运行 当前检查项 → 计算分数（纯函数，`eligible = failed at START`） → 签名并发送。完整设计见 [`docs/TECHNICAL-DESIGN.md`](docs/TECHNICAL-DESIGN.md)。 ## 🗺️ 路线图 - **v0.2** *(当前)* — 涵盖 3 个真实难度级别的 15 项检查，kiosk 配套应用，管理员自动刷新，agent 时钟偏差修复。 - **v0.3** — 更丰富的社区贡献检查插件 API，证据查看器 UI，CSV/PDF 结果导出。 - **v0.4** — Windows 参赛者 VM 支持（agent 移植），为减少资源占用使用 Go 重写 agent。 - **v1.0** — 生产环境加固：完整的重放保护、速率限制、多组织者机构。 详情请参阅 [`docs/V0.2-PLAN.md`](docs/V0.2-PLAN.md) 以及完整的 TDD 路线图 (§29)。 ## 🧯 故障排除（组织者 / 参赛者 VM） 供组织者在参赛者 VM 上最常执行的两项操作的快速参考。完整的分步指南 （印尼语）位于 [`docs/DEPLOYMENT-GUIDE.md`](docs/DEPLOYMENT-GUIDE.md#-troubleshooting)。 **在全新的 VM 克隆上首次运行：** ``` # 首先清除 shell history —— 克隆的 VM 不应泄露前一个用户的命令 cat /dev/null > ~/.bash_history && history -c && history -w cd ~/BlueForge git pull sudo bash image/build/provision.sh # plants the 15 intentional vulnerabilities ``` **将代码更新拉取到已安装的 VM 上** — 实际在启动时运行的 kiosk/agent 是一个由 `install-kiosk.sh` 安装到 `/opt/blueforge-agent/` 的**独立副本**，而不是 git checkout 本身。 仅靠 `git pull` **不会**更新正在运行的内容 — 你必须重新同步： ``` cd ~/BlueForge git pull sudo bash agent/kiosk/install-kiosk.sh # resyncs code into /opt + restarts the service sudo systemctl restart blueforge-agent ``` **参赛者意外关闭了 kiosk 窗口：** `kiosk.py` 现在会在大约 2 秒内 自动重新打开窗口 — 无需任何操作。如果 窗口确实卡住了，请双击桌面上的 **"Restart BlueForge"** 快捷方式（无需终端），或者运行 `bash /opt/blueforge-agent/kiosk/restart-kiosk.sh`。 **常用诊断命令：** ``` systemctl status blueforge-agent dhc-telnetd # are the services alive? ps aux | grep -E "kiosk.py|main.py" # is the kiosk/agent actually running? journalctl --user -b | grep -i -E "kiosk|webview|gtk" # kiosk autostart logs this boot diff ~/BlueForge/agent/kiosk.py /opt/blueforge-agent/kiosk.py # in sync? ``` ## ⚠️ 免责声明 本平台出于训练目的，故意在 VM 中植入安全漏洞。 **仅限隔离/物理隔离的竞赛网络使用** — 部署前请参阅 [DISCLAIMER.md](DISCLAIMER.md)。 ## 📄 许可证 [MIT](LICENSE) © 2026 Abil Khosim。