Class: Msf::Plugin::Lab::LabCommandDispatcher

Inherits:
Object
  • Object
show all
Includes:
Ui::Console::CommandDispatcher
Defined in:
plugins/lab.rb

Instance Attribute Summary collapse

Attributes included from Ui::Console::CommandDispatcher

#driver

Attributes included from Rex::Ui::Text::DispatcherShell::CommandDispatcher

#shell, #tab_complete_items

Instance Method Summary collapse

Methods included from Ui::Console::CommandDispatcher

#active_module, #active_module=, #active_session, #active_session=, #build_range_array, #docs_dir, #framework, #load_config, #log_error, #remove_lines

Methods included from Rex::Ui::Text::DispatcherShell::CommandDispatcher

#cmd_help, #cmd_help_help, #cmd_help_tabs, #deprecated_cmd, #deprecated_commands, #deprecated_help, #docs_dir, #help_to_s, included, #print, #print_error, #print_good, #print_line, #print_status, #print_warning, #tab_complete_directory, #tab_complete_filenames, #tab_complete_generic, #tab_complete_source_address, #unknown_command, #update_prompt

Constructor Details

#initialize(driver) ⇒ LabCommandDispatcher

Returns a new instance of LabCommandDispatcher.



17
18
19
20
21
22
23
24
25
26
27
28
29
# File 'plugins/lab.rb', line 17

def initialize(driver)
  super(driver)
  @controller = nil

  #
  # Require the lab gem, but fail nicely if it's not there.
  #
  begin
    require 'lab'
  rescue LoadError
    raise "WARNING: Lab gem not found, Please 'gem install lab'"
  end
end

Instance Attribute Details

#controllerObject

Returns the value of attribute controller.



15
16
17
# File 'plugins/lab.rb', line 15

def controller
  @controller
end

Instance Method Details

#cmd_lab_browse_to(*args) ⇒ Object



402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
# File 'plugins/lab.rb', line 402

def cmd_lab_browse_to(*args)
  return lab_usage if args.empty?

  uri = args[args.count - 1]
  if args[0] == 'all'
    print_line "Opening: #{uri} on all vms."
    @controller.each do |vm|
      if vm.running?
        print_line "#{vm.hostname} opening to uri: #{uri}."
        vm.open_uri(uri)
      end
    end
  else
    args[0..-2].each do |name_arg|
      next unless @controller.includes_hostname? name_arg

      if @controller[name_arg].running?
        print_line "#{name_arg} opening to uri: #{uri}."
        @controller[name_arg].open_uri(uri)
      end
    end
  end
end

#cmd_lab_clear(*_args) ⇒ Object



135
136
137
# File 'plugins/lab.rb', line 135

def cmd_lab_clear(*_args)
  @controller.clear!
end

#cmd_lab_help(*args) ⇒ Object



455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
# File 'plugins/lab.rb', line 455

def cmd_lab_help(*args)
  if args.empty?
    commands.each_pair { |k, v| print_line format("%-#{longest_cmd_size}s - %s", k, v) }
  else
    args.each do |c|
      if extended_help[c] || commands[c]
        print_line format("%-#{longest_cmd_size}s - %s", c, extended_help[c] || commands[c])
      else
        print_error "Unknown command '#{c}'"
      end
    end
  end

  print_line
  print_line "In order to use this plugin, you'll want to configure a .yml lab file"
  print_line 'You can find an example in data/lab/test_targets.yml'
  print_line
end

#cmd_lab_load(*args) ⇒ Object

Regular Lab Commands



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
# File 'plugins/lab.rb', line 68

def cmd_lab_load(*args)
  return lab_usage unless args.count == 1

  res = args[0]
  good_res = nil
  if (File.file?(res) && File.readable?(res))
    # then the provided argument is an absolute path and is gtg.
    good_res = res
  elsif [
    ::Msf::Config.data_directory + File::SEPARATOR + 'lab',
    # there isn't a user_data_directory, but could use:
    # ::Msf::Config.user_plugins_directory + File::SEPARATOR + "lab"
  ].each do |dir|
          res_path = dir + File::SEPARATOR + res
          if (File.file?(res_path) && File.readable?(res_path))
            good_res = res_path
            break
          end
        end
    # let's check to see if it's in the data/lab dir (like when tab completed)
  end
  if good_res
    @controller.from_file(good_res)
  else
    print_error("#{res} is not a valid lab definition file (.yml)")
  end
end

