base/bif/bro.bif.bro

GLOBAL

A collection of built-in functions that implement a variety of things such as general programming algorithms, string processing, math functions, introspection, type conversion, file/directory manipulation, packet filtering, interprocess communication and controlling protocol analyzer behavior.

You’ll find most of Bro’s built-in functions that aren’t protocol-specific in this file.

Namespace:GLOBAL
Source File:/scripts/base/bif/bro.bif.bro

Summary

Functions

active_file: function Checks whether a given file is open.
addr_to_counts: function Converts an addr to an index_vec.
addr_to_ptr_name: function Converts an IP address to a reverse pointer name.
addr_to_subnet: function Converts a addr to a subnet.
all_set: function Tests whether all elements of a boolean vector (vector of bool) are true.
anonymize_addr: function Anonymizes an IP address.
any_set: function Tests whether a boolean vector (vector of bool) has any true element.
bro_is_terminating: function Checks if Bro is terminating.
bro_version: function Returns the Bro version string.
bytestring_to_count: function Converts a string of bytes to a count.
bytestring_to_double: function Converts a string of bytes (in network byte order) to a double.
bytestring_to_hexstr: function Converts a string of bytes into its hexadecimal representation.
calc_next_rotate: function Calculates the duration until the next time a file is to be rotated, based on a given rotate interval.
capture_events: function Writes the binary event stream generated by the core to a given file.
capture_state_updates: function Writes state updates generated by &synchronized variables to a file.
cat: function Returns the concatenation of the string representation of its arguments.
cat_sep: function Concatenates all arguments, with a separator placed between each one.
check_subnet: function Checks if a specific subnet is a member of a set/table[subnet].
checkpoint_state: function Flushes in-memory state tagged with the &persistent attribute to disk.
clear_table: function Removes all elements from a set or table.
close: function Closes an open file and flushes any buffered content.
complete_handshake: function &deprecated Signals a remote peer that the local Bro instance finished the initial handshake.
connect: function &deprecated Establishes a connection to a remote Bro or Broccoli instance.
connection_exists: function Checks whether a connection is (still) active.
continue_processing: function Resumes Bro’s packet processing.
convert_for_pattern: function Escapes a string so that it becomes a valid pattern and can be used with the string_to_pattern.
count_to_port: function Converts a count and transport_proto to a port.
count_to_v4_addr: function Converts a count to an addr.
counts_to_addr: function Converts an index_vec to an addr.
current_analyzer: function Returns the ID of the analyzer which raised the current event.
current_time: function Returns the current wall-clock time.
decode_base64: function Decodes a Base64-encoded string.
decode_base64_conn: function Decodes a Base64-encoded string that was derived from processing a connection.
decode_base64_custom: function &deprecated Decodes a Base64-encoded string with a custom alphabet.
disable_analyzer: function Disables the analyzer which raised the current event (if the analyzer belongs to the given connection).
disable_print_hook: function Disables sending print_hook events to remote peers for a given file.
disconnect: function &deprecated Terminate the connection with a peer.
do_profiling: function Enables detailed collection of profiling statistics.
double_to_count: function Converts a double to a count.
double_to_interval: function Converts a double to an interval.
double_to_time: function Converts a double value to a time.
dump_current_packet: function Writes the current packet to a file.
dump_packet: function Writes a given packet to a file.
dump_rule_stats: function Write rule matcher statistics (DFA states, transitions, memory usage, cache hits/misses) to a file.
enable_communication: function &deprecated Enables the communication system.
enable_raw_output: function Prevents escaping of non-ASCII characters when writing to a file.
encode_base64: function Encodes a Base64-encoded string.
encode_base64_custom: function &deprecated Encodes a Base64-encoded string with a custom alphabet.
entropy_test_add: function Adds data to an incremental entropy calculation.
entropy_test_finish: function Finishes an incremental entropy calculation.
entropy_test_init: function Initializes data structures for incremental entropy calculation.
enum_to_int: function Converts an enum to an int.
exit: function Shuts down the Bro process immediately.
exp: function Computes the exponential function.
file_magic: function Determines the MIME type of a piece of data using Bro’s file magic signatures.
file_mode: function Converts UNIX file permissions given by a mode to an ASCII string.
file_size: function Returns the size of a given file.
filter_subnet_table: function For a set[subnet]/table[subnet], create a new table that contains all entries that contain a given subnet.
find_entropy: function Performs an entropy test on the given data.
floor: function Computes the greatest integer less than the given double value.
flush_all: function Flushes all open files to disk.
fmt: function Produces a formatted string à la printf.
fnv1a32: function Returns 32-bit digest of arbitrary input values using FNV-1a hash algorithm.
get_conn_transport_proto: function Extracts the transport protocol from a connection.
get_current_packet: function Returns the currently processed PCAP packet.
get_current_packet_header: function Function to get the raw headers of the currently processed packet.
get_event_peer: function &deprecated Returns the peer who generated the last event.
get_file_name: function Gets the filename associated with a file handle.
get_local_event_peer: function &deprecated Returns the local peer ID.
get_port_transport_proto: function Extracts the transport protocol from a port.
getenv: function Returns a system environment variable.
gethostname: function Returns the hostname of the machine Bro runs on.
getpid: function Returns Bro’s process ID.
global_ids: function Generates a table with information about all global identifiers.
global_sizes: function Generates a table of the size of all global variables.
haversine_distance: function Calculates distance between two geographic locations using the haversine formula.
hexstr_to_bytestring: function Converts a hex-string into its binary representation.
hrw_weight: function Calculates a weight value for use in a Rendezvous Hashing algorithm.
identify_data: function Determines the MIME type of a piece of data using Bro’s file magic signatures.
install_dst_addr_filter: function Installs a filter to drop packets destined to a given IP address with a certain probability if none of a given set of TCP flags are set.
install_dst_net_filter: function Installs a filter to drop packets destined to a given subnet with a certain probability if none of a given set of TCP flags are set.
install_src_addr_filter: function Installs a filter to drop packets from a given IP source address with a certain probability if none of a given set of TCP flags are set.
install_src_net_filter: function Installs a filter to drop packets originating from a given subnet with a certain probability if none of a given set of TCP flags are set.
int_to_count: function Converts a (positive) int to a count.
interval_to_double: function Converts an interval to a double.
is_external_connection: function Determines whether a connection has been received externally.
is_icmp_port: function Checks whether a given port has ICMP as transport protocol.
is_local_interface: function Checks whether a given IP address belongs to a local interface.
is_remote_event: function Checks whether the last raised event came from a remote peer.
is_tcp_port: function Checks whether a given port has TCP as transport protocol.
is_udp_port: function Checks whether a given port has UDP as transport protocol.
is_v4_addr: function Returns whether an address is IPv4 or not.
is_v4_subnet: function Returns whether a subnet specification is IPv4 or not.
is_v6_addr: function Returns whether an address is IPv6 or not.
is_v6_subnet: function Returns whether a subnet specification is IPv6 or not.
listen: function &deprecated Listens on a given IP address and port for remote connections.
ln: function Computes the natural logarithm of a number.
log10: function Computes the common logarithm of a number.
lookup_ID: function Returns the value of a global identifier.
lookup_addr: function Issues an asynchronous reverse DNS lookup and delays the function result.
lookup_asn: function Performs an ASN lookup of an IP address.
lookup_connection: function Returns the connection record for a given connection identifier.
lookup_hostname: function Issues an asynchronous DNS lookup and delays the function result.
lookup_hostname_txt: function Issues an asynchronous TEXT DNS lookup and delays the function result.
lookup_location: function Performs a geo-lookup of an IP address.
mask_addr: function Masks an address down to the number of given upper bits.
match_signatures: function Manually triggers the signature engine for a given connection.
matching_subnets: function Gets all subnets that contain a given subnet from a set/table[subnet].
md5_hash: function Computes the MD5 hash value of the provided list of arguments.
md5_hash_finish: function Returns the final MD5 digest of an incremental hash computation.
md5_hash_init: function Constructs an MD5 handle to enable incremental hash computation.
md5_hash_update: function Updates the MD5 value associated with a given index.
md5_hmac: function Computes an HMAC-MD5 hash value of the provided list of arguments.
merge_pattern: function &deprecated Merges and compiles two regular expressions at initialization time.
mkdir: function Creates a new directory.
mmdb_open_asn_db: function Initializes MMDB for later use of lookup_asn.
mmdb_open_location_db: function Initializes MMDB for later use of lookup_location.
network_time: function Returns the timestamp of the last packet processed.
open: function Opens a file for writing.
open_for_append: function Opens a file for writing or appending.
order: function Returns the order of the elements in a vector according to some comparison function.
piped_exec: function Opens a program with popen and writes a given string to the returned stream to send it to the opened process’s stdin.
port_to_count: function Converts a port to a count.
preserve_prefix: function Preserves the prefix of an IP address in anonymization.
preserve_subnet: function Preserves the prefix of a subnet in anonymization.
ptr_name_to_addr: function Converts a reverse pointer name to an address.
rand: function Generates a random number.
raw_bytes_to_v4_addr: function Converts a string of bytes into an IPv4 address.
reading_live_traffic: function Checks whether Bro reads traffic from one or more network interfaces (as opposed to from a network trace in a file).
reading_traces: function Checks whether Bro reads traffic from a trace file (as opposed to from a network interface).
record_fields: function Generates metadata about a record’s fields.
record_type_to_vector: function Converts a record type name to a vector of strings, where each element is the name of a record field.
remask_addr: function Takes some top bits (such as a subnet address) from one address and the other bits (intra-subnet part) from a second address and merges them to get a new address.
rename: function Renames a file from src_f to dst_f.
request_remote_events: function &deprecated Subscribes to all events from a remote peer whose names match a given pattern.
request_remote_logs: function &deprecated Requests logs from a remote peer.
request_remote_sync: function &deprecated Requests synchronization of IDs with a remote peer.
rescan_state: function Reads persistent state and populates the in-memory data structures accordingly.
resize: function Resizes a vector.
resume_state_updates: function &deprecated Resumes propagating &synchronized accesses.
rmdir: function Removes a directory.
rotate_file: function Rotates a file.
rotate_file_by_name: function Rotates a file identified by its name.
routing0_data_to_addrs: function Converts the data field of ip6_routing records that have rtype of 0 into a vector of addresses.
same_object: function Checks whether two objects reference the same internal object.
send_capture_filter: function &deprecated Sends a capture filter to a remote peer.
send_current_packet: function &deprecated Sends the currently processed packet to a remote peer.
send_id: function &deprecated Sends a global identifier to a remote peer, which then might install it locally.
send_ping: function &deprecated Sends a ping event to a remote peer.
send_state: function Sends all persistent state to a remote peer.
set_accept_state: function &deprecated Sets a boolean flag indicating whether Bro accepts state from a remote peer.
set_buf: function Alters the buffering behavior of a file.
set_compression_level: function &deprecated Sets the compression level of the session with a remote peer.
set_inactivity_timeout: function Sets an individual inactivity timeout for a connection and thus overrides the global inactivity timeout.
set_record_packets: function Controls whether packet contents belonging to a connection should be recorded (when -w option is provided on the command line).
setenv: function Sets a system environment variable.
sha1_hash: function Computes the SHA1 hash value of the provided list of arguments.
sha1_hash_finish: function Returns the final SHA1 digest of an incremental hash computation.
sha1_hash_init: function Constructs an SHA1 handle to enable incremental hash computation.
sha1_hash_update: function Updates the SHA1 value associated with a given index.
sha256_hash: function Computes the SHA256 hash value of the provided list of arguments.
sha256_hash_finish: function Returns the final SHA256 digest of an incremental hash computation.
sha256_hash_init: function Constructs an SHA256 handle to enable incremental hash computation.
sha256_hash_update: function Updates the SHA256 value associated with a given index.
skip_further_processing: function Informs Bro that it should skip any further processing of the contents of a given connection.
sort: function Sorts a vector in place.
sqrt: function Computes the square root of a double.
srand: function Sets the seed for subsequent rand calls.
strftime: function Formats a given time value according to a format string.
string_to_pattern: function Converts a string into a pattern.
strptime: function Parse a textual representation of a date/time value into a time type value.
subnet_to_addr: function Converts a subnet to an addr by extracting the prefix.
subnet_width: function Returns the width of a subnet.
suspend_processing: function Stops Bro’s packet processing.
suspend_state_updates: function &deprecated Stops propagating &synchronized accesses.
syslog: function Send a string to syslog.
system: function Invokes a command via the system function of the OS.
system_env: function Invokes a command via the system function of the OS with a prepared environment.
terminate: function Gracefully shut down Bro by terminating outstanding processing.
terminate_communication: function &deprecated Gracefully finishes communication by first making sure that all remaining data from parent and child has been sent out.
time_to_double: function Converts a time value to a double.
to_addr: function Converts a string to an addr.
to_count: function Converts a string to a count.
to_double: function Converts a string to a double.
to_int: function Converts a string to an int.
to_port: function Converts a string to a port.
to_subnet: function Converts a string to a subnet.
type_name: function Returns the type name of an arbitrary Bro variable.
uninstall_dst_addr_filter: function Removes a destination address filter.
uninstall_dst_net_filter: function Removes a destination subnet filter.
uninstall_src_addr_filter: function Removes a source address filter.
uninstall_src_net_filter: function Removes a source subnet filter.
unique_id: function Creates an identifier that is unique with high probability.
unique_id_from: function Creates an identifier that is unique with high probability.
unlink: function Removes a file from a directory.
uuid_to_string: function Converts a bytes representation of a UUID into its string form.
val_size: function Returns the number of bytes that a value occupies in memory.
write_file: function Writes data to an open file.

