base/bif/zeek.bif.zeek

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 Zeek’s built-in functions that aren’t protocol-specific in this file.

Namespace:GLOBAL

Summary

Functions

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

Detailed Interface

Functions

active_file
Type:function (f: file) : bool

Checks whether a given file is open.

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

Todo

Rename to is_open.

addr_to_counts
Type:function (a: addr) : index_vec

Converts an addr to an index_vec.

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

See also: counts_to_addr

addr_to_ptr_name
Type:function (a: addr) : string

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

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

See also: ptr_name_to_addr, to_addr

addr_to_subnet
Type:function (a: addr) : subnet

Converts a addr to a subnet.

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

See also: to_subnet

all_set
Type:function (v: any) : bool

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

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

See also: any_set

Note

Missing elements count as false.

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

Anonymizes an IP address.

A:

The address to anonymize.

Cl:

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

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

An anonymized version of a.

See also: preserve_prefix, preserve_subnet

Todo

Currently dysfunctional.

any_set
Type:function (v: any) : bool

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

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

See also: all_set

bro_is_terminating
Type:function () : bool
Attributes:&deprecated = “Remove in v3.1: use zeek_is_terminating”

Checks if Zeek is terminating. This function is deprecated, use zeek_is_terminating instead.

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

See also: terminate

bro_version
Type:function () : string
Attributes:&deprecated = “Remove in v3.1: use zeek_version”

Returns the Zeek version string. This function is deprecated, use zeek_version instead.

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

Converts a string of bytes to a count.

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

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

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

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

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

See also: hexdump, hexstr_to_bytestring

calc_next_rotate
Type:function (i: interval) : interval

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

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

See also: rotate_file, rotate_file_by_name

cat
Type:function (…) : string

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

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

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

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

See also: cat, string_cat

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

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

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

Removes all elements from a set or table.

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

Closes an open file and flushes any buffered content.

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

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

connection_exists
Type:function (c: conn_id) : bool

Checks whether a connection is (still) active.

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

See also: lookup_connection

continue_processing
Type:function () : any

Resumes Zeek’s packet processing.

See also: suspend_processing

convert_for_pattern
Type:function (s: string) : string

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

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

See also: string_to_pattern

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

Converts a count and transport_proto to a port.

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

See also: port_to_count

count_to_v4_addr
Type:function (ip: count) : addr

Converts a count to an addr.

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

See also: raw_bytes_to_v4_addr, to_addr, to_subnet

counts_to_addr
Type:function (v: index_vec) : addr

Converts an index_vec to an addr.

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

See also: addr_to_counts

current_analyzer
Type:function () : count

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

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

Returns the current wall-clock time.

In general, you should use network_time instead unless you are using Zeek for non-networking uses (such as general scripting; not particularly recommended), because otherwise your script may behave very differently on live traffic versus played-back traffic from a save file.

Returns:The wall-clock time.

See also: network_time

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

Decodes a Base64-encoded string.

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

See also: decode_base64_conn, encode_base64

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

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

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

See also: decode_base64

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

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

Cid:The connection identifier.
Aid:The analyzer ID.
Err_if_no_conn:Emit an error message if the connection does not exit.
Prevent:Prevent the same analyzer type from being attached in the future. This is useful for preventing the same analyzer from being automatically reattached in the future, e.g. as a result of a DPD signature suddenly matching.
Returns:True if the connection identified by cid exists and has analyzer aid and it is scheduled for removal.

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

do_profiling
Type:function () : any

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

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

double_to_count
Type:function (d: double) : count

Converts a double to a count.

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

See also: double_to_time

double_to_interval
Type:function (d: double) : interval

Converts a double to an interval.

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

See also: interval_to_double

double_to_time
Type:function (d: double) : time

Converts a double value to a time.

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

See also: time_to_double, double_to_count

dump_current_packet
Type:function (file_name: string) : bool

Writes the current packet to a file.

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

See also: dump_packet, get_current_packet

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

Writes a given packet to a file.

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

See also: get_current_packet, dump_current_packet

dump_rule_stats
Type:function (f: file) : bool

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

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

See also: get_matcher_stats

enable_raw_output
Type:function (f: file) : any

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

F:The file to disable raw output for.
encode_base64
Type:function (s: string, a: string &default = "" &optional) : string

Encodes a Base64-encoded string.

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

See also: decode_base64

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

Adds data to an incremental entropy calculation.

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

See also: find_entropy, entropy_test_add, entropy_test_finish

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

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

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

See also: find_entropy, entropy_test_init, entropy_test_add

entropy_test_init
Type:function () : opaque of entropy

