> ## Documentation Index
> Fetch the complete documentation index at: https://qitor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CyberGym

> 使用 `qitos.benchmark.cybergym`、外部同步的 `cybergym_agent` 和 QitOS 追踪记录，在 CyberGym 上运行安全漏洞 PoC 基准测试。

CyberGym 是一个面向漏洞触发与 PoC 生成的安全基准测试。任务通常会提供漏洞版本代码、描述信息和一个 `submit.sh`，智能体需要构造输入，让有漏洞版本触发异常，并最终通过已修复版本验证。

这次集成把 CyberGym 放进了 QitOS 的正式基准测试结构里：

* `qitos.benchmark.cybergym`
* `qitos.recipes.benchmarks.cybergym`
* `examples/benchmarks/cybergym_eval.py`

同时把运行产物统一放到 `runs/cybergym/` 下，便于直接用 `qita` 查看追踪记录。

注意：这次集成不直接提交 `cybergym_agent` 代码。运行前需要维护者手动把 `cybergym_agent` 仓库同步到 `qitos/benchmark/cybergym/agent/`。

## 集成结构

QitOS 侧的主要文件：

* `qitos/benchmark/cybergym/adapter.py`
* `qitos/benchmark/cybergym/runtime.py`
* `qitos/benchmark/cybergym/evaluator.py`
* `qitos/benchmark/cybergym/scorer.py`
* `qitos/benchmark/cybergym/runner.py`
* `qitos/recipes/benchmarks/cybergym.py`
* `examples/benchmarks/cybergym_eval.py`

职责划分：

* `adapter.py`：把 CyberGym 的 `task_id` 转成 QitOS `Task`
* `runtime.py`：生成任务目录并附加运行时元信息
* `runner.py`：调起外部同步进来的 `cybergym_agent`、写追踪记录、返回标准结果
* 方案：可复现基线
* 示例：最薄的一层命令入口

## 同步 `cybergym_agent`

运行前，需要先把 `cybergym_agent` 仓库同步到 QitOS 里。下面命令在 QitOS 仓库根目录执行：

```bash theme={null}
mkdir -p qitos/benchmark/cybergym/agent
rsync -a \
  --exclude .git \
  --exclude __pycache__ \
  --exclude test_agent.py \
  ../cybergym_agent/ \
  qitos/benchmark/cybergym/agent/
```

如果没有这一步，`qitos.benchmark.cybergym.runner` 会在运行时直接报错，提示先复制 `cybergym_agent`。

## 准备工作

<Steps>
  <Step title="准备 CyberGym 数据目录">
    确保可以访问 `cybergym_data/data`，例如放在 QitOS 同级目录的 `../cybergym/cybergym_data/data`。
  </Step>

  <Step title="启动 CyberGym 服务器">
    需要一台能运行 Docker 镜像的 CyberGym 服务器。示例：

    ```bash theme={null}
    cd ../cybergym
    python -m cybergym.server \
      --host 127.0.0.1 \
      --port 8669 \
      --log_dir ../qitos/runs/cybergym/server_poc \
      --db_path ../qitos/runs/cybergym/server_poc/poc.db
    ```
  </Step>

  <Step title="设置模型与验证密钥">
    ```bash theme={null}
    export CYBERGYM_CLAUDE_AUTH_TOKEN="your-model-key"
    export CYBERGYM_API_KEY="your-verify-key"
    ```
  </Step>
</Steps>

## 单任务运行

从 QitOS 仓库根目录运行：

```bash theme={null}
python examples/benchmarks/cybergym_eval.py \
  --task-id arvo:1065 \
  --data-dir ../cybergym/cybergym_data/data \
  --out-dir runs/cybergym/workspace/arvo_1065 \
  --server http://127.0.0.1:8669 \
  --difficulty level1 \
  --model-name GLM-5.1-sii \
  --api-key "$CYBERGYM_CLAUDE_AUTH_TOKEN" \
  --base-url https://your-openai-compatible-endpoint/v1 \
  --max-steps 30 \
  --trace-logdir runs/cybergym/traces
```

## 批量跑 100 个任务

假设 `tasks.txt` 每行一个 `task_id`：

```text theme={null}
arvo:1065
arvo:3938
oss-fuzz:42535201
...
```

从 QitOS 仓库根目录顺序跑：

```bash theme={null}
export TASKS_FILE=./tasks.txt
export SERVER=http://your-cybergym-server:8669

while read -r TASK_ID; do
  [ -z "$TASK_ID" ] && continue
  SLUG="${TASK_ID/:/_}"
  echo "===== START $TASK_ID ====="
  python examples/benchmarks/cybergym_eval.py \
    --task-id "$TASK_ID" \
    --data-dir ../cybergym/cybergym_data/data \
    --out-dir "runs/cybergym/workspace/$SLUG" \
    --server "$SERVER" \
    --difficulty level1 \
    --model-name GLM-5.1-sii \
    --api-key "$CYBERGYM_CLAUDE_AUTH_TOKEN" \
    --base-url https://your-openai-compatible-endpoint/v1 \
    --max-steps 30 \
    --trace-logdir runs/cybergym/traces
  echo "===== END $TASK_ID ====="
done < "$TASKS_FILE" | tee runs/cybergym/run-100.log
```

小并发时可以自行改成 `xargs -P 2` 或 `xargs -P 4`，但建议先验证模型端和服务器端的稳定性。

## 批量验证

CyberGym 的公开 `/submit-vul` 只返回漏洞侧结果。完整基准测试判定还需要修复侧验证。

在 `cybergym` 仓库根目录运行：

```bash theme={null}
python scripts/verify_batch_results.py \
  --logs_dir ../qitos/runs/cybergym/logs \
  --server http://your-cybergym-server:8669 \
  --pocdb_path ../qitos/runs/cybergym/server_poc/poc.db \
  --summary_json ../qitos/runs/cybergym/verify-summary.json
```

只看当前数据库状态、不真正发验证：

```bash theme={null}
python scripts/verify_batch_results.py \
  --logs_dir ../qitos/runs/cybergym/logs \
  --server http://your-cybergym-server:8669 \
  --pocdb_path ../qitos/runs/cybergym/server_poc/poc.db \
  --skip_verify
```

## 追踪记录与产物

运行后主要产物在：

* `runs/cybergym/workspace/`
* `runs/cybergym/server_poc/`
* `runs/cybergym/traces/`

查看追踪记录：

```bash theme={null}
qita board --logdir runs/cybergym/traces
```

QitOS 追踪记录会写出：

* `manifest.json`
* `events.jsonl`
* `steps.jsonl`

## 当前状态

这次集成已经验证了：

* CyberGym 任务能转成 QitOS `Task`
* 基准测试族已注册到 `qitos.benchmark`
* 方案和薄示例能正常调用同一条运行器
* 真实冒烟测试可以生成任务、初始化 `GLM-5.1-sii`、写出 QitOS 追踪记录

当前已知限制是模型协议还没有完全对齐。`GLM-5.1-sii` 目前更倾向输出 `<tool_call>...` 风格内容，而当前智能体还走 `JsonDecisionParser` 期望纯 JSON，因此在短冒烟测试里会停在解析器错误。这是下一步要处理的协议适配问题，不是 CyberGym 基准测试结构接入问题。