Previous: Predefined Variables, Up: Predefined Variables and Functions



6.2 Predefined Functions

Bro provides a number of built-in functions:

active_connection (id: conn_id) : bool
Returns true if the given connection identifier (originator/responder addresses and ports) corresponds to a currently-active connection.

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 (See XXX).

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 (See XXX).

log_hook (msg: string): bool

If you define this function, then Bro will call it with each string it is about to log. The function should return true if Bro should go ahead and log the message, false otherwise. See for further discussion and an example.

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:
  • embedded NULs become the text “\0
  • embedded DELs (delete characters) become the text “^?
  • ASCII “control” characters with code <= 26 become the text “^Letter”, where Letter is the corresponding (upper case) control character; for example, ASCII 2 becomes “^B
  • ASCII “control” characters with codes between 26 and 32 (non-inclusive) become the text “\xhex-code”; for example, ASCII 31 becomes “\x1f
  • if the string does not yet have a trailing NUL, one is added.

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 non-existing connection id if not a known connection. 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 m specify that the given field should have a width of m characters. Fields with fewer characters are right-padded with blanks up to this width.

A format specifier of “.$n” (coming after m, if present) instructs fmt to use a precision of n digits. You can only specify a precision for the e, f or g formats. (fmt generates a run-time error if either m or n exceeds 127.)

The different format specifiers are:

%
A literal percent-sign character.
D
Format as a date. Valid only for values of type time.

The exact format is yymmddhh:mm:ss for the local time zone, per strftime.


d
Format as an integer. Valid for types bool, count, int, port, addr, and net, with the latter three being converted from network order to host order prior to formatting. bool values of true format as the number 1, and false as 0.
e, f, g
Format as a floating point value. Valid for types double, time, and interval. The formatting is the same as for printf, including the field width m and precision n.

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:
LOGIN_STATE_AUTHENTICATE
The connection is in its initial authentication dialog.
LOGIN_STATE_LOGGED_IN
The analyzer believes the user has successfully authenticated.
LOGIN_STATE_SKIP
The analyzer has skipped any further processing of the connection.
LOGIN_STATE_CONFUSED
The analyzer has concluded that it does not correctly know the state of the connection, and/or the username associated with it (See XXX).

connection_id is not a known login connection 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 wierd 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 (See XXX). Compare against current_time. In general, you should use network_time unless you're using Bro for non-networking uses (such as general scripting; not particularly recommended), because otherwise your script may behave very differently on live traffic versus played-back traffic 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 .

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 (h 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, 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 ), false if it's reading from save files being played back .

Note: This function returns true even after Bro has stopped reading network traffic, for example due to receiving a termination signal. (See XXX)

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 the table below.

Direction Meaning
CONTENTS_NONE Stop recording the connection's content
CONTENTS_ORIG Record the data sent by the connection orginator (often the client).
CONTENTS_RESP Record the data sent by the connection responder (often the server).
CONTENTS_BOTH Record the data sent in both directions.

Table 6.1: Different types of directions for set_contents file


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 (see XXX) , which a separate utility program could then read to extract the stream.

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 .

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 , if any.

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 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).