Clients (like Armitage) interface with the Metasploit Framework through its Remote API. The Remote API is a way for clients to call functions in the Metasploit Framework’s RPC server. To pass different data types to/from the Metasploit Framework, clients use the MessagePack object serialization format.

Because clients may interface with the Metasploit Framework in this way, I’m sometimes asked… why can’t I connect Armitage to the Metasploit Framework RPC server directly? Worse, I’m sometimes asked for support by enterprising users who skipped the documentation and tried to wing setup on their own.

On this topic–if you want to stand up a team server, do consult the documentation. The process changed several times since I introduced this capability in Armitage. The correct way to stand up a server is to use the teamserver script that ships with the Armitage Linux package. This script starts msfrpcd, generates an SSL cert for you, and stands up the team server. To use it:

./teamserver [your external IP address] [shared password]

Now, let’s get back to the topic: Why do we have a team server?

The Metasploit Remote API is great, it allows one to query and execute modules. It also has an API to interact with a console. To build a collaboration environment on top of the Metasploit Framework, there are a few gaps. This is where the team server comes in. Armitage’s team server is a wrapper for the Metasploit RPC server. The team server adds functions for real-time communication, data sharing, and session sharing to the Metasploit Framework’s RPC server.

Here’s a little on what it does:

1. The team server is the center of Armitage’s ability to share sessions. Through it, I force any calls to meterpreter.read and meterpreter.write through a session multiplexer. This code adds Meterpreter commands to a queue with a tag. When the command executes, the multiplexer uses the tag to identify which client to send the output to. All clients that interact with Meterpreter, through the team server, do so with this multiplexing logic in place. This logic is what allows Cortana bots and Armitage/Cobalt Strike users to transparently share sessions.

2. Shell sessions are a different story. All commands in a shell session depend on the current working directory and I decided, early on, that it would be dangerous to transparently share a shell. For shell sessions, Armitage provides an API to request a lock on a session and an API to release the lock. If the Armitage client gets disconnected (for whatever reason), the team server automatically releases the client’s locks. If one of your teammates tries to interact with a shell that you own, they’ll get a message that states you are using the shell.

3. Early versions of the Metasploit Framework Remote API included calls to deal with the Metasploit Framework’s database. These calls were added by Ryan Linn for his DEF CON 19 talk, Multi-Player Metasploit. In November 2011, there was discussion about removing these calls altogether. The argument was that these calls were never documented in the Metasploit Remote API. To the best of my knowledge, if these calls are still present, they’re considered deprecated and could go  away at any time. To give Armitage clients access to the Metasploit Framework’s data, the team server emulates these database calls by talking to the database directly.

Emulating these database calls in the team server greatly improved Armitage’s performance. First, I saved a pass through Ruby on Rail’s active record cauldron of magic. I also save the CPU time to serialize data to MessagePack and unwrap it again. But, most importantly, controlling this code allowed me to design a scheme where the client communicates a hash of what it knows. The server uses the hash to decide if anything changed. If nothing changed, the data is not sent. This change made the Armitage team server infrastructure scale well to many clients with a lot of hosts.

4. The team server also provides a few random functions not present in the Metasploit Remote API. The team server offers a way to send files to or get files from the team server’s system. This is important as many Metasploit Framework modules have options that reference files local to the Metasploit Framework. The team server also provides calls that make real-time chat in the event log possible.

So, the next time you’re interested in connecting Armitage to a remote msfrpcd directly, beware that the team server exists for a reason. If you’d like to learn more about the team server, I published a paper a few years ago: Network Attack Collaboration: Sharing the Shell. The information in this blog post updates the information in the paper, but the paper still has a lot of good information.