ctfkit

A modular CTF toolkit — solve a challenge, then turn the solution into a reusable tool.中文

---

⚠️ Authorized use only. This toolkit is intended for CTF competitions, lab environments, and security testing with written authorization. Any use against systems without explicit permission is illegal. The author is not responsible for misuse. You are responsible for your own actions.

---

Why

Every CTF player knows the feeling: you spend 30 minutes hand-crafting a payload, finally crack the challenge, and then six weeks later you face the same problem in another competition and have to re-derive everything from scratch.

ctfkit is a small, opinionated antidote to that:

• Solve first, toolize second. Every function in this repo started as a one-shot script that solved a real challenge. If a tool doesn't come from a real pain point, it doesn't belong here.
• One tool, one job. No monolithic "Swiss army knife" — each @tool function does exactly one thing.
• 5-minute toolchain. Adding a new tool is a single decorator, a single import line, and a single test. If it's harder than that, the design is wrong.

Demo

$ ctfkit list --category web
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Category ┃ Name                ┃ Description                                 ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ web      │ rce.octal-escape    │ 用 bash ANSI-C quoting 八进制转义包裹命令   │
│ web      │ rce.bin-here-string │ 用 bash arithmetic + here-string 构造      │
└──────────┴─────────────────────┴──────────────────────────────────────────────┘

$ ctfkit run rce.octal-escape cmd="ls /tmp"
$'\\154\\163' $'\\57\\164\\155\\160'

$ ctfkit run rce.octal-escape cmd="id" --json
"$'\\151\\144'"

Quick start

git clone https://github.com/azerl/ctfkit.git
cd ctfkit
pip install -e ".[crypto,web,misc,dev]"

ctfkit list                          # see what's available
ctfkit show encoding.base64-decode   # inspect a tool
ctfkit run encoding.base64-decode data="SGVsbG8="   # run it → "Hello"
pytest                               # run the test suite

Design principles

1. Trivial to add a tool — one file + one @tool decorator.
2. Tools are decoupled — no cross-imports, no hidden state.
3. Pure inputs, pure outputs — tools accept explicit parameters and return plain data (str / dict / numbers). No I/O side effects inside the tool body; the CLI layer handles rendering.
4. CLI is just a thin entrypoint — every tool is a plain Python function you can import and call directly.

Add a new tool

After solving a CTF challenge, drop the reusable bit into ctfkit:

# src/ctfkit/crypto/rsa.py
from ctfkit.core.registry import tool

@tool(name="rsa.wiener", category="crypto", description="RSA 维纳攻击")
def wiener(e: int, n: int) -> int:
    """Wiener's attack: recover d when e is large."""
    # ... your implementation ...
    return d

# src/ctfkit/crypto/__init__.py
from . import rsa  # noqa: F401

# tests/test_crypto.py
def test_wiener_known_case():
    """2024 XXXX CTF — known answer."""
    assert wiener(e=..., n=...) == expected_d

That's it. The tool is now discoverable via ctfkit list, documented via ctfkit show, and invokable via ctfkit run rsa.wiener ....

Available tools

Category	Tool	Description
crypto	encoding.base64-decode	Base64 解码
crypto	encoding.base64-encode	Base64 编码
crypto	encoding.hex-decode	Hex 解码(支持 0x 前缀 / 分隔符)
crypto	encoding.hex-encode	Hex 编码
crypto	encoding.url-decode	URL 解码
crypto	encoding.url-encode	URL 编码
web	rce.octal-escape	bash ANSI-C quoting 八进制转义
web	rce.bin-here-string	bash arithmetic + here-string payload 构造

More tools land here every time a new challenge gets solved.

Project layout

ctfkit/
├── pyproject.toml
├── README.md
├── LICENSE
├── .github/workflows/test.yml
├── src/ctfkit/
│   ├── cli.py
│   ├── core/                # base / registry / output
│   ├── crypto/              # 密码学(encoding, classical, rsa, ...)
│   ├── misc/                # 杂项(stego, traffic, archive, ...)
│   └── web/                 # Web 安全(rce, sqli, ssti, jwt, ...)
├── tests/
└── examples/                # 每道做过的真题 + 解法记录

Naming convention

Tools follow <category>.<sub-category>.<action>:

• encoding.base64-decode
• rsa.wiener
• stego.lsb-extract
• web.jwt.none-alg

Categories are restricted to crypto / misc / web (extendable later).

Dependency groups

pip install -e ".[crypto]"   # crypto tools only
pip install -e ".[web]"      # web tools only
pip install -e ".[misc]"     # misc tools only
pip install -e ".[all]"      # everything
pip install -e ".[dev]"      # pytest + dev tools

Roadmap

The roadmap is not a feature wishlist — it's a mirror of challenges already solved. New tools land here as their motivating challenges get cracked.

• Project skeleton + decorator-based registry
• CLI: list / show / run / version
• Encoding helpers (Base64 / Hex / URL)
• RCE payload generators (octal escape / bin here-string)
• Classical ciphers (Caesar / Vigenère / Rail-fence)
• RSA attacks (Wiener / common-modulus / small-e / Pollard p-1)
• Image steganography (LSB / channel split / EXIF)
• Traffic analysis (TCP stream / USB keystroke)
• Web helpers (SSTI / JWT / SQLi assist)

Contributing

PRs welcome. Two rules:

1. Every new tool must come with a real challenge it solves (cite the source in the docstring or a tests/ example).
2. Don't add tools that wrap a famous library without justification — if pwntools / sqlmap already does it, just call those.

License

MIT — see LICENSE.