Telling Bro What's Important

One of the easiest ways to customize Bro is writing a local notice policy. Bro can detect a great number of potentially interesting situations, and the notice policy tells which of them the user wants to be escalated into a alarms. The notice policy can also specify further actions to be taken, such as paging the security officer. This article gives an introduction into writing such a notice policy.

Let us start with a little bit of background on Bro's philosophy on reporting things. Bro ships with a large number of policy scripts which perform a wide variety of analyses. Most of these scripts monitor for activity which might be of interest for the administrator. However, none of these scripts assesses the importance of what it finds itself. Instead, the scripts only flag situations as potentially interesting, leaving it to the local configuration to define which of them are in fact alarm-worthy. This decoupling of detection and reporting allows Bro to address the different needs sites have: the definition of what constitutes an attack differs quite a bit between environments, and activity deemed malicious at one place might be fully acceptable at another.

Whenever one of Bro's analysis scripts sees something potentially interesting, it flags the situation by raising a Notice. A Notice has a type, which reflects the kind of activity which has been detected, and it is usually augmented with additional context about the situation. For example, whenever the HTTP analyzer sees a suspicious URL being requested (such as /etc/passwd), it raises a Notice of the type HTTP_SensitiveURI and augments it with the requested URL itself as well as the involved hosts.

In terms of script code, "raising a Notice" is just a call to a predefined function called NOTICE. For example, to raise an HTTP_SensitiveURI such a call could look like this:

NOTICE([$note=HTTP_SensitiveURI, $conn=connection, 
        $URL=url, ...])

If one wants to know which types of Notices a Bro script can raise, one can just grep the script for calls to the NOTICE function.

Once raised, all Notices are processed centrally. By default, all Notices are in fact automatically turned into alarms and will therefore show up in alarm.log. The local site policy can however change this default behavior, as we describe in the following.

In general, each raised Notice gets mapped to one out of a set of predefined actions. Such an action can, e.g., be to send a mail to the administrator or to simply ignore the Notice. In the current trunk, the following actions are defined:

Action	Description
NOTICE_IGNORE	Ignore Notice completely.
NOTICE_FILE	File Notice only to notice.log; do not write an entry into alarm.log.
NOTICE_ALARM_ALWAYS	Report in alarm.log.
NOTICE_EMAIL	Send out a mail and report in alarm.log.
NOTICE_PAGE	Page security officer and report in alarm.log.

NOTICE_ALARM_ALWAYS reflects the default behavior if no other action is defined for a Notice. All notice actions except NOTICE_IGNORE also log to notice.log.

We can define which action is taken for a Notice in two ways. The first is to generally assign an action to all instances of a particular Notice type; the second provides the flexibility to filter individual Notice instances independent of their type. We discuss both in turn.

To generally apply the same action to all instances of a specific type, we assign a notice action filter to the type. In the most simple case such a filter does directly correspond to the intended action, per the following table:

Filter Name	Action
ignore_notice	NOTICE_IGNORE
file_notice	NOTICE_FILE
send_email_notice	NOTICE_EMAIL
send_page_notice	NOTICE_PAGE

(As NOTICE_ALARM_ALWAYS is the default action, there is no corresponding filter).

We map a Notice type to such a filter by adding an entry to Bro's predefined notice_action_filters table. For example, to just file all sensitive URIs into notice.log rather than turning them into alarms, we define:

@load notice-action-filters
    
redef notice_action_filters += {
        [HTTP_SensitiveURI] = file_notice
        };

Notice action filters are more powerful than just directly defining an action. Each filter is in fact a script function which gets the Notice instance as a parameter and returns the action Bro should take. In general, these functions can implement arbitrary schemes to settle on an action, which is why they are called "filters". In addition to the filters mentioned above (which just return the corresponding action without further ado), Bro's default script notice-action-filters.bro also defines the following ones (and more):

Filter name	Description
tally_notice_type	Count how often each Notice type occurred. The totals are reported when Bro terminates as new Notices of the type NoticeTally. The original Notices are just filed into notice.log.
tally_notice_type_and_ignore	Similar to tally_notice_type but discards original Notices.
file_if_remote	Do not alarm if Notice was triggered by a remote address.
notice_alarm_per_orig	Alarm only the first time we see the Notice type for each source address.
notice_alarm_per_orig_tally	Count Notice types per source address. Totals are reported, by default, every 5 hours as new NoticeTally Notices. The original Notices are just filed into notice.log.

Such filter functions are actually pretty easy to write. Have a look at the implementations in notice-action-filters.bro if you need different behavior.

Bro's set notice_policy provides the second way to define an action to be taken for a Notice. While notice_action_filters maps all instances of a particular Notice type to the same filter, notice_policy works on individual Notice instances. Each entry of notice_policy defines (1) a condition to be matched against all raised Notices and (2) an action to be taken if the condition matches.

Here's a simple example which tells Bro to ignore all Notices of type HTTP_SensitiveURI if the requested URL indicates that an image was requested (simplified example taken from policy/notice-policy.bro):

redef notice_policy += {
  [$pred(n: notice_info) = {
     return n$note == HTTP::HTTP_SensitiveURI &&
           n$URL == /.*\.(gif|jpg|png)/; 
     },
   $result = NOTICE_IGNORE]
  };

While the syntax might look a bit convoluted at first, it provides a lot of flexibility by leveraging Bro's match statement. $pred defines the entry's condition in the form of a predicate written as a Bro function. The function gets passed the raised Notice and it returns a boolean indicating whether the entry applies. If the predicate evaluates to true, Bro takes the action specified by $result. (If $result is omitted, the default action for a matching entry is NOTICE_FILE).

The notice_policy set can hold an arbitrary number of such entries. For each Notice, Bro evaluates the predicates of all of them. If multiple predicates evaluate to true, it is undefined which of the matching results is taken. One can however associate a priority with an entry by adding a field $priority=<int> to its definition; see policy/notice-policy.bro for examples. In the case of multiple matches with different priorities, Bro picks the one with the highest. If $priority is omitted, as it is in the example above, the default priority is 1.