pi-ctf

A pi package for authorized CTF work. Log in to a CTF platform once, pull challenge categories into isolated workspaces, and either solve them in the current session or delegate one worker agent per challenge through Herdr and pi-herdr. Optional pi-web-access support gives agents documentation-only web access.

Built for end-to-end CTF automation: acquire challenge files, prepare workspaces, launch specialized workers, recover flags, and optionally submit verified results.

The package includes category-specific skills for rev, web, pwn, crypto, forensics, misc, and OSINT, distilled from hands-on CTF experience and competition data. This is an early-stage open-source project; contributions—especially improvements to the skills—are welcome.

Four tools, two commands, no persistent daemon. The opt-in dashboard is an ephemeral loopback server for the current Pi session.

| Surface | Purpose | | --- | --- | | ctf_login | Log in to a CTFd/Laravel form, noCTF, or CTFd API-token platform, or read a public archive; stores a confirmed session (0600), never the password or token | | ctf_pull | Download a category (or chosen ids) so this session can solve the challenges | | ctf_solve | Download a category and delegate one worker per challenge; optional orchestrator submit: true | | ctf_local | Delegate local challenge directories; submit: true requires verified ctfctl platform metadata | | /ctfctl / /ctfctf | The whole thing from a slash command (/ctfctf is a compatibility alias) — see below |

Everything a human needs is one command. After installing the package and opening pi:

/ctfctl login https://ctf.example.com player     # masked password prompt
/ctfctl login https://ctf.example.com            # --auth token: CTFd API token from CTFCTL_TOKEN
/ctfctl login https://ctf.example.com --auth public   # a finished CTF's static export
/ctfctl status                                   # who am I logged in as, and with which credential
/ctfctl pull rev                                 # download the rev category, then solve it here
/ctfctl pull rev --dry-run                       # read-only plan: what would be downloaded, nothing written
/ctfctl pull rev --hints none                    # no hint request at all (nothing is ever unlocked)
/ctfctl solve rev                                # download it and open a worker pane per challenge
/ctfctl solve web 12,13                          # only those ids
/ctfctl solve rev --model gpt-5.6-luna --provider openai-codex-account-4 --thinking high  # optional worker runtime overrides
/ctfctl local rev ./my-pack                      # delegate a local challenge pack
/ctfctf local pwn ./arena-snapshots --model deepseek-v4-flash-vision-exp --provider opencode-go --thinking max --mode headless --timeout 480  # isolated local pwn race; hard 8-minute cap
/ctfctl local rev ./my-pack --dashboard                  # open the live worker Web UI; flags appear as workers solve
/ctfctl solve web --dashboard                            # watch every downloaded challenge/agent in one dashboard
/ctfctl solve web --submit                               # orchestrator submits each fresh FLAG.txt using the logged-in session
/ctfctl solve rev --mode herd --dashboard --submit       # watch workers and platform verdicts live
/ctfctl local rev ./challenges/rev --mode headless --submit  # supported for verified ctfctl-prepared platform workspaces
/ctfctl local rev ./my-pack --model gpt-5.6-luna --provider openai-codex-account-3 --thinking max --handoff <replacement-model> --provider-handoff <replacement-provider> --thinking-handoff max --handoff-timeout 900  # opt-in model handoff after 15 minutes instead of the five-minute default
/ctfctl solve rev --model mimo-v2.5-pro --provider opencode-go --thinking high --handoff <replacement-model> --provider-handoff <replacement-provider> --thinking-handoff max
/ctfctl checker                                   # report every FLAG.txt under this workspace as JSON
/ctfctl checker ./challenges/rev                 # scan one directory instead
/ctfctl checker watch                             # keep watching: a new FLAG.txt posts itself to the session
/ctfctl checker stop                              # stop watching
/ctfctl logout

Use cases

A few examples of the extension in action.

Solving in parallel

https://github.com/user-attachments/assets/af07f8e7-2076-4608-a9f4-5bbd1e73480d

2-minute demo of parallel solving — unmute for audio.

Dashboard

Install

Published package: pi-ctf on npm · Pi package details

npm (recommended)

# Install the latest stable release
pi install npm:pi-ctf

# Try it for one run without installing
pi -e npm:pi-ctf

# Update or remove the installed package
pi update npm:pi-ctf
pi remove npm:pi-ctf

GitHub or local checkout

# Install the latest source from GitHub
pi install https://github.com/Nhan-Laptop/pi-ctf-solver

# Equivalent git shorthand
pi install git:github.com/Nhan-Laptop/pi-ctf-solver

# Install from a local checkout
pi install /path/to/pi-ctf-solver

For the parallel worker panes, also install pi-herdr and run pi inside a Herdr pane: pi install npm:@yunosukeyoshino/pi-herdr. Without it the extension still works — it falls back to herd_spawn plans or isolated headless workers.

Installing pi-ctf also registers the ctf-* skills (skills/), which give the agent category playbooks for rev, web, pwn, crypto, forensics, misc and osint.

Development:

npm install
npm run typecheck
npm test
npm run lint
scripts/check-tools.sh --profile all   # host tools + every module in requirements.txt

Requirements

Python packages are in requirements.txt, grouped by the skill that needs each one and annotated with the module it provides:

python3 -m pip install -r requirements.txt

Two interpreters are involved and they are not interchangeable. sage -c is the only one with fpylll/numpy/sympy/gmpy2/igraph; plain python3 has Crypto, cryptography, z3, pwn, Pillow, capstone, elftools and lief. In this build neither sage -python nor sage --python exists, so the [sage] entries have to be installed with the Sage environment's own interpreter:

SAGE_PY=$(sage -c "import sys; print(sys.executable)")   # e.g. …/envs/sage/bin/python
"$SAGE_PY" -m pip install -r requirements.txt

scripts/check-tools.sh reads that file literally and imports every module for real, so it cannot rot silently: a missing required module fails the preflight, an optional one is only reported. A batch imports every selected module into one fresh interpreter, so an earlier import can satisfy a later entry (elftools is reached through pwn, numpy/gmpy2 through Sage). Such a row is disclosed as already_loaded rather than reported as an independent check. When a row has to be proven on its own, re-check exactly those rows in fresh processes:

python3 tools/crypto/check_dependencies.py --profile crypto --verify-isolated

A batch that could not run is reported with unverified evidence and never as a plain absence. When one batch fails, attribute it to the entries instead of guessing:

python3 tools/crypto/check_dependencies.py --profile crypto --isolate-failed

Each failed entry is probed on its own in a fresh bounded process, so the report says which entry broke while the overall run still fails: attribution is diagnosis, not a pass.

scripts/check-tools.sh                   # core: pi, node, python3, binutils + requirements.txt
scripts/check-tools.sh --profile crypto  # + the Sage environment behind the [sage] entries
scripts/check-tools.sh --profile all     # + rev/forensics niceties and every dependency

| Skill | Python | Host binaries (not pip) | | --- | --- | --- | | ctf-crypto | [sage] fpylll, numpy, sympy, gmpy2, igraph · [py3] pycryptodome, z3, pwn, cryptography | sage, flatter (optional escalation) | | ctf-pwn | pwntools, capstone, pyelftools | | | ctf-rev | z3, pwntools, pyelftools, capstone, lief, Pillow | | ctf-forensics | volatility3 (optional) | binwalk, exiftool, tshark, steghide (zsteg/pngcheck optional) | | ctf-web | requests | curl, openssl | | ctf-osint, ctf-misc | the shared set above (Crypto, Pillow, z3) | — |

A missing crypto/rev/forensics tool degrades one category rather than blocking the extension, and every worker is told which interpreter actually holds the Sage stack.

Safety

Use this only for competitions and wargames where automated tooling, target traffic and local analysis are expressly authorized. Extension code and worker agents run with your full user permissions — there is no sandbox — so only run challenges you are willing to execute locally.

Layout

extensions/ctfctl/
├── index.ts       # tool + command registration, secret prompts, pull/preview orchestration
├── auth.ts        # credential model, header mapping, identity verification, URL redaction
├── session.ts     # login methods, v1/v2 session storage, platform cache
├── secret.ts      # masked secret field (paste, unicode, ctrl+u/ctrl+w, cancel)
├── html.ts        # conservative HTML -> Markdown for descriptions
├── platform.ts    # authenticated CTF client (reads by default; metadata/hints; explicit submit API)
├── workspace.ts   # challenge directories, briefs, metadata sidecar, atomic downloads, .revtools
├── http.ts        # keep-alive HTTP client with timings and retry
├── delegate.ts    # herdr pane spawn, herd_spawn plan, headless fallback
├── dashboard.ts   # opt-in tokenized loopback Web UI, live status/SSE and FLAG.txt monitor
├── submit.ts      # opt-in fresh-flag monitor, dedupe and durable submission state
├── artifacts.ts   # bounded no-symlink workspace artifact reads
├── handoff.ts     # controlled PROGRESS.md and same-session replacement lifecycle
├── local.ts       # local challenge discovery
├── categories.ts  # canonical categories and platform aliases
├── crypto.ts      # deterministic crypto candidate triage
├── service.ts     # endpoint extraction + bounded read-only first contact
└── watchdog.ts    # stall watchdog for long-running workers
skills/            # ctf-core + one playbook per category (ctf-crypto/references: briefs + repos)
tools/reverse/     # bounded triage/runtime helpers copied to <challenge>/.revtools
tools/crypto/      # artifact digest + the crypto reference-recipe checks
scripts/           # host tool preflight (reads requirements.txt), run compilers, benchmarks
requirements.txt   # Python packages per skill, verified by scripts/check-tools.sh
tests/             # vitest: fake CTFd/noCTF/archive fixtures + tool-level tests
docs/              # login/crypto/rev measurements
.auto/             # the measurement loop: measure.sh, checks.sh, sweep-metrics.sh