User Manual: Customizing Bro
From BroWiki
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 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 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 (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, how to customize the most commonly changed items, and how to write new policy modules.
Contents |
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 Reference Manual.
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. 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 wantto 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 | shadow|netconfig) |
HotEmailRecipient
| smtp |  FIXME 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 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 connectionshave 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 [1]
Modules facility} 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 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 (user names that generate a login alarm), you do this:
redef forbidden_ids += { "guest", };
To add a new rootkit string to HTTP sensitive_URIs:
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
Tuning Scan Detection
There are a large number of tunable parameters in the scan analyzer, all of which are described in [2] the reference manual}. 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 hot-ids
analysis script 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 Reference Manual.
| 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 the login analyzer.
- ftp.bro: see the FTP analyzer.
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)