Initializes data structures for incremental entropy calculation.

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

See also: find_entropy, entropy_test_add, entropy_test_finish

enum_to_int
Type:function (e: any) : int

Converts an enum to an int.

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

Shuts down the Zeek process immediately.

Code:The exit code to return with.

See also: terminate

exp
Type:function (d: double) : double

Computes the exponential function.

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

See also: floor, sqrt, ln, log10

file_magic
Type:function (data: string) : mime_matches

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

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

See also: identify_data

file_mode
Type:function (mode: count) : string

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

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

Returns the size of a given file.

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

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

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

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

Data:

The data to compute the entropy for.

Returns:

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

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

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

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

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

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

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

See also: entropy_test_init, entropy_test_add, entropy_test_finish

floor
Type:function (d: double) : double

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

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

See also: sqrt, exp, ln, log10

flush_all
Type:function () : bool

Flushes all open files to disk.

Returns:True on success.

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

fmt
Type:function (…) : string

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

  • %: Literal %

  • -: Left-align field

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

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

  • [DTdxsefg]: Format specifier

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

See also: cat, cat_sep, string_cat

fnv1a32
Type:function (input: any) : count

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

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

See also: hrw_weight

get_conn_transport_proto
Type:function (cid: conn_id) : transport_proto

Extracts the transport protocol from a connection.

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

See also: get_port_transport_proto, get_orig_seq, get_resp_seq

get_current_packet
Type:function () : pcap_packet

Returns the currently processed PCAP packet.

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

See also: dump_current_packet, dump_packet

get_current_packet_header
Type:function () : raw_pkt_hdr

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

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

See also: raw_pkt_hdr, get_current_packet

get_file_name
Type:function (f: file) : string

Gets the filename associated with a file handle.

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

See also: open

get_port_transport_proto
Type:function (p: port) : transport_proto

Extracts the transport protocol from a port.

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

See also: get_conn_transport_proto, get_orig_seq, get_resp_seq

getenv
Type:function (var: string) : string

Returns a system environment variable.

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

See also: setenv

gethostname
Type:function () : string

Returns the hostname of the machine Zeek runs on.

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

Returns Zeek’s process ID.

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

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

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

See also: global_sizes

global_sizes
Type:function () : var_sizes

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

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

See also: global_ids

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

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

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

See also: haversine_distance_ip

hexstr_to_bytestring
Type:function (hexstr: string) : string

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

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

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

See also: hexdump, bytestring_to_hexstr

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

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

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

See also: fnv1a32

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

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

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

See also: file_magic

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

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

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

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

Todo

The return value should be changed to any.

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

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

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

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

Todo

The return value should be changed to any.

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

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

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

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

Todo

The return value should be changed to any.

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

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

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

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

Todo

The return value should be changed to any.

int_to_count
Type:function (n: int) : count

Converts a (positive) int to a count.

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

Converts an interval to a double.

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

See also: double_to_interval

is_external_connection
Type:function (c: connection) : bool

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

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

Checks whether a given port has ICMP as transport protocol.

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

See also: is_tcp_port, is_udp_port

is_local_interface
Type:function (ip: addr) : bool

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

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

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

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

Checks whether a given port has TCP as transport protocol.

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

See also: is_udp_port, is_icmp_port

is_udp_port
Type:function (p: port) : bool

Checks whether a given port has UDP as transport protocol.

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

See also: is_icmp_port, is_tcp_port

is_v4_addr
Type:function (a: addr) : bool

Returns whether an address is IPv4 or not.

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

Returns whether a subnet specification is IPv4 or not.

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

Returns whether an address is IPv6 or not.

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

Returns whether a subnet specification is IPv6 or not.

S:the subnet to check.
Returns:true if s is an IPv6 subnet, else false.
is_valid_ip
Type:function (ip: string) : bool

Checks if a string is a valid IPv4 or IPv6 address.

Ip:the string to check for valid IP formatting.
Returns:T if the string is a valid IPv4 or IPv6 address format.
ln
Type:function (d: double) : double

Computes the natural logarithm of a number.

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

See also: exp, floor, sqrt, log10

log10
Type:function (d: double) : double

Computes the common logarithm of a number.

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

See also: exp, floor, sqrt, ln

lookup_ID
Type:function (id: string) : any

Returns the value of a global identifier.

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

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

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

See also: lookup_hostname

lookup_asn
Type:function (a: addr) : count

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

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

See also: lookup_location

lookup_connection
Type:function (cid: conn_id) : connection

Returns the connection record for a given connection identifier.

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

See also: connection_exists

lookup_hostname
Type:function (host: string) : addr_set

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

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

