TracNav menu

Definitions

The Honeyclient architecture consists of the following terms and components:

  1. Network Terms
    1. Honeyclient VM
    2. Firewall VM
    3. Host System
    4. Remote Resource
    5. Internal Network
    6. DMZ Network
  2. Software Components
    1. HoneyClient::Agent
      1. HoneyClient::Agent::Driver
      2. HoneyClient::Agent::Driver::Browser
      3. HoneyClient::Agent::Driver::Browser::IE
      4. HoneyClient::Agent::Driver::Browser::FF
      5. HoneyClient::Agent::Integrity
        1. Registry
        2. File System
    2. HoneyClient::Manager
      1. HoneyClient::Manager::FW
      2. HoneyClient::Manager::VM
    3. HoneyClient::Util
      1. HoneyClient::Util::Config
      2. HoneyClient::Util::SOAP

Network Terms

The Architecture Definitions Diagram on the right illustrates each of the following network terms.

Architecture Definitions

Honeyclient VM

The Honeyclient VM (herein referred to as simply a "honeyclient") is a virtual machine (VM), designed to instrument (or drive) a locally running, target application to one or more remote resources. The purpose of this operation is to verify if the fetched content from each remote resource is malicious in nature, such that the honeyclient becomes compromised as a result of target application processing any of the content.

In this architecture, normal honeyclients are a:

  • VMware virtual machine
  • running a variant of the Microsoft Windows operating system
  • configured to automatically login as system administrator upon boot
  • and upon login, automatically execute the HoneyClient::Agent daemon inside a Cygwin environment

Note: Since Microsoft Windows is a commercial operating system, users are expected to create their own honeyclient, as directed in the user guide.

Firewall VM

The Firewall VM (herein referred to as simply a "firewall") is a virtual machine (VM), designed to route and filter honeyclient traffic between the internal network and the DMZ network. As a honeyclient is driven to a remote resource, the firewall is configured to permit that honeyclient to access the minimum set of resources required to process all fetched content from the remote resource.

For example, if the host system were to drive a honeyclient to the http://www.cnn.com page, the firewall would allow the honeyclient to contact all web servers that mapped to www.cnn.com (including any additional servers that may host external inline content, such as externally linked advertisements from http://www.doubleclick.net) over TCP port 80. Once the firewall grants the honeyclient access, the honeyclient is then signaled to drive to www.cnn.com.

Note: The HoneyClient::Agent::Driver::Browser::IE package currently does not support the ability to properly render external inline content on any website.
This is a currently open issue, documented as ticket #27.

In this architecture, a firewall is a:

Note: Since variants of the Honeywall CDROM Roo distribution can be distributed freely, a pre-configured version of the Firewall VM is provided (as listed in the user guide). This allows users to quickly setup and configure this component — rather than installing and configuring a comparable VM from scratch.

Note: The HoneyClient::Manager::FW daemon can run on any Linux distribution running kernel version 2.4 or higher, as the daemon not does currently leverage any special features/functionality within the Roo distribution (other than iptables). However, expect this to change eventually, as the HoneyClient::Manager::FW daemon starts to use these distribution-specific capabilities.

Host System

The Host System (herein referred to as simply the "host") is a Linux-based physical server, designed to manage each honeyclient and route honeyclient traffic between the DMZ network and the internet, in order for a honeyclient to access a specific remote resource.

In this architecture, the host is a:

Note: Users are expected to create their own host, as directed in the user guide.

Note: The HoneyClient::Manager client can run on any Linux OS capable of running VMware Server. The Gentoo Linux distribution was chosen, due to its flexible configuration and ease of use.

Remote Resource

A Remote Resource (herein referred to as simply a "resource") is any networked server, capable of delivering content to the honeyclient using known protocols over the internet. For example, valid resources can be web servers, mail servers, and FTP servers.

Note: Currently, honeyclients can be driven to only target resources capable of hosting content over HTTP. However, as more drivers are implemented, this architecture can grow to support other applications and protocols.

Internal Network

The Internal Network is a virtual, VMware host-only network designed to relay traffic between all honeyclients and the firewall.

Note: Users are expected to create this internal network upon configuring the host, as directed in the user guide.

DMZ Network

The DMZ Network is a virtual, VMware NAT-based network designed to relay traffic between the firewall and the internet.

Note: Users are expected to create this DMZ network upon configuring the host, as directed in the user guide.

Component Definitions

Software Components

Fundamentally, the Honeyclient architecture is a Perl-based client/server architecture, where SOAP::Lite is used as the communications mechanism. SOAP::Lite was chosen, due to its flexibility to support a wide range of protocols.

The Component Diagram on the right illustrates each of the following components are installed inside the network architecture. Furthermore, see the Data Flow Diagram, which illustrates how each component communicates in this system.

