Welcome to the BotHunter User Guide. This living document describe how to install, configure, and operate BotHunter on Linux, FreeBSD, MacOS, Windows, and our Live-CD Release (ISO CD image). Please send us feedback as you find mistakes and material that is unclear or incomplete, and we will endeavor to improve this online document so all may benefit.
When you register to download BotHunter, you must indicate which version of BotHunter you wish to use: Windows, Unix, or Live CD. We will then send you an email with a link to the appropriate release.

A LITTLE BACKGROUND: BotHunter is a new network defensive system design to help everyone from network adminstrators to individual Internet-connected PC users detect whether their systems are running coordination-centric malware (such as botnets, spambots, spyware, Trojan exfiltrators, worms, adware). It is based on an algorithm called network dialog correlation, developed under the Cyber-TA research program, in the Computer Science Laboratory at SRI International. BotHunter is NOT an intrusion detection system, firewall, spam blocker, or antivirus tool. These tools generally don't work in helping you rid your network of malware infections. BotHunter takes a different approach.

BotHunter monitors the two-way communication flows between hosts within your internal network and the Internet. It aggressively classifies data exchanges that cross your network boundary as potential dialog steps in the life cycle of an ongoing malware infection. BotHunter employs Snort as a dialog event generator, and Snort is heavily modified and customized to conduct this dialog classification process. Dialog events are then fed directly into a separate dialog correlation engine, where BotHunter maps each host's dialog production patterns against an abstract malware infection life cycle model. When enough evidence is acquired to declare a host infected, BotHunter produces an infection profile to summarize all evidence it has gathered regarding the infection.

Your system should have a modern Intel Pentium-class or Motorola PowerPC processor, at least 1 GB RAM, and at least 1 Ethernet NIC/WIC for network monitoring.

BotHunter performs some outbound communications to the SRI automated threat intelligence updating service and infection profile repository. BotHunter's threat updating service periodically probes the BotHunter repository server (located at SRI International, California, USA) to pull in the latest botnet command and control (C&C) blacklist, malware DNS list, and new malware detection rules, which are updated on a regular basis. This allows your fielded BotHunter to maintain its awareness of the latest C&C servers, malware-associated DNS lookups, Russian Business Network address space, and malware control/backdoor ports. The repository service allows your fielded BotHunter to send anonymized infection profiles of detected external C&C's, egg download sites, exploit sources, and rule detection patterns. It does not report any IP addresses from your trusted net, and BotProfile sources are anonymized and are not tracked.

To utilize the BotHunter automated remote updating service, you must enable outbound connections from your BotHunter host to TCP ports 5242 and 6282. You may disable these outbound connections and your BotHunter will function, but it will not be able to receive new threat intelligence from our remote updating service.

Our policy is that you must enable BotHunter's anonymous repository reporting system in order to receive dynamic updates via our automated threat intelligence updating service. When you enable anonymous repository reporting, you are contributing Internet infection data to a knowledge base that is driving in depth research activities while also contributing to the body of threat intelligence from which all BotHunter users benefit. You are making a contribution to help us ALL better fight Internet malware.

Installation requires Internet connectivity for downloading the necessary libraries, packages, and BotHunter ruleset updates.

For site-wide network monitoring, your target platform should have promiscuous-mode access to broadcast LAN traffic via port mirroring (e.g., Cisco Switched Port Analyzer (SPAN), 3COM Roving Analysis Port (RAP)). Ideally, your machine should be attached to a monitoring position on an internal network egress point to observe successful connection flows.

We strongly recommend that you place BotHunter behind your firewall. It does not need to monitor incoming packets that are blocked from entry to your net. See BotHunter Behind or In Front of Firewall for configuring BotHunter when the tap is in front of a firewall.

The following is a summary of the minimum steps necessary to install, configure, and start BotHunter, in its default configuration for live traffic monitoring on Unix. Installation and startup proceed in two phaes: 1) a root user phase in which all packages are set up and the BotHunter user account is established, and 2) the BotHunter user configuration phase, in which you can choose to start BotHunter or revise its configuration.

* Root privilege is required to install BotHunter: While installation requires root privilege, BotHunter will not require root privilege to run. A nonprivileged account will be created to run BotHunter.

