The BotHunter Graphical User Interface (BH-GUI) is a Java-based user interface for displaying BotHunter infection profiles and managing BotHunter's runtime operation.  BH-GUI allows you to start, shut down, and monitor the runtime operation of BotHunter, view BotHunter infection profiles, update the BotHunter ruleset, and receive malware- defense-related announcements from SRI.    

BH-GUI is part of the standard BotHunter installation.   This application requires Sun's Java Runtime Environment (JRE) Release 1.5 or later.  For the Windows XP release, Sun's JRE is installed (if necessary) as part of the standard BotHunter installation.

BH-GUI and the BotHunter analysis system are independent processes. Starting and exiting  BH-GUI will not automatically start or shut down BotHunter.  Furthermore, BH-GUI can be shut down and restarted as needed and will automatically determine the operational status of the currently running BotHunter. 

BH-GUI is started automatically when running the Windows XP and Ubunto self-booting CD versions of BotHunter.   BotHunter's Unix release starts in console mode by default, and can initiate BH-GUI via command line argument:

cta-bh%  BotHunter gui

When BH-GUI is started while there is no running BotHunter process, you will see a display window similar to that shown in Figure 1.    The Status panel (left), shows the full set of fields that are used to track BotHunter operational status when it is started.   The gray Profiles panel to the right will display summary entries for each infection profile that BotHunter may produce during its operation.  The white panel below the Profile panel will display the currently selected infection profile.   

Below the top menu bar to the left is the Run button, which starts BotHunter. 

Once BotHunter is started, the Shutdown and Update Status buttons will be enabled, and a subset of currently available status attributes will be shown in the status panel (see Section Status Panel for more details on each status field).

Figure 2 illustrates an example runtime display of BotHunter.   The BotHunter Profiles panel is blank during normal operations and will be populated when only BotHunter finds and reports an infected machine inside your network.  To view the infection profile in the panel below, select the entry by clicking on it.  Double clicking on the entry will spawn a popup window containing the profile, which is useful for comparing multiple profiles side by side.

The BH-GUI Status panel is used to monitor the status of the BotHunter systems.  The full set of status fields is shown in Figure 3 (left panel).  Prior to starting BotHunter, all fields are blank.  Once BotHunter is started, the subset of status fields with values to report are shown (right panel).   Status panel updates may be performed manually, by clicking on the Update Status button above the status panel.  You may also set the automatic status panel update interval by adjusting the time units to the right of the Update Status button.       

The status panel is useful for identifying potential errors that may arise during BotHunter operations.   For example, the command retries field will be shown when there are repeated failed attempts to start Snort, e.g., due to network interface errors or possible misconfiguration. To further analyze the cause of Snort errors, you may view the last 15 lines of the Snort stderr log using Ctrl-E (show Snort stderr, under the BotHunter menu item).   The status panel also indicates when BotHunter is unable to interact with the BotHunter repository, and therefore unable to receive dynamic rule updates.   Finally, under some conditions, unreliable repository communications may cause BotHunter to lose messages, as indicated by the Messages lost field.  This may be due to unreliable network connections or maintenance with SRI's BotHunter update server.

Before BotHunter is Started		After BotHunter is Started

The following is a brief description of the status panel fields:

Last status	Time of the last status update
Started	BotHunter process start time
Elapsed	Time elapsed since BotHunter process started
Memory Usage	Current BotHunter process memory usage
"Command retries	Snort retry count due to failures
Command restarts	Snort restart count due to updates
Last restart	Time of last Snort retry due to failure.  The last restart count is distinct from the last entry count.  Restarts are due to updates and are not caused be errors.
Lines read	Number of lines of Snort input read
Lines parsed	Number of lines of Snort input parsed into events
Local bot profiles	Number of BotHunter text profiles written
NetQuery requests	Number of NetQuery requests made
NetQuery responses	Number of NetQuery requests received
Bot message	Number of Bot profile messages sent to repository
Messages queued	Number of profile and NetQuery messages queued for repository
Messages sent	Number of profile and NetQuery messages sent to repository
Messages lost	Number of profile and NetQuery messages lost
Repository status	Status of sensor connection to repository
Connection failure	Last repository connection failure
Author ID	Most recently seen author ID
Observer ID	Most recently seen observer ID

