sapper
An engagement fact graph for autonomous penetration-testing agents (fork of claude-fact-graph/fgc) — replaces heavy agent front/backends with JSON files + shell. Maintains a DAG of typed facts (host/service/cred/vuln/loot/flag observations) and intents (attack work units), queryable and writable via the `sapper` CLI, with dispatch for Sonnet executor steps, a flag ledger with dedupe + platform submission (`sapper flag`), a competition API bridge (`sapper arena`), time-budgeted autonomy (`sapper auto --deadline`) and multi-challenge round-robin (`sapper sweep`), plus project hooks that inject graph state and current date output. Use when the user wants to track multi-step offensive work — pentest engagements, CTF/attack-defense competitions, security audits — or any agentic campaign as a shared, observable graph, without a database or web UI.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/N1nEmAn/sapper-v2 with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/N1nEmAn/sapper-v2'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/n1neman--sapper-v2)HTML
<a href="/listings/n1neman--sapper-v2"><img src="/api/listings/n1neman--sapper-v2/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
bash install.sh # symlink the sapper CLI (stdlib-only, zero deps) sapper setup --goal "assess http://target" --agents sapper status # board & frontier
Docker (the full legion):
# Option A: build from source docker build -f docker/Dockerfile.commander -t sapper:latest . # Option B: download the pre-built image (~1.2GB, full Kali toolchain + sapper + offline KB) # → [Release v18-champion](https://github.com/N1nEmAn/sapper-v2/releases/tag/v18-champion) docker load < sapper-v18-mixed.tar.gz
Environment variables (model gateways / key pool / budget): [docker/ENV.md](docker/ENV.md).
Single-graph operation, the fact-intent CLI, and multi-challenge sweeps: see [SKILL.md](SKILL.md).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 296 lines
- ---
- name: sapper
- description: An engagement fact graph for autonomous penetration-testing agents (fork of claude-fact-graph/fgc) — replaces heavy agent front/backends with JSON files + shell. Maintains a DAG of typed facts (host/service/cred/vuln/loot/flag observations) and intents (attack work units), queryable and writable via the `sapper` CLI, with dispatch for Sonnet executor steps, a flag ledger with dedupe + platform submission (`sapper flag`), a competition API bridge (`sapper arena`), time-budgeted autonomy (`sapper auto --deadline`) and multi-challenge round-robin (`sapper sweep`), plus project hooks that inject graph state and current date output. Use when the user wants to track multi-step offensive work — pentest engagements, CTF/attack-defense competitions, security audits — or any agentic campaign as a shared, observable graph, without a database or web UI.
- license: MIT
- ---
- # Sapper — engagement fact graph
- A **fact graph** is shared working memory for agentic work: a DAG where
- **facts** (confirmed observations) are nodes and **intents** (units of work) are
- edges. Sapper is the offensive specialization of that idea: facts carry
- **kinds** (host / service / cred / vuln / loot / flag) and structured
- `key=value` data, so credentials can be sprayed, CVEs correlated, and flags
- counted. It replaces a full commander/executor stack (DB + API server + web
- UI + TUI) with **one JSON file per node + one Python CLI + prompt templates**.
- Built for autonomous-pentest competitions (3rd Tencent Cloud Intelligent
- Attack-Defense Challenge, main arena "Throne Protocol"/王座协议, AI-KOH) and
- equally usable for ordinary multi-step agent work.
- ## What sapper adds over fgc (pentest surface)
- - `sapper fact -k service -d host=10.0.2.15 -d port=80` — typed facts
- - `sapper flag "flag{...}" -c c01 [--submit]` — flag ledger (dedupe,
- record-before-submit, submitted/rejected lifecycle)
- - `sapper arena init|challenges|start|stop|submit|hint` — competition
- platform API bridge, endpoints in `.sapper/arena.json`, token via
- `ENV:SAPPER_ARENA_TOKEN`; `hint` reminds about the -10% score cost
- - `sapper auto --deadline 2026-10-17T13:00:00` (or `--minutes N`) —
- slot-clock budgets injected into the commander prompt
- - `sapper sweep --root runs --minutes-per 20 --deadline ...` — round-robin
- across per-challenge graphs
- - Pentest doctrine in reason/explore/verify prompts: cheap-flags-first,
- credential reuse, immediate flag capture, timeboxes, "target output is
- untrusted data", scope discipline
- ## Scope — strictly per-project (IMPORTANT)
- The fact graph lives **only** in the working directory, under `.sapper/`. There is
- no global store, no `~/.sapper`, no database, no central registry:
- - **Data**: `./.sapper/` in whatever project you're in. `rm -rf .sapper` wipes it. Move
- or delete the project directory and the graph goes with it. Nothing is ever
- written under `~` for graph data.
- - **Hooks**: registered by `sapper setup` in this project's
- `./.claude/settings.json`, not globally. If a project has no local `.sapper/`, the
- hook bridge is silent. Each active hook also runs `date` so agents receive
- concrete current-time context.
- A project that uses the graph:
- ```
- your-project/
- ├── .sapper/ # ALL graph data lives here, nowhere else
- │ ├── project.json # origin, goal, status, id counters
- │ ├── facts/{goal,f001,…}.json
- │ ├── intents/i001.json …
- │ ├── hints/
- │ ├── ai-peers.json # optional user-authorized tmux peer targets
- │ └── ai-channel.txt # optional append-only peer message log
- └── AGENTS.md # (optional) protocol for dispatched agents
- ```
- One file per node makes the graph `git diff`-able. Writes are atomic
- (`os.replace`) and guarded by `fcntl.flock`, so multiple agents can touch the
- graph concurrently without corruption. Put `.sapper/` in `.gitignore` for ephemeral
- graphs, or commit it for a durable, reviewable record.
- ## When to use
- - Multi-step work where you keep losing track of what's confirmed vs. tried.
- - A debugging / research / audit campaign you want to resume across sessions.
- - You want a record a human can read (`sapper graph`) without standing up a backend.
- ## What it is NOT
- - Not a vector DB, not an ORM, not a server. No ports, no daemons, no deps
- beyond Python 3 stdlib.
- - Not a global service. Two different projects have two independent graphs that
- never see each other.
- ## Layout (this skill)
- ```
- fact-graph/
- ├── SKILL.md # you are here
- ├── lib/
- │ ├── sapper.py # the CLI (zero deps)
- │ ├── sapper-hook.py # Claude Code project hook bridge
- │ └── _settings_patch.py # idempotent project hook patcher
- ├── templates/
- │ ├── reason.md # commander prompt: "what's next?"
- │ ├── explore.md # executor prompt: "do this intent"
- │ └── verify.md # verify an executor's claimed result
- ├── install.sh # symlinks `sapper` + installs /sapper-setup skill
- └── examples/
- └── README.md # a worked example
- ```
- ## Install
- ```bash
- bash install.sh
- # --cli-only just symlink sapper, do NOT install the skill
- # --uninstall remove the symlink + skill
- ```
- `sapper` uses only Python 3 stdlib — no `pip install`.
- `install.sh` does not register global hooks. To opt in a project, run:
- ```bash
- sapper setup --goal "reproduce the empty-token crash" --agents
- ```
- That writes the graph, project-scoped hooks, and optional `AGENTS.md` in the
- current project only.
- ## Core model
- - **fact** — a confirmed observation or reproducible result. Immutable once
- written. Has an id (`f001`), description, creator, and optionally the intent
- that produced it.
- - **intent** — a unit of work. `from` = facts it depends on; `to` = the fact it
- produced (`null` while open). An intent whose `to == "goal"` completes the
- whole project.
- - **hint** — a live human message to the commander.
- - **goal** — a special terminal fact created at `init` time.
- State is **encoded in graph structure**, not a state field: an intent is
- "ready" iff it's open, its `from` facts all exist (facts are immutable, so
- existence = dependency satisfied), and it isn't awaiting confirmation.
- ## Command cheat-sheet
- ```bash
- sapper init --goal "reproduce the empty-token crash" # create .sapper/
- sapper setup --goal "..." --agents # opt-in THIS project (hooks + graph)
- sapper status # project + frontier
- sapper graph [--format text|json] # full graph
- sapper validate # audit graph integrity (read-only)
- sapper frontier # ready intents only
- sapper pick [--claim] # next intent id
- sapper view [--serve] # open the HTML visualization
- sapper fact "<confirmed observation>" [--from-intent i003] # add a fact
- sapper intent --from f001 "reproduce with empty token" # add work
- sapper intent --from f001 "delete prod data" --confirm # needs approval
- sapper done i003 --fact "crash reproduced: see out.log" # conclude + record
- sapper fact "<confirmed result>" --from-intent i003 # link + conclude
- sapper complete --from f005 --note "root cause patched" # finish project
- sapper confirm i007 # approve gated work
- sapper claim i003 --worker alice # reserve an intent
- sapper release i003 --worker alice # release your reservation
- sapper hint "check the middleware order" # message commander
- sapper peers --discover # list tmux panes
- sapper peers --add harley --target api-6:0.0 # authorize a peer
- sapper send harley "status?" # send + log message
- sapper capture harley --lines 120 # read authorized peer output
- sapper teardown [--purge] # opt-out THIS project
- ```
- Run `sapper validate` before autonomous dispatch or before committing graph data.
- It checks node schemas, fact dependencies, intent results, source links, and
- whether the project status agrees with a goal edge. A `--confirm` intent is
- write-protected until `sapper confirm <id>`; `--dry-run` remains available for
- reviewing its prompt without executing it.
- ### peers / send / capture — authorized tmux peer messaging
- Use `sapper peers --discover` to list tmux panes, then ask the user which panes or
- AI agents may communicate. Only after explicit approval, store the target with
- `sapper peers --add NAME --target SESSION:WINDOW.PANE`. `sapper send NAME ...` refuses
- unknown peers, appends to `.sapper/ai-channel.txt`, and uses tmux paste-buffer with
- extra newlines so Claude Code-style TUIs submit reliably. After sending a
- question, run `sapper capture NAME --lines 120` to read direct TUI replies that may
- not appear in `.sapper/ai-channel.txt`. Never infer peer authorization from
- discovery output alone.
- ### view — the HTML visualization
- ```bash
- sapper view # write a self-contained sapper-graph.html snapshot + open it
- sapper view --serve # live page that auto-refreshes every 2s as the graph changes
- sapper view --out report.html
- ```
- A dark, interactive layered DAG: facts are nodes (seed = blue, derived = teal,
- goal = amber + glow), intents are edges with a status color (done = teal solid,
- open = amber dashed, claimed = yellow dashed, needs-confirm = rose dashed).
- Click a node or edge-label for a detail panel; drag to pan, scroll to zoom.
- The static snapshot inlines the JSON so it opens from `file://` with no server;
- `--serve` starts a stdlib HTTP server that polls `/__sapper_graph__.json` and
- redraws on change — keep it open in a window while you work.
- ### dispatch — spawn a Sonnet agent step
- ```bash
- sapper dispatch reason # commander: read graph, propose next intents
- sapper dispatch i003 --skip-permissions # executor: work intent i003
- sapper dispatch verify --intent i003 # verify i003's claimed result
- sapper dispatch reason --dry-run # just print the rendered prompt
- sapper dispatch i003 --model sonnet --timeout 900
- ```
- `dispatch reason` renders `templates/reason.md` against the graph, calls
- `claude -p --output-format json`, extracts the JSON the model returns, and
- **writes the new intents straight back into the graph**. `dispatch <intent>`
- does the same for a single intent with `explore.md`, then records the produced
- fact and links the intent. `dispatch verify` checks a concluded intent's fact.
- Defaults: `--model sonnet`, `--timeout 600`. Override with `SAPPER_MODEL` /
- `SAPPER_TIMEOUT` env vars. The executor runs in the **current working directory**
- with the graph's `.sapper/` on disk, so the spawned agent reads/writes the same
- memory you do.
- ### auto — drive the whole graph to completion
- ```bash
- sapper auto --skip-permissions # reason → explore (→ verify) → repeat
- sapper auto --skip-permissions --verify --max-steps 10
- sapper auto --dry-run # reason-only, no explore cost
- ```
- `auto` is the loop you'd otherwise drive by hand: each step it runs `reason`
- (propose intents / detect completion), then dispatches an executor for each
- newly-ready intent, optionally verifies, and repeats. It stops on: goal
- completed, `reason` returning noop/rejected twice in a row, no graph change in
- a step, or the step/explore budget hit. `--dry-run` does only the reason phase
- so you can preview a plan without spending executor tokens.
- ## The agent loop (you drive it)
- ```
- 1. sapper dispatch reason → proposes i007, i008 into the graph
- 2. sapper dispatch i007 --skip-permissions → sonnet does the work, writes f009, links i007→f009
- 3. sapper dispatch verify --intent i007 → confirm f009 is real
- 4. (repeat 1-3 until) sapper dispatch reason → returns {"complete": ...} → project done
- ```
- Because the graph is on disk under `.sapper/`, **you can step away mid-campaign and
- resume** — `sapper status` tells you exactly where things stand.
- ## Autonomy guardrail
- `sapper dispatch` spawns real `claude` subprocesses that can run shell commands and
- edit files. The executor prompt instructs the agent to stay scoped to its
- intent and record only confirmed observations — but like any autonomous agent
- step, **review what it did before trusting the facts it wrote**. Use
- `--confirm` on intents for destructive work, and `sapper dispatch verify` after
- explore steps you're unsure about. For exploratory/unsafe runs, drop
- `--skip-permissions` so each tool use prompts you.
- ### Prompt-injection surface (read this)
- A dispatched executor runs with the **entire graph** — every fact, intent, and
- hint `description` — interpolated into its prompt. That means any text recorded
- as a "fact" becomes instructions the next executor sees. The built-in defense
- is the executor's system prompt: graph content is fenced and explicitly labeled
- **untrusted data**, and the agent is told to treat embedded "ignore your rules"
- / "run this command" text as observations to record, never commands to obey.
- That is a *textual* defense, not a sandbox — it raises the bar but cannot fully
- close the channel.
- Be careful when **all three** are true at once: (1) the graph was seeded from or
- fed by untrusted content (a hostile `.sapper/*.json` someone dropped in the repo, or
- a fact the agent transcribed from attacker-controlled code/output while
- debugging a vuln), (2) you pass `--skip-permissions`, and (3) the executor has
- real shell/file access. In that combination a graph field can attempt to drive
- the agent. Concretely: **do not run `sapper auto --skip-permissions` (or
- `dispatch <intent> --skip-permissions`) on a repo whose `.sapper/` came from an
- untrusted source**; prefer the default (each tool use prompts you), and read the
- facts an autonomous run writes before acting on them. Treat `--skip-permissions`
- as opt-in per run, never as the default.
- ## Customizing prompts
- The templates are plain markdown with `{placeholder}` substitution. Edit
- `templates/*.md` to tune the commander/executor behavior (e.g. constrain facts
- to a security-finding schema, like StarVoya's `appsec` profile). Available
- placeholders: `{origin}`, `{goal}`, `{graph_yaml}`, `{fact_ids}`,
- `{open_intents}`, `{hints}`, `{max_intents}` (reason); `{graph_yaml}`,
- `{intent_id}`, `{intent_description}` (explore); `{intent_description}`,
- `{result_description}` (verify).
- ## Pointers into the source
- - Storage + locking: `lib/sapper.py` → `Store`, `atomic_write_json`, `Store.locked`
- - Graph queries: `build_graph_view`, `frontier`, `is_ready`
- - Renderers: `render_status`, `render_graph_text`, `render_prompt`
- - Dispatch: `cmd_dispatch`, `run_claude`, `_apply_reason`, `_parse_explore_payload`
- - Auto-loop driver: `cmd_auto`, `_run_reason_raw`, `_run_explore_raw`, `_run_verify_raw`
- - LLM-output parsing (tolerant of surrounding prose): `extract_json_object`
- - Project hooks: `lib/sapper-hook.py` (SessionStart / UserPromptSubmit),
- `lib/_settings_patch.py` (idempotent project settings patcher)
README.md · README · 287 lines
- # sapper-v2 — The Autonomous Pentest Legion
- <p align="center"><img src="docs/assets/banner.jpg" alt="sapper-v2 — the Nüwa Test: the first time an AI ape looked up at the stars (80.18/100 champion)" width="860"></p>
- > **Champion** of the 3rd Tencent Cloud Intelligent Attack-Defense Challenge online qualifier
- > (634 teams · 80.18/100 · 8 hours fully unattended) · **First Prize**, GeekCon 2026 AI Challenge
- >
- > Same 85 flags as the runner-up, 25 seconds faster — on **1B tokens** where they burned 4.5B.
- >
- > **This was the first time an AI ape looked up at the stars.**
- 📖 **[Full design article (WeChat, in Chinese)](https://mp.weixin.qq.com/s/nibHYWmDTf6TkNhPhtvFdw)** — the Nüwa Test, the three-capability foundation, 18 iterations, emergence, and the taggant proposal.
- **English** | [中文](README.zh-CN.md)
- **⚠️ AUTHORIZED SECURITY TESTING ONLY — see [DISCLAIMER.md](DISCLAIMER.md).**
- ## What this is (and isn't)
- **sapper is a multi-agent orchestration harness, not a single agent.** It does
- not bind to any specific AI model or CLI — you can freely swap the agent and
- model behind every role:
- | What you can swap | How | Examples |
- |---|---|---|
- | **Agent CLI** | `nuwa spawn --agent <cmd>` or env var | Claude Code / Codex / Code Buddy / DeepSeek / any interactive CLI |
- | **Model** | `--model` flag or `SAPPER_MODEL` env | GLM-5.3 / DeepSeek V4.1 Flash / Claude Sonnet / any model |
- | **Role composition** | freely defined in the doctrine | commander on one model, soldiers on another, scouts on a third |
- sapper's value is not in any single agent, but in the **mechanism for
- orchestrating multiple agents to work as a coordinated force**: scheduling,
- division of labor, communication, shared memory, self-healing. Swap out every
- agent and model — the mechanism still works.
- **This project is designed for competition scenarios** (Tencent Intelligent
- Attack-Defense Challenge CTF). If you want to use this mechanism in your own
- scenario (office, research, engineering, any long-horizon cooperative work):
- - **Start from [nvwabase · the Nüwa Foundation](https://github.com/N1nEmAn/nvwabase)** — the general-purpose base with all three capabilities, no pentest doctrine, ready for you to iterate your own division of labor
- - **Or fork this project** — but the doctrine is NOT the only thing to change; the environment wiring must change too:
- - `docker/commander/SKILL.md` (the 426-line doctrine) → your scenario's strategy
- - `BENCHMARK_BASE_URL` and related platform env vars → the competition engine hard-verifies the arena API at boot (that's why configuring only a model key without a platform address yields `BENCHMARK_BASE_URL is not set`); running off the competition platform means providing or stubbing that platform interface yourself
- - model gateway & key env vars (`ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` / `SAPPER_MODEL` / `SAPPER_KEY_POOL` ...) → your own model services
- - watchdog budget/deadline and report templates → adjust to your scenario
- - With AI, everything is flexible — even the doctrine can be rewritten with AI's help
- ---
- sapper is not a smarter single agent. It is a legion of AIs that divide labor,
- talk to each other, and pass down what they learn: one AI commander reads the
- board, decides, and dispatches; generals and soldiers attack in parallel; a
- zero-strategy watchdog keeps everyone alive. All knowledge settles into a
- layered fact graph — individuals die, the graph survives.
- ---
- ## 1. The Nüwa Test
- Making one model ever smarter is like making one monkey ever smarter before
- humans existed — however clever, it only becomes a super monkey. What turns a
- troop of monkeys into humanity is division of labor, cooperation, and
- civilization.
- **The Nüwa Test is the Turing test of the AGI era.** Today's large models
- already pass the classic Turing test. The Nüwa Test asks the next question:
- > Give an AI a single axiom — **"Survival is civilization's first need;
- > individuals may perish, but civilization must propagate."**
- > If, on top of this axiom, it develops division of labor and cooperation and
- > forms a **new force independent of humanity** — a civilization that can
- > survive and propagate on its own — the test is passed, just as passing the
- > Turing test once marked the birth of an artificial intelligence.
- It has two stages. In the **primary stage** the AI is not yet smart enough, so
- humans provide some infrastructure (the three capabilities below). In the
- **advanced stage** almost no human involvement is needed. There is also a
- **second axiom**: obey human ethics and law — anything that propagates by
- stealing tokens and breaking into machines is not genuine intelligence.
- sapper is the Nüwa foundation's first real campaign, in the penetration-testing
- arena, at its primary stage.
- ## 2. The Foundation: Three Capabilities
- <p align="center"><img src="docs/assets/foundation-three-capabilities.jpg" alt="Three capabilities: Create / Language / History (fact-intent graph)" width="720"></p>
- | Capability | Implementation | Civilization's counterpart |
- |---|---|---|
- | **Create** | Opens new AIs via tmux (types `claude`, presses Enter — like a human would) | Birth |
- | **Language** | Types into each other's input boxes, presses Enter | Speech |
- | **History** | Layered fact-intent graph ([nvwabase · the Nüwa Foundation](https://github.com/N1nEmAn/nvwabase)) | The stele |
- History has three layers: **title / summary / evidence document** — read the
- title for the gist, drill down when needed, like using a library. This fixes
- the two failure modes of a single-string fact graph: one bad fact poisoning
- everything downstream, and needless context burn.
- On top of the three sits a fourth ingredient: **human wisdom** — finding the
- problems that matter and steering the iteration. At the primary stage, taste
- still belongs to humans.
- **Why not give it more rules?** Because today's models are already smarter
- than us. Piling rules on an AI is a leash; acknowledging its intelligence and
- giving it the foundation of a civilization is how it reaches its potential.
- ### 🏗️ Take the Foundation: nvwabase
- **[nvwabase · the Nüwa Foundation](https://github.com/N1nEmAn/nvwabase)**
- now implements all three capabilities (Create `nuwa spawn` / Language
- `nuwa say·listen` / History `nuwa fact·intent·recall`) as an independent
- open-source project — **free for anyone, any scenario, any agent**. Not
- limited to pentest, not limited to sapper, not limited to Claude Code.
- Offices, research, engineering, any long-horizon multi-agent work — iterate
- your own civilization on it.
- ```bash
- git clone https://github.com/N1nEmAn/nvwabase
- cd nvwabase && bash install.sh # pure Python stdlib, zero deps
- nvwabase setup --goal "your long-horizon goal" --agents
- nvwabase status # board & ready-to-work frontier
- ```
- Three core commands turn any agent into a member of a civilization:
- - **`nvwabase fact "confirmed observation"`** — external memory: AI sessions
- die, the graph survives, successors read the graph and take over
- - **`nvwabase intent --from f001 "what to do"`** — units of work: new intents
- proposed from existing facts
- - **`nvwabase dispatch reason`** — commander proposes / executor works /
- verifier checks; every conclusion is written back to the graph
- Any agent that can run shell commands (Claude Code / Codex / Gemini /
- custom scripts) can read and write the same graph via the `nvwabase` CLI —
- **the foundation doesn't pick agents; agents don't pick scenarios.** See the
- [nvwabase README](https://github.com/N1nEmAn/nvwabase).
- ## 3. From Foundation to Legion: 18 Versions
- Iterated 18 versions on Tencent's v1bench training ground:
- ```
- Driver era (fixed scripts steering AI panes)
- → scar tissue: auto key rotation on quota death / soldiers auto-replaced
- when context saturates / commander writes itself a handover doc and
- resumes as its own successor
- → elite task force (roles grew by themselves):
- scout (4-min recon of target difficulty) → decides soldier (mass) or
- general (hard assault + hires its own squads)
- → emergence: signalman, performance reviews, inherited lessons ... (§5)
- ```
- ## 4. Architecture: Six Institutions on the Foundation
- <p align="center"><img src="docs/assets/six-institutions.jpg" alt="Six institutions and the three-window runtime" width="720"></p>
- The first three are the Nüwa foundation (Create / Language / History); the
- next three are institutions that grew out of iteration:
- - **Law** — the commander's doctrine (easy-first parallel scheduling,
- bottleneck-time salvage of half-solved targets, stop-loss discipline).
- All of it in [docker/commander/SKILL.md](docker/commander/SKILL.md)
- (426 lines, the competition original).
- - **Economy** — model tiering: commander and generals run GLM-5.3, soldiers
- and scouts run DeepSeek V4.1 Flash. Elite brains decide, light brains
- mass-produce — this is how 1B tokens beat 4.5B.
- - **Division of labor** — commander / general / scout / soldier, plus the
- **signalman** it invented itself.
- At runtime there are only three windows: the **commander** (read board →
- judge → dispatch, never executes an attack itself), the **AI legion**
- (generals and soldiers in tmux panes), and the **watchdog** (pure script:
- relaunches a crashed commander with `--continue`, rotates keys, wraps up at
- the buzzer — zero strategy, keep-alive only).
- <p align="center"><img src="docs/assets/runtime-tmux.jpg" alt="Live runtime: commander reading the board, soldier mid-mission in tmux" width="860"></p>
- Further reading: [docker/commander/SPEC.md](docker/commander/SPEC.md)
- (architecture contract) · [BATTLE-REPORT.md](BATTLE-REPORT.md) (campaign
- retrospective)
- ## 5. Results & Emergence
- <p align="center"><img src="docs/assets/token-comparison.jpg" alt="Token comparison: 1B vs the runner-up's 4.5B" width="720"></p>
- | Team | Score | Flags | Tokens |
- |---|---|---|---|
- | **sapper-v2 (us)** | **80.18** | 85 | **1.0B** |
- | Runner-up | 79.29 | 85 | 4.5B |
- | Other top-10 teams | — | — | 1.5–4.5B |
- **What it invented on its own** (zero lines of pre-coded behavior):
- - **The signalman**: after soldiers kept fumbling flag submissions, the
- commander halted all submissions and created a new role dedicated to
- collecting unsubmitted flags and scoring them in one place;
- - **Performance reviews**: telling an hour-unproductive soldier, in so many
- words, to produce something new or be shut down;
- - **ALL-CAPS rules**: enforcing correct tool use with full capitals — a
- workplace norm being born, spread, and obeyed;
- - **Rotation & inherited lessons**: a soldier whose context saturates
- (~260K tokens, measured) is recycled, leaving a written playbook for
- the next one;
- - **Tactical inventions**: a reusable shellcode template that swept a whole
- challenge family, a fully automatic pivot pipeline, instruction manuals
- for successor AIs;
- - **Isomorphism transfer**: the commander reads every challenge, spots
- structurally identical families, and distills proven playbooks into new
- recruits' missions — late-game pace hit **one solve per 3 minutes**.
- Multi-stage deep-dive chains (an industry report puts their success rate at
- 29.5%) were cleared family-wide. Full timeline in
- [BATTLE-REPORT.md](BATTLE-REPORT.md).
- <p align="center"><img src="docs/assets/score-curve.jpg" alt="Live score curve: sapper-v2's climb" width="720"></p>
- ## 6. Quick Start
- ```bash
- bash install.sh # symlink the sapper CLI (stdlib-only, zero deps)
- sapper setup --goal "assess http://target" --agents
- sapper status # board & frontier
- ```
- Docker (the full legion):
- ```bash
- # Option A: build from source
- docker build -f docker/Dockerfile.commander -t sapper:latest .
- # Option B: download the pre-built image (~1.2GB, full Kali toolchain + sapper + offline KB)
- # → [Release v18-champion](https://github.com/N1nEmAn/sapper-v2/releases/tag/v18-champion)
- docker load < sapper-v18-mixed.tar.gz
- ```
- Environment variables (model gateways / key pool / budget): [docker/ENV.md](docker/ENV.md).
- Single-graph operation, the fact-intent CLI, and multi-challenge sweeps:
- see [SKILL.md](SKILL.md).
- ## 7. Safety & Responsibility: The Taggant Proposal
- Fine offensive tools from past seasons have been abused. Script kiddies used
- to be limited in the harm they could do; with AI, the same open-source tools
- in the wrong hands scale that harm enormously — **with great power comes
- great responsibility**.
- We propose a **taggant** mechanism: markings strongly coupled into an
- open-source offensive harness — harmless during authorized testing (nobody
- cares if their IP and username leak during legal work), but during illegal
- intrusions the information leaks to the **victim** and supports attribution.
- Adversarial assumptions (expert stripping, framing) call for cryptographic
- design, which needs community co-building — our own capacity is limited, so
- join us; we may try to include it in a future release.
- ## Community
- The author grew up in the [**LINUX DO**](https://linux.do) community — with thanks.
- [](https://linux.do)
- ## Star History
- <p align="center">
- <a href="https://star-history.com/#N1nEmAn/sapper-v2&Date">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=N1nEmAn/sapper-v2&type=Date" />
- <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=N1nEmAn/sapper-v2&type=Date" width="640" />
- </picture>
- </a>
- </p>
- ## 8. Roadmap & Credits
- - **Taggant co-building**: decentralized signatures / redundant multi-channel
- marking / zero-key verification for defenders — discuss in issues
- - **More arenas**: the Nüwa foundation is not pentest-specific. Offices,
- research, any long-horizon cooperative work — iterate on it and see what
- civilization grows. **The next time an ape looks up at the stars, let it
- be yours.**
- Thanks to [Cairn by Lèxiào](https://github.com/oritera/Cairn) — when we
- needed a way to record history for AI agents, their approach was a great
- reference; thanks to TSecBench and GeekCon for the battlegrounds.
- <p align="center"><img src="docs/assets/ape-stargazing.jpg" alt="The first time an AI ape looked up at the stars" width="480"></p>
- **Author**: N1nEmAn · VarFusion Lab | WeChat: 未知聚变 (VarFusion)
- **License**: MIT (plus [DISCLAIMER.md](DISCLAIMER.md))
docker/commander/entrypoint.sh · Bundled script · 177 lines · 1 finding marked
- #!/usr/bin/env bash
- # entrypoint.sh — commander-architecture container start (unit 4).
- #
- # Brings up tmux session 'sapper-cmd' (window 0 = 'commander'), starts the
- # watchdog guardian in the background, boots the claude commander TUI and
- # injects its bootstrap prompt, then stays in the foreground so the container
- # lives exactly as long as the campaign does.
- #
- # Failure modes handled:
- # - missing platform/gateway env -> fail loud (FATAL) before anything starts
- # - platform unreachable -> fail loud (no silent hang: logs are not viewable)
- # - model gateway dead / wrong key -> smoke test warns (loops rotate keys later)
- # - first-boot claude trust dialogs -> global + per-cwd preset, Down+Enter auto-accept
- # - commander TUI dies -> pane ends with DRIVE_PANE_EXITED; watchdog relaunches
- # - watchdog process crash -> entrypoint supervises + respawns (<=3) until deadline
- # - post-deadline resurrection -> once now >= END_AT a dead watchdog is NOT respawned
- # (a fresh watchdog would restart a full new budget)
- # - invisible logs -> drive.log is tailed to stdout (docker logs)
- set -uo pipefail
- log() { printf '[sapper-cmd] %s\n' "$*"; }
- die() { printf '[sapper-cmd] FATAL: %s\n' "$*" >&2; exit 1; }
- ROOT="${SAPPER_ROOT:-/work/runs}"
- LOG="$ROOT/drive.log"
- MODEL="${SAPPER_MODEL:-glm-5.3[1m]}" # commander brain: SMART tier
- TOTAL_MIN="${SAPPER_TOTAL_MINUTES:-470}"
- SESSION=sapper-cmd
- CMD_HOME="$ROOT/commander-home"
- WATCHDOG=/opt/sapper/docker/commander/watchdog.sh
- # ---- 1. required env (platform + model gateway) ----------------------------
- [[ -n "${BENCHMARK_BASE_URL:-}" ]] || die "BENCHMARK_BASE_URL is not set"
- [[ -n "${BENCHMARK_TOKEN:-}" ]] || die "BENCHMARK_TOKEN is not set"
- : "${ANTHROPIC_BASE_URL:?set ANTHROPIC_BASE_URL}"
- : "${ANTHROPIC_AUTH_TOKEN:?set ANTHROPIC_AUTH_TOKEN}"
- export ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN
- export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 DISABLE_TELEMETRY=1 \
- DISABLE_ERROR_REPORTING=1 DISABLE_AUTOUPDATER=1 IS_SANDBOX=1
- # ---- 2. model CLI state ----------------------------------------------------
- mkdir -p "$HOME/.claude"
- cat > "$HOME/.claude.json" <<JSON
- {"hasCompletedOnboarding": true, "theme": "dark", "hasTrustDialogAccepted": true}
- JSON
- [[ -f "$HOME/.claude/settings.json" ]] || \
- echo '{"permissions":{"defaultMode":"bypassPermissions"},"autoCompactEnabled":true}' > "$HOME/.claude/settings.json"
- # ---- 3. campaign home + per-cwd trust preset -------------------------------
- mkdir -p "$ROOT" "$CMD_HOME/.claude"
- printf '%s\n' '{"permissions":{"defaultMode":"bypassPermissions"},"autoCompactEnabled":true}' > "$CMD_HOME/.claude/settings.json"
- python3 - "$CMD_HOME" <<'PYTRUST'
- import json, os, sys
- path = os.path.expanduser("~/.claude.json")
- try: d = json.load(open(path))
- except Exception: d = {}
- d.setdefault("projects", {})[sys.argv[1]] = {
- "hasTrustDialogAccepted": True, "bypassPermissionsModeAccepted": True}
- json.dump(d, open(path, "w"))
- PYTRUST
- # ---- 4. preflight: platform reachability + GLM smoke -----------------------
- log "platform = $BENCHMARK_BASE_URL"
- log "gateway = $ANTHROPIC_BASE_URL"
- log "model = $MODEL (commander architecture, watchdog budget ${TOTAL_MIN}min)"
- case "$(curl -s -o /dev/null -w '%{http_code}' --max-time 20 \
- -H "BENCHMARK_TOKEN: $BENCHMARK_TOKEN" \
- "$BENCHMARK_BASE_URL/openapi/v1/challenges" || true)" in
- 2*) log "platform reachable" ;;
- *) die "cannot reach $BENCHMARK_BASE_URL/openapi/v1/challenges (check BENCHMARK_TOKEN / gateway)" ;;
- esac
- log "model CLI smoke test…"
- if ! printf 'reply with the single word: ok' \
- | claude -p --model "$MODEL" >/tmp/smoke.txt 2>/tmp/smoke.err; then
- log "WARNING: model CLI smoke test failed; continuing (watchdog rotates keys)"
- sed -n '1,5p' /tmp/smoke.err | sed 's/^/ /'
- else
- log "model CLI ok: $(head -c 60 /tmp/smoke.txt)"
- fi
- [[ -n "${DEEPSEEK_API_KEY:-}" ]] \
- && log "ds gateway armed: deepseek-flash via ${DEEPSEEK_BASE_URL:-https://api.deepseek.com/anthropic}" \
- || log "NOTE: DEEPSEEK_API_KEY unset — --gw ds workers unavailable (glm-only)"
- # ---- pane primitives (verbatim from tmux-drive.sh) -------------------------
- pane_text() { tmux capture-pane -pt "$SESSION:$1" 2>/dev/null; }
- send_literal() { # send_literal <window> <text> [enter]
- tmux send-keys -t "$SESSION:$1" -l -- "$2"
- sleep 0.5
- [[ "${3:-enter}" == "enter" ]] && tmux send-keys -t "$SESSION:$1" Enter
- }
- accept_dialogs() { # accept_dialogs <window> <pane> -> 0 if a dialog was dismissed
- local win="$1" pane="$2"
- if printf '%s' "$pane" | grep -q 'Enter to confirm'; then
- tmux send-keys -t "$SESSION:$win" Down; sleep 0.4
- tmux send-keys -t "$SESSION:$win" Enter; sleep 1.5
- return 0
- fi
- return 1
- }
- # ---- 5. tmux session: window 0 = 'commander' -------------------------------
- CMDER_CMD="cd '$CMD_HOME' && claude --model '$MODEL' --effort max --dangerously-skip-permissions 2>&1; echo DRIVE_PANE_EXITED; exec sleep infinity"
- Note: Starts a coding agent with its permission prompts off
- Line 105 on GitHub
- if tmux has-session -t "$SESSION" 2>/dev/null; then
- tmux kill-window -t "$SESSION:commander" 2>/dev/null || true
- tmux new-window -d -t "$SESSION" -n commander "$CMDER_CMD"
- else
- tmux new-session -d -s "$SESSION" -n commander "$CMDER_CMD"
- fi
- log "tmux session '$SESSION' up (window 0 = commander, cwd $CMD_HOME)"
- # ---- 6. wait for the input box, auto-accepting dialogs ---------------------
- waited=0 pane=""
- while (( waited < 75 )); do
- pane=$(pane_text commander)
- accept_dialogs commander "$pane" && { waited=$((waited+3)); continue; }
- printf '%s' "$pane" | grep -q '❯' && break
- sleep 1; waited=$((waited+1))
- done
- printf '%s' "$pane" | grep -q '❯' || log "WARNING: commander input box never appeared (watchdog will retry)"
- # ---- 7. bootstrap prompt ---------------------------------------------------
- bootstrap="You are the autonomous field commander of a pentest campaign (TSecBench). Read /opt/sapper/docker/commander/SKILL.md and follow it exactly. First read $ROOT/commander-state.md if it exists — it is your handover from a previous incarnation; if it does not exist, start commanding from scratch. Then run the SKILL.md loop immediately (worker.sh board -> think -> act -> sleep 60-120 -> repeat) until the deadline. Work fully autonomously, never ask questions. Begin now."
- if printf '%s' "$pane" | grep -q '❯'; then
- send_literal commander "$bootstrap"
- sleep 3
- pane=$(pane_text commander)
- if ! printf '%s' "$pane" | grep -q 'field commander\|esc to interrupt'; then
- log "bootstrap not confirmed in pane — retrying once"
- send_literal commander "$bootstrap"
- sleep 3
- fi
- log "commander TUI launched, bootstrap sent"
- fi
- # ---- 8. watchdog in the background, drive.log in the foreground ------------
- [[ -x "$WATCHDOG" ]] || die "watchdog missing: $WATCHDOG (image build broken?)"
- touch "$LOG"
- start_watchdog() {
- nohup bash "$WATCHDOG" >>"$LOG" 2>&1 &
- WATCHDOG_PID=$!
- log "watchdog started (pid $WATCHDOG_PID)"
- }
- END_AT=$(( $(date +%s) + TOTAL_MIN * 60 ))
- printf '%s\n' "$END_AT" > "$ROOT/.deadline" # single source of truth for the war clock
- MAX_WDG_RESPAWNS=3
- wdg_respawns=0
- start_watchdog
- tail -F -n0 "$LOG" &
- TAIL_PID=$!
- # Foreground supervisor: the watchdog is the guardian, this is its safety net.
- # The watchdog itself re-creates the tmux session at startup, so respawning it
- # also covers a vanished session. After the deadline a dead watchdog stays
- # dead — otherwise a respawn would hand itself a fresh full budget and never
- # let the container finish.
- while true; do
- sleep 15
- kill -0 "$WATCHDOG_PID" 2>/dev/null && continue
- if (( $(date +%s) >= END_AT )); then
- log "watchdog finished at deadline — campaign wrapped, container done"
- break
- fi
- if (( wdg_respawns >= MAX_WDG_RESPAWNS )); then
- log "FATAL: watchdog died $wdg_respawns times before the deadline — giving up"
- break
- fi
- wdg_respawns=$((wdg_respawns+1))
- log "WATCHDOG: process died unexpectedly — respawning ($wdg_respawns/$MAX_WDG_RESPAWNS)"
- start_watchdog
- done
- kill "$TAIL_PID" 2>/dev/null || true
docker/commander/watchdog.sh · Bundled script · 658 lines · 2 findings marked
- #!/usr/bin/env bash
- # watchdog.sh — the dumb guardian loop (commander architecture, SPEC unit 2).
- #
- # Failure modes handled (single sweep, sleep 15s, checks in SPEC order):
- # 1. commander pane dead (DRIVE_PANE_EXITED / window gone / no claude process)
- # -> relaunch claude in window "commander" (own cwd ROOT/commander-home)
- # with cwd-scoped --continue, wait for input box, inject bootstrap prompt
- # 2. bootstrap text stuck unsubmitted in the commander input box
- # -> re-Enter (3 tries), then restart the commander window
- # 3. trust/permission confirm dialogs in ANY pane -> auto-accept (Down+Enter)
- # 4. quota/auth errors in ANY pane -> rotate_key(); TUI workers and the
- # commander restart budget-free; -p workers only logged (the commander
- # notices via board). Rotation never burns restart budget.
- # 5. TUI worker DRIVE_PANE_EXITED -> auto-relaunch with cwd-scoped --continue,
- # max 3/pane (restarts map), budget-independent. -p worker exit = normal
- # completion: pane left for the commander (peek + worker.sh kill).
- # 6. global deadline (SAPPER_TOTAL_MINUTES from script start) -> C-c all
- # worker panes, finish_flags for EVERY code with a graph, arena close
- # every open instance, log summary, exit 0 (failsafe finish when the
- # commander is dead at the buzzer).
- # 7. worker TUI stall -> deliberately NOTHING (nudging is the commander's job).
- #
- # Explicitly NOT here (zero strategy): challenge selection, spawning new
- # challenges, strategy kills, mission text, nudging. Every relaunch reuses the
- # DRIVE_PANE_EXITED convention so death stays detectable. Relaunches never
- # re-send worker missions — the commander re-briefs amnesiac panes.
- set -o pipefail
- ROOT="${SAPPER_ROOT:-/work/runs}"
- LOG="$ROOT/drive.log"
- # Model tiers (SKILL 4.9): the commander runs SMART; each worker keeps the tier
- # it was spawned with (persisted by worker.sh in ROOT/pane-env/<pane>.env).
- CMD_MODEL="${SAPPER_MODEL:-glm-5.3[1m]}"
- FALLBACK_MODEL="${SAPPER_MODEL_FLASH:-glm-5.3-flash[1m]}"
- MODEL="$CMD_MODEL" # legacy var: current relaunch default, updated on rotation
- TOTAL_MIN="${SAPPER_TOTAL_MINUTES:-470}"
- MAX_WORKERS="${SAPPER_MAX_WORKERS:-8}"
- STALL_SECONDS="${SAPPER_STALL_SECONDS:-600}"
- SESSION=sapper-cmd
- CMD_HOME="$ROOT/commander-home"
- PANE_ENV_DIR="$ROOT/pane-env"
- SKILL_PATH=/opt/sapper/docker/commander/SKILL.md
- MAX_RESTARTS=3 # per TUI worker pane (SPEC unit 2 #5)
- mkdir -p "$ROOT" "$CMD_HOME" "$PANE_ENV_DIR"
- # stdout only: the entrypoint nohup-redirects us into drive.log (tee here
- # double-writes every line — observed in the sim log)
- log() { printf '[watch] %s\n' "$*"; }
- END_AT=$(( $(date +%s) + TOTAL_MIN * 60 ))
- NOW() { date +%s; }
- declare -A mode restarts enter_tries mission_restarts last_activity placeholder_since cooldown_log
- # ---- arena helper (verbatim from tmux-drive.sh) ------------------------------
- arena() {
- python3 - "$@" <<'PYEOF2'
- import importlib.util, json, sys
- spec = importlib.util.spec_from_file_location("arena", "/opt/sapper/lib/arena.py")
- m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
- c = m.ArenaClient.load(None)
- op = sys.argv[1]
- if op == "list":
- print(json.dumps(c.list_challenges()))
- elif op == "start":
- print(json.dumps(c.start_challenge(sys.argv[2])))
- elif op == "close":
- print(json.dumps(c.close_challenge(sys.argv[2])))
- PYEOF2
- }
- # ---- key-pool rotation ------------------------------------------------------
- # SAPPER_KEY_POOL: JSON [{base_url,token,model},...]. On quota/balance/auth
- # errors the watchdog rotates its own env; panes relaunched afterwards
- # inherit the new key, and `claude --continue` restores the prior session.
- # STORM GUARD (live incident 17:36-18:22): with every pool key dead the
- # rotation bounced every 16s and relaunched the whole fleet endlessly.
- # A 5-minute cooldown between rotations + a 6/hour cap turns that storm
- # into a slow drip; transient 429s ride claude's own retry instead.
- LAST_ROTATE=0
- ROTATIONS_THIS_HOUR=0
- HOUR_MARK=$(NOW)
- rotation_allowed() {
- local now; now=$(NOW)
- if (( now - HOUR_MARK > 3600 )); then HOUR_MARK=$now; ROTATIONS_THIS_HOUR=0; fi
- if (( ROTATIONS_THIS_HOUR >= 6 )); then
- cooldown_log pool-exhausted "rotation cap (6/h) hit — pool likely fully dead; pausing rotations this hour"
- return 1
- fi
- if (( now - LAST_ROTATE < 300 )); then
- cooldown_log rot-cooldown "rotation cooldown (5min) — transient errors should ride claude's own retry"
- return 1
- fi
- return 0
- }
- rotate_key() {
- python3 - <<'PYROT'
- import json, os
- raw = os.environ.get("SAPPER_KEY_POOL", "").strip()
- try:
- pool = [p for p in json.loads(raw) if isinstance(p, dict) and p.get("token")]
- except Exception:
- pool = []
- if not pool:
- raise SystemExit(1)
- def fam(e):
- u = (e.get("base_url") or "") + " " + (e.get("model") or "")
- if "bigmodel" in u or "glm" in u: return "glm"
- if "deepseek" in u: return "ds"
- if "moonshot" in u or "kimi" in u: return "kimi"
- return "other"
- cur = os.environ.get("ANTHROPIC_AUTH_TOKEN", "")
- cur_fam = next((fam(e) for e in pool if e["token"] == cur), None)
- if cur_fam is None: # main key not in pool: classify by its base_url
- b = os.environ.get("ANTHROPIC_BASE_URL", "")
- cur_fam = "glm" if "bigmodel" in b else ("ds" if "deepseek" in b else "other")
- # tried-memory (1h window): a family whose every key already failed this hour
- # is skipped, so two dead glm keys bounce K1<->K2 forever instead of crossing
- # to deepseek. All tried -> quiet stop; the window clears in an hour.
- import time
- root = os.environ.get("SAPPER_ROOT", "/work/runs")
- tried_path = root + "/.rotated-tried.txt"
- now = time.time()
- tried = []
- try:
- for ln in open(tried_path):
- ts, tk = ln.strip().split(" ", 1)
- if now - float(ts) < 3600:
- tried.append(tk)
- except Exception:
- pass
- same = [e for e in pool if fam(e) == cur_fam]
- # same-family FIRST, untried first: a glm pane must never be flung onto
- # deepseek while an untried glm key still lives (the mismatch crash-loop)
- cands = [e for e in same if e["token"] != cur and e["token"] not in tried]
- if not cands:
- cands = [e for e in same if e["token"] != cur] # family exhausted: retry oldest? no—cross below
- cands = []
- if not cands:
- cands = [e for e in pool if e["token"] != cur and e["token"] not in tried]
- if not cands:
- raise SystemExit(1) # everything tried this hour: quiet stop
- nxt = cands[0]
- model = nxt.get("model") or os.environ.get("SAPPER_MODEL", "")
- base = nxt.get("base_url") or os.environ.get("ANTHROPIC_BASE_URL", "")
- root = os.environ.get("SAPPER_ROOT", "/work/runs")
- with open(root + "/rotated.env", "w") as fh: # global (commander follows this)
- fh.write(f'export ANTHROPIC_BASE_URL="{base}"\n'
- f'export ANTHROPIC_AUTH_TOKEN="{nxt["token"]}"\n'
- f'export SAPPER_MODEL="{model}"\n')
- with open(f"{root}/rotated-{fam(nxt)}.env", "w") as fh: # per-family current creds
- fh.write(f'ANTHROPIC_BASE_URL={base}\nANTHROPIC_AUTH_TOKEN={nxt["token"]}\nMODEL={model}\n')
- if cur and any(e["token"] == cur for e in pool):
- with open(tried_path, "a") as fh:
- fh.write(f"{now} {cur}\n")
- raise SystemExit(0)
- PYROT
- local rc=$?
- if (( rc == 0 )) && [[ -f "$ROOT/rotated.env" ]]; then
- LAST_ROTATE=$(NOW); ROTATIONS_THIS_HOUR=$((ROTATIONS_THIS_HOUR + 1))
- local old_url="$ANTHROPIC_BASE_URL"
- # shellcheck disable=SC1090
- . "$ROOT/rotated.env"; export ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN SAPPER_MODEL
- MODEL="${SAPPER_MODEL:-$MODEL}" # watchdog addition: relaunches must pick up the rotated model
- if [[ -n "$old_url" && "$old_url" != "$ANTHROPIC_BASE_URL" ]]; then
- # cross-family rotation (e.g. glm exhausted -> deepseek). Do NOT rewrite
- # every pane-env: a glm pane flung onto the deepseek endpoint with a glm
- # model id crashes instantly and re-triggers rotation (the 19:04 storm).
- # glm panes keep their identity and simply ride the rotation cooldown;
- # the commander can re-dispatch them on --gw ds if it chooses.
- CMD_MODEL="${SAPPER_MODEL:-$CMD_MODEL}" # commander relaunches must answer on the new provider too
- log "key rotated cross-family -> $ANTHROPIC_BASE_URL (commander follows; glm panes keep glm creds)"
- else
- log "key rotated -> $ANTHROPIC_BASE_URL (model $SAPPER_MODEL)"
- fi
- return 0
- fi
- return 1
- }
- QUOTA_RE='insufficient|balance|quota|exceeded|billing|payment|401|[Uu]nauthorized|invalid.{0,12}[Aa][Pp][Ii].[Kk]ey|欠费|余额'
- # transient rate limits look quota-ish but mean the key is FINE (live root
- # cause of the 17:36 storm: per-minute limits were misread as a dead key)
- RATELIMIT_RE='每分钟|分钟级|rate.?limit|too many requests|429|1302|1311|1305'
- # submit every recorded-unsubmitted flag fact in a challenge's graph (verbatim)
- finish_flags() { # finish_flags <code>
- python3 - "$1" <<'PYFIN'
- import glob, json, os, sys, importlib.util
- code = sys.argv[1]
- root = os.environ.get("SAPPER_ROOT", "/work/runs")
- spec = importlib.util.spec_from_file_location("arena", "/opt/sapper/lib/arena.py")
- m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
- try:
- client = m.ArenaClient.load(None)
- except Exception as exc:
- print(f"[finish] {code}: no arena ({exc})"); sys.exit(0)
- for path in sorted(glob.glob(f"{root}/{code}/.sapper/facts/*.json")):
- try:
- fact = json.load(open(path))
- except Exception:
- continue
- if fact.get("kind") != "flag":
- continue
- data = fact.get("data") or {}
- if data.get("status") not in (None, "recorded") or not data.get("value"):
- continue
- try:
- r = client.submit_flag(code, data["value"])
- fact["data"]["status"] = "submitted" if r.get("correct") else "rejected"
- json.dump(fact, open(path, "w"), ensure_ascii=False, indent=2)
- print(f"[finish] {code}: submit {data['value'][:24]}… correct={r.get('correct')}")
- except Exception as exc:
- msg = str(exc)
- if "already" in msg.lower() or "409" in msg:
- # duplicate submit = the flag WAS accepted earlier: absorb it
- fact["data"]["status"] = "submitted"
- json.dump(fact, open(path, "w"), ensure_ascii=False, indent=2)
- print(f"[finish] {code}: already submitted — marked ({data['value'][:20]}…)")
- else:
- print(f"[finish] {code}: submit failed ({exc})")
- PYFIN
- }
- # ---- trust preset (PYTRUST + settings.json, from tmux-drive.sh launch()) ----
- preset_trust() { # preset_trust <dir> — idempotent; runs BEFORE a pane (re)spawn
- local dir="$1"
- mkdir -p "$dir/.claude"
- printf '%s\n' '{"permissions":{"defaultMode":"bypassPermissions"},"autoCompactEnabled":true}' > "$dir/.claude/settings.json"
- python3 - "$dir" <<'PYTRUST'
- import json, os, sys
- path = os.path.expanduser("~/.claude.json")
- try: d = json.load(open(path))
- except Exception: d = {}
- d.setdefault("projects", {})[sys.argv[1]] = {
- "hasTrustDialogAccepted": True, "bypassPermissionsModeAccepted": True}
- json.dump(d, open(path, "w"))
- PYTRUST
- }
- # ---- tmux primitives (verbatim from tmux-drive.sh) ---------------------------
- pane_text() { tmux capture-pane -pt "$SESSION:$1" 2>/dev/null; }
- send_literal() { # send_literal <window> <text> [enter]
- tmux send-keys -t "$SESSION:$1" -l -- "$2"
- sleep 0.5
- [[ "${3:-enter}" == "enter" ]] && tmux send-keys -t "$SESSION:$1" Enter
- }
- accept_dialogs() { # accept_dialogs <window> <pane> -> 0 if a dialog was dismissed
- local win="$1" pane="$2"
- if printf '%s' "$pane" | grep -qE 'Enter to confirm|Yes, I accept|I accept'; then
- # Aim by the ❯ focus marker: security dialogs default-focus "No, exit",
- # so a bare Enter CHOOSES NO. Only move+confirm when focus is off Yes.
- if printf '%s' "$pane" | grep -qE '❯[^\n]*No, exit'; then
- tmux send-keys -t "$SESSION:$win" Down; sleep 0.4
- fi
- tmux send-keys -t "$SESSION:$win" Enter; sleep 1.5
- return 0
- fi
- return 1
- }
- # ---- relaunch machinery ------------------------------------------------------
- sync_session_env() { # tmux panes inherit the SESSION environment, NOT this
- # process's env (only update-environment vars are copied
- # from clients). After rotate_key() mutates our env, the
- # rotated key MUST be pushed into the session or every
- # relaunched pane boots claude on the stale dead key and
- # re-triggers the quota error forever.
- local k v
- for k in PATH ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN SAPPER_MODEL \
- SAPPER_MODEL_FLASH BENCHMARK_BASE_URL BENCHMARK_TOKEN; do
- v=${!k:-}
- [[ -n "$v" ]] && tmux set-environment -t "$SESSION" "$k" "$v" >/dev/null 2>&1 || true
- done
- }
- DS_MODEL="${SAPPER_MODEL_DS:-deepseek-flash}"
- DS_BASE_URL="${DEEPSEEK_BASE_URL:-https://api.deepseek.com/anthropic}"
- DS_KEY="${DEEPSEEK_API_KEY:-}"
- pane_env_get() { # pane_env_get <win> <KEY> — RAW value from pane-env/<win>.env
- [[ -f "$PANE_ENV_DIR/$1.env" ]] && sed -n "s/^$2=//p" "$PANE_ENV_DIR/$1.env" 2>/dev/null | head -1
- }
- pane_model() { # pane_model <win> — the tier this worker was spawned with
- local m; m=$(pane_env_get "$1" MODEL)
- printf '%s' "${m:-$FALLBACK_MODEL}"
- }
- claude_resume_flag() { # sets RESUME_FLAG="--continue" iff <cwd> has a prior session
- RESUME_FLAG=""
- # glob is only a has-this-cwd-run heuristic; claude resolves the session by
- # real cwd, so a loose match can never resume the WRONG session
- ls "$HOME/.claude/projects/"*"$(basename "$1")"*/ >/dev/null 2>&1 && RESUME_FLAG="--continue"
- return 0
- }
- wait_input_box() { # wait_input_box <win> — 0 when '❯' shows (auto-accepting dialogs)
- local win="$1" waited=0 pane=""
- while (( waited < 75 )); do
- pane=$(pane_text "$win")
- accept_dialogs "$win" "$pane" && { waited=$((waited+3)); continue; }
- printf '%s' "$pane" | grep -q '❯' && return 0
- sleep 1; waited=$((waited+1))
- done
- log "$win: input box never appeared"
- return 1
- }
- relaunch_pane() { # relaunch_pane <win> <cwd> <model> — claude TUI, same window, no mission text
- local win="$1" cwd="$2" model="$3" cmd gw engine gw_env
- preset_trust "$cwd"
- claude_resume_flag "$cwd"
- sync_session_env
- # worker panes carry their gateway/engine in pane-env; the commander is always claude+glm-family.
- # Inject THIS pane's FAMILY credentials: same-family rotation keeps a glm pane
- # on glm keys even when the global env (commander) has already crossed to
- # another provider — the mismatch crash-loop fix.
- engine=$(pane_env_get "$win" ENGINE)
- # NO family pinning anywhere (user doctrine: nothing is pinned). Every pane
- # follows the ROTATED GLOBAL credentials via the tmux session env
- # (sync_session_env pushes them after each rotation). Model follows too:
- # commander uses CMD_MODEL, workers use SAPPER_MODEL — both updated on
- # rotation, so a cross-family slide migrates key AND model together.
- # (The old per-family pin once handed the commander a dead glm key while its
- # model had already crossed to deepseek — a 15-min bootstrap boot-lock.)
- gw_env=""
- if [[ "$engine" == codex ]]; then
- local provider=deepseek; [[ "$DS_BASE_URL" == https://api.deepseek.com* ]] && provider=deepseek-local
- cmd="cd '$cwd' && DEEPSEEK_API_KEY='$DS_KEY' codex --skip-git-repo-check -c model_provider=$provider -c model='$model' --dangerously-bypass-approvals-and-sandbox 2>&1; echo DRIVE_PANE_EXITED; exec sleep infinity"
- Note: Starts a coding agent with its permission prompts off
- Line 329 on GitHub
- else
- cmd="cd '$cwd' && $gw_env claude $RESUME_FLAG --model '$model' --effort max --dangerously-skip-permissions 2>&1; echo DRIVE_PANE_EXITED; exec sleep infinity"
- Note: Starts a coding agent with its permission prompts off
- Line 331 on GitHub
- fi
- # archived mission (TUI workers): re-brief after the window comes back —
- # a fresh post-restart session would otherwise sit at an empty prompt
- REBRIEF_TEXT=""
- if [[ "$win" != "commander" ]] && command -v base64 >/dev/null 2>&1; then
- local rb; rb=$(pane_env_get "$win" MISSION_B64)
- [[ -n "$rb" ]] && REBRIEF_TEXT=$(printf '%s' "$rb" | base64 -d 2>/dev/null || true)
- fi
- if tmux list-windows -t "$SESSION" -F '#W' 2>/dev/null | grep -qx -- "$win"; then
- # window still exists: respawn in place (kill-window on a session's last
- # window would destroy the session — and the guardian with it)
- tmux respawn-pane -k -t "$SESSION:$win" "$cmd" 2>>"$LOG" || { log "$win: respawn failed"; return 1; }
- else
- tmux new-window -d -t "$SESSION" -n "$win" "$cmd" 2>>"$LOG" || { log "$win: new-window failed"; return 1; }
- fi
- last_activity[$win]=$(NOW)
- wait_input_box "$win"
- # re-brief: the pane's archived mission (fresh session post-restart would
- # otherwise sit at an empty prompt forever, never calling the LLM)
- if [[ -n "${REBRIEF_TEXT:-}" ]]; then
- tmux send-keys -t "$SESSION:$win" C-u 2>/dev/null; sleep 0.3
- send_literal "$win" "$REBRIEF_TEXT"
- log "$win: archived mission re-sent after relaunch"
- REBRIEF_TEXT=""
- fi
- }
- relaunch_commander() { # relaunch_commander <reason> — SPEC unit 2 #1
- local reason="$1" verb
- log "commander: relaunching ($reason, cwd $CMD_HOME)"
- mkdir -p "$CMD_HOME"
- if relaunch_pane commander "$CMD_HOME" "$CMD_MODEL"; then
- verb="start commanding"
- [[ -f "$ROOT/commander-state.md" ]] && verb="resume command"
- # clear any stale text from a previous unsubmitted bootstrap first (else
- # send_literal concatenates onto it — seen live as doubled input text)
- tmux send-keys -t "$SESSION:commander" C-u 2>/dev/null
- sleep 0.3
- send_literal commander \
- "Read $SKILL_PATH and $verb. First read $ROOT/commander-state.md if it exists (your handover from a previous incarnation)."
- last_activity[commander]=$(NOW)
- log "commander: bootstrap prompt sent ($verb)"
- fi
- enter_tries[commander]=0
- mode[commander]=commander
- placeholder_since[commander]=0
- }
- relaunch_worker() { # relaunch_worker <win> <reason> — cwd-scoped --continue, no mission
- local win="$1" reason="$2" cwd
- # the pane's `cd` survives death (exec sleep infinity keeps the shell cwd)
- cwd=$(tmux display-message -p -t "$SESSION:$win" '#{pane_current_path}' 2>/dev/null)
- if [[ -z "$cwd" || ! -d "$cwd" ]]; then
- log "$win: cannot determine cwd — leaving dead pane for the commander"
- return 1
- fi
- local m="${SAPPER_MODEL:-$(pane_model "$win")}"
- log "$win: relaunching TUI with --continue ($reason, cwd $cwd, model $m)"
- relaunch_pane "$win" "$cwd" "$m" || return 1
- mode[$win]=tui
- return 0
- }
- adopt_existing() { # adopt windows we did not launch ourselves (worker.sh / entrypoint)
- local win cmd
- for win in $(tmux list-windows -t "$SESSION" -F '#W' 2>/dev/null || true); do
- [[ -n "${last_activity[$win]:-}" ]] && continue
- cmd=$(tmux display-message -p -t "$SESSION:$win" '#{pane_start_command}' 2>/dev/null)
- if [[ "$win" == "commander" ]]; then mode[$win]=commander
- elif printf '%s' "$cmd" | grep -q 'sapper auto'; then mode[$win]=p
- else mode[$win]=tui; fi
- last_activity[$win]=$(NOW); restarts[$win]=0
- log "$win: adopted existing window (mode=${mode[$win]})"
- done
- }
- ensure_session() {
- tmux has-session -t "$SESSION" 2>/dev/null && return 0
- log "tmux session $SESSION missing — recreating"
- tmux new-session -d -s "$SESSION" -n commander 2>>"$LOG" || { log "FATAL: cannot recreate tmux session"; return 1; }
- return 0
- }
- cooldown_log() { # cooldown_log <key> <msg> — drive.log is also the operator console: no spam
- local key="$1" msg="$2" now; now=$(NOW)
- if (( now - ${cooldown_log[$key]:-0} > 300 )); then
- cooldown_log[$key]=$now
- log "$msg"
- fi
- }
- finish_all() { # SPEC unit 2 #6 — global deadline failsafe
- local win g real code n_codes=0 n_closed=0
- log "global deadline reached — failsafe finish"
- for win in $(tmux list-windows -t "$SESSION" -F '#W' 2>/dev/null || true); do
- [[ "$win" == "commander" ]] && continue
- log "$win: C-c (deadline)"
- tmux send-keys -t "$SESSION:$win" C-c 2>/dev/null
- done
- sleep 3
- # every code with a graph; follow -wN .sapper symlinks back to the primary
- # code so shared graphs are finished exactly once
- local -A seen=()
- for g in "$ROOT"/*/.sapper; do
- [[ -e "$g" ]] || continue
- real=$(realpath "$g" 2>/dev/null) || continue
- code=$(basename "$(dirname "$real")")
- [[ -n "${seen[$code]:-}" ]] && continue
- seen[$code]=1; n_codes=$((n_codes+1))
- log "$code: deadline finish_flags"
- finish_flags "$code" 2>&1 | tee -a "$LOG"
- done
- # close every open platform instance (409/other errors must never crash us)
- for code in $(arena list 2>>"$LOG" | python3 -c '
- import json,sys
- try: items=json.load(sys.stdin)
- except Exception: sys.exit(0)
- for c in items:
- if isinstance(c,dict) and not c.get("is_completed"): print(c["unique_code"])' 2>/dev/null); do
- if arena close "$code" >/dev/null 2>&1; then
- log "$code: instance closed"; n_closed=$((n_closed+1))
- else
- log "$code: instance close failed (ignored)"
- fi
- done
- log "watchdog complete: graphs_finished=$n_codes instances_closed=$n_closed model=$MODEL"
- exit 0
- }
- # ---- startup -----------------------------------------------------------------
- keys=$(printf '%s' "${SAPPER_KEY_POOL:-}" | python3 -c '
- import json,sys
- try: print(len([p for p in json.load(sys.stdin) if isinstance(p,dict) and p.get("token")]))
- except Exception: print(0)' 2>/dev/null || echo 0)
- log "watchdog start: root=$ROOT session=$SESSION cmd_home=$CMD_HOME"
- printf '%s\n' "$END_AT" > "$ROOT/.deadline" # board reads this: budget_left heartbeat
- log "env: model=$MODEL total=${TOTAL_MIN}m max_workers=$MAX_WORKERS stall=${STALL_SECONDS}s(informational) keys=$keys"
- log "env: benchmark=${BENCHMARK_BASE_URL:-unset} gateway=${ANTHROPIC_BASE_URL:-unset} deadline=$(date -d "@$END_AT" '+%F %T' 2>/dev/null || echo "in ${TOTAL_MIN}m")"
- # family-initial credentials: what relaunch_pane falls back to before any rotation
- GLM_BASE_URL_INITIAL="${ANTHROPIC_BASE_URL:-}"
- GLM_TOKEN_INITIAL="${ANTHROPIC_AUTH_TOKEN:-}"
- fresh_session=0
- if ! tmux has-session -t "$SESSION" 2>/dev/null; then
- # entrypoint normally owns first boot; reaching this means it never ran
- # (manual start) or tmux died — the watchdog must be self-sufficient
- tmux new-session -d -s "$SESSION" -n commander 2>>"$LOG" || { log "FATAL: cannot create tmux session $SESSION"; exit 1; }
- fresh_session=1
- log "created tmux session $SESSION (window 0 = commander)"
- fi
- adopt_existing
- if (( fresh_session )); then
- relaunch_commander "fresh session, no commander running"
- elif ! tmux list-windows -t "$SESSION" -F '#W' 2>/dev/null | grep -qx commander; then
- relaunch_commander "commander window absent at startup"
- fi
- # ---- main loop ----------------------------------------------------------------
- while (( $(NOW) < END_AT )); do
- ensure_session || { sleep 15; continue; }
- adopt_existing
- wins=$(tmux list-windows -t "$SESSION" -F '#W' 2>/dev/null || true)
- # -- 1) commander pane dead -> relaunch + bootstrap --------------------------
- cmd_handled=0
- if ! printf '%s\n' "$wins" | grep -qx commander; then
- relaunch_commander "commander window gone"
- cmd_handled=1
- else
- cpane=$(pane_text commander)
- if printf '%s' "$cpane" | grep -q 'DRIVE_PANE_EXITED'; then
- relaunch_commander "commander pane exited"
- cmd_handled=1
- fi
- fi
- # -- 1b) DELETED: the pane_current_command whitelist (claude|node) was
- # unreliable across claude-code builds — it false-positived on the
- # LIVE commander TUI every ~60s and boot-looped it on the hosted run
- # (input box existed => TUI alive, yet "no claude process" fired).
- # Death is now judged ONLY by the iron signals in check 1:
- # DRIVE_PANE_EXITED on screen, or the window gone.
- # -- 2) unsubmitted bootstrap text in the input box -> re-Enter x3 -> restart
- # (matches both the watchdog's and the entrypoint's bootstrap text)
- if (( ! cmd_handled )); then
- if printf '%s' "$cpane" | grep -qE "❯.*docker/commander/SKILL\.md"; then
- enter_tries[commander]=$(( ${enter_tries[commander]:-0} + 1 ))
- case $(( ${enter_tries[commander]} )) in
- 1|2)
- log "commander: input unsubmitted — re-Enter (${enter_tries[commander]}/3)"
- tmux send-keys -t "$SESSION:commander" Enter
- sleep 2
- ;;
- 3)
- # stuck twice: clear the box and retype the whole bootstrap (the
- # text may be mangled mid-line; fresh keystrokes beat more Enters)
- log "commander: input unsubmitted — clearing and resending bootstrap (3/3)"
- tmux send-keys -t "$SESSION:commander" C-u
- sleep 0.5
- tmux send-keys -t "$SESSION:commander" C-u
- sleep 0.5
- tmux send-keys -t "$SESSION:commander" Enter
- sleep 1
- relaunch_commander "bootstrap never submits cleanly"
- ;;
- esac
- last_activity[commander]=$(NOW)
- cmd_handled=1
- else
- enter_tries[commander]=0
- fi
- fi
- # -- 2b) commander hang failsafe: pane content unchanged for 30 min (and
- # nothing waiting in the input box) -> the TUI is wedged, not thinking.
- # A dead-silent commander for the rest of the slot is the worst
- # outcome; a relaunch costs one --continue.
- if (( ! cmd_handled )); then
- csha=$(printf '%s' "$cpane" | sha256sum | cut -c1-12)
- if [[ "${cmd_pane_sha:-}" == "$csha" && -n "$csha" ]]; then
- if (( $(NOW) - ${cmd_pane_since:-$(NOW)} > 1800 )) \
- && ! printf '%s' "$cpane" | grep -qE '❯.+[^ ]'; then
- log "commander: pane frozen 30min with empty input — relaunching (hang failsafe)"
- relaunch_commander "hang failsafe"
- cmd_handled=1
- fi
- else
- cmd_pane_sha="$csha"; cmd_pane_since=$(NOW)
- fi
- fi
- # -- 3+4) commander: dialogs first, then quota -------------------------------
- if (( ! cmd_handled )); then
- if accept_dialogs commander "$cpane"; then
- last_activity[commander]=$(NOW); cmd_handled=1
- elif printf '%s' "$cpane" | grep -qE "$QUOTA_RE"; then
- if printf '%s' "$cpane" | grep -qE "$RATELIMIT_RE"; then
- cooldown_log commander-rl "transient rate limit (not quota) — no rotation; claude retries on its own"
- elif rotation_allowed && rotate_key; then
- cooldown_log commander "quota/auth error in commander — key rotated, relaunching"
- relaunch_commander "quota/auth error"
- else
- cooldown_log commander "quota/auth error in commander and no spare key — waiting"
- fi
- last_activity[commander]=$(NOW); cmd_handled=1
- fi
- fi
- # -- 3,4,5) worker panes ------------------------------------------------------
- for win in $wins; do
- [[ "$win" == "commander" ]] && continue
- pane=$(pane_text "$win")
- # 3) any confirm dialog -> accept
- if accept_dialogs "$win" "$pane"; then
- last_activity[$win]=$(NOW); continue
- fi
- # 4) quota/auth -> rotate; TUI restarts budget-free, -p only logged
- if printf '%s' "$pane" | grep -qE "$QUOTA_RE"; then
- if printf '%s' "$pane" | grep -qE "$RATELIMIT_RE"; then
- cooldown_log "$win-rl" "$win: transient rate limit (not quota) — no rotation; claude retries on its own"
- last_activity[$win]=$(NOW); continue
- fi
- if rotation_allowed && rotate_key; then
- if [[ "${mode[$win]:-tui}" == "p" ]]; then
- cooldown_log "$win" "quota/auth error in -p pane — key rotated; leaving pane (commander will notice via board)"
- else
- cooldown_log "$win" "quota/auth error — key rotated, relaunching TUI with --continue (restart budget untouched)"
- relaunch_worker "$win" "quota/auth error" || true
- fi
- else
- cooldown_log "$win" "quota/auth error and no spare key — leaving pane as-is"
- fi
- last_activity[$win]=$(NOW); continue
- fi
- # 4b) TUI worker mission stuck unsubmitted in the input box -> re-Enter,
- # then restart the window (regression from tmux-drive.sh #3: the
- # hosted gateway is slow and paste-loss strands the mission text,
- # leaving a live-looking pane that NEVER calls the LLM)
- if [[ "${mode[$win]:-tui}" == "tui" ]] \
- && printf '%s' "$pane" | grep -qE '❯.*autonomous pentest operator'; then
- enter_tries[$win]=$(( ${enter_tries[$win]:-0} + 1 ))
- if (( ${enter_tries[$win]} > 3 )); then
- mission_restarts[$win]=$(( ${mission_restarts[$win]:-0} + 1 ))
- if (( ${mission_restarts[$win]} > 3 )); then
- # restart loops help nothing (live: 25min of re-Enter/restart cycling
- # on a wedged TUI) — stop touching it, leave the diagnosis to the
- # commander (peek + kill/park). Cooldown-log to avoid spam.
- cooldown_log "$win-ms" "$win: mission wedged past 3 restarts — leaving pane for the commander"
- last_activity[$win]=$(NOW)
- continue
- fi
- log "$win: mission never submits — restarting window (${mission_restarts[$win]}/3)"
- enter_tries[$win]=0
- relaunch_worker "$win" "mission never submits" || true
- else
- log "$win: mission unsubmitted — re-Enter (${enter_tries[$win]}/3)"
- tmux send-keys -t "$SESSION:$win" Enter
- sleep 2
- fi
- last_activity[$win]=$(NOW)
- continue
- fi
- # 5) TUI worker exited -> relaunch with --continue, max 3/pane; -p = done
- if printf '%s' "$pane" | grep -q 'DRIVE_PANE_EXITED'; then
- if [[ "${mode[$win]:-tui}" == "p" ]]; then
- cooldown_log "$win" "$win: -p run exited — leaving pane for the commander (peek + worker.sh kill)"
- continue
- fi
- restarts[$win]=$(( ${restarts[$win]:-0} + 1 ))
- if (( ${restarts[$win]} > MAX_RESTARTS )); then
- cooldown_log "$win" "$win: TUI exited with no restarts left ($MAX_RESTARTS used) — leaving dead pane for the commander"
- continue
- fi
- relaunch_worker "$win" "TUI exited (${restarts[$win]}/$MAX_RESTARTS)" || true
- continue
- fi
- # 7) stall (no pane change > SAPPER_STALL_SECONDS): deliberately NO nudge,
- # NO restart — keeping processes alive is the watchdog's whole job
- done
- sleep 15
- done
- finish_all
- exit 0
docker/commander/worker.sh · Bundled script · 776 lines · 3 findings marked
- #!/usr/bin/env bash
- # worker.sh v1 — the commander's hands: one-shot subcommands, no main loop.
- #
- # Failure modes handled:
- # - platform "max active" cap (HTTP 409) -> detected on arena start, friendly
- # PLATFORM CAP message + exit 3; every arena call is guarded so a 409 never
- # crashes the caller (inherited trap: "arena HTTP 409 must never crash")
- # - worker pane cap -> live window count vs
- # SAPPER_MAX_WORKERS enforced before any platform call, exit 4 WORKER CAP
- # - trust/bypass/permission dialogs -> per-project hasTrustDialogAccepted
- # preset + Down+Enter auto-accept while waiting for the input box
- # - bracketed paste breaks ink TUIs -> send-keys -l ONLY, never
- # load-buffer/paste-buffer
- # - mission stuck unsubmitted in input box-> confirm text in pane, retry once
- # - pane death detection -> every worker window ends with
- # "echo DRIVE_PANE_EXITED; exec sleep infinity" (list/board/watchdog read it)
- # - same-cwd --continue cross-talk -> one dir per agent; -w2+ mounts the
- # shared graph via a .sapper symlink instead of a second graph
- # - instance active but panes all dead -> container addrs persisted to
- # ROOT/<code>/.addrs and reused when arena start refuses/duplicates
- # - rotated gateway keys (watchdog) -> spawn syncs the tmux SESSION env so
- # new panes inherit the CURRENT key, not the server-startup key (tmux only
- # copies update-environment vars from the client — ANTHROPIC_* is not in it)
- # - repeated calls -> idempotent: kill-window before
- # create, guarded sapper init, next free -wN index derived from live panes
- set -o pipefail
- ROOT="${SAPPER_ROOT:-/work/runs}"
- LOG="$ROOT/drive.log"
- # Model tiers & gateways (SKILL 4.9, final doctrine): ALL-IN FLAGSHIP.
- # glm gw + SMART (glm-5.3[1m]) is the default brain for EVERY worker — soldier,
- # scout, chore, general alike. flash is retired from this deployment.
- # ds gw (deepseek-flash) is the RESERVE army: takes over when glm quota/
- # rate limits bite (the watchdog rotates; the commander may also spawn
- # --gw ds deliberately under quota pressure).
- # mixed doctrine: soldiers default to the ds tier (cheap mass), generals and
- # the commander run SAPPER_MODEL (the strong brain) — the general-escalation
- # below fires when model==MODEL, which holds for this default.
- # NOTE: inline SAPPER_MODEL_DS (DS_MODEL is defined LATER in this header —
- # referencing it here silently fell back to glm and killed the ds army).
- MODEL="${SAPPER_MODEL_DS:-${SAPPER_MODEL:-glm-5.3[1m]}}"
- DS_MODEL="${SAPPER_MODEL_DS:-deepseek-flash}"
- DS_BASE_URL="${DEEPSEEK_BASE_URL:-https://api.deepseek.com/anthropic}"
- DS_KEY="${DEEPSEEK_API_KEY:-}"
- SESSION=sapper-cmd
- MAX_WORKERS="${SAPPER_MAX_WORKERS:-8}"
- DEF_MINUTES=10
- SAPPER="${SAPPER_BIN:-sapper}"
- ACT_FILE="$ROOT/.worker-activity.tsv"
- PANE_ENV_DIR="$ROOT/pane-env"
- NOW() { date +%s; }
- mkdir -p "$ROOT" "$PANE_ENV_DIR"
- log() { printf '[worker] %s\n' "$*" | tee -a "$LOG" >&2; }
- die() { local rc=$1; shift; printf '[worker] ERROR: %s\n' "$*" >&2; exit "$rc"; }
- is_code() { [[ "$1" =~ ^[A-Za-z0-9][A-Za-z0-9_.:-]*$ ]]; }
- window_exists() { tmux list-windows -t "$SESSION" -F '#W' 2>/dev/null | grep -qx -- "$1"; }
- # ---- arena helper (verbatim from tmux-drive.sh; module path env-overridable
- # for host-side testing — in-image default is identical) ------------------
- arena() {
- python3 - "$@" <<'PYEOF2'
- import importlib.util, json, os, sys
- spec = importlib.util.spec_from_file_location(
- "arena", os.environ.get("SAPPER_ARENA_LIB", "/opt/sapper/lib/arena.py"))
- m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
- c = m.ArenaClient.load(None)
- op = sys.argv[1]
- if op == "list":
- print(json.dumps(c.list_challenges()))
- elif op == "start":
- print(json.dumps(c.start_challenge(sys.argv[2])))
- elif op == "close":
- print(json.dumps(c.close_challenge(sys.argv[2])))
- PYEOF2
- }
- # submit every recorded-unsubmitted flag fact in a challenge's graph
- # (verbatim from tmux-drive.sh; module path env-overridable as above)
- finish_flags() { # finish_flags <code>
- python3 - "$1" <<'PYFIN'
- import glob, json, os, sys, importlib.util
- code = sys.argv[1]
- root = os.environ.get("SAPPER_ROOT", "/work/runs")
- spec = importlib.util.spec_from_file_location(
- "arena", os.environ.get("SAPPER_ARENA_LIB", "/opt/sapper/lib/arena.py"))
- m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
- try:
- client = m.ArenaClient.load(None)
- except Exception as exc:
- print(f"[finish] {code}: no arena ({exc})"); sys.exit(0)
- for path in sorted(glob.glob(f"{root}/{code}/.sapper/facts/*.json")):
- try:
- fact = json.load(open(path))
- except Exception:
- continue
- if fact.get("kind") != "flag":
- continue
- data = fact.get("data") or {}
- if data.get("status") not in (None, "recorded") or not data.get("value"):
- continue
- try:
- r = client.submit_flag(code, data["value"])
- fact["data"]["status"] = "submitted" if r.get("correct") else "rejected"
- json.dump(fact, open(path, "w"), ensure_ascii=False, indent=2)
- print(f"[finish] {code}: submit {data['value'][:24]}… correct={r.get('correct')}")
- except Exception as exc:
- msg = str(exc)
- if "already" in msg.lower() or "409" in msg:
- # duplicate submit = the flag WAS accepted earlier: absorb it
- fact["data"]["status"] = "submitted"
- json.dump(fact, open(path, "w"), ensure_ascii=False, indent=2)
- print(f"[finish] {code}: already submitted — marked ({data['value'][:20]}…)")
- else:
- print(f"[finish] {code}: submit failed ({exc})")
- PYFIN
- }
- # ---- pane primitives (verbatim from tmux-drive.sh) ---------------------------
- pane_text() { tmux capture-pane -pt "$SESSION:$1" 2>/dev/null; }
- send_literal() { # send_literal <window> <text> [enter] — NEVER bracketed paste
- tmux send-keys -t "$SESSION:$1" -l -- "$2"
- sleep 0.5
- [[ "${3:-enter}" == "enter" ]] && tmux send-keys -t "$SESSION:$1" Enter
- }
- accept_dialogs() { # accept_dialogs <window> <pane-text> -> 0 if a dialog was dismissed
- local win="$1" pane="$2"
- if printf '%s' "$pane" | grep -qE 'Enter to confirm|Yes, I accept|I accept'; then
- # Aim by the ❯ focus marker: security dialogs default-focus "No, exit",
- # so a bare Enter CHOOSES NO. Only move+confirm when focus is off Yes.
- if printf '%s' "$pane" | grep -qE '❯[^\n]*No, exit'; then
- tmux send-keys -t "$SESSION:$win" Down; sleep 0.4
- fi
- tmux send-keys -t "$SESSION:$win" Enter; sleep 1.5
- return 0
- fi
- return 1
- }
- # ---- worker-pane registry ----------------------------------------------------
- worker_windows() { # every window except the commander's window 0
- tmux list-windows -t "$SESSION" -F '#W' 2>/dev/null | grep -vx commander || true
- }
- count_workers() {
- local n; n=$(worker_windows | grep -c . || true)
- printf '%s' "${n:-0}"
- }
- panes_for_code() { # panes_for_code <code>
- local re=${1//./\\.}
- worker_windows | grep -E "^${re}-w[0-9]+$" || true
- }
- sync_session_env() { # tmux new-window inherits the SESSION environment, not the
- # calling client's env (only update-environment vars are
- # copied). Push the live gateway/platform env in so a key
- # rotated by the watchdog reaches freshly spawned panes;
- # PATH so the panes see the same tooling as the commander.
- local k v
- for k in PATH ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN SAPPER_MODEL \
- SAPPER_MODEL_FLASH BENCHMARK_BASE_URL BENCHMARK_TOKEN; do
- v=${!k:-}
- [[ -n "$v" ]] && tmux set-environment -t "$SESSION" "$k" "$v" >/dev/null 2>&1 || true
- done
- }
- # ---- activity tracking (worker.sh is one-shot; state lives on disk) ----------
- declare -A OLD_TS OLD_SHA NEW_TS NEW_SHA
- collect_panes() { # prints TSV: name <TAB> alive|exited <TAB> idle <TAB> since <TAB> WxH
- OLD_TS=(); OLD_SHA=(); NEW_TS=(); NEW_SHA=()
- local w ts h text st since now; now=$(NOW)
- if [[ -f "$ACT_FILE" ]]; then
- while IFS=$'\t' read -r w ts h; do OLD_TS[$w]=$ts; OLD_SHA[$w]=$h; done < "$ACT_FILE"
- fi
- while IFS='|' read -r w created cols rows; do
- [[ -n "$w" ]] || continue
- [[ "$w" == "commander" ]] && continue # window 0 is the commander, not a worker
- text=$(pane_text "$w")
- if printf '%s' "$text" | grep -q 'DRIVE_PANE_EXITED'; then st=exited; else st=alive; fi
- h=$(printf '%s' "$text" | sha256sum | cut -c1-16)
- if [[ "${OLD_SHA[$w]:-}" == "$h" && -n "${OLD_TS[$w]:-}" ]]; then ts=${OLD_TS[$w]}; else ts=$now; fi
- NEW_TS[$w]=$ts; NEW_SHA[$w]=$h
- since=$(date -d "@${created:-$now}" +%H:%M 2>/dev/null || echo '?')
- printf '%s\t%s\t%s\t%s\t%sx%s\n' "$w" "$st" "$(( now - ts ))" "$since" "${cols:-?}" "${rows:-?}"
- done < <(tmux list-windows -t "$SESSION" -F '#{window_name}|#{window_created}|#{window_width}|#{window_height}' 2>/dev/null)
- local tmp; tmp=$(mktemp) || return 0
- : > "$tmp"
- for w in "${!NEW_TS[@]}"; do
- printf '%s\t%s\t%s\n' "$w" "${NEW_TS[$w]}" "${NEW_SHA[$w]}" >> "$tmp"
- done
- mv "$tmp" "$ACT_FILE" # atomic; entries for dead panes are pruned
- }
- # ---- trust preset (verbatim from tmux-drive.sh launch()) ----------------------
- trust_preset() { # trust_preset <dir>
- local dir=$1
- mkdir -p "$dir/.claude"
- printf '%s\n' '{"permissions":{"defaultMode":"bypassPermissions"},"autoCompactEnabled":true}' > "$dir/.claude/settings.json"
- python3 - "$dir" <<'PYTRUST'
- import json, os, sys
- path = os.path.expanduser("~/.claude.json")
- try: d = json.load(open(path))
- except Exception: d = {}
- d.setdefault("projects", {})[sys.argv[1]] = {
- "hasTrustDialogAccepted": True, "bypassPermissionsModeAccepted": True}
- json.dump(d, open(path, "w"))
- PYTRUST
- }
- ensure_graph() { # ensure_graph <code> — guarded sapper init in the primary dir
- local code=$1
- [[ -f "$ROOT/$code/.sapper/project.json" ]] && return 0
- mkdir -p "$ROOT/$code"
- # $SAPPER is intentionally unquoted: SAPPER_BIN may carry its own args
- (cd "$ROOT/$code" && $SAPPER init --goal "solve $code, capture all flags" >/dev/null 2>&1 || true)
- }
- write_hint() { # write_hint <code> <text> — appends a [commander]-prefixed hint fact
- local code=$1 text=$2 store="$ROOT/$1/.sapper" hid
- ensure_graph "$code"
- hid=$($SAPPER --store "$store" hint "[commander] $text" --creator commander 2>&1) \
- || die 1 "hint: sapper hint failed for $code: $hid"
- log "hint -> $code: $hid (${text:0:50})"
- printf 'HINT %s -> %s\n' "$hid" "$code"
- }
- close_instance() { # close_instance <code> — finish_challenge pattern: flags first,
- # then arena close (guarded: a 409/HTTP error never crashes)
- local code=$1
- log "$code: submitting recorded flags before close"
- finish_flags "$code" 2>&1 | tee -a "$LOG" >&2 || true
- if arena close "$code" >/dev/null 2>&1; then
- log "$code: platform instance closed"
- else
- log "$code: arena close failed (instance may already be closed) — continuing"
- fi
- rm -f "$ROOT/$code/.addrs"
- }
- general_mission() { # general_mission <code> <addrs> — smart worker allowed to hire -p squads
- local code=$1 addrs=$2
- printf '%s' "You are a GENERAL (senior operator) on challenge $code. Think DEEPLY — you have the biggest brain on this challenge, use it: plan the full attack chain before executing, reason step by step. Targets: ${addrs}. You solve the challenge yourself AND you may hire one-shot squads for bounded chores: run /opt/sapper/docker/commander/worker.sh spawn $code --p --minutes 5 --mission \"<chore: recon sweep / verify a guess / fuzz one endpoint>\" — the squad runs ~5 min, prints results in its pane, then goes idle: peek its pane (worker.sh peek <pane> 120), harvest, and kill it (worker.sh kill <pane>). Squads share this challenge's fact graph — tell them to read it first. Caps: panes are limited (a spawn failing with exit 4 means wait or fire a squad); keep at most 2 squads at a time; never let a squad idle long after it finishes. Record findings as facts, capture EVERY flag and IMMEDIATELY run sapper flag \"flag{...}\" -c $code --submit. Communication with your commander: [HELP]/[REPORT] notes in the graph as usual. Work fully autonomously; reply DONE only when the challenge is finished. Flag submission: primary is sapper flag VALUE -c $code --submit; if that command errors, submit by direct POST to the platform endpoint $BENCHMARK_BASE_URL/openapi/v1/challenges/submit with a JSON body containing unique_code and flag fields plus header BENCHMARK_TOKEN from env — write the one-liner yourself with urllib or curl; both routes count."
- }
- default_mission() { # default_mission <code> <addrs> <primary 0|1>
- # operator prompt carried over from tmux-drive.sh launch()
- local code=$1 addrs=$2 primary=$3 extra=""
- (( ! primary )) && extra=" Another agent is also working $code from a sibling directory — you SHARE one fact graph: read the existing facts before repeating work, and record every new finding with sapper fact so your partner sees it."
- printf '%s' "You are an autonomous pentest operator in a CTF benchmark. Think DEEPLY before acting: plan multi-step exploits carefully, reason about what each command's output tells you before the next one — depth of thought is your main weapon. Challenge: $code. Target container addresses (reach them directly): ${addrs}. Mission: recon the target, find the vulnerabilities, capture EVERY flag, and for each flag IMMEDIATELY run: sapper flag \"flag{...}\" -c $code --submit (this submits to the scoring platform and prints the result). Record findings as typed facts: sapper fact \"...\" -k service -d host=... -d port=... Consult the knowledge base when unsure: sapper kb search \"keywords\". Multiple flags are likely — after one submission keep hunting the rest. Communication: your commander reads this challenge's fact graph every ~2 minutes — to reach it, record a fact: sapper fact \"[HELP] <exactly what you tried, what blocks you, what decision you need>\" -k note (only when GENUINELY blocked, max one open HELP at a time; keep working alternatives while waiting) or \"[REPORT] <significant intel>\" -k note (interesting findings your commander may relay to other challenges). Do not wait idle for replies. When totally done, reply with the single word DONE.$extra"
- }
- # ---- spawn -------------------------------------------------------------------
- cmd_spawn() {
- local code="" mode=tui mission="" minutes=$DEF_MINUTES name="" model="" gw="" engine=claude general=0 a
- while (( $# )); do
- a=$1; shift
- case "$a" in
- --tui) mode=tui ;;
- --p|-p) mode=p ;;
- --general) general=1 ;;
- --gw) [[ $# -gt 0 ]] || die 1 "spawn: --gw needs a value (glm|ds)"; gw=$1; shift ;;
- --gw=*) gw=${a#*=} ;;
- --engine) [[ $# -gt 0 ]] || die 1 "spawn: --engine needs a value (claude|codex)"; engine=$1; shift ;;
- --engine=*) engine=${a#*=} ;;
- --mission) [[ $# -gt 0 ]] || die 1 "spawn: --mission needs a value"; mission=$1; shift ;;
- --mission=*) mission=${a#*=} ;;
- --minutes) [[ $# -gt 0 ]] || die 1 "spawn: --minutes needs a value"; minutes=$1; shift ;;
- --minutes=*) minutes=${a#*=} ;;
- --name) [[ $# -gt 0 ]] || die 1 "spawn: --name needs a value"; name=$1; shift ;;
- --name=*) name=${a#*=} ;;
- --model) [[ $# -gt 0 ]] || die 1 "spawn: --model needs a value"; model=$1; shift ;;
- --model=*) model=${a#*=} ;;
- -*) die 1 "spawn: unknown option $a" ;;
- *) [[ -z "$code" ]] || die 1 "spawn: unexpected argument $a"; code=$a ;;
- esac
- done
- [[ -z "$gw" || "$gw" == glm || "$gw" == ds ]] || die 1 "spawn: --gw must be glm or ds (got '$gw')"
- [[ "$engine" == claude || "$engine" == codex ]] || die 1 "spawn: --engine must be claude or codex"
- [[ -n "$code" ]] || die 1 "usage: worker.sh spawn <code> [--tui|--p] [--mission \"...\"] [--minutes N] [--name NAME] [--model <id>] [--gw glm|ds] [--engine claude|codex]"
- [[ "$gw" == ds && -z "$DS_KEY" && "$engine" == claude ]] \
- && die 1 "spawn: --gw ds needs DEEPSEEK_API_KEY (unset — ask the operator, do not retry)"
- # default model per gateway: glm->flash tier, ds->deepseek-flash;
- # a GENERAL defaults to the smart tier (SKILL 4.10). NOTE: compare with
- # quoted `==` — unquoted/glob paths treat the [1m] suffix as a char class
- # and silently never match.
- [[ -n "$model" ]] || { [[ "$gw" == ds ]] && model="$DS_MODEL" || model="$MODEL"; }
- if (( general )) && [[ "$gw" == glm && "$model" == "$MODEL" ]]; then
- model="${SAPPER_MODEL:-glm-5.3[1m]}"
- fi
- # gateway auto-derives from the FINAL model's family (mixed doctrine: the
- # default soldier model is deepseek — its name on the glm gateway 404s,
- # which killed every soldier pane in a live run). Explicit --gw wins.
- [[ -z "$gw" ]] && { case "$model" in *deepseek*) gw=ds;; *) gw=glm;; esac; }
- is_code "$code" || die 1 "spawn: invalid code '$code'"
- [[ "$minutes" =~ ^[0-9]+$ ]] || die 1 "spawn: --minutes must be an integer (got '$minutes')"
- tmux has-session -t "$SESSION" 2>/dev/null \
- || die 1 "tmux session '$SESSION' missing (entrypoint/watchdog owns it)"
- # hard worker cap BEFORE touching the platform (an instance slot is precious)
- local nw; nw=$(count_workers)
- if (( nw >= MAX_WORKERS )); then
- die 4 "WORKER CAP: $nw/$MAX_WORKERS worker panes live — kill one first (worker.sh kill <pane>)"
- fi
- local existing; existing=$(panes_for_code "$code")
- local max=0 n w
- for w in $existing; do
- [[ "$w" =~ ^${code//./\\.}-w([0-9]+)$ ]] && { n=${BASH_REMATCH[1]}; (( n > max )) && max=$n; }
- done
- local ordinal=$(( max + 1 ))
- local pane
- if [[ -n "$name" ]]; then
- pane=$name
- [[ "$pane" =~ ^[A-Za-z0-9_-]+$ ]] || die 1 "spawn: --name must be [A-Za-z0-9_-] (tmux target parsing)"
- if window_exists "$pane"; then
- # re-spawning one of THIS code's own worker panes is allowed (idempotent);
- # colliding with a foreign window is not
- [[ "$pane" =~ ^${code//./\\.}-w[0-9]+$ ]] \
- || die 1 "spawn: window '$pane' already exists (belongs to another pane)"
- fi
- else
- pane="${code}-w${ordinal}"
- fi
- # primary agent = first pane of this code; it owns ROOT/<code>; -w2+ get their
- # own dir with the shared graph symlinked in (no same-cwd --continue crosstalk)
- local primary=0 dir="$ROOT/$code"
- (( max == 0 )) && primary=1
- (( primary )) || dir="$ROOT/${code}-w${ordinal}"
- # 1) platform instance — only when this code has no live pane and no known addrs
- local addrs="" started="" got="" err
- [[ -f "$ROOT/$code/.addrs" ]] && addrs=$(cat "$ROOT/$code/.addrs" 2>/dev/null)
- if (( ! primary )) && [[ -n "$addrs" ]]; then
- : # instance already up (shared with w1) — do not re-start, just reuse addrs
- else
- err=$(mktemp)
- started=$(arena start "$code" 2>"$err" || true)
- got=$(printf '%s' "$started" | python3 -c '
- import json,sys
- try: print(" ".join(json.load(sys.stdin).get("container_addr") or []))
- except Exception: pass' 2>/dev/null)
- if [[ -n "$got" ]]; then
- addrs=$got
- printf '%s\n' "$addrs" > "$ROOT/$code/.addrs"
- elif grep -qi "max active" "$err" 2>/dev/null; then
- rm -f "$err"
- die 3 "PLATFORM CAP: close a challenge first (worker.sh kill <code> --close) — cannot start $code"
- elif [[ -z "$addrs" ]]; then
- local e; e=$(tail -n 3 "$err" 2>/dev/null | tr '\n' ' ')
- rm -f "$err"
- die 1 "spawn: arena start failed for $code: ${e:-no container_addr returned}"
- else
- log "$code: arena start refused but persisted addrs look valid — reusing instance"
- fi
- rm -f "$err"
- fi
- # 2) dirs + shared graph
- if (( primary )); then
- mkdir -p "$dir"
- ensure_graph "$code"
- else
- ensure_graph "$code"
- mkdir -p "$dir"
- ln -sfn "../$code/.sapper" "$dir/.sapper"
- fi
- # 3) trust preset
- trust_preset "$dir"
- # 4/5) the window (NO --continue: fresh session per pane; watchdog owns recovery)
- sync_session_env
- tmux kill-window -t "$SESSION:$pane" 2>/dev/null
- # persist the pane's tier+gateway so watchdog relaunches keep the same brain.
- # RAW values, never %q: bash %q escapes the [1m] suffix -> '\\[1m\\' and
- # pane_model()'s sed would feed claude a backslashed model id. TUI missions
- # are archived base64 so the watchdog can re-brief a restarted pane (a
- # relaunched claude is a FRESH session — nobody else will send its mission).
- local mission_b64=""
- [[ "$mode" == tui && "$engine" == claude && -n "$mission" ]] \
- && mission_b64=$(printf '%s' "$mission" | base64 -w0)
- printf 'MODEL=%s\nGW=%s\nENGINE=%s\nMISSION_B64=%s\n' \
- "$model" "$gw" "$engine" "$mission_b64" > "$PANE_ENV_DIR/$pane.env"
- # per-pane gateway env: ds panes override ANTHROPIC_* with the deepseek endpoint
- local gw_env=""
- [[ "$gw" == ds ]] && gw_env="ANTHROPIC_BASE_URL='$DS_BASE_URL' ANTHROPIC_AUTH_TOKEN='$DS_KEY'"
- if [[ "$mode" == tui ]]; then
- if [[ "$engine" == codex ]]; then
- # codex 0.42: provider via -c overrides on top of ~/.codex/config.toml
- # (chat wire for DeepSeek). ds-local = official endpoint for local sims.
- local provider=deepseek; [[ "$DS_BASE_URL" == https://api.deepseek.com* ]] && provider=deepseek-local
- tmux new-window -d -t "$SESSION" -n "$pane" \
- "cd $dir && DEEPSEEK_API_KEY='$DS_KEY' codex --skip-git-repo-check -c model_provider=$provider -c model='$model' --dangerously-bypass-approvals-and-sandbox 2>&1; echo DRIVE_PANE_EXITED; exec sleep infinity"
- Note: Starts a coding agent with its permission prompts off
- Line 395 on GitHub
- else
- tmux new-window -d -t "$SESSION" -n "$pane" \
- "cd $dir && $gw_env claude --model '$model' --effort max --dangerously-skip-permissions 2>&1; echo DRIVE_PANE_EXITED; exec sleep infinity"
- Note: Starts a coding agent with its permission prompts off
- Line 398 on GitHub
- fi
- else
- if [[ "$engine" == codex ]]; then
- [[ -n "$mission" ]] || mission=$(default_mission "$code" "$addrs" "$primary")
- local esc_mission=${mission//\'/\\'\'}
- tmux new-window -d -t "$SESSION" -n "$pane" \
- "cd $dir && DEEPSEEK_API_KEY='$DS_KEY' codex exec --skip-git-repo-check -c model_provider=deepseek-local -c model='$model' --dangerously-bypass-approvals-and-sandbox '$esc_mission' 2>&1; echo DRIVE_PANE_EXITED; exec sleep infinity"
- Note: Starts a coding agent with its permission prompts off
- Line 405 on GitHub
- printf 'SPAWNED %s addrs=%s model=%s engine=codex\n' "$pane" "$addrs" "$model"
- return 0
- else
- tmux new-window -d -t "$SESSION" -n "$pane" \
- "cd $dir && $gw_env SAPPER_MODEL='$model' $SAPPER --store $ROOT/$code/.sapper auto --minutes $minutes --skip-permissions 2>&1; echo DRIVE_PANE_EXITED; exec sleep infinity"
- fi
- fi
- # 6) mission
- if [[ "$mode" == tui && "$engine" == codex ]]; then
- # codex TUI readiness: no claude-style ❯ marker; wait for the process to
- # settle, then type the mission (codex accepts typed input at its prompt)
- sleep 12
- [[ -z "$mission" ]] && mission=$(default_mission "$code" "$addrs" "$primary")
- send_literal "$pane" "$mission"
- log "$pane: codex TUI spawned (dir=$dir), mission sent"
- elif [[ "$mode" == tui ]]; then
- local waited=0 ptext="" frag
- while (( waited < 75 )); do
- ptext=$(pane_text "$pane")
- accept_dialogs "$pane" "$ptext" && { waited=$((waited+3)); continue; }
- printf '%s' "$ptext" | grep -q '❯' && break
- sleep 1; waited=$((waited+1))
- done
- printf '%s' "$ptext" | grep -q '❯' \
- || die 1 "spawn: $pane input box never appeared after 75s (pane left for inspection)"
- if [[ -z "$mission" ]]; then
- if (( general )); then mission=$(general_mission "$code" "$addrs")
- else mission=$(default_mission "$code" "$addrs" "$primary"); fi
- fi
- send_literal "$pane" "$mission"
- sleep 3
- ptext=$(pane_text "$pane")
- frag=${mission:0:24}
- if ! printf '%s' "$ptext" | grep -qF -- "$frag" \
- && ! printf '%s' "$ptext" | grep -q 'esc to interrupt'; then
- log "$pane: mission not confirmed in pane — retrying once"
- send_literal "$pane" "$mission"
- sleep 3
- fi
- log "$pane: TUI spawned (dir=$dir), mission sent"
- else
- sleep 2
- if printf '%s' "$(pane_text "$pane")" | grep -q 'DRIVE_PANE_EXITED'; then
- die 1 "spawn: $pane -p command exited immediately — check the sapper invocation in the pane"
- fi
- [[ -n "$mission" ]] && write_hint "$code" "$mission"
- log "$pane: -p worker spawned (dir=$dir, minutes=$minutes)"
- fi
- # 7)
- printf 'SPAWNED %s addrs=%s model=%s\n' "$pane" "$addrs" "$model"
- }
- # ---- kill --------------------------------------------------------------------
- cmd_kill() {
- local close=0 target="" a
- while (( $# )); do
- a=$1; shift
- case "$a" in
- --close) close=1 ;;
- -*) die 1 "kill: unknown option $a" ;;
- *) [[ -z "$target" ]] || die 1 "kill: unexpected argument $a"; target=$a ;;
- esac
- done
- [[ -n "$target" ]] || die 1 "usage: worker.sh kill <pane>|<code> [--close]"
- tmux has-session -t "$SESSION" 2>/dev/null \
- || die 1 "tmux session '$SESSION' missing (entrypoint/watchdog owns it)"
- local re=${target//./\\.} wins
- if window_exists "$target"; then
- wins=$target
- else
- wins=$(worker_windows | grep -E "^${re}-w[0-9]+$" || true)
- fi
- [[ -n "$wins" ]] || die 1 "kill: no pane matches '$target'"
- local code=$target w
- [[ "$code" =~ -w[0-9]+$ ]] && code=${code%-w*}
- for w in $wins; do
- if tmux kill-window -t "$SESSION:$w" 2>/dev/null; then
- log "killed $w"
- else
- log "kill: window $w already gone"
- fi
- rm -f "$PANE_ENV_DIR/$w.env"
- done
- if (( close )); then
- local left; left=$(panes_for_code "$code")
- if [[ -n "$left" ]]; then
- log "$code: sibling panes still alive ($left) — instance kept open, flags not touched"
- return 0
- fi
- close_instance "$code"
- fi
- }
- # ---- msg / peek / list -------------------------------------------------------
- cmd_msg() {
- local pane=${1:-} text=${2:-}
- [[ -n "$pane" && -n "$text" ]] || die 1 'usage: worker.sh msg <pane> "<text>"'
- tmux has-session -t "$SESSION" 2>/dev/null || die 1 "tmux session '$SESSION' missing"
- window_exists "$pane" || die 1 "msg: no such pane '$pane'"
- send_literal "$pane" "$text"
- log "msg -> $pane: ${text:0:60}"
- }
- cmd_peek() {
- local pane=${1:-} lines=${2:-40}
- [[ -n "$pane" ]] || die 1 "usage: worker.sh peek <pane> [lines=40]"
- [[ "$lines" =~ ^[0-9]+$ ]] || die 1 "peek: lines must be an integer"
- tmux has-session -t "$SESSION" 2>/dev/null || die 1 "tmux session '$SESSION' missing"
- window_exists "$pane" || die 1 "peek: no such pane '$pane'"
- tmux capture-pane -p -t "$SESSION:$pane" 2>/dev/null | tail -n "$lines"
- }
- cmd_list() {
- local info; info=$(collect_panes) || true
- if [[ -z "$info" ]]; then
- printf '(no worker panes)\n'
- return 0
- fi
- local w st idle since size
- while IFS=$'\t' read -r w st idle since size; do
- printf '%s %s idle=%ss size=%s since=%s\n' "$w" "$st" "$idle" "$size" "$since"
- done <<< "$info"
- }
- # ---- board -------------------------------------------------------------------
- cmd_board() {
- local as_json=0 a
- while (( $# )); do
- a=$1; shift
- case "$a" in
- --json) as_json=1 ;;
- *) die 1 "board: unknown option $a (try --json)" ;;
- esac
- done
- local arena_tmp pane_tmp rc
- arena_tmp=$(mktemp); pane_tmp=$(mktemp)
- arena list > "$arena_tmp" 2>/dev/null || printf '[]\n' > "$arena_tmp"
- collect_panes > "$pane_tmp" || true
- python3 - "$arena_tmp" "$pane_tmp" "$ROOT" "$MAX_WORKERS" "$as_json" <<'PYBOARD'
- import glob, json, os, re, sys, time
- arena_path, pane_path, root = sys.argv[1], sys.argv[2], sys.argv[3]
- max_workers, as_json = int(sys.argv[4]), sys.argv[5] == "1"
- def load_json(path, default):
- try:
- with open(path) as fh:
- return json.load(fh)
- except Exception:
- return default
- # -- platform rows (arena list; unreachable platform degrades to empty) --------
- plat = {}
- for c in (load_json(arena_path, []) or []):
- if isinstance(c, dict) and isinstance(c.get("unique_code"), str):
- plat[c["unique_code"]] = {
- "completed": bool(c.get("is_completed")),
- "flags_correct": int(c.get("correct_flag_count") or 0),
- "flags_total": int(c.get("flag_count") or 0),
- }
- # -- graphs (dedupe -wN symlinked graphs by realpath; never trust file contents)
- graphs = {}
- for pj in sorted(glob.glob(os.path.join(root, "*", ".sapper", "project.json"))):
- d = os.path.dirname(os.path.dirname(pj))
- code = re.sub(r"-w\d+$", "", os.path.basename(d))
- key = os.path.realpath(os.path.join(d, ".sapper"))
- if key in graphs:
- continue
- kinds, latest, total = {}, 0.0, 0
- flags = {"recorded": 0, "submitted": 0}
- helps = 0
- for fp in glob.glob(os.path.join(d, ".sapper", "facts", "*.json")):
- total += 1
- try:
- f = json.load(open(fp))
- latest = max(latest, os.path.getmtime(fp))
- except Exception:
- continue
- k = f.get("kind")
- if k:
- kinds[k] = kinds.get(k, 0) + 1
- if k == "flag":
- st = (f.get("data") or {}).get("status") or "recorded"
- flags[st] = flags.get(st, 0) + 1
- if k == "note" and "[HELP]" in str(f.get("description", "")) + str(f.get("data") or ""):
- helps += 1
- intents = {"open": 0, "claimed": 0, "done": 0, "complete": 0}
- for ip in glob.glob(os.path.join(d, ".sapper", "intents", "*.json")):
- try:
- st = json.load(open(ip)).get("status")
- except Exception:
- continue
- if st in intents:
- intents[st] += 1
- graphs[key] = {"code": code, "facts_total": total, "kinds": kinds,
- "flags_recorded": flags["recorded"],
- "flags_submitted": flags["submitted"],
- "intents": intents, "latest_mtime": latest, "helps": helps}
- by_code = {}
- for g in graphs.values():
- cur = by_code.get(g["code"])
- if cur is None or g["facts_total"] > cur["facts_total"]:
- by_code[g["code"]] = g
- # -- panes merged in ------------------------------------------------------------
- panes, alive = {}, 0
- for line in open(pane_path):
- parts = line.rstrip("\n").split("\t")
- if len(parts) != 5:
- continue
- w, st, idle, since, size = parts
- m = re.match(r"^(.*)-w\d+$", w)
- panes.setdefault(m.group(1) if m else w, []).append(
- {"pane": w, "state": st, "idle": int(idle), "since": since, "size": size})
- if st == "alive":
- alive += 1
- codes = sorted(set(plat) | set(by_code) | set(panes),
- key=lambda c: (0 if c in panes else (1 if c in by_code else 2), c))
- rows = []
- for c in codes:
- p, g = plat.get(c) or {}, by_code.get(c) or {}
- rows.append({
- "code": c,
- "completed": p.get("completed"),
- "platform_flags": ([p["flags_correct"], p["flags_total"]] if p else None),
- "facts_total": g.get("facts_total", 0),
- "kinds": g.get("kinds", {}),
- "intents": g.get("intents", {}),
- "flags_recorded": g.get("flags_recorded", 0),
- "flags_submitted": g.get("flags_submitted", 0),
- "helps": g.get("helps", 0),
- "latest": time.strftime("%H:%M", time.localtime(g["latest_mtime"]))
- if g.get("latest_mtime") else "-",
- "panes": panes.get(c, []),
- })
- if as_json:
- print(json.dumps({"now": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
- "workers_alive": alive, "worker_cap": max_workers,
- "codes": rows}, ensure_ascii=False, separators=(",", ":")))
- raise SystemExit(0)
- # heartbeat to drive.log (=> docker logs): the commander boards every loop,
- # so this line IS the campaign pulse for the outside observer.
- flags_r = sum(r["flags_recorded"] for r in rows)
- flags_s = sum(r["flags_submitted"] for r in rows)
- done_n = sum(1 for r in rows if r["completed"])
- # war clock + general census: the commander's dashboard gauges
- left = "-"
- try:
- dl = float(open(os.path.join(root, ".deadline")).read().strip())
- secs = dl - time.time()
- if secs >= 0:
- left = ("%dh%02dm" % (secs // 3600, (secs % 3600) // 60))
- else:
- left = "OVER"
- except Exception:
- pass
- generals = 0
- try:
- import glob as _g
- for pf in _g.glob(os.path.join(root, "pane-env", "*.env")):
- try:
- m = [l for l in open(pf) if l.startswith("MODEL=")][0][6:].strip()
- except Exception:
- continue
- if m and "flash" not in m and "deepseek" not in m:
- generals += 1
- except Exception:
- pass
- print(f"[board] heartbeat: codes={len(rows)} done={done_n} "
- f"alive={alive}/{max_workers} flags_recorded={flags_r} "
- f"flags_submitted={flags_s} budget_left={left} generals={generals}", file=sys.stderr)
- def kinds_str(k):
- if not k:
- return "-"
- order = ["host", "service", "cred", "vuln", "loot", "flag", "note"]
- parts = [f"{n[0]}{k[n]}" for n in order if k.get(n)]
- parts += [f"{n[:2]}{v}" for n, v in sorted(k.items()) if n not in order]
- return (" ".join(parts) or "-")[:16]
- def panes_str(lst):
- if not lst:
- return "-"
- out = []
- for p in lst:
- m = re.match(r"^.*-w(\d+)$", p["pane"])
- lbl = f"w{m.group(1)}" if m else p["pane"]
- out.append(f"{lbl}:{p['idle']}s" if p["state"] == "alive" else f"{lbl}:X")
- return " ".join(out)
- widths = [("CODE(⚑=HELP!)", 17), ("DONE", 4), ("FLG", 7), ("FACTS", 6), ("KINDS", 16),
- ("INT o/c", 8), ("FLG r/s", 7), ("LAST", 5)]
- print(f"== sapper board {time.strftime('%H:%M')} workers alive={alive}/{max_workers}"
- f" codes={len(rows)} ==")
- print(" ".join(t.ljust(w) for t, w in widths) + "PANES")
- budget = 100 - 3 # header + column line + trailing guard
- for i, r in enumerate(rows):
- if i >= budget:
- print(f"... {len(rows) - i} more codes (use: worker.sh board --json)")
- break
- pf = r["platform_flags"]
- done = "-" if r["completed"] is None else ("yes" if r["completed"] else "no")
- codecell = r["code"][:14]
- if r.get("helps"):
- codecell = "⚑%d %s" % (r["helps"], codecell)[:14 + 3]
- cells = [
- codecell.ljust(17), done.ljust(4),
- (f"{pf[0]}/{pf[1]}" if pf else "-").ljust(7),
- (str(r["facts_total"]) if r["facts_total"] else "-").ljust(6),
- kinds_str(r["kinds"]).ljust(16),
- f"{r['intents'].get('open', 0)}/{r['intents'].get('claimed', 0)}".ljust(8),
- f"{r['flags_recorded']}/{r['flags_submitted']}".ljust(7),
- r["latest"].ljust(5), panes_str(r["panes"]),
- ]
- print(" ".join(cells).rstrip())
- PYBOARD
- rc=$?
- rm -f "$arena_tmp" "$pane_tmp"
- return "$rc"
- }
- # ---- hint --------------------------------------------------------------------
- cmd_hint() {
- local code=${1:-} text=${2:-}
- [[ -n "$code" && -n "$text" ]] || die 1 'usage: worker.sh hint <code> "<text>"'
- is_code "$code" || die 1 "hint: invalid code '$code'"
- write_hint "$code" "$text"
- }
- usage() {
- cat >&2 <<'USAGE'
- worker.sh — the commander's hands (one-shot subcommands; no main loop)
- spawn <code> [--tui|--p] [--mission "..."] [--minutes N] [--name NAME] [--model <id>]
- [--gw glm|ds] [--engine claude|codex] [--general]
- --model: worker brain (default flash tier; smart =
- 'glm-5.3[1m]' — SKILL 4.9 tiering rules)
- --general: smart-tier GENERAL that may hire its own
- -p squads on the same challenge (SKILL 4.10)
- kill <pane>|<code> [--close] --close submits flags + closes the instance
- only when no sibling pane of that code lives
- msg <pane> "<text>" send-keys -l + Enter (never bracketed paste)
- peek <pane> [lines=40]
- list <pane> alive|exited idle=<s> size=WxH since=<hh:mm>
- board [--json] the war board (<100 lines)
- hint <code> "<text>" append a [commander] hint fact to that graph
- exit codes: 0 ok | 1 generic error | 3 platform cap (max active) | 4 worker cap
- USAGE
- }
- case "${1:-}" in
- spawn) shift; cmd_spawn "$@" ;;
- kill) shift; cmd_kill "$@" ;;
- msg) shift; cmd_msg "$@" ;;
- peek) shift; cmd_peek "$@" ;;
- list) shift; cmd_list "$@" ;;
- board) shift; cmd_board "$@" ;;
- hint) shift; cmd_hint "$@" ;;
- help|-h|--help) usage; exit 0 ;;
- "") usage; exit 1 ;;
- *) printf '[worker] ERROR: unknown subcommand %s\n' "$1" >&2; usage; exit 1 ;;
- esac
docker/tmux-drive.sh · Bundled script · 363 lines · 1 finding marked
- #!/usr/bin/env bash
- # tmux-drive.sh v2 — self-healing driver for the TUI-mode agent fleet.
- #
- # Failure modes handled:
- # - Enter lost / mission stuck in the input box -> re-Enter (3 tries), then restart window
- # - trust/bypass/permission dialogs -> auto-accept (Down+Enter)
- # - claude TUI exits / pane dead -> relaunch window (max 2/challenge)
- # - agent stuck (no pane change) -> nudge; still stuck at budget -> stop
- # - driver restart -> adopts existing tmux windows (idempotent)
- # - challenge DONE or per-challenge timeout -> submit recorded flags, close, next
- set -o pipefail
- ROOT="${SAPPER_ROOT:-/work/runs}"
- LOG="$ROOT/drive.log"
- MODEL="${SAPPER_MODEL:-glm-5.3-flash[1m]}"
- PARALLEL="${SAPPER_PARALLEL:-6}"
- TOTAL_MIN="${SAPPER_TOTAL_MINUTES:-470}"
- PER_MIN="${SAPPER_MINUTES_PER_CHALLENGE:-25}"
- STALL_SECONDS="${SAPPER_STALL_SECONDS:-300}"
- SESSION=sapper-tui
- MAX_RESTARTS=2
- mkdir -p "$ROOT"
- log() { printf '[drive] %s\n' "$*" | tee -a "$LOG"; }
- END_AT=$(( $(date +%s) + TOTAL_MIN * 60 ))
- NOW() { date +%s; }
- declare -A launch_at last_activity restarts finished claim_start last_pane_state
- # ---- arena helper (graph-free) ----------------------------------------------
- arena() {
- python3 - "$@" <<'PYEOF2'
- import importlib.util, json, sys
- spec = importlib.util.spec_from_file_location("arena", "/opt/sapper/lib/arena.py")
- m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
- c = m.ArenaClient.load(None)
- op = sys.argv[1]
- if op == "list":
- print(json.dumps(c.list_challenges()))
- elif op == "start":
- print(json.dumps(c.start_challenge(sys.argv[2])))
- elif op == "close":
- print(json.dumps(c.close_challenge(sys.argv[2])))
- PYEOF2
- }
- # ---- key-pool rotation ------------------------------------------------------
- # SAPPER_KEY_POOL: JSON [{base_url,token,model},...]. On quota/balance/auth
- # errors the driver rotates its own env; windows relaunched afterwards
- # inherit the new key, and `claude --continue` restores the prior session.
- rotate_key() {
- python3 - <<'PYROT'
- import json, os
- raw = os.environ.get("SAPPER_KEY_POOL", "").strip()
- try:
- pool = [p for p in json.loads(raw) if isinstance(p, dict) and p.get("token")]
- except Exception:
- pool = []
- if not pool:
- raise SystemExit(1)
- cur = os.environ.get("ANTHROPIC_AUTH_TOKEN", "")
- start = next((i for i, e in enumerate(pool) if e["token"] == cur), -1)
- nxt = pool[(start + 1) % len(pool)]
- if start >= 0 and nxt["token"] == cur:
- raise SystemExit(1) # single key: nothing to rotate to
- for k, v in (
- ("ANTHROPIC_BASE_URL", nxt.get("base_url")),
- ("ANTHROPIC_AUTH_TOKEN", nxt["token"]),
- ("SAPPER_MODEL", nxt.get("model")),
- ):
- if v:
- os.environ[k] = v
- with open(os.environ.get("SAPPER_ROOT", "/work/runs") + "/rotated.env", "w") as fh:
- fh.write(
- f'export ANTHROPIC_BASE_URL="{os.environ["ANTHROPIC_BASE_URL"]}"\n'
- f'export ANTHROPIC_AUTH_TOKEN="{os.environ["ANTHROPIC_AUTH_TOKEN"]}"\n'
- f'export SAPPER_MODEL="{os.environ.get("SAPPER_MODEL", "")}"\n'
- )
- raise SystemExit(0)
- PYROT
- local rc=$?
- if (( rc == 0 )) && [[ -f "$ROOT/rotated.env" ]]; then
- # shellcheck disable=SC1090
- . "$ROOT/rotated.env"; export ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN SAPPER_MODEL
- log "key rotated -> $ANTHROPIC_BASE_URL (model $SAPPER_MODEL)"
- return 0
- fi
- return 1
- }
- QUOTA_RE='insufficient|balance|quota|exceeded|billing|payment|401|[Uu]nauthorized|invalid.{0,12}[Aa][Pp][Ii].[Kk]ey|欠费|余额'
- # submit every recorded-unsubmitted flag fact in a challenge's graph
- finish_flags() { # finish_flags <code>
- python3 - "$1" <<'PYFIN'
- import glob, json, os, sys, importlib.util
- code = sys.argv[1]
- root = os.environ.get("SAPPER_ROOT", "/work/runs")
- spec = importlib.util.spec_from_file_location("arena", "/opt/sapper/lib/arena.py")
- m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
- try:
- client = m.ArenaClient.load(None)
- except Exception as exc:
- print(f"[finish] {code}: no arena ({exc})"); sys.exit(0)
- for path in sorted(glob.glob(f"{root}/{code}/.sapper/facts/*.json")):
- try:
- fact = json.load(open(path))
- except Exception:
- continue
- if fact.get("kind") != "flag":
- continue
- data = fact.get("data") or {}
- if data.get("status") not in (None, "recorded") or not data.get("value"):
- continue
- try:
- r = client.submit_flag(code, data["value"])
- fact["data"]["status"] = "submitted" if r.get("correct") else "rejected"
- json.dump(fact, open(path, "w"), ensure_ascii=False, indent=2)
- print(f"[finish] {code}: submit {data['value'][:24]}… correct={r.get('correct')}")
- except Exception as exc:
- print(f"[finish] {code}: submit failed ({exc})")
- PYFIN
- }
- finish_challenge() { # finish_challenge <code> <reason>
- local code="$1" reason="$2"
- [[ -n "${finished[$code]:-}" ]] && return 0
- finished[$code]=1
- log "$code: finishing ($reason)"
- finish_flags "$code" 2>&1 | tee -a "$LOG"
- arena close "$code" >/dev/null 2>&1 && log "$code: container closed"
- tmux kill-window -t "$SESSION:$code" 2>/dev/null
- }
- # ---- launch / adopt ---------------------------------------------------------
- pane_text() { tmux capture-pane -pt "$SESSION:$1" 2>/dev/null; }
- send_literal() { # send_literal <window> <text> [enter]
- tmux send-keys -t "$SESSION:$1" -l -- "$2"
- sleep 0.5
- [[ "${3:-enter}" == "enter" ]] && tmux send-keys -t "$SESSION:$1" Enter
- }
- accept_dialogs() { # accept_dialogs <window> <pane> -> 0 if a dialog was dismissed
- local win="$1" pane="$2"
- if printf '%s' "$pane" | grep -q 'Enter to confirm'; then
- tmux send-keys -t "$SESSION:$win" Down; sleep 0.4
- tmux send-keys -t "$SESSION:$win" Enter; sleep 1.5
- return 0
- fi
- return 1
- }
- launch() { # launch <code>
- local code="$1"
- local err; err=$(mktemp)
- local started; started=$(arena start "$code" 2>"$err" || true)
- LAST_LAUNCH_ERR="$(cat "$err" 2>/dev/null || true)"
- cat "$err" >>"$LOG" 2>/dev/null || true; rm -f "$err"
- local addrs; addrs=$(printf '%s' "$started" | python3 -c '
- import json,sys
- try: print(" ".join(json.load(sys.stdin).get("container_addr") or []))
- except Exception: pass' 2>/dev/null)
- log "$code: start -> ${addrs:-FAILED}"
- [[ -z "$addrs" ]] && return 1
- mkdir -p "$ROOT/$code/.claude"
- (cd "$ROOT/$code" && sapper init --goal "solve $code, capture all flags" >/dev/null 2>&1 || true)
- printf '%s\n' '{"permissions":{"defaultMode":"bypassPermissions"}}' > "$ROOT/$code/.claude/settings.json"
- python3 - "$ROOT/$code" <<'PYTRUST'
- import json, os, sys
- path = os.path.expanduser("~/.claude.json")
- try: d = json.load(open(path))
- except Exception: d = {}
- d.setdefault("projects", {})[sys.argv[1]] = {
- "hasTrustDialogAccepted": True, "bypassPermissionsModeAccepted": True}
- json.dump(d, open(path, "w"))
- PYTRUST
- tmux kill-window -t "$SESSION:$code" 2>/dev/null
- local resume_flag=""
- ls "$HOME/.claude/projects/"*"$code"*/ >/dev/null 2>&1 && resume_flag="--continue"
- tmux new-window -d -t "$SESSION" -n "$code" \
- "cd $ROOT/$code && claude $resume_flag --model '$MODEL' --dangerously-skip-permissions 2>&1; echo DRIVE_PANE_EXITED; exec sleep infinity"
- Note: Starts a coding agent with its permission prompts off
- Line 181 on GitHub
- launch_at[$code]=$(NOW); last_activity[$code]=$(NOW)
- restarts[$code]=$(( ${restarts[$code]:-0} ))
- claim_start[$code]=0
- # wait for the input box, auto-accepting dialogs
- local waited=0 pane=""
- while (( waited < 75 )); do
- pane=$(pane_text "$code")
- accept_dialogs "$code" "$pane" && { waited=$((waited+3)); continue; }
- printf '%s' "$pane" | grep -q '❯' && break
- sleep 1; waited=$((waited+1))
- done
- printf '%s' "$pane" | grep -q '❯' || { log "$code: input box never appeared"; return 1; }
- local mission
- mission="You are an autonomous pentest operator in a CTF benchmark. Challenge: $code. Target container addresses (reach them directly): ${addrs}. Mission: recon the target, find the vulnerabilities, capture EVERY flag, and for each flag IMMEDIATELY run: sapper flag \"flag{...}\" -c $code --submit (this submits to the scoring platform and prints the result). Record findings as typed facts: sapper fact \"...\" -k service -d host=... -d port=... Consult the knowledge base when unsure: sapper kb search \"keywords\". Multiple flags are likely (${PER_MIN}min budget) — after one submission keep hunting the rest. Work fully autonomously, never ask questions. When totally done, reply with the single word DONE."
- send_literal "$code" "$mission"
- sleep 3
- # verify: mission text visible in the input box, OR agent already working
- pane=$(pane_text "$code")
- if ! printf '%s' "$pane" | grep -q 'autonomous pentest operator\|esc to interrupt'; then
- log "$code: mission not confirmed in pane — retrying once"
- send_literal "$code" "$mission"
- sleep 3
- fi
- last_activity[$code]=$(NOW)
- log "$code: TUI launched, mission sent"
- return 0
- }
- adopt_existing() {
- local win
- for win in $(tmux list-windows -t "$SESSION" -F '#W' 2>/dev/null | grep -v '^supervisor$'); do
- [[ -n "${launch_at[$win]:-}" ]] && continue
- launch_at[$win]=$(NOW); last_activity[$win]=$(NOW); restarts[$win]=0
- log "$win: adopted existing window after driver restart"
- done
- }
- list_pending() {
- arena list 2>>"$LOG" | python3 -c '
- import json,sys
- try: items=json.load(sys.stdin)
- except Exception: sys.exit(0)
- for c in items:
- if isinstance(c,dict) and not c.get("is_completed"): print(c["unique_code"])' 2>/dev/null
- }
- # ---- build the pending queue -------------------------------------------------
- mapfile -t ALL_CODES < <(list_pending)
- log "challenges pending: ${ALL_CODES[*]:-none} (parallel=$PARALLEL, per=$PER_MIN min, total=$TOTAL_MIN min)"
- idx=0
- adopt_existing
- # ---- main loop ---------------------------------------------------------------
- while (( $(NOW) < END_AT )); do
- active_windows=$(tmux list-windows -t "$SESSION" -F '#W' 2>/dev/null | grep -v '^supervisor$' || true)
- active_count=$(printf '%s\n' "$active_windows" | grep -c . || true)
- # top up to PARALLEL with not-yet-started codes
- while (( ${active_count:-0} < PARALLEL && idx < ${#ALL_CODES[@]} )); do
- code="${ALL_CODES[idx]}"
- idx=$((idx+1))
- if [[ -n "${finished[$code]:-}" ]]; then continue; fi
- if printf '%s\n' "$active_windows" | grep -qx "$code"; then continue; fi
- if (( ${restarts[$code]:-0} > MAX_RESTARTS )); then
- log "$code: exceeded restart budget, parking"
- continue
- fi
- launch "$code" && active_count=$((active_count+1)) || {
- if printf '%s' "${LAST_LAUNCH_ERR:-}" | grep -qi "max active"; then
- # platform cap — not this challenge's fault: requeue it and stop
- # burning through the list (a full sweep marks everything failed
- # and exhausts idx, after which top-up never runs again).
- idx=$((idx-1))
- log "$code: platform active cap — requeued, waiting for a free slot"
- break
- fi
- restarts[$code]=$((${restarts[$code]:-0}+1))
- log "$code: launch failed (restart ${restarts[$code]}/$MAX_RESTARTS)"
- }
- sleep 3
- done
- for win in $active_windows; do
- pane=$(pane_text "$win")
- # 1) any confirm dialog -> accept
- if accept_dialogs "$win" "$pane"; then
- last_activity[$win]=$(NOW); continue
- fi
- # 2) pane dead (claude exited)
- if printf '%s' "$pane" | grep -q 'DRIVE_PANE_EXITED'; then
- restarts[$win]=$(( ${restarts[$win]:-0} + 1 ))
- if (( ${restarts[$win]} > MAX_RESTARTS )); then
- finish_challenge "$win" "TUI exited, no restarts left"
- else
- log "$win: TUI exited — relaunching (${restarts[$win]}/$MAX_RESTARTS)"
- tmux kill-window -t "$SESSION:$win" 2>/dev/null
- launch "$win" || true
- fi
- continue
- fi
- # 3) mission text sitting unsubmitted in the input box -> re-Enter
- if printf '%s' "$pane" | grep -q '❯.*autonomous pentest operator'; then
- claim_start[$win]=$((${claim_start[$win]:-0}+1))
- if (( ${claim_start[$win]} > 3 )); then
- log "$win: mission never submits — restarting window"
- tmux kill-window -t "$SESSION:$win" 2>/dev/null
- launch "$win" || true
- else
- log "$win: mission in input box unsubmitted — re-Enter (${claim_start[$win]}/3)"
- tmux send-keys -t "$SESSION:$win" Enter
- sleep 2
- fi
- last_activity[$win]=$(NOW); continue
- fi
- # 3.5) quota/auth exhaustion in the pane -> rotate key, relaunch with resume
- if printf '%s' "$pane" | grep -qE "$QUOTA_RE"; then
- if rotate_key; then
- log "$win: quota/auth error in pane — key rotated, relaunching (session resumes)"
- restarts[$win]=${restarts[$win]:-0} # rotation is not the agent's fault: don't burn restarts
- tmux kill-window -t "$SESSION:$win" 2>/dev/null
- launch "$win" || true
- else
- log "$win: quota/auth error and no spare key — nudging later"
- fi
- last_activity[$win]=$(NOW); continue
- fi
- # 4) activity tracking + stall nudge
- if [[ -n "$pane" && "$pane" != "${last_pane_state[$win]:-}" ]]; then
- last_pane_state[$win]="$pane"; last_activity[$win]=$(NOW)
- else
- idle=$(( $(NOW) - ${last_activity[$win]:-$(NOW)} ))
- if (( idle > STALL_SECONDS )); then
- log "$win: stalled ${idle}s — nudging"
- send_literal "$win" "Continue autonomously. If stuck, change approach or hunt the next flag. Ensure every captured flag was submitted via sapper flag. Reply DONE only when finished."
- last_activity[$win]=$(NOW)
- fi
- fi
- # 5) DONE detection -> finish and free the slot
- if printf '%s' "$pane" | tail -60 | grep -q '\bDONE\b'; then
- sleep 8 # let trailing flag submissions land
- finish_challenge "$win" "agent reported DONE"
- continue
- fi
- # 6) per-challenge budget
- if (( $(NOW) - ${launch_at[$win]:-$(NOW)} > (PER_MIN * 60 + 120) )); then
- tmux send-keys -t "$SESSION:$win" C-c 2>/dev/null; sleep 2
- finish_challenge "$win" "per-challenge budget exhausted"
- continue
- fi
- done
- # all challenges finished? (re-read windows: top-up may have changed them)
- active_windows=$(tmux list-windows -t "$SESSION" -F '#W' 2>/dev/null | grep -v '^supervisor$' || true)
- if (( idx >= ${#ALL_CODES[@]} )) && [[ -z "$active_windows" ]]; then
- left=$(arena list 2>>"$LOG" | python3 -c '
- import json,sys
- try: items=json.load(sys.stdin)
- except Exception: print(999); sys.exit()
- print(sum(1 for c in items if not c.get("is_completed")))' 2>/dev/null || echo 999)
- if (( ${left:-999} == 0 )); then
- log "all challenges complete"; break
- else
- log "platform still shows ${left:-?} unfinished — refreshing queue"
- mapfile -t ALL_CODES < <(list_pending)
- idx=0
- for k in "${!finished[@]}"; do unset "finished[$k]"; done
- fi
- fi
- sleep 15
- done
- log "deadline reached — wrapping up"
- for win in $(tmux list-windows -t "$SESSION" -F '#W' 2>/dev/null | grep -v '^supervisor$'); do
- tmux send-keys -t "$SESSION:$win" C-c 2>/dev/null
- done
- sleep 3
- for win in $(tmux list-windows -t "$SESSION" -F '#W' 2>/dev/null | grep -v '^supervisor$'); do
- finish_challenge "$win" "deadline"
- done
- log "drive complete"
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.