* Basic network configuration data is required:

The Windows release of BotHunter is designed for PC monitoring.  The Windows BotHunter configuration is performed during the installation process.    The Unix releases of BotHunter provide a comprehensive configuration interface to customize BotHunter for network deployment.  This section describes the Unix configuration features.

Express Mode Setup

The BotHunter configuration menu will be in 'express mode' by default, which provides the basic configuration options appropriate for most users. More detailed configuration control is available by switching to 'Custom' configuration mode. The following summarizes BotHunter's express mode configuration. If you wish to enter custom mode, follow the online help using the '?' response to all configuration prompts.

BotHunter has additional capabilities available through the "custom" configuration mode. This section documents some of the more frequently requested options. To enter "custom" configuration mode:


1. Enter BotHunter user configuration mode, using the BotHunter shell alias:

   cta-bh% BotHunter configure

2. Enter custom configuration mode by entering "custom" at the configuration prompt:

        Enter the number of the section to alter,
        "?"       for help on this prompt,
        "custom"  to switch to custom configure mode.
        "reset"   to restore the configuration to the "factory defaults",
        "abort"   to abort the installation and exit, or
        "done"    to save this new configuration (default: done):

BotHunter Behind or In Front of Firewall

If you must install BotHunter in front of your firewall, then enter "custom" user configuration mode and modify section "1" (Input Parameters) and hit enter to use the default for all prompts until you reach the prompt:

Are the packets examined by Snort from behind a firewall (default: true):

Enter "no" to inform BotHunter to adjust its exploit detection weights for a network tap placed in front of your firewall.

Infection Log Roll-over

BotHunter has the ability to automaticly roll-over the infection log to a new file based on time, size, or number of reports. To enable this feature, enter "custom" user configuration mode and modify section "3" (Output parameters) and hit enter to use the default for all prompts until you reach the prompt:

  Enter the name of the text output log file (default:
    botHunterResults_%dt.txt):

If the log file name you use for this prompt, like the default, includes special substitution elements (e.g., the "%dt" in the default, which will be replaced with a path-safe current timestamp) then the next three prompts will allow you to set the roll-over criteria for the infection log. Note that if your log does roll over, the GUI will only display the alerts from the latest file (the "Local bot profiles" count in the status panel is the cumulative count for the process, which will no longer match the count displayed in the "Current" tab heading).

Email Notification

BotHunter has the ability to send infection reports via e-mail. This feature is independent of any other infection reporting mechanism (e.g., it can be used in addition to, or instead of, the GUI). To enable this feature, enter "custom" user configuration mode and modify section "3" (Output parameters) and hit enter to use the default for all prompts until you reach the prompt:

  Enter the mail "to" destination (default ""):

Where you may now enter the destination e-mail address for all alerts. If an email address is supplied (use "none" at this prompt to disable this feature), you will then be prompted for the mail server to direct the mail (it will default to the first mail server specified in the Snort configuration section), the "from" email address, and the subject line.

ArcSight CEF Alerts

BotHunter has the ability to generate infection reports in the ArcSight Common Event Format. This feature is independent of any other infection reporting mechanism (e.g., it can be used in addition to, or instead of, the GUI). To enable this feature, enter "custom" user configuration mode and modify section "3" (Output parameters) and hit enter to use the default for all prompts until you reach the prompt:

  Enter the name of the file to receive ArcSight Common Event Format
  alerts (default: none):

Where you may now enter the name of the file to receive CEF alerts. Use the special name "none" to disable this feature, or "out" if you want the data written to the standard output stream.

Saved Snort log

When run in live-pipe mode (input mode "1"), BotHunter has the ability to save the Snort alert text logs used as input to the dialog correlation step and to roll over those log files based on time or size. Enter "custom" user configuration mode and modify section "1" (Input Parameters) and hit enter to use the default for all prompts until you reach the prompt:

  Enter the log file name to receive a local copy of the raw input
  data (use "none" for no local copy, default none):

You may now enter a log file name. If the log file name includes special substitution elements (e.g., "snort_alerts_%du.log"; type a "?" at the prompt to see a list), then you will get two additional prompts to configure the roll-over criteria.

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.