Keywords: doc-html

Next: Analyzers and Events Up: Predefined Variables and Functions Previous: Predefined Variables Contents Index
Subsections

- Run-time errors for non-existing connections
- Run-time errors for strings with NULs
- Functions for manipulating strings
- Functions for manipulating time

# 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 (§ ).

  [``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 (§ ).

``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 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 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:

  `%`
    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`, 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 and precision .

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

  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 (§ ). 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 `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 § ), 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 (§ ).

  Table 6.1: Different types of directions for `set_contents_file`.
  Direction | Meaning
  `CONTENTS_NONE` | Stop recording the connection's contents.
  `CONTENTS_ORIG` | Record the data sent by the connection originator (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.

  [``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 (§ ), 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 `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 (§ ), 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 `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).

##
Run-time errors for non-existing connections

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.

## Run-time errors for strings with NULs

While Bro allows NULs embedded within strings (§ ), for many of the predefined functions, their presence spells trouble, particularly when the string is being passed to a C run-time function. The same holds for strings that are not NUL-terminated. Because Bro string constants and values returned by Bro functions that construct strings such as `fmt` and `cat` are all NUL-terminated, such strings will not ordinarily arise; but their presence could indicate an attacker attempting to manipulate either a TCP endpoint, or the monitor itself, into misinterpreting a string they're sending.

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.

##
Functions for manipulating strings

Fix me: Missing

##
Functions for manipulating time

Fix me: Missing

Next: Analyzers and Events Up: Predefined Variables and Functions Previous: Predefined Variables Contents Index