:tocdepth: 3

base/utils/addrs.bro
====================

Functions for parsing and manipulating IP and MAC addresses.

:Source File: :download:`/scripts/base/utils/addrs.bro`

Summary
~~~~~~~
Constants
#########
============================================================ =
:bro:id:`ip_addr_regex`: :bro:type:`pattern`                 
:bro:id:`ipv4_addr_regex`: :bro:type:`pattern`               
:bro:id:`ipv6_8hex_regex`: :bro:type:`pattern`               
:bro:id:`ipv6_addr_regex`: :bro:type:`pattern`               
:bro:id:`ipv6_compressed_hex4dec_regex`: :bro:type:`pattern` 
:bro:id:`ipv6_compressed_hex_regex`: :bro:type:`pattern`     
:bro:id:`ipv6_hex4dec_regex`: :bro:type:`pattern`            
============================================================ =

Functions
#########
================================================= =========================================================================
:bro:id:`addr_to_uri`: :bro:type:`function`       Returns the string representation of an IP address suitable for inclusion
                                                  in a URI.
:bro:id:`find_ip_addresses`: :bro:type:`function` Extracts all IP (v4 or v6) address strings from a given string.
:bro:id:`has_valid_octets`: :bro:type:`function`  Checks if all elements of a string array are a valid octet value.
:bro:id:`is_valid_ip`: :bro:type:`function`       Checks if a string appears to be a valid IPv4 or IPv6 address.
:bro:id:`normalize_mac`: :bro:type:`function`     Given a string, extracts the hex digits and returns a MAC address in
                                                  the format: 00:a0:32:d7:81:8f.
================================================= =========================================================================


Detailed Interface
~~~~~~~~~~~~~~~~~~
Constants
#########
.. bro:id:: ip_addr_regex

   :Type: :bro:type:`pattern`
   :Default:

   ::

      /((((^?([[:digit:]]{1,3}\.[[:digit:]]{1,3}\.[[:digit:]]{1,3}\.[[:digit:]]{1,3})$?)|(^?(([0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4})$?))|(^?((([0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4})*)?)::(([0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4})*)?))$?))|(^?((([0-9A-Fa-f]{1,4}:){6,6})([0-9]+)\.([0-9]+)\.([0-9]+)\.([0-9]+))$?))|(^?((([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]+))$?)/


.. bro:id:: ipv4_addr_regex

   :Type: :bro:type:`pattern`
   :Default:

   ::

      /^?([[:digit:]]{1,3}\.[[:digit:]]{1,3}\.[[:digit:]]{1,3}\.[[:digit:]]{1,3})$?/


.. bro:id:: ipv6_8hex_regex

   :Type: :bro:type:`pattern`
   :Default:

   ::

      /^?(([0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4})$?/


.. bro:id:: ipv6_addr_regex

   :Type: :bro:type:`pattern`
   :Default:

   ::

      /(((^?(([0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4})$?)|(^?((([0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4})*)?)::(([0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4})*)?))$?))|(^?((([0-9A-Fa-f]{1,4}:){6,6})([0-9]+)\.([0-9]+)\.([0-9]+)\.([0-9]+))$?))|(^?((([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]+))$?)/


.. bro:id:: ipv6_compressed_hex4dec_regex

   :Type: :bro:type:`pattern`
   :Default:

   ::

      /^?((([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]+))$?/


.. bro:id:: ipv6_compressed_hex_regex

   :Type: :bro:type:`pattern`
   :Default:

   ::

      /^?((([0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4})*)?)::(([0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4})*)?))$?/


.. bro:id:: ipv6_hex4dec_regex

   :Type: :bro:type:`pattern`
   :Default:

   ::

      /^?((([0-9A-Fa-f]{1,4}:){6,6})([0-9]+)\.([0-9]+)\.([0-9]+)\.([0-9]+))$?/


Functions
#########
.. bro:id:: addr_to_uri

   :Type: :bro:type:`function` (a: :bro:type:`addr`) : :bro:type:`string`

   Returns the string representation of an IP address suitable for inclusion
   in a URI.  For IPv4, this does no special formatting, but for IPv6, the
   address is included in square brackets.
   

   :a: the address to make suitable for URI inclusion.
   

   :returns: the string representation of the address suitable for URI inclusion.

.. bro:id:: find_ip_addresses

   :Type: :bro:type:`function` (input: :bro:type:`string`) : :bro:type:`string_array`

   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*.

.. bro:id:: has_valid_octets

   :Type: :bro:type:`function` (octets: :bro:type:`string_array`) : :bro:type:`bool`

   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.

.. bro:id:: is_valid_ip

   :Type: :bro:type:`function` (ip_str: :bro:type:`string`) : :bro:type:`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.

.. bro:id:: normalize_mac

   :Type: :bro:type:`function` (a: :bro:type:`string`) : :bro:type:`string`

   Given a string, extracts the hex digits and returns a MAC address in
   the format: 00:a0:32:d7:81:8f. If the string doesn't contain 12 or 16 hex
   digits, an empty string is returned.
   

   :a: the string to normalize.
   

   :returns: a normalized MAC address, or an empty string in the case of an error.


