Figure: The Bro Directory Structure

The bro/bin Directory
=====================

The bin directory is the storage area for executable binary files used by Bro.

adtrace
.......

adtrace retrieves MAC and IP address information from tcpdump trace files

     usage:

                   adtrace <trace-file>

bro
...

This program is the primary Bro executable. Full use of the bro command is documented in the technical manual.

cf
..

A program that converts UNIX epoch time into a conventional date.  Most of the raw Bro logs record UNIX epoch time as the timestamp for their records.  Piping the file through cf will convert the time.  Full use of cf is documented in the technical manual.

rst
...

A program that Bro calls to form and send a reset packet which will tear down a tcp connection.  The use of rst is documented in the Technical Manual and in chapter ### of the User Manual.

The bro/etc Directory
=====================

Configuration and other ancillary files are stored in the etc directory.  These files are usually changed by supplimentary configuration tools supplied with the Bro distribution. Direct editing of these files is discouraged. If direct edits are made, the changes may be reversed or deleted during subsequent Bro updates.

alert_scores
............

This file contains ranking numbers for alarms (the use of the term "alert" is vestigial and will be changed in the future).  The ranking numbers are used as part of the ranking system for determining the success likelihood of an incident triggering a specific alarm.

bro.cfg
.......

This file contains configuration criteria for operational parameters.  Most of the parameters are set during the installation process and can be changed using the bro- config script.

bro.cfg.example
...............

A annotated, generic bro.cfg file.  This file is not used by Bro.  It is supplied for documentation purposes.

bro.rc
......

This is the script for controlled starting and stopping of Bro.  See section ### for its use.

bro.rc-hooks.sh
...............

This script is called by bro.rc at various points during the starting and stopping of Bro.  It is presented as an interface for customizations into the start and stop process.

signature_scores
................

This file contains ranking numbers for signatures.  The ranking numbers are used as part of the ranking system for determining the success likelyhood of an incident triggering a specific signature.

VERSION
.......

A file containing the Bro version number for the installed distribution.

The bro/var Directory
=====================

Temporary information about the current Bro instance is stored in the var directory.

autorestart
...........

Contains the word "ON" if Bro is configured to autorestart.

pid
...

Contains the process ID number for the current instance of Bro.

start_time
..........

Contains the date and time when the current instance of Bro was started.

The bro/scripts Directory
=========================

This directory contains a number of auxiliary scripts used to suppliment Bro's operation.

bro-config
..........

A utility script for changing the Bro operational parameters in the bro.cfg file.

bro-logchk.pl
.............

Currently, this file does not work

A utility program for searching ftp and http log files for activity by specific ip addresses.

     Usage:
        bro-logchk.pl -[hrDFHds] -f filename -a ipaddr -x ipaddr
            -h          print this usage information
            -F          using ftp log
            -H          using http log
            -r          try to resolve IP addresses to hostnames
            -f file     log file to parse
            -a ipaddr   only output connections from this address
            -s          only want matching source address (used with -a )
            -d          only want matching dest address (used with -a )
            -D          debug option
            -x ipaddr   exclude connections from this address

bro_log_compress.sh
...................

A very simple script written to manage log and coredump files.  By default it compresses log files older than 30 days and sends them to the archive directory; it deletes log files older than 60 days; and it deletes coredump files older than 4 days.

     Restrictions:

       * Must be run from a user account that has read/write/execute access to files in the $BROHOME directory.

host-grep
.........

Greps a Bro connection summary log on stdin for two given hostnames.

     Usage:

                host-grep [-a] hostname hostname < connection_log
                If -a is specified then we only want lines with *all* of the listed hosts.

     Restrictions:

       * Must have $BROHOME/scripts included in the PATH environment variable.

       * Will only work with hostnames.  ip addresses are not accepted

       * Uses host-to-addrs and ip-grep scripts

host-to-addrs
.............

Finds all ip addresses associated with a given hostname.

     Usage:

                host-to-addrs hostname

     Restrictions:

       * Must have $BROHOME/scripts included in the PATH environment variable.

       * Will only work with hostnames.  IP addresses are not accepted

