Changeset 1499

Show
Ignore:
Timestamp:
04/09/08 15:47:11 (8 months ago)
Author:
kindlund
Message:

Merging simpler_agent branch into trunk.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • honeyclient/trunk/bin/StartAgent.pl

    r1008 r1499  
    1 #!perl -w -Ilib 
     1#!perl -Ilib 
    22 
    33# $Id$ 
    …… 
    77use Carp (); 
    88 
     9use Term::ReadKey; 
    910use HoneyClient::Util::Config qw(getVar); 
    1011use HoneyClient::Agent; 
    …… 
    2122our $URL = HoneyClient::Agent->init(); 
    2223 
    23 our $agentState = undef; 
    24 my $tempState = undef; 
    25 our $faultDetected = 0; 
    26  
    2724print "URL: " . $URL. "\n"; 
    2825 
    29 sub _watchdogFaultHandler { 
    30  
    31     # Extract arguments. 
    32     my ($class, $res) = @_; 
    33  
    34     # Construct error message. 
    35     # Figure out if the error occurred in transport or over 
    36     # on the other side. 
    37     my $errMsg = $class->transport->status; # Assume transport error. 
    38  
    39     if (ref $res) { 
    40         $errMsg = $res->faultcode . ": ".  $res->faultstring . "\n"; 
    41     } 
    42  
    43     if (!$faultDetected) { 
    44         $LOG->error("Watchdog fault detected, recovering Agent daemon."); 
    45         $faultDetected = 1; 
    46     } 
    47     # XXX: Reenable this, eventually. 
    48     $LOG->error(__PACKAGE__ . "->_watchdogFaultHandler(): Error occurred during processing.\n" . $errMsg); 
    49     Carp::carp __PACKAGE__ . "->_watchdogFaultHandler(): Error occurred during processing.\n" . $errMsg; 
    50  
    51  
    52     # Regardless of the error, destroy the Agent process and reinitialize it. 
    53     # XXX: Sanity check this, eventually. 
    54     HoneyClient::Agent->destroy(); 
    55  
    56     # Wait for a small amount of time, in order for the killed process to release 
    57     # its control of the bound TCP port. 
    58     sleep 5; 
    59  
    60     $URL = HoneyClient::Agent->init(); 
    61  
    62     # Recreate a new stub handle, in case the global configuration has 
    63     # changed. 
    64     $stub = getClientHandle(address   => 'localhost', 
    65                             namespace => 'HoneyClient::Agent', 
    66                             fault_handler => \&_watchdogFaultHandler); 
    67  
    68     # Restore state information. 
    69     if (defined($agentState)) { 
    70         $som = $stub->updateState(encode_base64(nfreeze($agentState))); 
    71     } 
     26# Halt when we get any sort of keyboard input. 
     27my $key; 
     28ReadMode 4; # Turn off controls keys 
     29while (not defined ($key = ReadKey(-1))) { 
     30    # No key yet 
    7231} 
    73  
    74 $stub = getClientHandle(address   => 'localhost', 
    75                         namespace => 'HoneyClient::Agent', 
    76                         fault_handler => \&_watchdogFaultHandler); 
    77                  
    78 for (;;) { 
    79     # TODO: Make this a programmatic value. 
    80     sleep (5); 
    81     $som = $stub->getState(); 
    82     if (defined($som) and (ref($som) eq "SOAP::SOM")) { 
    83         $tempState = $som->result(); 
    84         if (defined($tempState)) { 
    85             # Make sure the new state is parsable, before saving it. 
    86             eval { 
    87                 $tempState = thaw(decode_base64($tempState)); 
    88             }; 
    89             if (!$@) { 
    90                 $agentState = $tempState; 
    91             } 
    92         } 
    93     } 
    94 } 
     32ReadMode 0; # Reset tty mode before exiting 
    9533 
    9634HoneyClient::Agent->destroy(); 

  • honeyclient/trunk/bin/StartManager.pl

    r1008 r1499  
    1 #!perl -w -Ilib 
    2  
    3 # $Id$ 
     1#!perl -Ilib 
     2####################################################################### 
     3# Created on:  Apr 08, 2008 
     4# File:        StartManager.pl 
     5# Description: Start up script for manager-based operations. 
     6# 
     7# CVS: $Id$ 
     8# 
     9# @author knwang, kindlund 
     10# 
     11# Copyright (C) 2007-2008 The MITRE Corporation.  All rights reserved. 
     12# 
     13# This program is free software; you can redistribute it and/or 
     14# modify it under the terms of the GNU General Public License 
     15# as published by the Free Software Foundation, using version 2 
     16# of the License. 
     17#  
     18# This program is distributed in the hope that it will be useful, 
     19# but WITHOUT ANY WARRANTY; without even the implied warranty of 
     20# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
     21# GNU General Public License for more details. 
     22#  
     23# You should have received a copy of the GNU General Public License 
     24# along with this program; if not, write to the Free Software 
     25# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 
     26# 02110-1301, USA. 
     27# 
     28####################################################################### 
     29 
     30BEGIN { 
     31    our $VERSION = 1.02; 
     32} 
     33our ($VERSION); 
     34 
     35=pod 
     36 
     37=head1 NAME 
     38 
     39StartManager.pl - Perl script to start the Manager on the 
     40host system. 
     41 
     42=head1 SYNOPSIS 
     43 
     44 StartManager.pl [options] [http://www.google.com http://www.cnn.com ...] 
     45 
     46 Options: 
     47 --help               This help message. 
     48 --man                Print full man page. 
     49 --driver_name=       Name of driver to use. 
     50 --master_vm_config=  Absolute path to the master VM configuration to use. 
     51 --url_list=          File containing newline separated URLs to use. 
     52 
     53=head1 OPTIONS 
     54 
     55=over 4 
     56 
     57=item B<--help> 
     58 
     59Print a brief help message and exits. 
     60 
     61=item B<--driver_name=> 
     62 
     63Specifies the driver name to use.  If none is specified, the 
     64default will be used. 
     65 
     66=item B<--master_vm_config=> 
     67 
     68Specifies the master VM configuration file to use.  If none 
     69is specified, the default will be used. 
     70 
     71=item B<--url_list=> 
     72 
     73If specified, the newline separated URLs inside this file will 
     74be parsed and fed into the Manager upon startup. 
     75 
     76=back 
     77 
     78=head1 DESCRIPTION 
     79 
     80This program starts the Manager on the host system.  If URLs 
     81are specified on the command-line, the program will  
     82assign a base priority to each URL and feed them into the Manager 
     83for additional processing. 
     84 
     85This program will run until manually terminated by the user, by 
     86pressing CTRL-C. 
     87 
     88=head1 SEE ALSO 
     89 
     90L<http://www.honeyclient.org/trac> 
     91 
     92=head1 REPORTING BUGS 
     93 
     94L<http://www.honeyclient.org/trac/newticket> 
     95 
     96=head1 AUTHORS 
     97 
     98Darien Kindlund, E<lt>kindlund@mitre.orgE<gt> 
     99 
     100Kathy Wang, E<lt>knwang@mitre.orgE<gt> 
     101 
     102=head1 COPYRIGHT & LICENSE 
     103 
     104Copyright (C) 2007-2008 The MITRE Corporation.  All rights reserved. 
     105 
     106This program is free software; you can redistribute it and/or 
     107modify it under the terms of the GNU General Public License 
     108as published by the Free Software Foundation, using version 2 
     109of the License. 
     110  
     111This program is distributed in the hope that it will be useful, 
     112but WITHOUT ANY WARRANTY; without even the implied warranty of 
     113MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
     114GNU General Public License for more details. 
     115  
     116You should have received a copy of the GNU General Public License 
     117along with this program; if not, write to the Free Software 
     118Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 
     11902110-1301, USA. 
     120 
     121=cut 
    4122 
    5123use strict; 
    …… 
    7125use Carp (); 
    8126 
     127# Include Pod Library 
     128use Pod::Usage; 
     129 
    9130# Include Dumper Library 
    10131use Data::Dumper; 
    …… 
    17138 
    18139# Include Getopt Parser 
    19 use Getopt::Long; 
     140use Getopt::Long qw(:config auto_help ignore_case_always); 
    20141 
    21142# Include utility access to global configuration. 
    22143use HoneyClient::Util::Config qw(getVar); 
    23144 
    24 # Include Manager Library 
    25 use HoneyClient::Manager; 
    26145 
    27146# Include Logging Library 
    …… 
    34153# Namely, the initial set of URLs that they want the Agent to use. 
    35154 
    36 # Change to 'HoneyClient::Agent::Driver::Browser::IE' or 
    37 #           'HoneyClient::Agent::Driver::Browser::FF' 
    38 my $driver = undef; 
    39 my $config = undef; 
    40 my $maxrel = undef; 
    41 my $nexturl = ""; 
    42 my $urllist= ""; 
    43  
    44 # TODO: Need --help option, along with sanity checking. 
    45 # TODO: Also need a decent POD for this code. 
    46 GetOptions('driver=s'             => \$driver, 
    47            'master_vm_config=s'   => \$config, 
    48            'url_list=s'           => \$urllist, 
    49            'max_relative_links:i' => \$maxrel); 
    50  
    51 # Sanity Check.  Make sure $driver is set. 
    52 unless (defined($driver)) { 
    53     $driver = getVar(name      => "default_driver", 
    54                      namespace => "HoneyClient::Agent"); 
    55 } 
    56  
    57 # Sanity Check.  Make sure $max_relative_links is set. 
    58 unless (defined($maxrel)) { 
    59     $maxrel = getVar(name      => "max_relative_links_to_visit", 
    60                      namespace => "HoneyClient::Agent::Driver::Browser"); 
    61 } 
     155# Inputs. 
     156my $driver_name = undef; 
     157my $master_vm_config = undef; 
     158my $url_list= ""; 
     159 
     160GetOptions('driver_name=s'        => \$driver_name, 
     161           'master_vm_config=s'   => \$master_vm_config, 
     162           'url_list=s'           => \$url_list, 
     163           'man'                  => sub { pod2usage(-exitstatus => 0, -verbose => 2) }, 
     164           'version'              => sub { 
     165                                        print "MITRE HoneyClient Project (http://www.honeyclient.org)\n" . 
     166                                              "------------------------------------------------------\n" . 
     167                                              $0  . " (v" . $VERSION . ")\n"; 
     168                                        exit(0); 
     169                                     }) or pod2usage(2); 
    62170 
    63171# Go through the list of urls to create the array 
    …… 
    66174my @urls; 
    67175push( @urls, @ARGV );  
    68 if( -e $urllist ){ 
    69     open URL, $urllist; 
     176if( -e $url_list ){ 
     177    open URL, $url_list; 
    70178    push(@urls, <URL>); 
    71179} 
    72180 
    73 # Get the first url from the list 
    74 # Create a hashtable in the form: url => 1 for links_to_visit  
    75 chomp @urls; 
    76 my $firsturl = shift @urls; 
    77 my %remaining_urls; 
     181# Get the base priority. 
     182my $priority = getVar(name      => "command_line_base_priority", 
     183                      namespace => "HoneyClient::Manager"); 
     184 
     185# Create a hashtable in the form: url => priority. 
     186my $work = {}; 
    78187foreach(@urls){ 
    79188    # We assign our initial list of URLs a priority of 1000, so that 
    80189    # they'll be (likely to be) selected first, before going to any other 
    81190    # external URLs found from subsequent drive operations. 
    82     $remaining_urls{$_} = 1000; 
     191    chomp; 
     192    if ($_ ne "") { 
     193        $work->{$_} = $priority; 
     194    } 
    83195} 
    84196 
    85 my $agentState = HoneyClient::Manager->run( 
    86                     driver           => $driver, 
    87                     master_vm_config => $config, 
    88                     agent_state      => encode_base64(nfreeze({ 
    89                         $driver => { 
    90                             next_link_to_visit => $firsturl, 
    91                             max_relative_links_to_visit => $maxrel, 
    92                             links_to_visit => \%remaining_urls, 
    93                          }, 
    94                     })),  
    95                  ); 
    96  
     197# Start the Manager. 
     198require HoneyClient::Manager; 
     199HoneyClient::Manager->run( 
     200    driver_name      => $driver_name, 
     201    master_vm_config => $master_vm_config, 
     202    work             => $work, 
     203); 

  • honeyclient/trunk/bin/bootstrap_agent.sh

    r1311 r1499  
    77# Remove all old /tmp/* entries. 
    88rm /tmp/* > /dev/null 2>&1 
     9 
     10# Remove any old capture logs entries. 
     11rm -rf ~/honeyclient/thirdparty/capture-mod/logs 
    912 
    1013# Determine the IP address of the VM running. 
    …… 
    3437 
    3538# Start the Agent code. 
    36 while [ true ] ; do 
    37     perl -Ilib bin/StartAgent.pl && sleep 1 
    38 done 
     39perl -Ilib bin/StartAgent.pl 

  • honeyclient/trunk/etc/honeyclient.xml

    r1401 r1499  
    6262    <!-- HoneyClient::Agent Options --> 
    6363    <Agent> 
    64         <!-- TODO: Update this. --> 
    6564        <address description="The IP or hostname that all Agent modules should use, when accepting SOAP requests." default="0.0.0.0"> 
    6665            0.0.0.0 
    …… 
    6867        <!-- TODO: Update this. --> 
    6968        <!-- Note: This port should be unique and not already in use by other modules, services, or daemons running inside the VM. --> 
    70         <port description="The TCP port number that the SOAP server for all Agent modules will listen on for requests." default="9000"> 
    71             9000 
     69        <port description="The TCP port number that the SOAP server for all Agent modules will listen on for requests." default="7627"> 
     70            7627 
    7271        </port> 
    7372        <allowed_drivers description="List of implemented Drivers that the Agent is allowed to run directly."> 
    …… 
    8079        <!-- HoneyClient::Agent::Driver Options --> 
    8180        <Driver> 
    82             <!-- TODO: Update this. --> 
     81            <!-- TODO: Update this. XXX: Command-line option, eventually? --> 
    8382            <timeout description="How long the Driver waits during a drive operation, before timing out (in seconds)." default="60"> 
    8483                20 
    8584            </timeout> 
    86             <ActiveContent> 
    87                 <enable description="Enables active content parsing. 1 enables, 0 disables." default="1"> 
    88                     0 
    89                 </enable> 
    90                 <Flash> 
    91                     <flasm_exec description="Path to the flasm executable." default="thirdparty/flasm/flasm.exe"> 
    92                         thirdparty/flasm/flasm.exe 
    93                     </flasm_exec> 
    94                 </Flash> 
    95             </ActiveContent> 
    9685            <Browser> 
    97                 <!-- HoneyClient::Agent::Driver::IE Options --> 
    98                 <!-- TODO: Update this. --> 
    99                 <ignore_links_timed_out description="If this parameter is 1, then the browser will never attempt to revisit any links that caused the browser to initially time out." default="0"> 
    100                     1 
    101                 </ignore_links_timed_out> 
    102                 <limit_spidering description="When set to 1, the Browser will not visit any derived links other than the initial set of URLs given.  This is useful when you want the Browser to only visit a specific set of URLs (perhaps malicious) and no other links that it finds on any of the visited pages.  When set to 1, this option will override max_relative_links_to_visit (essentially setting it to 0).  If you want the Browser to spider through derived links, set this value to 0." default="1"> 
    103                     1 
    104                 </limit_spidering> 
    105                 <max_relative_links_to_visit description="An integer, representing the maximum number of relative links that the browser should visit, before moving onto another website.  If negative, then the browser will exhaust all possible relative links found, before moving on.  This functionality is best effort; it's possible for the browser to visit new links on previously visited websites. Note that this value can be overridden if limit_spidering is set to 1 above." default="-1"> 
    106                     5 
    107                 </max_relative_links_to_visit> 
    108                 <positive_words description="If a link contains any number of these words, then its probability of being visited (its score) will increase."> 
    109                     <word>news</word> 
    110                     <word>new</word> 
    111                     <word>big</word> 
    112                     <word>latest</word> 
    113                     <word>main</word> 
    114                     <word>update</word> 
    115                     <word>sell</word> 
    116                     <word>free</word> 
    117                     <word>buy</word> 
    118                     <word>science</word> 
    119                 </positive_words> 
    120                 <negative_words description="If a link contains any number of these words, then its probability of being visited (its score) will decrease."> 
    121                     <word>archive</word> 
    122                     <word>privacy</word> 
    123                     <word>legal</word> 
    124                     <word>disclaim</word> 
    125                     <word>about</word> 
    126                     <word>contact</word> 
    127                     <word>copyright</word> 
    128                     <word>jobs</word> 
    129                     <word>careers</word> 
    130                     <word>term</word> 
    131                 </negative_words> 
    13286                <IE> 
    13387                    <!-- HoneyClient::Agent::Driver::Browser::IE Options --> 
    …… 
    149103                </FF> 
    150104            </Browser> 
    151             <EmailClient> 
    152             </EmailClient> 
    153105        </Driver> 
    154106        <perform_integrity_checks description="An integer, representing whether the Agent should perform any integrity checks. 1 enables, 0 disables." default="1"> 
    …… 
    163115                /tmp/realtime-changes.txt 
    164116            </realtime_changes_file> 
     117            <!-- HoneyClient::Agent::Integrity::Test Options --> 
     118            <Test> 
     119                <!-- 
     120                    Note: you should *never* need to change *any* values 
     121                    within this section of the configuration.  All contents 
     122                    are *only* used for unit testing. 
     123                --> 
     124                <realtime_changes_file description="When an integrity check fails, all changes will be written to this file within the compromized honeyclient VM's filesystem." default="/tmp/realtime-changes.txt"> 
     125                    t/test_integrity/realtime-changes.txt 
     126                </realtime_changes_file> 
     127            </Test> 
    165128        </Integrity> 
    166129    </Agent> 
     130    <!-- TODO: Update this. --> 
     131    <Crawler> 
     132        <ActiveContent> 
     133            <enable description="Enables active content parsing. 1 enables, 0 disables." default="1"> 
     134                0 
     135            </enable> 
     136            <Flash> 
     137                <flasm_exec description="Path to the flasm executable." default="thirdparty/flasm/flasm.exe"> 
     138                    thirdparty/flasm/flasm.exe 
     139                </flasm_exec> 
     140            </Flash> 
     141        </ActiveContent> 
     142        <Browser> 
     143            <!-- TODO: Update this. --> 
     144            <ignore_links_timed_out description="If this parameter is 1, then the browser will never attempt to revisit any links that caused the browser to initially time out." default="0"> 
     145                1 
     146            </ignore_links_timed_out> 
     147            <limit_spidering description="When set to 1, the Browser will not visit any derived links other than the initial set of URLs given.  This is useful when you want the Browser to only visit a specific set of URLs (perhaps malicious) and no other links that it finds on any of the visited pages.  When set to 1, this option will override max_relative_links_to_visit (essentially setting it to 0).  If you want the Browser to spider through derived links, set this value to 0." default="1"> 
     148                1 
     149            </limit_spidering> 
     150            <max_relative_links_to_visit description="An integer, representing the maximum number of relative links that the browser should visit, before moving onto another website.  If negative, then the browser will exhaust all possible relative links found, before moving on.  This functionality is best effort; it's possible for the browser to visit new links on previously visited websites. Note that this value can be overridden if limit_spidering is set to 1 above." default="-1"> 
     151                5 
     152            </max_relative_links_to_visit> 
     153            <positive_words description="If a link contains any number of these words, then its probability of being visited (its score) will increase."> 
     154                <word>news</word> 
     155                <word>new</word> 
     156                <word>big</word> 
     157                <word>latest</word> 
     158                <word>main</word> 
     159                <word>update</word> 
     160                <word>sell</word> 
     161                <word>free</word> 
     162                <word>buy</word> 
     163                <word>science</word> 
     164            </positive_words> 
     165            <negative_words description="If a link contains any number of these words, then its probability of being visited (its score) will decrease."> 
     166                <word>archive</word> 
     167                <word>privacy</word> 
     168                <word>legal</word> 
     169                <word>disclaim</word> 
     170                <word>about</word> 
     171                <word>contact</word> 
     172                <word>copyright</word> 
     173                <word>jobs</word> 
     174                <word>careers</word> 
     175                <word>term</word> 
     176            </negative_words> 
     177        </Browser> 
     178    </Crawler> 
    167179    <Manager> 
    168         <manager_state description="Upon termination, the Manager will attempt to append a complete copy of its state into this file, if specified." default=""> 
    169             manager.dump 
    170         </manager_state> 
    171180        <fingerprint_dump description="When the Manager encounters a suspicious VM, it will attempt to append a complete copy of the fingerprint information to this file, if specified."> 
    172181            fingerprint.dump 
    173182        </fingerprint_dump> 
    174         <!-- TODO: Update this. --> 
    175183        <address description="The IP or hostname that all Manager modules should use, when accepting SOAP requests." default="localhost"> 
    176184            localhost 
    177185        </address> 
    178         <!-- TODO: Update this. --> 
    179186        <!-- Note: This port should be unique and not already in use by other modules, services, or daemons running on the host system. --> 
    180         <port description="The TCP port number that the SOAP server for all Manager modules will listen on for requests." default="8089"> 
    181             8089 
     187        <port description="The TCP port number that the SOAP server for all Manager modules will listen on for requests." default="7627"> 
     188            7627 
    182189        </port> 
    183         <max_agent_error_count description="When the Agent is running, this value is the maximum number of SOAP communication errors the Manager will ignore (e.g., timeouts) before the Manager suspends the corresponding VM and clones a new Agent.  These errors mainly occur when the Manager loses connectivity to the Agent for some reason (i.e., software/OS crashing inside the VM).  Otherwise, the Manager would loop forever trying to reconnect with the faulty VM.  This value should never be set to 0 and should always be positive." default="3"> 
    184             3 
    185         </max_agent_error_count> 
     190        <num_urls_to_process description="If database support is enabled, this value indicates how many URLs the Manager will fetch from the database, process, and report back, before fetching for more URLs." default="10"> 
     191            10 
     192        </num_urls_to_process> 
     193        <database_retry_delay description="If database support is enabled, this value indicates how often (in seconds) the Manager will retry contacting the database, when it is ready for more URLs to process and no URLs were provided during the first request." default="2"> 
     194            2 
     195        </database_retry_delay> 
     196        <command_line_base_priority description="When the Manager is supplied URLs from the command line, it will assign each URL the following numerical base priority." default="1000"> 
     197            1000 
     198        </command_line_base_priority> 
    186199        <!-- HoneyClient::Manager::Database Options --> 
    187200        <Database> 
    …… 
    203216                192.168.0.128 
    204217            </address> 
    205             <!-- TODO: Update this. --> 
     218            <!-- TODO: Update this to 7627, eventually. --> 
    206219            <port description="Default FW port number" default="8083"> 
    207220                8083 
    …… 
    291304        <VM> 
    292305            <master_vm_config description="The full absolute path to the VM configuration file on the host system that will be used by all subsequent cloned VMs."> 
    293                 /vm/masters/Agent.Master-36/winXPPro.cfg 
     306                /vm/masters/Agent.Master-37/winXPPro.cfg 
    294307            </master_vm_config> 
    295             <port description="The TCP port number that the SOAP server of the VM daemon will listen on for requests.  Note: This port should be unique and not already be used by other modules, services, or daemons running on the host system." default="8089"> 
    296                 8089 
     308            <port description="The TCP port number that the SOAP server of the VM daemon will listen on for requests.  Note: This port should be unique and not already be used by other modules, services, or daemons running on the host system." default="7627"> 
     309                7627 
    297310            </port> 
    298311            <datastore_path description="The absolute path to the parent directory, where all HoneyClient VM data is stored on the host server.  It is assumed that individual VM data is stored in separate subdirectories within this parent directory." default="/vm"> 
    …… 
    317330                /var/log/messages 
    318331            </dhcp_log> 
     332            <!-- HoneyClient::Manager::VM::Clone Options --> 
     333            <Clone> 
     334                <archive_upon_suspend description="If set to 1, then everytime a cloned VM is suspended, a copy of the VM will be archived in the 'snapshot_path' directory.  Set this option to 0, if you discover errors during cloning operations, where the hard disk on the host system is overworked on slow systems." default="1"> 
     335                    1 
     336                </archive_upon_suspend> 
     337            </Clone> 
    319338            <!-- HoneyClient::Manager::VM::Test Options --> 
    320339            <Test> 

  • honeyclient/trunk/lib/HoneyClient/Agent.pm

    r1319 r1499  
    11####################################################################### 
    2 # Created on:  May 11, 2006 
     2# Created on:  April 02, 2008 
    33# Package:     HoneyClient::Agent 
    44# File:        Agent.pm 
    …… 
    99# @author knwang, ttruong, kindlund 
    1010# 
    11 # Copyright (C) 2007 The MITRE Corporation.  All rights reserved. 
     11# Copyright (C) 2007-2008 The MITRE Corporation.  All rights reserved. 
    1212# 
    1313# This program is free software; you can redistribute it and/or 
    …… 
    3838=head1 VERSION 
    3939 
    40 1.02 
     40This documentation refers to HoneyClient::Agent version 1.02. 
    4141 
    4242=head1 SYNOPSIS 
    …… 
    4444=head2 CREATING THE SOAP SERVER 
    4545 
    46 # XXX: Fill this in. 
     46  use HoneyClient::Agent; 
     47 
     48  # Handle SOAP requests on the default address:port. 
     49  my $URL = HoneyClient::Agent->init(); 
     50 
     51  # Handle SOAP requests on TCP port localhost:9090 
     52  my $URL = HoneyClient::Agent->init(address => "localhost", 
     53                                     port    => 9090); 
     54 
     55  print "Server URL: " . $URL . "\n"; 
     56 
     57  # Create a cleanup function, to execute whenever 
     58  # the SOAP server needs to be destroyed. 
     59  sub cleanup { 
     60      HoneyClient::Agent->destroy(); 
     61      exit; 
     62  } 
     63 
     64  # Install the cleanup handler, in case parent process 
     65  # dies unexpectedly. 
     66  $SIG{HUP}       = \&cleanup; 
     67  $SIG{INT}       = \&cleanup; 
     68  $SIG{QUIT}      = \&cleanup; 
     69  $SIG{ABRT}      = \&cleanup; 
     70  $SIG{PIPE}      = \&cleanup; 
     71  $SIG{TERM}      = \&cleanup; 
     72 
     73  # Catch all parent code errors, in order to perform cleanup 
     74  # on all child processes before exiting. 
     75  eval { 
     76      # Do rest of the parent processing here... 
     77  }; 
     78 
     79  # We assume you still want to still want to "die" on 
     80  # any errors found within the eval block. 
     81  if ($@) { 
     82      HoneyClient::Agent->destroy(); 
     83      die $@; 
     84  } 
     85 
     86  # Even if no errors occurred, initiate cleanup. 
     87  cleanup(); 
    4788 
    4889=head2 INTERACTING WITH THE SOAP SERVER 
    4990 
    50 # XXX: Fill this in. 
     91  use HoneyClient::Util::SOAP qw(getClientHandle); 
     92  use Data::Dumper; 
     93  use MIME::Base64 qw(encode_base64 decode_base64); 
     94  use Storable qw(thaw); 
     95  $Storable::Deparse = 1; 
     96  $Storable::Eval = 1; 
     97 
     98  # Create a new SOAP client, to talk to the HoneyClient::Agent 
     99  # module. 
     100  my $stub = getClientHandle(namespace => "HoneyClient::Agent", 
     101                             address   => "localhost"); 
     102  my $som; 
     103 
     104  # Get the properties of the Agent OS and driven application. 
     105  $som = $stub->getProperties(driver_name => "HoneyClient::Agent::Driver::Browser::IE"); 
     106  print Dumper($som->result()) . "\n"; 
     107 
     108  # Drive HoneyClient::Agent::Driver::Browser::IE to a website. 
     109  $som = $stub->drive(driver_name => "HoneyClient::Agent::Driver::Browser::IE", 
     110                      parameters  => encode_base64("http://www.mitre.org")); 
     111 
     112  # Check the result to see if any compromise was found. 
     113  # Look for the 'fingerprint' key in the resulting hastable. 
     114  print Dumper(thaw(decode_base64($som->result()))) . "\n";  
    51115 
    52116=head1 DESCRIPTION 
    …… 
    60124package HoneyClient::Agent; 
    61125 
    62 # XXX: Disabled version check, Honeywall does not have Perl v5.8 installed. 
    63 #use 5.008006; 
    64126use strict; 
    65127use warnings FATAL => 'all'; 
    66128use Config; 
    67129use Carp (); 
    68 # TODO: This can go away. 
    69 use POSIX qw(SIGALRM); 
    70130 
    71131####################################################################### 
    …… 
    101161    @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); 
    102162 
    103     # Check to make sure our OS is Windows-based. 
    104     # XXX: Fix this! 
    105     #if ($Config{osname} !~ /^MSWin32$/) { 
    106     #    Carp::croak "Error: " . __PACKAGE__ . " will only run on Win32 platforms!\n"; 
    107     #} 
    108  
    109     # Check to see if ithreads are compiled into this version of Perl. 
    110     $Config{useithreads} or Carp::croak "Error: Recompile Perl with ithread support, in order to use this module.\n"; 
     163    # Check to make sure our environment is Cygwin-based. 
     164    if ($Config{osname} !~ /^cygwin$/) { 
     165        Carp::croak "Error: " . __PACKAGE__ . " will only run in Cygwin environments!\n"; 
     166    } 
    111167 
    112168    $SIG{PIPE} = 'IGNORE'; # Do not exit on broken pipes. 
    …… 
    118174=begin testing 
    119175 
     176 
     177# Make sure Log::Log4perl loads 
     178BEGIN { use_ok('Log::Log4perl', qw(:nowarn)) 
     179        or diag("Can't load Log::Log4perl package. Check to make sure the package library is correctly listed within the path."); 
     180 
     181        # Suppress all logging messages, since we need clean output for unit testing. 
     182        Log::Log4perl->init({ 
     183            "log4perl.rootLogger"                               => "DEBUG, Buffer", 
     184            "log4perl.appender.Buffer"                          => "Log::Log4perl::Appender::TestBuffer", 
     185            "log4perl.appender.Buffer.min_level"                => "fatal", 
     186            "log4perl.appender.Buffer.layout"                   => "Log::Log4perl::Layout::PatternLayout", 
     187            "log4perl.appender.Buffer.layout.ConversionPattern" => "%d{yyyy-MM-dd HH:mm:ss} %5p [%M] (%F:%L) - %m%n", 
     188        }); 
     189} 
     190require_ok('Log::Log4perl'); 
     191use Log::Log4perl qw(:easy); 
     192 
     193# Make sure HoneyClient::Util::Config loads. 
     194BEGIN { use_ok('HoneyClient::Util::Config', qw(getVar)) 
     195        or diag("Can't load HoneyClient::Util::Config package.  Check to make sure the package library is correctly listed within the path."); 
     196 
     197        # Suppress all logging messages, since we need clean output for unit testing. 
     198        Log::Log4perl->init({ 
     199            "log4perl.rootLogger"                               => "DEBUG, Buffer", 
     200            "log4perl.appender.Buffer"                          => "Log::Log4perl::Appender::TestBuffer", 
     201            "log4perl.appender.Buffer.min_level"                => "fatal", 
     202            "log4perl.appender.Buffer.layout"                   => "Log::Log4perl::Layout::PatternLayout", 
     203            "log4perl.appender.Buffer.layout.ConversionPattern" => "%d{yyyy-MM-dd HH:mm:ss} %5p [%M] (%F:%L) - %m%n", 
     204        }); 
     205} 
     206require_ok('HoneyClient::Util::Config'); 
     207can_ok('HoneyClient::Util::Config', 'getVar'); 
     208use HoneyClient::Util::Config qw(getVar); 
     209 
     210# Suppress all logging messages, since we need clean output for unit testing. 
     211Log::Log4perl->init({ 
     212    "log4perl.rootLogger"                               => "DEBUG, Buffer", 
     213    "log4perl.appender.Buffer"                          => "Log::Log4perl::Appender::TestBuffer", 
     214    "log4perl.appender.Buffer.min_level"                => "fatal", 
     215    "log4perl.appender.Buffer.layout"                   => "Log::Log4perl::Layout::PatternLayout", 
     216    "log4perl.appender.Buffer.layout.ConversionPattern" => "%d{yyyy-MM-dd HH:mm:ss} %5p [%M] (%F:%L) - %m%n", 
     217}); 
     218 
    120219# Make sure the module loads properly, with the exportable 
    121220# functions shared. 
    122 BEGIN { use_ok('HoneyClient::Agent') or diag("Can't load HoneyClient::Agent package.  Check to make sure the package library is correctly listed within the path."); } 
    123 require_ok('HoneyClient::Agent'); 
    124 can_ok('HoneyClient::Agent', 'init'); 
    125 can_ok('HoneyClient::Agent', 'destroy'); 
    126 use HoneyClient::Agent; 
     221BEGIN { 
     222    # Check to make sure we're in a suitable environment. 
     223    use Config; 
     224    SKIP: { 
     225        skip 'HoneyClient::Agent only works in Cygwin environment.', 1 if ($Config{osname} !~ /^cygwin$/); 
     226     
     227        use_ok('HoneyClient::Agent') or diag("Can't load HoneyClient::Agent package.  Check to make sure the package library is correctly listed within the path."); 
     228    } 
     229} 
     230 
     231# Check to make sure we're in a suitable environment. 
     232use Config; 
     233SKIP: { 
     234    skip 'HoneyClient::Agent only works in Cygwin environment.', 3 if ($Config{osname} !~ /^cygwin$/); 
     235 
     236    require_ok('HoneyClient::Agent'); 
     237    can_ok('HoneyClient::Agent', 'init'); 
     238    can_ok('HoneyClient::Agent', 'destroy'); 
     239    if ($Config{osname} =~ /^cygwin$/) { 
     240        require HoneyClient::Agent; 
     241    } 
     242} 
    127243 
    128244# Make sure HoneyClient::Util::SOAP loads. 
    …… 
    133249use HoneyClient::Util::SOAP qw(getServerHandle getClientHandle); 
    134250 
    135 # Make sure HoneyClient::Util::Config loads. 
    136 BEGIN { use_ok('HoneyClient::Util::Config', qw(getVar)) or diag("Can't load HoneyClient::Util::Config package.  Check to make sure the package library is correctly listed within the path."); } 
    137 require_ok('HoneyClient::Util::Config'); 
    138 can_ok('HoneyClient::Util::Config', 'getVar'); 
    139 use HoneyClient::Util::Config qw(getVar); 
    140  
    141 # TODO: Include FF 
    142 # Make sure HoneyClient::Agent::Driver::Browser::IE loads. 
    143 BEGIN { use_ok('HoneyClient::Agent::Driver::Browser::IE') or diag("Can't load HoneyClient::Agent::Driver::Browser::IE package.  Check to make sure the package library is correctly listed within the path."); } 
    144 require_ok('HoneyClient::Agent::Driver::Browser::IE'); 
    145 # TODO: Update this list of function names. 
    146 can_ok('HoneyClient::Agent::Driver::Browser::IE', 'new'); 
    147 can_ok('HoneyClient::Agent::Driver::Browser::IE', 'drive'); 
    148 can_ok('HoneyClient::Agent::Driver::Browser::IE', 'getNextLink'); 
    149 can_ok('HoneyClient::Agent::Driver::Browser::IE', 'next'); 
    150 can_ok('HoneyClient::Agent::Driver::Browser::IE', 'isFinished'); 
    151 can_ok('HoneyClient::Agent::Driver::Browser::IE', 'status'); 
    152 use HoneyClient::Agent::Driver::Browser::IE; 
     251# Make sure HoneyClient::Agent::Integrity loads. 
     252BEGIN { use_ok('HoneyClient::Agent::Integrity') or diag("Can't load HoneyClient::Agent::Integrity package.  Check to make sure the package library is correctly listed within the path."); } 
     253require_ok('HoneyClient::Agent::Integrity'); 
     254use HoneyClient::Agent::Integrity; 
    153255 
    154256# Make sure Storable loads. 
    155 BEGIN { use_ok('Storable', qw(freeze nfreeze thaw dclone)) or diag("Can't load Storable package.  Check to make sure the package library is correctly listed within the path."); } 
     257BEGIN { use_ok('Storable', qw(nfreeze thaw)) or diag("Can't load Storable package.  Check to make sure the package library is correctly listed within the path."); } 
    156258require_ok('Storable'); 
    157 can_ok('Storable', 'freeze'); 
    158259can_ok('Storable', 'nfreeze'); 
    159260can_ok('Storable', 'thaw'); 
    160 can_ok('Storable', 'dclone'); 
    161 use Storable qw(freeze nfreeze thaw dclone); 
     261use Storable qw(nfreeze thaw); 
    162262 
    163263# Make sure MIME::Base64 loads. 
    …… 
    168268use MIME::Base64 qw(encode_base64 decode_base64); 
    169269 
    170 #XXX: Check to see if the port number should be externalized. 
     270# Make sure DateTime::HiRes loads. 
     271BEGIN { use_ok('DateTime::HiRes') or diag("Can't load DateTime::HiRes package.  Check to make sure the package library is correctly listed within the path."); } 
     272require_ok('DateTime::HiRes'); 
     273use DateTime::HiRes; 
     274 
     275# Make sure Data::Dumper loads. 
     276BEGIN { use_ok('Data::Dumper') or diag("Can't load Data::Dumper package.  Check to make sure the package library is correctly listed within the path."); } 
     277require_ok('Data::Dumper'); 
     278use Data::Dumper; 
     279 
     280BEGIN { 
     281 
     282    # Check to make sure we're in a suitable environment. 
     283    use Config; 
     284    SKIP: { 
     285        skip 'Win32 libraries only work in a Cygwin environment.', 1 if ($Config{osname} !~ /^cygwin$/); 
     286    
     287        # Make sure Win32::Job loads. 
     288        use_ok('Win32::Job') or diag("Can't load Win32::Job package.  Check to make sure the package library is correctly listed within the path."); 
     289    } 
     290} 
     291 
     292# Check to make sure we're in a suitable environment. 
     293use Config; 
     294SKIP: { 
     295    skip 'Win32 libraries only work in a Cygwin environment.', 1 if ($Config{osname} !~ /^cygwin$/); 
     296 
     297    require_ok('Win32::Job'); 
     298    if ($Config{osname} =~ /^cygwin$/) { 
     299        require Win32::Job; 
     300    } 
     301} 
     302 
    171303# Global test variables. 
    172304our $PORT = getVar(name      => "port", 
    …… 
    184316 
    185317# Include Integrity Library 
    186 # TODO: Include corresponding unit tests. 
    187318use HoneyClient::Agent::Integrity; 
    188  
    189 # Include Thread Libraries 
    190 use threads; 
    191 use threads::shared; 
    192 use Thread::Semaphore; 
    193 use Thread::Queue; 
    194319 
    195320# Include utility access to global configuration. 
    196321use HoneyClient::Util::Config qw(getVar); 
    197322 
    198 # XXX: Remove this, eventually. 
     323# Include Dumper Library 
    199324use Data::Dumper; 
    200325 
    201326# Include Hash Serialization Utility Libraries 
    202 use Storable qw(freeze nfreeze thaw dclone); 
     327use Storable qw(nfreeze thaw); 
    203328$Storable::Deparse = 1; 
    204329$Storable::Eval = 1; 
    …… 
    207332use MIME::Base64 qw(encode_base64 decode_base64); 
    208333 
    209 # Include Data Differential Analysis Libraries 
    210 # TODO: Include corresponding unit tests. 
    211 # XXX: Do we need this? 
    212 #use Data::Diff; 
    213 # TODO: Include corresponding unit tests. 
    214 # XXX: Do we need this? 
    215 #use Data::Structure::Util qw(unbless); 
    216  
    217 # Include Data Differential Analysis Libraries 
    218 # TODO: Include corresponding unit tests. 
    219 use Data::Compare; 
     334# Include Win32 Libraries 
     335use Win32::Job; 
     336 
     337# Use ISO 8601 DateTime Libraries 
     338use DateTime::HiRes; 
    220339 
    221