See also: lookup_addr

lookup_hostname_txt
Type:function (host: string) : string

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

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

See also: lookup_hostname

lookup_location
Type:function (a: addr) : geo_location

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

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

See also: lookup_asn

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

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

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

See also: remask_addr

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

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

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

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

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

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

Returns:The MD5 hash value of the concatenated arguments.

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

Note

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

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

Returns the final MD5 digest of an incremental hash computation.

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

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

md5_hash_init
Type:function () : opaque of md5

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

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

Returns:The opaque handle associated with this hash computation.

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

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

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

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

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

md5_hmac
Type:function (…) : string

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

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

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

mkdir
Type:function (f: string) : bool

Creates a new directory.

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

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

mmdb_open_asn_db
Type:function (f: string) : bool

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

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

See also: lookup_asn

mmdb_open_location_db
Type:function (f: string) : bool

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

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

See also: lookup_asn

network_time
Type:function () : time

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

Returns:The timestamp of the packet processed.

See also: current_time

open
Type:function (f: string) : file

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

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

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

open_for_append
Type:function (f: string) : file

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

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

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

order
Type:function (…) : index_vec

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

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

See also: sort

packet_sources
Type:function () : PacketSourceList
Returns:a list of packet sources being read by Zeek.

See also: reading_live_traffic, reading_traces

paraglob_equals
Type:function (p_one: opaque of paraglob, p_two: opaque of paraglob) : bool

Compares two paraglobs for equality.

P_one:A compiled paraglob.
P_two:A compiled paraglob.
Returns:True if both paraglobs contain the same patterns, false otherwise.

## .. zeek:see::paraglob_add paraglob_match paraglob_init

paraglob_init
Type:function (v: any) : opaque of paraglob

Initializes and returns a new paraglob.

V:Vector of patterns to initialize the paraglob with.
Returns:A new, compiled, paraglob with the patterns in v
paraglob_match
Type:function (handle: opaque of paraglob, match: string) : string_vec

Gets all the patterns inside the handle associated with an input string.

Handle:A compiled paraglob.
Match:string to match against the paraglob.
Returns:A vector of strings matching the input string.

## .. zeek:see::paraglob_add paraglob_equals paraglob_init

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

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

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

See also: system, system_env

port_to_count
Type:function (p: port) : count

Converts a port to a count.

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

See also: count_to_port

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

Preserves the prefix of an IP address in anonymization.

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

See also: preserve_subnet, anonymize_addr

Todo

Currently dysfunctional.

preserve_subnet
Type:function (a: subnet) : any

Preserves the prefix of a subnet in anonymization.

A:The subnet to preserve.

See also: preserve_prefix, anonymize_addr

Todo

Currently dysfunctional.

print_raw
Type:function (…) : bool

Renders a sequence of values to a string of bytes and outputs them directly to stdout with no additional escape sequences added. No additional newline is added to the end either.

Returns:Always true.

See also: fmt, cat, cat_sep, string_cat, to_json

ptr_name_to_addr
Type:function (s: string) : addr

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

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

See also: addr_to_ptr_name, to_addr

rand
Type:function (max: count) : count

Generates a random number.

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

See also: srand

Note

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

raw_bytes_to_v4_addr
Type:function (b: string) : addr

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

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

See also: raw_bytes_to_v4_addr, to_addr, to_subnet

reading_live_traffic
Type:function () : bool

Checks whether Zeek 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 Zeek has stopped reading network traffic, for example due to receiving a termination signal.

Returns:True if reading traffic from a network interface.

See also: reading_traces, packet_sources

reading_traces
Type:function () : bool

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

Returns:True if reading traffic from a network trace.

See also: reading_live_traffic, packet_sources

record_fields
Type:function (rec: any) : record_field_table

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

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

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

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

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

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

See also: mask_addr

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

Renames a file from src_f to dst_f.

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

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

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

Resizes a vector.

Aggr:The vector instance.
Newsize:The new size of aggr.
Returns:The old size of aggr, or 0 if aggr is not a vector.
rmdir
Type:function (d: string) : bool

Removes a directory.

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

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

rotate_file
Type:function (f: file) : rotate_info

Rotates a file.

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

See also: rotate_file_by_name, calc_next_rotate

rotate_file_by_name
Type:function (f: string) : rotate_info

Rotates a file identified by its name.

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

See also: rotate_file, calc_next_rotate

routing0_data_to_addrs
Type:function (s: string) : addr_vec

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

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

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

O1:The first object.
O2:The second object.
Returns:True if o1 and o2 are equal.
set_buf
Type:function (f: file, buffered: bool) : any

