Mettle
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.
Packaging
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
Gem API
To generate a payload with Mettle:
mettle = MetasploitPayloads::Mettle.new(platform_triple, config={})
The available platform triples for Linux targets are:
aarch64-linux-muslarmv5l-linux-musleabiarmv5b-linux-musleabii486-linux-muslx86_64-linux-muslpowerpc-linux-muslsfpowerpc64le-linux-muslmips-linux-muslsfmipsel-linux-muslsfmips64-linux-muslsfs390x-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-mingw32i686-w64-mingw32
For macOS/iOS builds, the following triples are added. To target older macOS/OSX
versions, see https://github.com/phracker/MacOSX-SDKs to get the appropriate
SDK folder.
arm-iphone-darwinaarch64-iphone-darwini386-apple-darwinx86_64-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 ofstderr: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:
mettle.to_binary(format=:process_image)
The formats are:
:exec- a standalone executable that can take command-line arguments (seemettle -h) or use pre-set ones:process_image- a process image that must be started with a custom stack (seedoc/stack_requirements.md)
Using with Metasploit
To pull your local changes of mettle into your Metasploit install:
- Add
-devto the version inlib/metasploit_payloads/mettle/version.rb - Build the gem as above
- Copy
pkg/metasploit-payloads-mettle-X.X.X.pre.dev.gemto the box you are using for Metasploit if it is different - Change the version in your metasploit-framework.gemspec to match the one you just built
gem install <path to new gem>(for example: 'metasploit_payloads-mettle', '0.4.1.pre.dev')- Run
bundle installin your Framework directory, and ensure you see something likeUsing metasploit_payloads-mettle 0.4.1.pre.dev (was 0.4.1)in the output - 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.
- Test Locally
- Land the changes to upstream master
- Monitor for the new gem on rubygems.org
- Once the gem appears, make a PR for bumping the version in framework