ip-grep
.......

Returns an exact grep pattern for matching the IP addresses of the given hosts

     Usage:

          ip-grep hostname hostname ...

     Restrictions:

       * Must have $BROHOME/scripts included in the PATH environment variable.

       * Will only work with hostnames.  ip addresses are not accepted

       * Uses host-to-addrs script

site-report.pl
..............

This script produces the daily consolidated site report.  By default, it is run daily via the cron job submitted by the bro user via files in /var/cron/tabs.

The bro/scripts/pm Directory
............................

This directory contains perl modules to support the perl scripts in the scripts directory.

The bro/policy Directory
========================

This directory contains all standard Bro policy files.  For more information about the policy files see section ###, Policy

Signature support files:

sig-addendum.sig
................

This file contains small support utilities that are used in the implementation of Bro signatures.

sig-functions.bro
.................

To be completed

sig-action.bro
..............

To be completed

Policy files:

  * active.bro

  * alarm.bro

  * analy.bro

  * anon.bro

  * backdoor.bro

  * blaster.bro

  * bro.bif.bro

  * bro.init

  * brolite.bro

  * capture-events.bro

  * checkpoint.bro

  * common-rw.bif.bro

  * conn-id.bro

  * conn.bro

  * const.bif.bro

  * contents.bro

  * cpu-adapt.bro

  * demux.bro

  * dns-info.bro

  * dns-lookup.bro

  * dns.bro

  * drop-adapt.bro

  * event.bif.bro

  * finger-rw.bif.bro

  * finger.bro

  * flag-irc.bro

  * flag-warez.bro

  * frag.bro

  * ftp-anonymizer.bro

  * ftp-cmd-arg.bro

  * ftp-reply-pattern.bro

  * ftp-rw.bif.bro

  * ftp-safe-words.bro

  * ftp.bro

  * gnutella.bro

  * hand-over.bro

  * hot-ids.bro

  * hot.bro

  * http-abstract.bro

  * http-body.bro

  * http-entity.bro

  * http-event.bro

  * http-header.bro

  * http-reply.bro

  * http-request.bro

  * http-rewriter.bro

  * http-rw.bif.bro

  * http.bro

  * icmp.bro

  * ident-rewriter.bro

  * ident-rw.bif.bro

  * ident.bro

  * inactivity.bro

  * interconn.bro

  * listen-clear.bro

  * listen-ssl.bro

  * load-level.bro

  * login.bro

  * mime.bro

  * mt.bro

  * netstats.bro

  * notice.bro

  * notice.bro.old

  * ntp.bro

  * pcap.bro

  * pkt-profile.bro

  * port-name.bro

  * portmapper.bro

  * print-filter.bro

  * print-globals.bro

  * print-resources.bro

  * print-sig-states.bro

  * profiling.bro

  * reduce-memory.bro

  * remote-pcap.bro

  * remote-print.bro

  * remote.bro

  * scan.bro

  * secondary-filter.bro

  * signatures.bro

  * signatures.bro.old

  * site.bro

  * smtp-relay.bro

  * smtp-rewriter.bro

  * smtp-rw.bif.bro

  * smtp.bro

  * snort.bro

  * software.bro

  * ssh-stepping.bro

  * ssh.bro

  * ssl-alerts.bro

  * ssl-ciphers.bro

  * ssl-errors.bro

  * ssl-worm.bro

  * ssl.bro

  * stats.bro

  * stepping.bro

  * synflood.bro

  * tcp.bro

  * tftp.bro

  * trw.bro

  * udp.bro

  * vlan.bro

  * weird.bro

  * worm.bro

The bro/site Directory
======================

signatures.sig
..............

To be completed

The bro/logs Directory
======================

All logs take the form

     type.hostname.start_date/time-end_date/time

The date/time stamps for each record in the files are always in UNIX (ticks since epoch) format. type is one of the following:

alarm
.....

Network occurrences that are determined to be of high importance will be written into the alarm file.  The determination is made by the Bro policy scripts.  Local site modifications can override default Bro alarms or create new ones that are site specific. Each entry contains the date/time, the alarm type, and a description of the alarm. This file is usually the "starting point" for investigation.  Each alarm should be evaluated for further follow-up action.

