FlagForge

面向非即时判题 CTF / 电子数据取证比赛的本地智能解题工作台。

Flask API · SQLite 持久化 · SSE 实时日志 · Docker 解题沙箱 · 多 Agent 编排 · Markdown Writeup · 获胜 Agent 问答

FlagForge 是一个本地运行的 CTF 智能解题工作台。它把题目录入、附件管理、模型配置、Agent 编排、实时日志、运行历史、writeup 复盘和获胜 Agent 问答整合到一个中文 Web 控制台里，适合个人练习、比赛复盘和快速验证题目。 后端使用 Python + Flask + SQLite，前端使用 Vue 3 + Vite。真实解题时，Solver 会在 Docker 沙箱中运行常用 CTF 工具，并通过 OpenAI 兼容 API、Codex CLI、Claude SDK 或其他已接入 provider 调用模型。 ## 软件截图 ### 创建题目  ### 题目详情  ### 运行详情  ## 功能概览 - 中文 Web 控制台：题目、运行、设置三个核心页面。 - 手动创建题目：前端填写 `metadata.yml` 字段，上传 distfiles，并可自定义每个附件的保存文件名。 - 导入本地题目：直接索引已有题目目录，目录内需要包含 `metadata.yml`。 - 题目信息编辑：在前端编辑名称、分类、分值、描述、连接信息、标签和 hints。 - 题目删除：可只删除 FlagForge 索引，也可由 API 删除本地题目文件。 - Agent 解题运行：按设置页的 Agent 数量、模型池和 Skills 启动，也可在单次运行前手动指定模型。 - 随时停止运行：运行列表和题目详情页都可以停止活跃运行。 - 状态查看：运行状态会自动刷新，支持 `queued`、`running`、`succeeded`、`failed`、`cancelled`、`interrupted`。 - 日志管理：运行中显示 SSE 实时日志，结束后显示历史日志，避免重复渲染导致页面卡顿；历史日志可刷新、清空和随运行记录删除。 - Writeup 生成：运行前可选择是否在解出 flag 后生成最终 writeup。 - Markdown 渲染与下载：writeup 在前端渲染成站点风格的 HTML，代码块带复制按钮，同时支持下载 Markdown。 - 获胜 Agent 问答：如果获胜 Agent 的 session 仍在当前后端进程中，前端可以继续向它提问。 - API 配置界面：前端可配置 OpenAI 兼容中转站、密钥、CTFd、Agent 数量、模型池和 Skills。 - 模型列表来自 API：后端会请求配置的 OpenAI 兼容中转站 `/models` 或 `/v1/models`，不会在前端硬编码模型列表。 - Skills 默认全启用：`FLAGFORGE_AGENT_SKILLS` 留空时，后端会启用本机全部 Codex Skills。 ## 快速启动 ### 1. 准备环境 需要： - Python 3.14+ - `uv` - Node.js 20+ 和 npm - Docker（真实运行 solver 时需要） - 至少一个可用模型 API Key 安装依赖： uv sync npm --prefix frontend install 构建解题沙箱镜像： docker build -f sandbox/Dockerfile.sandbox -t ctf-sandbox . 复制配置文件： cp .env.example .env 最小可用配置示例： OPENAI_BASE_URL=https://api.psydo.top OPENAI_API_KEY=sk-your-key FLAGFORGE_AGENT_COUNT=1 FLAGFORGE_AGENT_MODELS=gpt-5.5 FLAGFORGE_AGENT_SKILLS= CTFD_URL=https://ctf.example.com CTFD_TOKEN=ctfd_your_token 不要把真实 API Key 提交到 GitHub。`.env` 应该只保留在本地。 ### 2. 一键启动前后端 ./start.sh 默认地址： - 前端：`http://127.0.0.1:5174` - 后端：`http://127.0.0.1:5001` - 后端健康检查：`http://127.0.0.1:5001/api/health` 日志文件： logs/flagforge-backend.log logs/flagforge-frontend.log 按 `Ctrl+C` 会同时停止前端和后端。 端口被占用时： BACKEND_PORT=5002 FRONTEND_PORT=5175 ./start.sh ## Web 使用流程 ### 创建题目 进入“题目”页面，可以选择两种方式。 手动创建： 1. 填写目录名 slug、题目名称、分类、分值、标签、连接信息和描述。 2. 上传附件文件。 3. 为每个附件设置写入 `distfiles/` 后的文件名。 4. 点击“创建题目”。 后端会写入： challenges//metadata.yml challenges//distfiles/ 导入本地目录： 1. 准备一个已有题目目录。 2. 确保目录内有 `metadata.yml`。 3. 在前端输入目录路径并导入。 示例目录见： examples/manual-challenge/ 示例 `metadata.yml`： name: Manual Upload Example category: misc value: 100 description: | Example challenge directory matching the Web UI manual upload format. connection_info: "" tags: - example - manual-upload hints: - content: Inspect the attached README first. 如果想把新题目写到其他目录： CTF_AGENT_CHALLENGE_ROOT=/path/to/challenges ./start.sh ### 启动运行 进入题目详情页后，在“启动运行”区域可以： - 使用设置页里的 Agent 编排。 - 或关闭默认编排，手动选择单次运行模型。 - 选择是否“仅本地运行，不提交 flag”。 - 选择是否“解出后生成最终 writeup”。 默认行为： - 默认模型：`gpt-5.5` - 默认 provider：OpenAI 兼容 API - 默认模型规格：`openai/gpt-5.5` - 默认 Agent 数量：`1` - 默认 Skills：本机全部 Codex Skills - 默认生成 writeup：开启 - 默认不提交 flag：开启 ### 查看运行 “运行”页面用于查看所有历史记录和活跃任务。 运行详情页包含： - 运行信息 - 实时或历史日志 - Writeup - 向获胜 Agent 提问 - 最终结果 运行中展示 SSE 实时日志。运行结束后切换为历史日志，支持刷新和清空。运行记录删除时，对应日志和 writeup 文件也会删除。 ### Writeup 与 Agent 问答 如果运行成功且“生成最终 writeup”已开启，后端会向获胜 Agent 再发送一个复盘请求，要求它输出适合初学者学习的中文 Markdown writeup。 前端会把 writeup 渲染成紧凑排版的 HTML，代码块右上角有复制按钮，也可以下载原始 Markdown。 获胜 Agent 的 session 只保存在当前后端进程内。后端重启后，历史 writeup 仍然可查看和下载，但已保留的 Agent 会话通常不可继续提问。 ## 模型与 API 配置 进入“设置”页面可以配置： - `OPENAI_API_KEY` - `OPENAI_BASE_URL` - `ANTHROPIC_API_KEY` - `ANTHROPIC_BASE_URL` - `ANTHROPIC_AUTH_TOKEN` - `GEMINI_API_KEY` - `CTFD_URL` - `CTFD_TOKEN` - `CTFD_USER` - `CTFD_PASS` - `FLAGFORGE_AGENT_COUNT` - `FLAGFORGE_AGENT_MODELS` - `FLAGFORGE_AGENT_SKILLS` - `FLAGFORGE_WRITEUP_PROMPT` 敏感字段默认隐藏，但可以点击输入框右侧的小眼睛从本地后端读取原文： - 输入新值：更新 `.env` - 留空：保持原值 - 勾选清空：写入空值 ### OpenAI 兼容中转站 默认配置： OPENAI_BASE_URL=https://api.psydo.top FLAGFORGE_AGENT_MODELS=gpt-5.5 模型列表不是前端猜出来的。后端读取 `OPENAI_BASE_URL` 和 `OPENAI_API_KEY` 后，会先请求： /models 如果 `OPENAI_BASE_URL` 本身不以 `/v1` 结尾，后端还会兜底请求 `/v1/models`。 接口返回的模型 ID 会被转成可运行的模型规格： gpt-5.5 -> openai/gpt-5.5 如果模型接口不可用，前端会展示错误信息并保留 `gpt-5.5` 作为默认模型，不把本地猜测结果伪装成中转站模型列表。 ### Agent 数量、模型池和 Skills 示例： FLAGFORGE_AGENT_COUNT=3 FLAGFORGE_AGENT_MODELS=gpt-5.5,gpt-5.4,gpt-5.4-mini FLAGFORGE_AGENT_SKILLS= FLAGFORGE_WRITEUP_PROMPT=请基于你刚才完整的 CTF 解题过程，输出一份适合初学者学习复盘的中文 Markdown writeup。要求包含：题目背景、关键漏洞/思路、尝试过程、最终利用步骤、flag、常见坑点和复盘建议。不要省略关键命令或推理。 含义： - `FLAGFORGE_AGENT_COUNT` 控制一次运行启动多少个 solver agent，范围是 1 到 12。 - `FLAGFORGE_AGENT_MODELS` 是模型池，数量不足时会循环使用。 - 模型名可以写 `gpt-5.5`，后端会自动规范化为 `openai/gpt-5.5`。 - `FLAGFORGE_AGENT_SKILLS` 留空表示启用全部本机 Codex Skills。 - 如果只想启用部分 Skills，可以用逗号或换行分隔。 - `FLAGFORGE_WRITEUP_PROMPT` 是解出 flag 后发送给获胜 Agent 的 writeup 生成提示词，默认中文。 示例： FLAGFORGE_AGENT_SKILLS=ctf-web,ctf-pwn,ctf-writeup Skills 会注入 solver prompt。如果本机存在 `/root/.codex/skills`，Docker 沙箱内也会只读挂载该目录，方便 Agent 按题型读取技能说明。 ### Codex CLI Provider Web 默认使用 `openai/gpt-5.5`，也就是 OpenAI 兼容 API provider。如果你手动选择 `codex/...` 模型，后端会调用本机 `codex app-server`，这时需要单独配置 Codex CLI。 参考 `~/.codex/config.toml`： model_provider = "OpenAI" model = "gpt-5.5" review_model = "gpt-5.5" model_reasoning_effort = "xhigh" disable_response_storage = true network_access = "enabled" windows_wsl_setup_acknowledged = true model_context_window = 1000000 model_auto_compact_token_limit = 900000 [model_providers.OpenAI] name = "OpenAI" base_url = "https://api.psydo.top" wire_api = "responses" requires_openai_auth = true API Key 请通过环境变量或本机安全配置提供，不要写入 README 或提交到仓库。 ## CLI 用法 除了 Web 控制台，项目也保留了命令行入口。 单题运行： uv run ctf-solve \ --challenge examples/manual-challenge \ --models openai/gpt-5.5 \ --no-submit \ -v 连接 CTFd 并启动 coordinator： uv run ctf-solve \ --ctfd-url https://ctf.example.com \ --ctfd-token ctfd_your_token \ --challenges-dir challenges \ --max-challenges 10 \ --coordinator codex \ -v 向运行中的 coordinator 发送提示： uv run ctf-msg "优先检查所有 web 题的 robots.txt 和备份文件" ## API 速览 健康检查： GET /api/health 题目： GET /api/challenges POST /api/challenges POST /api/challenges/manual GET /api/challenges/ PUT /api/challenges/ DELETE /api/challenges/ 运行： GET /api/runs POST /api/runs GET /api/runs/ DELETE /api/runs/ POST /api/runs//cancel GET /api/runs//logs DELETE /api/runs//logs GET /api/runs//logs/stream GET /api/runs//writeup GET /api/runs//writeup/download GET /api/runs//agent/messages POST /api/runs//agent/messages 配置： GET /api/config PUT /api/config GET /api/config/secrets/ GET /api/models POST /api/models/test ## 项目结构 backend/ app/ # 配置、题目服务、运行管理、Skills 目录发现 agents/ # Swarm、Pydantic AI Solver、Codex Solver、Claude Solver storage/ # SQLite repo 和 schema bootstrap web/ # Flask app 和 REST/SSE 路由 tools/ # sandbox、flag、vision 等工具 frontend/ src/ # Vue 页面、组件、API 封装和样式 sandbox/ Dockerfile.sandbox sandbox-tools.txt examples/ manual-challenge/ scripts/ start-flagforge.sh tests/ app/ storage/ web/ 本地运行时会生成： .ctf-agent/web.sqlite3 .ctf-agent/logs/runs/.log .ctf-agent/logs/writeups/.md logs/flagforge-backend.log logs/flagforge-frontend.log challenges/ 这些运行数据通常不应该提交到 GitHub。 ## 生产构建 构建前端： npm --prefix frontend run build 由 Flask 直接服务构建后的前端： uv run python -m backend.web.app 默认地址： http://127.0.0.1:5000 也可以指定端口： CTF_AGENT_HOST=127.0.0.1 CTF_AGENT_PORT=5001 uv run python -m backend.web.app ## 测试 后端测试： uv run pytest 前端构建检查： npm --prefix frontend run build 启动脚本测试： uv run pytest tests/test_start_script.py ## 安全说明 FlagForge 当前按本地单用户工作台设计： - 不要把 Flask 后端直接暴露到公网。 - 不要提交 `.env`、API Key、CTFd Token、运行日志、writeup 或题目附件中的敏感数据。 - Solver 会执行模型生成的命令，真实运行前请确认 Docker 沙箱镜像和挂载目录符合你的隔离要求。 - CTFd 提交功能会使用配置的 token 或账号密码；练习时建议开启“仅本地运行，不提交 flag”。 ## License MIT License. See [LICENSE](LICENSE). ## Acknowledgements - [es3n1n/Eruditus](https://github.com/es3n1n/Eruditus)：`pull_challenges.py` 中的 CTFd 交互和 HTML 辅助思路。 - [verialabs/ctf-agent](https://github.com/verialabs/ctf-agent)：FlagForge 基于该 MIT License 项目的 agent 架构、CTFd 集成和 Docker 沙箱思路继续构建，并在此基础上扩展了中文 Web 控制台、运行历史、writeup 复盘和配置界面。

标签：Agent问答, Claude SDK, Codex CLI, CTF工具, CTF平台, DNS解析, Docker沙箱, FlagForge, Flask, Markdown Writeup, meg, OpenAI兼容API, Python, SQLite, SSE, Vite, Vue.js, writeup生成, 信息安全, 域渗透, 多Agent编排, 学习资源, 实时日志, 开源项目, 技术分享, 技术栈, 技能提升, 攻防训练, 无后门, 智能解题, 本地运行, 比赛复盘, 渲染项目, 漏洞搜索, 电子数据取证, 竞赛训练, 编程竞赛, 网络安全, 网络安全教育, 自动化解题, 获胜Agent, 解题工作台, 解题平台, 请求拦截, 隐私保护, 非即时判题, 项目案例, 题目管理