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¶
An internal function that helps initialize BIFs. |
|
Checks whether a given file is open. |
|
Converts an IP address to a reverse pointer name. |
|
Tests whether all elements of a boolean vector ( |
|
Anonymizes an IP address. |
|
Tests whether a boolean vector ( |
|
Returns a representation of the call stack as a vector of call stack elements, each containing call location information. |
|
Returns whether Zeek was started in bare mode. |
|
Converts a string of bytes to a |
|
Converts a string of bytes (in network byte order) to a |
|
Converts a string of bytes into its hexadecimal representation. |
|
Calculates the duration until the next time a file is to be rotated, based on a given rotate interval. |
|
Returns the concatenation of the string representation of its arguments. |
|
Concatenates all arguments, with a separator placed between each one. |
|
Checks if a specific subnet is a member of a set/table[subnet]. |
|
Removes all elements from a set or table. |
|
Closes an open file and flushes any buffered content. |
|
Compresses a given path by removing ‘..’s and the parent directory it references and also removing dual ‘/’s and extraneous ‘/./’s. |
|
Checks whether a connection is (still) active. |
|
Resumes Zeek’s packet processing. |
|
Escapes a string so that it becomes a valid |
|
Returns the ID of the analyzer which raised the current event. |
|
Returns the current wall-clock time. |
|
Decodes a Base64-encoded string. |
|
Decodes a Base64-encoded string that was derived from processing a connection. |
|
Disables the analyzer which raised the current event (if the analyzer belongs to the given connection). |
|
Enables detailed collection of profiling statistics. |
|
Writes the current packet to a file. |
|
Writes a given packet to a file. |
|
Write rule matcher statistics (DFA states, transitions, memory usage, cache hits/misses) to a file. |
|
Prevents escaping of non-ASCII characters when writing to a file. |
|
Encodes a Base64-encoded string. |
|
Adds data to an incremental entropy calculation. |
|
Finishes an incremental entropy calculation. |
|
Initializes data structures for incremental entropy calculation. |
|
Returns all value names associated with an enum type. |
|
Shuts down the Zeek process immediately. |
|
Computes the exponential function. |
|
Determines the MIME type of a piece of data using Zeek’s file magic signatures. |
|
Converts UNIX file permissions given by a mode to an ASCII string. |
|
Returns the size of a given file. |
|
For a set[subnet]/table[subnet], create a new table that contains all entries that contain a given subnet. |
|
Performs an entropy test on the given data. |
|
Computes the greatest integer less than the given |
|
Flushes all open files to disk. |
|
Produces a formatted string à la |
|
Returns 32-bit digest of arbitrary input values using FNV-1a hash algorithm. |
|
By default, zeek does not generate (raise) events that have not handled by any scripts. |
|
Extracts the transport protocol from a connection. |
|
Returns the currently processed PCAP packet. |
|
Function to get the raw headers of the currently processed packet. |
|
Gets the filename associated with a file handle. |
|
Extracts the transport protocol from a |
|
Returns a system environment variable. |
|
Returns the hostname of the machine Zeek runs on. |
|
Returns Zeek’s process ID. |
|
Generates a table of the “footprint” of all global container variables. |
|
Generates a table with information about all global identifiers. |
|
Returns a set giving the names of all global options. |
|
Generates a table of the size of all global variables. |
|
Calculates distance between two geographic locations using the haversine formula. |
|
Converts a hex-string into its binary representation. |
|
Calculates a weight value for use in a Rendezvous Hashing algorithm. |
|
Determines the MIME type of a piece of data using Zeek’s file magic signatures. |
|
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. |
|
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. |
|
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. |
|
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. |
|
Checks whether a given |
|
Checks whether a given IP address belongs to a local interface. |
|
Returns whether or not processing is currently suspended. |
|
Checks whether the last raised event came from a remote peer. |
|
Checks whether a given |
|
Checks whether a given |
|
Returns whether an address is IPv4 or not. |
|
Returns whether a subnet specification is IPv4 or not. |
|
Returns whether an address is IPv6 or not. |
|
Returns whether a subnet specification is IPv6 or not. |
|
Checks if a string is a valid IPv4 or IPv6 address. |
|
Computes the natural logarithm of a number. |
|
Computes the common logarithm of a number. |
|
Returns the value of a global identifier. |
|
Issues an asynchronous reverse DNS lookup and delays the function result. |
|
Performs an ASN lookup of an IP address. |
|
Performs an lookup of AS numbe & organization of an IP address. |
|
Returns the |
|
Issues an asynchronous DNS lookup and delays the function result. |
|
Issues an asynchronous TEXT DNS lookup and delays the function result. |
|
Performs a geo-lookup of an IP address. |
|
Masks an address down to the number of given upper bits. |
|
Manually triggers the signature engine for a given connection. |
|
Gets all subnets that contain a given subnet from a set/table[subnet]. |
|
Computes the MD5 hash value of the provided list of arguments. |
|
Returns the final MD5 digest of an incremental hash computation. |
|
Constructs an MD5 handle to enable incremental hash computation. |
|
Updates the MD5 value associated with a given index. |
|
Computes an HMAC-MD5 hash value of the provided list of arguments. |
|
Creates a new directory. |
|
Initializes MMDB for later use of lookup_asn or lookup_autonomous_system. |
|
Initializes MMDB for later use of lookup_location. |
|
Returns the timestamp of the last packet processed. |
|
Opens a file for writing. |
|
Opens a file for writing or appending. |
|
Returns the order of the elements in a vector according to some comparison function. |
|
Returns: the packet source being read by Zeek. |
|
Compares two paraglobs for equality. |
|
Initializes and returns a new paraglob. |
|
Gets all the patterns inside the handle associated with an input string. |
|
Opens a program with |
|
Preserves the prefix of an IP address in anonymization. |
|
Preserves the prefix of a subnet in anonymization. |
|
Renders a sequence of values to a string of bytes and outputs them directly
to |
|
Converts a reverse pointer name to an address. |
|
Generates a random number. |
|
Converts a |
|
Converts a |
|
Checks whether Zeek reads traffic from one or more network interfaces (as opposed to from a network trace in a file). |
|
Checks whether Zeek reads traffic from a trace file (as opposed to from a network interface). |
|
Generates metadata about a record’s fields. |
|
Converts a record type name to a vector of strings, where each element is the name of a record field. |
|
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. |
|
Renames a file from src_f to dst_f. |
|
Resizes a vector. |
|
Removes a directory. |
|
Rotates a file. |
|
Rotates a file identified by its name. |
|
Converts the data field of |
|
Checks whether two objects reference the same internal object. |
|
Alters the buffering behavior of a file. |
|
Sets an individual inactivity timeout for a connection and thus overrides the global inactivity timeout. |
|
Sets the timestamp associated with the last packet processed. |
|
Controls whether packet contents belonging to a connection should be
recorded (when |
|
Sets a system environment variable. |
|
Computes the SHA1 hash value of the provided list of arguments. |
|
Returns the final SHA1 digest of an incremental hash computation. |
|
Constructs an SHA1 handle to enable incremental hash computation. |
|
Updates the SHA1 value associated with a given index. |
|
Computes the SHA256 hash value of the provided list of arguments. |
|
Returns the final SHA256 digest of an incremental hash computation. |
|
Constructs an SHA256 handle to enable incremental hash computation. |
|
Updates the SHA256 value associated with a given index. |
|
Informs Zeek that it should skip any further processing of the contents of a given connection. |
|
Sorts a vector in place. |
|
Computes the square root of a |
|
Sets the seed for subsequent |
|
Formats a given time value according to a format string. |
|
Parse a textual representation of a date/time value into a |
|
Returns the width of a |
|
Stops Zeek’s packet processing. |
|
Send a string to syslog. |
|
Invokes a command via the |
|
Invokes a command via the |
|
Gracefully shut down Zeek by terminating outstanding processing. |
|
A function to convert arbitrary Zeek data into a JSON string. |
|
Returns all type name aliases of a value or type. |
|
Returns the type name of an arbitrary Zeek variable. |
|
Removes a destination address filter. |
|
Removes a destination subnet filter. |
|
Removes a source address filter. |
|
Removes a source subnet filter. |
|
Creates an identifier that is unique with high probability. |
|
Creates an identifier that is unique with high probability. |
|
Removes a file from a directory. |
|
Converts a bytes representation of a UUID into its string form. |
|
Computes a value’s “footprint”: the number of objects the value contains either directly or indirectly. |
|
|
Returns the number of bytes that a value occupies in memory. |
Writes data to an open file. |
|
Returns: list of command-line arguments ( |
|
Checks if Zeek is terminating. |
|
Returns the Zeek version string. |
Detailed Interface¶
Functions¶
- active_file¶
-
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¶
-
Converts an
addr
to anindex_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¶
-
Converts an IP address to a reverse pointer name. For example,
192.168.0.1
to1.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
- all_set¶
-
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¶
-
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
- backtrace¶
-
Returns a representation of the call stack as a vector of call stack elements, each containing call location information.
- Returns
the call stack information, including function, file, and line location information.
- bare_mode¶
-
Returns whether Zeek was started in bare mode.
- Returns
True if Zeek was started in bare mode, false otherwise.
- bytestring_to_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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
Removes all elements from a set or table.
- V
The set or table
- close¶
-
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
- compress_path¶
-
Compresses a given path by removing ‘..’s and the parent directory it references and also removing dual ‘/’s and extraneous ‘/./’s.
- Dir
a path string, either relative or absolute.
- Returns
a compressed version of the input path.
- connection_exists¶
-
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¶
-
Resumes Zeek’s packet processing.
See also:
suspend_processing
,is_processing_suspended
- convert_for_pattern¶
-
Escapes a string so that it becomes a valid
pattern
and can be used with thestring_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_double¶
-
See also:
int_to_double
,double_to_count
- count_to_port¶
- Type
function
(num:count
, proto:transport_proto
) :port
Converts a
count
andtransport_proto
to aport
.See also:
port_to_count
- count_to_v4_addr¶
-
See also:
raw_bytes_to_v4_addr
,to_addr
,to_subnet
,raw_bytes_to_v6_addr
- counts_to_addr¶
-
Converts an
index_vec
to anaddr
.- 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¶
-
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¶
-
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
,set_network_time
- decode_base64¶
-
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¶
-
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¶
-
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¶
-
- D
The
double
to convert.- Returns
The
double
d as signed integer. The value returned follows typical rounding rules, as implemented by rint().
See also:
double_to_time
- double_to_int¶
- double_to_interval¶
-
Converts a
double
to aninterval
.See also:
interval_to_double
- double_to_time¶
-
Converts a
double
value to atime
.See also:
time_to_double
,double_to_count
- dump_current_packet¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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 viaentropy_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¶
-
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_names¶
- Type
function
(et:any
) :string_set
Returns all value names associated with an enum type.
- Et
An enum type.
- Returns
All enum value names associated with enum type et. If et is not an enum type, an empty set is returned.
- enum_to_int¶
- exit¶
-
Shuts down the Zeek process immediately.
- Code
The exit code to return with.
See also:
terminate
- exp¶
-
Computes the exponential function.
- D
The argument to the exponential function.
- Returns
e to the power of d.
- 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¶
-
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¶
-
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¶
-
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¶
-
Computes the greatest integer less than the given
double
value. For example,floor(3.14)
returns3.0
, andfloor(-3.14)
returns-4.0
.
- flush_all¶
-
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¶
-
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 precisiond
: 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 126will 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¶
-
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
- generate_all_events¶
-
By default, zeek does not generate (raise) events that have not handled by any scripts. This means that these events will be invisible to a lot of other event handlers - and will not raise
new_event
.Calling this function will cause all event handlers to be raised. This is, likely, only useful for debugging and causes reduced performance.
- 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¶
-
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¶
-
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¶
-
Returns the hostname of the machine Zeek runs on.
- Returns
The hostname of the machine Zeek runs on.
- global_container_footprints¶
-
Generates a table of the “footprint” of all global container variables. This is (approximately) the number of objects the global contains either directly or indirectly. The number is not meant to be precise, but rather comparable: larger footprint correlates with more memory consumption. The table index is the variable name and the value is the footprint.
- Returns
A table that maps variable names to their footprints.
See also:
val_footprint
- global_ids¶
-
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_options¶
- Type
function
() :string_set
Returns a set giving the names of all global options.
- global_sizes¶
- Type
- Attributes
&deprecated
= “Remove in v5.1. MemoryAllocation() is deprecated and will be removed.”
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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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¶
- int_to_double¶
-
See also:
count_to_double
,double_to_count
- interval_to_double¶
-
Converts an
interval
to adouble
.See also:
double_to_interval
- is_icmp_port¶
-
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¶
-
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_processing_suspended¶
-
Returns whether or not processing is currently suspended.
See also:
suspend_processing
,continue_processing
- is_remote_event¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
Computes the natural logarithm of a number.
- D
The argument to the logarithm.
- Returns
The natural logarithm of d.
- log10¶
-
Computes the common logarithm of a number.
- D
The argument to the logarithm.
- Returns
The common logarithm of d.
- lookup_ID¶
-
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¶
-
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
- Attributes
&deprecated
= “Remove in v6.1. Functionality is now handled by lookup_autonomous_system().”
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 the IP address.
See also:
lookup_location
,lookup_autonomous_system
- lookup_autonomous_system¶
- Type
function
(a:addr
) :geo_autonomous_system
Performs an lookup of AS numbe & organization of an IP address. Requires Zeek to be built with
libmaxminddb
.- A
The IP address to lookup.
- Returns
A record with autonomous system number and organization that contains a.
See also:
lookup_location
,lookup_asn
- 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¶
-
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¶
-
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
,lookup_autonomous_system
- mask_addr¶
-
Masks an address down to the number of given upper bits. For example,
mask_addr(1.2.3.4, 18)
returns1.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¶
-
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¶
-
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¶
-
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 callmd5_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 invokingmd5_hash_update(c$http$md5_handle, some_more_data)
in thehttp_entity_data
event handler. When all data has arrived, a call tomd5_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¶
-
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¶
-
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¶
-
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¶
-
Initializes MMDB for later use of lookup_asn or lookup_autonomous_system. 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
,lookup_autonomous_system
- mmdb_open_location_db¶
-
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
,lookup_autonomous_system
- network_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
,set_network_time
- open¶
-
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¶
-
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¶
-
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 (assumingo
is the vector returned byorder
): v[o[0]], v[o[1]], etc.
See also:
sort
- packet_source¶
- Type
function
() :PacketSource
- Returns
the packet source being read by Zeek.
See also:
reading_live_traffic
,reading_traces
- paraglob_equals¶
-
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¶
-
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¶
-
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¶
-
See also:
count_to_port
- preserve_prefix¶
-
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¶
-
Preserves the prefix of a subnet in anonymization.
- A
The subnet to preserve.
See also:
preserve_prefix
,anonymize_addr
Todo
Currently dysfunctional.
- print_raw¶
-
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¶
-
Converts a reverse pointer name to an address. For example,
1.0.168.192.in-addr.arpa
to192.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¶
-
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¶
-
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.See also:
raw_bytes_to_v4_addr
,to_addr
,to_subnet
- raw_bytes_to_v6_addr¶
-
Converts a
string
of bytes into an IPv6 address. In particular, this function interprets the first 16 bytes of the string as an IPv6 address in network order.See also:
raw_bytes_to_v6_addr
,to_addr
,to_subnet
- reading_live_traffic¶
-
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_source
- reading_traces¶
-
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_source
- 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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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_network_time¶
-
Sets the timestamp associated with the last packet processed. Used for event replaying.
- Nt
The time to which to set “network time”.
- Returns
The timestamp of the packet processed.
See also:
current_time
,network_time
- set_record_packets¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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 callsha1_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 invokingsha1_hash_update(c$http$sha1_handle, some_more_data)
in thehttp_entity_data
event handler. When all data has arrived, a call tosha1_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¶
-
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¶
-
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¶
-
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¶
-
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 callsha256_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 invokingsha256_hash_update(c$http$sha256_handle, some_more_data)
in thehttp_entity_data
event handler. When all data has arrived, a call tosha256_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¶
-
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¶
-
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¶
-
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 befunction(a: T, b: T): int
, which returns a value less than zero ifa < b
for some type-specific notion of the less-than operator. The comparison function is optional if the type is a numeric type (int, count, double, time, 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¶
-
Computes the square root of a
double
.- X
The number to compute the square root of.
- Returns
The square root of x.
- srand¶
-
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¶
-
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¶
-
Converts a
string
into apattern
.- 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¶
-
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¶
-
Converts a
subnet
to anaddr
by extracting the prefix.- Sn
The subnet to convert.
- Returns
The subnet as an
addr
.
See also:
to_subnet
- subnet_width¶
-
Returns the width of a
subnet
.- Sn
The subnet.
- Returns
The width of the subnet.
See also:
to_subnet
- suspend_processing¶
-
Stops Zeek’s packet processing. This function is used to synchronize distributed trace processing with communication enabled (pseudo-realtime mode).
See also:
continue_processing
,is_processing_suspended
- system¶
-
Invokes a command via the
system
function of the OS. The command runs in the background withstdout
redirecting tostderr
. 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 assystem
, 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 withZEEK_ARG_
.- Returns
The return value from the OS
system
function.
See also:
system
,safe_shell_quote
,piped_exec
- terminate¶
-
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¶
-
Converts a
time
value to adouble
.See also:
double_to_time
- to_addr¶
-
- Ip
The
string
to convert.- Returns
The
string
ip asaddr
, 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
,raw_bytes_to_v6_addr
,to_subnet
- to_count¶
- to_double¶
- to_int¶
- 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¶
- to_subnet¶
-
Converts a
string
to asubnet
.- 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
,raw_bytes_to_v6_addr
,to_addr
- type_aliases¶
- Type
function
(x:any
) :string_set
Returns all type name aliases of a value or type.
- X
An arbitrary value or type.
- Returns
The set of all type name aliases of x (or the type of x if it’s a value instead of a type). For primitive values and types like
string
orcount
, this returns an empty set. For types with user-defined names likerecord
orenum
, the returned set contains the original user-defined name for the type along with all aliases. For other compound types, liketable
, the returned set is empty unless explicitly requesting aliases for a user-defined type alias or a value that was explicitly created using a type alias (as opposed to originating from an “anonymous” constructor or initializer for that compound type).
- type_name¶
-
Returns the type name of an arbitrary Zeek variable.
- T
An arbitrary object.
- Returns
The type name of t.
- uninstall_dst_addr_filter¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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¶
-
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
- unlink¶
-
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¶
-
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_footprint¶
-
Computes a value’s “footprint”: the number of objects the value contains either directly or indirectly. The number is not meant to be precise, but rather comparable: larger footprint correlates with more memory consumption.
- Returns
the footprint.
See also:
global_container_footprints
- val_size¶
- Type
- Attributes
&deprecated
= “Remove in v5.1. MemoryAllocation() is deprecated and will be removed.”
Returns the number of bytes that a value occupies in memory.
- V
The value
- Returns
The number of bytes that v occupies.
- write_file¶
-
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.