#cmd_lab_load_config(*args) ⇒ Object



160
161
162
163
164
165
166
167
168
169
170
171
172
173
# File 'plugins/lab.rb', line 160

def cmd_lab_load_config(*args)
  return lab_usage if args.empty?

  if args[0] =~ /^remote_/
    return lab_usage unless args.count == 3

    ## Expect a username & password
    @controller.build_from_config(args[0], args[1], args[2])
  else
    return lab_usage unless args.count == 1

    @controller.build_from_config(args[0])
  end
end

#cmd_lab_load_dir(*args) ⇒ Object



129
130
131
132
133
# File 'plugins/lab.rb', line 129

def cmd_lab_load_dir(*args)
  return lab_usage unless args.count == 2

  @controller.build_from_dir(args[0], args[1], true)
end

#cmd_lab_load_running(*args) ⇒ Object



145
146
147
148
149
150
151
152
153
154
155
156
157
158
# File 'plugins/lab.rb', line 145

def cmd_lab_load_running(*args)
  return lab_usage if args.empty?

  if args[0] =~ /^remote_/
    return lab_usage unless args.count == 3

    ## Expect a username & password
    @controller.build_from_running(args[0], args[1], args[2])
  else
    return lab_usage unless args.count == 1

    @controller.build_from_running(args[0])
  end
end

#cmd_lab_load_tabs(str, words) ⇒ Object

Tab completion for the lab_load command



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
# File 'plugins/lab.rb', line 99

