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
## Checks if all elements of a string array are a valid octet value.
##
## octets: an array of strings to check for valid octet values.
##
## Returns: T if every element is between 0 and 255, inclusive, else F.
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.
##
## ip_str: the string to check for valid IP formatting.
##
## Returns: T if the string is a valid IPv4 or IPv6 address format.
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.
##
## 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
{
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.
##
## 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
{
if ( is_v4_addr(a) )

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

@ -4,17 +4,17 @@ module GLOBAL;
export {
## 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.
global id_string: function(id: conn_id): string;
## 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.
global reverse_id_string: function(id: conn_id): string;
## Calls :bro:id:`id_string` or :bro:id:`reverse_id_string` if the second
## argument is T or F, respectively.
## Calls :bro:id:`id_string` or :bro:id:`reverse_id_string` if the
## second argument is T or F, respectively.
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
## 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
## the future.
## and seen to be gone, then the file is available for being seen again
## in the future.
##
## dir: The directory to monitor for files.
##

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

@ -1,8 +1,8 @@
@load ./site
type Direction: enum {
## The connection originator is not within the locally-monitored network,
## but the other endpoint is.
## The connection originator is not within the locally-monitored
## network, but the other endpoint is.
INBOUND,
## The connection originator is within the locally-monitored network,
## 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
## to the locally-monitored network.
##
## 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.
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.
## 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.
function addr_matches_host(ip: addr, h: Host): bool
{

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

@ -6,16 +6,16 @@ module Exec;
export {
type Command: record {
## The command line to execute. Use care to avoid injection attacks.
## I.e. if the command uses untrusted/variable data, sanitize
## it with str_shell_escape().
## The command line to execute. Use care to avoid injection
## attacks (i.e., if the command uses untrusted/variable data,
## sanitize it with :bro:see:`str_shell_escape`).
cmd: string;
## Provide standard in to the program as a string.
## Provide standard input to the program as a string.
stdin: string &default="";
## If additional files are required to be read in as part of the output
## of the command they can be defined here.
## If additional files are required to be read in as part of the
## output of the command they can be defined here.
read_files: set[string] &optional;
# The unique id for tracking executors.
## The unique id for tracking executors.
uid: string &default=unique_id("");
};
@ -24,7 +24,7 @@ export {
exit_code: count &default=0;
## True if the command was terminated with a signal.
signal_exit: bool &default=F;
## Each line of standard out.
## Each line of standard output.
stdout: vector of string &optional;
## Each line of standard error.
stderr: vector of string &optional;
@ -39,11 +39,11 @@ export {
##
## 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.
global run: function(cmd: Command): Result;
## The system directory for temp files.
## The system directory for temporary files.
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
## with filename).
## TODO: Make this work on Window's style directories.
## input: a string that may contain an absolute path
## Returns: the first absolute path found in input string, else an empty string
##
## .. todo:: Make this work on Window's style directories.
##
## 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
{
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
## 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
{
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.
## 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
## 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
{
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.
## 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
{
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
## 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).
## 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
## included, it needs to be escaped with another backslash due to Bro's
## 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
{
local i: count = 0;
@ -38,10 +41,13 @@ type PatternMatchResult: record {
## For example: ``match_pattern("foobar", /o*[a-k]/)`` returns
## ``[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]/)``
## returns ``[matched=T, str=oob, off=2]``
## s: a string to match against
## p: a pattern to match
## Returns: a record indicating the match status
## returns ``[matched=T, str=oob, off=2]``.
##
## s: a string to match against.
##
## p: a pattern to match.
##
## Returns: a record indicating the match status.
function match_pattern(s: string, p: pattern): PatternMatchResult
{
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.
global peek: function(q: Queue): any;
## Merge two queue's together. If any settings are applied
## to the queues, the settings from q1 are used for the new
## Merge two queues together. If any settings are applied
## to the queues, the settings from *q1* are used for the new
## merged queue.
##
## q1: The first queue. Settings are taken from here.
@ -64,8 +64,8 @@ export {
##
## q: The queue.
##
## ret: A vector containing the
## current contents of q as the type of ret.
## ret: A vector containing the current contents of the queue
## as the type of ret.
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`.
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
## an argument.
## 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
##! be implemented as Bro functions and don't need to be implemented as built
##! in functions.
##! be implemented as Bro functions and don't need to be implemented as built-in
##! functions.
## Returns true if the given string is at least 25% composed of 8-bit
## characters.
@ -9,10 +9,13 @@ function is_string_binary(s: string): bool
return |gsub(s, /[\x00-\x7f]/, "")| * 100 / |s| >= 25;
}
## Joins a set of string together, with elements delimited by a constant string.
## ss: a set of strings to join
## j: the string used to join set elements
## Returns: a string composed of the all elements of the set, delimited by the
## 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.
##
## Returns: a string composed of all elements of the set, delimited by the
## joining 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.
## s: a string to escape
## chars: a string containing all the characters that need to be escaped
## Returns: a string with all occurrences of any character in ``chars`` escaped
##
## s: a string to escape.
##
## 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.
function string_escape(s: string, chars: string): string
{
@ -42,10 +48,13 @@ function string_escape(s: string, chars: string): string
return s;
}
## Cut a number of character from the end of the given string.
## s: a string to trim
## tail_len: the number of characters to remove from end of string
## Returns: the string in ``s`` with ``tail_len`` characters removed from end
## 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 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
{
if ( tail_len > |s| )

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

@ -11,8 +11,9 @@ export {
type TrackCount: record {
## The counter for the number of times something has happened.
n: count &default=0;
## The index of the vector where the counter currently is. This is
## used to track which threshold is currently being watched for.
## The index of the vector where the counter currently is. This
## is used to track which threshold is currently being watched
## for.
index: count &default=0;
};
@ -24,15 +25,18 @@ export {
## This will check if a :bro:type:`TrackCount` variable has crossed any
## 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
## monitored threshold value
## Returns: T if a threshold has been crossed, else F
## monitored threshold value.
##
## Returns: T if a threshold has been crossed, else F.
global check_threshold: function(v: vector of count, tracker: TrackCount): bool;
## This will use the :bro:id:`default_notice_thresholds` variable to check
## a :bro:type:`TrackCount` variable to see if it has crossed another
## threshold.
## This will use the :bro:id:`default_notice_thresholds` variable to
## check a :bro:type:`TrackCount` variable to see if it has crossed
## another threshold.
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
## give a minimalized human readable string for the minutes
## and seconds represented by the interval.
## Given an interval, returns a string representing the minutes and seconds
## in the interval (for example, "3m34s").
function duration_to_mins_secs(dur: interval): string
{
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.
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;
}
}