Changeset 813

Show
Ignore:
Timestamp:
09/04/07 15:01:13 (1 year ago)
Author:
kindlund
Message:

Cleaned up Manager documentation (slightly). Still have to eventually fix documentation for all public function names.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

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

    r808 r813  
    77# CVS: $Id$ 
    88# 
    9 # @author knwang, ttruong, jdurick, kindlund 
     9# @author knwang, kindlund 
    1010# 
    1111# Copyright (C) 2007 The MITRE Corporation.  All rights reserved. 
    …… 
    3232=head1 NAME 
    3333 
    34 # XXX: Fill this in. 
     34HoneyClient::Manager - Perl extension to manage Agent VMs on the 
     35host system. 
    3536 
    3637=head1 VERSION 
    …… 
    4041=head1 SYNOPSIS 
    4142 
    42 =head2 CREATING THE SOAP SERVER 
    43  
    44 # XXX: Fill this in. 
    45  
    46 =head2 INTERACTING WITH THE SOAP SERVER 
    47  
    48 # XXX: Fill this in. 
     43  use HoneyClient::Manager; 
     44  use Data::Dumper; 
     45 
     46  # Utility functions to encode configuration data. 
     47  use Storable qw(nfreeze thaw); 
     48  use MIME::Base64 qw(encode_base64 decode_base64); 
     49 
     50  # Note: Make sure only one of these "my driver =" lines 
     51  # is uncommented. 
     52 
     53  # Use Internet Explorer as the instrumenting application. 
     54  my $driver = "HoneyClient::Agent::Driver::Browser::IE"; 
     55 
     56  # Use Mozilla Firefox as the instrumenting application. 
     57  #my $driver = "HoneyClient::Agent::Driver::Browser::FF"; 
     58 
     59  # Start the Manager. 
     60  HoneyClient::Manager->run( 
     61 
     62      driver => $driver, 
     63 
     64      agent_state => encode_base64(nfreeze({ 
     65 
     66          $driver => { 
     67 
     68              # Specify the next link for the Agent VM to visit. 
     69              next_link_to_visit => "http://www.mitre.org", 
     70 
     71              # If you have more than one link, you can also 
     72              # set this type of hashtable: 
     73              links_to_visit => { 
     74                  'http://www.google.com' => 1, 
     75              }, 
     76          }, 
     77 
     78      })), 
     79  ); 
    4980 
    5081=head1 DESCRIPTION 
    5182 
    52 # XXX: Fill this in. 
     83This module provides centralized control over provisioning, initializing, 
     84running, and suspending all Agent VMs.  Upon calling the run() function, 
     85the Manager will proceed to create a new clone of the master Honeyclient VM 
     86(aka. an Agent VM) and feed this Agent VM a new list of URLs to crawl. 
     87 
     88While the Agent VM is crawling, the Manager will check to make sure the 
     89Agent VM has not been compromised.  If no compromise was found, then the 
     90Manager will signal the Firewall to allow the Agent VM to contact the 
     91next set of network resources (i.e., a webserver). 
     92 
     93If the Manager discovers the Agent VM has been compromised, then the 
     94Manager will suspend the clone VM, log the incident, and create a new Agent 
     95VM clone -- where this new clone picks up with the next set of URLs to 
     96crawl. 
     97 
     98If there are no URLs left for the Agent VM to visit OR if the user 
     99presses CTRL+C while the Manager is running, then the Manager will 
     100suspend the currently running Agent VM and write its state information 
     101out to the filesystem on the host system.  This file is usually 
     102called 'Manager.dump'; however, the name can be changed by editing 
     103the <HoneyClient/><Manager/><manager_state/> section of the 
     104etc/honeyclient.xml file. 
     105 
     106This 'Manager.dump' file contains the set of URLs that the Honeyclients 
     107have visited, ignored, or tried to visit.  In order to determine 
     108which URLs were identified as malicious, you will need to check 
     109the syslog on the host system and search for the keyword of "FAILED". 
     110 
     111By default, all cloned VMs that the Manager suspends will have been 
     112flagged as compromised -- unless the set of URLs has been exhausted 
     113or the user prematurely terminates the process (by pressing CTRL+C). 
    53114 
    54115=cut 
    …… 
    813874=head1 BUGS & ASSUMPTIONS 
    814875 
    815 # XXX: Fill this in. 
     876Currently the documentation in the "EXPORTED FUNCTIONS" and 
     877"EXPORTS" sections are both incomplete; these sections are still 
     878a work-in-progress. 
     879 
     880This module relies on various libraries, which may have their own 
     881set of issues.  As such, see the following sections: 
     882 
     883=over 4 
     884 
     885=item * 
     886 
     887L<HoneyClient::Manager::VM::Clone/"BUGS & ASSUMPTIONS"> 
     888 
     889=back 
    816890 
    817891=head1 SEE ALSO 
    …… 
    829903=head1 AUTHORS 
    830904 
     905Darien Kindlund, E<lt>kindlund@mitre.orgE<gt> 
     906 
    831907Kathy Wang, E<lt>knwang@mitre.orgE<gt> 
    832  
    833 Thanh Truong, E<lt>ttruong@mitre.orgE<gt> 
    834  
    835 Darien Kindlund, E<lt>kindlund@mitre.orgE<gt> 
    836908 
    837909=head1 COPYRIGHT & LICENSE