Last updated at Mon, 25 Sep 2017 19:25:19 GMT

Taking Care of Universal Business: the Handler's Tale

With a few exceptions, payloads have to have a handler. That's the guy who waits with the car while your exploit runs into the liquor store.

To run an exploit module, we have to select and configure a payload first. In some cases, Metasploit can do this for you automatically, by just guessing that you probably wanted the best payload for the target platform and architecture. Once the payload is set up, we have to have a way to talk to it -- that's the handler. For a reverse style payload like windows/meterpreter/reverse_tcp, Metasploit will open a listening socket on the attacker machine and wait for connections from the payload. For bind, style where the payload listens on the victim machine, Metasploit starts a loop attempting to connect to that listener. (When we talk about Metasploit payloads, we always call the payload the server and msfconsole the client, regardless of which direction the TCP session is going.)

Once the connection is established, two things can happen. First, if the handler is expecting a stageless payload, msfconsole sets up an interactive session that you can use to control the payload, whether that's a socket <-> terminal passthrough like a raw shell connection or the full-fledged client that meterpreter needs. If, on the other hand, the payload is staged, the handler needs to transmit more code for the first stage to read and run. When that's done, everything proceeds the same as for a stageless payload.

Either way, it is very important that the payload and the handler have matching settings. If a staged payload expects x86 shellcode and the handler thinks it is talking to a MIPS payload, the second stage will crash and you'll lose your shell despite having successfully achieved code execution. Similarly, if the payload is staged and the handler is stageless, the server will either a) wait forever for shellcode that will never come or b) it will take whatever you type into the console as shellcode, which will certainly fail unless your binary typing skills are significantly better than mine.

You usually don't have to worry too much about any of this, because everything is taken care of for you automatically when you type run. Where it gets complicated is when you need to have multiple payloads or run multiple exploits using the same listener port. To accomplish that, it is often useful to have a handler independent of an exploit. Metasploit has exploit/multi/handler, which is a special exploit module that isn't really an exploit, for exactly this purpose. All it does is allow you to configure a payload and run the handler for it.

This week's update introduces a new command, handler, which does all the same work as multi/handler (and in fact runs multi/handler in the background) all from a single command. This means you no longer have to move away from the context of the exploit you're working in to set up a handler.

Having independent handlers is also super useful for when you want create a payload outside of the current msfconsole.

The perfect example here is when using something like veil to generate executables that bypass antivirus for manual delivery. When the payload is not associated with an exploit, you have to tell Metasploit the details that it would normally have from the exploit's settings.

Unfortunately, there are a couple of disadvantages with this. First, it's error-prone. If the settings in your payload and handler don't match, like I mentioned above, things will crash and you'll be missing out on shells. Second, it requires multiple listening ports if you want to be able to handle multiple platforms or architectures. Sometimes that's not a big deal, but when you're dealing with organizations that have strong egress filtering, it can become an insurmountable hassle.

This week's update makes all reverse HTTP handlers use a single handler. This means you can run multi/handler (or the new handler command) to set up a single HTTP handler on port 443, with a real CA-signed certificate, and point staged and/or stageless meterpreters for any of the supported platforms all at the same place.

This isn't perfect yet. Native Linux Meterpreter and its up and coming replacement, Mettle, don't yet support HTTP, so they can't yet take advantage of the new handler. TCP payloads can theoretically do something similar, but the implementation will require changing the way stagers work, which is always challenging because of the extreme space restrictions they have to operate under and the fact that changing the staging protocol will make all existing stagers stop working. If you have ideas for how to accomplish that without breaking everyone's existing payloads, I'd love to hear them.

New Modules

Auxiliary and post modules (1 new)

Get it

As always, you can update to the latest Metasploit Framework with msfupdate and you can get more details on the changes since the last blog post from GitHub:

To install fresh, check out the open-source-only Nightly Installers, or the binary installers which also include the commercial editions.