CTF Toolchain & Learning Platform

A modern, lightweight Capture The Flag (CTF) utility and context manager written in Python. This tool standardizes solving methodologies, captures solver context, inspects file structures, and automatically intercepts flags in the console stream to facilitate agentic solving workflows.

Managed using uv as the package manager and built with a modular, pure-Python architecture.

Eventually will implement MCP architecture to agentic solving. Focusing on static tooling for now. The more static tools I can add the less the agents have to do eventually, and the quicker I can solve the challenges by hand.

---

🚀 Key Features

1. Real-Time Flag Interception (Stdout Monitor)

• Automatic Flag Detection: Standard output stream interceptor scans terminal output in real-time.
• Persistent Capture: Detected flags matching the active regular expression format are instantly saved to config.toml (last_flag).

2. Custom Forensic Inspection

Pure-Python, zero-dependency parsers extract metadata without using heavy external libraries:

• POSIX Metadata: Hard link counts, ownership, permission masks, and inode data.
• Image Metadata: Scrapes TIFF/EXIF tags, Adobe XMP XML blocks, and Photoshop IPTC IIM records.
• Chunk/Comment Scrapers: Parses PNG text chunks (tEXt, zTXt, iTXt) and extracts comments from JPEG and GIF comment blocks.
• Physical Parameters: Returns image parameters (width, height, color depth, etc.) for JPEG, PNG, and GIF.

3. Recursive Decoding Engine

• Multi-layer Decoder: Integrates with chepy to identify and decode nested strings.
• Supported Formats: Hex, Base64, Base32, Binary, URL percent-encoding, ROT13, and string reversal.
• Intelligent Filtering: Prevents spam by only outputting ROT13 and Reversal transformations if they yield valid flag formats.

4. Steganography Cracker

• Steghide Wrapper: Automatically brute-forces passphrase-protected files using standard dictionary wordlists.
• Safe Execution: Runs in isolated temporary sandboxes to keep the workspace clean.

---

🛠️ CLI Reference

Context Commands

• ctf set-competition <name>: Configure active competition.
• ctf set-flag-format: Set expected flag regex format (supports original flag sample extraction).
• ctf flag: Output the last captured flag from the configuration.

Forensics Commands

• ctf forensics metadata <file>: Detailed metadata inspection.
  • -i, --inode: Output POSIX file attributes only.
  • -e, --exif: Output EXIF/XMP/IPTC data and decoded hints.
  • -p, --physical: Output physical parameters of the target media.
• ctf forensics flag-search <file>: Extract printable characters (GNU strings style) and match them against regular expressions.

Steganography Commands

• ctf steg crack-steghide <file> -w <wordlist>: Brute-force passphrase-protected files.
  • -o, --output <path>: Write the extracted payload directly to a file on success.

---

🧪 Development & Testing

This project is built following strict SDET workflows to ensure pipeline correctness:

• Sandbox Testing: Unit tests run using a dedicated sandboxed environment under tests/env.
• Testing Commands: Use uv run pytest to execute the full integration test suite.
• Dependency Management: Dependencies are locked in uv.lock and managed in pyproject.toml.