New way to add DLLs to railgun

If you are reading this, I probably submitted to the Metasploit repository directly for the first time! That's right, I have commit rights now. My first round of changes closed bug #3073 "Railgun DLL cache/definition loader needs a rewrite." This lead me to rewrite large chunks of code including how DLLs are defined and handled behind the scenes. This tutorial is a complement to those changes.

And here we go.

If the DLL you want to access is shipped with Windows and its API remains somewhat consistent, then you should NEVER load the DLL/Functions on the fly. Instead, benefit everyone and expand Railgun itself by adding support at a framework-level. This practice leads to better performance (the DLLs/Functions will be cached), cleaner code (the definitions will have their own place), and greater accessibility (the DLLs will be accessible wherever you can type client.railgun). In this blog post, I will show you how.

In our example we will be adding support for the DLL ws2_32.

1. Create a file to contain your definition class

DLL definition classes can be found in lib/rex/post/meterpreter/extensions/stdapi/railgun/def. The file name should be "def_" followed by your DLL's name. In our example, our file would be lib/rex/post/meterpreter/extensions/stdapi/railgun/def/def_ws2_32.rb

2. Declare the definition class

The class name should start with Def_ followed by your DLL name (case sensitive, underscores). In our case we would end up with thhe following code:

module Rex
module Post
module Meterpreter
module Extensions
module Stdapi
module Railgun
module Def
class Def_ws2_32
end; end; end; end; end; end; end

3. Add the create_dll method

The create_dll class method is responsible for returning a fully functional DLL. Within it, we will have the oppertunity to specify the DLL's path, what constants should be defined, and what functions will be available.

3.1 declare the method

def self.create_dll(dll_path = 'ws2_32')
end

3.2 Instantiate the DLL

dll = DLL.new(dll_path, ApiConstants.manager)

3.3 Add some functions

dll.add_function('WSACleanup', 'DWORD',[])

3.5 Love it!

def self.create_dll(dll_path = 'ws2_32')
dll = DLL.new(dll_path, ApiConstants.manager)
dll.add_function('WSACleanup', 'DWORD',[])
return dll
end

4. Make the DLL available

Making the DLL available to be used (client.railgun.my_dll_name) is straightforward. Open railgun.rb and add the name of your dll to BUILTIN_DLLS. Be sure to read the comment.

5. Enjoy!

Yep, that was it.