59 lines
3.3 KiB
Markdown
59 lines
3.3 KiB
Markdown
# AI-Enhanced 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.
|
|
|
|
---
|
|
|
|
## 🚀 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](file:///home/venus/code/ctf/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 inspect <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](file:///home/venus/code/ctf/tests/env).
|
|
* **Testing Commands**: Use `uv run pytest` to execute the full integration test suite.
|
|
* **Dependency Management**: Dependencies are locked in [uv.lock](file:///home/venus/code/ctf/uv.lock) and managed in [pyproject.toml](file:///home/venus/code/ctf/pyproject.toml).
|