Detailed Interface

Functions

active_file
Type:function (f: file) : bool

Checks whether a given file is open.

F:The file to check.
Returns:True if f is an open file.

Todo

Rename to is_open.

addr_to_counts
Type:function (a: addr) : index_vec

Converts an addr to an index_vec.

A:The address to convert into a vector of counts.
Returns:A vector containing the host-order address representation, four elements in size for IPv6 addresses, or one element for IPv4.

See also: counts_to_addr

addr_to_ptr_name
Type:function (a: addr) : string

Converts an IP address to a reverse pointer name. For example, 192.168.0.1 to 1.0.168.192.in-addr.arpa.

A:The IP address to convert to a reverse pointer name.
Returns:The reverse pointer representation of a.

See also: ptr_name_to_addr, to_addr

addr_to_subnet
Type:function (a: addr) : subnet

Converts a addr to a subnet.

A:The address to convert.
Returns:The address as a subnet.

See also: to_subnet

all_set
Type:function (v: any) : bool

Tests whether all elements of a boolean vector (vector of bool) are true.

V:The boolean vector instance.
Returns:True iff all elements in v are true.

See also: any_set

Note

Missing elements count as false.

anonymize_addr
Type:function (a: addr, cl: IPAddrAnonymizationClass) : addr

Anonymizes an IP address.

A:

The address to anonymize.

Cl:

The anonymization class, which can take on three different values:

  • ORIG_ADDR: Tag a as an originator address.
  • RESP_ADDR: Tag a as an responder address.
  • OTHER_ADDR: Tag a as an arbitrary address.
Returns:

An anonymized version of a.

See also: preserve_prefix, preserve_subnet

Todo

Currently dysfunctional.

any_set
Type:function (v: any) : bool

Tests whether a boolean vector (vector of bool) has any true element.

V:The boolean vector instance.
Returns:True if any element in v is true.

See also: all_set

bro_is_terminating
Type:function () : bool

Checks if Bro is terminating.

Returns:True if Bro is in the process of shutting down.

See also: terminate

bro_version
Type:function () : string

Returns the Bro version string.

Returns:Bro’s version, e.g., 2.0-beta-47-debug.
bytestring_to_count
Type:function (s: string, is_le: bool &default = F &optional) : count

Converts a string of bytes to a count.

S:A string of bytes containing the binary representation of the value.
Is_le:If true, s is assumed to be in little endian format, else it’s big endian.
Returns:The value contained in s, or 0 if the conversion failed.
bytestring_to_double
Type:function (s: string) : double

Converts a string of bytes (in network byte order) to a double.

S:A string of bytes containing the binary representation of a double value.
Returns:The double value contained in s, or 0 if the conversion failed.
bytestring_to_hexstr
Type:function (bytestring: string) : string

Converts a string of bytes into its hexadecimal representation. For example, "04" would be converted to "3034".

Bytestring:The string of bytes.
Returns:The hexadecimal representation of bytestring.

See also: hexdump, hexstr_to_bytestring

calc_next_rotate
Type:function (i: interval) : interval

Calculates the duration until the next time a file is to be rotated, based on a given rotate interval.

I:The rotate interval to base the calculation on.
Returns:The duration until the next file rotation time.

See also: rotate_file, rotate_file_by_name

capture_events
Type:function (filename: string) : bool

Writes the binary event stream generated by the core to a given file. Use the -x <filename> command line switch to replay saved events.

Filename:The name of the file which stores the events.
Returns:True if opening the target file succeeds.

See also: capture_state_updates

capture_state_updates
Type:function (filename: string) : bool

Writes state updates generated by &synchronized variables to a file.

Filename:The name of the file which stores the state updates.
Returns:True if opening the target file succeeds.

See also: capture_events

cat
Type:function (…) : string

Returns the concatenation of the string representation of its arguments. The arguments can be of any type. For example, cat("foo", 3, T) returns "foo3T".

Returns:A string concatentation of all arguments.
cat_sep
Type:function (…) : string

Concatenates all arguments, with a separator placed between each one. This function is similar to cat, but places a separator between each given argument. If any of the variable arguments is an empty string it is replaced by a given default string instead.

Sep:The separator to place between each argument.
Def:The default string to use when an argument is the empty string.
Returns:A concatenation of all arguments with sep between each one and empty strings replaced with def.

See also: cat, string_cat, cat_string_array, cat_string_array_n

check_subnet
Type:function (search: subnet, t: any) : bool

Checks if a specific subnet is a member of a set/table[subnet]. In contrast to the in operator, this performs an exact match, not a longest prefix match.

Search:the subnet to search for.
T:the set[subnet] or table[subnet].
Returns:True if the exact subnet is a member, false otherwise.
checkpoint_state
Type:function () : bool

Flushes in-memory state tagged with the &persistent attribute to disk. The function writes the state to the file .state/state.bst in the directory where Bro was started.

Returns:True on success.

See also: rescan_state

clear_table
Type:function (v: any) : any

Removes all elements from a set or table.

V:The set or table
close
Type:function (f: file) : bool

Closes an open file and flushes any buffered content.

F:A file handle to an open file.
Returns:True on success.

