Updating documentation for some utils/ policy scripts

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);

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;
 }
 

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;

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
+}

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");
+
 	}