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 |
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. |
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. |
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_custom: function | 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 | 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. |
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. |
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_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_matcher_stats: function | Returns statistics about the regular expression engine. |
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. |
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_pcap_filter: function | Installs a PCAP filter that has been precompiled with precompile_pcap_filter. |
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_v6_addr: function | Returns whether an address 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. |
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. |
net_stats: function | Returns packet capture statistics. |
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. |
pcap_error: function | Returns a string representation of the last PCAP error. |
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. |
precompile_pcap_filter: function | Precompiles a PCAP filter and binds it to a given identifier. |
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. |
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. |
resource_usage: function | Returns Bro process statistics. |
resume_state_updates: function | Resumes propagating &synchronized accesses. |
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. |
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. |
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. |
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.
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
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
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.
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:
|
Returns: | An anonymized version of a. |
See also: preserve_prefix, preserve_subnet
Todo
Currently dysfunctional.
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
Type: | function () : bool |
---|
Checks if Bro is terminating.
Returns: | True if Bro is in the process of shutting down. |
---|
See also: terminate
Type: | function () : string |
---|
Returns the Bro version string.
Returns: | Bro’s version, e.g., 2.0-beta-47-debug. |
---|
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. |
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. |
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
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
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
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
Type: | function (va_args: any) : 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. |
---|
Type: | function (va_args: any) : 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
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
Type: | function (v: any) : any |
---|
Removes all elements from a set or table.
V: | The set or table |
---|
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
Type: | function (p: event_peer) : bool |
---|
Signals a remote peer that the local Bro instance finished the initial handshake.
P: | The peer ID returned from connect. |
---|---|
Returns: | True on success. |
Type: | function (ip: addr, zone_id: string, p: port, our_class: string, retry: interval, ssl: bool) : count |
---|
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
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
Type: | function () : any |
---|
Resumes Bro’s packet processing.
See also: suspend_processing, suspend_state_updates, resume_state_updates
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
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
Type: | function (ip: count) : addr |
---|
Ip: | The count to convert. |
---|---|
Returns: | The count ip as addr. |
See also: raw_bytes_to_v4_addr, to_addr, to_subnet
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
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. |
---|
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
Type: | function (s: string) : string |
---|
Decodes a Base64-encoded string.
S: | The Base64-encoded string. |
---|---|
Returns: | The decoded version of s. |
See also: decode_base64_custom, encode_base64
Type: | function (s: string, a: string) : string |
---|
Decodes a Base64-encoded string with a custom alphabet.
S: | The Base64-encoded string. |
---|---|
A: | The custom alphabet. The empty string indicates the default alphabet. The length of a must be 64. For example, a custom alphabet could be "!#$%&/(),-.:;<>@[]^ `_{|}~abcdefghijklmnopqrstuvwxyz0123456789+?". |
Returns: | The decoded version of s. |
See also: decode_base64, encode_base64_custom
Type: | function (cid: conn_id, aid: count) : 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
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
Type: | function (p: event_peer) : bool |
---|
Terminate the connection with a peer.
P: | The peer ID returned from connect. |
---|---|
Returns: | True on success. |
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: net_stats, resource_usage, get_matcher_stats, dump_rule_stats, get_gap_summary
Type: | function (d: double) : count |
---|
D: | The double to convert. |
---|---|
Returns: | The double d as unsigned integer, or 0 if d < 0.0. |
See also: double_to_time
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
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
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
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
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: do_profiling, resource_usage, get_matcher_stats, net_stats, get_gap_summary
Todo
The return value should be changed to any or check appropriately.
Type: | function () : any |
---|
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.
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
Type: | function (s: string) : string |
---|
Encodes a Base64-encoded string.
S: | The string to encode |
---|---|
Returns: | The encoded version of s. |
See also: encode_base64_custom, decode_base64
Type: | function (s: string, a: string) : string |
---|
Encodes a Base64-encoded string with a custom alphabet.
S: | The string to encode |
---|---|
A: | The custom alphabet. The empty string indicates the default alphabet. The length of a must be 64. For example, a custom alphabet could be "!#$%&/(),-.:;<>@[]^ `_{|}~abcdefghijklmnopqrstuvwxyz0123456789+?". |
Returns: | The encoded version of s. |
See also: encode_base64, decode_base64_custom
Type: | function (handle: opaque, 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
Type: | function (handle: opaque) : 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
Type: | function () : opaque |
---|
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
Type: | function (code: int) : any |
---|
Shuts down the Bro process immediately.
Code: | The exit code to return with. |
---|
See also: terminate
Type: | function (d: double) : double |
---|
Computes the exponential function.
D: | The argument to the exponential function. |
---|---|
Returns: | e to the power of d. |
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
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]. |
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. |
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.
|
See also: entropy_test_init, entropy_test_add, entropy_test_finish
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. |
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
Type: | function (va_args: any) : 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)
A: Escape only NUL bytes (each one replaced with \0) in a string
[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
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
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
Type: | function () : event_peer |
---|
Returns the peer who generated the last event.
Returns: | The ID of the peer who generated the last event. |
---|
See also: get_local_event_peer
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
Type: | function () : event_peer |
---|
Returns the local peer ID.
Returns: | The peer ID of the local Bro instance. |
---|
See also: get_event_peer
Type: | function () : matcher_stats |
---|
Returns statistics about the regular expression engine. Statistics include the number of distinct matchers, DFA states, DFA state transitions, memory usage of DFA states, cache hits/misses, and average number of NFA states across all matchers.
Returns: | A record with matcher statistics. |
---|
See also: do_profiling, net_stats, resource_usage, dump_rule_stats, get_gap_summary
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
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
Type: | function () : string |
---|
Returns the hostname of the machine Bro runs on.
Returns: | The hostname of the machine Bro runs on. |
---|
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
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
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
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
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: precompile_pcap_filter, 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.
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: precompile_pcap_filter, 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.
Type: | function (id: PcapFilterID) : bool |
---|
Installs a PCAP filter that has been precompiled with precompile_pcap_filter.
Id: | The PCAP filter id of a precompiled filter. |
---|---|
Returns: | True if the filter associated with id has been installed successfully. |
See also: precompile_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, uninstall_dst_net_filter, pcap_error
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: precompile_pcap_filter, 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.
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: precompile_pcap_filter, 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.
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. |
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
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. |
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
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. |
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. |
---|
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
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
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. |
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. |
Type: | function (ip: addr, p: port, ssl: bool, ipv6: bool, zone_id: string, retry_interval: interval) : bool |
---|
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
Type: | function (d: double) : double |
---|
Computes the natural logarithm of a number.
D: | The argument to the logarithm. |
---|---|
Returns: | The natural logarithm of d. |
Type: | function (d: double) : double |
---|
Computes the common logarithm of a number.
D: | The argument to the logarithm. |
---|---|
Returns: | The common logarithm of d. |
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. |
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
Type: | function (a: addr) : count |
---|
Performs an AS lookup of an IP address. Requires Bro to be built with libgeoip.
A: | The IP address to lookup. |
---|---|
Returns: | The number of the AS that contains a. |
See also: lookup_location
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
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
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
Type: | function (a: addr) : geo_location |
---|
Performs a geo-lookup of an IP address. Requires Bro to be built with libgeoip.
A: | The IP address to lookup. |
---|---|
Returns: | A record with country, region, city, latitude, and longitude. |
See also: lookup_asn
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
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.
Type: | function (va_args: any) : 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.
Type: | function (handle: opaque) : 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
Type: | function () : opaque |
---|
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
Type: | function (handle: opaque, 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
Type: | function (va_args: any) : 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
Type: | function (p1: pattern, p2: pattern) : pattern |
---|
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.
Type: | function (f: string) : bool |
---|
Creates a new directory.
F: | The directory name. |
---|---|
Returns: | 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
Type: | function () : NetStats |
---|
Returns packet capture statistics. Statistics include the number of packets (i) received by Bro, (ii) dropped, and (iii) seen on the link (not always available).
Returns: | A record of packet statistics. |
---|
See also: do_profiling, resource_usage, get_matcher_stats, dump_rule_stats, get_gap_summary
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
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
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
Type: | function (va_args: any) : 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
Type: | function () : string |
---|
Returns a string representation of the last PCAP error.
Returns: | A descriptive error message of the PCAP function that failed. |
---|
See also: precompile_pcap_filter, 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, uninstall_dst_net_filter
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
Type: | function (p: port) : count |
---|
P: | The port to convert. |
---|---|
Returns: | The port p as count. |
See also: count_to_port
Type: | function (id: PcapFilterID, s: string) : bool |
---|
Precompiles a PCAP filter and binds it to a given identifier.
Id: | The PCAP identifier to reference the filter s later on. |
---|---|
S: | The PCAP filter. See man tcpdump for valid expressions. |
Returns: | True if s is valid and precompiles successfully. |
See also: 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, uninstall_dst_net_filter, pcap_error
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.
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.
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
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.
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
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
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
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 to inspect. |
---|---|
Returns: | A table that describes the fields of a record. |
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. |
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
Type: | function (p: event_peer, handlers: pattern) : bool |
---|
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
Type: | function (p: event_peer) : bool |
---|
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
Type: | function (p: event_peer, auth: bool) : bool |
---|
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
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
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. |
Type: | function () : bro_resources |
---|
Returns Bro process statistics. Statistics include real/user/sys CPU time, memory usage, page faults, number of TCP/UDP/ICMP connections, timers, and events queued/dispatched.
Returns: | A record with resource usage statistics. |
---|
See also: do_profiling, net_stats, get_matcher_stats, dump_rule_stats, get_gap_summary
Type: | function () : any |
---|
Resumes propagating &synchronized accesses.
See also: suspend_processing, continue_processing, suspend_state_updates
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
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
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. |
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. |
Type: | function (p: event_peer, s: string) : bool |
---|
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
Type: | function (p: event_peer) : bool |
---|
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
Type: | function (p: event_peer, id: string) : bool |
---|
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
Type: | function (p: event_peer, seq: count) : bool |
---|
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
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
Type: | function (p: event_peer, accept: bool) : bool |
---|
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
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
Type: | function (p: event_peer, level: count) : bool |
---|
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
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. |
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
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
Type: | function (va_args: any) : 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.
Type: | function (handle: opaque) : 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
Type: | function () : opaque |
---|
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
Type: | function (handle: opaque, 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
Type: | function (va_args: any) : 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.
Type: | function (handle: opaque) : 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
Type: | function () : opaque |
---|
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
Type: | function (handle: opaque, 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
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.
Type: | function (va_args: any) : 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
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. |
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.
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. |
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.
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. |
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
Type: | function () : any |
---|
Stops propagating &synchronized accesses.
See also: suspend_processing, continue_processing, resume_state_updates
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.
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
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
Type: | function () : bool |
---|
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. |
---|
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
Type: | function (ip: string) : 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
Type: | function (str: string) : count |
---|
Str: | The string to convert. |
---|---|
Returns: | The string str as unsigned integer, or 0 if str has an invalid format. |
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. |
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: | function (t: any) : string |
---|
Returns the type name of an arbitrary Bro variable.
T: | An arbitrary object. |
---|---|
Returns: | The type name of t. |
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: precompile_pcap_filter, 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
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: precompile_pcap_filter, 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
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: precompile_pcap_filter, 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
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: precompile_pcap_filter, 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
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
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 (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. |
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. |
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