See also: active_file, open, open_for_append, write_file, get_file_name, set_buf, flush_all, mkdir, enable_raw_output, rmdir, unlink, rename

complete_handshake
Type:function (p: event_peer) : bool
Attributes:&deprecated

Signals a remote peer that the local Bro instance finished the initial handshake.

P:The peer ID returned from connect.
Returns:True on success.
connect
Type:function (ip: addr, zone_id: string, p: port, our_class: string, retry: interval, ssl: bool) : count
Attributes:&deprecated

Establishes a connection to a remote Bro or Broccoli instance.

Ip:The IP address of the remote peer.
Zone_id:If ip is a non-global IPv6 address, a particular RFC 4007 zone_id can given here. An empty string, "", means not to add any zone_id.
P:The port of the remote peer.
Our_class:If a non-empty string, then the remote (listening) peer checks it against its class name in its peer table and terminates the connection if they don’t match.
Retry:If the connection fails, try to reconnect with the peer after this time interval.
Ssl:If true, use SSL to encrypt the session.
Returns:A locally unique ID of the new peer.

See also: disconnect, listen, request_remote_events, request_remote_sync, request_remote_logs, request_remote_events, set_accept_state, set_compression_level, send_state, send_id

connection_exists
Type:function (c: conn_id) : bool

Checks whether a connection is (still) active.

C:The connection id to check.
Returns:True if the connection identified by c exists.

See also: lookup_connection

continue_processing
Type:function () : any

Resumes Bro’s packet processing.

See also: suspend_processing, suspend_state_updates, resume_state_updates

convert_for_pattern
Type:function (s: string) : string

Escapes a string so that it becomes a valid pattern and can be used with the string_to_pattern. Any character from the set ^$-:"\/|*+?.(){}[] is prefixed with a \.

S:The string to escape.
Returns:An escaped version of s that has the structure of a valid pattern.

See also: merge_pattern, string_to_pattern

count_to_port
Type:function (num: count, proto: transport_proto) : port

Converts a count and transport_proto to a port.

Num:The port number.
Proto:The transport protocol.
Returns:The count num as port.

See also: port_to_count

count_to_v4_addr
Type:function (ip: count) : addr

Converts a count to an addr.

Ip:The count to convert.
Returns:The count ip as addr.

See also: raw_bytes_to_v4_addr, to_addr, to_subnet

counts_to_addr
Type:function (v: index_vec) : addr

Converts an index_vec to an addr.

V:The vector containing host-order IP address representation, one element for IPv4 addresses, four elements for IPv6 addresses.
Returns:An IP address.

See also: addr_to_counts

current_analyzer
Type:function () : count

Returns the ID of the analyzer which raised the current event.

Returns:The ID of the analyzer which raised the current event, or 0 if none.
current_time
Type:function () : time

Returns the current wall-clock time.

In general, you should use network_time instead unless you are 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.

Returns:The wall-clock time.

See also: network_time

decode_base64
Type:function (s: string, a: string &default = "" &optional) : string

Decodes a Base64-encoded string.

S:The Base64-encoded string.
A:An optional custom alphabet. The empty string indicates the default alphabet. If given, the string must consist of 64 unique characters.
Returns:The decoded version of s.

See also: decode_base64_conn, encode_base64

decode_base64_conn
Type:function (cid: conn_id, s: string, a: string &default = "" &optional) : string

Decodes a Base64-encoded string that was derived from processing a connection. If an error is encountered decoding the string, that will be logged to weird.log with the associated connection.

Cid:The identifier of the connection that the encoding originates from.
S:The Base64-encoded string.
A:An optional custom alphabet. The empty string indicates the default alphabet. If given, the string must consist of 64 unique characters.
Returns:The decoded version of s.

See also: decode_base64

decode_base64_custom
Type:function (s: string, a: string) : string
Attributes:&deprecated

Decodes a Base64-encoded string with a custom alphabet.

S:The Base64-encoded string.
A:The custom alphabet. The string must consist of 64 unique characters. The empty string indicates the default alphabet.
Returns:The decoded version of s.

See also: decode_base64, decode_base64_conn

disable_analyzer
Type:function (cid: conn_id, aid: count, err_if_no_conn: bool &default = T &optional) : bool

Disables the analyzer which raised the current event (if the analyzer belongs to the given connection).

Cid:The connection identifier.
Aid:The analyzer ID.
Returns:True if the connection identified by cid exists and has analyzer aid.

See also: Analyzer::schedule_analyzer, Analyzer::name

disable_print_hook
Type:function (f: file) : any

Disables sending print_hook events to remote peers for a given file. In a distributed setup, communicating Bro instances generate the event print_hook for each print statement and send it to the remote side. When disabled for a particular file, these events will not be propagated to other peers.

F:The file to disable print_hook events for.

See also: enable_raw_output

disconnect
Type:function (p: event_peer) : bool
Attributes:&deprecated

Terminate the connection with a peer.

P:The peer ID returned from connect.
Returns:True on success.

See also: connect, listen

do_profiling
Type:function () : any

Enables detailed collection of profiling statistics. Statistics include CPU/memory usage, connections, TCP states/reassembler, DNS lookups, timers, and script-level state. The script variable profiling_file holds the name of the file.

See also: get_conn_stats, get_dns_stats, get_event_stats, get_file_analysis_stats, get_gap_stats, get_matcher_stats, get_net_stats, get_proc_stats, get_reassembler_stats, get_thread_stats, get_timer_stats

double_to_count
Type:function (d: double) : count

Converts a double to a count.

D:The double to convert.
Returns:The double d as unsigned integer, or 0 if d < 0.0.

See also: double_to_time

double_to_interval
Type:function (d: double) : interval

Converts a double to an interval.

D:The double to convert.
Returns:The double d as interval.

See also: interval_to_double

double_to_time
Type:function (d: double) : time

Converts a double value to a time.

D:The double to convert.
Returns:The double value d as time.

See also: time_to_double, double_to_count

dump_current_packet
Type:function (file_name: string) : bool

Writes the current packet to a file.

File_name:The name of the file to write the packet to.
Returns:True on success.

See also: dump_packet, get_current_packet, send_current_packet

dump_packet
Type:function (pkt: pcap_packet, file_name: string) : bool

Writes a given packet to a file.

Pkt:The PCAP packet.
File_name:The name of the file to write pkt to.
Returns:True on success

See also: get_current_packet, dump_current_packet, send_current_packet

dump_rule_stats
Type:function (f: file) : bool

Write rule matcher statistics (DFA states, transitions, memory usage, cache hits/misses) to a file.

F:The file to write to.
Returns:True (unconditionally).

See also: get_matcher_stats

enable_communication
Type:function () : any
Attributes:&deprecated

Enables the communication system. By default, the communication is off until explicitly enabled, and all other calls to communication-related functions will be ignored until done so.

enable_raw_output
Type:function (f: file) : any

Prevents escaping of non-ASCII characters when writing to a file. This function is equivalent to &raw_output.

F:The file to disable raw output for.

See also: disable_print_hook

encode_base64
Type:function (s: string, a: string &default = "" &optional) : string

Encodes a Base64-encoded string.

S:The string to encode.
A:An optional custom alphabet. The empty string indicates the default alphabet. If given, the string must consist of 64 unique characters.
Returns:The encoded version of s.

See also: decode_base64

encode_base64_custom
Type:function (s: string, a: string) : string
Attributes:&deprecated

Encodes a Base64-encoded string with a custom alphabet.

S:The string to encode.
A:The custom alphabet. The string must consist of 64 unique characters. The empty string indicates the default alphabet.
Returns:The encoded version of s.

See also: encode_base64

entropy_test_add
Type:function (handle: opaque of entropy, data: string) : bool

Adds data to an incremental entropy calculation.

Handle:The opaque handle representing the entropy calculation state.
Data:The data to add to the entropy calculation.
Returns:True on success.

See also: find_entropy, entropy_test_add, entropy_test_finish

entropy_test_finish
Type:function (handle: opaque of entropy) : entropy_test_result

Finishes an incremental entropy calculation. Before using this function, one needs to obtain an opaque handle with entropy_test_init and add data to it via entropy_test_add.

Handle:The opaque handle representing the entropy calculation state.
Returns:The result of the entropy test. See find_entropy for a description of the individual components.

See also: find_entropy, entropy_test_init, entropy_test_add

entropy_test_init
Type:function () : opaque of entropy

Initializes data structures for incremental entropy calculation.

Returns:An opaque handle to be used in subsequent operations.

See also: find_entropy, entropy_test_add, entropy_test_finish

enum_to_int
Type:function (e: any) : int

Converts an enum to an int.

E:The enum to convert.
Returns:The int value that corresponds to the enum.
exit
Type:function (code: int) : any

Shuts down the Bro process immediately.

Code:The exit code to return with.

See also: terminate

exp
Type:function (d: double) : double

Computes the exponential function.

D:The argument to the exponential function.
Returns:e to the power of d.

See also: floor, sqrt, ln, log10

file_magic
Type:function (data: string) : mime_matches

Determines the MIME type of a piece of data using Bro’s file magic signatures.

Data:The data for which to find matching MIME types.
Returns:All matching signatures, in order of strength.

See also: identify_data

file_mode
Type:function (mode: count) : string

Converts UNIX file permissions given by a mode to an ASCII string.

Mode:The permissions (an octal number like 0644 converted to decimal).
Returns:A string representation of mode in the format rw[xsS]rw[xsS]rw[xtT].
file_size
Type:function (f: string) : double