conn
....

All network connections detected by Bro are recorded in this file.  A connection is defined by an initial packet that attempts to set up a session and all subsequent packets that take part in the session.  Initial packets that fail to set up a session are also recorded as connections and are tagged with a failure state that designates the reason for failure. Each entry contains the following data describing the connection: date/time, the duration of the connection, the local and remote ip addresses and ports, bytes transferred in each direction, the transport protocol (udp, tcp), the final state of the connection, and other information describing the connection. This file is often used in forensic analysis to determine network activity by a suspect host beyond the immediate alarm.

ftp
...

All transactions involving the well known ftp control port (21) are recorded into this file.  Each entry is marked by an arbitrary session number, allowing full ftp control sessions to be reconstructed. Each entry contains the date/time, a session number, and ftp connection information or the specific ftp commands transferred. This file is often used to examine details of  suspect ftp sessions.

http
....

All transaction involving the well known http ports (80, 8000, 8080) are recorded into this file.  Each entry is marked by an arbitrary session number, allowing the full http session to reconstructed Each entry contains the date/time, a session number, and http connection information or the specific http commands transferred. This file is often used to examine details of  suspect web sessions.

info
....

This file contains information concerning the operation of Bro during the time interval covered by the file.  The entries will consist of the Bro version number, startup information, and Bro runtime warnings and errors. This file is helpful in troubleshooting Bro operational difficulties.

notice
......

Network occurrences that are determined to be of nominal importance will be written into the notice file.  The determination is made by the Bro policy scripts.  Local site modifications can override default Bro alarms or create new ones that are site specific.  The notice files are similar to the alarm files, but of lesser importance. Each entry contains the date/time, a notice type, a notice action, the local and remote ip addresses and ports. Optionally, depending on the type of notice, an entry might contain information about user, filename, method, URL, and other messages. This file alerts to occurrences that are worth noting, but do not warrant an alarm.

signatures
..........

This file contains information associated with specific signature matches.  These matches do not necessarily correspond to all alarms or notices, only to those that are triggered by a signature. Each entry contains the date/time, a description of the signature,  the local and remote ip addresses and ports, the signature id number (if available),  a description of the signature trigger, a portion of the offending payload data, a count of that particular signature, and a count of the number of involved hosts. This file gives details that are helpful in evaluating if an event triggered by a signature match is a false- positive.

smtp
....

All transactions involving the well known smtp port (25) are recorded into this file.  Each entry is marked by an arbitrary session number, allowing full smtp sessions to be reconstructed. Each entry contains the date/time, a session number, and smtp connection information or the specific smtp commands transferred. This file is often used to examine details of suspect mail sessions.

software
........

This file is a record of all unique host/software pairs detected by Bro during the time interval covered by the file. Each entry in the file contains the date/time, the ip address of the host, and information about the software detected. This file can be useful for cataloging network software. However, population of this file on a busy network often results in a huge number of entries.  Since the relative daily usefulness of the file usually does not warrant the disk space it consumes, the software file is turned off by default.  It can be turned on by <<<instructions>>>

weird
.....

Network events that are unusual or exceptional are recorded in this file.  A number of these events "shouldn't" or even "can't" happen according to accepted protocol definitions, yet they do. Each entry in the file contains the date/time, the local and remote ip addresses and ports, and a short description of the weird activity. This file is useful for detecting odd behavior that might normally "fly under the radar" and also for getting a general sense of the amount of "garbage" that is on the network.

worm
....

Bro's worm.bro policy detects patterns generated by specific worms and records the instance in this file. Currently, the worms detected are code red1, code red2, nimda, and slammer. Each entry in the file contains the date/time, the worm detected, and the source ip address of the worm. This file is useful for spotting hosts that have been infected with worms.

Other files in the /logs directory are:

.state
......

To be completed

active_log
..........

To be completed

The bro/archive Directory
=========================

The archive directory is initially empty.  The script bro/script/bro_log_compress.sh populates the archive directory with compressed log files.

Other Files
===========