Bro functions and event handlers are written in an imperative style, and the statements available for doing so are similar to those provided in C. As in C, statements are terminated with a semi-colon. There are no restrictions on how many lines a statement can span. Whitespace can appear between any of the syntatic components in a statement, and its presence always serves as a separator (that is, a single syntactic component cannot in general contain embedded whitespace, unless it is escaped in some form, such as appearing inside a string literal).
Bro provides the following types of statements:
Syntax:expr ;As in C, an expression by itself can also be used as a statement. For example, assignments, calling functions, and scheduling timers are all expressions; they also are often used as statements.
Syntax:print file expr-list ;The expressions are converted to a list of strings, which are then printed as a comma-separated list. If the first expression is of type , then the other expressions are printed to the corresponding file; otherwise they're written to stdout.For control over how the strings are formatted, see the
fmt
function.
Syntax:log expr-list ;The expressions are converted to a list of strings, which are then logged as a comma-separated list. “Logging” means recording the values to bro-log-file. In addition, if Bro is reading live network traffic (as opposed to from a trace file), then the messages are also reported via syslog(3) at level LOG_NOTICE. If the message does not already include a timestamp, one is added.See the
log
module for a discussion of controlling logging behavior from your policy script. In particular, an important feature of thelog
statement is that prior to logging the giving string(s), Bro first invokes log-hook to determine whether to suppress the logging.
Syntax:event expr ( expr-list* ) ;Evaluates expr to obtain an event handler and queues an event for it with the value corresponding to the optional comma-separated list of values given by expr-list.Note:
event
statements look syntactically just like function calls, other than the keyword “event
”. However, function-call-expr, while queueing an event is not, since it does not return a value.
Syntax:if ( expr ) stmtEvaluates expr, which must yield a bool value. If true, executes stmt. For the second form, if false, executes stmt2.
if ( expr ) stmt else stmt2
Syntax:for ( var in expr ) stmtIterates over the indices of expr, which must evaluate to either aset
or atable
. For each iteration, var is set to one of the indices and stmt is executed. var needn't have been previously declared (in which case its type is implicitly inferred from that of the indices of expr), and must not be a global variable.If expr is a
set
, then the indices correspond to the members of the set. If expr is atable
, then they correspond to the indices of the table.Deficiency: You can only use
for
statements to iterate over sets and tables with a single, non-compound index type. You can't iterate over multi-dimensional or compound indices.Deficiency: Bro lacks ways of controlling the order in which it iterates over the indices.
Syntax:next ;Only valid within afor
statement. When executed, causes the loop to proceed to the next iteration value (i.e., the next index value).
Syntax:break ;Only valid within afor
statement. When executed, causes the loop to immediately exit.
Syntax:return expr ;Immediately exits the current function or event handler. For a function, returns the value expr (which is omitted if the function does not return a value, or for event handlers).
Syntax:add expr1 expr2 ;Adds the element specified by expr2 to the set given by expr1. For example,global active_hosts: set[addr, port]; ... add active_hosts[1.44.33.7, 80/tcp];addes an element corresponding to the pair 1.44.33.7 and 80/tcp to the set active_hosts.
Syntax:delete expr1 [expr2] ;Deletes the corresponding value, where expr1 corresponds to a set or table, and expr2 an element/index of the set/table. If the element is not in the set/table, does nothing.
Compound statements are formed from a list of (zero or more) statements enclosed in{}
's:{ statement* }
A lone:;denotes an empty, do-nothing statement.
Syntax:local var : type = initialization attributes ;Declares a local variable with the given type, initialization, and attributes, all of which are optional. The syntax of these fields is the same as for global-vars. The second form likewise declares a local variable, but one which is constant: trying to assign a new value to it results in an error. Deficiency:Currently, this
const var : type = initialization attributes ;const
restriction isn't detected/enforced.Unlike with C the scope of a local variable is from the point of declaration to the end of the encompassing function or event handler.