First iteration of the pivot menu for meterpreter

Author: OJ

lib/rex/post/meterpreter/packet_dispatcher.rb

@@ -561,16 +561,16 @@ def initialize_inbound_handlers
   def dispatch_inbound_packet(packet)
     handled = false
 
-    pivot = self.find_pivot(packet.session_guid)
+    pivot_session = self.find_pivot_session(packet.session_guid)
 
     tlv_enc_key = self.tlv_enc_key
-    tlv_enc_key = pivot.pivoted_session.tlv_enc_key if pivot
+    tlv_enc_key = pivot_session.pivoted_session.tlv_enc_key if pivot_session
 
     packet.from_r(tlv_enc_key)
 
     # Update our last reply time
     self.last_checkin = Time.now
-    pivot.pivoted_session.last_checkin = self.last_checkin if pivot
+    pivot_session.pivoted_session.last_checkin = self.last_checkin if pivot_session
 
     # If the packet is a response, try to notify any potential
     # waiters

lib/rex/post/meterpreter/pivot.rb

@@ -19,6 +19,10 @@ def initialize(session_class, display_name)
     self.session_class = session_class
     self.display_name = display_name
   end
+
+  def to_row
+    [self.id.unpack('H*')[0], display_name]
+  end
 end
 
 class Pivot
@@ -41,13 +45,13 @@ def request_handler(client, packet)
       if packet.method == 'core_pivot_session_new'
         session_guid = packet.get_tlv_value(TLV_TYPE_SESSION_GUID)
         listener_id = packet.get_tlv_value(TLV_TYPE_PIVOT_ID)
-        client.add_pivot(Pivot.new(client, session_guid, listener_id))
+        client.add_pivot_session(Pivot.new(client, session_guid, listener_id))
       elsif packet.method == 'core_pivot_session_died'
         session_guid = packet.get_tlv_value(TLV_TYPE_SESSION_GUID)
-        pivot = client.find_pivot(session_guid)
+        pivot = client.find_pivot_session(session_guid)
         if pivot
           pivot.pivoted_session.kill('Died')
-          client.remove_pivot(session_guid)
+          client.remove_pivot_session(session_guid)
         end
       end
       true

lib/rex/post/meterpreter/pivot_container.rb

@@ -16,16 +16,16 @@ module PivotContainer
   # Initializes the pivot association hash
   #
   def initialize_pivots
-    self.pivots = {}
+    self.pivot_sessions = {}
     self.pivot_listeners = {}
   end
 
   #
   # Adds a pivot to the container that is indexed by the pivoted
   # session guid.
   #
-  def add_pivot(pivot)
-    self.pivots[pivot.pivoted_session.session_guid] = pivot
+  def add_pivot_session(pivot)
+    self.pivot_sessions[pivot.pivoted_session.session_guid] = pivot
   end
 
   def add_pivot_listener(listener)
@@ -35,8 +35,8 @@ def add_pivot_listener(listener)
   #
   # Looks up a pivot instance based on its pivoted session guid.
   #
-  def find_pivot(pivot_session_guid)
-    return self.pivots[pivot_session_guid]
+  def find_pivot_session(pivot_session_guid)
+    return self.pivot_sessions[pivot_session_guid]
   end
 
   def find_pivot_listener(listener_id)
@@ -46,24 +46,24 @@ def find_pivot_listener(listener_id)
   #
   # Removes a pivot based on its pivoted session guid.
   #
-  def remove_pivot(pivot_session_guid)
-    return self.pivots.delete(pivot_session_guid)
+  def remove_pivot_session(pivot_session_guid)
+    return self.pivot_sessions.delete(pivot_session_guid)
   end
 
   def remove_pivot_listener(listener_id)
     return self.pivot_listeners.delete(listener_id)
   end
 
   #
-  # The hash of pivots.
+  # The hash of pivot sessions.
   #
-  attr_reader :pivots
+  attr_reader :pivot_sessions
 
   attr_reader :pivot_listeners
 
 protected
 
-  attr_writer :pivots # :nodoc:
+  attr_writer :pivot_sessions # :nodoc:
 
   attr_writer :pivot_listeners # :nodoc:
 

lib/rex/post/meterpreter/ui/console/command_dispatcher/core.rb

@@ -83,6 +83,8 @@ def commands
       if client.passive_service && client.sock.type? == 'tcp-ssl'
         c['ssl_verify'] = 'Modify the SSL certificate verification setting'
       end
+
+      c['pivot'] = 'Manage pivot listeners'
     end
 
     if client.platform == 'windows' || client.platform == 'linux'
@@ -119,6 +121,151 @@ def name
     'Core'
   end
 
