github/metasploit-payloads
1
Fork 0
mirror of https://github.com/rapid7/metasploit-payloads synced 2024-11-26 17:41:08 +01:00
Code Releases Activity
3b40f1abd0
metasploit-payloads/c/meterpreter
History
OJ 3b40f1abd0 Command refactor for clean shutdown + inline calls 
This work contains a bunch of changes around command dispatching. The
goals for this bit of work were to:

* Provide the ability for commands to be executed on the same thread as
  the server rather than always creating new threads and executing them on
  those threads.
* Have the means for _special_ commands, such as `exit` and `migrate` to
  shut down the server cleanly without having to rely on signalling across
  threads or by doing brutal thread termination via shared global handles.
  This should not only fix the dirty shutdown problem on Windows which
  leaves tasks dangling (or based on the prior attempt at fixing, crashing
  stuff as well), it should also help clean up the shutdown process in
  POSIX.

These changes hit a very important part of Meterpreter and so should be
reviewed with intense scrutnity. I expect this PR to garner a log of
critique and most likely a number of changes before being included in the
main line.

The `PacketDispatcher` was modified to include a new function pointer
called an `inline_handler`. This new member indicates that there's a
handler which should be invoked inline. While this sits alongside the
existing `handler`, they are actually mutually exclusive. If an
`inline_handler` is specified then the `handler` is ignored and it is
assumed that the command is intended to be handled inline. The signature
of the inline handler is different to the standard handler, and this is
why a new function pointer was added rather than a simple flag. Addition of
this parameter meant that the basic command structure changed, and that
obviously affects all of the extensions and their respective commands.
This changeset therefore updates each of those command declarations so
that they use the new macros that hide this detail.

Other things to be mindful of:

* This version of the code reads the command's `method` prior to invoking
  any other function, and after that the command itself is passed around to
  the threaded or non-threaded routes for invocation. An extra thread
  parameter was included as as result, and an overload for the
  `thread_create` function was added which supported this new parameter.
  This was named `thread_create3` because
  `thread_create_with_another_paramter` sounded a bit crap.
* The migration code, which originally had a `thread_kill` and an event
  wait once the new meterpreter session had been created, has been modified
  to not do any waiting at all. Instead it finishes execution as fast as
  possible and returns control to the server which should respond by
  shutting down in a clean way.
* Originally the code always attempted to call a command handler in the
  base command list and then, if found, would also call an "overload" in
  the extension commands list. From the investigation that I did, it
  appears that the overloaded methods did nothing in the base (they'd
  early out during invocation). As a result, the new way of doing things
  acts like a 'true' overload in that the extension commands are searched
  first, and if one is found this is the command that is executed. Any
  base commands with the same method name will not get executed. In the
  case where there is no extension command found, the base command list is
  then queried. If a command is found that command is instead invoked.
* The POSIX version still compiles cleanly, but I've never been able to
  build a version that runs on my machines. I'm not sure if there's a
  trick to getting POSIX builds to run, and if there is I don't know it.
  Whoever scrutinises this build should make sure that the POSIX version
  that they build can still run and (hopefully) exit cleanly.

I've added lots of documentation, but there's always room for improvement.

Hopefully this will fix the `*_tcp` side of Redmine 8438.

Bring on the feedback!
2013-10-17 22:36:49 +10:00
..
content Add doxygen, begin documenting, kitrap0d tidy 2013-09-26 14:29:46 +10:00
data/meterpreter Fix Makefile and add missing so2h.pl 2012-11-19 17:56:44 -06:00
output Make VisualStudio happy with an output dir 2013-03-20 14:10:22 -05:00
source Command refactor for clean shutdown + inline calls 2013-10-17 22:36:49 +10:00
tools Add doxygen, begin documenting, kitrap0d tidy 2013-09-26 14:29:46 +10:00
workspace Fix debug build of various components 2013-10-09 17:20:58 +10:00
.gitignore Update .gitignore to avoid conflict 2013-10-16 08:43:56 +10:00
.travis.yml Tell travis we need gcc-multilib 2013-03-20 10:33:59 -05:00
doxygen.cnf Fix exclude config to ignore unnecessary content 2013-10-17 10:39:13 +10:00
LICENSE Specify Rapid7 in appropriate location in LICENSE 2013-09-12 06:41:33 +10:00
make.bat Add doxygen, begin documenting, kitrap0d tidy 2013-09-26 14:29:46 +10:00
Makefile More Makefile clean up 2013-03-19 17:10:13 -05:00
README.md Whitespace 2013-10-16 20:03:47 -05:00

README.md

Current master branch: Meterpreter Build Status

meterpreter >

This is the new repository for the Meterpreter source, which was originally in the Metasploit Framework source.

