NUSGreyhats/ctf-agent-orchestrator

# ctf-agent-orchestrator 一个 AI 驱动的 CTF 解题工作站。它会开通一台预装了逆向工程、取证、密码学、pwn 和 Web 工具的云 VM，然后让你通过 Web UI 将 CTF 挑战交给一个或多个 AI 代理 —— **Claude Code** 和 **Codex**。你可以运行单个代理、让多个代理并行竞速，或者将挑战分发给一组一次性的 worker VM。 ``` ┌──────────┐ challenge ┌─────────────────────┐ spawns ┌──────────────┐ │ Web UI / │ ─────────────► │ Webapp (Starlette) │ ──────────► │ Claude / Codex│ │ Discord │ ◄───────────── │ state · streaming │ ◄────────── │ + full toolkit│ └──────────┘ live stream └─────────────────────┘ events └──────────────┘ ``` ## 为什么 现代 AI 代理可以自主解决许多 CTF 挑战 —— 瓶颈通常在于*环境*，而不是智能。代理需要 binutils、反汇编器、调试器、取证套件、网络工具，以及一个可以自由运行的沙箱。该项目一次性配置好该环境，然后让能够执行命令、读/写文件、协作并不断迭代的代理接触这些挑战，直到它们找到 flag。 代理开箱即用且非常有效，但在加入 **skills**（结构化、版本控制的工作流，指导如何处理每种挑战类型：取证、逆向、密码学、pwn、Web 等）后会变得更好。当你发现代理钻了牛角尖或遗漏了某个明显的技巧时，你可以将该经验教训编写成一个 skill，这样它就不会再犯同样的错误。skill 库会随着时间不断积累，解题率也会随之上升。 ## 功能 **代理与解题** - **Claude Code 和 Codex**，通过其原生的 SDK/集成路径。可为每个代理选择模型和推理努力程度。 - **并行模式** —— 添加多个代理行来竞速解决同一个挑战。每个代理都有一个独立的工作区，并通过工作笔记和 `notify_teammates` 工具共享经过验证的突破性进展。 - **引导** —— 发送解题过程中的指导；代理会从当前会话恢复并接收你的消息。 - **恢复 / 重试 / 标记已解决 / 标记未解决** —— 从保存的会话状态恢复、重新启动，或手动覆盖状态。 - **顾问** —— 一个针对每个挑战的对话式代理，它可以读取解题者的实时记录、回答你的问题、在网上研究技术/CVE，并可以向正在运行的解题者传达简明的提示。 **Web UI** - **基于 WebSocket 的实时流式传输** —— 包含思考块、工具调用、结果和带有语法高亮及可折叠部分的文本；支持并行运行时的分屏或标签视图。 - **flag 检测** —— 自动检测 `flag{…}`、`CTF{…}`、`HTB{…}`、`picoCTF{…}` 和自定义格式。在代理启动之前，会对挑战文件进行静默的 `ctfgrep` 预检，提前呈现出候选 flag。 - **自动提交** —— 检测到的 flag 可以提交到连接的平台；正确的 flag 会将挑战标记为已解决，并停止同级的运行。 - **文件浏览器** —— 检查原始挑战文件和每次运行的工作区（图像、语法高亮的文本、二进制文件的十六进制）。 - **使用量与统计** —— 每个代理的账户/使用量仪表板，以及每个挑战的 token/成本/持续时间/轮次明细。 - **导出** —— 下载包含完整活动日志的 Markdown 报告。 **挑战管理** - **单个、批量（`.zip`/`.7z`）和平台导入。** 直接从 **CTFd, rCTF, Hack The Box CTF, CDDC, Cywaria/Cympire, 和 SAS CTF** 拉取挑战；保存的连接可以重新同步新的挑战、分数和解题情况。 - **按需实例** —— 带有 Docker/机器实例的 HTB、Cywaria 和 SAS CTF 挑战会在解题时启动，其实例的连接信息会被注入到 prompt 中。 - **按挑战/按运行的 skill** —— 设置全局默认值，在创建时锁定挑战级别的 skill，或者在解题过程中更改某次运行的 skill（刷新符号链接，代理继续运行）。 - **默认开启 TLS 验证**，对于使用自签名证书/本地赛事的活动，可以选择明确关闭。 **基础设施** - **一键部署**，通过 Terraform 部署到 **Hetzner Cloud, DigitalOcean, 或 GCP**。 - **Swarm** —— 将挑战分发给一台专用的、一次性的 GCP worker VM（从黄金镜像克隆），将繁重的 CPU/RAM/磁盘工作与控制器隔离。请参阅 [SWARM.md](SWARM.md)。 - **WireGuard VPN** —— 内置管理功能，用于需要访问 CTF 基础设施网络的挑战，并支持到客户端内部 CIDR 的反向路由。 - **集成工具** —— 一个持久化的 GDB MCP 服务器（Claude + Codex），以及通过 `analyze-with-ida-domain-api` skill 实现的无头 IDA Pro 分析（需自带已授权的 IDA）。 - **Discord 机器人**（可选） —— 每个挑战独立的线程/频道、实时通知、flag 审查，以及用于团队协调的斜杠命令。