+  @@pivot_opts = Rex::Parser::Arguments.new(
+    '-t' => [true, 'Pivot listener type'],
+    '-i' => [true, 'Identifier of the pivot to remove'],
+    '-l' => [true, 'Host address to bind to (if applicable)'],
+    '-n' => [true, 'Name of the listener entity (if applicable)'],
+    '-a' => [true, 'Architecture of the stage to generate'],
+    '-p' => [true, 'Platform of the stage to generate'],
+    '-h' => [false, 'View help']
+  )
+
+  @@pivot_supported_archs = [ARCH_X64, ARCH_X86]
+  @@pivot_supported_platforms = ['windows']
+
+  def cmd_pivot_help
+    print_line('Usage: pivot <list|add|remove> [options]')
+    print_line
+    print_line('Manage pivot listeners on the target.')
+    print_line
+    print_line(@@pivot_opts.usage)
+    print_line
+    print_line('Supported pivot types:')
+    print_line('     - pipe (using named pipes over SMB)') 
+    print_line('Supported arhiectures:')
+    @@pivot_supported_archs.each do |a|
+      print_line('     - ' + a)
+    end
+    print_line('Supported platforms:')
+    print_line('     - windows')
+    print_line
+    print_line("eg.    pivot add -t pipe -l 192.168.0.1 -n msf-pipe -a #{@@pivot_supported_archs.first} -p windows")
+    print_line("       pivot list")
+    print_line("       pivot remove -i 1")
+    print_line
+  end
+
+  def cmd_pivot(*args)
+    if args.length == 0 || args.include?('-h')
+      cmd_pivot_help
+      return true
+    end
+
+    opts = {}
+    @@pivot_opts.parse(args) { |opt, idx, val|
+      case opt
+      when '-t'
+        opts[:type] = val
+      when '-i'
+        opts[:guid] = val
+      when '-l'
+        opts[:lhost] = val
+      when '-n'
+        opts[:name] = val
+      when '-a'
+        opts[:arch] = val
+      when '-p'
+        opts[:platform] = val
+      end
+    }
+
+    # first parameter is the command
+    case args[0]
+    when 'remove', 'del', 'delete', 'rm'
+      unless opts[:guid]
+        print_error('Pivot listener ID must be specified (-i)')
+        return false
+      end
+
+      unless opts[:guid] =~ /^[0-9a-f]{32}/i && opts[:guid].length == 32
+        print_error("Invalid pivot listener ID: #{opts[:guid]}")
+        return false
+      end
+
+      listener_id = [opts[:guid]].pack('H*')
+      unless client.find_pivot_listener(listener_id)
+        print_error("Unknown pivot listener ID: #{opts[:guid]}")
+        return false
+      end
+
+      Pivot.remove_listener(client, listener_id)
+      print_good("Successfully removed pivot: #{opts[:guid]}")
+    when 'list', 'show', 'print'
+      tbl = Rex::Text::Table.new(
+        'Header'  => 'Currently active pivot listeners',
+        'Indent'  => 4,
+        'Columns' => ['Id', 'Detail'])
+
+      client.pivot_listeners.each do |k, v|
+        tbl << v.to_row
+      end
+      print_line("\n#{tbl}\n")
+    when 'add'
+      unless opts[:type]
+        print_error('Pivot type must be specified (-t)')
+        return false
+      end
+
+      unless opts[:arch]
+        print_error('Architecture must be specified (-a)')
+        return false
+      end
+      unless @@pivot_supported_archs.include?(opts[:arch])
+        print_error("Unknown or unsupported architecture: #{opts[:arch]}")
+        return false
+      end
+
+      unless opts[:platform]
+        print_error('Platform must be specified (-p)')
+        return false
+      end
+      unless @@pivot_supported_platforms.include?(opts[:platform])
+        print_error("Unknown or unsupported platform: #{opts[:platform]}")
+        return false
+      end
+
+      # currently only one pivot type supported, more to come we hope
+      case opts[:type]
+      when 'pipe'
+        pivot_add_named_pipe(opts)
+      else
+        print_error("Unknown pivot type: #{opts[:type]}")
+        return false
+      end
+    else
+      print_error("Unknown command: #{args[0]}")
+    end
+  end
+
+  def pivot_add_named_pipe(opts)
+    unless opts[:lhost]
+      print_error('Pipe host must be specified (-l)')
+      return false
+    end
+
+    unless opts[:name]
+      print_error('Pipe name must be specified (-n)')
+      return false
+    end
+
+    # reconfigure the opts so that they can be passed to the setup function
+    opts[:pipe_host] = opts[:lhost]
+    opts[:pipe_name] = opts[:name]
+    Pivot.create_named_pipe_listener(client, opts)
+    print_good("Successfully created #{opts[:type]} pivot.")
+  end
+
   def cmd_sessions_help
     print_line('Usage: sessions <id>')
     print_line