Frida Script Runner

Frida Script Runner v1.0.0 is a powerful web-based toolkit designed for Android and iOS penetration testing and mobile application security analysis.

This tool simplifies the process of interacting with Frida, providing a user-friendly interface through Flask to enhance the efficiency of penetration testing tasks. It features AI-powered script generation through Codex CLI integration with MCP (Model Context Protocol) servers for advanced binary analysis.

A comprehensive toolkit for analyzing, manipulating, and interacting with mobile applications (Android & iOS), APK/IPA dumping, and automated script generation.

Features

Core Functionality

• Run Frida Scripts: Execute custom Frida scripts on selected mobile applications to analyze and manipulate their behavior.
• Real-time Output: View real-time output generated by the Frida process, allowing instant feedback on script execution.
• Script Organization: Organize Frida scripts into different directories for efficient management and easy selection.
• Custom Scripting: Easily create and run custom Frida scripts by copy-pasting the script code directly into the tool.

AI-Powered Script Generation 🤖

• Codex CLI Integration: Generate Frida scripts using the Codex CLI with advanced prompt engineering.
• MCP Server Support: Access Ghidra and JADX MCP servers for real-time binary analysis and reverse engineering.
• Frida API Compatibility: AI-generated scripts use only compatible functions from the official Frida JavaScript API.
• ARM Android Optimization: Scripts are specifically optimized for ARM Android devices with proper stability patterns.
• Interactive Script Tester: Test and refine your prompts with the built-in Codex Bridge web interface.

Application Management

• Dump APK/IPA From Device: Extract APK (Android) or IPA (iOS) files from connected devices by selecting installed packages.
• Searchable Package List: Quickly find target applications via live search functionality in the package selector.
• Custom Filename Option: Define a custom name for the dumped APK/IPA instead of using the default package name.
• Install APK to Device: Upload and install an APK file directly onto an Android device with a single click.

User Experience

• Modern UI Design: Clean and visually appealing user interface for better user experience.
• Docker Support: Full containerization support with host bridge for Codex CLI access.
• Cross-Platform: Works on Windows, Linux, and macOS with proper dependency management.

Feature Details

How to Use for Android & Custom Script

How to Use for iOS

Prerequisites

Required Software

• Python 3.11.x (required)
• Flask (web framework)
• Frida (instrumentation toolkit)
• ADB (for Android - installation guide)
• ideviceinfo (for iOS - installation guide)

AI Features (Optional)

• Codex CLI (for AI-powered script generation - setup guide)
• Ghidra MCP Server (for binary analysis integration)
• JADX MCP Server (for Android APK analysis)

Device Requirements

• Android: Root access required for Frida server installation
• iOS: Jailbroken device with Frida installed via Cydia/Sileo/Zebra

Installation

Method 1: Native Installation

1. Clone the repository:

   git clone https://github.com/z3n70/Frida-Script-Runner.git
   cd Frida-Script-Runner

2. Install Dependencies:

   pip3 install -r requirements.txt

3. Run The Application:

   python3.11 frida_script.py

4. Access the Web Interface:

   http://127.0.0.1:5000

Method 2: Docker Installation

1. Build and run with Docker Compose:

   docker-compose up --build

2. Start Codex Bridge (for AI features):

   # On host machine (Windows/Linux/macOS)
   python codex-bridge.py

3. Access the Applications:

   • Frida Script Runner: http://localhost:5000
   • Codex Bridge Tester: http://localhost:8091

AI Setup (Optional)

If you want to use AI-powered script generation:

1. Install Codex CLI:

   • Follow the Codex CLI setup guide
   • Authenticate with your OpenAI account and ensure the codex command is available

2. Configure MCP Servers (MUST):

   • Set up Ghidra MCP server for binary analysis
   • Configure JADX MCP server for APK analysis
   • Update paths in codex-bridge.py if needed
   • Copy .config.toml.example to .config.toml and adjust MCP server paths for your setup

Usage

Basic Usage

1. Device Setup:

   • Connect your USB device and run Frida Server (root/jailbreak required)
   • For iPhone: Ensure Frida is installed via Cydia, Sileo, Zebra, or another package manager

