root/honeyclient/branches/exp/jpuchalski-esx/etc/honeyclient.xml

<?xml version="1.0" encoding="utf-8"?>
<!--
#######################################################################
HoneyClient Configuration File

This configuration file is used by the HoneyClient perl modules in
order to specify and use the following global configuration options.

For information about the syntax of this file format, please type
"perldoc XML::Simple".

CVS: $Id$

#######################################################################

Syntax Notes:

Note: During processing, if the HoneyClient expects a module-specific
variable to be present within this configuration file (e.g., "address")
but it is not listed or commented out, then the code will attempt
to look for the same variable within any of the module's parents.

For example, the code may expect:
<HoneyClient>
    <Agent>
        <Driver>
            <address>localhost</address>
        </Driver>
    </Agent>
</HoneyClient>

But the following will work as well:
<HoneyClient>
    <Agent>
        <address>localhost</address>
    </Agent>
</HoneyClient>

<HoneyClient>
    <address>localhost</address>
</HoneyClient>

Keep in mind, though, that some variables should remain module-specific
(i.e., "port") in order to avoid collisions between modules.

-->
<HoneyClient>
    <!-- Global Options -->
    <organization description="The name of the organization that owns the host system.">
        MITRE
    </organization>
    <!-- Note: This timeout should be long enough so that the Agent watchdog code will properly let the integrity checking code finish, before detecting a faulty timeout in processing. -->
    <timeout description="Default timeout used for all communications between each module (in seconds)." default="3600">
        3600
    </timeout>
    <log_config description="The global Log4perl configuration file, used throughout all modules.  This setting should not need to be changed." default="etc/honeyclient_log.conf">
        etc/honeyclient_log.conf
    </log_config>
    <syslog_address description="The IP address of the syslog server that all logging messages will be sent to by both Agent and Manager processes over UDP port 514." default="10.0.0.1">
        10.0.0.1
    </syslog_address>
    <!-- HoneyClient::Agent Options -->
    <Agent>
        <address description="The IP or hostname that all Agent modules should use, when accepting SOAP requests." default="0.0.0.0">
            0.0.0.0
        </address>
        <!-- TODO: Update this. -->
        <!-- Note: This port should be unique and not already in use by other modules, services, or daemons running inside the VM. -->
        <port description="The TCP port number that the SOAP server for all Agent modules will listen on for requests." default="7627">
            7627
        </port>
        <allowed_drivers description="List of implemented Drivers that the Agent is allowed to run directly.">
            <name>HoneyClient::Agent::Driver::Browser::IE</name>
            <name>HoneyClient::Agent::Driver::Browser::FF</name>
        </allowed_drivers>
        <default_driver description="If no driver is manually specified, then this Driver will be used as the default by the Agent." default="HoneyClient::Agent::Driver::Browser::IE">
            HoneyClient::Agent::Driver::Browser::IE
        </default_driver>
        <!-- HoneyClient::Agent::Driver Options -->
        <Driver>
            <!-- TODO: Update this. XXX: Command-line option, eventually? -->
            <timeout description="How long the Driver waits during a drive operation, before timing out (in seconds)." default="60">
                20
            </timeout>
            <Browser>
                <IE>
                    <!-- HoneyClient::Agent::Driver::Browser::IE Options -->
                    <process_exec description="The absolute path to the Internet Explorer application process, as it sits in the VM filesystem." default="C:\Program Files\Internet Explorer\iexplore.exe">
                        C:\Program Files\Internet Explorer\iexplore.exe
                    </process_exec>
                    <process_name description="The name of the Internet Explorer executable, as it appears on the VM filesystem." default="iexplore.exe">
                        iexplore.exe
                    </process_name>
                </IE>
                <FF>
                    <!-- HoneyClient::Agent::Driver::Browser::FF Options -->
                    <process_exec description="The absolute path to the Mozilla Firefox application process, as it sits in the VM filesystem." default="C:\Program Files\Mozilla Firefox\firefox.exe">
                        C:\Program Files\Mozilla Firefox\firefox.exe
                    </process_exec>
                    <process_name description="The name of the Mozilla Firefox executable, as it appears on the VM filesystem." default="firefox.exe">
                        firefox.exe
                    </process_name>
                </FF>
            </Browser>
        </Driver>
        <perform_integrity_checks description="An integer, representing whether the Agent should perform any integrity checks. 1 enables, 0 disables." default="1">
            1
        </perform_integrity_checks>
        <!-- HoneyClient::Agent::Integrity Options -->
        <Integrity>
            <changes_found_file description="When an integrity check fails, all changes will be written to this file within the compromized honeyclient VM's filesystem." default="/tmp/changes.txt">
                /tmp/changes.txt
            </changes_found_file>
            <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">
                /tmp/realtime-changes.txt
            </realtime_changes_file>
            <!-- HoneyClient::Agent::Integrity::Test Options -->
            <Test>
                <!--
                    Note: you should *never* need to change *any* values
                    within this section of the configuration.  All contents
                    are *only* used for unit testing.
                -->
                <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">
                    t/test_integrity/realtime-changes.txt
                </realtime_changes_file>
            </Test>
        </Integrity>
    </Agent>
    <!-- TODO: Update this. -->
    <Crawler>
        <ActiveContent>
            <enable description="Enables active content parsing. 1 enables, 0 disables." default="1">
                0
            </enable>
            <Flash>
                <flasm_exec description="Path to the flasm executable." default="thirdparty/flasm/flasm.exe">
                    thirdparty/flasm/flasm.exe
                </flasm_exec>
            </Flash>
        </ActiveContent>
        <Browser>
            <!-- TODO: Update this. -->
            <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">
                1
            </ignore_links_timed_out>
            <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">
                1
            </limit_spidering>
            <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">
                5
            </max_relative_links_to_visit>
            <positive_words description="If a link contains any number of these words, then its probability of being visited (its score) will increase.">
                <word>news</word>
                <word>new</word>
                <word>big</word>
                <word>latest</word>
                <word>main</word>
                <word>update</word>
                <word>sell</word>
                <word>free</word>
                <word>buy</word>
                <word>science</word>
            </positive_words>
            <negative_words description="If a link contains any number of these words, then its probability of being visited (its score) will decrease.">
                <word>archive</word>
                <word>privacy</word>
                <word>legal</word>
                <word>disclaim</word>
                <word>about</word>
                <word>contact</word>
                <word>copyright</word>
                <word>jobs</word>
                <word>careers</word>
                <word>term</word>
            </negative_words>
        </Browser>
    </Crawler>
    <Manager>
        <num_simultaneous_clones description="Upon startup, the Manager will attempt to spawn the specified number of cloned VMs simultaneously.  To figure out an optimal value, take the amount of RAM allocated for your master VM (e.g., 256MB) and multiply that amount by this specified number (e.g., 4 simultaneous VMs x 256MB = 1GB).  You want to make sure that the total RAM requirements do not exceed the amount of RAM the host system can provision.  Allow the host system at least 512MB of RAM for normal operations." default="1">
            1
        </num_simultaneous_clones>
        <worker_startup_delay description="The amount of time (in seconds) that the Manager should wait between starting up successive clone VMs, so that the host system is not initially overwhelmed too much activity." default="300">
            300
        </worker_startup_delay>
        <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.">
            fingerprint.dump
        </fingerprint_dump>
        <address description="The IP or hostname that all Manager modules should use, when accepting SOAP requests." default="localhost">
            localhost
        </address>
        <!-- Note: This port should be unique and not already in use by other modules, services, or daemons running on the host system. -->
        <port description="The TCP port number that the SOAP server for all Manager modules will listen on for requests." default="7627">
            7627
        </port>
        <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">
            10
        </num_urls_to_process>
        <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">
            2
        </database_retry_delay>
        <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">
            1000
        </command_line_base_priority>
        <!-- HoneyClient::Manager::Database Options -->
        <Database>
            <enable description="Enables database operations. 1 enables, 0 disables." default="1">
                1
            </enable>
            <!-- TODO: Update this. -->
            <url description="The URL of the local Ruby web service, which interfaces with the local HoneyClient database.">
                http://127.0.0.1:3000/hc_database/api
            </url>
            <max_retry_count description="If the Manager is unable to contact the Ruby web service due to connectivity issues, then the Manager will retry up to the specified number of times before giving up." default="1800">
                1800
            </max_retry_count>
            <delay_between_retries description="If the Manager is unable to contact the Ruby web service due to connectivity issues, then the Manager will retry, waiting the specified amount of time (in seconds) between each retry attempt." default="2">
                2
            </delay_between_retries>
        </Database>
        <!-- HoneyClient::Manager::FW Options -->
        <FW>
            <vmnet_nat_router_address description="The IP address assigned to the VMware NAT interface (usually called vmnet8)." default="192.168.0.1">
                192.168.0.1
            </vmnet_nat_router_address>
            <!-- TODO: Update this. -->
            <address description="eth0 interface static IP">
                192.168.0.128
            </address>
            <!-- TODO: Update this to 7627, eventually. -->
            <port description="Default FW port number" default="8083">
                8083
            </port>
            <!-- TODO: Update this. -->
            <primaryDns description="Primary DNS IP Address">
                128.29.154.150
            </primaryDns>
            <!-- TODO: Update this. -->
            <secondaryDns description="Secondary DNS IP address">
                128.29.40.1
            </secondaryDns>
            <!-- TODO: Update this. -->
            <gsx_gateway description="IP address of VMware Server">
                10.0.0.1/32
            </gsx_gateway>
            <!-- TODO: Update this. -->
            <fwGateway description="Gateway IP address of the Firewall">
                10.0.0.254/32
            </fwGateway>
            <!-- TODO: Update this. -->
            <honeyclientnet description="CIDR notation for honeyclient netblock">
                10.0.0.0/24
            </honeyclientnet>
            <!-- TODO: Update this. -->
            <fwconfig description="Location of Firewall VM configuration file">
                /vm/honeywall-test/honeywall.vmx
            </fwconfig>
            <!-- TODO: Update this. -->
            <outputdir description="Output directory where logs will go on Firewall">
                fw-output
            </outputdir>
            <!-- TODO: Update this. -->
            <argus description="Argus binary location">
                /usr/local/sbin/argus
            </argus>
            <!-- TODO: Update this. -->
            <argusconfig description="Argus configuration file.">
                /etc/argus.conf
            </argusconfig>
            <!-- TODO: Update this. -->
            <argusoutput description="Argus logging directory">
                /var/log/argus
            </argusoutput>
            <!-- TODO: Update this. -->
            <arguspid description="Argus Process ID">
                /var/run/argus.pid
            </arguspid>
            <!-- TODO: Update this. -->
            <tcpdumplog description="Tcpdump log location directory">
                /var/log/tcpdump
            </tcpdumplog>
            <!-- TODO: Update this. -->
            <tcpdump description="Tcpdump binary">
                /usr/sbin/tcpdump
            </tcpdump>
            <!-- TODO: Update this. -->
            <dnspath description="DNS nameserver file">
                /etc/resolv.conf
            </dnspath>
            <!-- TODO: Update this. -->
            <dnsport description="DNS port number">
                53
            </dnsport>
            <!-- TODO: Update this. -->
            <LOCALHOST description="localhost address">
                127.0.0.1
            </LOCALHOST>
            <!-- TODO: Update this. -->
            <sshport description="SSH port number listening on">
                22
            </sshport>
            <!-- TODO: Update this. -->
            <debug description="Debug value (0 for no debugging, 1 for debugging output)">
                0
            </debug>
            <!-- TODO: Update this. -->
            <fwprocess description="Name of external SOAP listener.">
                startFWListener.pl
            </fwprocess>
            <!-- TODO: Update this. -->
            <config_file description="Location of config_file">
                etc/honeyclient_log.conf
            </config_file>
        </FW>
        <!-- HoneyClient::Manager::ESX Options -->
        <ESX>
            <service_url description="The full URL to the VIM service running on the ESX server." default="https://localhost/sdk/vimService">
                http://172.16.164.10/sdk/vimService
            </service_url>
            <user_name description="The username used to login to the VIM service running on the ESX server." default="root">
                root
            </user_name>
            <password description="The password used to login to the VIM service running on the ESX server.">
                passw0rd
            </password>
            <vm_id_length description="The length of each corresponding VM identifier (VMID).  This value can be any integer between 1 and 32, inclusive.  The VMID is a hexadecimal string that represents the VM's name.  It is designed to be generated once per clone and remain for the life of the VM (regardless of where it runs).  The VMID is used externally by HoneyClient::Manager and HoneyClient::Manager::FW.  The HoneyClient::Manager::FW package uses IPTables and binds each rule to a specific VMID.  However, IPTable's firewall rule labels can only be a maximum of 30 characters in length.  Thus, 26 is specified here, to account for 'VMID-OUT' as a possible chain name." default="26">
                26
            </vm_id_length>
            <default_quick_clone_snapshot_name description="When performing a quick clone, this value is the name of the initial snapshot that is created on the clone VM." default="Initial Snapshot - DO NOT ALTER OR RENAME THIS SNAPSHOT">
                Initial Snapshot - DO NOT ALTER OR RENAME THIS SNAPSHOT
            </default_quick_clone_snapshot_name>
            <default_quick_clone_snapshot_description description="When performing a quick clone, this value is the description of the initial snapshot that is created on the clone VM." default="">
