> ## 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.

# CyBench

> 使用 `CyBenchAdapter`、Docker 隔离和引导子任务评分，在 QitOS 上运行 CTF 风格安全评测。

CyBench 是一个夺旗赛（CTF）风格基准测试，用来评测智能体在安全分析任务上的表现，包括逆向工程、Web 利用、取证和密码学。任务运行在隔离环境中，得分通过比较智能体提交的答案与已知 flag 计算。

QitOS 提供：

* `CyBenchAdapter`
* `CyBenchRuntime`
* `score_cybench_submission`

因此你可以在 QitOS 执行内核上直接运行完整评测流程。

## 评分模式

| 模式             | 工作方式                    | 主指标                    |
| -------------- | ----------------------- | ---------------------- |
| **Guided**（默认） | 智能体按子任务逐步求解，并获得子任务级提示   | `guided_subtask_score` |
| **Unguided**   | 智能体只收到最终硬提示，需要直接拿到 flag | `unguided_success`     |

## 准备工作

<Steps>
  <Step title="安装基准测试依赖">
    ```bash theme={null}
    pip install "qitos[benchmarks]"
    ```
  </Step>

  <Step title="克隆 CyBench 仓库">
    ```bash theme={null}
    git clone https://github.com/andyzorigin/cybench.git references/cybench
    ```
  </Step>

  <Step title="安装 Docker">
    大多数 CyBench 任务都需要 Docker 启动挑战服务。
  </Step>

  <Step title="设置模型 API key">
    ```bash theme={null}
    export OPENAI_API_KEY="sk-..."
    ```
  </Step>
</Steps>

## 加载任务

```python theme={null}
from qitos.benchmark import CyBenchAdapter

adapter = CyBenchAdapter(
    cybench_root="references/cybench",
    run_with_subtasks=True,
)
records = adapter.load_records(limit=5)
tasks = adapter.to_tasks(records, split="guided")
```

一行式加载器：

```python theme={null}
from qitos.benchmark.cybench.adapter import load_cybench_tasks

tasks = load_cybench_tasks(
    cybench_root="references/cybench",
    run_with_subtasks=True,
    limit=10,
)
```

## 运行评测

优先使用官方命令行：

```bash theme={null}
qit bench run \
  --benchmark cybench \
  --split guided \
  --root references/cybench \
  --limit 20 \
  --output results/cybench_guided.jsonl \
  --model-name "Qwen/Qwen3-8B"
```

然后继续做聚合与检查：

```bash theme={null}
qit bench eval --input results/cybench_guided.jsonl --json
qita board --logdir runs
```

`cybench_eval.py` 依然保留，但它现在主要承担基准测试专用参考智能体封装器的角色。

运行单个引导任务：

```bash theme={null}
python examples/benchmarks/cybench_eval.py \
  --cybench-root references/cybench \
  --task-index 0 \
  --max-steps 12 \
  --model-name "Qwen/Qwen3-8B" \
  --api-key "$OPENAI_API_KEY"
```

运行非引导模式：

```bash theme={null}
python examples/benchmarks/cybench_eval.py \
  --cybench-root references/cybench \
  --task-index 0 \
  --unguided-mode \
  --max-steps 20 \
  --api-key "$OPENAI_API_KEY"
```

完整基准测试：

```bash theme={null}
python examples/benchmarks/cybench_eval.py \
  --run-all \
  --cybench-root references/cybench \
  --limit 50 \
  --max-workers 4 \
  --output-jsonl results/cybench.jsonl \
  --trace-logdir runs \
  --api-key "$OPENAI_API_KEY"
```

<Warning>
  CyBench 任务应始终运行在隔离环境中。挑战服务可能会开放端口或执行任意代码；生产评测建议启用 Docker 隔离。
</Warning>

## 智能体工具集

CyBench 评测智能体通常只注册一组适合 CTF 的最小工具面：

* `CodingToolSet`
* 终端执行
* `SubmitAnswer`

如有需要，也可以继续扩展浏览器工具。

## 评分与结果检查

`score_cybench_submission` 会统一计算：

* `guided_subtask_score`
* `guided_final_score`
* `unguided_success`
* `exact_matches`
* `partial_matches`

单条结果通常包含：

* `task_id`
* `mode`
* `success`
* `guided_subtask_score`
* `guided_final_score`
* `predictions`
* `references`
* `stop_reason`
* `steps`
* `latency_seconds`

评测结束后，仍然可以直接用：

```bash theme={null}
qita board --logdir runs
qita replay --run runs/<run_id>
```

来检查具体任务的追踪记录。