--- slug: "emberscale-enhanced" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/KevinMitchell-OSWP-CISSP/EmberScale-Enhanced@main/README.md" repo: "https://github.com/KevinMitchell-OSWP-CISSP/EmberScale-Enhanced" source_file: "README.md" branch: "main" --- # EmberScale - Advanced AI-Powered Reverse Engineering Tool
EmberScale AI Logo
[![GitHub](https://img.shields.io/badge/GitHub-EmberScale--Enhanced-blue?style=flat-square&logo=github)](https://github.com/KevinMitchell-OSWP-CISSP/EmberScale-Enhanced) [![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE) [![Python](https://img.shields.io/badge/Python-3.8+-blue?style=flat-square&logo=python)](https://python.org) [![Ghidra](https://img.shields.io/badge/Ghidra-11.4.2+-orange?style=flat-square)](https://ghidra-sre.org) [![Anthropic](https://img.shields.io/badge/Anthropic-Claude-purple?style=flat-square)](https://anthropic.com) [![Version](https://img.shields.io/badge/Version-2.0.0-blue?style=flat-square)](CHANGELOG.md) ## Overview EmberScale is a comprehensive reverse engineering tool that integrates advanced AI capabilities with Ghidra for enhanced binary analysis, vulnerability assessment, and security research. The tool leverages Anthropic's Claude AI models and the latest Agent Skills API to provide specialized analysis workflows, automated document generation, and intelligent reverse engineering assistance. **Built on the Foundation of [Decyx](https://github.com/philsajdak/decyx)**: EmberScale is an enhanced and expanded version of the original Decyx project by [philsajdak](https://github.com/philsajdak). We extend our deepest gratitude to the original Decyx team for creating the foundational AI-powered Ghidra extension that inspired this project. The core concepts, API integration patterns, and user experience principles from Decyx have been instrumental in developing EmberScale's advanced capabilities. **Repository**: [https://github.com/KevinMitchell-OSWP-CISSP/EmberScale-Enhanced](https://github.com/KevinMitchell-OSWP-CISSP/EmberScale-Enhanced) ## Key Features ### Core Capabilities (Production-Ready) - **AI-Powered Analysis**: Advanced binary analysis using Claude AI models - **Advanced Analysis**: Specialized reverse engineering workflows with comprehensive analysis - **Enhanced Ghidra Integration**: Deep integration with Ghidra's scripting API - **Usage Monitoring**: Comprehensive cost tracking and usage analytics - **Token Tracking**: Built-in usage tracking across all tools - **Error Handling**: Robust error handling and logging system ### Analysis Types - **Malware Analysis**: Advanced malware detection and analysis - **Firmware Analysis**: Comprehensive firmware security assessment - **Vulnerability Assessment**: Automated vulnerability detection and risk assessment - **Function Analysis**: Intelligent function analysis and classification - **String Analysis**: Advanced string pattern recognition and analysis - **Cross-Reference Analysis**: Comprehensive cross-reference analysis ### Document Generation - **Technical Reports**: Detailed analysis reports (Word/PDF) - **Analysis Spreadsheets**: Structured data analysis (Excel) - **Executive Presentations**: High-level summaries (PowerPoint) - **Specialized Reports**: IOC reports, vulnerability assessments, remediation guides ## Project Structure ``` EmberScale-Enhanced/ ├── EmberScale_Ghidra.py # Main Ghidra integration script ├── EmberScale_QA_Lite.py # Quick analysis tool ├── EmberScale-RE_Toolbox.py # Comprehensive analysis toolbox ├── EmberScale_Enhanced.py # Enhanced version (production-ready) ├── EmberScale_Usage_Monitor.py # Usage monitoring dashboard ├── EmberScale_Single_Decompile.py # Single function decompilation ├── decyx/ # Core API modules │ ├── api.py # Anthropic API integration │ ├── config.py # Configuration management │ ├── logger.py # Enhanced logging system │ ├── decompiler.py # Decompilation utilities │ ├── gui.py # GUI components │ └── utils.py # Utility functions ├── examples/ # Usage examples and tutorials │ ├── quick_start.py # Quick start guide │ └── custom_re_skill/ # Custom skill examples ├── assets/ # Media and documentation ├── INSTALLATION.md # Detailed installation guide ├── CHANGELOG.md # Version history ├── CONTRIBUTING.md # Contribution guidelines ├── LICENSE # MIT License ├── requirements.txt # Python dependencies └── README.md # This file └── ENHANCEMENT_SUMMARY.md # Enhancement summary ``` ## Production-Ready Improvements (v2.0.0) ### Enhanced Stability - **Removed Incomplete Features**: All stub functions and placeholder code removed - **Production-Ready Code**: Only fully implemented features included - **Robust Error Handling**: Comprehensive error handling across all tools - **Jython Compatibility**: Full compatibility with Ghidra's Jython environment ### Code Quality Improvements - **Enhanced Logging**: Structured logging system with multiple levels - **Token Tracking**: Built-in usage tracking for all EmberScale tools - **Configuration Management**: Environment variables and flexible settings - **Character Encoding**: Fixed all emoji and special character rendering issues ### Documentation & Examples - **Comprehensive Documentation**: Installation, usage, and contribution guides - **Quick Start Examples**: Interactive tutorials and examples - **Professional Structure**: Complete project structure with all necessary files - **Version History**: Detailed changelog and version tracking ## Installation & Setup ### Prerequisites 1. **Ghidra**: Version 11.4.2 or later 2. **Python**: Python 3.8+ (for Jython compatibility) 3. **Anthropic API Key**: Required for AI analysis capabilities 4. **Internet Connection**: Required for API calls ### Installation Steps 1. **Download EmberScale** ```bash git clone https://github.com/KevinMitchell-OSWP-CISSP/EmberScale-Enhanced.git cd EmberScale-Enhanced ``` 2. **Configure Ghidra** - Copy the `decyx` folder to your Ghidra scripts directory - Copy the main EmberScale scripts to your Ghidra scripts directory - Ensure Jython is properly configured in Ghidra 3. **Configure API Keys** - Run any EmberScale script in Ghidra - Enter your Anthropic API key when prompted - The key will be saved in Ghidra Preferences for future use 4. **Verify Installation** - Open Ghidra and load a binary - Run `EmberScale_Ghidra.py` from the Script Manager - Verify the API key is configured correctly ## Quick Start ### Basic Analysis 1. **Load a Binary**: Open your target binary in Ghidra 2. **Run Analysis**: Execute `EmberScale_Ghidra.py` from the Script Manager 3. **Select Analysis Type**: Choose from available analysis options 4. **Review Results**: Examine the AI-generated analysis results ### Advanced Analysis with Agent Skills 1. **Run Enhanced Script**: Execute `EmberScale_Agent_Skills.py` 2. **Select Specialized Analysis**: Choose from malware, firmware, or vulnerability analysis 3. **Generate Documents**: Let the AI generate comprehensive reports 4. **Review Outputs**: Examine generated Word documents, Excel spreadsheets, and PowerPoint presentations ### Usage Monitoring 1. **Run Usage Monitor**: Execute `EmberScale_Usage_Monitor.py` 2. **View Analytics**: Check usage statistics, costs, and trends 3. **Manage API Keys**: Configure and monitor API key usage 4. **Export Reports**: Generate usage reports for analysis ## Usage Examples ### Malware Analysis ```python # Advanced malware analysis with Agent Skills def perform_malware_analysis(): # Collect malware indicators indicators = collect_malware_indicators() # Create analysis prompt prompt = create_malware_analysis_prompt(indicators) # Use specialized Skills skills = [ {"type": "anthropic", "skill_id": "docx", "version": "latest"}, {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}, {"type": "anthropic", "skill_id": "pptx", "version": "latest"} ] # Perform analysis response = call_claude_with_skills(prompt, skills) ``` ### Firmware Analysis ```python # Comprehensive firmware analysis def perform_firmware_analysis(): # Collect firmware data firmware_data = collect_firmware_indicators() # Create analysis prompt prompt = create_firmware_analysis_prompt(firmware_data) # Use specialized Skills skills = [ {"type": "anthropic", "skill_id": "docx", "version": "latest"}, {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}, {"type": "anthropic", "skill_id": "pdf", "version": "latest"} ] # Perform analysis response = call_claude_with_skills(prompt, skills) ``` ### Vulnerability Assessment ```python # Comprehensive vulnerability assessment def perform_vulnerability_assessment(): # Collect vulnerability data vuln_data = collect_vulnerability_indicators() # Create assessment prompt prompt = create_vulnerability_assessment_prompt(vuln_data) # Use specialized Skills skills = [ {"type": "anthropic", "skill_id": "docx", "version": "latest"}, {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}, {"type": "anthropic", "skill_id": "pptx", "version": "latest"} ] # Perform assessment response = call_claude_with_skills(prompt, skills) ``` ## Configuration ### API Key Management - **Automatic Storage**: API keys are automatically stored in Ghidra Preferences - **Secure Storage**: Keys are encrypted and stored securely - **Multiple Keys**: Support for regular and admin API keys - **Key Validation**: Automatic validation of API key format and permissions ### Analysis Settings - **Model Selection**: Choose between Claude Sonnet and other available models - **Analysis Depth**: Configure analysis depth and detail level - **Output Format**: Select desired output formats and document types - **Custom Skills**: Configure custom reverse engineering Skills ### Usage Monitoring - **Cost Tracking**: Monitor API usage costs and trends - **Usage Analytics**: Track token usage, model usage, and operation types - **Budget Alerts**: Set up cost alerts and usage limits - **Report Generation**: Generate detailed usage reports ## Advanced Features ### Agent Skills Integration - **Pre-built Skills**: Access to Anthropic's pre-built Skills (Excel, PowerPoint, Word, PDF) - **Custom Skills**: Create and integrate custom reverse engineering Skills - **Multi-Skill Workflows**: Combine multiple Skills for comprehensive analysis - **Document Generation**: Automated generation of technical reports and presentations ### Enhanced UI Integration - **Smart Selections**: Intelligent selection management with visual feedback - **Advanced Navigation**: Enhanced program navigation and analysis - **Interactive Tables**: Specialized table displays for analysis results - **Status Integration**: Real-time status updates and progress tracking ### Usage Analytics - **Cost Analysis**: Detailed cost breakdown and trend analysis - **Usage Patterns**: Analysis of usage patterns and optimization opportunities - **Performance Metrics**: Track analysis performance and efficiency - **Custom Reports**: Generate custom usage and cost reports ## Security & Privacy ### Data Protection - **Local Processing**: Analysis data remains on your local system - **Secure API Calls**: All API calls use HTTPS encryption - **Key Security**: API keys are stored securely in Ghidra Preferences - **No Data Retention**: No analysis data is retained by external services ### Access Control - **API Key Management**: Secure API key storage and management - **Usage Limits**: Configurable usage limits and cost controls - **Audit Logging**: Comprehensive logging of all analysis activities - **Permission Management**: Fine-grained control over analysis capabilities ## Documentation ### Core Documentation - **README.md**: This comprehensive overview - **USAGE_MONITORING_README.md**: Detailed usage monitoring guide - **AGENT_SKILLS_README.md**: Agent Skills integration documentation - **ENHANCEMENT_SUMMARY.md**: Complete enhancement summary ### Example Implementations - **agent_skills_example.py**: Complete examples of Agent Skills usage - **custom_re_skill/**: Example custom reverse engineering Skill - **Usage Examples**: Comprehensive usage examples and tutorials ### API Reference - **Anthropic API**: Integration with Anthropic's Claude API - **Ghidra API**: Deep integration with Ghidra's scripting API - **Agent Skills API**: Integration with Anthropic's Agent Skills API ## Contributing ### Development Setup 1. **Fork the Repository**: Create your own fork of the project 2. **Create Branch**: Create a feature branch for your changes 3. **Make Changes**: Implement your improvements or fixes 4. **Test Changes**: Ensure all changes work correctly 5. **Submit PR**: Submit a pull request with your changes ### Contribution Guidelines - **Code Quality**: Follow Python best practices and coding standards - **Documentation**: Update documentation for any new features - **Testing**: Ensure all changes are thoroughly tested - **Compatibility**: Maintain compatibility with existing functionality ### Areas for Contribution - **Custom Skills**: Develop new reverse engineering Skills - **Analysis Algorithms**: Improve analysis accuracy and performance - **UI Enhancements**: Improve user interface and experience - **Documentation**: Improve documentation and examples - **Testing**: Add comprehensive test coverage ## 📄 License This project is licensed under the MIT License. See the LICENSE file for details. ## Acknowledgments - **[Decyx Project](https://github.com/philsajdak/decyx)**: The original AI-powered Ghidra extension by [philsajdak](https://github.com/philsajdak) that served as the foundation for EmberScale. Their innovative work in integrating Claude AI with Ghidra's API provided the core architecture and inspiration for this enhanced version. - **Ghidra Team**: For the excellent reverse engineering framework - **Anthropic**: For the powerful Claude AI models and Agent Skills API - **Community**: For feedback, contributions, and support ## Support ### Getting Help - **Documentation**: Check the comprehensive documentation - **Examples**: Review the example implementations - **Community**: Join the community discussions - **Issues**: Report issues and bugs ### Contact Information - **GitHub Issues**: Report bugs and request features - **Community Forum**: Join community discussions - **Email Support**: Contact the development team - **Documentation**: Check the comprehensive documentation --- **EmberScale - Advanced AI-Powered Reverse Engineering Tool** *Leveraging the power of AI to enhance reverse engineering workflows and security research.* **Repository**: [https://github.com/KevinMitchell-OSWP-CISSP/EmberScale-Enhanced](https://github.com/KevinMitchell-OSWP-CISSP/EmberScale-Enhanced)