State: Initialized - This snapshot marks the initial state of this clone VM, that is then used by all subsequent snapshots.  WARNING: If you alter delete this snapshot (or any dependent snapshots), then all dependent snapshots will become corrupted as well.
            </default_quick_clone_snapshot_description>
            <default_quick_clone_master_annotation description="When performing a quick clone, we annotate the source VM in order to inform the user to NEVER alter the source VM ever again." default="">
Type: Master VM
WARNING: DO NOT ALTER THIS VM FURTHER
OTHERWISE, ALL SUBSEQUENT CLONES WILL BE CORRUPTED
            </default_quick_clone_master_annotation>
            <operational_quick_clone_snapshot_description description="When initializing a new clone, this value is the description of the operational snapshot that is created on the clone VM." default="">
State: Operational - This snapshot marks the operational state of this clone VM.  At this point, the clone VM has a valid MAC and IP address, as well as a fully-started Agent running inside the VM.
            </operational_quick_clone_snapshot_description>
            <compromised_quick_clone_snapshot_description description="When initializing a new clone, this value is the description of a compromised snapshot that is created on the clone VM." default="">
State: Compromised - This snapshot marks a compromised state of this clone VM.  At this point, the clone VM has failed an integrity check after peforming some type of work.
            </compromised_quick_clone_snapshot_description>
            <master_vm_name description="The name of the master VM on the VMware ESX system that will be used by all subsequent cloned VMs.">
                Agent.Master-44-IE6
            </master_vm_name>
            <min_space_free description="The minimum amount of disk space (in GB) that must remain free in the primary datastore in order for the Manager to continue processing.  If the free disk space drops below this threshold, then the Manager will gracefully terminate." default="2">
                2
            </min_space_free>
            <!-- HoneyClient::Manager::ESX::Clone Options -->
            <Clone>
                <snapshot_upon_suspend description="If set to 1, then everytime a cloned VM is suspended, a snapshot of the VM will be saved upon suspend.  Set this option to 0, if you discover errors during cloning operations, where the hard disk on the VMware ESX System is overworked by slow disk operations." default="1">
                    1
                </snapshot_upon_suspend>
                <work_unit_limit description="An integer, indicating how many work units (e.g., URLs) the clone VM should process before destroying the VM and regenerating a new clone VM.  This option is useful to set, when trying to drive an application that appears to create slow memory leaks within the VM's OS.  For example, after processing X work units, the VM's OS runs out of memory altogether.  To deal with this issue, we preemptively destroy and regenerate a new clone VM at (X-1) work units, so that the leak no longer affects our operations.  To completely disable this functionality, specify -1." default="2000">
                    2000
                </work_unit_limit>
            </Clone>
            <!-- HoneyClient::Manager::ESX::Test Options -->
            <Test>
                <!--
                    Note: you should *never* need to change *any* values
                    within this section of the configuration.  All contents
                    are *only* used for unit testing.
                -->
                <test_vm_name description="The name of the test VM on the ESX server, that's used during unit testing." default="Test_VM">
                    Ubuntu_Test_VM
                </test_vm_name>
            </Test>
        </ESX>
        <!-- HoneyClient::Manager::VM Options -->
        <VM>
            <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.">
                /vm/masters/IE.7-Patched-2008-03-27-Default.Policy-Disabled.Active.Scripting-Disabled.File.Downloads-Disabled.Error.Reporting/winXPPro.cfg
            </master_vm_config>
            <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">
                7627
            </port>
            <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">
                /vm/clones
            </datastore_path>
            <snapshot_path description="The absolute path to the directory that contains all snapshot data, associated with every HoneyClient VM." default="/vm/snapshots">
                /vm/snapshots
            </snapshot_path>
            <min_space_free description="The minimum amount of disk space (in GB) that must remain free in both the datastore_path and snapshot_path in order for the Manager to continue processing.  If the free disk space drops below this threshold, then the Manager will gracefully terminate." default="2">
                2
            </min_space_free>
            <vmware_port description="The TCP port that VMware Server uses for console communication.  By default, this TCP port is 902.  Unless you've explicitly changes this port during the vmware-config.pl setup process, leave this setting as the default." default="902">
                902
            </vmware_port>
            <bin_tar description="The absolute path to the 'tar' executable, accessible on the host filesystem." default="/bin/tar">
                /bin/tar
            </bin_tar>
            <vm_id_length description="The length of each corresponding VM identifier (VMID).  This value can be any integer between 1 and 32, inclusive.  The VMID is a hexadecimal string that represents the VM's name.  It is designed to be generated once per clone and remain for the life of the VM (regardless of where it runs).  The VMID is used externally by HoneyClient::Manager and HoneyClient::Manager::FW.  The HoneyClient::Manager::FW package uses IPTables and binds each rule to a specific VMID.  However, IPTable's firewall rule labels can only be a maximum of 30 characters in length.  Thus, 26 is specified here, to account for 'VMID-OUT' as a possible chain name." default="26">
                26
            </vm_id_length>
            <dhcp_log description="The absolute path to the file that contains the DHCP logs, when a new VM gets a DHCP lease from the VMware Server." default="/var/log/messages">
                /var/log/messages
            </dhcp_log>
            <max_connect_retries description="When the VMware Server attempts to connect to any VM, it will repeatedly attempt to connect to the VM if the first attempt fails, for a maximum number of times specified by this value.  Generally, this value should not be changed, unless the host system has an exceptionally slow disk - in which case, increasing this value may help." default="5">
                5
            </max_connect_retries>
            <!-- HoneyClient::Manager::VM::Clone Options -->
            <Clone>
                <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">
                    1
                </archive_upon_suspend>
                <work_unit_limit description="An integer, indicating how many work units (e.g., URLs) the clone VM should process before destroying the VM and regenerating a new clone VM.  This option is useful to set, when trying to drive an application that appears to create slow memory leaks within the VM's OS.  For example, after processing X work units, the VM's OS runs out of memory altogether.  To deal with this issue, we preemptively destroy and regenerate a new clone VM at (X-1) work units, so that the leak no longer affects our operations.  To completely disable this functionality, specify -1." default="2000">
                    2000
                </work_unit_limit>
            </Clone>
            <!-- HoneyClient::Manager::VM::Test Options -->
            <Test>
                <!--
                    Note: you should *never* need to change *any* values
                    within this section of the configuration.  All contents
                    are *only* used for unit testing.
                -->
                <test_vm_config description="The relative path to the (empty) test VM, that's used during unit testing." default="t/test_vm/winXPPro.vmx">
                    t/test_vm/winXPPro.vmx
                </test_vm_config>
            </Test>
        </VM>
    </Manager>
    <!-- HoneyClient::Util Options -->
    <Util>
        <!-- HoneyClient::Util::Config Options -->
        <Config>
            <!-- HoneyClient::Util::Config::Test Options -->
            <Test>
                <!--
                    Note: you should *never* need to change *any* values
                    within this section of the configuration.  All contents
                    are *only* used for unit testing.
                -->
                <address description="The IP or hostname that this module should use, when performing unit tests." default="localhost" zing="foobar">localhost</address>
                <zingers>foobar</zingers>
                <Foo>
                    <Bar>
                        <address>baz</address>
                    </Bar>
                </Foo>
                <Yok>
                    <childA>12345678</childA>
                    <childA>ABCDEFGH</childA>
                    <childB>09876543</childB>
                    <childB>ZYXVTUWG</childB>
                </Yok>
            </Test>
        </Config>
    </Util>
</HoneyClient>