{"id":28515152,"url":"https://github.com/metinsaygin/blackforge","last_synced_at":"2026-04-29T10:32:24.038Z","repository":{"id":292854994,"uuid":"966896911","full_name":"MetinSAYGIN/BlackForge","owner":"MetinSAYGIN","description":" LLVM-based obfuscation with comparison","archived":false,"fork":false,"pushed_at":"2025-05-27T23:36:59.000Z","size":198,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-09T03:02:04.417Z","etag":null,"topics":["binary-analysis","binary-hardening","c-cpp","clang","code-protection","compiler","cybersecurity","llvm","llvm-pass","obfuscation","reverse-engineering","software-protection"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MetinSAYGIN.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-15T16:05:05.000Z","updated_at":"2025-06-04T20:02:47.000Z","dependencies_parsed_at":"2025-05-19T16:23:02.408Z","dependency_job_id":null,"html_url":"https://github.com/MetinSAYGIN/BlackForge","commit_stats":null,"previous_names":["metinsaygin/blackforge"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MetinSAYGIN/BlackForge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MetinSAYGIN%2FBlackForge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MetinSAYGIN%2FBlackForge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MetinSAYGIN%2FBlackForge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MetinSAYGIN%2FBlackForge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MetinSAYGIN","download_url":"https://codeload.github.com/MetinSAYGIN/BlackForge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MetinSAYGIN%2FBlackForge/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263718242,"owners_count":23500796,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binary-analysis","binary-hardening","c-cpp","clang","code-protection","compiler","cybersecurity","llvm","llvm-pass","obfuscation","reverse-engineering","software-protection"],"created_at":"2025-06-09T03:00:27.832Z","updated_at":"2026-04-29T10:32:23.652Z","avatar_url":"https://github.com/MetinSAYGIN.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"![License](https://img.shields.io/badge/license-MIT-blue.svg)\n![Language](https://img.shields.io/badge/language-Python-green.svg)\n![LLVM](https://img.shields.io/badge/LLVM-compatible-orange.svg)\n\nBlackForge is an advanced binary obfuscation framework that leverages LLVM passes to transform and protect your C/C++ source code. It provides comprehensive metrics and analysis to measure the effectiveness of various obfuscation techniques.\n\n## 🛡️ Features\n\n- **Custom LLVM Pass Integration**: Compile and apply your own LLVM obfuscation passes\n- **Project \u0026 File Support**: Works with both individual source files and complete projects with Makefiles\n- **Detailed Analysis**: Measures and compares key metrics between original and obfuscated binaries:\n  - Binary size changes\n  - Execution time impact\n  - CPU utilization\n  - Shannon entropy (obfuscation effectiveness)\n- **Comprehensive Logging**: Detailed logs for debugging and analysis\n- **Interactive Interface**: Simple CLI interface for selecting targets and passes\n\n## 📋 Requirements\n\n- Python 3.6+\n- LLVM toolchain (clang, opt)\n- psutil Python library\n- C/C++ compiler toolchain\n- make (for project mode)\n\n## 🚀 Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/MetinSAYGIN/BlackForge.git\ncd BlackForge\n```\n\n2. Install Python dependencies:\n```bash\npip install psutil\n```\n\n3. Ensure LLVM toolchain is installed (LLVM 19, Clang 19, Opt 19 ..):\n```bash\n# For Debian/Ubuntu\nsudo apt-get install llvm clang\n# For Fedora\nsudo dnf install llvm clang\n# For macOS\nbrew install llvm\n```\n\n## 📁 Project Structure\n\n```\nBlackForge/\n├── BlackForge.py       # Main script\n├── passes/             # LLVM obfuscation passes\n│   ├── pass1.cpp\n│   ├── pass2.cpp\n│   └── ...\n├── sources/            # Source code to be obfuscated\n│   ├── clair/          # Original source files\n│   │   ├── project1/\n│   │   ├── project2/\n│   │   └── project3/\n│   └── obfusque/       # Output obfuscated files\n│   │   ├── project1/\n│   │   ├── project2/\n│   │   └── project3/\n├── build/              # Compiled passes (.so files)\n└── logs/               # Logs directory\n```\n\n## 🔧 Usage\n\nRun the main script:\n\n```bash\npython BlackForge.py\n```\n\nFollow the interactive prompts to:\n1. Choose a target (project or file)\n2. Select an obfuscation pass\n3. Wait for the obfuscation and analysis to complete\n\n### For Individual Files\n\nIndividual C/C++ files can be placed directly in the `sources/clair/` directory.\nIt will not use any custom makefile, I recommend you to use \"Projects\".\n\n### For Projects\n\nProjects should be organized as directories inside `sources/clair/` with a Makefile that supports:\n- Regular compilation\n- `make clean`\n- Generation of `.ll` files\n\nThe script will automatically add an `obfuscate` target to your Makefile if needed.\n\nThen compare both binaries with \n\n```bash\npython Compare.py\n```\n## 📊 Example Output\n```bash\n[+] Comparaison entre:\n- Clair    : sources/clair/hello_world\n- Obfusqué : sources/obfusque/hello_world/hello_world\n\n[+] Benchmark du binaire clair...\n[+] Benchmark du binaire obfusqué...\n\n=== RÉSULTATS ===\n\u003e\u003e Taille du binaire final (fichier compilé)\nClair    : 69.00 Ko\nObfusqué : 69.00 Ko (+0.00%)\n\n\u003e\u003e Taille des segments ELF (mémoire utile)\ntext   : 2183 → 2408 (+225 | +10.31%)\ndata   : 632 → 632 (+0 | +0.00%)\nbss    : 8 → 8 (+0 | +0.00%)\ndec    : 2823 → 3048 (+225 | +7.97%)\nhex    : 0 → 0 (+0 | +0.00%)\nfilename : 0 → 0 (+0 | +0.00%)\n\n\u003e\u003e Entropie du binaire (aléa du contenu)\nClair    : 0.5456\nObfusqué : 0.5818 (+0.0361)\n\n\u003e\u003e Temps d'exécution moyen (5 runs)\nClair    : 0.0045s (±0.0001)\nObfusqué : 0.0044s (±0.0001)\nDifférence : -0.0001s (-1.63%)\n```\n\n## 📝 Creating Custom Obfuscation Passes\n\n1. Create a new C++ file in the `passes/` directory\n2. Implement your pass using the LLVM Pass infrastructure\n3. Run BlackForge and select your pass\n\nExample of a simple pass structure:\n\n```cpp\n#include \"llvm/IR/PassManager.h\"\n#include \"llvm/Passes/PassBuilder.h\"\n#include \"llvm/Passes/PassPlugin.h\"\n\nusing namespace llvm;\n\nnamespace {\n  struct MyObfuscationPass : public PassInfoMixin\u003cMyObfuscationPass\u003e {\n    PreservedAnalyses run(Function \u0026F, FunctionAnalysisManager \u0026FAM) {\n      // Implement your obfuscation logic here\n      return PreservedAnalyses::none();\n    }\n  };\n}\n\nextern \"C\" LLVM_ATTRIBUTE_WEAK ::llvm::PassPluginLibraryInfo\nllvmGetPassPluginInfo() {\n  return {\n    LLVM_PLUGIN_API_VERSION, \"MyObfuscationPass\", \"v0.1\",\n    [](PassBuilder \u0026PB) {\n      PB.registerPipelineParsingCallback(\n        [](StringRef Name, FunctionPassManager \u0026FPM,\n           ArrayRef\u003cPassBuilder::PipelineElement\u003e) {\n          if (Name == \"my-obfuscation-pass\") {\n            FPM.addPass(MyObfuscationPass());\n            return true;\n          }\n          return false;\n        });\n    }\n  };\n}\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📜 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## 🙏 Acknowledgments\n\n- LLVM Project for their amazing compiler infrastructure\n- All contributors who have helped shape this project\n\n## 🔍 Use Cases\n\n### Software Protection for Commercial Applications\n\nBlackForge can be used to protect proprietary algorithms and intellectual property in commercial software:\n\n```bash\n# Obfuscate a key algorithm before shipping\n$ python BlackForge.py \n[?] Sélectionnez un projet ou fichier source:\n  0) [FICHIER] license_check.c\n→ Choix (numéro): 0\n\n[?] Sélectionnez une passe d'obfuscation:\n  0) control_flow_flattening\n  1) string_encryption\n→ Choix (numéro): 1\n\n[+] Compilation de la passe string_encryption...\n...\n=== 📊 RÉSULTATS DE L'ANALYSE ===\n+----------------+----------------+----------------+\n| Métrique       | Binaire clair  | Binaire obfusqué |\n+----------------+----------------+----------------+\n| Taille (Ko)    |          8.25  |          10.45  |\n| Temps (s)      |       0.0015   |        0.0018   |\n| Entropie       |       5.4532   |        6.2143   |\n+----------------+----------------+----------------+\n```\n\n### Academic Research on Obfuscation Techniques\n\nResearchers can use BlackForge to measure the effectiveness of different obfuscation techniques:\n\n```bash\n# Run multiple passes on the same file and compare results\n$ python BlackForge.py  # Run with first pass\n...\n$ python BlackForge.py  # Run with second pass\n...\n$ python BlackForge.py  # Run with combined passes\n...\n\n# Compare the logs and metrics to evaluate effectiveness vs. performance impact\n```\n\n## 📝 To Do\n\n* Improved integration with complex projects (with multiple source files)\n* Implement a lightweight web interface for a more user-friendly experience\n* Add batch processing mode for evaluating multiple passes at once\n* Support for more diverse metrics and analysis tools\n* Add pre-built common obfuscation passes library\n\n\n\n## 👨‍💻 Author\n\n**Metin SAYGIN**  \n*Developed with AI assistance for code optimization and documentation*\n---\n*BlackForge - Advanced Binary Obfuscation Framework*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetinsaygin%2Fblackforge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetinsaygin%2Fblackforge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetinsaygin%2Fblackforge/lists"}