ronin-support 1.0.5 → 1.1.0.rc1

data/lib/ronin/support/network/ip_range/cidr.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2006-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # ronin-support is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published
@@ -31,7 +31,6 @@ module Ronin
         #     cidr.each { |ip puts }
         #     # 10.0.0.0
         #     # 10.0.0.1
-        #     # 10.0.0.2
         #     # ...
         #     # 10.0.0.254
         #     # 10.0.0.255
@@ -44,6 +43,49 @@ module Ronin
 
           include Enumerable
 
+          ipv4_octet = /(?:\d{1,2}|1\d{2}|2[1-4]\d|25[0-5])/
+          ipv4_addr  = /#{ipv4_octet}(?:\.#{ipv4_octet}){3}/
+
+          # Regular expression that matches IPv4 CIDR ranges.
+          #
+          # @api private
+          #
+          # @since 1.1.0
+          IPV4_REGEX = %r{\A#{ipv4_addr}(?:/(?:\d|[12]\d|3[0-2]))?\z}
+
+          # Regular expression that matches IPv6 CIDR ranges.
+          #
+          # @api private
+          #
+          # @since 1.1.0
+          IPV6_REGEX = %r{\A(?:
+            (?:[0-9a-fA-F]{1,4}:){6}#{ipv4_addr}|
+            (?:[0-9a-fA-F]{1,4}:){5}[0-9a-fA-F]{1,4}:#{ipv4_addr}|
+            (?:[0-9a-fA-F]{1,4}:){5}:[0-9a-fA-F]{1,4}:#{ipv4_addr}|
+            (?:[0-9a-fA-F]{1,4}:){1,1}(?::[0-9a-fA-F]{1,4}){1,4}:#{ipv4_addr}|
+            (?:[0-9a-fA-F]{1,4}:){1,2}(?::[0-9a-fA-F]{1,4}){1,3}:#{ipv4_addr}|
+            (?:[0-9a-fA-F]{1,4}:){1,3}(?::[0-9a-fA-F]{1,4}){1,2}:#{ipv4_addr}|
+            (?:[0-9a-fA-F]{1,4}:){1,4}(?::[0-9a-fA-F]{1,4}){1,1}:#{ipv4_addr}|
+            :(?::[0-9a-fA-F]{1,4}){1,5}:#{ipv4_addr}|
+            (?:(?:[0-9a-fA-F]{1,4}:){1,5}|:):#{ipv4_addr}|
+            (?:[0-9a-fA-F]{1,4}:){1,1}(?::[0-9a-fA-F]{1,4}){1,6}|
+            (?:[0-9a-fA-F]{1,4}:){1,2}(?::[0-9a-fA-F]{1,4}){1,5}|
+            (?:[0-9a-fA-F]{1,4}:){1,3}(?::[0-9a-fA-F]{1,4}){1,4}|
+            (?:[0-9a-fA-F]{1,4}:){1,4}(?::[0-9a-fA-F]{1,4}){1,3}|
+            (?:[0-9a-fA-F]{1,4}:){1,5}(?::[0-9a-fA-F]{1,4}){1,2}|
+            (?:[0-9a-fA-F]{1,4}:){1,6}(?::[0-9a-fA-F]{1,4}){1,1}|
+            [0-9a-fA-F]{1,4}(?::[0-9a-fA-F]{1,4}){7}|
+            :(?::[0-9a-fA-F]{1,4}){1,7}|
+            (?:(?:[0-9a-fA-F]{1,4}:){1,7}|:):
+          )(?:/(?:\d{1,2}|1[0-1]\d+|12[0-8]))?\z}x
+
+          # Regular expression to match IP-glob ranges.
+          #
+          # @api private
+          #
+          # @since 1.1.0
+          REGEX = /#{IPV4_REGEX}|#{IPV6_REGEX}/
+
           # The CIDR IP range string.
           #
           # @return [String]
@@ -59,12 +101,21 @@ module Ronin
           #   The address family for the CIDR range. This is mainly for
           #   backwards compatibility with `IPAddr#initialize`.
           #
+          # @raise [ArgumentError]
+          #   The CIDR range string was not a valid IPv4 or IPv6 CIDR range.
+          #
           def initialize(string,family=Socket::AF_UNSPEC)
+            unless (string =~ IPV4_REGEX || string =~ IPV6_REGEX)
+              raise(ArgumentError,"invalid CIDR range: #{string.inspect}")
+            end
+
             super(string,family)
 
             @string = string
           end
 
+          alias prefix_address to_string
+
           #
           # Alias for {#initialize new}.
           #
@@ -151,8 +202,8 @@ module Ronin
           #
           # @example
           #   IPRange::CIDR.each('10.0.0.1/24') { |ip| puts ip }
+          #   # 10.0.0.0
           #   # 10.0.0.1
-          #   # 10.0.0.2
           #   # ...
           #   # 10.0.0.254
           #   # 10.0.0.255
@@ -161,6 +212,65 @@ module Ronin
             new(string).each(&block)
           end
 
+          #
+          # Determines if the given IP belongs to the IP CIDR range.
+          #
+          # @param [IP, IPAddr, String] ip
+          #   The IP to test.
+          #
+          # @return [Boolean]
+          #   Specifies whether the IP is or is not within the IP CIDR range.
+          #
+          # @since 1.1.0
+          #
+          def include?(ip)
+            ip = IPAddr.new(ip) unless ip.kind_of?(IPAddr)
+
+            family_mask = MASKS[@family]
+            start_addr  = @addr
+            end_addr    = @addr | (~@mask_addr & family_mask)
+            ip_addr     = ip.to_i
+
+            return (ip_addr >= start_addr) && (ip_addr <= end_addr)
+          end
+
+          #
+          # Compares the CIDR range to another IP range.
+          #
+          # @param [Object] other
+          #   The other IP range.
+          #
+          # @return [Boolean]
+          #
+          # @since 1.1.0
+          #
+          def ==(other)
+            other.kind_of?(self.class) &&
+              family == other.family &&
+              to_i   == other.to_i
+          end
+
+          #
+          # Determines if the given IP range is a sub-set of the IP CIDR range.
+          #
+          # @param [CIDR, Glob, Enumerable<String>] other
+          #   The other IP range.
+          #
+          # @return [Boolean]
+          #
+          # @since 1.1.0
+          #
+          def ===(other)
+            case other
+            when CIDR
+              include?(other.first) && include?(other.last)
+            when Enumerable
+              other.all? { |ip| include?(ip) }
+            else
+              false
+            end
+          end
+
           #
           # Iterates over each IP address that is included in the addresses
           # netmask. Supports both IPv4 and IPv6 addresses.
@@ -174,17 +284,14 @@ module Ronin
           #
           # @return [self]
           #
-          # @note
-          #   This method will skip IPv4 addresses ending in `.0` or `.255`.
-          #
           # @example
           #   cidr = IPAddr.new('10.1.1.1/24')
           #   cidr.each { |ip| puts ip }
+          #   # 10.0.0.0
           #   # 10.0.0.1
-          #   # 10.0.0.2
           #   # ...
-          #   # 10.0.0.253
           #   # 10.0.0.254
+          #   # 10.0.0.255
           #
           def each
             return enum_for(__method__) unless block_given?
@@ -192,14 +299,7 @@ module Ronin
             family_mask = MASKS[@family]
 
             (0..((~@mask_addr) & family_mask)).each do |i|
-              ip_uint = (@addr | i)
-
-              # skip IPv4 addresses ending in .0 or .255
-              if (ipv4? && ((ip_uint & 0xff) == 0 || (ip_uint & 0xff) == 0xff))
-                next
-              end
-
-              yield _to_string(ip_uint)
+              yield _to_string(@addr | i)
             end
 
             return self
@@ -223,6 +323,17 @@ module Ronin
             _to_string(@addr | ~@mask_addr)
           end
 
+          #
+          # Calculates the size of the CIDR range.
+          #
+          # @return [Integer]
+          #
+          # @since 1.1.0
+          #
+          def size
+            2**(SIZES.fetch(family) - prefix)
+          end
+
           #
           # Converts the CIDR range back into a String.
           #

data/lib/ronin/support/network/ip_range/glob.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2006-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # ronin-support is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published
@@ -29,23 +29,23 @@ module Ronin
         #
         #     ip_range = IPRange::Glob.new('10.0.1-3.*/24')
         #     ip_range.each { |ip| puts ip }
+        #     # 10.0.1.0
         #     # 10.0.1.1
-        #     # 10.0.1.2
         #     # ...
-        #     # 10.0.1.253
         #     # 10.0.1.254
+        #     # 10.0.1.255
         #     # ...
+        #     # 10.0.2.0
         #     # 10.0.2.1
-        #     # 10.0.2.2
         #     # ...
-        #     # 10.0.2.253
         #     # 10.0.2.254
+        #     # 10.0.2.255
         #     # ...
+        #     # 10.0.3.0
         #     # 10.0.3.1
-        #     # 10.0.3.2
         #     # ...
-        #     # 10.0.3.253
         #     # 10.0.3.254
+        #     # 10.0.3.255
         #
         # @api public
         #
@@ -55,6 +55,55 @@ module Ronin
 
           include Enumerable
 
+          ipv4_octet       = /(?:\d{1,2}|1\d{2}|2[1-4]\d|25[0-5])/
+          ipv4_octet_range = /#{ipv4_octet}(?:-#{ipv4_octet})?/
+          ipv4_octet_list  = /(?:#{ipv4_octet_range}(?:,#{ipv4_octet_range})*|\*)/
+          ipv4_addr        = /#{ipv4_octet_list}(?:\.#{ipv4_octet_list}){3}/
+
+          # Regular expression that matches IPv4-glob ranges.
+          #
+          # @api private
+          #
+          # @since 1.1.0
+          IPV4_REGEX = /\A#{ipv4_addr}\z/
+
+          ipv6_octet       = /[0-9a-fA-F]{1,4}/
+          ipv6_octet_range = /#{ipv6_octet}(?:-#{ipv6_octet})?/
+          ipv6_octet_list  = /(?:#{ipv6_octet_range}(?:,#{ipv6_octet_range})*|\*)/
+
+          # Regular expression that matches IPv6-glob ranges.
+          #
+          # @api private
+          #
+          # @since 1.1.0
+          IPV6_REGEX = /\A(?:
+            (?:#{ipv6_octet_list}:){6}#{ipv4_addr}|
+            (?:#{ipv6_octet_list}:){5}#{ipv6_octet_list}:#{ipv4_addr}|
+            (?:#{ipv6_octet_list}:){5}:#{ipv6_octet_list}:#{ipv4_addr}|
+            (?:#{ipv6_octet_list}:){1,1}(?::#{ipv6_octet_list}){1,4}:#{ipv4_addr}|
+            (?:#{ipv6_octet_list}:){1,2}(?::#{ipv6_octet_list}){1,3}:#{ipv4_addr}|
+            (?:#{ipv6_octet_list}:){1,3}(?::#{ipv6_octet_list}){1,2}:#{ipv4_addr}|
+            (?:#{ipv6_octet_list}:){1,4}(?::#{ipv6_octet_list}){1,1}:#{ipv4_addr}|
+            :(?::#{ipv6_octet_list}){1,5}:#{ipv4_addr}|
+            (?:(?:#{ipv6_octet_list}:){1,5}|:):#{ipv4_addr}|
+            (?:#{ipv6_octet_list}:){1,1}(?::#{ipv6_octet_list}){1,6}|
+            (?:#{ipv6_octet_list}:){1,2}(?::#{ipv6_octet_list}){1,5}|
+            (?:#{ipv6_octet_list}:){1,3}(?::#{ipv6_octet_list}){1,4}|
+            (?:#{ipv6_octet_list}:){1,4}(?::#{ipv6_octet_list}){1,3}|
+            (?:#{ipv6_octet_list}:){1,5}(?::#{ipv6_octet_list}){1,2}|
+            (?:#{ipv6_octet_list}:){1,6}(?::#{ipv6_octet_list}){1,1}|
+            #{ipv6_octet_list}(?::#{ipv6_octet_list}){7}|
+            :(?::#{ipv6_octet_list}){1,7}|
+            (?:(?:#{ipv6_octet_list}:){1,7}|:):
+          )\z/x
+
+          # Regular expression to match IP-glob ranges.
+          #
+          # @api private
+          #
+          # @since 1.1.0
+          REGEX = /#{IPV4_REGEX}|#{IPV6_REGEX}/
+
           # The IP glob string.
           #
           # @return [String]
@@ -66,27 +115,36 @@ module Ronin
           # @param [String] string
           #   The IP-glob string to parse.
           #
+          # @raise [ArgumentError]
+          #   The IP-glob string was neither a valid IPv4 or IPv6 glob address.
+          #
           def initialize(string)
             @string = string
 
-            if @string.include?(':') # IPv6
-              @version   = 6
-              @separator = ':'
-              @base      = 16
-              @formatter = method(:format_ipv6_address)
-            else # IPv4
+            case string
+            when IPV4_REGEX
               @version   = 4
-              @separator = '.'
               @base      = 10
               @formatter = method(:format_ipv4_address)
+
+              separator   = '.'
+              octet_range = (0..255)
+            when IPV6_REGEX
+              @version   = 6
+              @base      = 16
+              @formatter = method(:format_ipv6_address)
+
+              separator   = ':'
+              octet_range = (0..0xffff)
+            else
+              raise(ArgumentError,"invalid IP-glob range: #{string.inspect}")
             end
 
-            @ranges = @string.split(@separator).map do |segment|
-              case segment
-              when '*' then (1..254)
-              when /,/ then parse_list(segment)
-              when /-/ then parse_range(segment)
-              else          [segment]
+            @ranges = string.split(separator).map do |segment|
+              if    segment == '*'        then octet_range
+              elsif segment.include?(',') then parse_list(segment)
+              elsif segment.include?('-') then parse_range(segment)
+              else                             [segment]
               end
             end
           end
@@ -123,23 +181,23 @@ module Ronin
           #
           # @example Enumerate through a IPv4 glob range:
           #   IPRange::Glob.each('10.0.1-3.*') { |ip| puts ip }
+          #   # 10.0.1.0
           #   # 10.0.1.1
-          #   # 10.0.1.2
           #   # ...
-          #   # 10.0.1.253
           #   # 10.0.1.254
+          #   # 10.0.1.255
           #   # ...
+          #   # 10.0.2.0
           #   # 10.0.2.1
-          #   # 10.0.2.2
           #   # ...
-          #   # 10.0.2.253
           #   # 10.0.2.254
+          #   # 10.0.2.255
           #   # ...
+          #   # 10.0.3.0
           #   # 10.0.3.1
-          #   # 10.0.3.2
           #   # ...
-          #   # 10.0.3.253
           #   # 10.0.3.254
+          #   # 10.0.3.255
           #
           # @example Enumerate through a globbed IPv6 range:
           #   IPRange::Glob.each('::ff::02-0a::c3') { |ip| puts ip }
@@ -166,6 +224,54 @@ module Ronin
             @version == 6
           end
 
+          #
+          # Determines whether the IP address exists within the IP range.
+          #
+          # @param [IP, IPAddr, String] ip
+          #   The IP address to check.
+          #
+          # @return [Boolean]
+          #   Indicates whether the IP address exists within the IP range.
+          #
+          # @since 1.1.0
+          #
+          def include?(ip)
+            super(ip.to_s)
+          end
+
+          #
+          # Compares the IP glob range to another IP range.
+          #
+          # @param [Object] other
+          #   The other IP range.
+          #
+          # @return [Boolean]
+          #
+          # @since 1.1.0
+          #
+          def ==(other)
+            other.kind_of?(self.class) && @string == other.string
+          end
+
+          #
+          # Determines if the given IP range is a sub-set of the IP CIDR range.
+          #
+          # @param [Glob, CIDR, Enumerable<String>] other
+          #   The other IP range.
+          #
+          # @return [Boolean]
+          #
+          # @since 1.1.0
+          #
+          def ===(other)
+            case other
+            when Enumerable
+              other.all? { |ip| include?(ip) }
+            else
+              false
+            end
+          end
+
           #
           # Enumerates over the IP-glob range.
           #
@@ -181,23 +287,23 @@ module Ronin
           # @example Enumerate through a IPv4 glob range:
           #   ip_range = IPRange::Glob.new('10.0.1-3.*')
           #   ip_range.each { |ip| puts ip }
+          #   # 10.0.1.0
           #   # 10.0.1.1
-          #   # 10.0.1.2
           #   # ...
-          #   # 10.0.1.253
           #   # 10.0.1.254
+          #   # 10.0.1.255
           #   # ...
+          #   # 10.0.2.0
           #   # 10.0.2.1
-          #   # 10.0.2.2
           #   # ...
-          #   # 10.0.2.253
           #   # 10.0.2.254
+          #   # 10.0.2.255
           #   # ...
+          #   # 10.0.3.0
           #   # 10.0.3.1
-          #   # 10.0.3.2
           #   # ...
-          #   # 10.0.3.253
           #   # 10.0.3.254
+          #   # 10.0.3.255
           #
           # @example Enumerate through a globbed IPv6 range:
           #   ip_range = IPRange::Glob.new('::ff::02-0a::c3')
@@ -214,6 +320,43 @@ module Ronin
             return self
           end
 
+          #
+          # The first address in the IP glob range.
+          #
+          # @return [String]
+          #   The first IP address in the IP glob range.
+          #
+          # @since 1.1.0
+          #
+          def first
+            @formatter.call(@ranges.map(&:first))
+          end
+
+          #
+          # The last address in the IP glob range.
+          #
+          # @return [String]
+          #   The last IP address in the IP glob range.
+          #
+          # @since 1.1.0
+          #
+          def last
+            @formatter.call(@ranges.map(&:last))
+          end
+
+          #
+          # Calculates the size of the IP glob range.
+          #
+          # @return [Integer]
+          #
+          # @since 1.1.0
+          #
+          def size
+            @ranges.reduce(1) do |total,parts|
+              total * parts.size
+            end
+          end
+
           #
           # Converts the IP-glob range back into a String.
           #

data/lib/ronin/support/network/ip_range/range.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2006-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # ronin-support is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published
@@ -145,7 +145,7 @@ module Ronin
           #
           # Determines if the given IP belongs to the ASN IP range.
           #
-          # @param [IPAddr, String] ip
+          # @param [IP, IPAddr, String] ip
           #   The IP to test.
           #
           # @return [Boolean]
@@ -171,26 +171,14 @@ module Ronin
           # @return [Enumerator]
           #   If no block is given, an Enumerator will be returned.
           #
-          # @note
-          #   This method will skip IPv4 addresses ending in `.0` or `.255`.
-          #
           # @example
-          #   range = IPRange::Range.new('1.1.1.0','1.1.1.255')
+          #   range = IPRange::Range.new('1.1.1.1','1.1.3.42')
           #   range.each { |ip| puts ip }
           #   # 1.1.1.1
           #   # 1.1.1.2
           #   # ...
-          #   # 1.1.1.253
-          #   # 1.1.1.254
-          #
-          # @example
-          #   range IPRange::Range.new('1.1.1.100','1.1.3.200')
-          #   range.each { |ip| puts ip }
-          #   # 1.1.1.100
-          #   # 1.1.1.101
-          #   # ...
-          #   # 1.1.3.199
-          #   # 1.1.3.200
+          #   # 1.1.3.41
+          #   # 1.1.3.42
           #
           def each
             return enum_for(__method__) unless block_given?
@@ -198,11 +186,6 @@ module Ronin
             ipaddr = @begin.clone
 
             (@begin_uint..@end_uint).each do |ip_uint|
-              # skip IPv4 addresses ending in .0 or .255
-              if (ipv4? && ((ip_uint & 0xff) == 0 || (ip_uint & 0xff) == 0xff))
-                next
-              end
-
               ipaddr.send(:set,ip_uint)
               yield ipaddr.to_s
             end
@@ -224,6 +207,38 @@ module Ronin
               self.end   == other.end
           end
 
+          #
+          # Determines if the given IP range is a sub-set of the IP range.
+          #
+          # @param [IPRange::Range, CIDR, Glob, Enumerable<String>] other
+          #   The other IP range.
+          #
+          # @return [Boolean]
+          #
+          # @since 1.1.0
+          #
+          def ===(other)
+            case other
+            when IPRange::Range
+              self.begin <= other.begin && self.end >= other.end
+            when Enumerable
+              other.all? { |ip| include?(ip) }
+            else
+              false
+            end
+          end
+
+          #
+          # Calculates the size of the IP range.
+          #
+          # @return [Integer]
+          #
+          # @since 1.1.0
+          #
+          def size
+            (@end_uint - @begin_uint) + 1
+          end
+
           #
           # Converts the IP range to a String.
           #