Noureddine RAMDI / Metasploit on Android via Termux: Automating a fragile Ruby native extension patch

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
995 Words
github-stars metasploit termux android ruby security shell

h4ck3r0/Metasploit-termux

Metasploit is a staple in security testing, but running it on Android devices has been a headache since it was dropped from official Termux repositories. The core problem lies in compiling critical Ruby native extensions on Android’s unique libc variant, Bionic, which breaks common assumptions in native code. Metasploit-termux tackles this head-on with an automated installer that patches these issues, making Metasploit accessible on mobile without hours of manual debugging.

Metasploit-termux: bringing Metasploit Framework to Android via Termux

Metasploit-termux is a shell-based automated installer designed to provision the Metasploit Framework inside Termux on Android devices. Termux provides a Linux-like terminal environment on Android, but with its own quirks, notably the use of Bionic libc instead of the standard glibc found on most Linux systems.

This installer script fills the void left after Metasploit was removed from Termux’s official repos. It handles the entire setup pipeline, including fetching the latest Metasploit Framework, managing dependencies, and configuring the environment to run Metasploit tools like msfconsole and msfvenom.

Under the hood, the script is optimized for ARM and ARM64 Android architectures, which are the predominant CPU types in modern phones. It includes tailored workarounds for compatibility issues specific to these platforms. The entire process is silent by default, logging errors to an install.log file, which improves the developer and user experience by avoiding noisy output during installation.

Key components managed by the installer include:

  • Ruby 3.4.0 and its native extensions, particularly Nokogiri and Gumbo, which are notoriously difficult to build on Android due to header mismatches with Bionic libc.
  • PostgreSQL database setup and initialization, as Metasploit relies heavily on it for storing session and exploit data.
  • Cleanup routines for stale PID files that can block PostgreSQL server startup, a common failure point in headless or interrupted installs.

The script is maintained by Raj Aryan (h4ck3r0), who has focused on creating a seamless experience for security practitioners needing a mobile Metasploit environment without manual dependency wrangling.

Technical strengths and tradeoffs in the Metasploit-termux installer

What sets this project apart is its surgical patch to fix Ruby 3.4.0’s Nokogiri/Gumbo native extension compilation problems on Android. Native extensions in Ruby rely on C libraries and headers that expect glibc’s definitions. Android’s Bionic libc diverges in subtle ways, leading to cryptic compilation errors.

The patch applied by this installer script modifies the build environment to align header expectations, enabling successful compilation. This is a brittle chain: Ruby → native extensions (Nokogiri/Gumbo) → libxml2 and Gumbo C libraries → Bionic libc headers. Without the patch, users face a multi-hour debugging ordeal, often abandoning attempts to run Metasploit natively on Android.

Beyond the patch, the installer offers:

  • PostgreSQL auto-initialization: The script automates database cluster creation and user setup, critical for Metasploit’s operation.

  • Stale PID cleanup: Leftover PID files from previous interrupted PostgreSQL sessions can prevent the database server from starting. The script proactively cleans these, reducing startup errors.

  • Silent logging mode: By redirecting all installation logs and errors to install.log, the installer avoids cluttering the terminal, which is helpful on mobile devices with limited screen space.

The tradeoff is that this script is highly opinionated and platform-specific. It assumes Termux is installed from F-Droid, requires a minimum of 2GB internal storage, and a stable internet connection. It’s optimized for ARM and ARM64 architectures, so it may not work on x86 Android devices or emulators.

The code is shell script-based, which keeps dependencies minimal but can be less robust compared to compiled installers. However, this aligns well with Termux’s environment and the need for portability.

Quick start with the Metasploit-termux installer

Getting Metasploit running on Termux is straightforward with this installer. Here’s the exact sequence of commands as documented:

# Install git if not present
apt install git -y

# Run the installer script
bash metasploit.sh

After the installation completes successfully, you can launch Metasploit’s interactive console with:

msfconsole

For generating payloads, use:

msfvenom

Keep in mind that Metasploit is resource-intensive. If Android kills the process, make sure to disable “Battery Optimization” for Termux to allow it to run uninterrupted in the background.

Verdict: who should use Metasploit-termux?

Metasploit-termux is a practical tool for mobile security practitioners and penetration testers who want a native Metasploit experience on Android. It removes the barrier of manually resolving complex Ruby native extension compilation issues on Bionic libc, a task that can be tedious and error-prone.

Its main limitation is platform specificity — it targets ARM/ARM64 devices running Termux from F-Droid, and requires at least 2GB of storage and a stable internet connection. The installer is shell script-based, which is simple but less flexible than some compiled alternatives.

For anyone needing to run Metasploit on a phone or tablet without resorting to full Linux containers or rooting, this project offers a viable, streamlined solution. The silent installation mode and PostgreSQL automation improve reliability and user experience.

If you are comfortable with Termux and need Metasploit on the go, this installer is worth trying. Otherwise, traditional Linux or desktop environments will still offer more stable and performant Metasploit setups.

→ GitHub Repo: h4ck3r0/Metasploit-termux ⭐ 266 · Shell