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 ofcapture_filter
andrestrict_filter
. Meant for internal use, and as an example of refinement (See XXX).
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.
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).
Returns the concatenation of the string representation of its arguments, which can be of any type. For example,cat("foo", 3, T)
returns"foo3T"
.
Returns a cleaned up version ofs
, 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 “
\x
hex-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 theconnection
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 stringlittle
occurs somewhere withinbig
, false otherwise.
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 ofs
assuming thatedit_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
andbro_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.
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 afterm
, if present) instructsfmt
to use a precision of n digits. You can only specify a precision for thee
,f
org
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 yy–mm–dd–hh:mm:ss for the local time zone, per strftime.
d
- Format as an integer. Valid for types
bool
,count
,int
,port
,addr
, andnet
, 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
, andinterval
. 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, percat
.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.
Looks up the given environment variable and returns its value, or an empty string if it is not defined.
Returns true if the given port
value corresponds to a TCP port,
false otherwise (i.e., it belongs to a UDP port).
Returns the number of elements in its argument, which must be of typetable
orset
. 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 aswierd
orred
) 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 simplytag
.
mask_addr (a: addr, top_bits_to_keep: count): addr
Returns the addressa
masked down to the number of upper bits indicated bytop_bits_to_keep
, which must be greater than 0 and less than 33. For example,mask_addr(1.2.3.4, 18)
returns1.2.0.0
, andmask_addr(1.2.255.4, 18)
returns1.2.192.0
.Compare with
to_net
.
max_count (a: count, b: count): count
Returns the larger ofa
orb
.
max_double (a: double, b: double): double
Returns the larger ofa
orb
.
max_interval (a: interval, b: interval): interval
Returns the larger ofa
orb
.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 ofa
orb
.
min_double (a: double, b: double): double
Returns the smaller ofa
orb
.
min_interval (a: interval, b: interval): interval
Returns the smaller ofa
orb
.Deficiency: If Bro supported polymorphic functions, then this function could be merged with its predecessors, gaining simplicity and clarity.
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.
Returns the timestamp of the most recently read packet, whether read from a live network interface or from a save file (See XXX). Compare againstcurrent_time
. In general, you should usenetwork_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.
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 FTPPASV
command to extract the IP address and port number indicated by the server. The values are returned in anftp_port
record, which has three fields:h
, the address (h is mnemonic for host);p
, the (TCP) port; andvalid
, 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 FTPPORT
request to extract the IP address and port number indicated by the server. The values are returned in anftp_port
, which has three fields, as indicated in the discussion ofparse_ftp_pasv
.
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 tonew_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 asconnection_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 ofn
bytes from the given string, starting at positionstart
. 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 fromstart
to its end, then returns the characters fromstart
to the end.
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).
Returns the network prefix historically associated with the given address. That is, ifa
'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).