Returns the size of a given file.

F:The name of the file whose size to lookup.
Returns:The size of f in bytes.
filter_subnet_table
Type:function (search: subnet, t: any) : any

For a set[subnet]/table[subnet], create a new table that contains all entries that contain a given subnet.

Search:the subnet to search for.
T:the set[subnet] or table[subnet].
Returns:A new table that contains all the entries that cover the subnet searched for.
find_entropy
Type:function (data: string) : entropy_test_result

Performs an entropy test on the given data. See http://www.fourmilab.ch/random.

Data:

The data to compute the entropy for.

Returns:

The result of the entropy test, which contains the following fields.

  • entropy: The information density expressed as a number of bits per character.

  • chi_square: The chi-square test value expressed as an absolute number and a percentage which indicates how frequently a truly random sequence would exceed the value calculated, i.e., the degree to which the sequence tested is suspected of being non-random.

    If the percentage is greater than 99% or less than 1%, the sequence is almost certainly not random. If the percentage is between 99% and 95% or between 1% and 5%, the sequence is suspect. Percentages between 90% and 95% and 5% and 10% indicate the sequence is “almost suspect.”

  • mean: The arithmetic mean of all the bytes. If the data are close to random, it should be around 127.5.

  • monte_carlo_pi: Each successive sequence of six bytes is used as 24-bit x and y coordinates within a square. If the distance of the randomly-generated point is less than the radius of a circle inscribed within the square, the six-byte sequence is considered a “hit.” The percentage of hits can be used to calculate the value of pi. For very large streams the value will approach the correct value of pi if the sequence is close to random.

  • serial_correlation: This quantity measures the extent to which each byte in the file depends upon the previous byte. For random sequences this value will be close to zero.

See also: entropy_test_init, entropy_test_add, entropy_test_finish

floor
Type:function (d: double) : double

Computes the greatest integer less than the given double value. For example, floor(3.14) returns 3.0, and floor(-3.14) returns -4.0.

D:The double to manipulate.
Returns:The next lowest integer of d as double.

See also: sqrt, exp, ln, log10

flush_all
Type:function () : bool

Flushes all open files to disk.

Returns:True on success.

See also: active_file, open, open_for_append, close, get_file_name, write_file, set_buf, mkdir, enable_raw_output, rmdir, unlink, rename

fmt
Type:function (…) : string

Produces a formatted string à la printf. The first argument is the format string and specifies how subsequent arguments are converted for output. It is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output, and conversion specifications, each of which fetches zero or more subsequent arguments. Conversion specifications begin with % and the arguments must properly correspond to the specifier. After the %, the following characters may appear in sequence:

  • %: Literal %

  • -: Left-align field

  • [0-9]+: The field width (< 128)

  • .: Precision of floating point specifiers [efg] (< 128)

  • [DTdxsefg]: Format specifier

    • [DT]: ISO timestamp with microsecond precision
    • d: Signed/Unsigned integer (using C-style %lld/%llu
      for int/count)
    • x: Unsigned hexadecimal (using C-style %llx);
      addresses/ports are converted to host-byte order
    • s: String (byte values less than 32 or greater than 126
      will be escaped)
    • [efg]: Double
Returns:Returns the formatted string. Given no arguments, fmt returns an empty string. Given no format string or the wrong number of additional arguments for the given format specifier, fmt generates a run-time error.

See also: cat, cat_sep, string_cat, cat_string_array, cat_string_array_n

fnv1a32
Type:function (input: any) : count

Returns 32-bit digest of arbitrary input values using FNV-1a hash algorithm. See https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function.

Input:The desired input value to hash.
Returns:The hashed value.

See also: hrw_weight

get_conn_transport_proto
Type:function (cid: conn_id) : transport_proto

Extracts the transport protocol from a connection.

Cid:The connection identifier.
Returns:The transport protocol of the connection identified by cid.

See also: get_port_transport_proto, get_orig_seq, get_resp_seq

get_current_packet
Type:function () : pcap_packet

Returns the currently processed PCAP packet.

Returns:The currently processed packet, which is a record containing the timestamp, snaplen, and packet data.

See also: dump_current_packet, dump_packet, send_current_packet

get_current_packet_header
Type:function () : raw_pkt_hdr

Function to get the raw headers of the currently processed packet.

Returns:The raw_pkt_hdr record containing the Layer 2, 3 and 4 headers of the currently processed packet.

See also: raw_pkt_hdr, get_current_packet

get_event_peer
Type:function () : event_peer
Attributes:&deprecated

Returns the peer who generated the last event.

Note, this function is deprecated. It works correctly only for local events and events received through the legacy communication system. It does not work for events received through Broker and will report an error in that case.

Returns:The ID of the peer who generated the last event.

See also: get_local_event_peer

get_file_name
Type:function (f: file) : string

Gets the filename associated with a file handle.

F:The file handle to inquire the name for.
Returns:The filename associated with f.

See also: open

get_local_event_peer
Type:function () : event_peer
Attributes:&deprecated

Returns the local peer ID.

Returns:The peer ID of the local Bro instance.

See also: get_event_peer

get_port_transport_proto
Type:function (p: port) : transport_proto

Extracts the transport protocol from a port.

P:The port.
Returns:The transport protocol of the port p.

See also: get_conn_transport_proto, get_orig_seq, get_resp_seq

getenv
Type:function (var: string) : string

Returns a system environment variable.

Var:The name of the variable whose value to request.
Returns:The system environment variable identified by var, or an empty string if it is not defined.

See also: setenv

gethostname
Type:function () : string

Returns the hostname of the machine Bro runs on.

Returns:The hostname of the machine Bro runs on.
getpid
Type:function () : count

Returns Bro’s process ID.

Returns:Bro’s process ID.
global_ids
Type:function () : id_table

Generates a table with information about all global identifiers. The table value is a record containing the type name of the identifier, whether it is exported, a constant, an enum constant, redefinable, and its value (if it has one).

Returns:A table that maps identifier names to information about them.

See also: global_sizes

global_sizes
Type:function () : var_sizes

Generates a table of the size of all global variables. The table index is the variable name and the value is the variable size in bytes.

Returns:A table that maps variable names to their sizes.

See also: global_ids

haversine_distance
Type:function (lat1: double, long1: double, lat2: double, long2: double) : double

Calculates distance between two geographic locations using the haversine formula. Latitudes and longitudes must be given in degrees, where southern hemispere latitudes are negative and western hemisphere longitudes are negative.

Lat1:Latitude (in degrees) of location 1.
Long1:Longitude (in degrees) of location 1.
Lat2:Latitude (in degrees) of location 2.
Long2:Longitude (in degrees) of location 2.
Returns:Distance in miles.

See also: haversine_distance_ip

hexstr_to_bytestring
Type:function (hexstr: string) : string

Converts a hex-string into its binary representation. For example, "3034" would be converted to "04".

The input string is assumed to contain an even number of hexadecimal digits (0-9, a-f, or A-F), otherwise behavior is undefined.

Hexstr:The hexadecimal string representation.
Returns:The binary representation of hexstr.

See also: hexdump, bytestring_to_hexstr

hrw_weight
Type:function (key_digest: count, site_id: count) : count

Calculates a weight value for use in a Rendezvous Hashing algorithm. See https://en.wikipedia.org/wiki/Rendezvous_hashing. The weight function used is the one recommended in the original

Paper:http://www.eecs.umich.edu/techreports/cse/96/CSE-TR-316-96.pdf.
Key_digest:A 32-bit digest of a key. E.g. use fnv1a32 to produce this.
Site_id:A 32-bit site/node identifier.
Returns:The weight value for the key/site pair.

See also: fnv1a32

identify_data
Type:function (data: string, return_mime: bool &default = T &optional) : string

Determines the MIME type of a piece of data using Bro’s file magic signatures.

Data:The data to find the MIME type for.
Return_mime:Deprecated argument; does nothing, except emit a warning when false.
Returns:The MIME type of data, or “<unknown>” if there was an error or no match. This is the strongest signature match.

See also: file_magic

install_dst_addr_filter
Type:function (ip: addr, tcp_flags: count, prob: double) : bool

Installs a filter to drop packets destined to a given IP address with a certain probability if none of a given set of TCP flags are set. Note that for IPv6 packets with a routing type header and non-zero segments left, this filters out against the final destination of the packet according to the routing extension header.

Ip:Drop packets to this IP address.
Tcp_flags:If none of these TCP flags are set, drop packets to ip with probability prob.
Prob:The probability [0.0, 1.0] used to drop packets to ip.
Returns:True (unconditionally).

See also: Pcap::precompile_pcap_filter, Pcap::install_pcap_filter, install_src_addr_filter, install_src_net_filter, uninstall_src_addr_filter, uninstall_src_net_filter, install_dst_net_filter, uninstall_dst_addr_filter, uninstall_dst_net_filter, Pcap::error

Todo

The return value should be changed to any.

install_dst_net_filter
Type:function (snet: subnet, tcp_flags: count, prob: double) : bool

Installs a filter to drop packets destined to a given subnet with a certain probability if none of a given set of TCP flags are set.

Snet:Drop packets to this subnet.
Tcp_flags:If none of these TCP flags are set, drop packets to snet with probability prob.
Prob:The probability [0.0, 1.0] used to drop packets to snet.
Returns:True (unconditionally).