def cmd_lab_load_tabs(str, words)
  tabs = []
  # return tabs if words.length > 1
  if (str && str =~ (/^#{Regexp.escape(File::SEPARATOR)}/))
    # then you are probably specifying a full path so let's just use normal file completion
    return tab_complete_filenames(str, words)
  elsif (!(words[1]) || !words[1].match(%r{^/}))
    # then let's start tab completion in the data/lab directory
    begin
      [
        ::Msf::Config.data_directory + File::SEPARATOR + 'lab',
        # there isn't a user_data_directory, but could use:
        # ::Msf::Config.user_plugins_directory + File::SEPARATOR + "lab"
      ].each do |dir|
        next if !::File.exist? dir

        tabs += ::Dir.new(dir).find_all do |e|
          path = dir + File::SEPARATOR + e
          ::File.file?(path) and File.readable?(path)
        end
      end
    rescue Exception
    end
  else
    tabs += tab_complete_filenames(str, words)
  end

  return tabs
end

#cmd_lab_reset(*args) ⇒ Object



293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
# File 'plugins/lab.rb', line 293

def cmd_lab_reset(*args)
  return lab_usage if args.empty?

  if args[0] == 'all'
    print_line 'Resetting all lab vms.'
    @controller.each(&:reset)
  else
    args.each do |arg|
      if @controller.includes_hostname?(arg) && @controller.find_by_hostname(arg).running?
        print_line "Resetting lab vm #{arg}."
        @controller.find_by_hostname(arg).reset
      end
    end
  end
end

#cmd_lab_revert(*args) ⇒ Object



327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
# File 'plugins/lab.rb', line 327

def cmd_lab_revert(*args)
  return lab_usage if args.count < 2

  snapshot = args[args.count - 1]

  if args[0] == 'all'
    print_line "Reverting all lab vms to snapshot: #{snapshot}."
    @controller.each { |vm| vm.revert_snapshot(snapshot) }
  else
    args[0..-2].each do |name_arg|
      next unless @controller.includes_hostname? name_arg

      print_line "Reverting #{name_arg} to snapshot: #{snapshot}."
      @controller[name_arg].revert_snapshot(snapshot)
    end
  end
end

#cmd_lab_run_command(*args) ⇒ Object



345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
# File 'plugins/lab.rb', line 345

def cmd_lab_run_command(*args)
  return lab_usage if args.empty?

  command = args[args.count - 1]
  if args[0] == 'all'
    print_line "Running command #{command} on all vms."
    @controller.each do |vm|
      if vm.running?
        print_line "#{vm.hostname} running command: #{command}."
        vm.run_command(command)
      end
    end
  else
    args[0..-2].each do |name_arg|
      next unless @controller.includes_hostname? name_arg

      if @controller[name_arg].running?
        print_line "#{name_arg} running command: #{command}."
        @controller[name_arg].run_command(command)
      end
    end
  end
end

#cmd_lab_save(*args) ⇒ Object



139
140
141
142
143
# File 'plugins/lab.rb', line 139

def cmd_lab_save(*args)
  return lab_usage if args.empty?

  @controller.to_file(args[0])
end

#cmd_lab_search(*args) ⇒ Object



196
197
198
199
200
201
202
203
204
205
206
207
208
# File 'plugins/lab.rb', line 196

def cmd_lab_search(*args)
  if args.empty?
    hlp_print_lab
  else
    args.each do |arg|
      print_line "Searching for vms with hostname matching #{arg}"
      @controller.each do |vm|
        print_line "checking to see #{vm.hostname} matches #{arg}"
        print_line "#{vm.hostname} matched #{arg}" if vm.hostname =~ Regexp.new(arg)
      end
    end
  end
end

#cmd_lab_search_tags(*args) ⇒ Object



210
211
212
213
214
215
216
217
218
219
220
221
222
# File 'plugins/lab.rb', line 210

def cmd_lab_search_tags(*args)
  if args.empty?
    hlp_print_lab
  else
    args.each do |arg|
      print_line "Searching for vms with tags matching #{arg}"
      @controller.each do |vm|
        print_line "checking to see #{vm.hostname} is tagged #{arg}"
        print_line "#{vm.hostname} tagged #{arg}" if vm.tagged?(arg)
      end
    end
  end
end

#cmd_lab_show(*args) ⇒ Object

Commands for dealing with a currently-loaded lab



178
179
180
181
182
183
184
185
186
187
188
189
190
# File 'plugins/lab.rb', line 178

def cmd_lab_show(*args)
  if args.empty?
    hlp_print_lab
  else
    args.each do |name|
      if @controller.includes_hostname? name
        print_line @controller[name].to_yaml
      else
        print_error "Unknown vm '#{name}'"
      end
    end
  end
end

#cmd_lab_show_running(*_args) ⇒ Object



192
193
194
# File 'plugins/lab.rb', line 192

def cmd_lab_show_running(*_args)
  hlp_print_lab_running
end

#cmd_lab_snapshot(*args) ⇒ Object



309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
# File 'plugins/lab.rb', line 309

def cmd_lab_snapshot(*args)
  return lab_usage if args.count < 2

  snapshot = args[args.count - 1]

  if args[0] == 'all'
    print_line "Snapshotting all lab vms to snapshot: #{snapshot}."
    @controller.each { |vm| vm.create_snapshot(snapshot) }
  else
    args[0..-2].each do |name_arg|
      next unless @controller.includes_hostname? name_arg

      print_line "Snapshotting #{name_arg} to snapshot: #{snapshot}."
      @controller[name_arg].create_snapshot(snapshot)
    end
  end
end

#cmd_lab_start(*args) ⇒ Object



224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
# File 'plugins/lab.rb', line 224

def cmd_lab_start(*args)
  return lab_usage if args.empty?

  if args[0] == 'all'
    @controller.each do |vm|
      print_line "Starting lab vm #{vm.hostname}."
      if !vm.running?
        vm.start
      else
        print_line "Lab vm #{vm.hostname} already running."
      end
    end
  else
    args.each do |arg|
      next unless @controller.includes_hostname? arg

      vm = @controller.find_by_hostname(arg)
      if !vm.running?
        print_line "Starting lab vm #{vm.hostname}."
        vm.start
      else
        print_line "Lab vm #{vm.hostname} already running."
      end
    end
  end
end

#cmd_lab_stop(*args) ⇒ Object



251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
# File 'plugins/lab.rb', line 251

def cmd_lab_stop(*args)
  return lab_usage if args.empty?

  if args[0] == 'all'
    @controller.each do |vm|
      print_line "Stopping lab vm #{vm.hostname}."
      if vm.running?
        vm.stop
      else
        print_line "Lab vm #{vm.hostname} not running."
      end
    end
  else
    args.each do |arg|
      next unless @controller.includes_hostname? arg

      vm = @controller.find_by_hostname(arg)
      if vm.running?
        print_line "Stopping lab vm #{vm.hostname}."
        vm.stop
      else
        print_line "Lab vm #{vm.hostname} not running."
      end
    end
  end
end

#cmd_lab_suspend(*args) ⇒ Object



278
279
280
281
282
283
284
285
286
287
288
289
290
291
# File 'plugins/lab.rb', line 278

def cmd_lab_suspend(*args)
  return lab_usage if args.empty?

  if args[0] == 'all'
    @controller.each(&:suspend)
  else
    args.each do |arg|
      if @controller.includes_hostname?(arg) && @controller.find_by_hostname(arg).running?
        print_line "Suspending lab vm #{arg}."
        @controller.find_by_hostname(arg).suspend
      end
    end
  end
end

#cmd_lab_upload(*args) ⇒ Object

Command: lab_upload [vmids] [from] [to]

Description: Uploads a file to the guest(s)

Quirks: Pass “all” as a vmid to have it operate on all vms.



376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
# File 'plugins/lab.rb', line 376

def cmd_lab_upload(*args)
  return lab_usage if args.empty?
  return lab_usage if args.count < 3

  local_path = args[args.count - 2]
  vm_path = args[args.count - 1]

  if args[0] == 'all'
    @controller.each do |vm|
      if vm.running?
        print_line "Copying from #{local_path} to #{vm_path} on #{vm.hostname}"
        vm.copy_to_guest(local_path, vm_path)
      end
    end
  else
    args[0..-2].each do |vmid_arg|
      next unless @controller.includes_hostname? vmid_arg

      if @controller[vmid_arg].running?
        print_line "Copying from #{local_path} to #{vm_path} on #{vmid_arg}"
        @controller[vmid_arg].copy_to_guest(local_path, vm_path)
      end
    end
  end
end

#commandsObject

Returns the hash of commands supported by this dispatcher.



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
# File 'plugins/lab.rb', line 34

def commands
  {
    'lab_help' => "lab_help <lab command> - Show that command's description.",
    'lab_show' => 'lab_show - show all vms in the lab.',
    'lab_search' => 'lab_search - search local vms in the lab.',
    'lab_search_tags' => 'lab_search_tag - search local vms in the lab.',
    # "lab_search_remote" => "lab_search_remote - search remote vms in the lab.",
    'lab_show_running' => 'lab_show_running - show running vms.',
    'lab_load' => 'lab_load [file] - load a lab definition from disk.',
    'lab_save' => 'lab_save [filename] - persist a lab definition in a file.',
    'lab_load_running' => 'lab_load_running [type] [user] [host] - use the running vms to create a lab.',
    'lab_load_config' => 'lab_load_config [type] [user] [host] - use the vms in the config to create a lab.',
    'lab_load_dir' => 'lab_load_dir [type] [directory] - create a lab from a specified directory.',
    'lab_clear' => 'lab_clear - clear the running lab.',
    'lab_start' => 'lab_start [vmid+|all] start the specified vm.',
    'lab_reset' => 'lab_reset [vmid+|all] reset the specified vm.',
    'lab_suspend' => 'lab_suspend [vmid+|all] suspend the specified vm.',
    'lab_stop' => 'lab_stop [vmid+|all] stop the specified vm.',
    'lab_revert' => 'lab_revert [vmid+|all] [snapshot] revert the specified vm.',
    'lab_snapshot' => 'lab_snapshot [vmid+|all] [snapshot] snapshot all targets for this exploit.',
    'lab_upload' => 'lab_upload [vmid] [local_path] [remote_path] upload a file.',
    'lab_run_command' => 'lab_run_command [vmid+|all] [command] run a command on all targets.',
    'lab_browse_to' => 'lab_browse_to [vmid+|all] [uri] use the default browser to browse to a uri.'
  }
end

#extended_helpObject

No extended help yet, but this is where more detailed documentation on particular commands would live. Key is command, (not cmd_command), value is the documentation.



437
438
439
440
441
442
# File 'plugins/lab.rb', line 437

def extended_help
  {
    'lab_fake_cmd' => "This is a fake command. It's got its own special docs." +
      (' ' * longest_cmd_size) + 'It might be long so so deal with formatting somehow.'
  }
end

#lab_usageObject

Map for usages



445
446
447
448
449
450
451
452
453
# File 'plugins/lab.rb', line 445

def lab_usage
  caller[0][/`cmd_(.*)'/]
  cmd = Regexp.last_match(1)
  if extended_help[cmd] || commands[cmd]
    cmd_lab_help cmd
  else # Should never really get here...
    print_error "Unknown command. Try 'help'"
  end
end

#longest_cmd_sizeObject

Commands for help



430
431
432
# File 'plugins/lab.rb', line 430

def longest_cmd_size
  commands.keys.map(&:size).max
end

#nameObject



60
61
62
# File 'plugins/lab.rb', line 60

def name
  'Lab'
end