HoneyClient::Agent

The Agent component is a Perl-based SOAP server, running as a daemon within the Cygwin environment on the honeyclient VM. Once the honeyclient OS boots and automatically logs in with Administrator privileges, this daemon is configured to startup by default.

This component's role is to solely service SOAP requests from the Manager, which include:

  • HoneyClient::Agent->run()
    • instrumenting the target application via a specific driver implementation
  • HoneyClient::Agent->getState()
    • reporting the latest driver state
  • HoneyClient::Agent->updateState()
    • allowing the Manager to modify any portion of the latest driver state
  • HoneyClient::Agent->getStatus()
    • reporting the latest statistical information about the current driver state
  • HoneyClient::Agent->shutdown()
    • shutting down the Agent

HoneyClient::Agent::Driver

The Driver component is a Perl-based interface (API), representing and enforcing common SOAP methods that every child Driver object must implement. The intent of this package is to be a Perl-equivalent type of Java-based interface file.

Each Driver implementation must define a corresponding work unit. This is the smallest, repetitive action performed by the target application, where each action may cause the target application to process one or more resource (e.g., view one page, download one file, receive one email).

Perl objects that implement the Driver interface, are solely designed to service local requests from the Agent, which include:

  • HoneyClient::Agent::Driver->new()
    • creating a new object (complete with initial state) and initializing the target application for instrumentation
  • HoneyClient::Agent::Driver->drive()
    • driving the target application for one work unit
  • HoneyClient::Agent::Driver->isFinished()
    • signaling when the Driver has exhausted all possible resources to process and requires additional input from the Manager (via the Agent) to proceed further
  • HoneyClient::Agent::Driver->next()
    • reporting next set of resources that the Driver will contact, upon the next drive() call
      (This used to ultimately signal the firewall to allow the honeyclient to access the next set of resources, in order to properly allow the Driver to process the next work unit.)
  • HoneyClient::Agent::Driver->status()
    • reporting status information about the Driver's work unit progress so far

This architecture provides two initial driver implementations that can instrument the following target applications:

TODO: The rest of this page is currently a work-in-progress and is subject to change frequently. If you would like to monitor changes to this page, feel free to subscribe for notifications.

HoneyClient::Agent::Driver::Browser

HoneyClient::Agent::Driver::Browser::IE

  • Maintaining driver state, including keeping track of:
    • Resources the driver has processed
    • Resources the driver was unable to process (and has subsequently ignored)
    • Resources the driver has yet to visit

Note: The HoneyClient::Agent::Driver::Browser::IE package currently does not support the ability to properly render external inline content on any website.
This is a currently open issue, documented as ticket #27.

HoneyClient::Agent::Driver::Browser::FF

HoneyClient::Agent::Integrity

The Integrity component is a centralized interface for the Agent to easily access all integrity-checking capabilities.

An Integrity object offers the following public methods to the Agent:

  • HoneyClient::Agent::Integrity->new()
    • creates a new Integrity object and baselines the honeyclient OS, using all available child HoneyClient::Agent::Integrity::* packages
  • HoneyClient::Agent::Integrity->check()
    • checks the honeyclient OS against the previously recorded baseline, using all available child HoneyClient::Agent::Integrity::* packages, and reports a list of changes found within the honeyclient OS, if any were found
Registry

By default, the following registry hives in the Windows OS are checked: 

HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

