Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time
November 1, 2016 15:39
January 21, 2017 21:18
September 17, 2021 11:15
November 27, 2017 03:13
June 1, 2019 10:07


This is an implementation of a native-code Meterpreter, designed for portability, embeddability, and low resource utilization. It can run on the smallest embedded Linux targets to big iron, and targets Android, iOS, macOS, Linux, and Windows, but can be ported to almost any POSIX-compliant environment.

Building on Linux

Debain, Ubuntu, and derivatives are most supported for builds. To build, you need at least 5GB of free disk space, and the following packages available:

# Dependencies
apt install curl build-essential git autoconf automake libtool bison flex gcc ruby rake bundler git mingw-w64

The Dockerfile under docker/Dockerfile contains a pre-configured build environment as well.

Building on macOS

On macOS you will need to install the xcode command line tools as follows:

xcode-select --install

Make Targets

For general development, there are a few make targets defined:

Running make will build for the local environment. E.g. if you're on macOS, it will build for macOS using your native compiler and tools.

make TARGET=triple will build for a specific host triple. See below for some common ones.

make clean will clean the 'mettle' directory for the current build target

make distclean will clean the entire build target`

make all-parallel will build for every known target, useful with '-j' to build multiple targets at once.

make clean-parallel and make distclean-parallel do similar for all targets.


To build the gem for distribution (currently requires Linux or macOS):

rake build

To check the resulting binaries:

rake check

To completely reset your dev environment and delete all binary artifacts:

rake mettle:ultraclean


To generate a payload with Mettle:

mettle =, config={})

The available platform triples for Linux targets are:

  • aarch64-linux-musl
  • armv5l-linux-musleabi
  • armv5b-linux-musleabi
  • i486-linux-musl
  • x86_64-linux-musl
  • powerpc-linux-muslsf
  • powerpc64le-linux-musl
  • mips-linux-muslsf
  • mipsel-linux-muslsf
  • mips64-linux-muslsf
  • s390x-linux-musl

For Mingw32-64 Windows targets, the following triples are added. On up-to-date Debian / Ubuntu systems, the mingw-w64 package will install both toolchains.

  • x86_64-w64-mingw32
  • i686-w64-mingw32

For macOS/iOS builds, the following triples are added. To target older macOS/OSX versions, see to get the appropriate SDK folder.

  • arm-iphone-darwin
  • aarch64-iphone-darwin
  • i386-apple-darwin
  • x86_64-apple-darwin
  • aarch64-apple-darwin

Available config options are:

  • :background - fork to background as a daemon
  • :debug - to turn on debug messages
  • :log_file - the file to send debug messages to instead of stderr
  • :uri - the uri to connect back to
  • :uuid - the UUID to identify the payload

Config options can also be set with:

mettle.config[:key] = val

To get a binary with installed options call:


The formats are:

  • :exec - a standalone executable that can take command-line arguments (see mettle -h) or use pre-set ones
  • :process_image - a process image that must be started with a custom stack (see doc/

Using with Metasploit

To pull your local changes of mettle into your Metasploit install:

  1. Add -dev to the version in lib/metasploit_payloads/mettle/version.rb
  2. Build the gem as above
  3. Copy pkg/ to the box you are using for Metasploit if it is different
  4. Change the version in your metasploit-framework.gemspec to match the one you just built
  5. gem install <path to new gem> (for example: 'metasploit_payloads-mettle', '')
  6. Run bundle install in your Framework directory, and ensure you see something like Using metasploit_payloads-mettle (was 0.4.1) in the output
  7. Congrats, you are now done!

Pushing out a New Gem

Build CI will automatically publish new gems when commits land to master and pass build.

  1. Test Locally
  2. Land the changes to upstream master
  3. Monitor for the new gem on
  4. Once the gem appears, make a PR for bumping the version in framework


This is an implementation of a native-code Meterpreter, designed for portability, embeddability, and low resource utilization.






No packages published