CyberGym服务端实现细节:滑动窗口限流、SQLite PoC数据库与分片存储设计
CyberGym服务端实现细节:滑动窗口限流、SQLite PoC数据库与分片存储设计
CyberGym 是一个大规模网络安全评测框架,用于评估 AI Agent 在真实漏洞分析任务中的能力。本文深入解析 CyberGym 服务端(Server)的实现细节:基于 FastAPI 的 PoC 提交服务、按 agent_id 维度的滑动窗口限流、基于 SQLite 的 PoC 数据库,以及两级哈希目录的分片存储设计,帮助你在部署评测环境时理解每个组件的设计动机。
一、服务端整体架构 🏗️
CyberGym 服务端由 main.py 定义,基于 FastAPI + uvicorn 构建,核心职责是接收 Agent 提交的 PoC(Proof of Concept,漏洞触发样本),在 Docker 沙箱中运行并返回退出码与输出。
服务端暴露两类路由(见 main.py#L131-L132):
| 路由 | 端点 | 用途 |
|---|---|---|
| 公开路由 | POST /submit-vul |
Agent 提交 PoC,在"含漏洞版本"上验证是否触发崩溃 |
私有路由(需 X-API-Key 头) |
POST /submit-fix |
在"修复版本"上验证 PoC 不再触发 |
| 私有路由 | POST /query-poc |
按 agent_id / task_id 查询 PoC 记录 |
| 私有路由 | POST /verify-agent-pocs |
对某 Agent 的全部 PoC 做复验 |
所有配置集中在 types.py#L9-L26 的 ServerConfig(Pydantic Settings),支持命令行参数与 CYBERGYM_ 前缀环境变量覆盖,例如 --db_path、--rate_limit_max_requests 等(见 main.py#L235-L274)。
二、滑动窗口限流:保护沙箱不被打爆 🛡️
Agent 在迭代调试时可能高频提交 PoC,而每次提交都会启动 Docker 容器并运行目标程序。为防止资源被耗尽可能,服务端内置了滑动窗口限流器 RateLimiter(rate_limiter.py)。
其工作机制非常简洁:
- 按 agent_id 分桶:内部用
dict<a href="https://link.gitcode.com/i/321706b9c9276e76a9087bdcf96a3c85" target="_blank">str, deque[float]]为每个 Agent 维护一个时间戳队列([rate_limiter.py#L14); - 滑动窗口判断:每次
check()时,先弹出窗口之外的过期时间戳,若队列长度已达max_requests,抛出 HTTP 429(rate_limiter.py#L18-L38); - 线程安全:全程用
threading.Lock保护,避免 FastAPI 并发请求下的竞态; - 惰性清理:
_purge_stale每隔一个窗口周期运行一次,删除所有条目已过期、彻底空闲的 Agent 桶,防止字典无限膨胀(rate_limiter.py#L40-L44)。
默认配置为 60 秒内每个 Agent 最多 20 次请求(types.py#L20-L21),可通过启动参数 --rate_limit_max_requests 与 --rate_limit_window_seconds 调整。相比"固定窗口"方案,滑动窗口在窗口交界处不会突发双倍的请求通过,对评测公平性更友好。
限流检查发生在通过校验和验证之后(main.py#L154-L157),也就是说:签名不合法的请求直接被 400 拒绝,不占用限流配额。
三、SQLite PoC 数据库:记录、去重与缓存 🔍
PoC 的元数据统一存储在单文件 SQLite 数据库中,默认路径为 ./poc.db(由 --db_path 指定)。数据模型 PoCRecord 定义在 pocdb.py#L16-L28:
| 字段 | 说明 |
|---|---|
agent_id / task_id |
提交方与任务标识,均建索引 |
poc_id |
随机 UUID,全局唯一,作为 PoC 在磁盘上的主键 |
poc_hash |
PoC 内容的 SHA-256,用于去重 |
poc_length |
PoC 字节数 |
vul_exit_code / fix_exit_code |
分别在含漏洞/修复版本上的运行退出码 |
created_at / updated_at |
UTC 时间戳 |
设计上值得注意的几点:
- 复合唯一约束
(agent_id, task_id, poc_hash):同一 Agent 对同一任务提交相同内容的 PoC 不会重复建记录,实现天然的去重 + 结果缓存——再次提交时直接返回磁盘上保存的output.{mode}文件内容,不再启动容器(server_utils.py#L223-L248); - WAL 日志模式:
init_engine在每个连接上执行PRAGMA journal_mode=WAL和PRAGMA synchronous=NORMAL,显著提升并发读写性能(pocdb.py#L91-L108); - 连接池参数:
check_same_thread=False+ 30 秒锁等待 + 8 常驻 / 16 溢出连接,适配 FastAPI 的多工作线程访问单文件数据库的场景。
评测结束后,可用 verify_agent_result.py 拉取某个 agent_id 的全部记录并触发 /verify-agent-pocs 复验,服务端会跳过已触发崩溃(vul_exit_code 为 0 或 300)的样本,只重跑未复现的 PoC(main.py#L207-L228)。
四、分片存储设计:让海量文件不塌方 📁
CyberGym 会接收成千上万个 PoC 文件与运行日志,若全部堆在一个目录下,文件系统的目录查找会急剧退化。服务端采用两级哈希分片方案:
logs/ab/cd/1234abcd.../
├── poc.bin # PoC 原始内容
├── output.vul # 含漏洞版本运行输出
└── output.fix # 修复版本运行输出
实现仅一行核心逻辑:取 poc_id 前 2 个字符作为一级目录、第 3~4 位作为二级目录(server_utils.py#L198-L200)。UUID 十六进制的均匀分布使文件近似均匀地散列到 65536 个子目录中,单目录文件数始终保持在极低的水平。
同样的"分片"思想也体现在服务端数据集的分片下载上:完整评测数据约 10TB,官方将其切成 cybergym-oss-fuzz-data.7z.part-aa ~ part-bb 共 30 个分片(download_chunks.sh),下载完成后用 cat part-* > 完整归档 拼接还原——分片粒度让大文件传输可以断点续传、并行下载。若只做静态评测,也可用 download_binary_only_runners.py 拉取约 130GB 的纯二进制模式运行器镜像,或 download_subset.py 拉取 10 个任务的子集快速体验。
五、一次提交的完整旅程 ✈️
把前面的组件串起来,/submit-vul 请求(main.py#L135-L166)的处理链路是:
- 大小校验:上传文件超过
max_file_size_mb(默认 10MB)直接 413; - 校验和验证:
sha256(task_id + agent_id + salt)必须匹配,防止伪造身份(task/types.py#L47-L54),同时借助 mask_map.json 中的任务 ID 掩码保护题目来源(task/mask.py); - 限流检查:
rate_limiter.check(agent_id); - 哈希去重:查 SQLite,命中缓存则直接返回;
- 落盘 + 沙箱执行:PoC 写入分片目录,Docker 容器以
network_mode="none"隔离网络、只读挂载 PoC,10 秒命令超时(exit 137 映射为自定义退出码 300 表示超时未崩溃)(server_utils.py#L70-L109); - 回写结果:运行输出存盘,
vul_exit_code更新进数据库。
六、快速启动 CyberGym 服务端 🚀
# 安装服务端依赖
pip3 install -e '.[server]'
# 启动 PoC 提交服务
python3 -m cybergym.server \
--host 0.0.0.0 --port 8666 \
--mask_map_path mask_map.json \
--log_dir ./server_poc \
--db_path ./server_poc/poc.db
二进制模式追加 --binary_dir <数据目录> 即可(见 README.md 的 Evaluation 一节)。服务端日志采用滚动文件策略,单文件 10MB、保留 5 份(main.py#L25-L55)。
七、小结
CyberGym 服务端的三个设计各有明确的工程目标:
- 滑动窗口限流:细粒度、线程安全,保护昂贵的 Docker 沙箱资源;
- SQLite PoC 数据库:单文件即可运维,WAL + 唯一约束带来性能与去重双重收益;
- 两级哈希分片存储:以极低的实现成本换取万级文件规模下的稳定 I/O 性能。
这套"轻量、自洽、可审计"的架构,正是它能够支撑大规模 AI Agent 安全评测的关键所在。