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`	Signals a remote peer that the local Bro instance finished the initial handshake.
`connect`: `function`	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`	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`	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`.
`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`	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`	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.
`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`	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 AS 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`	Merges and compiles two regular expressions at initialization time.
`mkdir`: `function`	Creates a new directory.
`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`	Subscribes to all events from a remote peer whose names match a given pattern.
`request_remote_logs`: `function`	Requests logs from a remote peer.
`request_remote_sync`: `function`	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`	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`	Sends a capture filter to a remote peer.
`send_current_packet`: `function`	Sends the currently processed packet to a remote peer.
`send_id`: `function`	Sends a global identifier to a remote peer, which then might install it locally.
`send_ping`: `function`	Sends a ping event to a remote peer.
`send_state`: `function`	Sends all persistent state to a remote peer.
`set_accept_state`: `function`	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`	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`	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`	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.

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

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

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.

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:	The string of bytes.
Returns:	The hexadecimal representation of bytestring.

base/bif/bro.bif.bro

Summary

Functions

Detailed Interface

Functions

Table of Contents

Next Page

Previous Page

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

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

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

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

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.

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

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

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.

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

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

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

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

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.

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.

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

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.

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

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

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

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

base/bif/bro.bif.bro

Summary

Functions

Detailed Interface

Functions

Table of Contents

Next Page

Previous Page

Search

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

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

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.

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

E:	The `enum` to convert.
Returns:	The `int` value that corresponds to the `enum`.

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

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

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]`.

F:	The name of the file whose size to lookup.
Returns:	The size of f in bytes.

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