By default, all keys and values in these registry hives are analyzed — except for keys and values in the following regex paths: 

    $key_dirnames_to_ignore = [ 
        '^HKEY_CURRENT_USER\\\SessionInformation.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Internet Explorer\\\Main$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Internet Explorer\\\Security\\\AntiPhishing.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Internet Explorer\\\TypedURLs$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Explorer\\\MenuOrder\\\Favorites\\\Links.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Explorer\\\MountPoints2\\\CPC\\\Volume.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Explorer\\\UserAssist\\\.+\\\Count.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Ext\\\Stats\\\.+\\\iexplore.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Internet Settings\\\Connections.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Internet Settings\\\5.0\\\Cache.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\ShellNoRoam\\\BagMRU.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\ShellNoRoam\\\MUICache.*$',
        '^HKEY_CURRENT_USER\\\Volatile Environment$',
        '^HKEY_LOCAL_MACHINE\\\SOFTWARE\\\Microsoft\\\Cryptography\\\RNG$',
        '^HKEY_LOCAL_MACHINE\\\SOFTWARE\\\Microsoft\\\Windows\\\CurrentVersion\\\BITS$',
        '^HKEY_LOCAL_MACHINE\\\SOFTWARE\\\Microsoft\\\Windows\\\CurrentVersion\\\Group Policy\\\State\\\Machine\\\Extension-List\\\.*$',
        '^HKEY_LOCAL_MACHINE\\\SOFTWARE\\\Microsoft\\\Windows\\\CurrentVersion\\\WindowsUpdate\\\.*$',
        '^HKEY_LOCAL_MACHINE\\\SOFTWARE\\\Microsoft\\\Windows\\\CurrentVersion\\\WindowsUpdate\\\Auto Update.*$', 
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\ControlSet.+\\\Services\\\.+\\\Parameters\\\Tcpip.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\ControlSet.+\\\Services\\\Dhcp\\\Parameters.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\ControlSet.+\\\Services\\\Eventlog\\\Application\\\ESENT.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\ControlSet.+\\\Services\\\SharedAccess\\\Epoch.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\ControlSet.+\\\Services\\\Tcpip\\\Parameters\\\Interfaces\\\.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\CurrentControlSet\\\Services\\\Dhcp\\\Parameters.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\CurrentControlSet\\\Services\\\Eventlog\\\Application\\\ESENT.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\CurrentControlSet\\\Services\\\Tcpip\\\Parameters\\\Interfaces\\\.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\CurrentControlSet\\\Services\\\.+\\\Parameters\\\Tcpip.*$',
        '^HKEY_USERS\\\.+\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Explorer\\\UserAssist\\\.+\\\Count.*$', 
        '^HKEY_USERS\\\.+\\\Software\\\Microsoft\\\Windows\\\ShellNoRoam\\\BagMRU.*$',
        '^HKEY_USERS\\\.+\\\UNICODE Program Groups.*$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Internet Explorer\\\Main$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Internet Explorer\\\Security\\\AntiPhishing.*$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Internet Explorer\\\TypedURLs$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Explorer\\\MenuOrder\\\Favorites\\\Links.*$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Explorer\\\MountPoints2\\\CPC\\\Volume.*$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Ext\\\Stats\\\.+\\\iexplore.*$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Internet Settings\\\Connections.*$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Internet Settings\\\5.0\\\Cache.*$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Windows\\\ShellNoRoam\\\MUICache.*$',
    ];
File System

By default, all files and directories in the Windows OS file system are checked — except for files and directories in the following Cygwin-based regex paths: 

/cygdrive/c/cygwin/tmp/changes.txt
/cygdrive/c/cygwin/tmp/cleanfile.txt
/cygdrive/c/cygwin/home/Administrator/
/cygdrive/c/Documents and Settings/Administrator/Desktop/honeyclient
/cygdrive/c/WINDOWS/Prefetch/
/cygdrive/c/WINDOWS/WindowsUpdate.log
/cygdrive/c/WINDOWS/Debug/UserMode/userenv.log
/cygdrive/c/WINDOWS/SoftwareDistribution/DataStore/
/cygdrive/c/WINDOWS/SchedLgU.Txt
/cygdrive/c/WINDOWS/SoftwareDistribution/ReportingEvents.log
/cygdrive/c/WINDOWS/system32/config/SysEvent.Evt
/cygdrive/c/WINDOWS/system32/wbem/
/cygdrive/c/WINDOWS/PCHEALTH/HELPCTR/DataColl/
/cygdrive/c/Documents and Settings/All Users/Application Data/Microsoft/Network/Downloader/
/cygdrive/c/Documents and Settings/Administrator/Application Data/Mozilla/Firefox/Profiles/
/cygdrive/c/Documents and Settings/Administrator/Local Settings/Application Data/Mozilla/Firefox/Profiles/
/cygdrive/c/Documents and Settings/Administrator/Application Data/Talkback/MozillaOrg/Firefox15/Win32/2006050817/permdata.box
/cygdrive/c/Documents and Settings/Administrator/Cookies/index.dat
/cygdrive/c/Documents and Settings/Administrator/Local Settings/History/History.IE5/
/cygdrive/c/Documents and Settings/Administrator/Local Settings/Temporary Internet Files/Content.IE5
/cygdrive/c/Documents and Settings/Administrator/Recent/
/cygdrive/c/Program Files/Mozilla Firefox/updates/
/cygdrive/c/Program Files/Mozilla Firefox/active-update.xml
/cygdrive/c/Program Files/Mozilla Firefox/updates.xml
/cygdrive/c/WINDOWS/SoftwareDistribution/WuRedir/

HoneyClient::Manager

HoneyClient::Manager::FW

HoneyClient::Manager::VM

HoneyClient::Util

HoneyClient::Util::Config

HoneyClient::Util::SOAP

Note: Currently, all SOAP communication occurs using the HTTP protocol. By default, this protocol provides little security in terms of confidentiality and integrity. This is a known issue and has been documented as ticket #28 already. Eventually, the system will use certificate-based HTTPS mutual authentication instead.

Attachments