jonscafe/whaley

GitHub: jonscafe/whaley

专为 CTF 比赛打造的 Docker 实例管理器，为每位参赛者提供独立隔离的挑战环境并集成动态 Flag、作弊检测和资源监控。

Stars: 7 | Forks: 0

🐳 Whaley

专为 CTF 比赛打造的 Docker 实例管理器

功能特性 • 快速开始 • 文档 • 系统截图 • 参与贡献

## 📋 概述 **Whaley** 是一个专为 Capture The Flag (CTF) 比赛设计的生产就绪型 Docker 实例管理器。将其部署在专用服务器上，可为每位参赛者提供各自独立的隔离挑战环境——具备自动端口分配、资源限制以及与 CTFd 的无缝集成等功能。 ### 为什么选择 Whaley？ | 问题 | Whaley 的解决方案 | |---------|-------------------| | 共享挑战实例会导致相互干扰 | 🔒 为每个用户/团队提供**独立容器** | | 手动管理端口容易出错 | 🎯 带冲突预防的**自动端口分配** | | 无法直观了解参赛者的资源使用情况 | 📊 **实时监控**仪表盘 | | 难以检测 flag 共享（作弊）行为 | 🔍 **可疑提交检测** | | 动态 flag 的配置非常复杂 | 💉 与 CTFd **轻松集成**并自动注入 flag | ## ✨ 功能特性
### 🚀 核心功能 - **动态生成实例** — 为每个用户/团队提供独立的 Docker 容器 - **自动端口分配** — 智能端口管理（10000-60000 范围） - **多端口挑战** — 支持复杂的多服务挑战 - **自动清理** — 超时后自动终止实例 - **支持 Docker Compose** — 标准的 `.yaml` 和 `.yml` 格式 - **强制资源限制** — 对所有容器强制执行全局内存、CPU 和 PID 上限 - **按挑战自定义资源** — 可在管理面板中微调每个挑战的资源限制 ### 🔐 认证与安全 - **CTFd 集成** — 通过 CTFd 访问令牌验证用户和管理员 RBAC - **无认证模式** — 基于.IP 识别的公开活动模式 - **网络隔离** — 每个实例都运行在独立的 Docker 网络中 - **分布式锁** — 基于 Redis 的锁机制，确保多 worker 的安全性 - **Fork 炸弹防护** — 限制每个容器的 PID 数量 ### 🚩 动态 Flag - **唯一的 Flag** — 每个用户/团队在每个挑战中获得独立的 flag - **自动注入 Flag** — 在构建时将 flag 注入到挑战文件中 - **CTFd 注册** — 自动向 CTFd 注册 flag - **提交监控** — 检测并记录 flag 共享企图 - **团队模式支持** — 启用时，团队内共享 flag ### 📊 监控与管理 - **实时指标** — 查看每个容器的实时 CPU/RAM 使用情况 - **实例取证** — 在终止时或按需捕获日志 - **管理仪表盘** — 用于监控和管理的 Web UI - **挑战管理器** — 无需 SSH 即可上传和编辑挑战 - **挑战开关** — 在管理面板中激活/停用挑战 - **管理员设置界面** — 通过 Web UI 配置所有 Whaley 设置（无需编辑 env/compose 文件） - **事件日志** — 包含 Docker 错误的完整审计跟踪
## 🚀 快速开始 ### 前置条件 - Docker Engine 24.0+ 及 Docker Compose v2 - 4 核以上的 CPU，8GB 以上的 RAM（参见[容量规划](#-capacity-planning)） - Linux 服务器（推荐 Ubuntu 22.04+ 或 Debian 12+） ### 安装 ``` # Clone 仓库 git clone https://github.com/jonscafe/whaley.git cd whaley # 配置环境 cp .env.example .env nano .env # Edit with your settings # 启动 Whaley docker compose up -d ``` ### 访问入口 | 界面 | URL | 描述 | |-----------|-----|-------------| | **用户仪表盘** | `http://your-server:8000/` | 挑战实例生成界面 | | **管理面板** | `http://your-server:8000/admin` | 监控与管理 | | **API 文档** | `http://your-server:8000/docs` | Swagger API 文档 | ## ⚙️ 配置说明 ### 基础设置 ``` # Authentication AUTH_MODE=ctfd # "ctfd" or "none" CTFD_URL=https://your-ctfd.com # Your CTFd instance URL CTFD_API_KEY=ctfd_xxx... # CTFd admin API key for dynamic flags/sync # 网络 PUBLIC_HOST=auto # VPS IP ("auto" for detection) PORT_RANGE_START=20000 PORT_RANGE_END=50000 # Admin ADMIN_KEY=your-secure-key # Local admin key when AUTH_MODE=none # Dynamic Flags DYNAMIC_FLAGS_ENABLED=true FLAG_PREFIX=FLAG # e.g., FLAG{...} # Team Mode TEAM_MODE=auto # "auto", "enabled", or "disabled" ``` ### 生产环境设置（可选） ``` # PostgreSQL 高可用 DATABASE_URL=postgresql+asyncpg://user:pass@db:5432/whaley # Redis 分布式锁（多个 worker 时必需） REDIS_URL=redis://redis:6379/0 # 网络隔离（推荐） NETWORK_ISOLATION_ENABLED=true NETWORK_ICC_DISABLED=true TRUSTED_PROXIES=127.0.0.1,::1 # Only these proxies may set client IP headers # 资源限制（在所有容器上强制执行） CONTAINER_MAX_MEMORY=512m # Max memory per container CONTAINER_MAX_CPU=1.0 # Max CPU cores per container CONTAINER_PIDS_LIMIT=256 # Max PIDs per container (fork bomb protection) ``` ## 📁 挑战目录结构 在 `challenges/` 目录中创建挑战： ``` challenges/ └── my-web-challenge/ ├── challenge.yaml # Challenge metadata ├── docker-compose.yaml # Container definition ├── Dockerfile ├── flag.txt # Flag file (auto-injected) └── src/ └── app.py ``` ### challenge.yaml ``` id: my-web-challenge name: "SQL Injection Lab" category: web description: "Can you bypass the login?" ports: - 80 timeout: 3600 # 1 hour ``` ### docker-compose.yaml ``` services: web: build: . ports: - "${PORT_80}:80" environment: - FLAG=${FLAG} mem_limit: 256m cpus: 0.5 ``` ## 👥 团队模式 Whaley 支持按团队共享实例和 flag 的 CTFd 团队模式： | 功能 | 用户模式 | 团队模式 | |---------|:---------:|:---------:| | 实例所有权 | 归属用户 | 归属团队 | | 动态 Flag | 每个用户独立 | 团队内共享 | | 实例控制权 | 仅创建者 | 任何团队成员 | | 可疑行为检测 | 用户之间 | 团队之间 | 设置 `TEAM_MODE=auto` 可自动从 CTFd 的设置中检测该模式。 ## 📊 容量规划 ### 估算公式 ``` Concurrent Instances = Teams × Active Challenges × 0.5 RAM Required = Concurrent Instances × 256MB (average) Ports Required = Concurrent Instances × Ports per Challenge ``` ### 服务器建议配置 | 活动规模 | CPU | RAM | 存储 | 示例 | |------------|:---:|:---:|:-------:|---------| | **小型**（≤50 支队伍） | 4 核 | 8 GB | 40 GB SSD | 本地 CTF 比赛 | | **中型**（50-150 支队伍） | 8 核 | 32 GB | 100 GB SSD | 高校 CTF 比赛 | | **大型**（150-300 支队伍） | 16 核 | 64 GB | 200 GB SSD | 全国性 CTF 比赛 | ### 计算示例 ## 📸 系统截图
User Dashboard
User Dashboard 		Admin Dashboard
Admin Dashboard
Event Logs
Event Logs 		Challenge Manager
Challenge Manager
Dynamic Flags
Dynamic Flags 		CTFd Sync
CTFd Challenge Sync
## ⚙️ 管理员设置与挑战管理 ### 实时设置（无需重启） 所有核心的 Whaley 设置均可在运行时通过 **Admin Panel → ⚙️ Settings** 选项卡进行更改： | 类别 | 设置项 | |----------|----------| | **实例** | 超时时间，每个用户/团队的最大实例数 | | **资源** | 容器最大内存，CPU 核心数，PID 限制 | | **网络** | 端口范围，网络隔离，公网主机 | | **功能** | 动态 flag，flag 前缀 | | **认证** | 认证模式 (CTFd/None)，CTFd URL，CTFd API 密钥，本地管理员密钥回退 | | **取证** | 自动捕获，保留期限 | 更改将持久化到数据库，并在容器重启后依然有效——无需编辑 `docker-compose.yaml` 或 `.env` 文件。 ### 挑战 激活/停用 开关 通过 **Challenge Manager** 选项卡控制哪些挑战可见并允许生成： - **🟢 激活** — 在用户仪表盘上可见，可被生成 - **🔴 停用** — 对用户隐藏，生成请求将被拒绝 (HTTP 403) 可在比赛期间使用此功能为后续轮次预先部署挑战，或者在不删除挑战的情况下快速禁用有问题的题目。 挑战上传功能会拒绝路径穿越、绝对路径和符号链接。如果运行时挑战目录树中包含符号链接，也会被拒绝。浏览器编辑器只能写入大小在 2 MB 以内的文本文件，且当存在活跃实例正在使用某个挑战时，Whaley 会阻止删除该挑战。 ### 强制资源限制 Whaley 会对**每个**容器强制执行最大资源限制，而无论挑战的 `docker-compose.yaml` 中指定了什么： ``` CONTAINER_MAX_MEMORY=512m # Caps mem_limit in compose files CONTAINER_MAX_CPU=1.0 # Caps cpus in compose files CONTAINER_PIDS_LIMIT=256 # Injects pids_limit (fork bomb protection) ``` 如果某些挑战需要更多资源，可以通过管理员 API 设置按挑战覆盖的资源限制。 ## 📖 文档 有关详细的完整文档，请参阅 **[DOCUMENTATION.md](DOCUMENTATION.md)**： - 🔧 [安装与配置](DOCUMENTATION.md#installation) - 📦 [挑战结构与示例](DOCUMENTATION.md#challenge-structure) - 🔌 [API 参考](DOCUMENTATION.md#api-reference) - 🛡️ [安全注意事项](DOCUMENTATION.md#security) - 📈 [实例取证](DOCUMENTATION.md#instance-forensics) - 🔍 [资源监控](DOCUMENTATION.md#resource-monitoring) - 📊 [容量规划](DOCUMENTATION.md#capacity-planning) - ⚙️ [管理员设置与挑战管理](DOCUMENTATION.md#admin-settings) ### 贡献指南 - 🐛 修复 Bug 及改进 - 📝 完善文档 - 🎨 UI/UX 改进 - 🧪 提高测试覆盖率 - 🌐 国际化支持 ## 📄 许可证 本项目基于 **MIT License** 授权 —— 详见 [LICENSE](LICENSE) 文件。 ## 👨‍💻 作者
keii
keii
Creator & Maintainer

Built with ❤️ for the CTF community

If you find Whaley useful, please consider giving it a ⭐

GitHub stars

标签：CTFd, Docker, Web截图, 作弊检测, 动态靶标, 安全防御评估, 实例管理, 容器安全, 容器编排, 搜索引擎查询, 测试用例, 版权保护, 特权提升, 竞赛平台, 端口分配, 网络安全, 自动化部署, 请求拦截, 资源限制, 逆向工具, 隐私保护, 隔离环境, 靶场管理