From c5e98a811677c6716658dca26726d0ce4b9a9c68 Mon Sep 17 00:00:00 2001 From: Jon Siwek Date: Mon, 18 Jul 2011 20:14:06 -0500 Subject: [PATCH] Updating documentation for some utils/ policy scripts --- policy/utils/addrs.bro | 16 ++++---- policy/utils/conn_ids.bro | 10 +++-- policy/utils/directions-and-hosts.bro | 38 +++++++++++++++++-- .../btest/Baseline/policy.utils.addrs/output | 11 ++++++ testing/btest/policy/utils/addrs.test | 5 +++ 5 files changed, 66 insertions(+), 14 deletions(-) diff --git a/policy/utils/addrs.bro b/policy/utils/addrs.bro index e9ad403991..415b9adfa9 100644 --- a/policy/utils/addrs.bro +++ b/policy/utils/addrs.bro @@ -27,8 +27,9 @@ const ip_addr_regex = /(([0-9A-Fa-f]{1,4}:){6,6})([0-9]+)\.([0-9]+)\.([0-9]+)\.([0-9]+)/ | # 6Hex4Dec /(([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 -## Takes an array of strings and returns T if all elements in are a valid -## value for an octet (0-255), else returns F +## 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 { local num = 0; @@ -41,8 +42,9 @@ function has_valid_octets(octets: string_array): bool return T; } -## Takes a string and returns T or F if the string appears to be a full and -## valid IP address. +## 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 { local octets: string_array; @@ -81,9 +83,9 @@ function is_valid_ip(ip_str: string): bool return F; } -## This outputs a string_array of ip addresses extracted from a string. -## given: "this is 1.1.1.1 a test 2.2.2.2 string with ip addresses 3.3.3.3" -## outputs: { [0] = 1.1.1.1, [1] = 2.2.2.2, [2] = 3.3.3.3 } +## 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. function find_ip_addresses(input: string): string_array { local parts = split_all(input, ip_addr_regex); diff --git a/policy/utils/conn_ids.bro b/policy/utils/conn_ids.bro index 9ac8c1b473..3a10263a95 100644 --- a/policy/utils/conn_ids.bro +++ b/policy/utils/conn_ids.bro @@ -4,15 +4,17 @@ module GLOBAL; export { ## Takes a conn_id record and returns a string representation with the - ## the general data flow appearing to be toward the right. + ## the 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 toward the left. + ## the 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 either the :bro:id:`id_string` or :bro:id:`reverse_id_string` - ## function depending on the second argument. + ## 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; } diff --git a/policy/utils/directions-and-hosts.bro b/policy/utils/directions-and-hosts.bro index cf69ee682d..6d27d5e26b 100644 --- a/policy/utils/directions-and-hosts.bro +++ b/policy/utils/directions-and-hosts.bro @@ -1,6 +1,24 @@ @load site -type Direction: enum { INBOUND, OUTBOUND, BIDIRECTIONAL, NO_DIRECTION }; +type Direction: enum { + ## 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. + OUTBOUND, + ## Only one endpoint is within the locally-monitored network, meaning + ## the connection is either outbound or inbound. + BIDIRECTIONAL, + ## This value doesn't match any connection. + NO_DIRECTION +}; + +## 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 +## Returns: T if the two connection endpoints match the given direction, else F. function id_matches_direction(id: conn_id, d: Direction): bool { if ( d == NO_DIRECTION ) return F; @@ -15,8 +33,22 @@ function id_matches_direction(id: conn_id, d: Direction): bool else if ( d == INBOUND ) return !o_local && r_local; } - -type Host: enum { LOCAL_HOSTS, REMOTE_HOSTS, ALL_HOSTS, NO_HOSTS }; + +type Host: enum { + ## A host within the locally-monitored network. + LOCAL_HOSTS, + ## A host not within the locally-monitored network. + REMOTE_HOSTS, + ## Any host. + ALL_HOSTS, + ## This value doesn't match any host. + NO_HOSTS +}; + +## Checks whether a given host (IP address) matches a given 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 { if ( h == NO_HOSTS ) return F; diff --git a/testing/btest/Baseline/policy.utils.addrs/output b/testing/btest/Baseline/policy.utils.addrs/output index 1fd98b968d..d93268a565 100644 --- a/testing/btest/Baseline/policy.utils.addrs/output +++ b/testing/btest/Baseline/policy.utils.addrs/output @@ -30,3 +30,14 @@ T F F F +============ test find_ip_addresses() +{ +[0] = 1.1.1.1, +[2] = 3.3.3.3, +[1] = 2.2.2.2 +} +{ +[0] = 1.1.1.1, +[2] = 3.3.3.3, +[1] = 0:0:0:0:0:0:0:0 +} diff --git a/testing/btest/policy/utils/addrs.test b/testing/btest/policy/utils/addrs.test index 4c3701eb7b..b15d42fb5f 100644 --- a/testing/btest/policy/utils/addrs.test +++ b/testing/btest/policy/utils/addrs.test @@ -96,4 +96,9 @@ event bro_init() # hybrid format's ipv4 part should test that all octet's are 0-255 ip = "2001:db8:0:0:0:FFFF:192.168.0.256"; print is_valid_ip(ip); + + print "============ test find_ip_addresses()"; + print find_ip_addresses("this is 1.1.1.1 a test 2.2.2.2 string with ip addresses 3.3.3.3"); + print find_ip_addresses("this is 1.1.1.1 a test 0:0:0:0:0:0:0:0 string with ip addresses 3.3.3.3"); + }