Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-07 17:18:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
zeek/doc/scripts/base/bif/bro.bif.bro.rst
Jon Siwek 7e9d48f532 Remove broxygen Sphinx integration 
The broxygen-generated files now live in the git repo, have tests
that check that they are up-to-date, and a script to re-generate
them on-demand.
2018-12-18 10:15:22 -06:00

3567 lines
121 KiB
ReStructuredText
Raw Blame History

:tocdepth: 3
base/bif/bro.bif.bro
====================
.. bro:namespace:: 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
Summary
~~~~~~~
Functions
#########
=============================================================================== ===============================================================================
:bro:id:`active_file`: :bro:type:`function` Checks whether a given file is open.
:bro:id:`addr_to_counts`: :bro:type:`function` Converts an :bro:type:`addr` to an :bro:type:`index_vec`.
:bro:id:`addr_to_ptr_name`: :bro:type:`function` Converts an IP address to a reverse pointer name.
:bro:id:`addr_to_subnet`: :bro:type:`function` Converts a :bro:type:`addr` to a :bro:type:`subnet`.
:bro:id:`all_set`: :bro:type:`function` Tests whether *all* elements of a boolean vector (``vector of bool``) are
true.
:bro:id:`anonymize_addr`: :bro:type:`function` Anonymizes an IP address.
:bro:id:`any_set`: :bro:type:`function` Tests whether a boolean vector (``vector of bool``) has *any* true
element.
:bro:id:`bro_is_terminating`: :bro:type:`function` Checks if Bro is terminating.
:bro:id:`bro_version`: :bro:type:`function` Returns the Bro version string.
:bro:id:`bytestring_to_count`: :bro:type:`function` Converts a string of bytes to a :bro:type:`count`.
:bro:id:`bytestring_to_double`: :bro:type:`function` Converts a string of bytes (in network byte order) to a :bro:type:`double`.
:bro:id:`bytestring_to_hexstr`: :bro:type:`function` Converts a string of bytes into its hexadecimal representation.
:bro:id:`calc_next_rotate`: :bro:type:`function` Calculates the duration until the next time a file is to be rotated, based
on a given rotate interval.
:bro:id:`capture_events`: :bro:type:`function` Writes the binary event stream generated by the core to a given file.
:bro:id:`capture_state_updates`: :bro:type:`function` Writes state updates generated by :bro:attr:`&synchronized` variables to a
file.
:bro:id:`cat`: :bro:type:`function` Returns the concatenation of the string representation of its arguments.
:bro:id:`cat_sep`: :bro:type:`function` Concatenates all arguments, with a separator placed between each one.
:bro:id:`check_subnet`: :bro:type:`function` Checks if a specific subnet is a member of a set/table[subnet].
:bro:id:`checkpoint_state`: :bro:type:`function` Flushes in-memory state tagged with the :bro:attr:`&persistent` attribute
to disk.
:bro:id:`clear_table`: :bro:type:`function` Removes all elements from a set or table.
:bro:id:`close`: :bro:type:`function` Closes an open file and flushes any buffered content.
:bro:id:`complete_handshake`: :bro:type:`function` :bro:attr:`&deprecated` Signals a remote peer that the local Bro instance finished the initial
handshake.
:bro:id:`connect`: :bro:type:`function` :bro:attr:`&deprecated` Establishes a connection to a remote Bro or Broccoli instance.
:bro:id:`connection_exists`: :bro:type:`function` Checks whether a connection is (still) active.
:bro:id:`continue_processing`: :bro:type:`function` Resumes Bro's packet processing.
:bro:id:`convert_for_pattern`: :bro:type:`function` Escapes a string so that it becomes a valid :bro:type:`pattern` and can be
used with the :bro:id:`string_to_pattern`.
:bro:id:`count_to_port`: :bro:type:`function` Converts a :bro:type:`count` and ``transport_proto`` to a :bro:type:`port`.
:bro:id:`count_to_v4_addr`: :bro:type:`function` Converts a :bro:type:`count` to an :bro:type:`addr`.
:bro:id:`counts_to_addr`: :bro:type:`function` Converts an :bro:type:`index_vec` to an :bro:type:`addr`.
:bro:id:`current_analyzer`: :bro:type:`function` Returns the ID of the analyzer which raised the current event.
:bro:id:`current_time`: :bro:type:`function` Returns the current wall-clock time.
:bro:id:`decode_base64`: :bro:type:`function` Decodes a Base64-encoded string.
:bro:id:`decode_base64_conn`: :bro:type:`function` Decodes a Base64-encoded string that was derived from processing a connection.
:bro:id:`decode_base64_custom`: :bro:type:`function` :bro:attr:`&deprecated` Decodes a Base64-encoded string with a custom alphabet.
:bro:id:`disable_analyzer`: :bro:type:`function` Disables the analyzer which raised the current event (if the analyzer
belongs to the given connection).
:bro:id:`disable_print_hook`: :bro:type:`function` Disables sending :bro:id:`print_hook` events to remote peers for a given
file.
:bro:id:`disconnect`: :bro:type:`function` :bro:attr:`&deprecated` Terminate the connection with a peer.
:bro:id:`do_profiling`: :bro:type:`function` Enables detailed collection of profiling statistics.
:bro:id:`double_to_count`: :bro:type:`function` Converts a :bro:type:`double` to a :bro:type:`count`.
:bro:id:`double_to_interval`: :bro:type:`function` Converts a :bro:type:`double` to an :bro:type:`interval`.
:bro:id:`double_to_time`: :bro:type:`function` Converts a :bro:type:`double` value to a :bro:type:`time`.
:bro:id:`dump_current_packet`: :bro:type:`function` Writes the current packet to a file.
:bro:id:`dump_packet`: :bro:type:`function` Writes a given packet to a file.
:bro:id:`dump_rule_stats`: :bro:type:`function` Write rule matcher statistics (DFA states, transitions, memory usage, cache
hits/misses) to a file.
:bro:id:`enable_communication`: :bro:type:`function` :bro:attr:`&deprecated` Enables the communication system.
:bro:id:`enable_raw_output`: :bro:type:`function` Prevents escaping of non-ASCII characters when writing to a file.
:bro:id:`encode_base64`: :bro:type:`function` Encodes a Base64-encoded string.
:bro:id:`encode_base64_custom`: :bro:type:`function` :bro:attr:`&deprecated` Encodes a Base64-encoded string with a custom alphabet.
:bro:id:`entropy_test_add`: :bro:type:`function` Adds data to an incremental entropy calculation.
:bro:id:`entropy_test_finish`: :bro:type:`function` Finishes an incremental entropy calculation.
:bro:id:`entropy_test_init`: :bro:type:`function` Initializes data structures for incremental entropy calculation.
:bro:id:`enum_to_int`: :bro:type:`function` Converts an :bro:type:`enum` to an :bro:type:`int`.
:bro:id:`exit`: :bro:type:`function` Shuts down the Bro process immediately.
:bro:id:`exp`: :bro:type:`function` Computes the exponential function.
:bro:id:`file_magic`: :bro:type:`function` Determines the MIME type of a piece of data using Bro's file magic
signatures.
:bro:id:`file_mode`: :bro:type:`function` Converts UNIX file permissions given by a mode to an ASCII string.
:bro:id:`file_size`: :bro:type:`function` Returns the size of a given file.
:bro:id:`filter_subnet_table`: :bro:type:`function` For a set[subnet]/table[subnet], create a new table that contains all entries
that contain a given subnet.
:bro:id:`find_entropy`: :bro:type:`function` Performs an entropy test on the given data.
:bro:id:`floor`: :bro:type:`function` Computes the greatest integer less than the given :bro:type:`double` value.
:bro:id:`flush_all`: :bro:type:`function` Flushes all open files to disk.
:bro:id:`fmt`: :bro:type:`function` Produces a formatted string à la ``printf``.
:bro:id:`fnv1a32`: :bro:type:`function` Returns 32-bit digest of arbitrary input values using FNV-1a hash algorithm.
:bro:id:`get_conn_transport_proto`: :bro:type:`function` Extracts the transport protocol from a connection.
:bro:id:`get_current_packet`: :bro:type:`function` Returns the currently processed PCAP packet.
:bro:id:`get_current_packet_header`: :bro:type:`function` Function to get the raw headers of the currently processed packet.
:bro:id:`get_event_peer`: :bro:type:`function` :bro:attr:`&deprecated` Returns the peer who generated the last event.
:bro:id:`get_file_name`: :bro:type:`function` Gets the filename associated with a file handle.
:bro:id:`get_local_event_peer`: :bro:type:`function` :bro:attr:`&deprecated` Returns the local peer ID.
:bro:id:`get_port_transport_proto`: :bro:type:`function` Extracts the transport protocol from a :bro:type:`port`.
:bro:id:`getenv`: :bro:type:`function` Returns a system environment variable.
:bro:id:`gethostname`: :bro:type:`function` Returns the hostname of the machine Bro runs on.
:bro:id:`getpid`: :bro:type:`function` Returns Bro's process ID.
:bro:id:`global_ids`: :bro:type:`function` Generates a table with information about all global identifiers.
:bro:id:`global_sizes`: :bro:type:`function` Generates a table of the size of all global variables.
:bro:id:`haversine_distance`: :bro:type:`function` Calculates distance between two geographic locations using the haversine
formula.
:bro:id:`hexstr_to_bytestring`: :bro:type:`function` Converts a hex-string into its binary representation.
:bro:id:`hrw_weight`: :bro:type:`function` Calculates a weight value for use in a Rendezvous Hashing algorithm.
:bro:id:`identify_data`: :bro:type:`function` Determines the MIME type of a piece of data using Bro's file magic
signatures.
:bro:id:`install_dst_addr_filter`: :bro:type:`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.
:bro:id:`install_dst_net_filter`: :bro:type:`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.
:bro:id:`install_src_addr_filter`: :bro:type:`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.
:bro:id:`install_src_net_filter`: :bro:type:`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.
:bro:id:`int_to_count`: :bro:type:`function` Converts a (positive) :bro:type:`int` to a :bro:type:`count`.
:bro:id:`interval_to_double`: :bro:type:`function` Converts an :bro:type:`interval` to a :bro:type:`double`.
:bro:id:`is_external_connection`: :bro:type:`function` Determines whether a connection has been received externally.
:bro:id:`is_icmp_port`: :bro:type:`function` Checks whether a given :bro:type:`port` has ICMP as transport protocol.
:bro:id:`is_local_interface`: :bro:type:`function` Checks whether a given IP address belongs to a local interface.
:bro:id:`is_remote_event`: :bro:type:`function` Checks whether the last raised event came from a remote peer.
:bro:id:`is_tcp_port`: :bro:type:`function` Checks whether a given :bro:type:`port` has TCP as transport protocol.
:bro:id:`is_udp_port`: :bro:type:`function` Checks whether a given :bro:type:`port` has UDP as transport protocol.
:bro:id:`is_v4_addr`: :bro:type:`function` Returns whether an address is IPv4 or not.
:bro:id:`is_v4_subnet`: :bro:type:`function` Returns whether a subnet specification is IPv4 or not.
:bro:id:`is_v6_addr`: :bro:type:`function` Returns whether an address is IPv6 or not.
:bro:id:`is_v6_subnet`: :bro:type:`function` Returns whether a subnet specification is IPv6 or not.
:bro:id:`listen`: :bro:type:`function` :bro:attr:`&deprecated` Listens on a given IP address and port for remote connections.
:bro:id:`ln`: :bro:type:`function` Computes the natural logarithm of a number.
:bro:id:`log10`: :bro:type:`function` Computes the common logarithm of a number.
:bro:id:`lookup_ID`: :bro:type:`function` Returns the value of a global identifier.
:bro:id:`lookup_addr`: :bro:type:`function` Issues an asynchronous reverse DNS lookup and delays the function result.
:bro:id:`lookup_asn`: :bro:type:`function` Performs an ASN lookup of an IP address.
:bro:id:`lookup_connection`: :bro:type:`function` Returns the :bro:type:`connection` record for a given connection identifier.
:bro:id:`lookup_hostname`: :bro:type:`function` Issues an asynchronous DNS lookup and delays the function result.
:bro:id:`lookup_hostname_txt`: :bro:type:`function` Issues an asynchronous TEXT DNS lookup and delays the function result.
:bro:id:`lookup_location`: :bro:type:`function` Performs a geo-lookup of an IP address.
:bro:id:`mask_addr`: :bro:type:`function` Masks an address down to the number of given upper bits.
:bro:id:`match_signatures`: :bro:type:`function` Manually triggers the signature engine for a given connection.
:bro:id:`matching_subnets`: :bro:type:`function` Gets all subnets that contain a given subnet from a set/table[subnet].
:bro:id:`md5_hash`: :bro:type:`function` Computes the MD5 hash value of the provided list of arguments.
:bro:id:`md5_hash_finish`: :bro:type:`function` Returns the final MD5 digest of an incremental hash computation.
:bro:id:`md5_hash_init`: :bro:type:`function` Constructs an MD5 handle to enable incremental hash computation.
:bro:id:`md5_hash_update`: :bro:type:`function` Updates the MD5 value associated with a given index.
:bro:id:`md5_hmac`: :bro:type:`function` Computes an HMAC-MD5 hash value of the provided list of arguments.
:bro:id:`merge_pattern`: :bro:type:`function` :bro:attr:`&deprecated` Merges and compiles two regular expressions at initialization time.
:bro:id:`mkdir`: :bro:type:`function` Creates a new directory.
:bro:id:`mmdb_open_asn_db`: :bro:type:`function` Initializes MMDB for later use of lookup_asn.
:bro:id:`mmdb_open_location_db`: :bro:type:`function` Initializes MMDB for later use of lookup_location.
:bro:id:`network_time`: :bro:type:`function` Returns the timestamp of the last packet processed.
:bro:id:`open`: :bro:type:`function` Opens a file for writing.
:bro:id:`open_for_append`: :bro:type:`function` Opens a file for writing or appending.
:bro:id:`order`: :bro:type:`function` Returns the order of the elements in a vector according to some
comparison function.
:bro:id:`piped_exec`: :bro:type:`function` Opens a program with ``popen`` and writes a given string to the returned
stream to send it to the opened process's stdin.
:bro:id:`port_to_count`: :bro:type:`function` Converts a :bro:type:`port` to a :bro:type:`count`.
:bro:id:`preserve_prefix`: :bro:type:`function` Preserves the prefix of an IP address in anonymization.
:bro:id:`preserve_subnet`: :bro:type:`function` Preserves the prefix of a subnet in anonymization.
:bro:id:`ptr_name_to_addr`: :bro:type:`function` Converts a reverse pointer name to an address.
:bro:id:`rand`: :bro:type:`function` Generates a random number.
:bro:id:`raw_bytes_to_v4_addr`: :bro:type:`function` Converts a :bro:type:`string` of bytes into an IPv4 address.
:bro:id:`reading_live_traffic`: :bro:type:`function` Checks whether Bro reads traffic from one or more network interfaces (as
opposed to from a network trace in a file).
:bro:id:`reading_traces`: :bro:type:`function` Checks whether Bro reads traffic from a trace file (as opposed to from a
network interface).
:bro:id:`record_fields`: :bro:type:`function` Generates metadata about a record's fields.
:bro:id:`record_type_to_vector`: :bro:type:`function` Converts a record type name to a vector of strings, where each element is
the name of a record field.
:bro:id:`remask_addr`: :bro:type:`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.
:bro:id:`rename`: :bro:type:`function` Renames a file from src_f to dst_f.
:bro:id:`request_remote_events`: :bro:type:`function` :bro:attr:`&deprecated` Subscribes to all events from a remote peer whose names match a given
pattern.
:bro:id:`request_remote_logs`: :bro:type:`function` :bro:attr:`&deprecated` Requests logs from a remote peer.
:bro:id:`request_remote_sync`: :bro:type:`function` :bro:attr:`&deprecated` Requests synchronization of IDs with a remote peer.
:bro:id:`rescan_state`: :bro:type:`function` Reads persistent state and populates the in-memory data structures
accordingly.
:bro:id:`resize`: :bro:type:`function` Resizes a vector.
:bro:id:`resume_state_updates`: :bro:type:`function` :bro:attr:`&deprecated` Resumes propagating :bro:attr:`&synchronized` accesses.
:bro:id:`rmdir`: :bro:type:`function` Removes a directory.
:bro:id:`rotate_file`: :bro:type:`function` Rotates a file.
:bro:id:`rotate_file_by_name`: :bro:type:`function` Rotates a file identified by its name.
:bro:id:`routing0_data_to_addrs`: :bro:type:`function` Converts the *data* field of :bro:type:`ip6_routing` records that have
*rtype* of 0 into a vector of addresses.
:bro:id:`same_object`: :bro:type:`function` Checks whether two objects reference the same internal object.
:bro:id:`send_capture_filter`: :bro:type:`function` :bro:attr:`&deprecated` Sends a capture filter to a remote peer.
:bro:id:`send_current_packet`: :bro:type:`function` :bro:attr:`&deprecated` Sends the currently processed packet to a remote peer.
:bro:id:`send_id`: :bro:type:`function` :bro:attr:`&deprecated` Sends a global identifier to a remote peer, which then might install it
locally.
:bro:id:`send_ping`: :bro:type:`function` :bro:attr:`&deprecated` Sends a ping event to a remote peer.
:bro:id:`send_state`: :bro:type:`function` Sends all persistent state to a remote peer.
:bro:id:`set_accept_state`: :bro:type:`function` :bro:attr:`&deprecated` Sets a boolean flag indicating whether Bro accepts state from a remote peer.
:bro:id:`set_buf`: :bro:type:`function` Alters the buffering behavior of a file.
:bro:id:`set_compression_level`: :bro:type:`function` :bro:attr:`&deprecated` Sets the compression level of the session with a remote peer.
:bro:id:`set_inactivity_timeout`: :bro:type:`function` Sets an individual inactivity timeout for a connection and thus
overrides the global inactivity timeout.
:bro:id:`set_record_packets`: :bro:type:`function` Controls whether packet contents belonging to a connection should be
recorded (when ``-w`` option is provided on the command line).
:bro:id:`setenv`: :bro:type:`function` Sets a system environment variable.
:bro:id:`sha1_hash`: :bro:type:`function` Computes the SHA1 hash value of the provided list of arguments.
:bro:id:`sha1_hash_finish`: :bro:type:`function` Returns the final SHA1 digest of an incremental hash computation.
:bro:id:`sha1_hash_init`: :bro:type:`function` Constructs an SHA1 handle to enable incremental hash computation.
:bro:id:`sha1_hash_update`: :bro:type:`function` Updates the SHA1 value associated with a given index.
:bro:id:`sha256_hash`: :bro:type:`function` Computes the SHA256 hash value of the provided list of arguments.
:bro:id:`sha256_hash_finish`: :bro:type:`function` Returns the final SHA256 digest of an incremental hash computation.
:bro:id:`sha256_hash_init`: :bro:type:`function` Constructs an SHA256 handle to enable incremental hash computation.
:bro:id:`sha256_hash_update`: :bro:type:`function` Updates the SHA256 value associated with a given index.
:bro:id:`skip_further_processing`: :bro:type:`function` Informs Bro that it should skip any further processing of the contents of
a given connection.
:bro:id:`sort`: :bro:type:`function` Sorts a vector in place.
:bro:id:`sqrt`: :bro:type:`function` Computes the square root of a :bro:type:`double`.
:bro:id:`srand`: :bro:type:`function` Sets the seed for subsequent :bro:id:`rand` calls.
:bro:id:`strftime`: :bro:type:`function` Formats a given time value according to a format string.
:bro:id:`string_to_pattern`: :bro:type:`function` Converts a :bro:type:`string` into a :bro:type:`pattern`.
:bro:id:`strptime`: :bro:type:`function` Parse a textual representation of a date/time value into a ``time`` type value.
:bro:id:`subnet_to_addr`: :bro:type:`function` Converts a :bro:type:`subnet` to an :bro:type:`addr` by
extracting the prefix.
:bro:id:`subnet_width`: :bro:type:`function` Returns the width of a :bro:type:`subnet`.
:bro:id:`suspend_processing`: :bro:type:`function` Stops Bro's packet processing.
:bro:id:`suspend_state_updates`: :bro:type:`function` :bro:attr:`&deprecated` Stops propagating :bro:attr:`&synchronized` accesses.
:bro:id:`syslog`: :bro:type:`function` Send a string to syslog.
:bro:id:`system`: :bro:type:`function` Invokes a command via the ``system`` function of the OS.
:bro:id:`system_env`: :bro:type:`function` Invokes a command via the ``system`` function of the OS with a prepared
environment.
:bro:id:`terminate`: :bro:type:`function` Gracefully shut down Bro by terminating outstanding processing.
:bro:id:`terminate_communication`: :bro:type:`function` :bro:attr:`&deprecated` Gracefully finishes communication by first making sure that all remaining
data from parent and child has been sent out.
:bro:id:`time_to_double`: :bro:type:`function` Converts a :bro:type:`time` value to a :bro:type:`double`.
:bro:id:`to_addr`: :bro:type:`function` Converts a :bro:type:`string` to an :bro:type:`addr`.
:bro:id:`to_count`: :bro:type:`function` Converts a :bro:type:`string` to a :bro:type:`count`.
:bro:id:`to_double`: :bro:type:`function` Converts a :bro:type:`string` to a :bro:type:`double`.
:bro:id:`to_int`: :bro:type:`function` Converts a :bro:type:`string` to an :bro:type:`int`.
:bro:id:`to_port`: :bro:type:`function` Converts a :bro:type:`string` to a :bro:type:`port`.
:bro:id:`to_subnet`: :bro:type:`function` Converts a :bro:type:`string` to a :bro:type:`subnet`.
:bro:id:`type_name`: :bro:type:`function` Returns the type name of an arbitrary Bro variable.
:bro:id:`uninstall_dst_addr_filter`: :bro:type:`function` Removes a destination address filter.
:bro:id:`uninstall_dst_net_filter`: :bro:type:`function` Removes a destination subnet filter.
:bro:id:`uninstall_src_addr_filter`: :bro:type:`function` Removes a source address filter.
:bro:id:`uninstall_src_net_filter`: :bro:type:`function` Removes a source subnet filter.
:bro:id:`unique_id`: :bro:type:`function` Creates an identifier that is unique with high probability.
:bro:id:`unique_id_from`: :bro:type:`function` Creates an identifier that is unique with high probability.
:bro:id:`unlink`: :bro:type:`function` Removes a file from a directory.
:bro:id:`uuid_to_string`: :bro:type:`function` Converts a bytes representation of a UUID into its string form.
:bro:id:`val_size`: :bro:type:`function` Returns the number of bytes that a value occupies in memory.
:bro:id:`write_file`: :bro:type:`function` Writes data to an open file.
=============================================================================== ===============================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Functions
#########
.. bro:id:: active_file
:Type: :bro:type:`function` (f: :bro:type:`file`) : :bro:type:`bool`
Checks whether a given file is open.
:f: The file to check.
:returns: True if *f* is an open :bro:type:`file`.
.. todo:: Rename to ``is_open``.
.. bro:id:: addr_to_counts
:Type: :bro:type:`function` (a: :bro:type:`addr`) : :bro:type:`index_vec`
Converts an :bro:type:`addr` to an :bro:type:`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.
.. bro:see:: counts_to_addr
.. bro:id:: addr_to_ptr_name
:Type: :bro:type:`function` (a: :bro:type:`addr`) : :bro:type:`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*.
.. bro:see:: ptr_name_to_addr to_addr
.. bro:id:: addr_to_subnet
:Type: :bro:type:`function` (a: :bro:type:`addr`) : :bro:type:`subnet`
Converts a :bro:type:`addr` to a :bro:type:`subnet`.
:a: The address to convert.
:returns: The address as a :bro:type:`subnet`.
.. bro:see:: to_subnet
.. bro:id:: all_set
:Type: :bro:type:`function` (v: :bro:type:`any`) : :bro:type:`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.
.. bro:see:: any_set
.. note::
Missing elements count as false.
.. bro:id:: anonymize_addr
:Type: :bro:type:`function` (a: :bro:type:`addr`, cl: :bro:type:`IPAddrAnonymizationClass`) : :bro:type:`addr`
Anonymizes an IP address.
:a: The address to anonymize.
:cl: The anonymization class, which can take on three different values:
- ``ORIG_ADDR``: Tag *a* as an originator address.
- ``RESP_ADDR``: Tag *a* as an responder address.
- ``OTHER_ADDR``: Tag *a* as an arbitrary address.
:returns: An anonymized version of *a*.
.. bro:see:: preserve_prefix preserve_subnet
.. todo:: Currently dysfunctional.
.. bro:id:: any_set
:Type: :bro:type:`function` (v: :bro:type:`any`) : :bro:type:`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.
.. bro:see:: all_set
.. bro:id:: bro_is_terminating
:Type: :bro:type:`function` () : :bro:type:`bool`
Checks if Bro is terminating.
:returns: True if Bro is in the process of shutting down.
.. bro:see:: terminate
.. bro:id:: bro_version
:Type: :bro:type:`function` () : :bro:type:`string`
Returns the Bro version string.
:returns: Bro's version, e.g., 2.0-beta-47-debug.
.. bro:id:: bytestring_to_count
:Type: :bro:type:`function` (s: :bro:type:`string`, is_le: :bro:type:`bool` :bro:attr:`&default` = ``F`` :bro:attr:`&optional`) : :bro:type:`count`
Converts a string of bytes to a :bro:type:`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.
.. bro:id:: bytestring_to_double
:Type: :bro:type:`function` (s: :bro:type:`string`) : :bro:type:`double`
Converts a string of bytes (in network byte order) to a :bro:type:`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.
.. bro:id:: bytestring_to_hexstr
:Type: :bro:type:`function` (bytestring: :bro:type:`string`) : :bro:type:`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*.
.. bro:see:: hexdump hexstr_to_bytestring
.. bro:id:: calc_next_rotate
:Type: :bro:type:`function` (i: :bro:type:`interval`) : :bro:type:`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.
.. bro:see:: rotate_file rotate_file_by_name
.. bro:id:: capture_events
:Type: :bro:type:`function` (filename: :bro:type:`string`) : :bro:type:`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.
.. bro:see:: capture_state_updates
.. bro:id:: capture_state_updates
:Type: :bro:type:`function` (filename: :bro:type:`string`) : :bro:type:`bool`
Writes state updates generated by :bro:attr:`&synchronized` variables to a
file.
:filename: The name of the file which stores the state updates.
:returns: True if opening the target file succeeds.
.. bro:see:: capture_events
.. bro:id:: cat
:Type: :bro:type:`function` (...) : :bro:type:`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.
.. bro:id:: cat_sep
:Type: :bro:type:`function` (...) : :bro:type:`string`
Concatenates all arguments, with a separator placed between each one. This
function is similar to :bro:id:`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*.
.. bro:see:: cat string_cat cat_string_array cat_string_array_n
.. bro:id:: check_subnet
:Type: :bro:type:`function` (search: :bro:type:`subnet`, t: :bro:type:`any`) : :bro:type:`bool`
Checks if a specific subnet is a member of a set/table[subnet].
In contrast to the ``in`` operator, this performs an exact match, not
a longest prefix match.
:search: the subnet to search for.
:t: the set[subnet] or table[subnet].
:returns: True if the exact subnet is a member, false otherwise.
.. bro:id:: checkpoint_state
:Type: :bro:type:`function` () : :bro:type:`bool`
Flushes in-memory state tagged with the :bro:attr:`&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.
.. bro:see:: rescan_state
.. bro:id:: clear_table
:Type: :bro:type:`function` (v: :bro:type:`any`) : :bro:type:`any`
Removes all elements from a set or table.
:v: The set or table
.. bro:id:: close
:Type: :bro:type:`function` (f: :bro:type:`file`) : :bro:type:`bool`
Closes an open file and flushes any buffered content.
:f: A :bro:type:`file` handle to an open file.
:returns: True on success.
.. bro:see:: active_file open open_for_append write_file
get_file_name set_buf flush_all mkdir enable_raw_output
rmdir unlink rename
.. bro:id:: complete_handshake
:Type: :bro:type:`function` (p: :bro:type:`event_peer`) : :bro:type:`bool`
:Attributes: :bro:attr:`&deprecated`
Signals a remote peer that the local Bro instance finished the initial
handshake.
:p: The peer ID returned from :bro:id:`connect`.
:returns: True on success.
.. bro:id:: connect
:Type: :bro:type:`function` (ip: :bro:type:`addr`, zone_id: :bro:type:`string`, p: :bro:type:`port`, our_class: :bro:type:`string`, retry: :bro:type:`interval`, ssl: :bro:type:`bool`) : :bro:type:`count`
:Attributes: :bro:attr:`&deprecated`
Establishes a connection to a remote Bro or Broccoli instance.
:ip: The IP address of the remote peer.
:zone_id: If *ip* is a non-global IPv6 address, a particular :rfc:`4007`
``zone_id`` can given here. An empty string, ``""``, means
not to add any ``zone_id``.
:p: The port of the remote peer.
:our_class: If a non-empty string, then the remote (listening) peer checks it
against its class name in its peer table and terminates the
connection if they don't match.
:retry: If the connection fails, try to reconnect with the peer after this
time interval.
:ssl: If true, use SSL to encrypt the session.
:returns: A locally unique ID of the new peer.
.. bro:see:: disconnect
listen
request_remote_events
request_remote_sync
request_remote_logs
request_remote_events
set_accept_state
set_compression_level
send_state
send_id
.. bro:id:: connection_exists
:Type: :bro:type:`function` (c: :bro:type:`conn_id`) : :bro:type:`bool`
Checks whether a connection is (still) active.
:c: The connection id to check.
:returns: True if the connection identified by *c* exists.
.. bro:see:: lookup_connection
.. bro:id:: continue_processing
:Type: :bro:type:`function` () : :bro:type:`any`
Resumes Bro's packet processing.
.. bro:see:: suspend_processing suspend_state_updates resume_state_updates
.. bro:id:: convert_for_pattern
:Type: :bro:type:`function` (s: :bro:type:`string`) : :bro:type:`string`
Escapes a string so that it becomes a valid :bro:type:`pattern` and can be
used with the :bro:id:`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
:bro:type:`pattern`.
.. bro:see:: merge_pattern string_to_pattern
.. bro:id:: count_to_port
:Type: :bro:type:`function` (num: :bro:type:`count`, proto: :bro:type:`transport_proto`) : :bro:type:`port`
Converts a :bro:type:`count` and ``transport_proto`` to a :bro:type:`port`.
:num: The :bro:type:`port` number.
:proto: The transport protocol.
:returns: The :bro:type:`count` *num* as :bro:type:`port`.
.. bro:see:: port_to_count
.. bro:id:: count_to_v4_addr
:Type: :bro:type:`function` (ip: :bro:type:`count`) : :bro:type:`addr`
Converts a :bro:type:`count` to an :bro:type:`addr`.
:ip: The :bro:type:`count` to convert.
:returns: The :bro:type:`count` *ip* as :bro:type:`addr`.
.. bro:see:: raw_bytes_to_v4_addr to_addr to_subnet
.. bro:id:: counts_to_addr
:Type: :bro:type:`function` (v: :bro:type:`index_vec`) : :bro:type:`addr`
Converts an :bro:type:`index_vec` to an :bro:type:`addr`.
:v: The vector containing host-order IP address representation,
one element for IPv4 addresses, four elements for IPv6 addresses.
:returns: An IP address.
.. bro:see:: addr_to_counts
.. bro:id:: current_analyzer
:Type: :bro:type:`function` () : :bro:type:`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.
.. bro:id:: current_time
:Type: :bro:type:`function` () : :bro:type:`time`
Returns the current wall-clock time.
In general, you should use :bro:id:`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.
.. bro:see:: network_time
.. bro:id:: decode_base64
:Type: :bro:type:`function` (s: :bro:type:`string`, a: :bro:type:`string` :bro:attr:`&default` = ``""`` :bro:attr:`&optional`) : :bro:type:`string`
Decodes a Base64-encoded string.
:s: The Base64-encoded string.
:a: An optional custom alphabet. The empty string indicates the default
alphabet. If given, the string must consist of 64 unique characters.
:returns: The decoded version of *s*.
.. bro:see:: decode_base64_conn encode_base64
.. bro:id:: decode_base64_conn
:Type: :bro:type:`function` (cid: :bro:type:`conn_id`, s: :bro:type:`string`, a: :bro:type:`string` :bro:attr:`&default` = ``""`` :bro:attr:`&optional`) : :bro:type:`string`
Decodes a Base64-encoded string that was derived from processing a connection.
If an error is encountered decoding the string, that will be logged to
``weird.log`` with the associated connection.
:cid: The identifier of the connection that the encoding originates from.
:s: The Base64-encoded string.
:a: An optional custom alphabet. The empty string indicates the default
alphabet. If given, the string must consist of 64 unique characters.
:returns: The decoded version of *s*.
.. bro:see:: decode_base64
.. bro:id:: decode_base64_custom
:Type: :bro:type:`function` (s: :bro:type:`string`, a: :bro:type:`string`) : :bro:type:`string`
:Attributes: :bro:attr:`&deprecated`
Decodes a Base64-encoded string with a custom alphabet.
:s: The Base64-encoded string.
:a: The custom alphabet. The string must consist of 64 unique characters.
The empty string indicates the default alphabet.
:returns: The decoded version of *s*.
.. bro:see:: decode_base64 decode_base64_conn
.. bro:id:: disable_analyzer
:Type: :bro:type:`function` (cid: :bro:type:`conn_id`, aid: :bro:type:`count`, err_if_no_conn: :bro:type:`bool` :bro:attr:`&default` = ``T`` :bro:attr:`&optional`) : :bro:type:`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*.
.. bro:see:: Analyzer::schedule_analyzer Analyzer::name
.. bro:id:: disable_print_hook
:Type: :bro:type:`function` (f: :bro:type:`file`) : :bro:type:`any`
Disables sending :bro:id:`print_hook` events to remote peers for a given
file. In a
distributed setup, communicating Bro instances generate the event
:bro:id:`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 :bro:id:`print_hook` events for.
.. bro:see:: enable_raw_output
.. bro:id:: disconnect
:Type: :bro:type:`function` (p: :bro:type:`event_peer`) : :bro:type:`bool`
:Attributes: :bro:attr:`&deprecated`
Terminate the connection with a peer.
:p: The peer ID returned from :bro:id:`connect`.
:returns: True on success.
.. bro:see:: connect listen
.. bro:id:: do_profiling
:Type: :bro:type:`function` () : :bro:type:`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 :bro:id:`profiling_file`
holds the name of the file.
.. bro:see:: get_conn_stats
get_dns_stats
get_event_stats
get_file_analysis_stats
get_gap_stats
get_matcher_stats
get_net_stats
get_proc_stats
get_reassembler_stats
get_thread_stats
get_timer_stats
.. bro:id:: double_to_count
:Type: :bro:type:`function` (d: :bro:type:`double`) : :bro:type:`count`
Converts a :bro:type:`double` to a :bro:type:`count`.
:d: The :bro:type:`double` to convert.
:returns: The :bro:type:`double` *d* as unsigned integer, or 0 if *d* < 0.0.
.. bro:see:: double_to_time
.. bro:id:: double_to_interval
:Type: :bro:type:`function` (d: :bro:type:`double`) : :bro:type:`interval`
Converts a :bro:type:`double` to an :bro:type:`interval`.
:d: The :bro:type:`double` to convert.
:returns: The :bro:type:`double` *d* as :bro:type:`interval`.
.. bro:see:: interval_to_double
.. bro:id:: double_to_time
:Type: :bro:type:`function` (d: :bro:type:`double`) : :bro:type:`time`
Converts a :bro:type:`double` value to a :bro:type:`time`.
:d: The :bro:type:`double` to convert.
:returns: The :bro:type:`double` value *d* as :bro:type:`time`.
.. bro:see:: time_to_double double_to_count
.. bro:id:: dump_current_packet
:Type: :bro:type:`function` (file_name: :bro:type:`string`) : :bro:type:`bool`
Writes the current packet to a file.
:file_name: The name of the file to write the packet to.
:returns: True on success.
.. bro:see:: dump_packet get_current_packet send_current_packet
.. bro:id:: dump_packet
:Type: :bro:type:`function` (pkt: :bro:type:`pcap_packet`, file_name: :bro:type:`string`) : :bro:type:`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
.. bro:see:: get_current_packet dump_current_packet send_current_packet
.. bro:id:: dump_rule_stats
:Type: :bro:type:`function` (f: :bro:type:`file`) : :bro:type:`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).
.. bro:see:: get_matcher_stats
.. bro:id:: enable_communication
:Type: :bro:type:`function` () : :bro:type:`any`
:Attributes: :bro:attr:`&deprecated`
Enables the communication system. By default, the communication is off until
explicitly enabled, and all other calls to communication-related functions
will be ignored until done so.
.. bro:id:: enable_raw_output
:Type: :bro:type:`function` (f: :bro:type:`file`) : :bro:type:`any`
Prevents escaping of non-ASCII characters when writing to a file.
This function is equivalent to :bro:attr:`&raw_output`.
:f: The file to disable raw output for.
.. bro:see:: disable_print_hook
.. bro:id:: encode_base64
:Type: :bro:type:`function` (s: :bro:type:`string`, a: :bro:type:`string` :bro:attr:`&default` = ``""`` :bro:attr:`&optional`) : :bro:type:`string`
Encodes a Base64-encoded string.
:s: The string to encode.
:a: An optional custom alphabet. The empty string indicates the default
alphabet. If given, the string must consist of 64 unique characters.
:returns: The encoded version of *s*.
.. bro:see:: decode_base64
.. bro:id:: encode_base64_custom
:Type: :bro:type:`function` (s: :bro:type:`string`, a: :bro:type:`string`) : :bro:type:`string`
:Attributes: :bro:attr:`&deprecated`
Encodes a Base64-encoded string with a custom alphabet.
:s: The string to encode.
:a: The custom alphabet. The string must consist of 64 unique
characters. The empty string indicates the default alphabet.
:returns: The encoded version of *s*.
.. bro:see:: encode_base64
.. bro:id:: entropy_test_add
:Type: :bro:type:`function` (handle: :bro:type:`opaque` of entropy, data: :bro:type:`string`) : :bro:type:`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.
.. bro:see:: find_entropy entropy_test_add entropy_test_finish
.. bro:id:: entropy_test_finish
:Type: :bro:type:`function` (handle: :bro:type:`opaque` of entropy) : :bro:type:`entropy_test_result`
Finishes an incremental entropy calculation. Before using this function,
one needs to obtain an opaque handle with :bro:id:`entropy_test_init` and
add data to it via :bro:id:`entropy_test_add`.
:handle: The opaque handle representing the entropy calculation state.
:returns: The result of the entropy test. See :bro:id:`find_entropy` for a
description of the individual components.
.. bro:see:: find_entropy entropy_test_init entropy_test_add
.. bro:id:: entropy_test_init
:Type: :bro:type:`function` () : :bro:type:`opaque` of entropy
Initializes data structures for incremental entropy calculation.
:returns: An opaque handle to be used in subsequent operations.
.. bro:see:: find_entropy entropy_test_add entropy_test_finish
.. bro:id:: enum_to_int
:Type: :bro:type:`function` (e: :bro:type:`any`) : :bro:type:`int`
Converts an :bro:type:`enum` to an :bro:type:`int`.
:e: The :bro:type:`enum` to convert.
:returns: The :bro:type:`int` value that corresponds to the :bro:type:`enum`.
.. bro:id:: exit
:Type: :bro:type:`function` (code: :bro:type:`int`) : :bro:type:`any`
Shuts down the Bro process immediately.
:code: The exit code to return with.
.. bro:see:: terminate
.. bro:id:: exp
:Type: :bro:type:`function` (d: :bro:type:`double`) : :bro:type:`double`
Computes the exponential function.
:d: The argument to the exponential function.
:returns: *e* to the power of *d*.
.. bro:see:: floor sqrt ln log10
.. bro:id:: file_magic
:Type: :bro:type:`function` (data: :bro:type:`string`) : :bro:type:`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.
.. bro:see:: identify_data
.. bro:id:: file_mode
:Type: :bro:type:`function` (mode: :bro:type:`count`) : :bro:type:`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]``.
.. bro:id:: file_size
:Type: :bro:type:`function` (f: :bro:type:`string`) : :bro:type:`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.
.. bro:id:: filter_subnet_table
:Type: :bro:type:`function` (search: :bro:type:`subnet`, t: :bro:type:`any`) : :bro:type:`any`
For a set[subnet]/table[subnet], create a new table that contains all entries
that contain a given subnet.
:search: the subnet to search for.
:t: the set[subnet] or table[subnet].
:returns: A new table that contains all the entries that cover the subnet searched for.
.. bro:id:: find_entropy
:Type: :bro:type:`function` (data: :bro:type:`string`) : :bro:type:`entropy_test_result`
Performs an entropy test on the given data.
See http://www.fourmilab.ch/random.
:data: The data to compute the entropy for.
:returns: The result of the entropy test, which contains the following
fields.
- ``entropy``: The information density expressed as a number of
bits per character.
- ``chi_square``: The chi-square test value expressed as an
absolute number and a percentage which indicates how
frequently a truly random sequence would exceed the value
calculated, i.e., the degree to which the sequence tested is
suspected of being non-random.
If the percentage is greater than 99% or less than 1%, the
sequence is almost certainly not random. If the percentage is
between 99% and 95% or between 1% and 5%, the sequence is
suspect. Percentages between 90\% and 95\% and 5\% and 10\%
indicate the sequence is "almost suspect."
- ``mean``: The arithmetic mean of all the bytes. If the data
are close to random, it should be around 127.5.
- ``monte_carlo_pi``: Each successive sequence of six bytes is
used as 24-bit *x* and *y* coordinates within a square. If
the distance of the randomly-generated point is less than the
radius of a circle inscribed within the square, the six-byte
sequence is considered a "hit." The percentage of hits can
be used to calculate the value of pi. For very large streams
the value will approach the correct value of pi if the
sequence is close to random.
- ``serial_correlation``: This quantity measures the extent to
which each byte in the file depends upon the previous byte.
For random sequences this value will be close to zero.
.. bro:see:: entropy_test_init entropy_test_add entropy_test_finish
.. bro:id:: floor
:Type: :bro:type:`function` (d: :bro:type:`double`) : :bro:type:`double`
Computes the greatest integer less than the given :bro:type:`double` value.
For example, ``floor(3.14)`` returns ``3.0``, and ``floor(-3.14)``
returns ``-4.0``.
:d: The :bro:type:`double` to manipulate.
:returns: The next lowest integer of *d* as :bro:type:`double`.
.. bro:see:: sqrt exp ln log10
.. bro:id:: flush_all
:Type: :bro:type:`function` () : :bro:type:`bool`
Flushes all open files to disk.
:returns: True on success.
.. bro:see:: active_file open open_for_append close
get_file_name write_file set_buf mkdir enable_raw_output
rmdir unlink rename
.. bro:id:: fmt
:Type: :bro:type:`function` (...) : :bro:type:`string`
Produces a formatted string à la ``printf``. The first argument is the
*format string* and specifies how subsequent arguments are converted for
output. It is composed of zero or more directives: ordinary characters (not
``%``), which are copied unchanged to the output, and conversion
specifications, each of which fetches zero or more subsequent arguments.
Conversion specifications begin with ``%`` and the arguments must properly
correspond to the specifier. After the ``%``, the following characters
may appear in sequence:
- ``%``: Literal ``%``
- ``-``: Left-align field
- ``[0-9]+``: The field width (< 128)
- ``.``: Precision of floating point specifiers ``[efg]`` (< 128)
- ``[DTdxsefg]``: Format specifier
- ``[DT]``: ISO timestamp with microsecond precision
- ``d``: Signed/Unsigned integer (using C-style ``%lld``/``%llu``
for ``int``/``count``)
- ``x``: Unsigned hexadecimal (using C-style ``%llx``);
addresses/ports are converted to host-byte order
- ``s``: String (byte values less than 32 or greater than 126
will be escaped)
- ``[efg]``: Double
:returns: Returns the formatted string. Given no arguments, :bro:id:`fmt`
returns an empty string. Given no format string or the wrong
number of additional arguments for the given format specifier,
:bro:id:`fmt` generates a run-time error.
.. bro:see:: cat cat_sep string_cat cat_string_array cat_string_array_n
.. bro:id:: fnv1a32
:Type: :bro:type:`function` (input: :bro:type:`any`) : :bro:type:`count`
Returns 32-bit digest of arbitrary input values using FNV-1a hash algorithm.
See `<https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function>`_.
:input: The desired input value to hash.
:returns: The hashed value.
.. bro:see:: hrw_weight
.. bro:id:: get_conn_transport_proto
:Type: :bro:type:`function` (cid: :bro:type:`conn_id`) : :bro:type:`transport_proto`
Extracts the transport protocol from a connection.
:cid: The connection identifier.
:returns: The transport protocol of the connection identified by *cid*.
.. bro:see:: get_port_transport_proto
get_orig_seq get_resp_seq
.. bro:id:: get_current_packet
:Type: :bro:type:`function` () : :bro:type:`pcap_packet`
Returns the currently processed PCAP packet.
:returns: The currently processed packet, which is a record
containing the timestamp, ``snaplen``, and packet data.
.. bro:see:: dump_current_packet dump_packet send_current_packet
.. bro:id:: get_current_packet_header
:Type: :bro:type:`function` () : :bro:type:`raw_pkt_hdr`
Function to get the raw headers of the currently processed packet.
:returns: The :bro:type:`raw_pkt_hdr` record containing the Layer 2, 3 and
4 headers of the currently processed packet.
.. bro:see:: raw_pkt_hdr get_current_packet
.. bro:id:: get_event_peer
:Type: :bro:type:`function` () : :bro:type:`event_peer`
:Attributes: :bro:attr:`&deprecated`
Returns the peer who generated the last event.
Note, this function is deprecated. It works correctly only for local events and
events received through the legacy communication system. It does *not* work for
events received through Broker and will report an error in that case.
:returns: The ID of the peer who generated the last event.
.. bro:see:: get_local_event_peer
.. bro:id:: get_file_name
:Type: :bro:type:`function` (f: :bro:type:`file`) : :bro:type:`string`
Gets the filename associated with a file handle.
:f: The file handle to inquire the name for.
:returns: The filename associated with *f*.
.. bro:see:: open
.. bro:id:: get_local_event_peer
:Type: :bro:type:`function` () : :bro:type:`event_peer`
:Attributes: :bro:attr:`&deprecated`
Returns the local peer ID.
:returns: The peer ID of the local Bro instance.
.. bro:see:: get_event_peer
.. bro:id:: get_port_transport_proto
:Type: :bro:type:`function` (p: :bro:type:`port`) : :bro:type:`transport_proto`
Extracts the transport protocol from a :bro:type:`port`.
:p: The port.
:returns: The transport protocol of the port *p*.
.. bro:see:: get_conn_transport_proto
get_orig_seq get_resp_seq
.. bro:id:: getenv
:Type: :bro:type:`function` (var: :bro:type:`string`) : :bro:type:`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.
.. bro:see:: setenv
.. bro:id:: gethostname
:Type: :bro:type:`function` () : :bro:type:`string`
Returns the hostname of the machine Bro runs on.
:returns: The hostname of the machine Bro runs on.
.. bro:id:: getpid
:Type: :bro:type:`function` () : :bro:type:`count`
Returns Bro's process ID.
:returns: Bro's process ID.
.. bro:id:: global_ids
:Type: :bro:type:`function` () : :bro:type:`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.
.. bro:see:: global_sizes
.. bro:id:: global_sizes
:Type: :bro:type:`function` () : :bro:type:`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.
.. bro:see:: global_ids
.. bro:id:: haversine_distance
:Type: :bro:type:`function` (lat1: :bro:type:`double`, long1: :bro:type:`double`, lat2: :bro:type:`double`, long2: :bro:type:`double`) : :bro:type:`double`
Calculates distance between two geographic locations using the haversine
formula. Latitudes and longitudes must be given in degrees, where southern
hemispere latitudes are negative and western hemisphere longitudes are
negative.
:lat1: Latitude (in degrees) of location 1.
:long1: Longitude (in degrees) of location 1.
:lat2: Latitude (in degrees) of location 2.
:long2: Longitude (in degrees) of location 2.
:returns: Distance in miles.
.. bro:see:: haversine_distance_ip
.. bro:id:: hexstr_to_bytestring
:Type: :bro:type:`function` (hexstr: :bro:type:`string`) : :bro:type:`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*.
.. bro:see:: hexdump bytestring_to_hexstr
.. bro:id:: hrw_weight
:Type: :bro:type:`function` (key_digest: :bro:type:`count`, site_id: :bro:type:`count`) : :bro:type:`count`
Calculates a weight value for use in a Rendezvous Hashing algorithm.
See `<https://en.wikipedia.org/wiki/Rendezvous_hashing>`_.
The weight function used is the one recommended in the original
:paper: `<http://www.eecs.umich.edu/techreports/cse/96/CSE-TR-316-96.pdf>`_.
:key_digest: A 32-bit digest of a key. E.g. use :bro:see:`fnv1a32` to
produce this.
:site_id: A 32-bit site/node identifier.
:returns: The weight value for the key/site pair.
.. bro:see:: fnv1a32
.. bro:id:: identify_data
:Type: :bro:type:`function` (data: :bro:type:`string`, return_mime: :bro:type:`bool` :bro:attr:`&default` = ``T`` :bro:attr:`&optional`) : :bro:type:`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.
.. bro:see:: file_magic
.. bro:id:: install_dst_addr_filter
:Type: :bro:type:`function` (ip: :bro:type:`addr`, tcp_flags: :bro:type:`count`, prob: :bro:type:`double`) : :bro:type:`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).
.. bro:see:: Pcap::precompile_pcap_filter
Pcap::install_pcap_filter
install_src_addr_filter
install_src_net_filter
uninstall_src_addr_filter
uninstall_src_net_filter
install_dst_net_filter
uninstall_dst_addr_filter
uninstall_dst_net_filter
Pcap::error
.. todo:: The return value should be changed to any.
.. bro:id:: install_dst_net_filter
:Type: :bro:type:`function` (snet: :bro:type:`subnet`, tcp_flags: :bro:type:`count`, prob: :bro:type:`double`) : :bro:type:`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).
.. bro:see:: Pcap::precompile_pcap_filter
Pcap::install_pcap_filter
install_src_addr_filter
install_src_net_filter
uninstall_src_addr_filter
uninstall_src_net_filter
install_dst_addr_filter
uninstall_dst_addr_filter
uninstall_dst_net_filter
Pcap::error
.. todo:: The return value should be changed to any.
.. bro:id:: install_src_addr_filter
:Type: :bro:type:`function` (ip: :bro:type:`addr`, tcp_flags: :bro:type:`count`, prob: :bro:type:`double`) : :bro:type:`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).
.. bro:see:: Pcap::precompile_pcap_filter
Pcap::install_pcap_filter
install_src_net_filter
uninstall_src_addr_filter
uninstall_src_net_filter
install_dst_addr_filter
install_dst_net_filter
uninstall_dst_addr_filter
uninstall_dst_net_filter
Pcap::error
.. todo:: The return value should be changed to any.
.. bro:id:: install_src_net_filter
:Type: :bro:type:`function` (snet: :bro:type:`subnet`, tcp_flags: :bro:type:`count`, prob: :bro:type:`double`) : :bro:type:`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).
.. bro:see:: Pcap::precompile_pcap_filter
Pcap::install_pcap_filter
install_src_addr_filter
uninstall_src_addr_filter
uninstall_src_net_filter
install_dst_addr_filter
install_dst_net_filter
uninstall_dst_addr_filter
uninstall_dst_net_filter
Pcap::error
.. todo:: The return value should be changed to any.
.. bro:id:: int_to_count
:Type: :bro:type:`function` (n: :bro:type:`int`) : :bro:type:`count`
Converts a (positive) :bro:type:`int` to a :bro:type:`count`.
:n: The :bro:type:`int` to convert.
:returns: The :bro:type:`int` *n* as unsigned integer, or 0 if *n* < 0.
.. bro:id:: interval_to_double
:Type: :bro:type:`function` (i: :bro:type:`interval`) : :bro:type:`double`
Converts an :bro:type:`interval` to a :bro:type:`double`.
:i: The :bro:type:`interval` to convert.
:returns: The :bro:type:`interval` *i* as :bro:type:`double`.
.. bro:see:: double_to_interval
.. bro:id:: is_external_connection
:Type: :bro:type:`function` (c: :bro:type:`connection`) : :bro:type:`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.
.. bro:id:: is_icmp_port
:Type: :bro:type:`function` (p: :bro:type:`port`) : :bro:type:`bool`
Checks whether a given :bro:type:`port` has ICMP as transport protocol.
:p: The :bro:type:`port` to check.
:returns: True iff *p* is an ICMP port.
.. bro:see:: is_tcp_port is_udp_port
.. bro:id:: is_local_interface
:Type: :bro:type:`function` (ip: :bro:type:`addr`) : :bro:type:`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.
.. bro:id:: is_remote_event
:Type: :bro:type:`function` () : :bro:type:`bool`
Checks whether the last raised event came from a remote peer.
:returns: True if the last raised event came from a remote peer.
.. bro:id:: is_tcp_port
:Type: :bro:type:`function` (p: :bro:type:`port`) : :bro:type:`bool`
Checks whether a given :bro:type:`port` has TCP as transport protocol.
:p: The :bro:type:`port` to check.
:returns: True iff *p* is a TCP port.
.. bro:see:: is_udp_port is_icmp_port
.. bro:id:: is_udp_port
:Type: :bro:type:`function` (p: :bro:type:`port`) : :bro:type:`bool`
Checks whether a given :bro:type:`port` has UDP as transport protocol.
:p: The :bro:type:`port` to check.
:returns: True iff *p* is a UDP port.
.. bro:see:: is_icmp_port is_tcp_port
.. bro:id:: is_v4_addr
:Type: :bro:type:`function` (a: :bro:type:`addr`) : :bro:type:`bool`
Returns whether an address is IPv4 or not.
:a: the address to check.
:returns: true if *a* is an IPv4 address, else false.
.. bro:id:: is_v4_subnet
:Type: :bro:type:`function` (s: :bro:type:`subnet`) : :bro:type:`bool`
Returns whether a subnet specification is IPv4 or not.
:s: the subnet to check.
:returns: true if *s* is an IPv4 subnet, else false.
.. bro:id:: is_v6_addr
:Type: :bro:type:`function` (a: :bro:type:`addr`) : :bro:type:`bool`
Returns whether an address is IPv6 or not.
:a: the address to check.
:returns: true if *a* is an IPv6 address, else false.
.. bro:id:: is_v6_subnet
:Type: :bro:type:`function` (s: :bro:type:`subnet`) : :bro:type:`bool`
Returns whether a subnet specification is IPv6 or not.
:s: the subnet to check.
:returns: true if *s* is an IPv6 subnet, else false.
.. bro:id:: listen
:Type: :bro:type:`function` (ip: :bro:type:`addr`, p: :bro:type:`port`, ssl: :bro:type:`bool`, ipv6: :bro:type:`bool`, zone_id: :bro:type:`string`, retry_interval: :bro:type:`interval`) : :bro:type:`bool`
:Attributes: :bro:attr:`&deprecated`
Listens on a given IP address and port for remote connections.
:ip: The IP address to bind to.
:p: The TCP port to listen on.
:ssl: If true, Bro uses SSL to encrypt the session.
:ipv6: If true, enable listening on IPv6 addresses.
:zone_id: If *ip* is a non-global IPv6 address, a particular :rfc:`4007`
``zone_id`` can given here. An empty string, ``""``, means
not to add any ``zone_id``.
:retry_interval: If address *ip* is found to be already in use, this is
the interval at which to automatically retry binding.
:returns: True on success.
.. bro:see:: connect disconnect
.. bro:id:: ln
:Type: :bro:type:`function` (d: :bro:type:`double`) : :bro:type:`double`
Computes the natural logarithm of a number.
:d: The argument to the logarithm.
:returns: The natural logarithm of *d*.
.. bro:see:: exp floor sqrt log10
.. bro:id:: log10
:Type: :bro:type:`function` (d: :bro:type:`double`) : :bro:type:`double`
Computes the common logarithm of a number.
:d: The argument to the logarithm.
:returns: The common logarithm of *d*.
.. bro:see:: exp floor sqrt ln
.. bro:id:: lookup_ID
:Type: :bro:type:`function` (id: :bro:type:`string`) : :bro:type:`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.
.. bro:id:: lookup_addr
:Type: :bro:type:`function` (host: :bro:type:`addr`) : :bro:type:`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*.
.. bro:see:: lookup_hostname
.. bro:id:: lookup_asn
:Type: :bro:type:`function` (a: :bro:type:`addr`) : :bro:type:`count`
Performs an ASN lookup of an IP address.
Requires Bro to be built with ``libmaxminddb``.
:a: The IP address to lookup.
:returns: The number of the ASN that contains *a*.
.. bro:see:: lookup_location
.. bro:id:: lookup_connection
:Type: :bro:type:`function` (cid: :bro:type:`conn_id`) : :bro:type:`connection`
Returns the :bro:type:`connection` record for a given connection identifier.
:cid: The connection ID.
:returns: The :bro:type:`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.
.. bro:see:: connection_exists
.. bro:id:: lookup_hostname
:Type: :bro:type:`function` (host: :bro:type:`string`) : :bro:type:`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*.
.. bro:see:: lookup_addr
.. bro:id:: lookup_hostname_txt
:Type: :bro:type:`function` (host: :bro:type:`string`) : :bro:type:`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*.
.. bro:see:: lookup_hostname
.. bro:id:: lookup_location
:Type: :bro:type:`function` (a: :bro:type:`addr`) : :bro:type:`geo_location`
Performs a geo-lookup of an IP address.
Requires Bro to be built with ``libmaxminddb``.
:a: The IP address to lookup.
:returns: A record with country, region, city, latitude, and longitude.
.. bro:see:: lookup_asn
.. bro:id:: mask_addr
:Type: :bro:type:`function` (a: :bro:type:`addr`, top_bits_to_keep: :bro:type:`count`) : :bro:type:`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.
.. bro:see:: remask_addr
.. bro:id:: match_signatures
:Type: :bro:type:`function` (c: :bro:type:`connection`, pattern_type: :bro:type:`int`, s: :bro:type:`string`, bol: :bro:type:`bool`, eol: :bro:type:`bool`, from_orig: :bro:type:`bool`, clear: :bro:type:`bool`) : :bro:type:`bool`
Manually triggers the signature engine for a given connection.
This is an internal function.
.. bro:id:: matching_subnets
:Type: :bro:type:`function` (search: :bro:type:`subnet`, t: :bro:type:`any`) : :bro:type:`subnet_vec`
Gets all subnets that contain a given subnet from a set/table[subnet].
:search: the subnet to search for.
:t: the set[subnet] or table[subnet].
:returns: All the keys of the set or table that cover the subnet searched for.
.. bro:id:: md5_hash
:Type: :bro:type:`function` (...) : :bro:type:`string`
Computes the MD5 hash value of the provided list of arguments.
:returns: The MD5 hash value of the concatenated arguments.
.. bro:see:: 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 :bro:id:`md5_hash_init` and
friends.
.. bro:id:: md5_hash_finish
:Type: :bro:type:`function` (handle: :bro:type:`opaque` of md5) : :bro:type:`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*.
.. bro:see:: 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
.. bro:id:: md5_hash_init
:Type: :bro:type:`function` () : :bro:type:`opaque` of md5
Constructs an MD5 handle to enable incremental hash computation. You can
feed data to the returned opaque value with :bro:id:`md5_hash_update` and
eventually need to call :bro:id:`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
:bro:id:`http_entity_data` event handler. When all data has arrived, a call
to :bro:id:`md5_hash_finish` returns the final hash value.
:returns: The opaque handle associated with this hash computation.
.. bro:see:: 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
.. bro:id:: md5_hash_update
:Type: :bro:type:`function` (handle: :bro:type:`opaque` of md5, data: :bro:type:`string`) : :bro:type:`bool`
Updates the MD5 value associated with a given index. It is required to
call :bro:id:`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.
.. bro:see:: 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
.. bro:id:: md5_hmac
:Type: :bro:type:`function` (...) : :bro:type:`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.
.. bro:see:: 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
.. bro:id:: merge_pattern
:Type: :bro:type:`function` (p1: :bro:type:`pattern`, p2: :bro:type:`pattern`) : :bro:type:`pattern`
:Attributes: :bro:attr:`&deprecated`
Merges and compiles two regular expressions at initialization time.
:p1: The first pattern.
:p2: The second pattern.
:returns: The compiled pattern of the concatenation of *p1* and *p2*.
.. bro:see:: convert_for_pattern string_to_pattern
.. note::
This function must be called at Bro startup time, e.g., in the event
:bro:id:`bro_init`.
.. bro:id:: mkdir
:Type: :bro:type:`function` (f: :bro:type:`string`) : :bro:type:`bool`
Creates a new directory.
:f: The directory name.
:returns: True if the operation succeeds or if *f* already exists,
and false if the file creation fails.
.. bro:see:: active_file open_for_append close write_file
get_file_name set_buf flush_all enable_raw_output
rmdir unlink rename
.. bro:id:: mmdb_open_asn_db
:Type: :bro:type:`function` (f: :bro:type:`string`) : :bro:type:`bool`
Initializes MMDB for later use of lookup_asn.
Requires Bro to be built with ``libmaxminddb``.
:f: The filename of the MaxMind ASN DB.
:returns: A boolean indicating whether the db was successfully opened.
.. bro:see:: lookup_asn
.. bro:id:: mmdb_open_location_db
:Type: :bro:type:`function` (f: :bro:type:`string`) : :bro:type:`bool`
Initializes MMDB for later use of lookup_location.
Requires Bro to be built with ``libmaxminddb``.
:f: The filename of the MaxMind City or Country DB.
:returns: A boolean indicating whether the db was successfully opened.
.. bro:see:: lookup_asn
.. bro:id:: network_time
:Type: :bro:type:`function` () : :bro:type:`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.
.. bro:see:: current_time
.. bro:id:: open
:Type: :bro:type:`function` (f: :bro:type:`string`) : :bro:type:`file`
Opens a file for writing. If a file with the same name already exists, this
function overwrites it (as opposed to :bro:id:`open_for_append`).
:f: The path to the file.
:returns: A :bro:type:`file` handle for subsequent operations.
.. bro:see:: active_file open_for_append close write_file
get_file_name set_buf flush_all mkdir enable_raw_output
rmdir unlink rename
.. bro:id:: open_for_append
:Type: :bro:type:`function` (f: :bro:type:`string`) : :bro:type:`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 :bro:id:`open`).
:f: The path to the file.
:returns: A :bro:type:`file` handle for subsequent operations.
.. bro:see:: active_file open close write_file
get_file_name set_buf flush_all mkdir enable_raw_output
rmdir unlink rename
.. bro:id:: order
:Type: :bro:type:`function` (...) : :bro:type:`index_vec`
Returns the order of the elements in a vector according to some
comparison function. See :bro:id:`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.
.. bro:see:: sort
.. bro:id:: piped_exec
:Type: :bro:type:`function` (program: :bro:type:`string`, to_write: :bro:type:`string`) : :bro:type:`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.
.. bro:see:: system system_env
.. bro:id:: port_to_count
:Type: :bro:type:`function` (p: :bro:type:`port`) : :bro:type:`count`
Converts a :bro:type:`port` to a :bro:type:`count`.
:p: The :bro:type:`port` to convert.
:returns: The :bro:type:`port` *p* as :bro:type:`count`.
.. bro:see:: count_to_port
.. bro:id:: preserve_prefix
:Type: :bro:type:`function` (a: :bro:type:`addr`, width: :bro:type:`count`) : :bro:type:`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.
.. bro:see:: preserve_subnet anonymize_addr
.. todo:: Currently dysfunctional.
.. bro:id:: preserve_subnet
:Type: :bro:type:`function` (a: :bro:type:`subnet`) : :bro:type:`any`
Preserves the prefix of a subnet in anonymization.
:a: The subnet to preserve.
.. bro:see:: preserve_prefix anonymize_addr
.. todo:: Currently dysfunctional.
.. bro:id:: ptr_name_to_addr
:Type: :bro:type:`function` (s: :bro:type:`string`) : :bro:type:`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*.
.. bro:see:: addr_to_ptr_name to_addr
.. bro:id:: rand
:Type: :bro:type:`function` (max: :bro:type:`count`) : :bro:type:`count`
Generates a random number.
:max: The maximum value of the random number.
:returns: a random positive integer in the interval *[0, max)*.
.. bro:see:: srand
.. note::
This function is a wrapper about the function ``random``
provided by the OS.
.. bro:id:: raw_bytes_to_v4_addr
:Type: :bro:type:`function` (b: :bro:type:`string`) : :bro:type:`addr`
Converts a :bro:type:`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 (:bro:type:`string`) to convert.
:returns: The byte :bro:type:`string` *b* as :bro:type:`addr`.
.. bro:see:: raw_bytes_to_v4_addr to_addr to_subnet
.. bro:id:: reading_live_traffic
:Type: :bro:type:`function` () : :bro:type:`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.
.. bro:see:: reading_traces
.. bro:id:: reading_traces
:Type: :bro:type:`function` () : :bro:type:`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.
.. bro:see:: reading_live_traffic
.. bro:id:: record_fields
:Type: :bro:type:`function` (rec: :bro:type:`any`) : :bro:type:`record_field_table`
Generates metadata about a record's fields. The returned information
includes the field name, whether it is logged, its value (if it has one),
and its default value (if specified).
:rec: The record value or type to inspect.
:returns: A table that describes the fields of a record.
.. bro:id:: record_type_to_vector
:Type: :bro:type:`function` (rt: :bro:type:`string`) : :bro:type:`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*.
.. bro:id:: remask_addr
:Type: :bro:type:`function` (a1: :bro:type:`addr`, a2: :bro:type:`addr`, top_bits_from_a1: :bro:type:`count`) : :bro:type:`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.
.. bro:see:: mask_addr
.. bro:id:: rename
:Type: :bro:type:`function` (src_f: :bro:type:`string`, dst_f: :bro:type:`string`) : :bro:type:`bool`
Renames a file from src_f to dst_f.
:src_f: the name of the file to rename.
:dest_f: the name of the file after the rename operation.
:returns: True if the rename succeeds and false otherwise.
.. bro:see:: active_file open_for_append close write_file
get_file_name set_buf flush_all enable_raw_output
mkdir rmdir unlink
.. bro:id:: request_remote_events
:Type: :bro:type:`function` (p: :bro:type:`event_peer`, handlers: :bro:type:`pattern`) : :bro:type:`bool`
:Attributes: :bro:attr:`&deprecated`
Subscribes to all events from a remote peer whose names match a given
pattern.
:p: The peer ID returned from :bro:id:`connect`.
:handlers: The pattern describing the events to request from peer *p*.
:returns: True on success.
.. bro:see:: request_remote_sync
request_remote_logs
set_accept_state
.. bro:id:: request_remote_logs
:Type: :bro:type:`function` (p: :bro:type:`event_peer`) : :bro:type:`bool`
:Attributes: :bro:attr:`&deprecated`
Requests logs from a remote peer.
:p: The peer ID returned from :bro:id:`connect`.
:returns: True on success.
.. bro:see:: request_remote_events
request_remote_sync
.. bro:id:: request_remote_sync
:Type: :bro:type:`function` (p: :bro:type:`event_peer`, auth: :bro:type:`bool`) : :bro:type:`bool`
:Attributes: :bro:attr:`&deprecated`
Requests synchronization of IDs with a remote peer.
:p: The peer ID returned from :bro:id:`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.
.. bro:see:: request_remote_events
request_remote_logs
set_accept_state
.. bro:id:: rescan_state
:Type: :bro:type:`function` () : :bro:type:`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 :bro:id:`checkpoint_state`.
:returns: True on success.
.. bro:see:: checkpoint_state
.. bro:id:: resize
:Type: :bro:type:`function` (aggr: :bro:type:`any`, newsize: :bro:type:`count`) : :bro:type:`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 :bro:type:`vector`.
.. bro:id:: resume_state_updates
:Type: :bro:type:`function` () : :bro:type:`any`
:Attributes: :bro:attr:`&deprecated`
Resumes propagating :bro:attr:`&synchronized` accesses.
.. bro:see:: suspend_processing continue_processing suspend_state_updates
.. bro:id:: rmdir
:Type: :bro:type:`function` (d: :bro:type:`string`) : :bro:type:`bool`
Removes a directory.
:d: The directory name.
:returns: True if the operation succeeds, and false if the
directory delete operation fails.
.. bro:see:: active_file open_for_append close write_file
get_file_name set_buf flush_all enable_raw_output
mkdir unlink rename
.. bro:id:: rotate_file
:Type: :bro:type:`function` (f: :bro:type:`file`) : :bro:type:`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.
.. bro:see:: rotate_file_by_name calc_next_rotate
.. bro:id:: rotate_file_by_name
:Type: :bro:type:`function` (f: :bro:type:`string`) : :bro:type:`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.
.. bro:see:: rotate_file calc_next_rotate
.. bro:id:: routing0_data_to_addrs
:Type: :bro:type:`function` (s: :bro:type:`string`) : :bro:type:`addr_vec`
Converts the *data* field of :bro:type:`ip6_routing` records that have
*rtype* of 0 into a vector of addresses.
:s: The *data* field of an :bro:type:`ip6_routing` record that has
an *rtype* of 0.
:returns: The vector of addresses contained in the routing header data.
.. bro:id:: same_object
:Type: :bro:type:`function` (o1: :bro:type:`any`, o2: :bro:type:`any`) : :bro:type:`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.
.. bro:id:: send_capture_filter
:Type: :bro:type:`function` (p: :bro:type:`event_peer`, s: :bro:type:`string`) : :bro:type:`bool`
:Attributes: :bro:attr:`&deprecated`
Sends a capture filter to a remote peer.
:p: The peer ID returned from :bro:id:`connect`.
:s: The capture filter.
:returns: True if sending the packet succeeds.
.. bro:see:: send_id send_state send_ping send_current_packet
.. bro:id:: send_current_packet
:Type: :bro:type:`function` (p: :bro:type:`event_peer`) : :bro:type:`bool`
:Attributes: :bro:attr:`&deprecated`
Sends the currently processed packet to a remote peer.
:p: The peer ID returned from :bro:id:`connect`.
:returns: True if sending the packet succeeds.
.. bro:see:: send_id send_state send_ping send_capture_filter
dump_packet dump_current_packet get_current_packet
.. bro:id:: send_id
:Type: :bro:type:`function` (p: :bro:type:`event_peer`, id: :bro:type:`string`) : :bro:type:`bool`
:Attributes: :bro:attr:`&deprecated`
Sends a global identifier to a remote peer, which then might install it
locally.
:p: The peer ID returned from :bro:id:`connect`.
:id: The identifier to send.
:returns: True on success.
.. bro:see:: send_state send_ping send_current_packet send_capture_filter
.. bro:id:: send_ping
:Type: :bro:type:`function` (p: :bro:type:`event_peer`, seq: :bro:type:`count`) : :bro:type:`bool`
:Attributes: :bro:attr:`&deprecated`
Sends a ping event to a remote peer. In combination with an event handler
for :bro:id:`remote_pong`, this function can be used to measure latency
between two peers.
:p: The peer ID returned from :bro:id:`connect`.
:seq: A sequence number (also included by :bro:id:`remote_pong`).
:returns: True if sending the ping succeeds.
.. bro:see:: send_state send_id send_current_packet send_capture_filter
.. bro:id:: send_state
:Type: :bro:type:`function` (p: :bro:type:`event_peer`) : :bro:type:`bool`
Sends all persistent state to a remote peer.
:p: The peer ID returned from :bro:id:`connect`.
:returns: True on success.
.. bro:see:: send_id send_ping send_current_packet send_capture_filter
.. bro:id:: set_accept_state
:Type: :bro:type:`function` (p: :bro:type:`event_peer`, accept: :bro:type:`bool`) : :bro:type:`bool`
:Attributes: :bro:attr:`&deprecated`
Sets a boolean flag indicating whether Bro accepts state from a remote peer.
:p: The peer ID returned from :bro:id:`connect`.
:accept: True if Bro accepts state from peer *p*, or false otherwise.
:returns: True on success.
.. bro:see:: request_remote_events
request_remote_sync
set_compression_level
.. bro:id:: set_buf
:Type: :bro:type:`function` (f: :bro:type:`file`, buffered: :bro:type:`bool`) : :bro:type:`any`
Alters the buffering behavior of a file.
:f: A :bro:type:`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.
.. bro:see:: active_file open open_for_append close
get_file_name write_file flush_all mkdir enable_raw_output
rmdir unlink rename
.. bro:id:: set_compression_level
:Type: :bro:type:`function` (p: :bro:type:`event_peer`, level: :bro:type:`count`) : :bro:type:`bool`
:Attributes: :bro:attr:`&deprecated`
Sets the compression level of the session with a remote peer.
:p: The peer ID returned from :bro:id:`connect`.
:level: Allowed values are in the range *[0, 9]*, where 0 is the default and
means no compression.
:returns: True on success.
.. bro:see:: set_accept_state
.. bro:id:: set_inactivity_timeout
:Type: :bro:type:`function` (cid: :bro:type:`conn_id`, t: :bro:type:`interval`) : :bro:type:`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.
.. bro:id:: set_record_packets
:Type: :bro:type:`function` (cid: :bro:type:`conn_id`, do_record: :bro:type:`bool`) : :bro:type:`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.
.. bro:see:: skip_further_processing
.. note::
This is independent of whether Bro processes the packets of this
connection, which is controlled separately by
:bro:id:`skip_further_processing`.
.. bro:see:: get_contents_file set_contents_file
.. bro:id:: setenv
:Type: :bro:type:`function` (var: :bro:type:`string`, val: :bro:type:`string`) : :bro:type:`bool`
Sets a system environment variable.
:var: The name of the variable.
:val: The (new) value of the variable *var*.
:returns: True on success.
.. bro:see:: getenv
.. bro:id:: sha1_hash
:Type: :bro:type:`function` (...) : :bro:type:`string`
Computes the SHA1 hash value of the provided list of arguments.
:returns: The SHA1 hash value of the concatenated arguments.
.. bro:see:: 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 :bro:id:`sha1_hash_init` and
friends.
.. bro:id:: sha1_hash_finish
:Type: :bro:type:`function` (handle: :bro:type:`opaque` of sha1) : :bro:type:`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*.
.. bro:see:: 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
.. bro:id:: sha1_hash_init
:Type: :bro:type:`function` () : :bro:type:`opaque` of sha1
Constructs an SHA1 handle to enable incremental hash computation. You can
feed data to the returned opaque value with :bro:id:`sha1_hash_update` and
finally need to call :bro:id:`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
:bro:id:`http_entity_data` event handler. When all data has arrived, a call
to :bro:id:`sha1_hash_finish` returns the final hash value.
:returns: The opaque handle associated with this hash computation.
.. bro:see:: 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
.. bro:id:: sha1_hash_update
:Type: :bro:type:`function` (handle: :bro:type:`opaque` of sha1, data: :bro:type:`string`) : :bro:type:`bool`
Updates the SHA1 value associated with a given index. It is required to
call :bro:id:`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.
.. bro:see:: 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
.. bro:id:: sha256_hash
:Type: :bro:type:`function` (...) : :bro:type:`string`
Computes the SHA256 hash value of the provided list of arguments.
:returns: The SHA256 hash value of the concatenated arguments.
.. bro:see:: 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 :bro:id:`sha256_hash_init` and
friends.
.. bro:id:: sha256_hash_finish
:Type: :bro:type:`function` (handle: :bro:type:`opaque` of sha256) : :bro:type:`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*.
.. bro:see:: 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
.. bro:id:: sha256_hash_init
:Type: :bro:type:`function` () : :bro:type:`opaque` of sha256
Constructs an SHA256 handle to enable incremental hash computation. You can
feed data to the returned opaque value with :bro:id:`sha256_hash_update` and
finally need to call :bro:id:`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
:bro:id:`http_entity_data` event handler. When all data has arrived, a call
to :bro:id:`sha256_hash_finish` returns the final hash value.
:returns: The opaque handle associated with this hash computation.
.. bro:see:: 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
.. bro:id:: sha256_hash_update
:Type: :bro:type:`function` (handle: :bro:type:`opaque` of sha256, data: :bro:type:`string`) : :bro:type:`bool`
Updates the SHA256 value associated with a given index. It is required to
call :bro:id:`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.
.. bro:see:: 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
.. bro:id:: skip_further_processing
:Type: :bro:type:`function` (cid: :bro:type:`conn_id`) : :bro:type:`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
:bro:id:`connection_finished`.
.. bro:id:: sort
:Type: :bro:type:`function` (...) : :bro:type:`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.
.. bro:see:: order
.. bro:id:: sqrt
:Type: :bro:type:`function` (x: :bro:type:`double`) : :bro:type:`double`
Computes the square root of a :bro:type:`double`.
:x: The number to compute the square root of.
:returns: The square root of *x*.
.. bro:see:: floor exp ln log10
.. bro:id:: srand
:Type: :bro:type:`function` (seed: :bro:type:`count`) : :bro:type:`any`
Sets the seed for subsequent :bro:id:`rand` calls.
:seed: The seed for the PRNG.
.. bro:see:: rand
.. note::
This function is a wrapper about the function ``srandom``
provided by the OS.
.. bro:id:: strftime
:Type: :bro:type:`function` (fmt: :bro:type:`string`, d: :bro:type:`time`) : :bro:type:`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*.
.. bro:id:: string_to_pattern
:Type: :bro:type:`function` (s: :bro:type:`string`, convert: :bro:type:`bool`) : :bro:type:`pattern`
Converts a :bro:type:`string` into a :bro:type:`pattern`.
:s: The string to convert.
:convert: If true, *s* is first passed through the function
:bro:id:`convert_for_pattern` to escape special characters of
patterns.
:returns: *s* as :bro:type:`pattern`.
.. bro:see:: convert_for_pattern merge_pattern
.. note::
This function must be called at Bro startup time, e.g., in the event
:bro:id:`bro_init`.
.. bro:id:: strptime
:Type: :bro:type:`function` (fmt: :bro:type:`string`, d: :bro:type:`string`) : :bro:type:`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*.
.. bro:id:: subnet_to_addr
:Type: :bro:type:`function` (sn: :bro:type:`subnet`) : :bro:type:`addr`
Converts a :bro:type:`subnet` to an :bro:type:`addr` by
extracting the prefix.
:sn: The subnet to convert.
:returns: The subnet as an :bro:type:`addr`.
.. bro:see:: to_subnet
.. bro:id:: subnet_width
:Type: :bro:type:`function` (sn: :bro:type:`subnet`) : :bro:type:`count`
Returns the width of a :bro:type:`subnet`.
:sn: The subnet.
:returns: The width of the subnet.
.. bro:see:: to_subnet
.. bro:id:: suspend_processing
:Type: :bro:type:`function` () : :bro:type:`any`
Stops Bro's packet processing. This function is used to synchronize
distributed trace processing with communication enabled
(*pseudo-realtime* mode).
.. bro:see:: continue_processing suspend_state_updates resume_state_updates
.. bro:id:: suspend_state_updates
:Type: :bro:type:`function` () : :bro:type:`any`
:Attributes: :bro:attr:`&deprecated`
Stops propagating :bro:attr:`&synchronized` accesses.
.. bro:see:: suspend_processing continue_processing resume_state_updates
.. bro:id:: syslog
:Type: :bro:type:`function` (s: :bro:type:`string`) : :bro:type:`any`
Send a string to syslog.
:s: The string to log via syslog
.. bro:id:: system
:Type: :bro:type:`function` (str: :bro:type:`string`) : :bro:type:`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.
.. bro:see:: 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.
.. bro:id:: system_env
:Type: :bro:type:`function` (str: :bro:type:`string`, env: :bro:type:`table_string_of_string`) : :bro:type:`int`
Invokes a command via the ``system`` function of the OS with a prepared
environment. The function is essentially the same as :bro:id:`system`,
but changes the environment before invoking the command.
:str: The command to execute.
:env: A :bro:type:`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.
.. bro:see:: system str_shell_escape piped_exec
.. bro:id:: terminate
:Type: :bro:type:`function` () : :bro:type:`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.
.. bro:see:: exit bro_is_terminating
.. bro:id:: terminate_communication
:Type: :bro:type:`function` () : :bro:type:`bool`
:Attributes: :bro:attr:`&deprecated`
Gracefully finishes communication by first making sure that all remaining
data from parent and child has been sent out.
:returns: True if the termination process has been started successfully.
.. bro:id:: time_to_double
:Type: :bro:type:`function` (t: :bro:type:`time`) : :bro:type:`double`
Converts a :bro:type:`time` value to a :bro:type:`double`.
:t: The :bro:type:`time` to convert.
:returns: The :bro:type:`time` value *t* as :bro:type:`double`.
.. bro:see:: double_to_time
.. bro:id:: to_addr
:Type: :bro:type:`function` (ip: :bro:type:`string`) : :bro:type:`addr`
Converts a :bro:type:`string` to an :bro:type:`addr`.
:ip: The :bro:type:`string` to convert.
:returns: The :bro:type:`string` *ip* as :bro:type:`addr`, or the unspecified
address ``::`` if the input string does not parse correctly.
.. bro:see:: to_count to_int to_port count_to_v4_addr raw_bytes_to_v4_addr
to_subnet
.. bro:id:: to_count
:Type: :bro:type:`function` (str: :bro:type:`string`) : :bro:type:`count`
Converts a :bro:type:`string` to a :bro:type:`count`.
:str: The :bro:type:`string` to convert.
:returns: The :bro:type:`string` *str* as unsigned integer, or 0 if *str* has
an invalid format.
.. bro:see:: to_addr to_int to_port to_subnet
.. bro:id:: to_double
:Type: :bro:type:`function` (str: :bro:type:`string`) : :bro:type:`double`
Converts a :bro:type:`string` to a :bro:type:`double`.
:str: The :bro:type:`string` to convert.
:returns: The :bro:type:`string` *str* as double, or 0 if *str* has
an invalid format.
.. bro:id:: to_int
:Type: :bro:type:`function` (str: :bro:type:`string`) : :bro:type:`int`
Converts a :bro:type:`string` to an :bro:type:`int`.
:str: The :bro:type:`string` to convert.
:returns: The :bro:type:`string` *str* as :bro:type:`int`.
.. bro:see:: to_addr to_port to_subnet
.. bro:id:: to_port
:Type: :bro:type:`function` (s: :bro:type:`string`) : :bro:type:`port`
Converts a :bro:type:`string` to a :bro:type:`port`.
:s: The :bro:type:`string` to convert.
:returns: A :bro:type:`port` converted from *s*.
.. bro:see:: to_addr to_count to_int to_subnet
.. bro:id:: to_subnet
:Type: :bro:type:`function` (sn: :bro:type:`string`) : :bro:type:`subnet`
Converts a :bro:type:`string` to a :bro:type:`subnet`.
:sn: The subnet to convert.
:returns: The *sn* string as a :bro:type:`subnet`, or the unspecified subnet
``::/0`` if the input string does not parse correctly.
.. bro:see:: to_count to_int to_port count_to_v4_addr raw_bytes_to_v4_addr
to_addr
.. bro:id:: type_name
:Type: :bro:type:`function` (t: :bro:type:`any`) : :bro:type:`string`
Returns the type name of an arbitrary Bro variable.
:t: An arbitrary object.
:returns: The type name of *t*.
.. bro:id:: uninstall_dst_addr_filter
:Type: :bro:type:`function` (ip: :bro:type:`addr`) : :bro:type:`bool`
Removes a destination address filter.
:ip: The IP address for which a destination filter was previously installed.
:returns: True on success.
.. bro:see:: Pcap::precompile_pcap_filter
Pcap::install_pcap_filter
install_src_addr_filter
install_src_net_filter
uninstall_src_addr_filter
uninstall_src_net_filter
install_dst_addr_filter
install_dst_net_filter
uninstall_dst_net_filter
Pcap::error
.. bro:id:: uninstall_dst_net_filter
:Type: :bro:type:`function` (snet: :bro:type:`subnet`) : :bro:type:`bool`
Removes a destination subnet filter.
:snet: The subnet for which a destination filter was previously installed.
:returns: True on success.
.. bro:see:: Pcap::precompile_pcap_filter
Pcap::install_pcap_filter
install_src_addr_filter
install_src_net_filter
uninstall_src_addr_filter
uninstall_src_net_filter
install_dst_addr_filter
install_dst_net_filter
uninstall_dst_addr_filter
Pcap::error
.. bro:id:: uninstall_src_addr_filter
:Type: :bro:type:`function` (ip: :bro:type:`addr`) : :bro:type:`bool`
Removes a source address filter.
:ip: The IP address for which a source filter was previously installed.
:returns: True on success.
.. bro:see:: Pcap::precompile_pcap_filter
Pcap::install_pcap_filter
install_src_addr_filter
install_src_net_filter
uninstall_src_net_filter
install_dst_addr_filter
install_dst_net_filter
uninstall_dst_addr_filter
uninstall_dst_net_filter
Pcap::error
.. bro:id:: uninstall_src_net_filter
:Type: :bro:type:`function` (snet: :bro:type:`subnet`) : :bro:type:`bool`
Removes a source subnet filter.
:snet: The subnet for which a source filter was previously installed.
:returns: True on success.
.. bro:see:: Pcap::precompile_pcap_filter
Pcap::install_pcap_filter
install_src_addr_filter
install_src_net_filter
uninstall_src_addr_filter
install_dst_addr_filter
install_dst_net_filter
uninstall_dst_addr_filter
uninstall_dst_net_filter
Pcap::error
.. bro:id:: unique_id
:Type: :bro:type:`function` (prefix: :bro:type:`string`) : :bro:type:`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.
.. bro:see:: unique_id_from
.. bro:id:: unique_id_from
:Type: :bro:type:`function` (pool: :bro:type:`int`, prefix: :bro:type:`string`) : :bro:type:`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.
.. bro:see:: unique_id
.. bro:id:: unlink
:Type: :bro:type:`function` (f: :bro:type:`string`) : :bro:type:`bool`
Removes a file from a directory.
:f: the file to delete.
:returns: True if the operation succeeds and the file was deleted,
and false if the deletion fails.
.. bro:see:: active_file open_for_append close write_file
get_file_name set_buf flush_all enable_raw_output
mkdir rmdir rename
.. bro:id:: uuid_to_string
:Type: :bro:type:`function` (uuid: :bro:type:`string`) : :bro:type:`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*.
.. bro:id:: val_size
:Type: :bro:type:`function` (v: :bro:type:`any`) : :bro:type:`count`
Returns the number of bytes that a value occupies in memory.
:v: The value
:returns: The number of bytes that *v* occupies.
.. bro:id:: write_file
:Type: :bro:type:`function` (f: :bro:type:`file`, data: :bro:type:`string`) : :bro:type:`bool`
Writes data to an open file.
:f: A :bro:type:`file` handle to an open file.
:data: The data to write to *f*.
:returns: True on success.
.. bro:see:: active_file open open_for_append close
get_file_name set_buf flush_all mkdir enable_raw_output
rmdir unlink rename
Reference in a new issue View git blame Copy permalink