Changeset 811

Show
Ignore:
Timestamp:
08/31/07 17:30:48 (1 year ago)
Author:
kindlund
Message:

Completed documentation of VM::Clone.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • honeyclient/branches/exp/kindlund-dynamic_updates/lib/HoneyClient/Manager/VM/Clone.pm

    r810 r811  
    4242=head1 SYNOPSIS 
    4343 
    44 # XXX: FIX THIS 
    45  
    46   # NOTE: This package is an INTERFACE specification only!  It is 
    47   # NOT intended to be used directly.  Rather, it is expected that 
    48   # other Driver specific sub-packages will INHERIT and IMPLEMENT 
    49   # these methods. 
    50  
    51   # Eventually, change each reference of 'HoneyClient::Agent::Driver' 
    52   # to an implementation-specific 'HoneyClient::Agent::Driver::*'  
    53   # package name. 
    54   use HoneyClient::Agent::Driver; 
     44  use HoneyClient::Manager::VM::Clone; 
    5545 
    5646  # Library used exclusively for debugging complex objects. 
    5747  use Data::Dumper; 
    5848 
    59   # Eventually, call the new() function on an implementation-specific 
    60   # Driver package name. 
    61   my $driver = HoneyClient::Agent::Driver->new(); 
     49  # Create a new cloned VM, using the default 
     50  # 'master_vm_config' listed in the global configuration 
     51  # file (etc/honeyclient.xml). 
     52  my $clone = HoneyClient::Manager::VM::Clone->new(); 
     53 
     54  # When the new() operation completes, you are guaranteed that the 
     55  # cloned VM is powered on, has an IP address, and has a HoneyClient::Agent daemon 
     56  # ready for use. 
     57   
     58  # Let's get the path to the newly created clone's configuration file. 
     59  my $config = $clone->{'config'}; 
     60 
     61  # Figure out which master VM this clone is based on. 
     62  my $master_vm_config = $clone->{'master_vm_config'}; 
     63 
     64  # Get the MAC address of the cloned VM's primary network interface. 
     65  my $mac_address = $clone->{'mac_address'}; 
     66 
     67  # Get the IP address of the cloned VM's primary network interface. 
     68  my $ip_address = $clone->{'ip_address'}; 
     69 
     70  # Get the name of the cloned VM (as it appears in the VMware Console). 
     71  my $name = $clone->{'name'}; 
     72 
     73  # If you want the cloned VM to be suspended and no longer used, 
     74  # simply set the variable to 'undef'. 
     75  $clone = undef; 
     76 
     77  # For existing cloned VMs that have been powered off or suspended, 
     78  # you can create a Clone object to interact with those as well. 
     79  $clone = HoneyClient::Manager::VM::Clone->new(config => '/vm/clones/other/winXPPro.cfg'); 
    6280 
    6381  # If you want to see what type of "state information" is physically 
    64   # inside $driver, try this command at any time. 
    65   print Dumper($driver); 
    66  
    67   # Continue to "drive" the driver, until it is finished. 
    68   while (!$driver->isFinished()) { 
    69  
    70       # Before we drive the application to a new set of resources, 
    71       # find out where we will be going within the application, first. 
    72       print "About to contact the following resources:\n"; 
    73       print Dumper($driver->next()); 
    74  
    75       # Now, drive the application. 
    76       $driver->drive(); 
    77  
    78       # Get status of current iteration of work. 
    79       print "Status:\n"; 
    80       print Dumper($driver->status()); 
    81        
    82   } 
     82  # inside $clone, try this command at any time. 
     83  print Dumper($clone); 
    8384 
    8485=head1 DESCRIPTION 
    8586 
    86 # XXX: FIX THIS 
    87  
    88 This library allows the Agent module to access any drivers running on the 
    89 HoneyClient VM in a consistent fashion.  This module is object-oriented in 
    90 design, allowing specific types of drivers to inherit these abstractly 
    91 defined interface methods. 
    92  
    93 Fundamentally, a "Driver" is a programmatic construct, designed to 
    94 automate a back-end application that is intended to be exploited by 
    95 different types of malware.  As such, the "Agent" interacts with each 
    96 B<application-specific> Driver running inside the HoneyClient VM, in 
    97 order to programmatically automate the corresponding applications. 
    98  
    99 When a "Driver" is "driven", this implies that the back-end application 
    100 is accessing a B<new> Internet resource, in order to intentionally be exposed 
    101 to new malware and thus become exploited. 
    102  
    103 Example implementation Drivers involve automating certain types and 
    104 B<versions> of web browsers (e.g., Microsoft Internet Explorer, Mozilla  
    105 Firefox) or even email applications (e.g., Microsoft Outlook, Mozilla 
    106 Thunderbird). 
     87This library provides the Manager module with an object-oriented interface 
     88towards interacting with cloned virtual machines.  It allows the Manager 
     89to quickly create new cloned VMs in a consistent manner, without requiring  
     90the Manager to deal with all the nuances in cloning VMs. 
     91 
     92When a new "Clone" object is created, the following normally occurs: 
     93 
     94=over 4 
     95 
     96=item 1) 
     97 
     98A new VM is created, based upon cloning a given master VM. 
     99 
     100=item 2)  
     101 
     102The cloned VM is powered on and the name of the VM is recorded. 
     103 
     104=item 3)  
     105 
     106The MAC and IP address of the cloned VM's primary network interface 
     107are recorded. 
     108 
     109=item 4) 
     110 
     111The HoneyClient::Agent daemon running inside the cloned VM is verified 
     112and ready for use. 
     113 
     114=back 
     115 
     116Note: If an existing cloned VM's configuration file is specified in 
     117the new() call, then the "Clone" object will reuse this VM (by not 
     118creating any duplicate VMs) and proceed to power up this VM, along 
     119with going through the same verification procedures. 
    107120 
    108121=cut 
    …… 
    812825=head1 BUGS & ASSUMPTIONS 
    813826 
    814 This package has been designed in an object-oriented fashion, as a 
    815 simple B<INTERFACE> for other, more robust fully-implemented  
    816 HoneyClient::Agent::Driver::* sub-packages to inherit. 
    817  
    818 Specifically, B<ONLY> the new() function is implemented in this package. 
    819 While this allows any user to create Driver B<$object>s by explicitly 
    820 calling the HoneyClient::Agent::Driver->new() function, any subsequent 
    821 calls to any other method (i.e., $object->drive()) will B<FAIL>, as it is 
    822 expected that fully defined Driver sub-packages would implement these 
    823 capabilities. 
    824  
    825 In a nutshell, this object is nothing more than a blessed anonymous 
     827Currently, the new() function assumes that the master VM supplied 
     828has been setup and configured according to the specification listed 
     829here: 
     830 
     831L<http://www.honeyclient.org/trac/wiki/UserGuide#HoneyclientVM> 
     832 
     833Thus, upon cloning, if a cloned VM is unable to properly boot into 
     834Windows and load the HoneyClient::Agent daemon properly, then the 
     835new() call will B<hang indefinately>. 
     836 
     837In a nutshell, this object is basically a blessed anonymous 
    826838reference to a hashtable, where (key => value) pairs are defined in 
    827839the L<DEFAULT PARAMETER LIST>, as well as fed via the new() function 
    …… 
    841853 
    842854=head1 AUTHORS 
    843  
    844 Kathy Wang, E<lt>knwang@mitre.orgE<gt> 
    845  
    846 Thanh Truong, E<lt>ttruong@mitre.orgE<gt> 
    847855 
    848856Darien Kindlund, E<lt>kindlund@mitre.orgE<gt>