metasploit-payloads Documentation

Unified repository for different Metasploit Framework payloads

2,076 stars C C 7 files · ~6,598 tokens
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy metasploit-payloads on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name metasploit-payloads --restart always rapid7/metasploit-payloads:latest

Technical Documentation: rapid7/metasploit-payloads

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

metasploit-payloads

Appveyor build status:

This is a unified repository for different Metasploit Framework payloads, which merges these repositories:

An alternate cross-platform C Meterpreter, called Mettle, is developed at https://github.com/rapid7/mettle

See the individual directories for meterpreter-specific README, build instructions and license details:

For Python and PHP Meterpreter, you can test changes to these files by symlinking the associated files to ~/.msf4/payloads/meterpreter.
As an example, here is how this might look like for a Python Meterpreter edit:

bash
mkdir -p ~/.msf4/payloads
cd ~/metasploit-payloads
ln -s ~/metasploit-payloads/python/meterpreter/ext_server_stdapi.py ~/.msf4/payloads/meterpreter/ext_server_stdapi.py
file ~/.msf4/payloads/meterpreter/ext_server_stdapi.py
       /home/your_user/.msf4/payloads/meterpreter/ext_server_stdapi.py: symbolic link to /home/your_user/git/metasploit-payloads/python/meterpreter/ext_server_stdapi.py

If things went right you should see a warning message when selecting one of the corresponding Meterpreter payloads and receiving a session:

text
msf6 > use payload/python/meterpreter/reverse_tcp
msf6 payload(python/meterpreter/reverse_tcp) > set LHOST 192.168.153.128
LHOST => 192.168.153.128
msf6 payload(python/meterpreter/reverse_tcp) > generate -f raw -o reverse.py
[*] Writing 436 bytes to reverse.py...
msf6 payload(python/meterpreter/reverse_tcp) > to_handler
[*] Payload Handler Started as Job 0

[*] Started reverse TCP handler on 192.168.153.128:4444
msf6 payload(python/meterpreter/reverse_tcp) > WARNING: Local file /home/your_user/.msf4/payloads/meterpreter/meterpreter.py is being used
WARNING: Local files may be incompatible with the Metasploit Framework
[*] Sending stage (24380 bytes) to 192.168.153.1
WARNING: Local file /home/your_user/.msf4/payloads/meterpreter/ext_server_stdapi.py is being used
[*] Meterpreter session 1 opened (192.168.153.128:4444 -> 192.168.153.1:50334) at 2022-12-13 12:49:49 -0600

When making changes to Meterpreter - ensure that the test modules are verified as working.

Overview (`gem/README.md`)

Metasploit Payloads

This gem is a Metasploit-specific gem that contains all of the
Meterpreter payloads (except for Mettle). This is made up of:

  • Windows DLLs
  • Java Classes
  • PHP/Python Scripts

Mettle, the Native Linux / Posix payload, currently is developed at
https://github.com/rapid7/mettle (to be moved here at some point?)

Installation

Given the nature of the contents of this gem, installation
outside of Metasploit is not advised. To use Meterpreter,
download and install Metasploit itself.

Building

To build the gem:

  1. Update the version number in lib/metasploit-payloads/version.rb
  2. Run:
  • rake win_prep to build on Windows
  • rake java_prep to build Java files
  • rake python_prep and rake php_prep to copy the latest PHP/Python
    meterpreter files into place
  1. Binaries will be built in the data folder.
  2. Run rake build to generate the new gem file using content in
    meterpreter folder.
  3. Run rake release to release the binary to RubyGems.

Note, when using the command rake win_prep and related Windows rake
tasks, you must be in the Visual Studio Developer command prompt,
and have a path to a git binary in your default path. If your
git.exe is part of posh-git or GitHub for Windows, that means adding
something like the following to your path:

"C:\Users\USERNAME\AppData\Local\GitHub\PortableGit_LONG_UUID_STRING_THING\bin"

Overview (`java/README.md`)

Building the Java and Android Meterpreter

  1. Install Maven and Java 1.8, this will depend on your OS
  2. Download the Android SDK
  3. Install Android SDK Platforms 3, 10 and 19, and update the "Android SDK Tools" and "Android SDK Platform-tools"
  4. Compile the Android and Java Meterpreter, which deploys to the ../metasploit-framework folder
