N1nEmAn/sapper-v2

sapper-v2 orchestrates a swarm of AI agents for authorized penetration testing and CTF-style attack challenges. Rather than one clever agent, it uses a commander that reads the board and dispatches work, generals and soldiers that attack in parallel, and a script-only watchdog that keeps the system alive. The project reports winning the online qualifier of the 3rd Tencent Cloud Intelligent Attack-Defense Challenge with 80.18/100 across 634 teams, running 8 hours unattended.

How the legion works

At runtime there are three windows: the commander (reads the board, judges, dispatches, and never attacks itself), the AI legion (generals and soldiers in tmux panes), and the watchdog (a pure script that relaunches a crashed commander with --continue, rotates keys, and wraps up at the buzzer). The commander's doctrine is documented separately in a 426-line skill file from the competition, and an architecture contract sits alongside it (commander skill, architecture spec).

Two mechanisms distinguish it. First, history as a layered graph: facts are stored as title / summary / evidence document, so agents read the gist and drill down only when needed. The README says this addresses single-string fact graphs' failure modes—one bad fact poisoning downstream work, and wasted context. Second, model tiering: commanders and generals run on a stronger model while scouts and soldiers run a cheaper one, which the author ties to finishing on 1B tokens where the runner-up used 4.5B.

Getting started

A stdlib-only CLI is installed by install.sh, then configured with a goal and a target; sapper status shows the board and frontier. The full legion runs via Docker, with gateway, key-pool, and budget environment variables described in the project's environment doc (README). The README also points to a single-graph CLI and multi-challenge sweep workflow in SKILL.md.

Constraints and safety

The README restricts use to authorized security testing only and links a separate disclaimer (DISCLAIMER.md). The licence is MIT, so the disclaimer is the operational boundary, not a licence restriction. The author notes that fine offensive tools have been abused, and proposes a taggant mechanism to mark a harness so that illegal intrusions leak attribution data to victims; this is a proposal, not a shipped feature, and the author admits their own capacity to build it is limited.

The reported results are competition scores on Tencent's v1bench training ground, not an independent evaluation of real-world penetration testing. Claims of emergent behavior—a self-invented signalman role, performance reviews, inherited playbooks—are the author's retrospective account (BATTLE-REPORT.md), and the multi-stage success-rate figure is attributed to an unnamed industry report rather than measured in this project.