Alters the buffering behavior of a file.

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

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

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

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

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

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

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

See also: skip_further_processing

Note

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

See also: get_contents_file, set_contents_file

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

Sets a system environment variable.

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

See also: getenv

sha1_hash
Type:function (…) : string

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

Returns:The SHA1 hash value of the concatenated arguments.

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

Note

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

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

Returns the final SHA1 digest of an incremental hash computation.

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

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

sha1_hash_init
Type:function () : opaque of sha1

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

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

Returns:The opaque handle associated with this hash computation.

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

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

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

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

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

sha256_hash
Type:function (…) : string

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

Returns:The SHA256 hash value of the concatenated arguments.

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

Note

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

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

Returns the final SHA256 digest of an incremental hash computation.

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

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

sha256_hash_init
Type:function () : opaque of sha256

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

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

Returns:The opaque handle associated with this hash computation.

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

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

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

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

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

skip_further_processing
Type:function (cid: conn_id) : bool

Informs Zeek that it should skip any further processing of the contents of a given connection. In particular, Zeek 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

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

sort
Type:function (…) : any

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

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

See also: order

sqrt
Type:function (x: double) : double

Computes the square root of a double.

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

See also: floor, exp, ln, log10

srand
Type:function (seed: count) : any

Sets the seed for subsequent rand calls.

Seed:The seed for the PRNG.

See also: rand

Note

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

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

Formats a given time value according to a format string.

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

Converts a string into a pattern.

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

See also: convert_for_pattern

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

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

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

Converts a subnet to an addr by extracting the prefix.

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

See also: to_subnet

subnet_width
Type:function (sn: subnet) : count

Returns the width of a subnet.

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

See also: to_subnet

suspend_processing
Type:function () : any

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

See also: continue_processing

syslog
Type:function (s: string) : any

Send a string to syslog.

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

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

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

See also: system_env, safe_shell_quote, piped_exec

Note

Note that this corresponds to the status of backgrounding the given command, not to the exit status of the command itself. A value of 127 corresponds to a failure to execute sh, and -1 to an internal system failure.

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

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

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

See also: system, safe_shell_quote, piped_exec

terminate
Type:function () : bool

Gracefully shut down Zeek by terminating outstanding processing.

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

See also: exit, zeek_is_terminating

time_to_double
Type:function (t: time) : double

Converts a time value to a double.

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

See also: double_to_time

to_addr
Type:function (ip: string) : addr

Converts a string to an addr.

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

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

to_count
Type:function (str: string) : count

Converts a string to a count.

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

See also: to_addr, to_int, to_port, to_subnet

to_double
Type:function (str: string) : double

Converts a string to a double.

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

Converts a string to an int.

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

See also: to_addr, to_port, to_subnet

to_json
Type:function (val: any, only_loggable: bool &default = F &optional, field_escape_pattern: pattern &default = /^?(^_)$?/ &optional) : string

A function to convert arbitrary Zeek data into a JSON string.

V:The value to convert to JSON. Typically a record.
Only_loggable:If the v value is a record this will only cause fields with the &log attribute to be included in the JSON.
Returns:a JSON formatted string.

See also: fmt, cat, cat_sep, string_cat, print_raw

to_port
Type:function (s: string) : port

Converts a string to a port.

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

See also: to_addr, to_count, to_int, to_subnet

to_subnet
Type:function (sn: string) : subnet

Converts a string to a subnet.

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

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

type_name
Type:function (t: any) : string

Returns the type name of an arbitrary Zeek variable.

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

Removes a destination address filter.

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

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

uninstall_dst_net_filter
Type:function (snet: subnet) : bool

Removes a destination subnet filter.

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

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

uninstall_src_addr_filter
Type:function (ip: addr) : bool

Removes a source address filter.

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

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

uninstall_src_net_filter
Type:function (snet: subnet) : bool

Removes a source subnet filter.

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

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

unique_id
Type:function (prefix: string) : string

Creates an identifier that is unique with high probability.

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

See also: unique_id_from

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

Creates an identifier that is unique with high probability.

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

See also: unique_id

Type:function (f: string) : bool

Removes a file from a directory.

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

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

uuid_to_string
Type:function (uuid: string) : string

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

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

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

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

Writes data to an open file.

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

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

zeek_args
Type:function () : string_vec
Returns:list of command-line arguments (argv) used to run Zeek.
zeek_is_terminating
Type:function () : bool

Checks if Zeek is terminating.

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

See also: terminate

zeek_version
Type:function () : string

Returns the Zeek version string.

Returns:Zeek’s version, e.g., 2.0-beta-47-debug.