NAME

HoneyClient::Agent - Perl extension to instantiate a SOAP server that provides a central interface for all agent-based HoneyClient operations.

VERSION

0.98

SYNOPSIS

CREATING THE SOAP SERVER

# XXX: Fill this in.

INTERACTING WITH THE SOAP SERVER

# XXX: Fill this in.

DESCRIPTION

This library creates a SOAP server within the HoneyClient VM, allowing the HoneyClient::Manager to perform agent-based operations within the VM.

LOCAL FUNCTIONS

The following init() and destroy() functions are the only direct calls required to startup and shutdown the SOAP server.

All other interactions with this daemon should be performed as SOAP::Lite function calls, in order to ensure consistency across client sessions. See the "EXTERNAL SOAP FUNCTIONS" section, for more details.

HoneyClient::Agent->init(address => $localAddr, port => $localPort, ...)

Starts a new SOAP server, within a child process.

Inputs: $localAddr is an optional argument, specifying the IP address for the SOAP server to listen on. $localPort is an optional argument, specifying the TCP port for the SOAP server to listen on.

Additionally optional, driver-specific arguments can be specified as sub-hashtables, where the top-level key corresponds to the name of the implemented driver and the value contains all the expected hash data that can be fed to HoneyClient::Agent::Driver->new() instances.

 Here is an example set of arguments:

   HoneyClient::Agent->init(
       address => '127.0.0.1',
       port    => 9000,
       IE      => {
           timeout => 30,
           links_to_visit => {
               'http://www.mitre.org/' => 1,
           },
       },
   );

 

Output: The full URL of the web service provided by the SOAP server.

HoneyClient::Agent->destroy()

Terminates the SOAP server within the child process.

Output: True if successful, false otherwise.

EXTERNAL SOAP FUNCTIONS

run(driver_name => $driverName)

Runs the Agent for one cycle. In this cycle, the following happens:

1)

The specified Driver is driven for multiple work units, where each consecutive drive operation contacts the same network resources (aka. "targets"). The Driver ceases its operation, as soon as it has exhausted all targets or until it is ready to contact a different set of targets.

2)

Once the specified driver has stopped, the Agent performs a corresponding Integrity check.

# XXX: Fill this in.

Inputs: $driverName is the name of the Driver to use, when running this cycle.

Output: Returns true if the Agent successfully started a new cycle; returns false, if the Agent is still running an existing cycle and has not finished yet.

Notes: During a single run() cycle, it is expected that the driven application will only contact the same targets. This allows the Manager to update firewall rules between cycles.

#=begin testing # # XXX: Fill this in. # #=end testing

BUGS & ASSUMPTIONS

# XXX: Fill this in.

SEE ALSO

http://www.honeyclient.org/trac

REPORTING BUGS

http://www.honeyclient.org/trac/newticket

ACKNOWLEDGEMENTS

Paul Kulchenko for developing the SOAP::Lite module.

AUTHORS

Kathy Wang, <knwang@mitre.org>

Thanh Truong, <ttruong@mitre.org>

Darien Kindlund, <kindlund@mitre.org>

COPYRIGHT & LICENSE

Copyright (C) 2007 The MITRE Corporation. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, using version 2 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

cpanm HoneyClient::Agent

perl -MCPAN -e shell
install HoneyClient::Agent