Next: , Previous: brolite Analysis Script, Up: Analyzers and Events


7.10 The alarm Analysis Script

The alarm utility module redefines a single variable:

`bro_alarm_file : file'
A special Bro variable used internally to specify a file where Bro should record messages logged by alarm statements (as well as generating real-time notifications via syslog).

Default: if the $BRO_LOG_SUFFIX environment variable is defined, then alarm.<$BRO_LOG_SUFFIX>, otherwise alarm.log.

See bro_alarm_file for further discussion.

If you do not include this module, then Bro records alarm messages to stderr. Here is a sample definition of alarm_hook:

     global msg_count: table[string] of count &default = 0;
     
     event alarm_summary(msg: string)
         {
         alarm fmt("(%s) %d times", msg, msg_count[msg]);
         }
     
     function alarm_hook(msg: string): bool
         {
         if ( ++msg_count[msg] == 1 )
             # First time we've seen this message - log it.
             return T;
     
         if ( msg_count[msg] == 5 )
             # We've seen it five times, enough to be worth
             # summarizing.  Do so five minutes from now,
             # for whatever total we've seen by then.
             schedule +5 min { alarm_summary(msg) };
     
         return F;
         }
     

You can also control Bro's alarm processing by defining the special function alarm-hook. It takes a single argument, msg: string, the message in a just-executed alarm statement, and returns a boolean value: true if Bro should indeed log the message, false if not. The above example shows a definition of alarm_hook that checks each alarm message to see whether the same text has been logged before. It only logs the first instance of a message. If a message appears at least five times, then it schedules a future alarm_summary event for 5 minutes in the future; the purpose of this event is to summarize the total number of times the message has appeared at that point in time.