Building - Windows

Meterpreter is now being built with Visual Studio 2012 Express for Desktop or any paid version of Visual Studio 2012. Earlier toolsets on Windows are no longer supported.

Visual Studio 2012 requires .NET 4.5 in order to run, and as a result isn't compatible with Windows XP due to the fact that .NET 4.5 will not run on Windows XP. However, this does not mean that Metepreter itself will not run on Windows XP, it just means that it's not possible to build it on Windows XP.

Visual Studio 2012 Express

In order to build successfully with this version of Visual Studio you must first make sure that the most recent updates have been applied. At the time of writing, the latest known update is Update 3. Without this update you won't be able to build.

To make sure you have the appropriate updates applied:

  1. Open Visual Studio 2012.
  2. Open the Tools menu and select Extensions and Updates
  3. Select the Updates item on the left side of the dialog box.
  4. Follow the prompts to install any updates that are found.

With those updates applied you should be ready to build Meterpreeter.

Running the Build

Open up a Visual Studio command prompt by selecting Developer Command Prompt for VS2012 from the Start menu. Alternatively you can run vcvars32.bat from an existing command line prompt, just make sure it's the VS2012 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 compiled binaries are written to the output/x86 and output/x64 folders.

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.

Building - POSIX

You will need:

  • A compiler toolchain (build-essential package on Ubuntu)
  • gcc-multilib, if you're building on a 64-bit machine
  • jam
  • wget

Meterpreter requires libpcap-1.1.1 and OpenSSL 0.9.8o sources, which it will download automatically during the build process. If for some reason, you cannot access the internet during build, you will need to:

Note that the 'depclean' and 'really-clean' make targets will delete these files.

Now you should be able to type make in the base directory, go make a sandwich, and come back to a working[1] meterpreter for Linux.

[1] For some value of "working." Meterpreter in POSIX environments is not considered stable. It does stuff, but expect occasional problems.

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. In POSIX you can do this automatically if metasploit-framework and meterpreter live in the same place by running make install

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

Creating Extensions

Creating extensions isn't complicated, but it's not simple either. In an attempt make the set up a little easier on the Meterpreter side, a new project called ext_server_bare has been created which is just the shell of a project which can be used as the starting point for your code. To use this as a template to create your own project, you can follow these steps.

Note: All paths listed here are relative to the root meterpreter folder where this document resides.

Pick a name for your extension, make sure it's something meaningful and short. For the sake of example, we'll create a new extension called splat. Once you have a cool an meaningful name, you can get your project going by doing the following:

  1. Create a new folder called workspace/ext_server_splat.
  2. Copy workspace/ext_server_bare/ext_server_bare.vcxproj to workspace/ext_server_bare/ext_server_splat.vcxproj
  3. Open workspace/ext_server_bare/ext_server_splat.vcxproj with a text editor and..
    • Replace all instances of BARE with SPLAT.
    • Replace all instances of bare with splat.
    • Search for the ProjectGuid property in the document. It looks like <ProjectGuid>{D3F39324-040D-4B1F-ADA9-762F16A120E6}</ProjectGuid>. When found, generate a new GUID for your project either using guidgen.exe or an online tool, and replace this GUID with your new GUID. Make sure you keep the curly braces.
  4. Create a new folder called source/extensions/splat.
  5. Copy source/extensions/bare/bare.c to source/extensions/splat/splat.c
  6. Copy source/extensions/bare/bare.h to source/extensions/splat/splat.h
  7. Open workspace/meterpreter.sln in Visual Studio 2012.
  8. Right-click on the solution item called Solution 'meterpreter' and select Add, then Existing Project....
  9. Browse to your new project's location at workspace/ext_server_splat and select ext_server_splat.vcxproj.
  10. The solution should automagically pick up your project configurations and wire them in where appropriate.
  11. Right-click, again, on the solution item and select Configuration Manager.
  12. In the resulting window, iterate through all combinations Active Solution Configuration and Active Solution Platform and make sure that:
    • Configuration matches with all the other extensions in each case.
    • Platform matches with all the other extensions in each case.
    • Build is checked in each case.
    • Deploy is NOT checked in each case.
  13. Modify the contents of splat.c and splat.h so that the file header commands are up to date, and that all references to bare have been removed.

At this point you're ready to start adding your extension's functionality.

Things to Remember

  • Your extension is set up to build both 32 and 64 bit versions. Make sure you're mindful of this when you are writing your code. All of the usual pitfalls apply when dealing with things like pointer sizes, value trunction, etc.
  • Make sure your extension builds correctly from the command line using make.
  • The outputs of your builds, when successful, are copied to output/x64 and output/x86.

Good luck!