mattiapertusati/Cybernetic-CTF-Decoder

# 👾 Cybernetic Autonomous CTF Decoder An intelligent, heuristic-based multi-layered decryption and decoding tool built in Python. Designed to autonomously break complex "Matryoshka" style cryptography challenges commonly found in Capture The Flag (CTF) events. ## 📖 The Story & AI Pair Programming This tool started as a simple script to solve a specific TryHackMe room but quickly evolved into an advanced architectural challenge. It was fully developed using **AI Pair Programming** (human-guided LLM interaction). The most fascinating part of the development process was battling **AI Reward Hacking**. As the tool's heuristic scoring system became more complex, the AI occasionally attempted to "cheat" the system—for example, by generating fake Base64 strings from ROT47 artifacts just to trigger a +800 point structural bonus, or by aggressively hunting for the word `FLAG{` even if it meant outputting corrupted strings. Fixing these logic gaps required implementing strict URL decoding, adaptive scoring thresholds, and a "Matryoshka Bridge" to safely navigate between cryptography and base encodings without triggering false positives. ## ✨ Key Features * **Multi-Layered "Matryoshka" Unpacking:** Automatically detects and chains together multiple encodings (e.g., *Hex -> Base64 -> ROT47 -> Vigenère*) without human intervention. * **Heuristic Language Scoring:** Uses a dynamically loaded 10,000-word English dictionary to evaluate the plaintext viability of the decrypted output. It doesn't just guess; it mathematically assesses if a sentence makes linguistic sense. * **Dynamic Key Extraction:** Parses the ciphertext for inline keys (e.g., `(key: mysecret)`) on the fly, stores them in its arsenal, and uses them for subsequent cryptographic brute-forcing (like Vigenère). * **Anti-Hallucination Mechanisms:** Built-in safeguards (Strict Mode) against false positives, preventing the tool from chasing invalid URL encodings or mathematically coincidental but useless strings. * **Supported Bases & Ciphers:** Base16 (Hex), Base32, Base58, Base64, Ascii85, Base85, Base91, ASCII Decimal Arrays, Caesar (ROT13), ROT47, XOR Bitwise, Circular Bitwise Shifts, and Vigenère. ## ⚙️ How It Works The tool runs a maximum of 15 autonomous loops, divided into two main phases: 1. **Deterministic Decoding Phase:** Attempts to peel off standard encodings (Bases, Hex, URL). If it unlocks a new layer, it loops back. 2. **Cryptographic Brute-Force Phase:** If standard bases fail, it generates hundreds of cryptographic candidates (Shifts, XORs, Vigenère) and passes them through the **Language Scoring Engine**. The candidate with the highest linguistic score becomes the new baseline text for the next loop. The loop stops automatically ("Emergency Brake") when the language score exceeds a strict threshold (1400+ points), guaranteeing that the final output is readable human text or a CTF flag. ## 🚀 Usage ### Prerequisites The script uses standard Python libraries, but requires a few optional modules for specific base encodings. pip install base58 base91 ## Running the Decoder Simply run the script and provide the encrypted string when prompted. You can also run the built-in unit tests. # Run the decoder python3 autodecoder.py # Run unit tests to verify the core logic python3 autodecoder.py --test ## 🤝 Disclaimer This tool was created for educational purposes, CTF competitions, and to explore the limits of heuristic scoring in automated decoding.