2. Run Scripts:

   • Open the web interface and select the target package and script
   • Click "Run Frida" to start the Frida process
   • View real-time output in the output container

3. Script Management:

   • Android scripts: Place in Script Directory 1
   • iOS scripts: Place in Script Directory 2
   • See script.json for structure and naming conventions

AI-Powered Script Generation

1. Using the Web Interface:

   • Navigate to the "AI Generate" tab
   • Enter your request (e.g., "Hook the login function and log parameters")
   • Click "Generate Script" to create a custom Frida script

2. Using the Codex Bridge Tester:

   • Access http://localhost:8091 (when bridge is running)
   • Test different prompts and refine your requests
   • Generated scripts are optimized for ARM Android devices

3. Example Prompts:

   • "Intercept SSL pinning bypass for Android app"
   • "Hook Java method com.example.App.authenticate and modify return value"
   • "Monitor file operations and log file paths"
   • "Hook the main function and log all parameters"

Advanced Features

• Binary Analysis: AI can access Ghidra/JADX data for accurate function names and addresses
• Auto-Fix: Scripts automatically include ARM stability patterns and error handling
• Real-time Analysis: MCP servers provide live binary analysis during script generation

Architecture

┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│   Web Interface     │    │  Codex Bridge      │    │   MCP Servers       │
│   (Flask App)       │◄───┤  (AI Integration)   │◄───┤  (Binary Analysis)  │
│                     │    │                     │    │                     │
│ • Script Runner     │    │ • Codex CLI Proxy  │    │ • Ghidra Server     │
│ • Package Manager   │    │ • Prompt Engineering│    │ • JADX Server       │
│ • Real-time Output  │    │ • MCP Client        │    │ • Function Analysis │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘
           │
           ▼
┌─────────────────────┐    ┌─────────────────────┐
│   Frida Runtime     │    │   Mobile Device     │
│                     │◄───┤                     │
│ • Script Execution  │    │ • Android (rooted)  │
│ • Instrumentation   │    │ • iOS (jailbroken)  │
│ • Memory Analysis   │    │ • Running Apps      │
└─────────────────────┘    └─────────────────────┘

Troubleshooting

Common Issues

Empty AI Response:

• Ensure Codex CLI is properly installed and authenticated
• Check that the bridge is using the correct command format (--file and --prompt)
• Verify timeout settings (5 minutes default)

Frida Server Connection Failed:

• Verify device is rooted/jailbroken
• Ensure Frida server is running with proper permissions
• Check ADB/USB debugging connection

MCP Server Issues:

• Update MCP server paths in codex-bridge.py
• Ensure Ghidra/JADX servers are running and accessible
• Check network connectivity and firewall settings

Docker Issues:

• Ensure bridge is running on host machine
• Verify port forwarding (5000 for app, 8091 for bridge)
• Check Docker networking configuration

Performance Tips

• Use the Codex Bridge Tester to refine prompts before production use
• Enable MCP servers for more accurate script generation
• Monitor ARM-specific patterns in generated scripts
• Use 5-minute timeout for complex binary analysis requests

API Reference

Frida Script Runner Endpoints

• GET / - Main web interface
• POST /run_frida - Execute Frida script
• POST /generate-frida-script - AI script generation
• POST /get_packages - List device packages
• POST /dump_apk - Extract APK/IPA files

Codex Bridge Endpoints

• GET /health - Bridge health check
• POST /generate-script - Generate Frida script
• GET / - Interactive tester interface

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository and create a feature branch
2. Test thoroughly on both Android and iOS devices
3. Document new features in README and code comments
4. Follow coding standards and maintain compatibility
5. Submit pull requests with clear descriptions

Contact the maintainer: zenalarifin_

Contributors

Core Team

• Karjok
• Hasyim
• Irvan W
• Yudha
• Alfan
• Revan

License & Acknowledgments

Special Thanks

• Frida Project - Exceptional instrumentation toolkit
• Frida-ios-dump - IPA decryption tools
• OpenAI - Codex-powered script generation
• MCP Servers - Binary analysis integration

Security Notice

This tool is designed for authorized penetration testing and security research purposes only. Users are responsible for ensuring they have proper authorization before testing any mobile applications or devices.

---

Made with ❤️ for the mobile security community