abgoosht is a comprehensive MiniC code obfuscation and deobfuscation framework with both classical and AI agent-based transformation capabilities.
- 💾 Input: MiniC/C-like source code
- 📤 Output: Hardened or clarified source code, depending on module
- 🧩 Modes: CLI, Gradio Web UI, Python API
- 🛡️ Purpose: Security research, pedagogy, code analysis, AI-driven transformation experiments
- Obfuscator: Makes code harder to read/analyze
- Deobfuscator: Attempts to restore readability of obfuscated code
- AI Agent-based Modules: Obfuscation and deobfuscation using ML/AI models or rules, for advanced, adaptive transformations
The Abgoosht system is designed as a modular pipeline that processes MiniC code through multiple transformation stages. At its core, it integrates a custom parsing and transformation engine written in C++, which handles lexical analysis, parsing, abstract syntax tree generation, and code regeneration. Surrounding this core is an orchestration layer that connects user interfaces, AI agents, and benchmarking tools. The system supports both obfuscation and deobfuscation flows, allowing the same architecture to operate in reverse depending on the selected mode.
User input enters the system through interfaces such as a web UI or CLI, after which it is routed into the transformation pipeline. The pipeline begins with lexical analysis and parsing to construct an intermediate representation of the code. This representation is then passed through various transformation modules, including classical obfuscation techniques and AI-driven transformations. Once processing is complete, the code is regenerated and optionally evaluated using a benchmarking container that measures correctness, performance, and structural changes. Feedback from AI agents can also be looped back into the system to iteratively refine transformations.
A key aspect of Abgoosht’s design is its integration of AI agents that enhance both obfuscation and deobfuscation processes. These agents can analyze code structure, suggest transformations, and adapt strategies dynamically based on context. The system is built to be extensible, allowing developers to add new transformation techniques, plug in different AI models, or customize parsing rules. This flexibility makes Abgoosht suitable for research, experimentation, and real-world applications where evolving code transformation strategies are required.
- Features
- Project Structure & Modules
- Quick Start
- Obfuscator Module
- Deobfuscator Module
- AI Agent-based Transformations
- Extending the System
- Examples
- Usage Scenarios
- Troubleshooting & FAQ
- Roadmap
- Contributing
- Acknowledgments
- Disclaimer & Security Notes
- License
- Multi-transform Obfuscator: 20+ techniques (renaming, dead code, block reordering, etc)
- Deobfuscator: Rule-based and experimental AI methods for code recovery
- Gradio Web UI: Visual, point-and-click interface for uploading source & tweaking parameters
- CLI Tool: Batch and automated workflows
- Dockerized: Cross-platform and reproducible environments
- Modular Architecture: Add/remove techniques easily
- Benchmark Tools: Evaluate quality, speed, resiliency of transformations
- AI Integration: Optional transformer/LLM-based smart obfuscation and deobfuscation (see AI Agent-based Transformations)
abgoosht/
├── main.py # CLI tool for obfuscation
├── gradio_app.py # Gradio-based web app UI
├── requirements.txt # Python dependencies
├── Dockerfile # Container build script
├── benchmark_runner.py # Benchmark automation
│
├── obfuscator/ # All classical and AI-based obfuscators
│ ├── parser.py
│ ├── transformer.py
│ ├── generators.py
│ ├── techniques/ # Individual technique classes per file
│ └── ...
│
├── deobfuscator/ # Rule-based & AI agent-based deobfuscation
│ ├── parser.py
│ ├── transformer.py
│ ├── generators.py
│ ├── techniques/ # Individual technique classes per file
│ └── ...
│
├── abgoosht_parser/ # Custom parser for the MiniC grammar
├── examples/ # Example MiniC files (original, obfuscated, restored)
└── ...- Python 3.11+
- (Optional) Docker
git clone https://github.com/dwin-gharibi/abgoosht.git
cd abgooshtpython -m venv venv
source venv/bin/activate
pip install -r requirements.txtpython main.py -i input.mc -o output.mcpython gradio_app.pyThen open the provided URL in your browser.
docker build -t abgoosht .
docker run -p 80:80 abgooshtObfuscator applies layered code transformations to maximize difficulty of static analysis.
Click for full list
- VariableRenamer: Randomizes variable names
- DeadCodeInserter: Adds non-executing code for confusion
- MisleadingComments: Adds misleading/irrelevant comments
- IrrelevantLogging: Introduces non-informative logs
- FunctionSplitter/InlineFunctions: Code splitting/inline expansion
- ExprComplexifier: Turns simple expressions into complicated ones
- AliasGenerator: Introduces variable aliases and shims
- ConstantFolding/MacroHell: Constant transformations and macro use
- ReorderBlocks: Alters block sequence
- DummyControl: Inserts fake branches/loops
- TypeMisleading/StructObfuscator: Obscures type information
- ControlFlattener: Makes control flow harder to follow
- JunkInserter: Injects extraneous (but safe) code
- OpaquePredicate/FakeRecursion: Use misleading conditions and call patterns
- LoopUnroller, FunctionSplitter
- Custom: Easily add your technique in
obfuscator/techniques/
Attempts to restore original code structure and readability. Useful for:
- Security analysis / forensics
- Educational demos on reverse engineering
- Evaluating effectiveness of obfuscation
- Rule-based: Pattern matches obfuscated constructs and attempts to revert them.
- Refactoring: Removes/restructures dummy/opaque/junk blocks.
- Comment Cleaning: Strips or paraphrases misleading comments.
- AI Agent: Uses LLMs or transformer models to "translate" obfuscated code back to idiomatic MiniC.
State: Experimental; results may vary depending on model quality.
An AI agent in abgoosht refers to a (possibly LLM-based) Python component that analyzes code with the intent to contextually choose/adapt obfuscation or deobfuscation transforms:
- Can use pre-trained or fine-tuned Language Models (like GPT, Llama, etc)
- Makes transformation decisions based on code semantics, not just syntax patterns
- May generate novel obfuscations or infer human-intended structure
- Obfuscation: The agent identifies kernels of logic and chooses a dynamic blend of transformations, or generates constructs beyond fixed hand-coded rules.
- Deobfuscation: The agent attempts to recover human-readable logic, possibly combining multiple steps (renaming, restructuring, paraphrasing).
Current status:
The AI modules require integration with external APIs or additional model checkpoints.
- Add new obfuscators: Just drop a file/class in
obfuscator/techniques/and register inmain.py. - Add new deobfuscators: Similar pattern in
deobfuscator/.
python main.py -i clean_example.mc -o garbled_example.mcpython deobfuscator/main.py -i garbled_example.mc -o restored_example.mc- Researchers: Modeling and measuring the resilience of various obfuscation strategies.
- Students & Instructors: Demonstrate compiler/transformation concepts.
- Security Analysts: Evaluate or test code hardening techniques.
- AI Developers: Experiment with language models for code transformation.
| Path | Purpose |
|---|---|
| main.py | CLI tool for obfuscator |
| gradio_app.py | Launches Gradio UI |
| benchmark_runner.py | Benchmarking, experimentation scripts |
| requirements.txt | Python dependencies |
| Dockerfile | Reproducible container build |
| obfuscator/ | Classical and AI-based obfuscator code |
| obfuscator/techniques/ | Each file = one obfuscation strategy |
| deobfuscator/ | Classical and AI-based deobfuscators |
| abgoosht_parser/ | MiniC/C parser implementation |
| examples/ | MiniC code for examples/tests |
- Flexible, modular, and extensible for many workflows
- Unifies classical & ML-based approaches
- Educational: clear code structure, many comments, easy to follow
- Ready-to-use with Docker and UI
- AI modules require additional setup (API keys, local models)
- The project is specialized for MiniC, not C/C++
- Not designed for commercial obfuscation-grade protection
- AI agent: pre-configured inference with open-source LLMs
- Add more transformation patterns (structural, semantic)
- Expand deobfuscator’s reasoning
- CI/CD and auto-badges
- More examples/tutorials
- Public API endpoints
- Check your input conforms to MiniC standards.
- Make sure all dependencies are installed.
- Performance may vary. Obfuscation is designed for small-medium MiniC/C-like programs.
- No tool guarantees “perfect” deobfuscation, especially after heavy/AI transformations — treat as a best effort.
- Fork, branch, PR!
- Try to keep style consistent and document new obfuscation techniques.
- AI/ML contributions especially welcome.
- Python & Gradio team
- OpenAI, Meta, HuggingFace LLM contributors (for AI modules)
- Early testers & reviewers
- abgoosht is for RESEARCH AND EDUCATIONAL PURPOSES only.
- It is not meant for production grade software protection.
- Authors are not responsible for misuse or legal issues arising from generated code.