See also: Pcap::precompile_pcap_filter, Pcap::install_pcap_filter, install_src_addr_filter, install_src_net_filter, uninstall_src_addr_filter, uninstall_src_net_filter, install_dst_addr_filter, uninstall_dst_addr_filter, uninstall_dst_net_filter, Pcap::error

Todo

The return value should be changed to any.

install_src_addr_filter
Type:function (ip: addr, tcp_flags: count, prob: double) : bool

Installs a filter to drop packets from a given IP source address with a certain probability if none of a given set of TCP flags are set. Note that for IPv6 packets with a Destination options header that has the Home Address option, this filters out against that home address.

Ip:The IP address to drop.
Tcp_flags:If none of these TCP flags are set, drop packets from ip with probability prob.
Prob:The probability [0.0, 1.0] used to drop packets from ip.
Returns:True (unconditionally).

See also: Pcap::precompile_pcap_filter, Pcap::install_pcap_filter, install_src_net_filter, uninstall_src_addr_filter, uninstall_src_net_filter, install_dst_addr_filter, install_dst_net_filter, uninstall_dst_addr_filter, uninstall_dst_net_filter, Pcap::error

Todo

The return value should be changed to any.

install_src_net_filter
Type:function (snet: subnet, tcp_flags: count, prob: double) : bool

Installs a filter to drop packets originating from a given subnet with a certain probability if none of a given set of TCP flags are set.

Snet:The subnet to drop packets from.
Tcp_flags:If none of these TCP flags are set, drop packets from snet with probability prob.
Prob:The probability [0.0, 1.0] used to drop packets from snet.
Returns:True (unconditionally).

See also: Pcap::precompile_pcap_filter, Pcap::install_pcap_filter, install_src_addr_filter, uninstall_src_addr_filter, uninstall_src_net_filter, install_dst_addr_filter, install_dst_net_filter, uninstall_dst_addr_filter, uninstall_dst_net_filter, Pcap::error

Todo

The return value should be changed to any.

int_to_count
Type:function (n: int) : count

Converts a (positive) int to a count.

N:The int to convert.
Returns:The int n as unsigned integer, or 0 if n < 0.
interval_to_double
Type:function (i: interval) : double

Converts an interval to a double.

I:The interval to convert.
Returns:The interval i as double.

See also: double_to_interval

is_external_connection
Type:function (c: connection) : bool

Determines whether a connection has been received externally. For example, Broccoli or the Time Machine can send packets to Bro via a mechanism that is one step lower than sending events. This function checks whether the packets of a connection stem from one of these external packet sources.

C:The connection to test.
Returns:True if c has been received externally.
is_icmp_port
Type:function (p: port) : bool

Checks whether a given port has ICMP as transport protocol.

P:The port to check.
Returns:True iff p is an ICMP port.

See also: is_tcp_port, is_udp_port

is_local_interface
Type:function (ip: addr) : bool

Checks whether a given IP address belongs to a local interface.

Ip:The IP address to check.
Returns:True if ip belongs to a local interface.
is_remote_event
Type:function () : bool

Checks whether the last raised event came from a remote peer.

Returns:True if the last raised event came from a remote peer.
is_tcp_port
Type:function (p: port) : bool

Checks whether a given port has TCP as transport protocol.

P:The port to check.
Returns:True iff p is a TCP port.

See also: is_udp_port, is_icmp_port

is_udp_port
Type:function (p: port) : bool

Checks whether a given port has UDP as transport protocol.

P:The port to check.
Returns:True iff p is a UDP port.

See also: is_icmp_port, is_tcp_port

is_v4_addr
Type:function (a: addr) : bool

Returns whether an address is IPv4 or not.

A:the address to check.
Returns:true if a is an IPv4 address, else false.
is_v4_subnet
Type:function (s: subnet) : bool

Returns whether a subnet specification is IPv4 or not.

S:the subnet to check.
Returns:true if s is an IPv4 subnet, else false.
is_v6_addr
Type:function (a: addr) : bool

Returns whether an address is IPv6 or not.

A:the address to check.
Returns:true if a is an IPv6 address, else false.
is_v6_subnet
Type:function (s: subnet) : bool

Returns whether a subnet specification is IPv6 or not.

S:the subnet to check.
Returns:true if s is an IPv6 subnet, else false.
listen
Type:function (ip: addr, p: port, ssl: bool, ipv6: bool, zone_id: string, retry_interval: interval) : bool
Attributes:&deprecated

Listens on a given IP address and port for remote connections.

Ip:The IP address to bind to.
P:The TCP port to listen on.
Ssl:If true, Bro uses SSL to encrypt the session.
Ipv6:If true, enable listening on IPv6 addresses.
Zone_id:If ip is a non-global IPv6 address, a particular RFC 4007 zone_id can given here. An empty string, "", means not to add any zone_id.
Retry_interval:If address ip is found to be already in use, this is the interval at which to automatically retry binding.
Returns:True on success.

See also: connect, disconnect

ln
Type:function (d: double) : double

Computes the natural logarithm of a number.

D:The argument to the logarithm.
Returns:The natural logarithm of d.

See also: exp, floor, sqrt, log10

log10
Type:function (d: double) : double

Computes the common logarithm of a number.

D:The argument to the logarithm.
Returns:The common logarithm of d.

See also: exp, floor, sqrt, ln

lookup_ID
Type:function (id: string) : any

Returns the value of a global identifier.

Id:The global identifier.
Returns:The value of id. If id does not describe a valid identifier, the string "<unknown id>" or "<no ID value>" is returned.
lookup_addr
Type:function (host: addr) : string

Issues an asynchronous reverse DNS lookup and delays the function result. This function can therefore only be called inside a when condition, e.g., when ( local host = lookup_addr(10.0.0.1) ) { f(host); }.

Host:The IP address to lookup.
Returns:The DNS name of host.

See also: lookup_hostname

lookup_asn
Type:function (a: addr) : count

Performs an ASN lookup of an IP address. Requires Bro to be built with libmaxminddb.

A:The IP address to lookup.
Returns:The number of the ASN that contains a.

See also: lookup_location

lookup_connection
Type:function (cid: conn_id) : connection

Returns the connection record for a given connection identifier.

Cid:The connection ID.
Returns:The connection record for cid. If cid does not point to an existing connection, the function generates a run-time error and returns a dummy value.

See also: connection_exists

lookup_hostname
Type:function (host: string) : addr_set

Issues an asynchronous DNS lookup and delays the function result. This function can therefore only be called inside a when condition, e.g., when ( local h = lookup_hostname("www.bro.org") ) { f(h); }.

Host:The hostname to lookup.
Returns:A set of DNS A and AAAA records associated with host.

See also: lookup_addr

lookup_hostname_txt
Type:function (host: string) : string

Issues an asynchronous TEXT DNS lookup and delays the function result. This function can therefore only be called inside a when condition, e.g., when ( local h = lookup_hostname_txt("www.bro.org") ) { f(h); }.

Host:The hostname to lookup.
Returns:The DNS TXT record associated with host.

See also: lookup_hostname

lookup_location
Type:function (a: addr) : geo_location

Performs a geo-lookup of an IP address. Requires Bro to be built with libmaxminddb.

A:The IP address to lookup.
Returns:A record with country, region, city, latitude, and longitude.

See also: lookup_asn

mask_addr
Type:function (a: addr, top_bits_to_keep: count) : subnet

Masks an address down to the number of given upper bits. For example, mask_addr(1.2.3.4, 18) returns 1.2.0.0.

A:The address to mask.
Top_bits_to_keep:
 The number of top bits to keep in a; must be greater than 0 and less than 33 for IPv4, or 129 for IPv6.
Returns:The address a masked down to top_bits_to_keep bits.

See also: remask_addr

match_signatures
Type:function (c: connection, pattern_type: int, s: string, bol: bool, eol: bool, from_orig: bool, clear: bool) : bool

Manually triggers the signature engine for a given connection. This is an internal function.

matching_subnets
Type:function (search: subnet, t: any) : subnet_vec

Gets all subnets that contain a given subnet from a set/table[subnet].

Search:the subnet to search for.
T:the set[subnet] or table[subnet].
Returns:All the keys of the set or table that cover the subnet searched for.
md5_hash
Type:function (…) : string

Computes the MD5 hash value of the provided list of arguments.

Returns:The MD5 hash value of the concatenated arguments.

See also: md5_hmac, md5_hash_init, md5_hash_update, md5_hash_finish, sha1_hash, sha1_hash_init, sha1_hash_update, sha1_hash_finish, sha256_hash, sha256_hash_init, sha256_hash_update, sha256_hash_finish

Note

This function performs a one-shot computation of its arguments. For incremental hash computation, see md5_hash_init and friends.

md5_hash_finish
Type:function (handle: opaque of md5) : string

Returns the final MD5 digest of an incremental hash computation.

Handle:The opaque handle associated with this hash computation.
Returns:The hash value associated with the computation of handle.

See also: md5_hmac, md5_hash, md5_hash_init, md5_hash_update, sha1_hash, sha1_hash_init, sha1_hash_update, sha1_hash_finish, sha256_hash, sha256_hash_init, sha256_hash_update, sha256_hash_finish

md5_hash_init
Type:function () : opaque of md5

Constructs an MD5 handle to enable incremental hash computation. You can feed data to the returned opaque value with md5_hash_update and eventually need to call md5_hash_finish to finish the computation and get the hash digest.