In addition to providing live monitoring of BotHunter, BH-GUI also allows you to view infection profile logs produced from prior runs of BotHunter.  You can load a prior infection profile log through the File menu under the Prior Runs option.    Prior runs may be opened in parallel with monitoring the currently running BotHunter.   When a prior run is selected, a new  infection profile display panel is created.  The status panel is not displayed while prior runs are analyzed, as this panel is applicable only for displaying attributes of an active BotHunter process.   Figure 4 illustrates an example prior run view.

Each profile display panel is associated with a tab directly above the panel, and you may move across display panels by selecting the associated tab.  When you have completed viewing a prior infection profile log, use the Close Tab button on the bottom right corner of the panel to close the panel.

Four options are available from the top Menu bar of BH-GUI:  File, BotHunter, Window, and Help. 

The File menu  allows you to alter the application preferences, select prior runs or alternate BotHunter configurations (applicable to the Unix release), and exit BH-GUI. 



The BotHunter menu is used to control interactions with the BotHunter system.  You may start and  shut down BotHunter, or initiate a status update directly from this menu, or through the corresponding Run, Shutdown, or Update buttons, available on the main display. The show snort stderr option allows you to view the last set of standard error messages produced from Snort (for diagnostic purposes).   The remote update option, when enabled, indicates that rule and configuration updates are available for BotHunter to download and use.



The Window menu is used to control the display of the main BH-GUI and its popup display windows.



The Help menu provides access to BH-GUI version information, and access to all BotHunter- related online documentation via your default browser.   You can also connect to the Malware Threat Center for other project-related information.  

The Preferences option under File Menu allows you to configure various BH-GUI application options.  Four option panels are available for configuring BH-GUI: Profile, Toolbar, Visual Display, and Misc.

The Profile tab allows you to configure the field display for the infection profile panel.   The prof_columns property allows you to select which columns will be displayed. The prof_sorting property allows you to select the default sorting fields when displaying infection profiles. The sorting will consider the order in which the fields are listed (e.g., the second sorting field will only be used when the values of the first sorting field are equal). The user may add or remove a new "temporary" primary sorting key by successively clicking on the field heading name at the top of the profile table. The prof_timefmt allows you to select the time display format.  

Note: when you modify a field, click to another field to set the change before selecting the OK button. 

The Toolbar tab allows you to set  properties of the toolbar buttons on the main display panel.  The tb_status_update property allows you to display or suppress the manual update button, and the tb_status_update_ival property allows you to display or suppress the update interval timer.   The tb_snort_stderr property allows you to display the Snort stderr button (Ctrl-E), which is disabled by default.  The tb_remote_update property allows you to display or suppress the remote update button, which when enabled indicates that a new rule update package is available for BotHunter to download.  Note that BotHunter is by default configured to automatically download the latest ruleset updates, and therefore this button may be disabled, even when new updates are made available.

The Visual tab allows you to select foreground and background display colors, and display properties such as line wrap, time format, and message display count.

The Misc tab allows you to select miscellaneous timing and control properties that BH-GUI will use when interacting with the BotHunter system.  

BH-GUI is shut down using the Quit option under the File Menu.  Note that BH-GUI is an independent application, and shutting down the BH-GUI does not shut down BotHunter.  When you can restart BH-GUI, it will automatically detect whether a BotHunter process is currently operating and if so will display its current state.     If you wish to shut down BotHunter, you can use the Shutdown button on the main display (above the Status panel).

The BotHunter team gratefully acknowledges those increasingly fewer U.S. funding agencies that are actively supporting new research in information security.    We especially thank Cliff Wang at ARO for his support of the Cyber-TA project and  BotHunter.