text
mvn package -Dandroid.sdk.path=/path/to/android-sdk -Dandroid.release=true -P deploy

Next time you run msfconsole, you should see: WARNING: Local files may be incompatible with the Metasploit Framework.
This means that msfconsole is now using your newly built version of the Java and Android Meterpreter :)

Building on Docker

Ensure that both the metasploit-payloads and metasploit-framework folders co-exist beside eachother:

text
$ ls working_directory
metasploit-framework
metasploit-payloads

Next you can download a pre-built Docker image from Rapid7's Docker Hub account:

text
docker pull rapid7/msf-ubuntu-x64-meterpreter:latest

Or this Docker image can be built manually:

text
cd working_directory/metasploit-payloads/docker
docker build -t rapid7/msf-ubuntu-x64-meterpreter:latest .

Next run the Docker image as a container and mount the working_directory.
This interactive shell will allow you to compile the Android and Java Meterpreter, and deploy
to the ../metasploit-framework folder as normal:

text
cd working_directory
docker run --rm  -it -w $(pwd) -v $(pwd):$(pwd) rapid7/msf-ubuntu-x64-meterpreter:latest /bin/bash

cd metasploit-payloads/java
# Optional: You may need to run a clean if you are having compilation issues
make clean
make android

Building on OSX

text
brew tap homebrew/cask-versions
brew install --cask temurin8
brew install --cask android-sdk
brew install maven
sdkmanager --licenses
sdkmanager "platforms;android-3"
sdkmanager "platforms;android-10"
sdkmanager "platforms;android-19"

#cd metasploit-payloads/java

# Important: Ensure Java 1.8 is used when compiling
export JAVA_HOME=/Library/Java/JavaVirtualMachines/openjdk-8.jdk/Contents/Home

# Just Meterpreter
mvn package -P deploy

# With Android
mvn package -Dandroid.sdk.path=/usr/local/share/android-sdk -Dandroid.release=true -P deploy

Compiling JavaPayload and Java Meterpreter manually

To compile JavaPayload (a Java stager / code loader) and Java Meterpreter for
Metasploit, you need Maven 3.1 or above (Maven 3.5 works at the time of this
writing), and a copy of JDK 8.0 or later. Ensure that mvn and javac are in
your path and work. Then run

text
mvn package

to package all the files needed for Java meterpreter. The two files that you will be generated are:

text
meterpreter/meterpreter/target/meterpreter.jar
meterpreter/stdapi/target/ext_server_stdapi.jar

To get Metasploit to use these files, you need to place them in a place where
it can find them. To automatically build and install these files into
Metasploit Framework for testing, run:

text
mvn -P deploy package

This will package all the files and copy them into the correct place for
Metasploit, assuming that the metasploit-framework repository is checked out in
an adjacent directory to this one. (../../metasploit-framework/data/java). If
you get spurious compilation errors, make sure that there is an exclude rule in
your antivirus for the Metasploit directory (or that your antivirus is
disabled).

If the path to your metasploit framework repository is not
../../metasploit-framework, but for example (with Kali Linux)

/usr/share/metasploit-framework/, set the deploy.path directive like so:

text
mvn -D deploy.path=/usr/share/metasploit-framework -P deploy package

When you are editing this or any other Meterpreter, you will want to make sure
that your copy of metasploit-framework is also up-to-date. We occasionally
update the network protocol between Metasploit and its Payloads, and if the two
do not match, things will probably not work. Metasploit will warn you the first
time it stages a development payload that it is doing so, and that the payload
and Metasploit framework may be incompatible.

Each time you make a change to your code, you must build and deploy the files
into metasploit-framework for it to see the updates. It is not necessary to
restart msfconsole when updating payloads however, as they are read from disk
each time. So, a reasonable strategy when debugging is to leave msfconsole
running with exploit/multi/handler, and just install and restage payloads as
needed.

