Module: Msf::Post::SessionUpgrade

Includes:
Exploit::Remote::AutoCheck, Exploit::Retry
Defined in:
lib/msf/core/post/session_upgrade.rb

Overview

Shared orchestration logic for session upgrade modules. Provides LHOST resolution, handler lifecycle, payload generation, and wait-for-session polling. Consuming modules implement ‘execute_upgrade` for delivery.

Instance Method Summary collapse

Methods included from Exploit::Retry

#poll_until_truthy, #retry_until_truthy

Methods included from Exploit::Remote::AutoCheck

#exploit, included, #run

Instance Method Details

#execute_upgrade(lhost) ⇒ Object

Contract method — consuming modules must override this to deliver the payload to the target. Raises NotImplementedError if not implemented.

Raises:

  • (NotImplementedError) 


57
58
59
 
# File 'lib/msf/core/post/session_upgrade.rb', line 57

def execute_upgrade(lhost)
  raise NotImplementedError, 'Consuming modules must implement execute_upgrade(lhost)'
end

#generate_upgrade_payload(lhost, lport, payload_name) ⇒ String?

Generates raw stager bytes via the framework payload API.

Parameters:

  • lhost (String) —

    the listen host for the payload

  • lport (Integer, String) —

    the listen port for the payload

  • payload_name (String) —

    framework payload name (e.g. ‘windows/meterpreter/reverse_tcp’)

Returns:

  • (String, nil) —

    raw payload bytes on success, nil on failure



67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/msf/core/post/session_upgrade.rb', line 67

def generate_upgrade_payload(lhost, lport, payload_name)
  payload_obj = framework.payloads.create(payload_name)
  unless payload_obj
    print_error("Invalid payload: #{payload_name}")
    return nil
  end

  unless payload_obj.respond_to?(:generate_simple)
    print_error("Payload #{payload_name} does not support generate_simple")
    return nil
  end

  payload_obj.generate_simple('OptionStr' => "LHOST=#{lhost} LPORT=#{lport}")
end

#initialize(info = {}) ⇒ Object 



17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/msf/core/post/session_upgrade.rb', line 17

def initialize(info = {})
  super

  register_options(
    [
      Msf::OptAddressLocal.new('LHOST', [false, 'IP of host that will receive the connection from the payload.']),
      Msf::OptInt.new('LPORT', [true, 'Port for payload to connect to.', 4444]),
      Msf::OptBool.new('HANDLER', [true, 'Start an exploit/multi/handler to receive the connection.', true])
    ]
  )

  register_advanced_options(
    [
      Msf::OptInt.new('HANDLE_TIMEOUT', [true, 'How long to wait (in seconds) for the session to come back.', 30])
    ]
  )
end

#run_upgrade ⇒ Object

Orchestration entry point. Consuming modules call this from ‘run`.



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/msf/core/post/session_upgrade.rb', line 36

def run_upgrade
  lhost = resolve_lhost
  if lhost.nil?
    fail_with(Msf::Exploit::Failure::BadConfig, 'Unable to determine LHOST. Please set LHOST manually.')
  end

  existing_session_ids = framework.sessions.keys.map(&:to_i).to_set

  start_upgrade_handler(lhost) if datastore['HANDLER']

  execute_upgrade(lhost)

  if datastore['HANDLER']
    wait_for_upgrade_session(existing_session_ids)
  end
ensure
  cleanup_upgrade_handler
end