Bro provides a number of built-in functions:
[active_file (f: file): bool] Returns true if the given file is open.
[add_interface (iold: string, inew: string): string]
Used to refine the initialization of interfaces. Meant
for internal use, and as an example of refinement (§
[add_tcpdump_filter (fold: string, fnew: string): string]
Used to refine the initializations of capture_filter
and restrict_filter. Meant for internal use, and as an
example of refinement (§
[byte_len (s: string): count] Returns the number of bytes in the given string. This includes any embedded NULs, and also a trailing NUL, if any (which is why the function isn't called strlen; to remind the user that Bro strings can include NULs).
[cat (args: any): string] Returns the concatenation of the string representation of its arguments, which can be of any type. For example, cat("foo", 3, T) returns "foo3T".
[clean (s: string): string] Returns a cleaned up version of s, meaning that:
\0
''
^?
''
^
Letter'', where Letter is
the corresponding (upper case) control character; for example,
ASCII 2 becomes ``^B
''
\x
hex-code''; for example,
ASCII 31 becomes ``\x1f
''
[close (f: file): bool] Flushes any buffered output for the given file and closes it. Returns true if the file was open, false if already closed or never opened.
[connection_record (id: conn_id): connection] Returns the connection record corresponding to the given connection identifier. Note: If the connection does not exist, then exits with a fatal run-time error.
Deficiency: If Bro had an exception mechanism, then we could avoid the fatal run-time error, and likewise could get rid of active_connection.
[contains_string (big: string, little: string): bool] Returns true if the string little occurs somewhere within big, false otherwise.
[current_time (): time] Returns the current clock time. You will usually instead want to use network_time.
[discarder_check_icmp (i: ip_hdr, ih: icmp_hdr): bool] Not documented. [discarder_check_ip (i: ip_hdr): bool] Not documented. [discarder_check_tcp (i: ip_hdr, t: tcp_hdr, d: string): bool] Not documented. [discarder_check_udp (i: ip_hdr, u: udp_hdr, d: string): bool] Not documented.
[edit (s: string, edit_char: string): string]
Returns a version of s assuming that edit_char is the ``backspace''
character (usually "\x08"
for backspace or "\x7f"
for DEL).
For example, edit("hello there", "e") returns "llo t".
edit_char must be a string of exactly one character, or Bro generates a run-time error and uses the first character in the string.
Deficiency: To do a proper job, edit should also know about delete-word and delete-line editing; and it would be very convenient if it could do multiple types of edits all in one shot, rather than requiring separate invocations.
[exit (): int] Exits Bro with a status of 0.
Deficiency: This function should probably allow you to specify the exit status.
Note: If you invoke this function, then the usual cleanup functions net_done and bro_done are not invoked. There probably should be an additional ``shutdown'' function that provides for cleaner termination.
[flush_all (): bool] Flushes all open files to disk.
[fmt (args: any): string]
Performs sprintf-style formatting. The first argument gives
the format specifier to which the remaining arguments are formatted,
left-to-right. As with sprintf, the format for each argument
is introduced using ``%'', and
formats beginning with a positive integer specify
that the given field should have a width of
characters. Fields
with fewer characters are right-padded with blanks up to this width.
A format specifier of ``.'' (coming after
, if present)
instructs fmt to use a precision of
digits. You can
only specify a precision for the e, f or g
formats.
(fmt generates a run-time error if either
or
exceeds 127.)
The different format specifiers are:
The exact format is yy-mm-dd-hh:mm:ss for the local time zone, per strftime.
Given no arguments, fmt returns an empty string.
Given a non-string first argument, fmt returns the concatenation of all its arguments, per cat.
Finally, given the wrong number of additional arguments for the given format specifier, fmt generates a run-time error.
[get_login_state (c: conn_id): count] Returns the state of the given login (Telnet or Rlogin) connection, one of:
or a run-time error and a value of LOGIN_STATE_AUTHENTICATE if the connection is not a login connection.
[get_orig_seq (c: conn_id): count] Returns the highest sequence number sent by a connection's originator, or 0 if there's no such TCP connection. Sequence numbers are absolute (i.e., they reflect the values seen directly in packet headers; they are not relative to the beginning of the connection).
[get_resp_seq (c: conn_id): count] Returns the highest sequence number sent by a connection's responder, or 0 if there's no such TCP connection.
[getenv (var: string): string] Looks up the given environment variable and returns its value, or an empty string if it is not defined.
[is_tcp_port (p: port): bool] Returns true if the given port value corresponds to a TCP port, false otherwise (i.e., it belongs to a UDP port).
[length (args: any): count] Returns the number of elements in its argument, which must be of type table or set. If not exactly one argument is specified, or if the argument is not a table or a set, then generates a run-time message and returns 0.
Deficiency: If Bro had a union type, then we could get rid of the magic ``args: any'' specification and catch parameter mismatches at compile-time instead of run-time.
[log_file_name (tag: string): string]
Returns a name for a log file (such as weird or red)
in a standard form. The form depends on whether $BRO_ID is set.
If so, then the format is ``<
tag>.<$BRO_ID>
''. Otherwise,
it is simply tag.
[mask_addr (a: addr, top_bits_to_keep: count): addr] Returns the address a masked down to the number of upper bits indicated by top_bits_to_keep, which must be greater than 0 and less than 33. For example, mask_addr(1.2.3.4, 18) returns 1.2.0.0, and mask_addr(1.2.255.4, 18) returns 1.2.192.0.
Compare with to_net.
[max_count (a: count, b: count): count] Returns the larger of a or b.
[max_double (a: double, b: double): double] Returns the larger of a or b.
[max_interval (a: interval, b: interval): interval] Returns the larger of a or b.
Deficiency: If Bro supported polymorphic functions, then this function could be merged with its predecessors, gaining simplicity and clarity.
[min_count (a: count, b: count): count] Returns the smaller of a or b.
[min_double (a: double, b: double): double] Returns the smaller of a or b.
[min_interval (a: interval, b: interval): interval] Returns the smaller of a or b.
Deficiency: If Bro supported polymorphic functions, then this function could be merged with its predecessors, gaining simplicity and clarity.
[mkdir (f: string): bool] Creates a directory with the given name, if it does not already exist. Returns true upon success, false (with a run-time message) if unsuccessful.
[network_time (): time]
Returns the timestamp of the most recently read packet, whether read
from a live network interface or from a save file (§
[open (f: string): file] Opens the given filename for write access. Creates the file if it does not already exist. Generates a run-time error if the file cannot be opened/created.
[open_for_append (f: string): file] Opens the given filename for append access. Creates the file if it does not already exist. Generates a run-time error if the file cannot be opened/created.
[open_log_file (tag: string): file] Opens a log file associated with the given tag, using a filename format as returned by log_file_name.
[parse_ftp_pasv (s: string): ftp_port]
Parses the server's reply to an FTP PASV command to extract the
IP address and port number indicated by the server. The values
are returned in an ftp_port record, which has three
fields: h, the address ( is mnemonic for host);
p, the (TCP) port; and valid, a boolean that is true
if the server's reply was in the required format, false if not,
or if any of the individual values (or the indicated port number)
are out of range.
[parse_ftp_port (s: string): ftp_port] Parses the argument included in a client's FTP PORT request to extract the IP address and port number indicated by the server. The values are returned in an ftp_port record, which has three fields, as indicated in the discussion of parse_ftp_pasv.
[reading_live_traffic (): bool]
Returns true if Bro was invoked to read live network traffic (from
one or more network interfaces, per §
Note: This function returns true even after Bro has stopped reading
network traffic, for example due to receiving a termination signal
(§
[set_buf (f: file, buffered: bool)] Specifies that writing to the given file should either be fully buffered (if buffered is true), or line-buffered (if false). Does not return a value.
[set_contents_file (c: conn_id, direction: count, f: file): bool] Specifies that the traffic stream of the given connection in the given direction should be recorded to the given file. direction is one of the values given in Table 6.2.
Note: CONTENTS_BOTH results in the two directions being intermixed in the file, in the order the data was seen by Bro.
Note: The data recorded to the file reflects the byte stream, not the contents of individual packets. Reordering and duplicates are removed. If any data is missing, the recording stops at the missing data; see ack_above_hole for how this can happen.
Deficiency: Bro begins recording the traffic stream starting with
new traffic it sees. Experience has shown it would be highly handy if
Bro could record the entire connection to the file, including previously
seen traffic. In principle, this is possible if Bro is recording the
traffic to a save file (§
Returns true upon success, false upon an error.
[set_login_state (c: conn_id, new_state: count): bool] Manually sets the state of the given login (Telnet or Rlogin) connection to new_state, which should be one of the values described in get_login_state.
Generates a run-time error and returns false if the connection is not a login connection. Otherwise, returns true.
[set_record_packets (c: conn_id, do_record: bool): bool]
Controls whether Bro should or should not record the packets corresponding
to the given connection to the save file (§
Returns true upon success, false upon an error.
[skip_further_processing (c: conn_id): bool] Informs bro that it should skip any further processing of the contents of the given connection. In particular, Bro will refrain from reassembling the TCP byte stream and from generating events relating to any analyzers that have been processing the connection. Bro will still generate connection-oriented events such as connection_finished.
This function provides a way to shed some load in order to reduce the computational burden placed on the monitor.
Returns true upon success, false upon an error.
[sub_bytes (s: string, start: count, n: count): string] Returns a copy of n bytes from the given string, starting at position start. The beginning of a string corresponds to position 1.
If start is 0 or exceeds the length of the string, returns an empty string.
If the string does not have n characters from start to its end, then returns the characters from start to the end.
[system (s: string): int] Runs the given string as a sh command (via C's system call).
Note: The command is run in the background with stdout redirected to stderr.
Returns the return value from the system call. Note: This corresponds to the status of backgrounding the given command, not to the exit status of the command itself. A value of 127 corresponds to a failure to execute sh, and -1 to an internal system failure.
[to_lower (s: string): string] Returns a copy of the given string with the uppercase letters (as indicated by isascii and isupper) folded to lowercase (via tolower).
[to_net (a: addr): net]
Returns the network prefix historically associated with the given
address. That is, if a's leading octet is less than 128,
then returns
<
a>
/8;
if between 128 and 191, inclusive, then
<
a>
/16;
if between 192 and 223, then
<
a>
/24;
and, otherwise,
<
a>
/32.
See the discussion of the net type for more about network prefixes.
Generates a run-time error and returns 0.0.0.0 if the address is IPv6.
Note: Such network prefixes have become obsolete with the advent of CIDR; still, for some sites they prove useful because they correspond to existing address allocations.
Compare with mask_addr.
[to_upper (s: string): string] Returns a copy of the given string with the lowercase letters (as indicated by isascii and islower) folded to uppercase (via toupper).
Note that for all functions that take a conn_id argument except active_connection, Bro generates a run-time error and returns false if the given connection does not exist.
In general, any of the functions above that are passed a string argument
will check for the presence of an embedded NUL or the lack of a terminating
NUL. If either occurs, they generate a run-time message, and the
string is transformed into the value
"<string-with-NUL>"
.
There are three exceptions: clean, byte_len, and sub_bytes. These functions do not complain about embedded NULs or lack of trailing NULs.