For example, when computing incremental MD5 values of transferred files in multiple concurrent HTTP connections, one keeps an optional handle in the HTTP session record. Then, one would call c$http$md5_handle = md5_hash_init() once before invoking md5_hash_update(c$http$md5_handle, some_more_data) in the http_entity_data event handler. When all data has arrived, a call to md5_hash_finish returns the final hash value.

Returns:The opaque handle associated with this hash computation.

See also: md5_hmac, md5_hash, md5_hash_update, md5_hash_finish, sha1_hash, sha1_hash_init, sha1_hash_update, sha1_hash_finish, sha256_hash, sha256_hash_init, sha256_hash_update, sha256_hash_finish

md5_hash_update
Type:function (handle: opaque of md5, data: string) : bool

Updates the MD5 value associated with a given index. It is required to call md5_hash_init once before calling this function.

Handle:The opaque handle associated with this hash computation.
Data:The data to add to the hash computation.
Returns:True on success.

See also: md5_hmac, md5_hash, md5_hash_init, md5_hash_finish, sha1_hash, sha1_hash_init, sha1_hash_update, sha1_hash_finish, sha256_hash, sha256_hash_init, sha256_hash_update, sha256_hash_finish

md5_hmac
Type:function (…) : string

Computes an HMAC-MD5 hash value of the provided list of arguments. The HMAC secret key is generated from available entropy when Bro starts up, or it can be specified for repeatability using the -K command line flag.

Returns:The HMAC-MD5 hash value of the concatenated arguments.

See also: md5_hash, md5_hash_init, md5_hash_update, md5_hash_finish, sha1_hash, sha1_hash_init, sha1_hash_update, sha1_hash_finish, sha256_hash, sha256_hash_init, sha256_hash_update, sha256_hash_finish

merge_pattern
Type:function (p1: pattern, p2: pattern) : pattern
Attributes:&deprecated

Merges and compiles two regular expressions at initialization time.

P1:The first pattern.
P2:The second pattern.
Returns:The compiled pattern of the concatenation of p1 and p2.

See also: convert_for_pattern, string_to_pattern

Note

This function must be called at Bro startup time, e.g., in the event bro_init.

mkdir
Type:function (f: string) : bool

Creates a new directory.

F:The directory name.
Returns:True if the operation succeeds or if f already exists, and false if the file creation fails.

See also: active_file, open_for_append, close, write_file, get_file_name, set_buf, flush_all, enable_raw_output, rmdir, unlink, rename

mmdb_open_asn_db
Type:function (f: string) : bool

Initializes MMDB for later use of lookup_asn. Requires Bro to be built with libmaxminddb.

F:The filename of the MaxMind ASN DB.
Returns:A boolean indicating whether the db was successfully opened.

See also: lookup_asn

mmdb_open_location_db
Type:function (f: string) : bool

Initializes MMDB for later use of lookup_location. Requires Bro to be built with libmaxminddb.

F:The filename of the MaxMind City or Country DB.
Returns:A boolean indicating whether the db was successfully opened.

See also: lookup_asn

network_time
Type:function () : time

Returns the timestamp of the last packet processed. This function returns the timestamp of the most recently read packet, whether read from a live network interface or from a save file.

Returns:The timestamp of the packet processed.

See also: current_time

open
Type:function (f: string) : file

Opens a file for writing. If a file with the same name already exists, this function overwrites it (as opposed to open_for_append).

F:The path to the file.
Returns:A file handle for subsequent operations.

See also: active_file, open_for_append, close, write_file, get_file_name, set_buf, flush_all, mkdir, enable_raw_output, rmdir, unlink, rename

open_for_append
Type:function (f: string) : file

Opens a file for writing or appending. If a file with the same name already exists, this function appends to it (as opposed to open).

F:The path to the file.
Returns:A file handle for subsequent operations.

See also: active_file, open, close, write_file, get_file_name, set_buf, flush_all, mkdir, enable_raw_output, rmdir, unlink, rename

order
Type:function (…) : index_vec

Returns the order of the elements in a vector according to some comparison function. See sort for details about the comparison function.

V:The vector whose order to compute.
Returns:A vector of count with the indices of the ordered elements. For example, the elements of v in order are (assuming o is the vector returned by order): v[o[0]], v[o[1]], etc.

See also: sort

piped_exec
Type:function (program: string, to_write: string) : bool

Opens a program with popen and writes a given string to the returned stream to send it to the opened process’s stdin.

Program:The program to execute.
To_write:Data to pipe to the opened program’s process via stdin.
Returns:True on success.

See also: system, system_env

port_to_count
Type:function (p: port) : count

Converts a port to a count.

P:The port to convert.
Returns:The port p as count.

See also: count_to_port

preserve_prefix
Type:function (a: addr, width: count) : any

Preserves the prefix of an IP address in anonymization.

A:The address to preserve.
Width:The number of bits from the top that should remain intact.

See also: preserve_subnet, anonymize_addr

Todo

Currently dysfunctional.

preserve_subnet
Type:function (a: subnet) : any

Preserves the prefix of a subnet in anonymization.

A:The subnet to preserve.

See also: preserve_prefix, anonymize_addr

Todo

Currently dysfunctional.

ptr_name_to_addr
Type:function (s: string) : addr

Converts a reverse pointer name to an address. For example, 1.0.168.192.in-addr.arpa to 192.168.0.1.

S:The string with the reverse pointer name.
Returns:The IP address corresponding to s.

See also: addr_to_ptr_name, to_addr

rand
Type:function (max: count) : count

Generates a random number.

Max:The maximum value of the random number.
Returns:a random positive integer in the interval [0, max).

See also: srand

Note

This function is a wrapper about the function random provided by the OS.

raw_bytes_to_v4_addr
Type:function (b: string) : addr

Converts a string of bytes into an IPv4 address. In particular, this function interprets the first 4 bytes of the string as an IPv4 address in network order.

B:The raw bytes (string) to convert.
Returns:The byte string b as addr.

See also: raw_bytes_to_v4_addr, to_addr, to_subnet

reading_live_traffic
Type:function () : bool

Checks whether Bro reads traffic from one or more network interfaces (as opposed to from a network trace in a file). Note that this function returns true even after Bro has stopped reading network traffic, for example due to receiving a termination signal.

Returns:True if reading traffic from a network interface.

See also: reading_traces

reading_traces
Type:function () : bool

Checks whether Bro reads traffic from a trace file (as opposed to from a network interface).

Returns:True if reading traffic from a network trace.

See also: reading_live_traffic

record_fields
Type:function (rec: any) : record_field_table

Generates metadata about a record’s fields. The returned information includes the field name, whether it is logged, its value (if it has one), and its default value (if specified).

Rec:The record value or type to inspect.
Returns:A table that describes the fields of a record.
record_type_to_vector
Type:function (rt: string) : string_vec

Converts a record type name to a vector of strings, where each element is the name of a record field. Nested records are flattened.

Rt:The name of the record type.
Returns:A string vector with the field names of rt.
remask_addr
Type:function (a1: addr, a2: addr, top_bits_from_a1: count) : addr

Takes some top bits (such as a subnet address) from one address and the other bits (intra-subnet part) from a second address and merges them to get a new address. This is useful for anonymizing at subnet level while preserving serial scans.

A1:The address to mask with top_bits_from_a1.
A2:The address to take the remaining bits from.
Top_bits_from_a1:
 The number of top bits to keep in a1; must be greater than 0 and less than 129. This value is always interpreted relative to the IPv6 bit width (v4-mapped addresses start at bit number 96).
Returns:The address a masked down to top_bits_to_keep bits.

See also: mask_addr

rename
Type:function (src_f: string, dst_f: string) : bool

Renames a file from src_f to dst_f.

Src_f:the name of the file to rename.
Dest_f:the name of the file after the rename operation.
Returns:True if the rename succeeds and false otherwise.

See also: active_file, open_for_append, close, write_file, get_file_name, set_buf, flush_all, enable_raw_output, mkdir, rmdir, unlink

request_remote_events
Type:function (p: event_peer, handlers: pattern) : bool
Attributes:&deprecated

Subscribes to all events from a remote peer whose names match a given pattern.

P:The peer ID returned from connect.
Handlers:The pattern describing the events to request from peer p.
Returns:True on success.

See also: request_remote_sync, request_remote_logs, set_accept_state

request_remote_logs
Type:function (p: event_peer) : bool
Attributes:&deprecated

Requests logs from a remote peer.

P:The peer ID returned from connect.
Returns:True on success.

See also: request_remote_events, request_remote_sync

request_remote_sync
Type:function (p: event_peer, auth: bool) : bool
Attributes:&deprecated

Requests synchronization of IDs with a remote peer.

P:The peer ID returned from connect.
Auth:If true, the local instance considers its current state authoritative and sends it to p right after the handshake.
Returns:True on success.

See also: request_remote_events, request_remote_logs, set_accept_state

rescan_state
Type:function () : bool

Reads persistent state and populates the in-memory data structures accordingly. Persistent state is read from the .state directory. This function is the dual to checkpoint_state.

Returns:True on success.

See also: checkpoint_state

resize
Type:function (aggr: any, newsize: count) : count

Resizes a vector.

Aggr:The vector instance.
Newsize:The new size of aggr.
Returns:The old size of aggr, or 0 if aggr is not a vector.
resume_state_updates
Type:function () : any
Attributes:&deprecated

Resumes propagating &synchronized accesses.

See also: suspend_processing, continue_processing, suspend_state_updates

rmdir
Type:function (d: string) : bool

Removes a directory.

