adding more features inclided steg analysis, decoding engines, and more

tests

README.md

@@ -1,38 +1,58 @@
-# CTF toolchain for linux
-This project is meant to be an ai-enhancing ctf toolchain to track your work and help you faster
-The system keeps track of your file history, current ctf, challenge catagory, etc to make it easy to provide AI with the context to give you the right answer
-The focus is on building a solid methodology to solve any problem.
+# 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.
 
-# Dev flow
-## initialize a competition
-Take user input (eventually screenshots) and generate a new competition directory with directories for each catagory
-## Initialize a challenge
-Make a new challenge directory and cd into it
-Review recently downloaded files, and add challenge files
-## Progress tracker
-Generate an active log file from command history
-Accept user prompts to inform history
-- finished (challenge finished)
-- begin route (start a new path of exploration)
-- help (prompts AI with challenge and progress to give reliable and relevant help)
-- success (current path succeeded with previously run command)
-- context (add context at this point in the log)
-## Built in scripts and libraries
-- built in rapid forensics testing and flag analysis based on context
-## Write up aid
-Shows all of your quickly commented notes
-Creates prompt for AI to generate a write up showing your process
-- feedback (generates feedback on your work flow and suggests improvements)
+Managed using `uv` as the package manager and built with a modular, pure-Python architecture.
 
-# Misc
-the end goal is to create a methodology solid enough to build out a full AI tool chain around it while allowing tight human integration
+---
 
+## 🚀 Key Features
 
-## features
-- Cyberchef like decoding and magic feature
-- regexing input text for flag
-    - flag selection and filtering with remembered prev. flags
-# Tools
-- forensics
-    - forensics tool for basic file analysis
+### 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).