Debugging Metasploit with Visual Studio Code on Linux

The last couple of months I have been focusing on learning to develop and use the Metasploit framework. As probably most of the readers know by now, the Metasploit framework is an excellent tool to develop and maintain your exploits mostly because most of the tools are already there and you don't have to reinvent the wheel. On the other hand, if you want to use it for the development, it is important to learn its internals.

Setting up the debugging environment

Figure 1: Debug screen in VS CodeThis post focusses on debugging the Metasploit console process within the VS Code, which is my IDE of choice for both Windows and Linux development, but the approach can be used with other IDEs and on the other Ruby applications as well. While it is easy to do some simple debugging with printing the status messages to the screen, there are times when Metasploit core calls fail and the developer is not sure why that is happening. In this case, it is much better to directly jump into the debugging instead of even considering littering the core code with the output statements.

The problem with VS Code debugging is it has its integrated console, which is usually not suitable for more UI-intensive console applications like Metasploit CLI. The approach to take here is to connect to a remote debugging process. Although this sounds really involved, it encompasses three easy steps.

  1. Install Ruby tools for VS Code. This will give you the ability to set the breakpoints directly in VS Code UI and to use all its other available debugging tools. Just make sure to properly set up the debugging parameters, especially the executable file name.

  2. Run the process you want to debug and allow it to be attached to. It is as easy as opening the console and using the following command: rdebug-ide --host --port 1234 -- /usr/bin/msfconsole. The executable won't start immediately, but will instead wait for the debugger client to attach. You can use loopback address for local debugging. The default listening port is 1234.

  3. In VS Code, select the "Listen for rdebug-ide" debug option to attach to the debugging server. To do this, click on the debugger icon on the left sidebar and then select the option from the drop-down to the right of the "Run" green arrow button. You can set up any custom settings by pressing on the "Cog" options button. You can follow the advanced steps described here if you have additional needs.

Figure 2: Ruby debugger server running a Metasploit instanceThe only thing that's left is to set up the breakpoints in the VS Code window and run the debugger. After the debugging is started, the terminal window where the debugging server was started will start showing the debugged program's UI changes. After some time the breakpoints will get hit and you can continue debugging at will.


This approach to debugging Metasploit (or any other Ruby program for that matter) is much more versatile than printing the debugging messages from the module to the console as you can usually step into the Metasploit's core methods and see exactly what is going on under the hood. You also avoid having to restart the Metasploit application in the case when debugging MSF Core calls with console output messages (an approach that novice people usually take I would never recommend).

Debugging, Metasploit, Ruby, VS Code