CTFd API实战指南:CTF Agent如何每5秒自动抓取新题并下发解题任务
CTFd API实战指南:CTF Agent如何每5秒自动抓取新题并下发解题任务
CTF Agent(ctf-agent)是一款自主 CTF 求解器,让多个 AI 模型在 Docker 沙箱中并行竞速解题,曾在 BSidesSF 2026 拿下 52/52 满分并夺得冠军。本文拆解它最核心的工程链路:如何用 CTFd API 每 5 秒轮询一次、增量检测新题,并把解题任务自动下发给多模型解题蜂群(Swarm)。
项目简介:CTF Agent 是什么 🤖
用一句话概括:一个 Coordinator(协调器)LLM 管理整场比赛,N 个解题 Swarm 各自攻击一道题,每个 Swarm 内多个模型同时开工,谁先找到 flag 谁赢。
它的默认模型阵容(定义在 backend/models.py)覆盖了两个厂商的 5 个模型:
| 模型 | 提供方 | 定位 |
|---|---|---|
| Claude Opus 4.6 (medium) | Claude SDK | 速度与质量均衡 |
| Claude Opus 4.6 (max) | Claude SDK | 深度推理 |
| GPT-5.4 | Codex | 综合最强 |
| GPT-5.4-mini | Codex | 快,适合简单题 |
| GPT-5.3-codex | Codex | 高推理强度 |
整体数据流如下(摘自 README.md):
+-----------------+
| CTFd Platform |
+--------+--------+
|
+--------v--------+
| Poller (5s) | ← 每 5 秒轮询一次 CTFd API
+--------+--------+
|
+--------v--------+
| Coordinator LLM | ← Claude / Codex 当"队长"
+--+--+--+--------+
| | |
Swarm Swarm Swarm ← 每道题一个蜂群,5 个模型竞速
| | |
Docker Sandbox(隔离容器,预装 pwntools、radare2、GDB…)
CTFd API 实战第一步:三种认证方式
所有对 CTFd 的调用都封装在 backend/ctfd.py 的 CTFdClient 中,它同时兼容两种认证:
- Token 认证(推荐):请求头带上
Authorization: Token <你的token>,最简洁; - 账号密码登录:先
GET /login页面正则提取nonce,再POST /login换取 session cookie; - CSRF 兜底:非 Token 提交时从
/challenges页面提取csrfNonce,遇到 403 会自动刷新令牌重试一次。
轮询用的核心接口只有两个,非常轻量:
| 接口 | 用途 |
|---|---|
GET /api/v1/challenges?per_page=500 |
拉取题目列表(轻量 stub,过滤 hidden 题),见 fetch_challenge_stubs |
GET /api/v1/users/me + /solves |
拉取已解题名单(区分队伍/个人),见 fetch_solved_names |
提交 flag 则走 POST /api/v1/challenges/attempt,并按 correct / already_solved / incorrect 三种状态给出可读反馈,见 submit_flag。
5 秒轮询原理:增量对比而非全量拉取 ⏱️
轮询器 CTFdPoller 在 backend/poller.py 中,默认 interval_s = 5.0。它的巧妙之处在 三次设计:
- 静默播种(Seed):启动时先拉一次题目和已解列表,只填充"已知状态",不触发任何事件——避免开局把存量题目当成"新题"误报;
- 集合差集检测:每 5 秒对题目名单和已解名单各做一次差集,
current - known得到new_challenge或challenge_solved事件,放入异步事件队列,核心逻辑见 _poll_once; - 防误报保护:如果本轮返回的题目数不足已知的一半,或已解数突然清零(通常是 API 抖动),直接跳过本轮,防止把故障当成"题目全没了"。
后台循环本身只有两行语义:sleep(5s) → poll_once(),见 _loop。
新题出现后:任务如何下发 🏁
Poller 产出事件后,真正的调度发生在共享协调器循环 run_event_loop(backend/agents/coordinator_loop.py),它同时服务 Claude 和 Codex 两种协调器后端:
- 开局指令:统计
CTF is LIVE: X 题 / Y 已解,把未解清单一次性告知 Coordinator LLM,并立即对所有未解题 自动预生成 Swarm(_auto_spawn_unsolved),即使 LLM 漏发指令也有兜底; - 新题秒级响应:每轮先取事件(5 秒超时),检测到
new_challenge就既通知 LLM("Spawn a swarm")又直接 自动拉起 Swarm; - 解出即止损:
challenge_solved事件到达时,自动kill()对应 Swarm,不再浪费 token; - 人机协同:内置一个本地 HTTP 端口,允许操作员在赛中大呼提示(Operator Message),与 solver 消息、Swarm 状态合并后一并交给 Coordinator,每 60 秒还附一条含花费($)的状态汇报。
任务下发的具体动作在 do_spawn_swarm 中,顺序是:
- 容量检查:活跃 Swarm 数达到
max_concurrent_challenges(默认 10,CLI--max-challenges可调)就排队等待; - 自动拉题:本地没有该题目录时,调用 pull_challenge 下载附件到
distfiles/,并把题目描述(HTML 转 Markdown)、分类、分值、标签、connection_info、hints 写入metadata.yml; - 启动竞速:构造
ChallengeSwarm(backend/agents/swarm.py),按模型 spec 分发到 Claude SDK / Codex / Pydantic AI 三类求解后端,为每个模型开独立 Docker 沙箱。
同队模型之间还能"串通":每道题内置一个 ChallengeMessageBus 消息总线,A 模型的发现(如"这道题是 RSA,e=65537")会被 B 模型在下一轮 prompt 中读到,避免重复踩坑。
快速上手:4 步跑通 CTFd 自动解题
# 1. 克隆仓库
git clone https://gitcode.com/gh_mirrors/ct/ctf-agent
cd ctf-agent
# 2. 安装依赖并构建解题沙箱镜像
uv sync
docker build -f sandbox/Dockerfile.sandbox -t ctf-sandbox .
# 3. 配置凭据(CTFd 地址/Token + 至少一家模型厂商的 API Key)
cp .env.example .env
# 4. 启动协调器,全自动解题
uv run ctf-solve \
--ctfd-url https://ctf.example.com \
--ctfd-token ctfd_your_token \
--challenges-dir challenges \
--max-challenges 10 -v
沙箱镜像定义在 sandbox/Dockerfile.sandbox,预装了 pwn/rev/crypto/forensics/stego 全谱系工具。不想连 CTFd?仓库根目录还有独立拉题脚本 pull_challenges.py,支持 Token 或账号密码两种认证,把题目下载到本地目录后即可用 --challenge 目录 单题调试。配置项集中管理在 backend/config.py,支持 .env 与环境变量双通道。
关键源码文件速查 📂
| 模块 | 路径 | 职责 |
|---|---|---|
| CTFd 客户端 | backend/ctfd.py | 认证、拉题、拉附件、提交 flag |
| 5 秒轮询器 | backend/poller.py | 增量检测新题 / 已解题,产出事件 |
| 协调器主循环 | backend/agents/coordinator_loop.py | 事件消费、自动 spawn / kill Swarm |
| 协调器工具函数 | backend/agents/coordinator_core.py | 拉题、下发 Swarm、读 solver 轨迹 |
| 解题蜂群 | backend/agents/swarm.py | 多模型竞速、flag 去重提交 |
| 消息总线 | backend/message_bus.py | 跨模型共享发现 |
| 模型阵容 | backend/models.py | 默认 5 模型 spec 与上下文窗口 |
| CLI 入口 | backend/cli.py | ctf-solve 参数解析 |
小结
CTF Agent 的 CTFd 链路可以浓缩为一条公式:轻量 stub 轮询(5s)→ 集合差集事件化 → Coordinator 事件循环 → 自动拉题 + 多模型 Swarm 竞速。它证明了在竞赛场景下,"轮询 + 增量检测 + 事件驱动"这套朴素而稳健的模式,足以支撑 100% 解题率的全自动作战——这套架构对任何需要持续监听外部平台状态并自动触发任务流的 Agent 项目,都有直接参考价值。