D:The directory name.
Returns:True if the operation succeeds, and false if the directory delete operation fails.

See also: active_file, open_for_append, close, write_file, get_file_name, set_buf, flush_all, enable_raw_output, mkdir, unlink, rename

rotate_file
Type:function (f: file) : rotate_info

Rotates a file.

F:An open file handle.
Returns:Rotation statistics which include the original file name, the name after the rotation, and the time when f was opened/closed.

See also: rotate_file_by_name, calc_next_rotate

rotate_file_by_name
Type:function (f: string) : rotate_info

Rotates a file identified by its name.

F:The name of the file to rotate
Returns:Rotation statistics which include the original file name, the name after the rotation, and the time when f was opened/closed.

See also: rotate_file, calc_next_rotate

routing0_data_to_addrs
Type:function (s: string) : addr_vec

Converts the data field of ip6_routing records that have rtype of 0 into a vector of addresses.

S:The data field of an ip6_routing record that has an rtype of 0.
Returns:The vector of addresses contained in the routing header data.
same_object
Type:function (o1: any, o2: any) : bool

Checks whether two objects reference the same internal object. This function uses equality comparison of C++ raw pointer values to determine if the two objects are the same.

O1:The first object.
O2:The second object.
Returns:True if o1 and o2 are equal.
send_capture_filter
Type:function (p: event_peer, s: string) : bool
Attributes:&deprecated

Sends a capture filter to a remote peer.

P:The peer ID returned from connect.
S:The capture filter.
Returns:True if sending the packet succeeds.

See also: send_id, send_state, send_ping, send_current_packet

send_current_packet
Type:function (p: event_peer) : bool
Attributes:&deprecated

Sends the currently processed packet to a remote peer.

P:The peer ID returned from connect.
Returns:True if sending the packet succeeds.

See also: send_id, send_state, send_ping, send_capture_filter, dump_packet, dump_current_packet, get_current_packet

send_id
Type:function (p: event_peer, id: string) : bool
Attributes:&deprecated

Sends a global identifier to a remote peer, which then might install it locally.

P:The peer ID returned from connect.
Id:The identifier to send.
Returns:True on success.

See also: send_state, send_ping, send_current_packet, send_capture_filter

send_ping
Type:function (p: event_peer, seq: count) : bool
Attributes:&deprecated

Sends a ping event to a remote peer. In combination with an event handler for remote_pong, this function can be used to measure latency between two peers.

P:The peer ID returned from connect.
Seq:A sequence number (also included by remote_pong).
Returns:True if sending the ping succeeds.

See also: send_state, send_id, send_current_packet, send_capture_filter

send_state
Type:function (p: event_peer) : bool

Sends all persistent state to a remote peer.

P:The peer ID returned from connect.
Returns:True on success.

See also: send_id, send_ping, send_current_packet, send_capture_filter

set_accept_state
Type:function (p: event_peer, accept: bool) : bool
Attributes:&deprecated

Sets a boolean flag indicating whether Bro accepts state from a remote peer.

P:The peer ID returned from connect.
Accept:True if Bro accepts state from peer p, or false otherwise.
Returns:True on success.

See also: request_remote_events, request_remote_sync, set_compression_level

set_buf
Type:function (f: file, buffered: bool) : any

Alters the buffering behavior of a file.

F:A file handle to an open file.
Buffered:When true, f is fully buffered, i.e., bytes are saved in a buffer until the block size has been reached. When false, f is line buffered, i.e., bytes are saved up until a newline occurs.

See also: active_file, open, open_for_append, close, get_file_name, write_file, flush_all, mkdir, enable_raw_output, rmdir, unlink, rename

set_compression_level
Type:function (p: event_peer, level: count) : bool
Attributes:&deprecated

Sets the compression level of the session with a remote peer.

P:The peer ID returned from connect.
Level:Allowed values are in the range [0, 9], where 0 is the default and means no compression.
Returns:True on success.

See also: set_accept_state

set_inactivity_timeout
Type:function (cid: conn_id, t: interval) : interval

Sets an individual inactivity timeout for a connection and thus overrides the global inactivity timeout.

Cid:The connection ID.
T:The new inactivity timeout for the connection identified by cid.
Returns:The previous timeout interval.
set_record_packets
Type:function (cid: conn_id, do_record: bool) : bool

Controls whether packet contents belonging to a connection should be recorded (when -w option is provided on the command line).

Cid:The connection identifier.
Do_record:True to enable packet contents, and false to disable for the connection identified by cid.
Returns:False if cid does not point to an active connection, and true otherwise.

See also: skip_further_processing

Note

This is independent of whether Bro processes the packets of this connection, which is controlled separately by skip_further_processing.

See also: get_contents_file, set_contents_file

setenv
Type:function (var: string, val: string) : bool

Sets a system environment variable.

Var:The name of the variable.
Val:The (new) value of the variable var.
Returns:True on success.

See also: getenv

sha1_hash
Type:function (…) : string

Computes the SHA1 hash value of the provided list of arguments.

Returns:The SHA1 hash value of the concatenated arguments.

See also: md5_hash, md5_hmac, md5_hash_init, md5_hash_update, md5_hash_finish, sha1_hash_init, sha1_hash_update, sha1_hash_finish, sha256_hash, sha256_hash_init, sha256_hash_update, sha256_hash_finish

Note

This function performs a one-shot computation of its arguments. For incremental hash computation, see sha1_hash_init and friends.

sha1_hash_finish
Type:function (handle: opaque of sha1) : string

Returns the final SHA1 digest of an incremental hash computation.

Handle:The opaque handle associated with this hash computation.
Returns:The hash value associated with the computation of handle.

See also: md5_hmac, md5_hash, md5_hash_init, md5_hash_update, md5_hash_finish, sha1_hash, sha1_hash_init, sha1_hash_update, sha256_hash, sha256_hash_init, sha256_hash_update, sha256_hash_finish

sha1_hash_init
Type:function () : opaque of sha1

Constructs an SHA1 handle to enable incremental hash computation. You can feed data to the returned opaque value with sha1_hash_update and finally need to call sha1_hash_finish to finish the computation and get the hash digest.

For example, when computing incremental SHA1 values of transferred files in multiple concurrent HTTP connections, one keeps an optional handle in the HTTP session record. Then, one would call c$http$sha1_handle = sha1_hash_init() once before invoking sha1_hash_update(c$http$sha1_handle, some_more_data) in the http_entity_data event handler. When all data has arrived, a call to sha1_hash_finish returns the final hash value.

Returns:The opaque handle associated with this hash computation.

See also: md5_hmac, md5_hash, md5_hash_init, md5_hash_update, md5_hash_finish, sha1_hash, sha1_hash_update, sha1_hash_finish, sha256_hash, sha256_hash_init, sha256_hash_update, sha256_hash_finish

sha1_hash_update
Type:function (handle: opaque of sha1, data: string) : bool

Updates the SHA1 value associated with a given index. It is required to call sha1_hash_init once before calling this function.

Handle:The opaque handle associated with this hash computation.
Data:The data to add to the hash computation.
Returns:True on success.

See also: md5_hmac, md5_hash, md5_hash_init, md5_hash_update, md5_hash_finish, sha1_hash, sha1_hash_init, sha1_hash_finish, sha256_hash, sha256_hash_init, sha256_hash_update, sha256_hash_finish

sha256_hash
Type:function (…) : string

Computes the SHA256 hash value of the provided list of arguments.

Returns:The SHA256 hash value of the concatenated arguments.

See also: md5_hash, md5_hmac, md5_hash_init, md5_hash_update, md5_hash_finish, sha1_hash, sha1_hash_init, sha1_hash_update, sha1_hash_finish, sha256_hash_init, sha256_hash_update, sha256_hash_finish

Note

This function performs a one-shot computation of its arguments. For incremental hash computation, see sha256_hash_init and friends.

sha256_hash_finish
Type:function (handle: opaque of sha256) : string

Returns the final SHA256 digest of an incremental hash computation.

Handle:The opaque handle associated with this hash computation.
Returns:The hash value associated with the computation of handle.

See also: md5_hmac, md5_hash, md5_hash_init, md5_hash_update, md5_hash_finish, sha1_hash, sha1_hash_init, sha1_hash_update, sha1_hash_finish, sha256_hash, sha256_hash_init, sha256_hash_update

sha256_hash_init
Type:function () : opaque of sha256

Constructs an SHA256 handle to enable incremental hash computation. You can feed data to the returned opaque value with sha256_hash_update and finally need to call sha256_hash_finish to finish the computation and get the hash digest.

For example, when computing incremental SHA256 values of transferred files in multiple concurrent HTTP connections, one keeps an optional handle in the HTTP session record. Then, one would call c$http$sha256_handle = sha256_hash_init() once before invoking sha256_hash_update(c$http$sha256_handle, some_more_data) in the http_entity_data event handler. When all data has arrived, a call to sha256_hash_finish returns the final hash value.

Returns:The opaque handle associated with this hash computation.

See also: md5_hmac, md5_hash, md5_hash_init, md5_hash_update, md5_hash_finish, sha1_hash, sha1_hash_init, sha1_hash_update, sha1_hash_finish, sha256_hash, sha256_hash_update, sha256_hash_finish

sha256_hash_update
Type:function (handle: opaque of sha256, data: string) : bool

Updates the SHA256 value associated with a given index. It is required to call sha256_hash_init once before calling this function.

