metasploit-framework/lib/lab/README

This folder contains the libraries necessary to run the lab plugin, and can also be used in a standalone way to automate virtual machines.

Currently you will need to have this code running on a linux box, and your VMHost will likely need to be linux as well. If you're interested in porting it to windows, please contact jcran@metasploit.com. 

#########
CONCEPTS:
#########


Drivers: Drivers implement the underlying command for each vm (such as start/stop/revert)

Controllers: Controllers implement the commands which apply to all vms (such as listing all running vms)

Currently Supported:
	workstation (wraps vmrun command)
	workstation_vixr (uses the vixr gem from rhythmx)
	remote_workstation (wraps vmrun command on a remote host)
	virtualbox
	dynagen (underlying vm for GNS3 - cisco hardware)
Planned:
	qemu
	qemudo
	amazon
	others?

DEPENDENCIES:
  - whatever vm software is necessary for the driver you're using
  - net/ssh - the gem (net-ssh), not the msf library. Required to perform ssh_exec in the case tools are not installed on the device. Not necessary if tools are installed.
  - net/scp - the gem (net-scp). Required to copy files to/from the devices in the case that tools are not installed. Not necessary if tools are installed. 
  - vixr - required to use the workstation_vixr driver
  - fog - required to use the fog_amazon driver

###########
LAB PLUGIN:
###########

BACKGROUND:
  The lab plugin adds a number of commands which may be useful if you're interested in automating remote hosts with rc scripts. If you are testing an IPS / IDS, or determing if an exploit was successful, you'll need to have targets which can be easily started / reverted. The lab plugin provides those commands. 

USAGE:
  msf> load lab
  msf> lab_help
  msf> lab_load <path_to_lab_file> // see data/lab/test_targets.yml for an example
  msf> lab_start vm1
  msf> lab_snapshot vm1 emosheep  
  // do some stuff
  msf> lab_revert vm1 emosheep
  msf> lab_stop  vm1

###########
STANDALONE:
###########

BACKGROUND:
  The lab libraries add tons of useful functionality that isn't exposed through the lab plugin, such as the ability to run commands on hosts. This library can serve as an excellent base for more complex operations on a remote host as well. 

USAGE:
  You must first create a yaml file which describes your vm. See data/lab/test_targets.yml for an example.  

  require 'vm_controller'
  vm_controller = ::Lab::Controllers::VmController.new(YAML.load_file(lab_def)) 
  vm_controller['vm1'].start
  vm_controller['vm1'].snapshot("clean") 
  vm_controller['vm1'].run_command("rm /etc/resolv.conf")
  vm_controller['vm1'].open_uri("http://autopwn:8080")
  vm_controller['vm1'].revert("clean")