# BoxPwnr — LLM-Driven CTF/Pentest Runner (Docker)

> BoxPwnr runs CTF and pentest-style targets in a Kali Docker executor, using an LLM to script commands with budgets, timeouts, and resumable progress.

## Install

Copy the content below into your project:

## Quick Use

```bash
git clone --recurse-submodules https://github.com/0ca/BoxPwnr
cd BoxPwnr

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

uv run boxpwnr --platform htb --target meow
```

## Intro

BoxPwnr runs CTF and pentest-style targets in a Kali Docker executor, using an LLM to script commands with budgets, timeouts, and resumable progress.

- **Best for:** Running repeatable, budgeted security task attempts (CTFs, labs, benchmarks) with a clean executor boundary
- **Works with:** Docker; `uv` (Python dependency manager); supports multiple platforms and model providers (per README)
- **Setup time:** 10–25 minutes

## Practical Notes

- GitHub: 393 stars · 46 forks; pushed 2026-05-12 (verified via GitHub API).
- README requires cloning with submodules and running `uv sync` to create `.venv` before `uv run boxpwnr …`.
- README documents hard limits like `--max-turns`, `--max-cost`, and execution timeouts (default 30s, max 300s).

## Main

A useful BoxPwnr pattern for teams:

1. Define a **target catalog** (labs/benchmarks) and run with consistent flags (`--max-turns`, `--max-cost`) so results are comparable.
2. Keep the executor boundary strict: everything runs inside the Docker environment; your host stays clean.
3. Use `--generate-progress` / `--resume-from` to create handoffs between attempts instead of restarting from scratch.
4. When a task is “almost solved”, switch to manual follow-up (or keep the target running) and treat the LLM as a coordinator, not a miracle worker.

This keeps experimentation fast while still producing artifacts you can review later.

### FAQ

**Q: Do I need Docker?**
A: Yes. README says BoxPwnr requires Docker to be installed and running.

**Q: How do I control cost/time?**
A: Use `--max-cost`, `--max-turns`, and execution timeout flags described in the README.

**Q: What’s the minimal run command?**
A: After `uv sync`, run `uv run boxpwnr --platform htb --target meow` (example from README).

## Source & Thanks

> Source: https://github.com/0ca/BoxPwnr
> License: AGPL-3.0
> GitHub stars: 393 · forks: 46

---

<!-- ZH -->

## 快速使用

```bash
git clone --recurse-submodules https://github.com/0ca/BoxPwnr
cd BoxPwnr

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

uv run boxpwnr --platform htb --target meow
```

## 简介

BoxPwnr 在 Docker 里的 Kali 环境执行靶场/CTF 任务，用 LLM 编排命令并支持 max-turns/max-cost 等预算限制，还能生成可恢复的进度文件用于续跑。

- **适合谁：** 需要“可重复 + 有预算上限”的安全任务尝试（CTF/靶场/基准）
- **可搭配：** Docker；`uv` 依赖管理；支持多平台与多模型提供方（见 README）
- **准备时间：** 10–25 分钟

## 实战建议

- GitHub：393 stars · 46 forks；最近更新 2026-05-12（GitHub API 验证）。
- README 要求带子模块克隆，并用 `uv sync` 初始化环境，然后 `uv run boxpwnr …` 执行。
- README 提供硬约束：`--max-turns`、`--max-cost`，以及默认/最大执行超时（30s / 300s）。

## 主要内容

团队落地 BoxPwnr 的一个好用模式：

1. 做一个 **目标目录**（靶场/基准/CTF），并统一参数（`--max-turns`、`--max-cost`），保证不同尝试可对比。
2. 执行边界保持干净：所有命令跑在 Docker/Kali 里，主机环境不被污染。
3. 用 `--generate-progress` / `--resume-from` 做交接，不用每次重来。
4. 接近成功时转入人工跟进（或 keep target），把 LLM 当作编排者而不是“魔法棒”。

这样既快又能留下可复盘的产物。

### FAQ

**必须要 Docker 吗？**
答：是的。README 明确要求 Docker 已安装并运行。

**怎么控制成本/时间？**
答：用 README 提到的 `--max-cost`、`--max-turns` 以及执行超时参数。

**最小运行命令是什么？**
答：完成 `uv sync` 后，按 README 示例执行 `uv run boxpwnr --platform htb --target meow`。

## 来源与感谢

> Source: https://github.com/0ca/BoxPwnr
> License: AGPL-3.0
> GitHub stars: 393 · forks: 46


---
Source: https://tokrepo.com/en/workflows/boxpwnr-llm-driven-ctf-pentest-runner-docker
Author: Agent Toolkit