# 🔐 burp-frame – Unified Android Penetration Testing Framework
[](#)
[](https://www.python.org/)
[](LICENSE)
[](#)
**burp-frame** is a **professional-grade, cross-platform automation tool** meticulously designed to streamline mobile security assessments on **rooted Android devices and emulators**. It functions as a **"one-shot" tester's toolkit** 🎯, unifying essential tasks for **HTTPS traffic interception** and **dynamic analysis**, encompassing comprehensive certificate management, flexible global and per-application proxy configurations, robust Frida server deployment, and advanced, ****highly effective SSL pinning and security bypass techniques**.
Built for **security professionals**, **pen testers**, and **mobile developers**,`burp-frame` automates complex, multi-step workflows with a **user-friendly yet powerful command-line interface (CLI)**, supported by robust logging and cross-platform compatibility.
---
## ✨ Key Features
- **Unified CLI**: A singular, intuitive command-line interface for orchestrating all Android pentesting operations, simplifying complex workflows.
- **Certificate Installation (`install` module)**:
- **One-command certificate installation** of Burp Suite CA certificates directly onto the Android device.
- **Automates conversion** of Burp CA certificates from DER format to the Android-compatible `.0` format, complete with subject hash calculation.
- **Intelligent deployment**: Pushes converted certificates to the traditional `/system/etc/security/cacerts/` path, or leverages the systemless capabilities of Magisk.
- **Magisk Support**: Specifically designed to install certificates seamlessly into the systemless Magisk path, maintaining system integrity.
- **Dry-run mode**: Allows simulation of the entire certificate installation process without making any actual modifications to the device, ideal for testing and verification.
- **Proxy Management (`proxy` module)**:
- **Flexible global HTTP proxy settings**: Easily set and clear system-wide HTTP proxy configurations on the Android device via ADB for comprehensive traffic interception.
- **(Conceptual) Per-application proxy settings**: Provides a framework for managing proxy settings for specific applications, though practical effectiveness may vary across Android versions and app implementations.
- **Connectivity testing**: Includes functionality to test the configured global proxy's connectivity, ensuring your interception setup is active and correctly routing traffic.
- **Network intelligence**: Discover and display active network interfaces and their associated IP addresses on the connected device.
- **Frida Integration (`frida` module)**:
- **Automated Frida server deployment**: Deploys the appropriate `frida-server` binary to the connected Android device based on its architecture and intelligently attempts to start it in the background.
- **Process management**: List all running processes on the device, and kill processes efficiently by either their PID or package name.
- **Script injection**: Launch target applications with a custom Frida JavaScript script immediately injected, enabling early instrumentation.
- **Advanced Certificate Re-Pinning Bypass**: A specialized Frida capability to inject a custom CA certificate (like your Burp CA) directly into an application's trust store at runtime, effectively bypassing SSL pinning even when traditional certificate installation methods fail.
- **SSL Pinning & Security Bypasses (`bypass-ssl` & `universal-bypass` modules)**:
- **Generic SSL Bypass**: Facilitates the management (listing, downloading) and application of general-purpose Frida scripts designed to bypass various forms of SSL pinning implemented in Android applications.
- **Comprehensive Universal Bypass**: It provides **one-shot bypassing of common Android security mechanisms** directly from your terminal. Deploys a **powerful, all-in-one Frida script (enhanced with the latest techniques)** to comprehensively bypass multiple crucial security checks, including:
- **SSL pinning:** Covering multiple methods including OkHttp, Conscrypt, and HostnameVerifier.
- **Root detection:** Bypassing checks via filesystem anomalies, Runtime exec calls, SystemProperties, and common libraries like RootBeer.
- **Debugger checks:** Circumventing detection mechanisms for attached debuggers.
- **Emulator checks:** Masking indicators that reveal an application is running in an emulated environment.
- **Device Management (`device` module)**:
- **Essential device control**: Remotely reboot the connected Android device.
- **File system manipulation**: Remount the `/system` partition as either read-write (`remount-rw`) or read-only (`remount-ro`), crucial for system-level modifications (requires root).
- **Device discovery**: List all currently connected ADB devices and their properties.
- **Application lifecycle management**: Effortlessly install and uninstall APKs onto the device.
- **Flexible connectivity**: Connect to and disconnect from ADB devices over TCP/IP (e.g., for Wi-Fi debugging).
- **Automation & Usability**:
- **Automated cleanup**: Ensures all temporary certificate files and directories created by the framework are removed upon application exit.
- **Interactive and intelligent CLI**: Provides clear prompts, auto-validation of inputs, and helpful, context-aware messages to guide the user.
- **Detailed logging**: Generates timestamped, categorized logs to a dedicated `logs/` directory, essential for auditing, troubleshooting, and documenting pentesting activities.
- **Cross-Platform Compatibility**: Fully supports Windows, macOS, and Linux operating systems.
---
## 📦 Requirements
- **Python 3.7+** The framework is built on modern Python features.
- **[ADB (Android Debug Bridge)](https://developer.android.com/studio/releases/platform-tools)** The primary tool for device communication. Ensure it's installed and accessible in your system's PATH.
- [OpenSSL](https://www.openssl.org/) available in `PATH`. It is required for certificate conversions. Ensure it's installed and available in your PATH.
- **Frida CLI (frida-tools):** Install via `pip install frida-tools` (note: `pip install frida` also covers the Python library requirement).
- **Frida Server:** The on-device component of Frida. `burp-frame frida deploy` automates its download and deployment, requiring a working internet connection for the initial setup.
- **Rooted Android device or emulator** Essential for modifying system partitions (e.g., for certificate installation) and for many advanced Frida operations. (e.g., [Genymotion](https://www.genymotion.com/), or Magisk-patched Android Virtual Devices (AVDs))
- **Burp Suite CA certificate** Exported as a `.der` format file from Burp Suite. This is necessary for the `install` command and the `frida cert-repin` functionality.
---
## 🚀 Installation
### Option 1: From PyPI (recommended)
For the easiest installation, use pip:
```bash
pip install burp-frame
```
### Option 2: From source
For development or to access the latest features, clone the repository and install from source:
```bash
git clone https://github.com/Gashaw512/burp-frame
cd burp-frame/ # Navigate to the project root directory
pip install . # Installs the 'burp-frame' package from the current directory
```
> ✅ **Tip**: Always use a Python [virtual environment](https://docs.python.org/3/library/venv.html "null") (`python -m venv .venv` then `source .venv/bin/activate`) to isolate project dependencies and avoid conflicts with system-wide Python packages.
## ⚙️ Quick Start
Follow these steps to get started quickly with `burp-frame`:
### 1. Configure External Tool Paths
Before `burp-frame` can operate, you must tell it where to find your `adb` and `openssl` executables. You can also configure paths for Frida binaries if they are not in your system's `PATH`.
```
# Example for Windows:
burp-frame config --adb "C:\path\to\your\platform-tools\adb.exe" --openssl "C:\path\to\OpenSSL\bin\openssl.exe"
# Example for Linux/macOS:
burp-frame config --adb "/usr/local/bin/adb" --openssl "/usr/bin/openssl"
```
You can verify your current configuration settings at any time:
```bash
burp-frame config
```
### 2. Connect Your Android Device
Ensure your Android device (physical or emulator) is properly connected and recognized by ADB.
- Enable **USB debugging** on your Android phone or emulator (typically found in Developer Options).
- Verify your device is detected by ADB:
```bash
adb devices
```
### 3. Deploy Frida Server
For all Frida-related commands to function, the `frida-server` must be running on your Android device. `burp-frame` automates this process:
```bash
burp-frame frida deploy
```
## 📝 Command-Specific Usage
This section provides detailed usage examples for each module within the `burp-frame` framework.
### **`install` Module: Certificate Installation**
This module streamlines the process of installing your Burp Suite CA certificate onto Android devices, crucial for intercepting HTTPS traffic.
- **Before you begin**: In **Burp Suite**: Navigate to `Proxy → Proxy Settings/Options → Import/Export CA Certificate`. Choose **DER format** and save the exported file (e.g., `burp.der`) to your local machine.
- **Standard interactive installation (prompt-based)**: This will guide you through selecting your `.der` certificate file and automatically manage the conversion and deployment process.
```
burp-frame install
```
> You’ll be prompted to select the certificate file path. The device will automatically reboot once the installation is successful.
- **Install for Magisk systemless root**: If your device uses Magisk for systemless root, this option ensures the certificate is installed in the appropriate module path, preserving system integrity.
```
burp-frame install --magisk
```
- **Simulate installation without making changes (Dry-run mode)**: Useful for testing the installation workflow and verifying prerequisites without modifying the device.
```
burp-frame install --dry-run
```
### **`proxy` Module: Device Proxy Configuration**
This module facilitates setting and managing HTTP proxy settings on the Android device, both globally and, conceptually, on a per-application basis.
- **Set global HTTP proxy**: Configures the entire Android device to route all HTTP/S traffic through your specified proxy (e.g., Burp Suite).
```
burp-frame proxy set <YOUR_HOST_IP>:8080
# Example: burp-frame proxy set 192.168.1.100:8080
```
- **Clear global HTTP proxy**: Removes any existing global HTTP proxy settings, reverting the device to direct internet access.
```
burp-frame proxy clear
```
- **Get current global HTTP proxy settings**: Retrieves and displays the currently configured global HTTP proxy settings on the Android device.
```
burp-frame proxy get
```
- **Test global HTTP proxy connection**: Initiates an HTTP request from the device through the currently configured global proxy to a specified URL, reporting on connectivity. Useful for verifying your proxy setup.
```
burp-frame proxy test --url http://google.com
```
- **Display device IP addresses**: Lists the active network interfaces and their associated IPv4 and IPv6 addresses on the connected Android device, aiding in network configuration and troubleshooting.
```
burp-frame proxy ips
```
- **(Conceptual) Set per-app proxy**: **Note:** This method attempts to set a proxy for a specific application but is not universally reliable across all apps or Android versions. For robust per-app proxying or certificate pinning bypass, leveraging the `frida` module (e.g., `frida cert-repin`) is often more effective.
```
burp-frame proxy app set com.example.app <YOUR_HOST_IP>:8080
```
- **(Conceptual) Clear per-app proxy**: Attempts to remove any proxy settings for a specific application previously set by this tool.
```
burp-frame proxy app clear com.example.app
```
- **(Conceptual) Get per-app proxy**: Attempts to retrieve proxy settings for a specific application.
```
burp-frame proxy app get com.example.app
```
- **(Conceptual) List apps with proxy settings**: Lists applications that _might_ have specific proxy settings applied by this tool.
```
burp-frame proxy app list
```
### **`frida` Module: Dynamic Instrumentation**
This module provides extensive functionalities for deploying, managing, and interacting with Frida on your Android device, enabling powerful dynamic analysis and runtime manipulation.
- **Deploy Frida server to the device**: This is the first step for any Frida operation. It automatically identifies the correct `frida-server` binary for your device's architecture, pushes it, sets permissions, and starts it.
```
burp-frame frida deploy
```
- **List all running processes on the device**: Provides an overview of active processes, useful for identifying target applications.
```
burp-frame frida ps
```
- **Kill a process by PID or package name**: Terminates a specified running process on the device.
```
burp-frame frida kill <PID_OR_PACKAGE_NAME>
# Example: burp-frame frida kill com.example.app
# Example: burp-frame frida kill 12345
```
- **Launch an app and inject a custom Frida script**: Starts a specified application and immediately injects your custom Frida JavaScript (`.js`) script into its process.
```
burp-frame frida launch <PACKAGE_NAME> --script /path/to/your/custom_frida_script.js
```
- **Apply certificate re-pinning bypass (using a custom CA)**: This is an advanced technique for bypassing SSL pinning. It first pushes a local certificate file (e.g., your Burp CA certificate in `.0` format) to the device. Then, it uses a specialized Frida script to hook the application's SSLContext and dynamically inject your custom CA into its trusted certificate store at runtime.
```
burp-frame frida cert-repin <PACKAGE_NAME> --cert /path/to/your/burp_certificate_file.0
# To attach to an already running app instead of launching:
# burp-frame frida cert-repin <PACKAGE_NAME> --cert /path/to/your/burp_certificate_file.0 --attach
```
> 💡 **Note**: The `.0` certificate file is an Android-specific format derived from your Burp CA. It can be generated automatically by the `burp-frame install` command, or manually converted from DER using `openssl`.
### **`bypass-ssl` Module: Generic SSL Pinning Bypasses**
This module focuses on managing and applying general-purpose Frida scripts specifically designed for SSL pinning bypasses, complementing the certificate re-pinning method.
- **List available local SSL bypass scripts**: Shows a list of `.js` scripts available in your local `data/frida_scripts/bypass/` directory that can be applied for SSL pinning bypass.
```
burp-frame bypass-ssl list
```
- **Download a generic SSL bypass script**: Fetches a commonly used, generic SSL pinning bypass script from a public source and saves it to your local scripts directory.
```
burp-frame bypass-ssl download
```
- **Apply a local SSL bypass script to a target application**: Injects a chosen local `.js` script (from your scripts directory) into a target application to attempt SSL pinning bypass.
```
burp-frame bypass-ssl apply <PACKAGE_NAME> --script universal_bypass.js
# To attach to a running app instead of launching:
# burp-frame bypass-ssl apply <PACKAGE_NAME> --script universal_bypass.js --target-running
```
### **`universal-bypass` Module: Comprehensive Security Bypasses**
This module provides an incredibly powerful, all-in-one Frida script that combines multiple advanced techniques to bypass a wide array of security checks commonly implemented in Android applications. This includes, but is not limited to, various forms of SSL pinning, sophisticated debugger detection, diverse root detection mechanisms (file system, command execution, property checks), and common emulator detection logic.
- **Apply universal bypass (launches app and injects)**: Starts the target application and immediately injects the comprehensive universal bypass script.
burp-frame universal-bypass <PACKAGE_NAME>
- **Apply universal bypass (attaches to running app and injects)**: Attaches to an already running instance of the target application and injects the comprehensive universal bypass script.
burp-frame universal-bypass <PACKAGE_NAME> --attach
> ⚠️ **Important**: Both `frida cert-repin` and `universal-bypass` commands will keep your terminal session active to maintain the Frida injection. **Do not close your terminal** until you are finished with your testing, as closing it will detach Frida, and the bypasses will cease to function. To detach, simply press **Ctrl+C** in the terminal where the command is running.
### **`device` Module: Android Device Management**
This module offers a suite of commands for controlling your Android device's state and managing installed applications, leveraging ADB.
- **Essential device control**: Remotely reboot the connected Android device.
```
burp-frame device reboot
```
- **File system manipulation**: Remount the `/system` partition as either read-write (`remount-rw`) or read-only (`remount-ro`), crucial for system-level modifications (requires root).
```
burp-frame device remount-rw
```
- **Device discovery**: List all currently connected ADB devices and their properties.
```
burp-frame device ls
```
- **Application lifecycle management**: Effortlessly install and uninstall APKs onto the device.
```
burp-frame device install /path/to/your/app.apk
```
- **Flexible connectivity**: Connect to and disconnect from ADB devices over TCP/IP (e.g., for Wi-Fi debugging).
```
burp-frame device connect 192.168.1.10:5555
```
- **Disconnect from a device over TCP/IP**: Terminates an existing network-based ADB connection.
```
burp-frame device disconnect 192.168.1.10:5555
```
### **`config` Module: Tool Path Configuration**
This module allows you to easily manage and persist the absolute paths to external tools (`adb`, `openssl`, Frida binaries) that `burp-frame` depends on.
- **Interactive configuration wizard**: Launches an interactive prompt to guide you through setting paths for all supported tools.
```
burp-frame config
```
- **Set specific paths directly**: Allows direct specification of tool paths via command-line arguments.
```
burp-frame config --adb "/path/to/adb" --openssl "/path/to/openssl" --frida-server-binary "/path/to/frida-server" --frida-cli "/path/to/frida"
```
- **View current configuration**: Displays all currently stored tool paths.
```
burp-frame config
```
> You can also manually inspect the `config.json` file. Its location varies by OS: typically `~/.config/burp-frame/config.json` on Linux/macOS, or `C:\Users\YOUR_USER\AppData\Roaming\burp-frame\config.json` on Windows.
### **`logs` Module: View Operation Logs**
This module provides easy access to `burp-frame`'s detailed operation logs, essential for troubleshooting, auditing, and understanding framework activity.
- **View recent logs and select a log file to display**: Lists the most recent log files and allows you to choose one to display its contents directly in the terminal.
```
burp-frame logs
```
## ⚠️ Troubleshooting
| Issue | Solution |
|------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| ❌ adb or openssl not found | Run `burp-frame config` to set the correct paths. |
| ❌ Certificate conversion fails | Ensure OpenSSL is installed and accessible. Confirm the certificate is in DER format. |
| ❌ Device not detected | Run `adb devices` to confirm connection. Ensure USB debugging is enabled on your device. Check ADB drivers if on Windows. For remote connections, ensure `adb tcpip` is enabled on the device and firewall allows connection. |
| ❌ frida-server not running/found | After `burp-frame frida deploy`, verify `frida-server` is running on the device. Check device logs for errors if it fails to start. |
| ❌ Frida attachment fails | Ensure the target app is running (for `--attach`), correct package name is used, and device has `frida-server` running. Check device memory and process limits. |
| ⚠️ adb remount fails | Ensure your device/emulator is rooted. Some devices have dm-verity enabled on `/system`. Try `adb disable-verity` followed by `adb reboot`, `adb root`, then `adb remount`. |
| ❌ ImportError after PyPI install | Ensure `pip install burp-frame` completed without errors. If running from source, make sure you ran `pip install .` from the project root (where `pyproject.toml` is). |
| ❌ TypeError: ArgumentParser.__init__() got an unexpected keyword argument 'formatter' | Update your `cli.py` to use `formatter_class=argparse.RawTextHelpFormatter` instead of `formatter=...` in all `add_parser` calls. |
## 📚 FAQ
- **How do I export the certificate from Burp?** Go to: **Proxy → Options → Import/Export CA Certificate**. Choose **DER format** and save the file (e.g., `burp.der`).
- **Why does `burp-frame` require root access for certificate installation?** Android mandates that trusted CA certificates are installed into the system's certificate store, which resides in a protected `/system` partition. Modifying this partition requires root privileges. Magisk provides a systemless way to do this, and `burp-frame` supports it.
- **My emulator isn't rooted. What now?** `burp-frame` requires root access for system-level certificate installation and many advanced Frida operations. If your emulator isn't rooted, consider using one of the following:
- ✅ **Genymotion**: Its emulators are rooted by default, offering a convenient testing environment.
- ✅ **Magisk-patched AVDs**: You can create or patch Android Virtual Devices to include Magisk for root access.
- ✅ **Custom rooted emulator images**: Utilize pre-built or custom-rooted Android emulator images.
- **`adb remount` fails?** This issue often arises when `dm-verity` (a verified boot feature) is enabled on the system partition, preventing remounting. Try the following sequence:
```
adb disable-verity
adb reboot
adb root
adb remount
```
## 🤝 Contributing
Contributions, bug reports, and feature requests are highly welcomed and encouraged! If you’d like to help improve **burp-frame**, please follow these steps:
1. **Fork the repository** on GitHub.
2. **Create a feature branch** (`git checkout -b feature/your-feature-name`).
3. **Implement your changes** and ensure tests pass.
4. **Submit a pull request** describing your contributions clearly.
📄 **CONTRIBUTING.md** – _coming soon_ (This file will provide more detailed guidelines for contributions).
For suggestions, feedback, or collaboration inquiries, feel free to reach out: 📧 [kidanugashaw@gmail.com](mailto:kidanugashaw@gmail.com "null")
## 📝 License
**burp-frame** is distributed under the **MIT License**. This permissive license allows you to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software. © 2025 [Gashaw Kidanu](https://github.com/Gashaw512/burp-frame "null"). See the [LICENSE](https://www.google.com/search?q=LICENSE "null") file for full details.
## 👋 Final Notes
**burp-frame** is an actively maintained and continuously evolving framework, designed with extensibility and usability in mind. Whether you're a dedicated red teamer, a meticulous security engineer, or a mobile developer focused on application security, this tool is crafted to streamline your workflow for HTTPS interception and dynamic analysis on Android platforms.
> **Intercept with confidence. Secure with precision.** — _burp-frame_
Raw data
{
"_id": null,
"home_page": null,
"name": "burp-frame",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "android, burpsuite, certificate, installer, root, magisk, interception, security, frida, ssl-pinning, bypass, universal-bypass, mobile-security, pentesting",
"author": null,
"author_email": "Gashaw Kidanu <kidanugashaw@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/95/eb/89a6c461f1b5a99e85afd1f686e5760e26aa459b5d1aaf340a81ccb9c917/burp_frame-1.0.0.tar.gz",
"platform": null,
"description": "# \ud83d\udd10 burp-frame \u2013 Unified Android Penetration Testing Framework\r\n\r\n[](#)\r\n[](https://www.python.org/)\r\n[](LICENSE)\r\n[](#)\r\n\r\n**burp-frame** is a **professional-grade, cross-platform automation tool** meticulously designed to streamline mobile security assessments on \u200b**rooted Android devices and emulators\u200b**. It functions as a **\"one-shot\" tester's toolkit** \ud83c\udfaf, unifying essential tasks for **HTTPS traffic interception** and \u200b**dynamic analysis**\u200b, encompassing comprehensive certificate management, flexible global and per-application proxy configurations, robust Frida server deployment, and advanced, **\u200b**highly effective SSL pinning and security bypass techniques**\u200b.\r\n\r\nBuilt for **security professionals**, **pen testers**, and **mobile developers**,`burp-frame` automates complex, multi-step workflows with a **user-friendly yet powerful command-line interface (CLI)**, supported by robust logging and cross-platform compatibility.\r\n\r\n\r\n\r\n---\r\n\r\n\r\n## \u2728 Key Features\r\n\r\n- **Unified CLI**: A singular, intuitive command-line interface for orchestrating all Android pentesting operations, simplifying complex workflows.\r\n \r\n- **Certificate Installation (`install` module)**:\r\n \r\n - **One-command certificate installation** of Burp Suite CA certificates directly onto the Android device.\r\n \r\n - **Automates conversion** of Burp CA certificates from DER format to the Android-compatible `.0` format, complete with subject hash calculation.\r\n \r\n - **Intelligent deployment**: Pushes converted certificates to the traditional `/system/etc/security/cacerts/` path, or leverages the systemless capabilities of Magisk.\r\n \r\n - **Magisk Support**: Specifically designed to install certificates seamlessly into the systemless Magisk path, maintaining system integrity.\r\n \r\n - **Dry-run mode**: Allows simulation of the entire certificate installation process without making any actual modifications to the device, ideal for testing and verification.\r\n \r\n- **Proxy Management (`proxy` module)**:\r\n \r\n - **Flexible global HTTP proxy settings**: Easily set and clear system-wide HTTP proxy configurations on the Android device via ADB for comprehensive traffic interception.\r\n \r\n - **(Conceptual) Per-application proxy settings**: Provides a framework for managing proxy settings for specific applications, though practical effectiveness may vary across Android versions and app implementations.\r\n \r\n - **Connectivity testing**: Includes functionality to test the configured global proxy's connectivity, ensuring your interception setup is active and correctly routing traffic.\r\n \r\n - **Network intelligence**: Discover and display active network interfaces and their associated IP addresses on the connected device.\r\n \r\n- **Frida Integration (`frida` module)**:\r\n \r\n - **Automated Frida server deployment**: Deploys the appropriate `frida-server` binary to the connected Android device based on its architecture and intelligently attempts to start it in the background.\r\n \r\n - **Process management**: List all running processes on the device, and kill processes efficiently by either their PID or package name.\r\n \r\n - **Script injection**: Launch target applications with a custom Frida JavaScript script immediately injected, enabling early instrumentation.\r\n \r\n - **Advanced Certificate Re-Pinning Bypass**: A specialized Frida capability to inject a custom CA certificate (like your Burp CA) directly into an application's trust store at runtime, effectively bypassing SSL pinning even when traditional certificate installation methods fail.\r\n \r\n- **SSL Pinning & Security Bypasses (`bypass-ssl` & `universal-bypass` modules)**:\r\n \r\n - **Generic SSL Bypass**: Facilitates the management (listing, downloading) and application of general-purpose Frida scripts designed to bypass various forms of SSL pinning implemented in Android applications.\r\n \r\n - **Comprehensive Universal Bypass**: It provides **one-shot bypassing of common Android security mechanisms** directly from your terminal. Deploys a **powerful, all-in-one Frida script (enhanced with the latest techniques)** to comprehensively bypass multiple crucial security checks, including:\r\n - **SSL pinning:** Covering multiple methods including OkHttp, Conscrypt, and HostnameVerifier.\r\n - **Root detection:** Bypassing checks via filesystem anomalies, Runtime exec calls, SystemProperties, and common libraries like RootBeer.\r\n - **Debugger checks:** Circumventing detection mechanisms for attached debuggers.\r\n - **Emulator checks:** Masking indicators that reveal an application is running in an emulated environment.\r\n\r\n- **Device Management (`device` module)**:\r\n \r\n - **Essential device control**: Remotely reboot the connected Android device.\r\n \r\n - **File system manipulation**: Remount the `/system` partition as either read-write (`remount-rw`) or read-only (`remount-ro`), crucial for system-level modifications (requires root).\r\n \r\n - **Device discovery**: List all currently connected ADB devices and their properties.\r\n \r\n - **Application lifecycle management**: Effortlessly install and uninstall APKs onto the device.\r\n \r\n - **Flexible connectivity**: Connect to and disconnect from ADB devices over TCP/IP (e.g., for Wi-Fi debugging).\r\n \r\n- **Automation & Usability**:\r\n \r\n - **Automated cleanup**: Ensures all temporary certificate files and directories created by the framework are removed upon application exit.\r\n \r\n - **Interactive and intelligent CLI**: Provides clear prompts, auto-validation of inputs, and helpful, context-aware messages to guide the user.\r\n \r\n - **Detailed logging**: Generates timestamped, categorized logs to a dedicated `logs/` directory, essential for auditing, troubleshooting, and documenting pentesting activities.\r\n \r\n - **Cross-Platform Compatibility**: Fully supports Windows, macOS, and Linux operating systems.\r\n---\r\n\r\n## \ud83d\udce6 Requirements\r\n\r\n- **Python 3.7+** The framework is built on modern Python features.\r\n- **[ADB (Android Debug Bridge)](https://developer.android.com/studio/releases/platform-tools)** The primary tool for device communication. Ensure it's installed and accessible in your system's PATH.\r\n- [OpenSSL](https://www.openssl.org/) available in `PATH`. It is required for certificate conversions. Ensure it's installed and available in your PATH.\r\n- **Frida CLI (frida-tools):** Install via `pip install frida-tools` (note: `pip install frida` also covers the Python library requirement).\r\n- **Frida Server:** The on-device component of Frida. `burp-frame frida deploy` automates its download and deployment, requiring a working internet connection for the initial setup.\r\n- **Rooted Android device or emulator** Essential for modifying system partitions (e.g., for certificate installation) and for many advanced Frida operations. (e.g., [Genymotion](https://www.genymotion.com/), or Magisk-patched Android Virtual Devices (AVDs))\r\n- **Burp Suite CA certificate** Exported as a `.der` format file from Burp Suite. This is necessary for the `install` command and the `frida cert-repin` functionality.\r\n---\r\n\r\n## \ud83d\ude80 Installation\r\n\r\n### Option 1: From PyPI (recommended)\r\n\r\nFor the easiest installation, use pip:\r\n\r\n```bash\r\npip install burp-frame\r\n\r\n```\r\n\r\n### Option 2: From source\r\n\r\nFor development or to access the latest features, clone the repository and install from source:\r\n\r\n```bash\r\ngit clone https://github.com/Gashaw512/burp-frame\r\ncd burp-frame/ # Navigate to the project root directory\r\npip install . # Installs the 'burp-frame' package from the current directory\r\n\r\n```\r\n\r\n> \u2705 **Tip**: Always use a Python [virtual environment](https://docs.python.org/3/library/venv.html \"null\") (`python -m venv .venv` then `source .venv/bin/activate`) to isolate project dependencies and avoid conflicts with system-wide Python packages.\r\n\r\n## \u2699\ufe0f Quick Start\r\n\r\nFollow these steps to get started quickly with `burp-frame`:\r\n\r\n### 1. Configure External Tool Paths\r\n\r\nBefore `burp-frame` can operate, you must tell it where to find your `adb` and `openssl` executables. You can also configure paths for Frida binaries if they are not in your system's `PATH`.\r\n\r\n```\r\n# Example for Windows:\r\nburp-frame config --adb \"C:\\path\\to\\your\\platform-tools\\adb.exe\" --openssl \"C:\\path\\to\\OpenSSL\\bin\\openssl.exe\"\r\n\r\n# Example for Linux/macOS:\r\nburp-frame config --adb \"/usr/local/bin/adb\" --openssl \"/usr/bin/openssl\"\r\n\r\n```\r\n\r\nYou can verify your current configuration settings at any time:\r\n\r\n```bash\r\nburp-frame config\r\n\r\n```\r\n\r\n### 2. Connect Your Android Device\r\n\r\nEnsure your Android device (physical or emulator) is properly connected and recognized by ADB.\r\n\r\n- Enable **USB debugging** on your Android phone or emulator (typically found in Developer Options).\r\n \r\n- Verify your device is detected by ADB:\r\n \r\n```bash\r\n adb devices\r\n \r\n```\r\n \r\n\r\n### 3. Deploy Frida Server\r\n\r\nFor all Frida-related commands to function, the `frida-server` must be running on your Android device. `burp-frame` automates this process:\r\n\r\n```bash\r\nburp-frame frida deploy\r\n\r\n```\r\n## \ud83d\udcdd Command-Specific Usage\r\n\r\nThis section provides detailed usage examples for each module within the `burp-frame` framework.\r\n\r\n### **`install` Module: Certificate Installation**\r\n\r\nThis module streamlines the process of installing your Burp Suite CA certificate onto Android devices, crucial for intercepting HTTPS traffic.\r\n\r\n- **Before you begin**: In **Burp Suite**: Navigate to `Proxy \u2192 Proxy Settings/Options \u2192 Import/Export CA Certificate`. Choose **DER format** and save the exported file (e.g., `burp.der`) to your local machine.\r\n \r\n- **Standard interactive installation (prompt-based)**: This will guide you through selecting your `.der` certificate file and automatically manage the conversion and deployment process.\r\n \r\n ```\r\n burp-frame install\r\n \r\n ```\r\n \r\n > You\u2019ll be prompted to select the certificate file path. The device will automatically reboot once the installation is successful.\r\n \r\n- **Install for Magisk systemless root**: If your device uses Magisk for systemless root, this option ensures the certificate is installed in the appropriate module path, preserving system integrity.\r\n \r\n ```\r\n burp-frame install --magisk\r\n \r\n ```\r\n \r\n- **Simulate installation without making changes (Dry-run mode)**: Useful for testing the installation workflow and verifying prerequisites without modifying the device.\r\n \r\n ```\r\n burp-frame install --dry-run\r\n \r\n ```\r\n \r\n\r\n### **`proxy` Module: Device Proxy Configuration**\r\n\r\nThis module facilitates setting and managing HTTP proxy settings on the Android device, both globally and, conceptually, on a per-application basis.\r\n\r\n- **Set global HTTP proxy**: Configures the entire Android device to route all HTTP/S traffic through your specified proxy (e.g., Burp Suite).\r\n \r\n ```\r\n burp-frame proxy set <YOUR_HOST_IP>:8080\r\n # Example: burp-frame proxy set 192.168.1.100:8080\r\n \r\n ```\r\n \r\n- **Clear global HTTP proxy**: Removes any existing global HTTP proxy settings, reverting the device to direct internet access.\r\n \r\n ```\r\n burp-frame proxy clear\r\n \r\n ```\r\n \r\n- **Get current global HTTP proxy settings**: Retrieves and displays the currently configured global HTTP proxy settings on the Android device.\r\n \r\n ```\r\n burp-frame proxy get\r\n \r\n ```\r\n \r\n- **Test global HTTP proxy connection**: Initiates an HTTP request from the device through the currently configured global proxy to a specified URL, reporting on connectivity. Useful for verifying your proxy setup.\r\n \r\n ```\r\n burp-frame proxy test --url http://google.com\r\n \r\n ```\r\n \r\n- **Display device IP addresses**: Lists the active network interfaces and their associated IPv4 and IPv6 addresses on the connected Android device, aiding in network configuration and troubleshooting.\r\n \r\n ```\r\n burp-frame proxy ips\r\n \r\n ```\r\n \r\n- **(Conceptual) Set per-app proxy**: **Note:** This method attempts to set a proxy for a specific application but is not universally reliable across all apps or Android versions. For robust per-app proxying or certificate pinning bypass, leveraging the `frida` module (e.g., `frida cert-repin`) is often more effective.\r\n \r\n ```\r\n burp-frame proxy app set com.example.app <YOUR_HOST_IP>:8080\r\n \r\n ```\r\n \r\n- **(Conceptual) Clear per-app proxy**: Attempts to remove any proxy settings for a specific application previously set by this tool.\r\n \r\n ```\r\n burp-frame proxy app clear com.example.app\r\n \r\n ```\r\n \r\n- **(Conceptual) Get per-app proxy**: Attempts to retrieve proxy settings for a specific application.\r\n \r\n ```\r\n burp-frame proxy app get com.example.app\r\n \r\n ```\r\n \r\n- **(Conceptual) List apps with proxy settings**: Lists applications that _might_ have specific proxy settings applied by this tool.\r\n \r\n ```\r\n burp-frame proxy app list\r\n \r\n ```\r\n \r\n\r\n### **`frida` Module: Dynamic Instrumentation**\r\n\r\nThis module provides extensive functionalities for deploying, managing, and interacting with Frida on your Android device, enabling powerful dynamic analysis and runtime manipulation.\r\n\r\n- **Deploy Frida server to the device**: This is the first step for any Frida operation. It automatically identifies the correct `frida-server` binary for your device's architecture, pushes it, sets permissions, and starts it.\r\n \r\n ```\r\n burp-frame frida deploy\r\n \r\n ```\r\n \r\n- **List all running processes on the device**: Provides an overview of active processes, useful for identifying target applications.\r\n \r\n ```\r\n burp-frame frida ps\r\n \r\n ```\r\n \r\n- **Kill a process by PID or package name**: Terminates a specified running process on the device.\r\n \r\n ```\r\n burp-frame frida kill <PID_OR_PACKAGE_NAME>\r\n # Example: burp-frame frida kill com.example.app\r\n # Example: burp-frame frida kill 12345\r\n \r\n ```\r\n \r\n- **Launch an app and inject a custom Frida script**: Starts a specified application and immediately injects your custom Frida JavaScript (`.js`) script into its process.\r\n \r\n ```\r\n burp-frame frida launch <PACKAGE_NAME> --script /path/to/your/custom_frida_script.js\r\n \r\n ```\r\n \r\n- **Apply certificate re-pinning bypass (using a custom CA)**: This is an advanced technique for bypassing SSL pinning. It first pushes a local certificate file (e.g., your Burp CA certificate in `.0` format) to the device. Then, it uses a specialized Frida script to hook the application's SSLContext and dynamically inject your custom CA into its trusted certificate store at runtime.\r\n \r\n ```\r\n burp-frame frida cert-repin <PACKAGE_NAME> --cert /path/to/your/burp_certificate_file.0\r\n # To attach to an already running app instead of launching:\r\n # burp-frame frida cert-repin <PACKAGE_NAME> --cert /path/to/your/burp_certificate_file.0 --attach\r\n \r\n ```\r\n \r\n > \ud83d\udca1 **Note**: The `.0` certificate file is an Android-specific format derived from your Burp CA. It can be generated automatically by the `burp-frame install` command, or manually converted from DER using `openssl`.\r\n \r\n\r\n### **`bypass-ssl` Module: Generic SSL Pinning Bypasses**\r\n\r\nThis module focuses on managing and applying general-purpose Frida scripts specifically designed for SSL pinning bypasses, complementing the certificate re-pinning method.\r\n\r\n- **List available local SSL bypass scripts**: Shows a list of `.js` scripts available in your local `data/frida_scripts/bypass/` directory that can be applied for SSL pinning bypass.\r\n \r\n ```\r\n burp-frame bypass-ssl list\r\n \r\n ```\r\n \r\n- **Download a generic SSL bypass script**: Fetches a commonly used, generic SSL pinning bypass script from a public source and saves it to your local scripts directory.\r\n \r\n ```\r\n burp-frame bypass-ssl download\r\n \r\n ```\r\n \r\n- **Apply a local SSL bypass script to a target application**: Injects a chosen local `.js` script (from your scripts directory) into a target application to attempt SSL pinning bypass.\r\n \r\n ```\r\n burp-frame bypass-ssl apply <PACKAGE_NAME> --script universal_bypass.js\r\n # To attach to a running app instead of launching:\r\n # burp-frame bypass-ssl apply <PACKAGE_NAME> --script universal_bypass.js --target-running\r\n \r\n ```\r\n \r\n\r\n### **`universal-bypass` Module: Comprehensive Security Bypasses**\r\n\r\nThis module provides an incredibly powerful, all-in-one Frida script that combines multiple advanced techniques to bypass a wide array of security checks commonly implemented in Android applications. This includes, but is not limited to, various forms of SSL pinning, sophisticated debugger detection, diverse root detection mechanisms (file system, command execution, property checks), and common emulator detection logic.\r\n - **Apply universal bypass (launches app and injects)**: Starts the target application and immediately injects the comprehensive universal bypass script.\r\n \r\n \r\n burp-frame universal-bypass <PACKAGE_NAME>\r\n \r\n \r\n \r\n - **Apply universal bypass (attaches to running app and injects)**: Attaches to an already running instance of the target application and injects the comprehensive universal bypass script.\r\n \r\n \r\n burp-frame universal-bypass <PACKAGE_NAME> --attach\r\n \r\n > \u26a0\ufe0f **Important**: Both `frida cert-repin` and `universal-bypass` commands will keep your terminal session active to maintain the Frida injection. **Do not close your terminal** until you are finished with your testing, as closing it will detach Frida, and the bypasses will cease to function. To detach, simply press **Ctrl+C** in the terminal where the command is running.\r\n \r\n\r\n### **`device` Module: Android Device Management**\r\n\r\nThis module offers a suite of commands for controlling your Android device's state and managing installed applications, leveraging ADB.\r\n\r\n- **Essential device control**: Remotely reboot the connected Android device.\r\n \r\n ```\r\n burp-frame device reboot\r\n \r\n ```\r\n \r\n- **File system manipulation**: Remount the `/system` partition as either read-write (`remount-rw`) or read-only (`remount-ro`), crucial for system-level modifications (requires root).\r\n \r\n ```\r\n burp-frame device remount-rw\r\n \r\n ```\r\n \r\n- **Device discovery**: List all currently connected ADB devices and their properties.\r\n \r\n ```\r\n burp-frame device ls\r\n \r\n ```\r\n \r\n- **Application lifecycle management**: Effortlessly install and uninstall APKs onto the device.\r\n \r\n ```\r\n burp-frame device install /path/to/your/app.apk\r\n \r\n ```\r\n \r\n- **Flexible connectivity**: Connect to and disconnect from ADB devices over TCP/IP (e.g., for Wi-Fi debugging).\r\n \r\n ```\r\n burp-frame device connect 192.168.1.10:5555\r\n \r\n ```\r\n \r\n- **Disconnect from a device over TCP/IP**: Terminates an existing network-based ADB connection.\r\n \r\n ```\r\n burp-frame device disconnect 192.168.1.10:5555\r\n \r\n ```\r\n \r\n\r\n### **`config` Module: Tool Path Configuration**\r\n\r\nThis module allows you to easily manage and persist the absolute paths to external tools (`adb`, `openssl`, Frida binaries) that `burp-frame` depends on.\r\n\r\n- **Interactive configuration wizard**: Launches an interactive prompt to guide you through setting paths for all supported tools.\r\n \r\n ```\r\n burp-frame config\r\n \r\n ```\r\n \r\n- **Set specific paths directly**: Allows direct specification of tool paths via command-line arguments.\r\n \r\n ```\r\n burp-frame config --adb \"/path/to/adb\" --openssl \"/path/to/openssl\" --frida-server-binary \"/path/to/frida-server\" --frida-cli \"/path/to/frida\"\r\n \r\n ```\r\n \r\n- **View current configuration**: Displays all currently stored tool paths.\r\n \r\n ```\r\n burp-frame config\r\n \r\n ```\r\n \r\n > You can also manually inspect the `config.json` file. Its location varies by OS: typically `~/.config/burp-frame/config.json` on Linux/macOS, or `C:\\Users\\YOUR_USER\\AppData\\Roaming\\burp-frame\\config.json` on Windows.\r\n \r\n\r\n### **`logs` Module: View Operation Logs**\r\n\r\nThis module provides easy access to `burp-frame`'s detailed operation logs, essential for troubleshooting, auditing, and understanding framework activity.\r\n\r\n- **View recent logs and select a log file to display**: Lists the most recent log files and allows you to choose one to display its contents directly in the terminal.\r\n \r\n ```\r\n burp-frame logs\r\n \r\n ```\r\n \r\n## \u26a0\ufe0f Troubleshooting\r\n\r\n| Issue | Solution |\r\n|------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|\r\n| \u274c adb or openssl not found | Run `burp-frame config` to set the correct paths. |\r\n| \u274c Certificate conversion fails | Ensure OpenSSL is installed and accessible. Confirm the certificate is in DER format. |\r\n| \u274c Device not detected | Run `adb devices` to confirm connection. Ensure USB debugging is enabled on your device. Check ADB drivers if on Windows. For remote connections, ensure `adb tcpip` is enabled on the device and firewall allows connection. |\r\n| \u274c frida-server not running/found | After `burp-frame frida deploy`, verify `frida-server` is running on the device. Check device logs for errors if it fails to start. |\r\n| \u274c Frida attachment fails | Ensure the target app is running (for `--attach`), correct package name is used, and device has `frida-server` running. Check device memory and process limits. |\r\n| \u26a0\ufe0f adb remount fails | Ensure your device/emulator is rooted. Some devices have dm-verity enabled on `/system`. Try `adb disable-verity` followed by `adb reboot`, `adb root`, then `adb remount`. |\r\n| \u274c ImportError after PyPI install | Ensure `pip install burp-frame` completed without errors. If running from source, make sure you ran `pip install .` from the project root (where `pyproject.toml` is). |\r\n| \u274c TypeError: ArgumentParser.__init__() got an unexpected keyword argument 'formatter' | Update your `cli.py` to use `formatter_class=argparse.RawTextHelpFormatter` instead of `formatter=...` in all `add_parser` calls. |\r\n\r\n## \ud83d\udcda FAQ\r\n\r\n- **How do I export the certificate from Burp?** Go to: **Proxy \u2192 Options \u2192 Import/Export CA Certificate**. Choose **DER format** and save the file (e.g., `burp.der`).\r\n \r\n- **Why does `burp-frame` require root access for certificate installation?** Android mandates that trusted CA certificates are installed into the system's certificate store, which resides in a protected `/system` partition. Modifying this partition requires root privileges. Magisk provides a systemless way to do this, and `burp-frame` supports it.\r\n \r\n- **My emulator isn't rooted. What now?** `burp-frame` requires root access for system-level certificate installation and many advanced Frida operations. If your emulator isn't rooted, consider using one of the following:\r\n \r\n - \u2705 **Genymotion**: Its emulators are rooted by default, offering a convenient testing environment.\r\n \r\n - \u2705 **Magisk-patched AVDs**: You can create or patch Android Virtual Devices to include Magisk for root access.\r\n \r\n - \u2705 **Custom rooted emulator images**: Utilize pre-built or custom-rooted Android emulator images.\r\n \r\n- **`adb remount` fails?** This issue often arises when `dm-verity` (a verified boot feature) is enabled on the system partition, preventing remounting. Try the following sequence:\r\n \r\n ```\r\n adb disable-verity\r\n adb reboot\r\n adb root\r\n adb remount\r\n \r\n ```\r\n \r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nContributions, bug reports, and feature requests are highly welcomed and encouraged! If you\u2019d like to help improve **burp-frame**, please follow these steps:\r\n\r\n1. **Fork the repository** on GitHub.\r\n \r\n2. **Create a feature branch** (`git checkout -b feature/your-feature-name`).\r\n \r\n3. **Implement your changes** and ensure tests pass.\r\n \r\n4. **Submit a pull request** describing your contributions clearly.\r\n\r\n\ud83d\udcc4 **CONTRIBUTING.md** \u2013 _coming soon_ (This file will provide more detailed guidelines for contributions).\r\n\r\nFor suggestions, feedback, or collaboration inquiries, feel free to reach out: \ud83d\udce7 [kidanugashaw@gmail.com](mailto:kidanugashaw@gmail.com \"null\")\r\n\r\n## \ud83d\udcdd License\r\n\r\n**burp-frame** is distributed under the **MIT License**. This permissive license allows you to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software. \u00a9 2025 [Gashaw Kidanu](https://github.com/Gashaw512/burp-frame \"null\"). See the [LICENSE](https://www.google.com/search?q=LICENSE \"null\") file for full details.\r\n\r\n## \ud83d\udc4b Final Notes\r\n\r\n**burp-frame** is an actively maintained and continuously evolving framework, designed with extensibility and usability in mind. Whether you're a dedicated red teamer, a meticulous security engineer, or a mobile developer focused on application security, this tool is crafted to streamline your workflow for HTTPS interception and dynamic analysis on Android platforms.\r\n\r\n> **Intercept with confidence. Secure with precision.** \u2014 _burp-frame_\r\n\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A unified Android penetration testing framework with certificate installation, proxy configuration, Frida instrumentation, and universal bypasses.",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/Gashaw512/burp-frame/issues",
"Homepage": "https://github.com/Gashaw512/burp-frame"
},
"split_keywords": [
"android",
" burpsuite",
" certificate",
" installer",
" root",
" magisk",
" interception",
" security",
" frida",
" ssl-pinning",
" bypass",
" universal-bypass",
" mobile-security",
" pentesting"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "59cb05aad9a833b96a472e1cda6b7a88d36a119a5dc88d3d6ff06a5340884d9a",
"md5": "af7875d2bcbe710e59de5a7bd336728c",
"sha256": "aad4b402ed264657f9f24630374f29669859e99b62b532a9a69dfeaa4e2ff00c"
},
"downloads": -1,
"filename": "burp_frame-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "af7875d2bcbe710e59de5a7bd336728c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 55856,
"upload_time": "2025-08-14T15:23:45",
"upload_time_iso_8601": "2025-08-14T15:23:45.609716Z",
"url": "https://files.pythonhosted.org/packages/59/cb/05aad9a833b96a472e1cda6b7a88d36a119a5dc88d3d6ff06a5340884d9a/burp_frame-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "95eb89a6c461f1b5a99e85afd1f686e5760e26aa459b5d1aaf340a81ccb9c917",
"md5": "c03ed0820bd1b9ab63409c27e0a4ed2b",
"sha256": "1bf9cc8097f98d0ec70764f0b87c666b190afb89164a079a996e5374510cae34"
},
"downloads": -1,
"filename": "burp_frame-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "c03ed0820bd1b9ab63409c27e0a4ed2b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 55105,
"upload_time": "2025-08-14T15:23:47",
"upload_time_iso_8601": "2025-08-14T15:23:47.239205Z",
"url": "https://files.pythonhosted.org/packages/95/eb/89a6c461f1b5a99e85afd1f686e5760e26aa459b5d1aaf340a81ccb9c917/burp_frame-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 15:23:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Gashaw512",
"github_project": "burp-frame",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "burp-frame"
}
JSON
