Bro is very customizable, and there are several ways to modify Bro to suit your environment. You can write your own policy analyzers using the Bro language. Most sites will likely just want to do minor customizations, such as changing the level of an alert from "notice" to "alarm", or turning on or off particular analyzers. The chapter describes how to do these types of customizations. Information on how to write your own analyzers can be found in the Bro Reference Manual (http://www.bro-ids.org/Bro-reference-manual/).

The default policy scripts for Bro are all in $BROHOME/policy. These files should never be edited, as your edits will be lost when you upgrade Bro. To customize Bro for your site, you should make all your changes in $BROHOME/site. Many simple changes just require you to redefine (using the redef (http://www.bro-ids.org/Bro-reference-manual/Variables-Overview.html) operator, a Bro constant from a standard policy script with your own custom value. You can also write your own custom script to do whatever you want.

For example, to add "guest" to the list of forbidden_ids (http://www.bro-ids.org/Bro-reference-manual/hot_002dids-Module.html) (user names that generate a login alarm), you do this:

    redef forbidden_ids += { "guest", };

In this chapter we give an overview of all the standard Bro policy scripts, what notices they generate, and how to customize the most commonly changed items, and how to write new policy modules.

Builtin Policy Files
====================

Bro policy script is the basic analyzer used by Bro to determine what network events are alarm worthy. A policy can also specify what actions to take and how to report activities, as well as determine what activities to scrutinize. Bro uses policies to determine what activities to classify as hot, or questionable in intent. These hot network sessions can then be flagged, watched, or responded to via other policies or applications determined to be necessary, such as calling rst to reset a connection on the local side, or to add an IP address block to a main router's ACL (Access Control List). The policy files use the Bro scripting language, which is discussed in great detail in The Bro Reference Manual (http://www.bro-ids.org/Bro-reference-manual/index.html).

Policy files are loaded using an @load command. The semantics of @load are "load in this script if it hasn't already been loaded", so there is no harm in loading something in multiple policy scripts. The following policy scripts are included with Bro. The first set are all on by default, and the second group can be added by adding them to your site/brohost.bro policy file.

Bro Analyzers are described in detail in the Reference Manual (http://www.bro-ids.org/Bro-reference-manual/Analyzers-and-Events.html). These policy files are loaded by default:

     site    defines local and neighbor networks from static config
     alarm      open logging file for alarm events
     tcp     initialize BPF filter for SYN/FIN/RST TCP packets
     login    rlogin/telnet analyzer (or to ensure they are disabled)
     weird    initialize generic mechanism for detecting unusual events
     conn    access and record connection events
     hot    defines certain forms of sensitive access
     frag    process TCP fragments
     print-resources    on exit, print resource usage information, useful for tuning
     signatures     the signature policy engine
     scan    generic scan detection mechanism
     trw    additional, more sensitive scan detection
     http   general http analyzer, low level of detail
     http-request    detailed analysis of http requests
     http-reply      detailed analysis of http replys
     ftp     FTP analysis
     portmapper    record and analyze RPC portmapper requests
     smtp    record and analyze email traffic
     tftp    identify and log TFTP sessions
     worm   flag HTTP-based worm sources such as Code Red
     software    track software versions; required for some signature matching
     blaster   looks for blaster worm
     synflood   looks for synflood attacks
     stepping   used to detect when someone logs into
     your site from an external net, and then soon logs into another site
     reduce-memory   sets shorter timeouts for saving state,
     thus saving memory. If your Bro is using < 50% of you RAM, try not loading this

These are not loaded by default:

     Policy   Description     Why off by default
     drop      Include if site has ability to drop hostile remotes     Turn on if needed
     icmp      icmp analysis     CPU intensive and low payoff
     dns     DNS analysis     CPU intensive and low payoff
     ident   ident program analyzer     historical, no longer interesting
     gnutella   looks for hosts running Gnutella     Turn this on if you want
     to know about this
     ssl    ssl analyzer     still experimental
     ssh-stepping   Detects stepping stones where both incoming and outgoing connections are ssh
       Possibly too CPU intensive (needs more testing)
     analy   Performs statistical analysis     only used in off-line alalysis
     backdoor   Looks for backdoors     only effective when also capturing bulk traffic
     passwords   Looks for clear text passwords     may want to turn on if your site does not allow clear text passwords
     file-flush   Causes all log files to be flushed every N seconds     may want to turn on if you are doing "real time" analysis

To modify which analyzers are loaded, edit or create a file in $BROHOME/site. If you write your own new custom analyzer, it goes in this directory too. To disable an analyzer, add "@unload policy.bro" to the beginning of the file $BROHOME/site/brohost.bro, before the line "@load brolite.bro". To add additional analyzers, add them @load them in $BROHOME/site/brohost.bro.

Notices
=======

The primary output facility in Bro is called a Notice. The Bro distribution includes a number of standard of Notices, listed below. The table contains the name of the Notice, what Bro policy file generates it, and a short description of what the Notice is about.

     Notice   Policy   Description

     AckAboveHole   weird   Could mean packet drop; could also be a faulty TCP implementation
     AddressDropIgnored   scan   A request to drop connectivity has been ignored ; (scan detected, but one of these flags is true:  !can_drop_connectivity, or never_shut_down, or never_drop_nets )
     AddressDropped    scan   Connectivity w/ given address has been dropped
     AddressScan   scan   The source has scanned a number of addrs
     BackscatterSeen   scan   Apparent flooding backscatter seen from source
     ClearToEncrypted_SS   stepping    A stepping stone was seen in which the first part of the chain is a clear-text connection but the second part is encrypted. This often means that a password or passphrase has been exposed in the clear, and may also mean that the user has an incomplete notion that their connection is protected from eavesdropping.
     ContentGap   weird   Data has sequence hole; perhaps due to filtering
     CountSignature    signatures   Signature has triggered multiple times for a destination
     DNS::DNS_MappingChanged   DNS   Some sort of change WRT previous Bro lookup
     DNS::DNS_PTR_Scan   dns   Summary of a set of PTR lookups (automatically generated once/day when dns policy is loaded)
     DroppedPackets   netstats   Number of packets dropped as reported by the packet filter
     FTP::FTP_BadPort   ftp   Bad format in PORT/PASV;
     FTP::FTP_ExcessiveFilename   ftp    Very long filename seen
     FTP::FTP_PrivPort   ftp   Privileged port used in PORT/PASV
     FTP::FTP_Sensitive   ftp   Sensitive connection (as defined in hot)
     FTP::FTP_UnexpectedConn   ftp   FTP data transfer from unexpected src
     HTTP::HTTP_SensitiveURI   http   Sensitive URI in GET/POST/HEAD (default sensitive URIs defined http-request.bro; e.g.:  /etc.*\/.*(passwd|shadow|netconfig)
     HotEmailRecipient   smtp   XXX Need Example, default = NULL
     ICMP::ICMPAsymPayload   icmp    Payload in echo req-resp not the same
     ICMP::ICMPConnectionPair   icmp   Too many ICMPs between hosts (default = 200)
     IdentSensitiveID   ident   Sensitive username in Ident lookup
     LocalWorm   worm   Worm seen in local host (searches for code red 1, code red 2, nimda, slammer)
     LoginForbidden ButConfused   login    Interactive login seen using forbidden username, but the analyzer was confused in following the login dialog, so may be in error.
     LoginForbiddenButConfused   login    Interactive login seen using forbidden username, but the analyzer was confused in following the login dialog, so may be in error.
     Multiple SigResponders   signatures    host has triggered the same signature on multiple responders
     MultipleSigResponders   signatures    host has triggered the same signature on multiple responders
     MultipleSignatures   signatures   host has triggered many signatures
     Multiple SigResponders   signatures    host has triggered the same signature on multiple responders
     OutboundTFTP   tftp    outbound TFTP seen
     PasswordGuessing   scan   source tried too many user/password combinations (default = 25)
     PortScan   scan    the source has scanned a number of ports
     RemoteWorm   worm   worm seen in remote host
     Resolver Inconsistency    dns    the answer returned by a DNS server differs from one previously returned
     ResolverInconsistency    dns    the answer returned by a DNS server differs from one previously returned
     ResourceSummary   print-resources   prints Bro resource usage
     Retransmission Inconsistency   weird   possible evasion; usually just bad TCP implementation
     RetransmissionInconsistency   weird   possible evasion; usually just bad TCP implementation
     SSL_SessConIncon   ssl   session data not consistent with connection
     SSL_X509Violation   ssl   blanket X509 error
     ScanSummary   scan   a summary of scanning activity, output once / day
     SensitiveConnection   conn   connection marked "hot", See: Reference Manual section on hot ids (http://www.bro-ids.org/Bro-reference-manual/hot_002dids-Module.html) for more information.
     SensitiveDNS_Lookup   dns   DNS lookup of sensitive hostname/addr; default list of sensitive hosts = NULL
     SensitiveLogin   login   interactive login using sensitive username (defined in 'hot')
     Sensitive PortmapperAccess   portmapper   the given combination of the service looked up via the pormapper, the host requesting the lookup, and the host from which it's requiesting it is deemed sensitive
     SensitivePortmapperAccess   portmapper   the given combination of the service looked up via the pormapper, the host requesting the lookup, and the host from which it's requiesting it is deemed sensitive
     SensitiveSignature   signatures    generic for alarm-worthy
     SensitiveUsername InPassword   login   During a login dialog, a sensitive username (e.g., "rewt") was seen in the user's password.  This is reported as a notice because it could be that the login analyzer didn't track the authentication dialog correctly, and in fact what it thinks is the user's password is instead the user's username.
     SensitiveUsernameInPassword   login   During a login dialog, a sensitive username (e.g., "rewt") was seen in the user's password.  This is reported as a notice because it could be that the login analyzer didn't track the authentication dialog correctly, and in fact what it thinks is the user's password is instead the user's username.
     SignatureSummary   signatures   summarize number of times a host triggered a signature (default = 1/day)
     SynFloodEnd   synflood   end of syn-flood against a certain victim.
     A syn-flood is defined to be more than SYNFLOOD_THRESHOLD (default = 15000) new connections
     have been reported within the last SYNFLOOD_INTERVAL (default = 60 seconds) for a certain IP.
     SynFloodStart   synflood   start of syn-flood against a certain victim
     SynFloodStatus   synflood   report of ongoing syn-flood
     TRWAddressScan   trw   source flagged as scanner by TRW algorithm
     TRWScanSummary   trw   summary of scanning activities reported by TRW
     Terminating Connection   conn   "rst" command sent to connection origin, connection terminated, triggered in the following policies: ftp and login: forbidden user id, hot (connection from host with spoofed IP address)
     TerminatingConnection   conn   "rst" command sent to connection origin, connection terminated, triggered in the following policies: ftp and login: forbidden user id, hot (connection from host with spoofed IP address?)
     W32B_SourceLocal   blaster   report a local W32.Blaster-infected host
     W32B_SourceRemote   blaster   report a remote W32.Blaster-infected host
     WeirdActivity   Weird   generic unusual, alarm-worthy activity

Note that some of the Notice names start with "ModuleName::" (e.g.: FTP::FTP_BadPort) and some do not. This is becuase not all of the Bro Analyzers have been converted to use the Modules facility (http://www.bro-ids.org/Bro-reference-manual/Module-Facility.html) yet.  Eventually all notices will start with "ModuleName::".

To get a list of all Notices that your particular Bro configuration might generate, you can type:

       sh . $BROHOME/etc/bro.cfg; bro -z notice $BRO_HOSTNAME.bro

Notice Actions
==============

Notices that are deemed particularly important are called Alarms. Alarms are sent to the alarm log file, and to optionally to syslog.

The standard Bro distribution supports a number of types of notice actions, these are:

     NOTICE_IGNORE     do nothing
     NOTICE_FILE    send to 'notice' file
     NOTICE_ALARM_ALWAYS     send to alarm file and syslog
     NOTICE_ALARM_PER_CONN    send to alarm file once per connection
     NOTICE_EMAIL    send to alarm file and send email
     NOTICE_PAGE    send to alarm file and send to pager

It is also possible to define your own custom notice actions.

By default, all notices are set to NOTICE_ALARM_ALWAYS except for the following:

     ContentGap, AckAboveHole, AddressDropIgnored, PacketsDropped,
     RetransmissionInconsistency

By default all Alarms are also sent to syslog. To disable this, add:

   redef enable_syslog = F;

To change the default notice action for a given notice, add something like this to your site/brohost.bro file:

   redef notice_action_filters += {
        [[WeirdActivity, ContentGap]] = ignore_notice,
   };

This will cause the Notices WeirdActivity and ContentGap to no longer get logged anywhere. To send these Notices to the Notice log file only, and not to the Alarm log, add this:

   redef notice_action_filters += {
        [[WeirdActivity, ContentGap]] = file_notice,
   };

For NOTICE_EMAIL and NOTICE_PAGE, email is sent using the script specified by the mail_script variable (default: "mail_notice.sh"), which must be in $PATH. To activate this, $mail_dest must be set. Email is only sent if Bro is reading live traffic.

For example, to send email on TerminatingConnection and FTP_Sensitive notices, add something like this:

redef mail_dest = "youremail@yoursite.edu";

redef notice_action_filters += {
    [[TerminatingConnection, FTP::FTP_Sensitive]] = send_email_notice,
};

Customizing Builtin Policy
==========================

The default policy scripts for Bro are all in $BROHOME/policy. Remember that these files should never be edited, as your edits will be lost when you upgrade Bro. To customize Bro for your site, you should make all your changes in $BROHOME/site. Many simple changes just require you to redefine (using the redef (http://www.bro-ids.org/Bro-reference-manual/Variables-Overview.html) operator, a Bro constant from a standard policy script with your own custom value. You can also write your own custom script to do whatever you want.

Here are some example of the types of things you may want to customize.

To add "guest" to the list of forbidden_ids (http://www.bro-ids.org/Bro-reference-manual/hot_002dids-Module.html) (user names that generate a login alarm), you do this:

    redef forbidden_ids += { "guest", };

To add a new rootkit string to HTTP sensitive_URIs (http://www.bro-ids.org/Bro-reference-manual/http_002drequestbro.html):
   redef HTTP::sensitive_URIs += /^.*rootdown.pl.*$/;

Writing New Policy
==================

For example, if your site only allows external http and mail to a small, controlled lists of hosts, you could write a new .bro file containing this:

const web_servers = { www.lbl.gov, www.bro-ids.org, };
const mail_servers = { smtp.lbl.gov, smtp2.lbl.gov, };

const allow_my_services: set[addr, port] = {
        [mail_servers, smtp],
        [web_servers, http],
};

Bro can then generate an Alarm or even terminate the connection for policy violations. For example:

event connection_established(c: connection)
{
   local id = c$id;
   local service = id$resp_p;
   local inbound = is_local_addr(id$resp_h);

   if ( inbound && [id$resp_h, service] !in allow_my_services )
      NOTICE ([$note=SensitiveConnection, $conn=c,
		$msg=fmt("hot: %s", full_id_string(c)) ]);
    if ( inbound && service in terminate_successful_inbound_service )
            terminate_connection(c);
}

To test this you might do the following. First, generate some "offline" data to play with:

      # tcpdump -s 0 -w trace.out port smtp or port http

Kill off the tcpdump after capturing traffic for a few minutes (use ctrl-C). Then add the above Bro code to your hostname.bro file, and run Bro against this captured trace file:

      # setenv BROHOME /usr/local/bro
      # setenv BROPATH $BROHOME/site:$BROHOME/policy
      # bro -r trace.out hostname.bro

Signatures
==========

     [file Bro-signatures.texi not included]

Tuning Scan Detection
=====================

There are a large number of tunable parameters in the scan analyzer, all of which are described in the reference manual (http://www.bro-ids.org/Bro-reference-manual/scan-Analyzer.html). Most of these parameters should be fine for all sites. The only settings that you may want to tune are:

  * report_peer_scan: Generate a log message whenever a remote host has attempted to connect to the given number of distinct hosts. Default = { 100, 1000, 10000, }.

  * report_outbound_peer_scan: Generate a log message whenever a local host has attempted to connect to the given number of remost hosts. Default = { 100, 1000, }.

  * skip_services: list of ports to ignore scans on, because they often gets scanned by legitimate (or at least common) services. The default list can be found in the brolite.bro file.

If you want enable ICMP scan detection, set these:

     redef ICMP::detect_scans = T;
     redef ICMP::scan_threshold = 100;

Other Customizations
====================

There are a number of things you may wish to customize.

hot_ids

The policy file hot-ids.bro (http://www.bro-ids.org/Bro-reference-manual/hot_002dids-Module.html) contains a number of constants that you might want to customize by "redef"ing them in your brohost.bro policy file. These are all used to generate FTP and login alarms (SensitiveConnection Notice) for suspicious users. The user ID's that are in hot_ids and not in always_hot_ids are only hot upon successful login. For details see the Bro Reference Manual (http://www.bro-ids.org/Bro-reference-manual/hot_002dids-Module.html).

     constant   Defaults
     forbidden_ids   "uucp", "daemon", "rewt", "nuucp",
     "EZsetup", "OutOfBox", "4Dgifts",
     "ezsetup", "outofbox", "4dgifts", "sgiweb"
     "r00t", "ruut", "bomb", "backdoor",
     "bionic", "warhead", "check_mate", "checkmate", "check_made",
     "themage", "darkmage", "y0uar3ownd", "netfrack", "netphrack"
     always_hot_ids   "lp", "demos",
     "retro", "milk", "moof", "own", "gdm", "anacnd",
     + forbidden_ids
     hot_ids   "root", "system", "smtp", "sysadm", "diag", "sysdiag", "sundiag",
     "sync", "tutor", "tour",
     "operator", "sys", "toor", "issadmin", "msql", "sysop", "sysoper",
     + always_hot_ids

Input/Output Strings

The policy files login.bro and ftp.bro both contain a list of input and output strings that indicate suspicious activity. In you wish to add anything to this list, you may want to redef one of these.

     login.bro: see input_trouble and output_trouble (http://www.bro-ids.org/Bro-reference-manual/login-variables.html)
     ftp.bro: see ftp_hot_files (http://www.bro-ids.org/Bro-reference-manual/ftp-variables.html)

Sensitive URIs

The policy file http-request.bro contain a list of http URI's that indicate suspicious activity. In you wish to add anything to this list, you may want to redef one of these.

     sensitive_URIs
     sensitive_post_URIs

Log Files

redef this to rotate the log files every N seconds

     log_rotate_interval (default = 0 sec, don't rotate)

redef this to rotate the log files when they get this big

     log_max_size (default = 250e6, rotate when any file exceeds 250 MB)