Handle:The opaque handle associated with this hash computation.
Data:The data to add to the hash computation.
Returns:True on success.

See also: md5_hmac, md5_hash, md5_hash_init, md5_hash_update, md5_hash_finish, sha1_hash, sha1_hash_init, sha1_hash_update, sha1_hash_finish, sha256_hash, sha256_hash_init, sha256_hash_finish

skip_further_processing
Type:function (cid: conn_id) : bool

Informs Bro that it should skip any further processing of the contents of a 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.

Cid:The connection ID.
Returns:False if cid does not point to an active connection, and true otherwise.

Note

Bro will still generate connection-oriented events such as connection_finished.

sort
Type:function (…) : any

Sorts a vector in place. The second argument is a comparison function that takes two arguments: if the vector type is vector of T, then the comparison function must be function(a: T, b: T): int, which returns a value less than zero if a < b for some type-specific notion of the less-than operator. The comparison function is optional if the type is an integral type (int, count, etc.).

V:The vector instance to sort.
Returns:The vector, sorted from minimum to maximum value. If the vector could not be sorted, then the original vector is returned instead.

See also: order

sqrt
Type:function (x: double) : double

Computes the square root of a double.

X:The number to compute the square root of.
Returns:The square root of x.

See also: floor, exp, ln, log10

srand
Type:function (seed: count) : any

Sets the seed for subsequent rand calls.

Seed:The seed for the PRNG.

See also: rand

Note

This function is a wrapper about the function srandom provided by the OS.

strftime
Type:function (fmt: string, d: time) : string

Formats a given time value according to a format string.

Fmt:The format string. See man strftime for the syntax.
D:The time value.
Returns:The time d formatted according to fmt.
string_to_pattern
Type:function (s: string, convert: bool) : pattern

Converts a string into a pattern.

S:The string to convert.
Convert:If true, s is first passed through the function convert_for_pattern to escape special characters of patterns.
Returns:s as pattern.

See also: convert_for_pattern, merge_pattern

Note

This function must be called at Bro startup time, e.g., in the event bro_init.

strptime
Type:function (fmt: string, d: string) : time

Parse a textual representation of a date/time value into a time type value.

Fmt:The format string used to parse the following d argument. See man strftime for the syntax.
D:The string representing the time.
Returns:The time value calculated from parsing d with fmt.
subnet_to_addr
Type:function (sn: subnet) : addr

Converts a subnet to an addr by extracting the prefix.

Sn:The subnet to convert.
Returns:The subnet as an addr.

See also: to_subnet

subnet_width
Type:function (sn: subnet) : count

Returns the width of a subnet.

Sn:The subnet.
Returns:The width of the subnet.

See also: to_subnet

suspend_processing
Type:function () : any

Stops Bro’s packet processing. This function is used to synchronize distributed trace processing with communication enabled (pseudo-realtime mode).

See also: continue_processing, suspend_state_updates, resume_state_updates

suspend_state_updates
Type:function () : any
Attributes:&deprecated

Stops propagating &synchronized accesses.

See also: suspend_processing, continue_processing, resume_state_updates

syslog
Type:function (s: string) : any

Send a string to syslog.

S:The string to log via syslog
system
Type:function (str: string) : int

Invokes a command via the system function of the OS. The command runs in the background with stdout redirecting to stderr. Here is a usage example: system(fmt("rm \"%s\"", str_shell_escape(sniffed_data)));

Str:The command to execute.
Returns:The return value from the OS system function.

See also: system_env, str_shell_escape, piped_exec

Note

Note that 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.

system_env
Type:function (str: string, env: table_string_of_string) : int

Invokes a command via the system function of the OS with a prepared environment. The function is essentially the same as system, but changes the environment before invoking the command.

Str:The command to execute.
Env:A table with the environment variables in the form of key-value pairs. Each specified environment variable name will be automatically prepended with BRO_ARG_.
Returns:The return value from the OS system function.

See also: system, str_shell_escape, piped_exec

terminate
Type:function () : bool

Gracefully shut down Bro by terminating outstanding processing.

Returns:True after successful termination and false when Bro is still in the process of shutting down.

See also: exit, bro_is_terminating

terminate_communication
Type:function () : bool
Attributes:&deprecated

Gracefully finishes communication by first making sure that all remaining data from parent and child has been sent out.

Returns:True if the termination process has been started successfully.
time_to_double
Type:function (t: time) : double

Converts a time value to a double.

T:The time to convert.
Returns:The time value t as double.

See also: double_to_time

to_addr
Type:function (ip: string) : addr

Converts a string to an addr.

Ip:The string to convert.
Returns:The string ip as addr, or the unspecified address :: if the input string does not parse correctly.

See also: to_count, to_int, to_port, count_to_v4_addr, raw_bytes_to_v4_addr, to_subnet

to_count
Type:function (str: string) : count

Converts a string to a count.

Str:The string to convert.
Returns:The string str as unsigned integer, or 0 if str has an invalid format.

See also: to_addr, to_int, to_port, to_subnet

to_double
Type:function (str: string) : double

Converts a string to a double.

Str:The string to convert.
Returns:The string str as double, or 0 if str has an invalid format.
to_int
Type:function (str: string) : int

Converts a string to an int.

Str:The string to convert.
Returns:The string str as int.

See also: to_addr, to_port, to_subnet

to_port
Type:function (s: string) : port

Converts a string to a port.

S:The string to convert.
Returns:A port converted from s.

See also: to_addr, to_count, to_int, to_subnet

to_subnet
Type:function (sn: string) : subnet

Converts a string to a subnet.

Sn:The subnet to convert.
Returns:The sn string as a subnet, or the unspecified subnet ::/0 if the input string does not parse correctly.

See also: to_count, to_int, to_port, count_to_v4_addr, raw_bytes_to_v4_addr, to_addr

type_name
Type:function (t: any) : string

Returns the type name of an arbitrary Bro variable.

T:An arbitrary object.
Returns:The type name of t.
uninstall_dst_addr_filter
Type:function (ip: addr) : bool

Removes a destination address filter.

Ip:The IP address for which a destination filter was previously installed.
Returns:True on success.

See also: Pcap::precompile_pcap_filter, Pcap::install_pcap_filter, install_src_addr_filter, install_src_net_filter, uninstall_src_addr_filter, uninstall_src_net_filter, install_dst_addr_filter, install_dst_net_filter, uninstall_dst_net_filter, Pcap::error

uninstall_dst_net_filter
Type:function (snet: subnet) : bool

Removes a destination subnet filter.

Snet:The subnet for which a destination filter was previously installed.
Returns:True on success.

See also: Pcap::precompile_pcap_filter, Pcap::install_pcap_filter, install_src_addr_filter, install_src_net_filter, uninstall_src_addr_filter, uninstall_src_net_filter, install_dst_addr_filter, install_dst_net_filter, uninstall_dst_addr_filter, Pcap::error

uninstall_src_addr_filter
Type:function (ip: addr) : bool

Removes a source address filter.

Ip:The IP address for which a source filter was previously installed.
Returns:True on success.

See also: Pcap::precompile_pcap_filter, Pcap::install_pcap_filter, install_src_addr_filter, install_src_net_filter, uninstall_src_net_filter, install_dst_addr_filter, install_dst_net_filter, uninstall_dst_addr_filter, uninstall_dst_net_filter, Pcap::error

uninstall_src_net_filter
Type:function (snet: subnet) : bool

Removes a source subnet filter.

Snet:The subnet for which a source filter was previously installed.
Returns:True on success.

See also: Pcap::precompile_pcap_filter, Pcap::install_pcap_filter, install_src_addr_filter, install_src_net_filter, uninstall_src_addr_filter, install_dst_addr_filter, install_dst_net_filter, uninstall_dst_addr_filter, uninstall_dst_net_filter, Pcap::error

unique_id
Type:function (prefix: string) : string

Creates an identifier that is unique with high probability.

Prefix:A custom string prepended to the result.
Returns:A string identifier that is unique.

See also: unique_id_from

unique_id_from
Type:function (pool: int, prefix: string) : string

Creates an identifier that is unique with high probability.

Pool:A seed for determinism.
Prefix:A custom string prepended to the result.
Returns:A string identifier that is unique.

See also: unique_id

Type:function (f: string) : bool

Removes a file from a directory.

F:the file to delete.
Returns:True if the operation succeeds and the file was deleted, and false if the deletion fails.

See also: active_file, open_for_append, close, write_file, get_file_name, set_buf, flush_all, enable_raw_output, mkdir, rmdir, rename

uuid_to_string
Type:function (uuid: string) : string

Converts a bytes representation of a UUID into its string form. For example, given a string of 16 bytes, it produces an output string in this format: 550e8400-e29b-41d4-a716-446655440000. See http://en.wikipedia.org/wiki/Universally_unique_identifier.

Uuid:The 16 bytes of the UUID.
Returns:The string representation of uuid.
val_size
Type:function (v: any) : count

Returns the number of bytes that a value occupies in memory.

V:The value
Returns:The number of bytes that v occupies.
write_file
Type:function (f: file, data: string) : bool

Writes data to an open file.

F:A file handle to an open file.
Data:The data to write to f.
Returns:True on success.

See also: active_file, open, open_for_append, close, get_file_name, set_buf, flush_all, mkdir, enable_raw_output, rmdir, unlink, rename


Previous Page

base/bif/types.bif.bro

Copyright 2016, The Bro Project. Last updated on January 10, 2019. Created using Sphinx 1.7.5.