Bro variables can be complicated to understand because they have a number of possibilities and features. They can be global or local in scope; modifiable or constant (unchangeable); explicitly or implicitly typed; optionally initialized; defined to have additional attributes; and, for global variables, redefined to have a different initialization or different attributes from their first declaration.
Rather than giving the full syntax for variable declarations, which is messy, in the following sections we discuss each of these facets of variables in turn, illustrating them with the minimal necessary syntax. However, keep in mind that the features can be combined as needed in a variable declaration.
global name : type ;or
local name : type ;which declares name to have the given type and the corresponding scope.
You can intermix function/event handler definitions with declarations of global variables, and, indeed, they're in fact the same thing (that is, a function or event handler definition is equivalent to defining a global variable of type function or event and associating its initial value with that of the function or event handler). So the following is fine:
global a: count; function b(p: port): string { if ( p < 1024/tcp ) return "privileged"; else return "ephemeral"; } global c: addr;
However, you cannot mix declarations of global variables with global statements; the following is not allowed:
print "hello, world"; global a: count;
Local variables, on the other hand, can only be declared within a function or event handler. (Unlike for global statements, these declarations can come after statements.) Their scope persists to the end of the function. For example:
function b(p: port): string { if ( p < 1024/tcp ) local port_type = "privileged"; else port_type = "ephemeral"; return port_type; }
const response_script = "./scripts/nuke-em";Note that const variables must be initialized (otherwise, of course, there's no way for them to ever hold a useful value).
The utility of marking a variable as unmodifiable is for clarity in expressing your script--making it explicit that a particular value will never change--and also allows Bro to possibly optimize accesses to the variable (though it does little of this currently).
Note that const variables can be redefined via redef.
global a: count;directly indicates that a's type is count.
However, Bro can also implicitly type the variable by looking at the type of the expression you use to initialize the variable:
global a = 5;also declares a's type to be count, since that's the type of the initialization expression (the constant 5). There is no difference between this declaration and:
global a: count = 5;except that it is more concise both to write and to read. In particular, Bro remains strongly typed, even though it also supports implicit typing; the key is that once the type is implicitly inferred, it is thereafter strongly enforced.
Bro's type inference is fairly powerful: it can generally figure out the type whatever initialization expression you use. For example, it correctly infers that:
global c = { [21/tcp, "ftp"], [[80/tcp, 8000/tcp, 8080/tcp], "http"], };specifies that c's type is set[port, string]. But for still more complicated expressions, it is not always able to infer the correct type. When this occurs, you need to explicitly specify the type.
global a = 5;indicates that the initial value of a is the value 5 (and also implicitly types a as type count, per §
The syntax of an initialization is ``= expression'', where
the given expression must be assignment-compatible with the variable's
type (if explicitly given). Tables and sets also have special initializer
forms, which are discussed in §
& attrfor attributes that are specified simply using their name, and
& attr = exprfor attributes that have a value associated with them.
The attributes
&redef
&add_func
and
&delete_func,
pertain to redefining variables; they are discussed in §
The attributes
&default,
&create_expire,
&read_expire,
&write_expire, and
&expire_func
are for use with table's and set's.
See §
The attribute
&optional
specifies that a record field is optional. See §
Finall, to specify multiple attributes, you do not separate them with commas (doing so would actually make Bro's grammar ambiguous), but just list them one after another. For example:
global a: table[port] of string &redef &default="missing";
To do.