When you are done editing and want to revert Metasploit to use the builtin
payloads, simply delete data/meterpreter/*.jar and data/meterpreter/java
from your Metasploit framework directory. It will then fall back to the
versions bundled with the metasploit-payloads Ruby gem.

IDE Support

Note: First ensure you have Java 1.8 installed, and your IDE is using Java 1.8

In case you want to edit/debug JavaPayload for Metasploit or Java Meterpreter
with an IDE, Maven provides plugins to auto-generate project files for your
favourite environment (at least for Eclipse, Netbeans or IntelliJ).

I use Eclipse, so to generate project files I use

text
mvn eclipse:eclipse

This will generate project files that can be imported via

File->Import->Existing Projects into Workspace

into your Eclipse workspace.

(Note that if this is your first Maven project you want to use in Eclipse, you
also have to run

text
mvn -Declipse.workspace=/path/to/your/workspace eclipse:configure-workspace

to set up path variables like M2_REPO to point to the correct location.)

For NetBeans or IntelliJ IDEA, refer to the documentation at

http://maven.apache.org/netbeans-module.html
http://maven.apache.org/plugins/maven-idea-plugin/

Overview (`c/meterpreter/README.md`)

Windows Native C meterpreter >

Before you do anything, you're going to need to make sure you have the dependencies set up. Windows Meterpreter has the following repositories set up as submodule dependencies:

For Meterpreter to build correctly, these submodules must be initialised and updated,
like so:

text
git clone https://github.com/rapid7/metasploit-payloads
cd metasploit-payloads
git submodule init
git submodule update

With the code checked out and the submodules updated, you're ready to run a build. Here you have two main options:

  • Compile Windows Meterpreter on Windows with VS2019 or later.
  • Cross-compile Windows Meterpreter on Linux, either directly on your host or via a Docker container.

Building - Windows on Windows

Meterpreter currently supports being built with Visual Studio 2019 or later, including the free/community editions.
Before building make sure to disable antivirus/windows defender.

VS 2019

Building with VS2019 works with any version, including community. If you have an installation already, just make sure you have the following extra bits installed:

  • Under Workloads:
    • Desktop Development with C++
  • Under Individual Components:
    • C++ Windows XP Support for VS 2017 (v141) tools [Deprecated]

If you don't have an installation ready, follow these steps:

  1. Install Chocolatey.
  2. Install VS with all the required components by running the following command in Powershell:
text
choco install visualstudio2019community -y --package-parameters "--config C:\YOUR_PATH\metasploit-payloads\c\meterpreter\vs-configs\vs2019.vsconfig"

Running the Build

Open a Developer Command Prompt for Visual Studio 2019 or later from the Start menu.
Alternatively you can run vcvars32.bat from an existing command
line prompt, just make sure it's the right one if you have multiple versions of VS
installed on your machine.

Once you have your environment variables set up, change to the root folder where the
meterpreter source is located. From here you can:

  • Build the x86 version by running: make x86
  • Build the x64 version by running: make x64
  • Build both x86 and x64 versions by running: make

The Rapid7 build automation uses v141_xp to build the distributed binaries, so projects must build with that platform toolset.

The compiled binaries are written to the output folder.

If you are not a Rapid7 employee, make sure you build the source using the debug or release configurations when inside Visual Studio. If you attempt to build r7_debug or r7_release you will get compiler errors due to missing libraries.

If you build the source from the command line the toolset will choose the most appropriate build configuration for you and hence calling make should "Just Work™".

If you are a Rapid7 employee you will need the PSSDK source in order to build the extra components using the r7_* build configurations.

If submodule dependencies are not found on the file system, the script should display an error message like so:

text
Meterpreter's submodule dependencies can't be found.
From your git console, please run:
  $ git submodule init && git submodule update

Building - Windows on Linux

Configuring a build environment on Linux is a bit of a pain in the rear and is also very likely to change in the near future as we move towards building via clang and making use of llvm for things such as transformations. As a result, we would recommend that you don't try to set up a host environment just yet. The best option is to make use of the docker container that has been built and configured to do the builds for you.

The docker container should be published to the Internet. However, if it isn't, you can build it yourself by running:

text
make docker-container

This takes a while, so be patient.

If you want to use the pre-built container all you have to do is run a normal build, and the container image will be downloaded if it's not present in the current list of locally available images. To do this, run:

text
make docker

Making the components

As mentioned above, to build the entire supported suite of binaries, run the following:

text
make docker

It's possible to build architecture-specific versions by appending the architecture in question.

text
# Build x64 only
make docker-x64
# Build x86 only
make docker-x86

There are a number of other options in the Makefile, including the ability to build individual sets. Here are some examples:

text
# Build metsrv for all architectures
make docker-metsrv
# Build stdapi for x86
make docker-ext-stdapi-x86

All binaries are copied to the local output folder. All activites are done under the context of the current user even inside the container, so generated binaries should have the correct ownership.

Notes

  • The builds on Linux aren't not 100% clean yet, this is something we are working on. Expect to see a few warnings pop up.
  • We aren't yet able to build the python and powershell extensions thanks to some assembly magic and COM nonsense. This is something we hope to resolve in the near future.
  • These binaries might not be ABI compatible with binaries created with Visual Studio. There may be edge cases where memory is allocated in one location and freed in another, and hence if the allocators don't match you end up with pain and suffering. We'll be working on something to resolve this as well so that these binaries can be mixed and matched.

Testing

There is currently no automated testing for meterpreter, but we're working on it.

Once you've made changes and compiled a new .dll or .so, copy the contents of the output/ directory into your Metasploit Framework's data/meterpreter/ directory.

If you made any changes to metsrv.dll ensure that all extensions still load and function properly.

Debugging

Debugging wiki page

For debugging it helps to have two machines ready, one Windows (to be setup as described earlier to build meterpreter)
and one Ubuntu (ths is where you would have your framework dev envrionment), these can both be VMs.

git clone this repo onto your framework development machine and then map it as a network drive to the Windows machine.
Don't forget to run git submodule init && git submodule update.
Once that's done you can load the project up in Visual Studio as described in the "Building - Windows on Windows" section of the Readme.

To build in Debug mode all you need to do in the Visual Studio UI is select Debug from the configuration dropwdown (as opposed to Release or r7_Release).
Now select Win32 or x64 depending on whether you want to build for 32 or 64 bit meterpreter (or both) and then (re)build the solution.

Once you compile code, you need to link it to Framework so you can test it. Because other people at R7 are super smart, this is not so bad.
Go to a terminal in the payloads repo that can see both framework and payloads (I do this on my ubuntu machine)
Run make install-windows

text
$ make install-windows
Installing Windows payloads

All this does is copy the generated .dll's to metasploit-framework/data/meterpreter

Once the dlls are in place, you should get a warning about using local payloads when you generate a session:

text
WARNING: Local file /home/dwelch/dev/metasploit-framework/data/meterpreter/metsrv.x64.dll is being used
WARNING: Local files may be incompatible with the Metasploit Framework

Once that is in place, run debugView as admin on the machine running the payload. Be sure to select "Global_Win32" messages in the "Capture" dropdown box.

Overview (`java/javapayload/README.md`)

JavaPayload4Metasploit - Single payload loader class to be used in the Metasploit project

© 2010 Michael 'mihi' Schierl, <schierlm at users dot sourceforge dot net>

Introduction

The JavaPayloads
contain useful payloads written in pure Java. But they assume that the
attacker has a Java VM on their machine, as the builders and stage
handlers are written in Java. In addition, when creating a new payload
class that should reside in a signed jar, the jar has to be re-signed as
classes have changed.

In contrast, this package contains a single metasploit.Payload class
which is configured by a property file in the classpath (i. e. in the
same jar). As it is possible to add unsigned resources to a jar without
requiring to re-sign it, and as it is easy to manipulate zip/jar files
from Ruby, this makes it possible to leverage the powers of JavaPayload
from Metasploit which is written in Ruby and not in Java.

System requirements

Same as JavaPayload. JRE 1.2 on the victim machine is enough :-)

On the attacker machine, no Java at all is required.

How to use the *Payload* class.

The Payload class is a standard java main class (i. e. it has a
public static void main(String[]) method), so the most obvious way to
invoke it is putting it into a Jar file whose manifest's Main-Class
attribute is metasploit.Payload. The resuling jar can be started using
java -jar jarfile.jar. There are 3 example jars available that use
this technique; they are described later.

Alternatively, the main class can of course be called from other
classes, like metasploit.Payload.main(null);, as the arguments
parameter is ignored. Note that in a sandboxed environment the caller
needs to have all permissions, and also the Payload class has to be
loaded with all permissions. In case there is untrusted code in the
stack trace (but the direct caller has all permissions), the call has to
be wrapped in a
doPrivileged
call (like it is done in the several well known public exploits for
CVE-2008-5353).

Once loaded, the class will lookup a file called /metasploit.dat from
the class path and load it as a Property
file
(basically a text file with Name=value lines, but note that some
special characters need escaping). If the file cannot be found, default
values are used.

Depending on the property values (see below), the class will then
optionally write itself to disk and spawn a sub-process (once or several
times) to disconnect the payload from the calling process. All temporary
files will be deleted afterwards. (Even on Windows it is possible to
delete a running class file as technically, not the class file but the
Java VM is running).

After that, it will either listen on a port and accept a socket, connect
to an URL (using a protocol like HTTP or HTTPS), create an active socket
connection, or (for debugging purposes) just uses standard input and
standard output; in any case, the resulting input/output streams are
used for the staging

Once the stage is loaded, the streams are handed to the stage. Stages
may require optional parameters (a string) which can be given in the
property file.

When the stage quits, the payload class terminates and cleans up after
itself if needed.

Supported properties (and their default values)

`Spawn`(`=0`)

The number of java processes that should be spawned. 0 will run the
payload inside the original process, 1 will spawn once (to continue
running when the original process terminates), and 2 will spawn twice
(on certain popular operating systems it is impossible to obtain parent
process information if the parent process has already died).

`Executable`(`=`)

Points to an executable in the class path (next to metasploit.dat),
which will be extracted to a temporary directory (with original
filename), made executable (if needed by the OS) and executed. When this
option is present, no staging will be performed and all options
documented below are ignored.

`StageParameters`(`=`)

Additional parameters to be used by the stage, regardless whether it was
embedded or not. Only few stages support/require parameters.

`URL`(`=`)

Load the stage from this URL. The URL will be requested and the
resulting stream will be used for loading the stage classes from. As the
stage's output stream will discard all input, this is only useful with
stages (like Meterpreter) that can communicate via some other means back
to the attacker.

Note: If this option is given, LHOST and LPORT are ignored.

`LPORT`(`=4444`)

Port to listen on or to connect to (if LHOST is also set). If
explicitly set to 0, no connection will be made, but standard
input/output streams will be used instead.

`LHOST`(`=`)

Host to connect to. If not set, the payload will listen instead.

Staging protocol

The staging protocol is quite simple. All classes are sent uncompressed
(as they are inside the .jar file). Each class is prefixed by a 32-bit
big-endian size. After the last class, a size of 0 is sent. The classes
will be defined in the order they are sent (i. e. they can only refer to
classes defined before), and the last sent class will be loaded as a
stage.

In case of an embedded stage, no staging is used - the stream is
directly passed to the stage.

Supported stages (in alphabetical order)

The stages are original
JavaPayload stages
to make updates easier. All stages listed here can be used without
special "Java" tricks (like serialization or JDWP protocol), to easily
use them from Ruby.

`Meterpreter`

  • Stage classes
    javapayload.stage.Stage,
    com.metasploit.meterpreter.MemoryBufferURLConnection,
    com.metasploit.meterpreter.MemoryBufferURLStreamHandler,
    javapayload.stage.Meterpreter

  • Parameters
    Optional parameter NoRedirect for debugging.

  • Stage protocol
    Meterpreter protocol

Loader to load the Java version of Metasploit's own post-exploitation
toolkit.

`Shell`

  • Stage classes
    javapayload.stage.Stage, javapayload.stage.StreamForwarder,
    javapayload.stage.Shell

  • Parameters
    Not supported

  • Stage protocol
    Plain text

This stager loads /bin/sh on Unix systems and cmd.exe on Windows
systems, and else just behaves like the Exec stage.

Overview (`python/meterpreter/README.md`)

Python Meterpreter

Running unit tests:

text
# Only required if less than python 3.3
python -m pip install mock

# Run the tests
python -m unittest discover -v ./tests

Running a single test failure:

text
python3 ./tests/test_file.py class_name
python3 ./tests/test_file.py class_name.method_name

# For example
python3 ./tests/test_ext_server_stdapi.py TestExtServerStdApi.test_stdapi_net_config_get_interfaces_via_osx_ifconfig

# Or:
python3 -m unittest tests.test_ext_server_stdapi.ExtServerStdApiFileSystemTest.test_stdapi_fs_stat

To debug tests, add the following code snippet to enter into an interactive debugger at the calling stack frame:

python
import pdb; pdb.set_trace()

Overview (`c/meterpreter/source/tiny-regex-c/README.md`)

tiny-regex-c

This library is taken from https://github.com/kokke/tiny-regex-c/tree/2d306a5a71128853d18292e8bb85c8e745fbc9d0 - with changes to support null-bytes.

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →