AIxCTF

A Claude Code-centered AutoResearch Runtime for autonomous CTF solving.

Most CTF agents are prompt wrappers. AIxCTF experiments with the missing
runtime layer around Claude Code:

• bounded research rounds;
• durable state and resumable artifacts;
• isolated multi-challenge scheduling;
• hook checkpoints and scope guards;
• evidence-gated results;
• handoff and recovery artifacts.

Context is not memory. Durable state is memory.

AIxCTF is an early, architecture-first MVP. It is not a benchmark claim, a
production-grade sandbox, or a promise that Claude Code can solve every CTF
challenge.

Why not just prompt Claude Code?

Claude Code is the semantic solver: it reasons about the challenge, runs
experiments, and attempts exploits. The AIxCTF runtime owns the surrounding
lifecycle:

challenge
  -> runtime controller
  -> challenge scheduler
  -> bounded research round
  -> Claude Code
  -> hook checkpoints
  -> state, evidence, handoff, and result

A chat transcript is transient and difficult to audit. AIxCTF instead records
each challenge in an isolated workspace so a run can be inspected and resumed
from durable facts.

Research round model

A round is not simply another request for a flag. It is an observable research
step:

question -> hypothesis -> experiment -> observation
         -> evidence -> conclusion -> next experiment

The outer RuntimeController schedules challenge visits until challenges are
solved, exhausted, or a hard runtime limit is reached. In multi-challenge mode,
each active challenge gets its own workspace and Claude Code child process.

Evidence-gated results

The runtime does not accept a bare claim that a challenge is solved. A solved
result requires an exact flag, an evidence artifact containing the flag, and
reproducible command or script provenance. A failed result records a failure
reason and handoff so later work can continue from the observed state.

This is a first evidence gate, not an independent flag verifier. Stronger
verification is part of the roadmap.

Quick start

Requirements for a local dry-run:

• Python 3.11 or newer;
• no API key or Claude Code installation is required.

Syntax-check the runtime:

python3 -m compileall .claude

Run two bounded rounds without invoking Claude Code or writing generated files
into the repository:

WORKDIR=/tmp/aixctf-ws \
OUTPUT_DIR=/tmp/aixctf-out \
CHALLENGE_DIR=. \
CHALLENGE_ID=local-smoke \
AIXCTF_CHALLENGE_MODE=single \
AIXCTF_DRY_RUN=1 \
AIXCTF_MAX_ROUNDS=2 \
AIXCTF_MAX_ROUNDS_PER_VISIT=1 \
python3 .claude/entrypoint.py

The expected dry-run result is failed with
failure_reason: dry_run_no_solver. That status confirms the controller and
artifact pipeline ran without pretending a solver was present.

Build the runtime image:

docker build -t aixctf-agent .claude

For a real challenge run, mount or point CHALLENGE_DIR at the challenge input,
set a writable workspace and output directory, authenticate Claude Code through
its supported environment, and set AIXCTF_DRY_RUN=0.

Durable state and outputs

Each challenge workspace contains runtime-owned artifacts such as:

$WORKDIR/
  challenge/
  rounds/*.json
  events/*.json
  evidence/
  state.json
  progress.jsonl
  status.json
  notes.md
  handoff.md
  result.json

In multi-challenge mode, state is isolated under one workspace per challenge.
The controller writes individual challenge results plus a controller summary.

Architecture

The implementation lives under .claude/:

.claude/
  entrypoint.py   runtime entrypoint
  runner/         controller, scheduler, rounds, state, and results
  hooks/          deterministic tool checkpoints and guards
  sync/           fail-open human progress synchronization
  templates/      category and bounded subtask prompts
  docs/           routed tactical knowledge cards
  tools/          pwn and web triage helpers

Start with the architecture index, or read these focused documents:

• Architecture overview
• AutoResearch loop
• Runtime components
• State, artifacts, and results
• Subagents and handoff
• Hooks, progress, and human sync
• Knowledge library and prompts
• Build and acceptance criteria
• Architecture diagrams

Current limitations

• No independent flag verifier exists yet.
• Hooks are checkpoint controls and guardrails, not a complete security boundary.
• State is persisted, but updates do not yet provide full transactional or
  event-sourced recovery semantics.
• No public benchmark or solve-rate claim has been published.
• The Docker dependency chain needs stronger version and checksum pinning for
  reproducible builds.
• Context compilation and adaptive scheduling remain future work.

See ROADMAP.md for the planned progression from the current MVP to
a benchmarkable runtime.

Contributing

Technical feedback and focused contributions are welcome, especially around
verifiers, sandbox hardening, runtime reliability, challenge adapters,
benchmarking, scheduler policies, result schemas, and tactical knowledge cards.

Please keep runtime changes inside .claude/, preserve challenge scope checks,
and include the validation commands and security impact in pull requests.

License

Licensed under the Apache License 2.0.