完整功能列表 (点击展开)

**代理与模型** - Claude Code（通过 `claude-agent-sdk`）和 Codex（通过 `codex app-server`，基于 stdio 的 JSON-RPC） - 每个代理的模型选择 —— Claude: Opus 4.8/4.7/4.6/4.5, Sonnet 4.6/4.5, Haiku 4.5, Fable 5 (默认 Opus 4.6 1M); Codex: 从本地缓存/配置中发现 - 每个代理的推理努力程度 —— Claude 为 low/medium/high/max；Codex 则自动发现（默认为 XHigh），并带有兼容性保护，因此不受支持的组合会回退而不是报错 - 每个提供商的会话恢复（Claude session id, Codex thread id）以及持久化的默认代理开关 **解题与协作** - 单一和并行解题模式；在同一个挑战上让多个代理竞速，或者向现有挑战添加运行（自动从单一模式升级为并行模式） - 独立的每次运行的工作区，通过符号链接提供原始文件的 `challenge_files/` 视图 - 每个代理的工作笔记，通过交叉符号链接，队友可以阅读它们 - `notify_teammates` 工具用于传达经过验证的突破（Claude 进程内的 MCP 工具，Codex 的动态工具），并注入到队友的会话中 - 用户向所有正在运行的代理广播（通过 Web 或 Discord） - 在解题过程中引导正在运行的代理；停止一次或所有运行；恢复、重试、标记为已解决、标记为未解决 - 当其中一个代理解决或提交了正确的 flag 时，自动停止其他同级的运行 **Web UI** - 通过 WebSocket 实时流式传输思考过程、工具调用、工具结果、文本和原始输出 - 语法高亮、可折叠的工具部分、复制按钮、子代理标签页、分屏或标签式的多代理布局、每个事件的耗时时间戳、用户 prompt 显示为聊天气泡 - 对 `flag{}`/`CTF{}`/`HTB{}`/`picoCTF{}`/自定义格式进行 flag 检测，具有从中性到 正确/拒绝 的持久化状态 - 静默的 `ctfgrep` 预检会在代理启动前呈现出候选 flag；自动将检测到的 flag 提交到连接的平台 - 用于原始文件和每次运行工作区的文件浏览器（图像/文本/十六进制），支持自动刷新，并带有安全的服务器端路径解析 - 每个挑战的统计信息（输入/输出/缓存 token、成本、持续时间、API 时间、轮次、工具调用、每个模型的明细、汇总） - 使用量仪表板（Claude 身份验证/计划/组织 + token 使用量 + 每日图表；Codex 身份验证状态；每个代理的挑战总计） - 每个挑战的顾问代理（可配置提供商/模型），它可以读取解题者的记录、回答问题、在网上进行研究并传达提示 - Markdown 导出报告 + 批量导出索引；全局跨挑战的 toast 通知；键盘快捷键；响应式可折叠侧边栏；深色/浅色主题 **挑战与平台** - 创建单个挑战或批量上传 `.zip`/`.7z` 归档文件（导入前可预览/编辑元数据） - 从 CTFd, rCTF, Hack The Box CTF, CDDC, Cywaria/Cympire, SAS CTF 和 GPN 导入（通过自动发现的插件注册表） - 保存的平台连接可以重新同步新挑战以及分数/解题更新 - 在解题时启动按需的 Docker/机器实例（HTB, Cywaria, SAS）；连接信息注入到 prompt 中 - HTB 多答案（`flagsInfo`）支持，带有 `submit_answer.py` 辅助脚本 - 每个挑战的导入大小上限；默认开启 TLS 验证，对于不安全的 TLS 可选择明确关闭 **Skills** - 仓库 skill（取证和特定工具）加上外部的 [ljagiello/ctf-skills](https://github.com/ljagiello/ctf-skills)，编译进 `all-skills/` 目录 - 选定的 skill 通过符号链接进入每次运行的 `.claude/skills` 和 `.codex/skills`；Codex 也会将它们作为结构化的 skill 输入接收 - 全局默认 skill，在创建时锁定挑战级别的 skill，在运行过程中应用每次运行的 skill 覆盖（停止 → 刷新符号链接 → 恢复） - 从 Settings 中以 `.zip` 压缩包或单个 `SKILL.md` 的形式上传新 skill **基础设施与工具** - 通过 Terraform 一键部署到 Hetzner Cloud, DigitalOcean, 或 GCP - 运行时允许列表的部署同步，在 VM 上保留 `challenges/` 和 `state/` - Swarm: 将挑战分发给从黄金镜像克隆的一次性 GCP worker —— 支持按挑战固定、启动/停止/删除、空闲自动停止（默认 30 分钟）、凭证同步、Local | Swarm (auto) | Swarm:\ 的运行目标选择器、实时的 SSH 文件浏览，以及枢纽辐射型 VPN 路由 - WireGuard VPN 管理：服务器控制、生成的 Linux 客户端配置、到客户端内部 CIDR 的反向路由、可选的 `dnsmasq` DNS 转发、状态（握手时间 + 传输情况） - 持久化的 GDB MCP 服务器（为 Claude 和 Codex 注册）；通过 `analyze-with-ida-domain-api` skill 实现的无头 IDA Pro 分析（需自带已授权的 IDA） - 丰富的预装工具链（逆向工程、磁盘/内存/网络/文件取证、密码学、pwn、Web） - 基于 uv 的 Python 安装；感知依赖的并行配置（`INSTALL_SCRIPTS_PARALLEL`）；设置结束时的验证 **Discord (可选)** - 将每个挑战的目标设为线程或与类别匹配的频道 - 关于启动、停止、解决、flag 检测、突破和完成的通知 - flag 审查按钮（提交 / 拒绝 / 标记正确 / 广播）和挑战操作按钮（状态、统计、输出尾部、flag、提交、已解决、停止、恢复） - 斜杠命令：`/broadcast` `/ctf` `/files` `/flags` `/help` `/resume` `/solved` `/stats` `/status` `/steer` `/stop` `/submit` `/tail` - 实时设置调节（网关在配置更改时启动/停止/重启） **持久化与安全** - 挑战元数据、运行历史记录、检测到的 flag、每次运行的 JSONL 日志、平台连接和设置持久化存储在 `state/` 和 `challenges/` 下；重启时会重置过期的 `solving` 运行 - HTTP Basic/会话身份验证，对更改状态的路由进行 CSRF 保护，带有 Origin 验证的已认证 WebSocket - 浏览器安全响应头（CSP, `nosniff`, Referrer-Policy, X-Frame-Options, Permissions-Policy, COOP, 基于 TLS 的 HSTS）

## 支持的代理 | 代理 | 模型 | 努力程度 | 恢复 | 协作 | 引导 | |-------|--------|---------------|--------|---------------|----------| | **Claude Code** | 提供商默认值, Fable 5, Opus 4.8/4.7/4.6/4.5, Sonnet 4.6/4.5, Haiku 4.5 (默认 **Opus 4.6 1M**) | 提供商默认值, Low, Medium, High, Max (默认 **High**) | ✅ | `notify_teammates`, 工作笔记 | ✅ | | **Codex** | 从本地 Codex 缓存/配置中发现 | 按模型区分；常见的回退 Low, Medium, High, XHigh (默认 **XHigh**) | ✅ | `notify_teammates`, 工作 | ✅ | 在一个挑战上设置两个或更多代理行会自动创建一个并行运行。 ## 入门指南 ### 1. 部署 VM 选择一个云服务提供商（有关特定于提供商的选项，请参阅 [infra/README.md](infra/README.md)）： ``` cd infra/hetzner # or infra/digitalocean or infra/gcp cp terraform.tfvars.example terraform.tfvars # 使用你的设置编辑 terraform.tfvars terraform init terraform apply ``` 这将创建 VM、复制运行时文件、运行设置脚本、验证环境并启动 webapp 服务。使用以下命令检索登录密码： ``` terraform output -raw webapp_password # also stored on the VM at /root/.ctf-solver-password ``` ### 2. 认证代理 通过 SSH 登录并登录到你要使用的代理： ``` ssh root@$(terraform output -raw external_ip) claude auth login # Claude Code codex login # Codex ``` ### 3. 从 Web UI 解题 打开 `https://` 并登录，然后： 1. **+ 添加挑战** → 单个、批量上传或从平台导入。 2. 填写名称、描述、flag 格式，并上传/导入文件。 3. 选择代理 / 模型 / 努力程度 —— 添加更多行以进行并行竞速。 4. **创建并解题**，并实时观看输出的流式传输。 5. 如果遇到停滞则进行引导；如果完成但未解决则恢复/重试；使用“文件”选项卡检查工作区。 ### 4. (可选) Discord 在 **Settings** 中使用 bot token 和频道启用 Discord。该 bot 会创建每个挑战的线程/频道，并支持斜杠命令 —— `/ctf`, `/status`, `/flags`, `/files`, `/broadcast`, `/submit`, `/solved`, `/resume`, `/stop`。 ### 销毁 ``` cd infra/hetzner # or your provider terraform destroy ``` ## Skills Skills 是指导代理如何处理挑战类型的结构化工作流。它们有两个来源，都在设置期间被编译到运行时的 `all-skills/` 目录中： - **此仓库**（`skills/`） —— 取证（磁盘、内存、pcap、隐写术/修复）和特定于工具的 skill（IDA、apk 分析、内核 GEF 调试、angrop ROP 链）。 - **[ljagiello/ctf-skills](https://github.com/ljagiello/ctf-skills)** —— 针对 pwn、Web、密码学、逆向、杂项、osint、恶意软件和 AI/ML 的分类 skill。 webapp 通过符号链接将选定的 skill 链接到每次运行的 `.claude/skills` 和 `.codex/skills` 中。你还可以从 **Settings** 上传 `.zip` 压缩包或单个 `SKILL.md`。有关完整目录，请参阅 [skills/README.md](skills/README.md)。 ## 项目结构 ``` infra/ Terraform configs (Hetzner, DigitalOcean, GCP) install_scripts/ Numbered provisioning scripts (tools, CLIs, deps); run.sh, lib/ helpers webapp/ Starlette/ASGI app — challenge management + agent streaming agents/ Agent provider implementations (Claude, Codex) + broadcast bus plugins/ CTF platform integrations (CTFd, rCTF, HTB, CDDC, Cywaria, SAS) swarm*.py Remote GCP worker dispatch (manager, runner, exec) static/ Frontend (vanilla JS, CSS) mcps/ MCP servers (GDB debugger) skills/ Repo-owned agent skills (forensics, tools) ``` 在 VM 上创建的仅运行时目录：`all-skills/`（编译后的 skill 目录）、`challenges/`（上传的文件、工作区、设置）和 `state/`（挑战元数据、每次运行的 JSONL 日志、平台连接）。这些会在部署同步期间保留。 ## 文档 - **[DESIGN.md](DESIGN.md)** —— 架构、协作模型、文件系统布局、解题生命周期、平台插件、VPN、安全性、持久化以及完整的设置参考。 - **[SWARM.md](SWARM.md)** —— 远程 GCP 执行的设计与操作。 - **[infra/README.md](infra/README.md)** —— 每个提供商的 Terraform 用法。 - **[skills/README.md](skills/README.md)** —— skill 目录。

标签：AI智能体, Python, 云资产清单, 无后门, 自动化漏洞验证, 请求拦截, 逆向工具, 逆向工程