Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-15 21:18:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Fix typos and formatting in the base/utils docs

Browse source
This commit is contained in:
Daniel Thayer 2013-10-16 20:41:56 -05:00
parent c224fbe7f8
commit 92dc8e5880
13 changed files with 107 additions and 69 deletions
Download patch file Download diff file Expand all files Collapse all files

10
scripts/base/utils/addrs.bro
View file

@ -28,7 +28,9 @@ const ip_addr_regex =
/(([0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4})*)?)::(([0-9A-Fa-f]{1,4}:)*)([0-9]+)\.([0-9]+)\.([0-9]+)\.([0-9]+)/; # CompressedHex4Dec /(([0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4})*)?)::(([0-9A-Fa-f]{1,4}:)*)([0-9]+)\.([0-9]+)\.([0-9]+)\.([0-9]+)/; # CompressedHex4Dec
## Checks if all elements of a string array are a valid octet value. ## Checks if all elements of a string array are a valid octet value.
##
## octets: an array of strings to check for valid octet values. ## octets: an array of strings to check for valid octet values.
##
## Returns: T if every element is between 0 and 255, inclusive, else F. ## Returns: T if every element is between 0 and 255, inclusive, else F.
function has_valid_octets(octets: string_array): bool function has_valid_octets(octets: string_array): bool
{ {
@ -43,7 +45,9 @@ function has_valid_octets(octets: string_array): bool
} }
## Checks if a string appears to be a valid IPv4 or IPv6 address. ## Checks if a string appears to be a valid IPv4 or IPv6 address.
##
## ip_str: the string to check for valid IP formatting. ## ip_str: the string to check for valid IP formatting.
##
## Returns: T if the string is a valid IPv4 or IPv6 address format. ## Returns: T if the string is a valid IPv4 or IPv6 address format.
function is_valid_ip(ip_str: string): bool function is_valid_ip(ip_str: string): bool
{ {
@ -84,8 +88,10 @@ function is_valid_ip(ip_str: string): bool
} }
## Extracts all IP (v4 or v6) address strings from a given string. ## Extracts all IP (v4 or v6) address strings from a given string.
##
## input: a string that may contain an IP address anywhere within it. ## input: a string that may contain an IP address anywhere within it.
## Returns: an array containing all valid IP address strings found in input. ##
## Returns: an array containing all valid IP address strings found in *input*.
function find_ip_addresses(input: string): string_array function find_ip_addresses(input: string): string_array
{ {
local parts = split_all(input, ip_addr_regex); local parts = split_all(input, ip_addr_regex);
@ -105,7 +111,7 @@ function find_ip_addresses(input: string): string_array
## ##
## a: the address to make suitable for URI inclusion. ## a: the address to make suitable for URI inclusion.
## ##
## Returns: the string representation of *a* suitable for URI inclusion. ## Returns: the string representation of the address suitable for URI inclusion.
function addr_to_uri(a: addr): string function addr_to_uri(a: addr): string
{ {
if ( is_v4_addr(a) ) if ( is_v4_addr(a) )

8
scripts/base/utils/conn-ids.bro
View file

@ -4,17 +4,17 @@ module GLOBAL;
export { export {
## Takes a conn_id record and returns a string representation with the ## Takes a conn_id record and returns a string representation with the
## the general data flow appearing to be from the connection originator ## general data flow appearing to be from the connection originator
## on the left to the responder on the right. ## on the left to the responder on the right.
global id_string: function(id: conn_id): string; global id_string: function(id: conn_id): string;
## Takes a conn_id record and returns a string representation with the ## Takes a conn_id record and returns a string representation with the
## the general data flow appearing to be from the connection responder ## general data flow appearing to be from the connection responder
## on the right to the originator on the left. ## on the right to the originator on the left.
global reverse_id_string: function(id: conn_id): string; global reverse_id_string: function(id: conn_id): string;
## Calls :bro:id:`id_string` or :bro:id:`reverse_id_string` if the second ## Calls :bro:id:`id_string` or :bro:id:`reverse_id_string` if the
## argument is T or F, respectively. ## second argument is T or F, respectively.
global directed_id_string: function(id: conn_id, is_orig: bool): string; global directed_id_string: function(id: conn_id, is_orig: bool): string;
} }

4
scripts/base/utils/dir.bro
View file

@ -11,8 +11,8 @@ export {
## Register a directory to monitor with a callback that is called ## Register a directory to monitor with a callback that is called
## every time a previously unseen file is seen. If a file is deleted ## every time a previously unseen file is seen. If a file is deleted
## and seen to be gone, the file is available for being seen again in ## and seen to be gone, then the file is available for being seen again
## the future. ## in the future.
## ##
## dir: The directory to monitor for files. ## dir: The directory to monitor for files.
## ##

16
scripts/base/utils/directions-and-hosts.bro
View file

@ -1,8 +1,8 @@
@load ./site @load ./site
type Direction: enum { type Direction: enum {
## The connection originator is not within the locally-monitored network, ## The connection originator is not within the locally-monitored
## but the other endpoint is. ## network, but the other endpoint is.
INBOUND, INBOUND,
## The connection originator is within the locally-monitored network, ## The connection originator is within the locally-monitored network,
## but the other endpoint is not. ## but the other endpoint is not.
@ -16,8 +16,11 @@ type Direction: enum {
## Checks whether a given connection is of a given direction with respect ## Checks whether a given connection is of a given direction with respect
## to the locally-monitored network. ## to the locally-monitored network.
##
## id: a connection record containing the originator/responder hosts. ## id: a connection record containing the originator/responder hosts.
## d: a direction with respect to the locally-monitored network ##
## d: a direction with respect to the locally-monitored network.
##
## Returns: T if the two connection endpoints match the given direction, else F. ## Returns: T if the two connection endpoints match the given direction, else F.
function id_matches_direction(id: conn_id, d: Direction): bool function id_matches_direction(id: conn_id, d: Direction): bool
{ {
@ -46,8 +49,11 @@ type Host: enum {
}; };
## Checks whether a given host (IP address) matches a given host type. ## Checks whether a given host (IP address) matches a given host type.
## ip: address of a host ##
## h: a host type ## ip: address of a host.
##
## h: a host type.
##
## Returns: T if the given host matches the given type, else F. ## Returns: T if the given host matches the given type, else F.
function addr_matches_host(ip: addr, h: Host): bool function addr_matches_host(ip: addr, h: Host): bool
{ {

20
scripts/base/utils/exec.bro
View file

@ -6,16 +6,16 @@ module Exec;
export { export {
type Command: record { type Command: record {
## The command line to execute. Use care to avoid injection attacks. ## The command line to execute. Use care to avoid injection
## I.e. if the command uses untrusted/variable data, sanitize ## attacks (i.e., if the command uses untrusted/variable data,
## it with str_shell_escape(). ## sanitize it with :bro:see:`str_shell_escape`).
cmd: string; cmd: string;
## Provide standard in to the program as a string. ## Provide standard input to the program as a string.
stdin: string &default=""; stdin: string &default="";
## If additional files are required to be read in as part of the output ## If additional files are required to be read in as part of the
## of the command they can be defined here. ## output of the command they can be defined here.
read_files: set[string] &optional; read_files: set[string] &optional;
# The unique id for tracking executors. ## The unique id for tracking executors.
uid: string &default=unique_id(""); uid: string &default=unique_id("");
}; };
@ -24,7 +24,7 @@ export {
exit_code: count &default=0; exit_code: count &default=0;
## True if the command was terminated with a signal. ## True if the command was terminated with a signal.
signal_exit: bool &default=F; signal_exit: bool &default=F;
## Each line of standard out. ## Each line of standard output.
stdout: vector of string &optional; stdout: vector of string &optional;
## Each line of standard error. ## Each line of standard error.
stderr: vector of string &optional; stderr: vector of string &optional;
@ -39,11 +39,11 @@ export {
## ##
## cmd: The command to run. Use care to avoid injection attacks! ## cmd: The command to run. Use care to avoid injection attacks!
## ##
## returns: A record representing the full results from the ## Returns: A record representing the full results from the
## external program execution. ## external program execution.
global run: function(cmd: Command): Result; global run: function(cmd: Command): Result;
## The system directory for temp files. ## The system directory for temporary files.
const tmp_dir = "/tmp" &redef; const tmp_dir = "/tmp" &redef;
} }

26
scripts/base/utils/paths.bro
View file

@ -4,9 +4,12 @@ const absolute_path_pat = /(\/|[A-Za-z]:[\\\/]).*/;
## Given an arbitrary string, extracts a single, absolute path (directory ## Given an arbitrary string, extracts a single, absolute path (directory
## with filename). ## with filename).
## TODO: Make this work on Window's style directories. ##
## input: a string that may contain an absolute path ## .. todo:: Make this work on Window's style directories.
## Returns: the first absolute path found in input string, else an empty string ##
## input: a string that may contain an absolute path.
##
## Returns: the first absolute path found in input string, else an empty string.
function extract_path(input: string): string function extract_path(input: string): string
{ {
const dir_pattern = /(\/|[A-Za-z]:[\\\/])([^\"\ ]|(\\\ ))*/; const dir_pattern = /(\/|[A-Za-z]:[\\\/])([^\"\ ]|(\\\ ))*/;
@ -20,8 +23,10 @@ function extract_path(input: string): string
## Compresses a given path by removing '..'s and the parent directory it ## Compresses a given path by removing '..'s and the parent directory it
## references and also removing dual '/'s and extraneous '/./'s. ## 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 ## dir: a path string, either relative or absolute.
##
## Returns: a compressed version of the input path.
function compress_path(dir: string): string function compress_path(dir: string): string
{ {
const cdup_sep = /((\/)*([^\/]|\\\/)+)?((\/)+\.\.(\/)*)/; const cdup_sep = /((\/)*([^\/]|\\\/)+)?((\/)+\.\.(\/)*)/;
@ -56,10 +61,13 @@ function compress_path(dir: string): string
} }
## Constructs a path to a file given a directory and a file name. ## Constructs a path to a file given a directory and a file name.
## dir: the directory in which the file lives ##
## file_name: the name of the file ## dir: the directory in which the file lives.
##
## file_name: the name of the file.
##
## Returns: the concatenation of the directory path and file name, or just ## Returns: the concatenation of the directory path and file name, or just
## the file name if it's already an absolute path ## the file name if it's already an absolute path.
function build_path(dir: string, file_name: string): string function build_path(dir: string, file_name: string): string
{ {
return (file_name == absolute_path_pat) ? return (file_name == absolute_path_pat) ?
@ -67,7 +75,7 @@ function build_path(dir: string, file_name: string): string
} }
## Returns a compressed path to a file given a directory and file name. ## Returns a compressed path to a file given a directory and file name.
## See :bro:id`build_path` and :bro:id:`compress_path`. ## See :bro:id:`build_path` and :bro:id:`compress_path`.
function build_path_compressed(dir: string, file_name: string): string function build_path_compressed(dir: string, file_name: string): string
{ {
return compress_path(build_path(dir, file_name)); return compress_path(build_path(dir, file_name));

18
scripts/base/utils/patterns.bro
View file

@ -5,11 +5,14 @@ module GLOBAL;
## Given a pattern as a string with two tildes (~~) contained in it, it will ## Given a pattern as a string with two tildes (~~) contained in it, it will
## return a pattern with string set's elements OR'd together where the ## return a pattern with string set's elements OR'd together where the
## double-tilde was given (this function only works at or before init time). ## double-tilde was given (this function only works at or before init time).
## ss: a set of strings to OR together ##
## ss: a set of strings to OR together.
##
## pat: the pattern containing a "~~" in it. If a literal backslash is ## pat: the pattern containing a "~~" in it. If a literal backslash is
## included, it needs to be escaped with another backslash due to Bro's ## included, it needs to be escaped with another backslash due to Bro's
## string parsing reducing it to a single backslash upon rendering. ## string parsing reducing it to a single backslash upon rendering.
## Returns: the input pattern with "~~" replaced by OR'd elements of input set ##
## Returns: the input pattern with "~~" replaced by OR'd elements of input set.
function set_to_regex(ss: set[string], pat: string): pattern function set_to_regex(ss: set[string], pat: string): pattern
{ {
local i: count = 0; local i: count = 0;
@ -38,10 +41,13 @@ type PatternMatchResult: record {
## For example: ``match_pattern("foobar", /o*[a-k]/)`` returns ## For example: ``match_pattern("foobar", /o*[a-k]/)`` returns
## ``[matched=T, str=f, off=1]``, because the *first* match is for ## ``[matched=T, str=f, off=1]``, because the *first* match is for
## zero o's followed by an [a-k], but ``match_pattern("foobar", /o+[a-k]/)`` ## zero o's followed by an [a-k], but ``match_pattern("foobar", /o+[a-k]/)``
## returns ``[matched=T, str=oob, off=2]`` ## returns ``[matched=T, str=oob, off=2]``.
## s: a string to match against ##
## p: a pattern to match ## s: a string to match against.
## Returns: a record indicating the match status ##
## p: a pattern to match.
##
## Returns: a record indicating the match status.
function match_pattern(s: string, p: pattern): PatternMatchResult function match_pattern(s: string, p: pattern): PatternMatchResult
{ {
local a = split_n(s, p, T, 1); local a = split_n(s, p, T, 1);

8
scripts/base/utils/queue.bro
View file

@ -42,8 +42,8 @@ export {
## Returns: The value at the end of the queue. ## Returns: The value at the end of the queue.
global peek: function(q: Queue): any; global peek: function(q: Queue): any;
## Merge two queue's together. If any settings are applied ## Merge two queues together. If any settings are applied
## to the queues, the settings from q1 are used for the new ## to the queues, the settings from *q1* are used for the new
## merged queue. ## merged queue.
## ##
## q1: The first queue. Settings are taken from here. ## q1: The first queue. Settings are taken from here.
@ -64,8 +64,8 @@ export {
## ##
## q: The queue. ## q: The queue.
## ##
## ret: A vector containing the ## ret: A vector containing the current contents of the queue
## current contents of q as the type of ret. ## as the type of ret.
global get_vector: function(q: Queue, ret: vector of any); global get_vector: function(q: Queue, ret: vector of any);
} }

2
scripts/base/utils/site.bro
View file

@ -67,7 +67,7 @@ export {
## The function inspects :bro:id:`Site::neighbor_zones`. ## The function inspects :bro:id:`Site::neighbor_zones`.
global is_neighbor_name: function(name: string): bool; global is_neighbor_name: function(name: string): bool;
## Function that returns a common separated list of email addresses ## Function that returns a comma-separated list of email addresses
## that are considered administrators for the IP address provided as ## that are considered administrators for the IP address provided as
## an argument. ## an argument.
## The function inspects :bro:id:`Site::local_admins`. ## The function inspects :bro:id:`Site::local_admins`.

35
scripts/base/utils/strings.bro
View file

@ -1,6 +1,6 @@
##! Functions to assist with small string analysis and manipulation that can ##! Functions to assist with small string analysis and manipulation that can
##! be implemented as Bro functions and don't need to be implemented as built ##! be implemented as Bro functions and don't need to be implemented as built-in
##! in functions. ##! functions.
## Returns true if the given string is at least 25% composed of 8-bit ## Returns true if the given string is at least 25% composed of 8-bit
## characters. ## characters.
@ -9,10 +9,13 @@ function is_string_binary(s: string): bool
return |gsub(s, /[\x00-\x7f]/, "")| * 100 / |s| >= 25; return |gsub(s, /[\x00-\x7f]/, "")| * 100 / |s| >= 25;
} }
## Joins a set of string together, with elements delimited by a constant string. ## Join a set of strings together, with elements delimited by a constant string.
## ss: a set of strings to join ##
## j: the string used to join set elements ## ss: a set of strings to join.
## Returns: a string composed of the all elements of the set, delimited by the ##
## j: the string used to join set elements.
##
## Returns: a string composed of all elements of the set, delimited by the
## joining string. ## joining string.
function join_string_set(ss: set[string], j: string): string function join_string_set(ss: set[string], j: string): string
{ {
@ -30,9 +33,12 @@ function join_string_set(ss: set[string], j: string): string
} }
## Given a string, returns an escaped version. ## Given a string, returns an escaped version.
## s: a string to escape ##
## chars: a string containing all the characters that need to be escaped ## s: a string to escape.
## Returns: a string with all occurrences of any character in ``chars`` escaped ##
## chars: a string containing all the characters that need to be escaped.
##
## Returns: a string with all occurrences of any character in *chars* escaped
## using ``\``, and any literal ``\`` characters likewise escaped. ## using ``\``, and any literal ``\`` characters likewise escaped.
function string_escape(s: string, chars: string): string function string_escape(s: string, chars: string): string
{ {
@ -42,10 +48,13 @@ function string_escape(s: string, chars: string): string
return s; return s;
} }
## Cut a number of character from the end of the given string. ## Cut a number of characters from the end of the given string.
## s: a string to trim ##
## tail_len: the number of characters to remove from end of string ## s: a string to trim.
## Returns: the string in ``s`` with ``tail_len`` characters removed from end ##
## tail_len: the number of characters to remove from the end of the string.
##
## Returns: the given string with *tail_len* characters removed from the end.
function cut_tail(s: string, tail_len: count): string function cut_tail(s: string, tail_len: count): string
{ {
if ( tail_len > |s| ) if ( tail_len > |s| )

20
scripts/base/utils/thresholds.bro
View file

@ -11,8 +11,9 @@ export {
type TrackCount: record { type TrackCount: record {
## The counter for the number of times something has happened. ## The counter for the number of times something has happened.
n: count &default=0; n: count &default=0;
## The index of the vector where the counter currently is. This is ## The index of the vector where the counter currently is. This
## used to track which threshold is currently being watched for. ## is used to track which threshold is currently being watched
## for.
index: count &default=0; index: count &default=0;
}; };
@ -24,15 +25,18 @@ export {
## This will check if a :bro:type:`TrackCount` variable has crossed any ## This will check if a :bro:type:`TrackCount` variable has crossed any
## thresholds in a given set. ## thresholds in a given set.
## v: a vector holding counts that represent thresholds ##
## v: a vector holding counts that represent thresholds.
##
## tracker: the record being used to track event counter and currently ## tracker: the record being used to track event counter and currently
## monitored threshold value ## monitored threshold value.
## Returns: T if a threshold has been crossed, else F ##
## Returns: T if a threshold has been crossed, else F.
global check_threshold: function(v: vector of count, tracker: TrackCount): bool; global check_threshold: function(v: vector of count, tracker: TrackCount): bool;
## This will use the :bro:id:`default_notice_thresholds` variable to check ## This will use the :bro:id:`default_notice_thresholds` variable to
## a :bro:type:`TrackCount` variable to see if it has crossed another ## check a :bro:type:`TrackCount` variable to see if it has crossed
## threshold. ## another threshold.
global default_check_threshold: function(tracker: TrackCount): bool; global default_check_threshold: function(tracker: TrackCount): bool;
} }

5
scripts/base/utils/time.bro
View file

@ -1,7 +1,6 @@
## Given an interval, returns a string of the form 3m34s to ## Given an interval, returns a string representing the minutes and seconds
## give a minimalized human readable string for the minutes ## in the interval (for example, "3m34s").
## and seconds represented by the interval.
function duration_to_mins_secs(dur: interval): string function duration_to_mins_secs(dur: interval): string
{ {
local dur_count = double_to_count(interval_to_double(dur)); local dur_count = double_to_count(interval_to_double(dur));

4
scripts/base/utils/urls.bro
View file

@ -1,4 +1,4 @@
## Functions for URL handling. ##! Functions for URL handling.
## A regular expression for matching and extracting URLs. ## A regular expression for matching and extracting URLs.
const url_regex = /^([a-zA-Z\-]{3,5})(:\/\/[^\/?#"'\r\n><]*)([^?#"'\r\n><]*)([^[:blank:]\r\n"'><]*|\??[^"'\r\n><]*)/ &redef; const url_regex = /^([a-zA-Z\-]{3,5})(:\/\/[^\/?#"'\r\n><]*)([^?#"'\r\n><]*)([^[:blank:]\r\n"'><]*|\??[^"'\r\n><]*)/ &redef;
@ -22,4 +22,4 @@ function find_all_urls_without_scheme(s: string): string_set
} }
return return_urls; return return_urls;
} }