ruby-masscan 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd5ccf856ca875649425af00ffe4f90092cc81e250b30a54c640acd575504387
-  data.tar.gz: b1f064fe48e81cee639f7a32d8e0b77334593ba757ff30d8f554c2fb3a4860bf
+  metadata.gz: 5c7131e7fffe842982596ea49bdc4caafdcab24c9a2b1bd1dcc0b1372ca710ef
+  data.tar.gz: 50a2a06aca667ba92b82366f904420f6d42e30d05259ebab46a372ca7b4f4618
 SHA512:
-  metadata.gz: ec9bc404c40601950b44f6414af17809cf42132b2ee8e83e26268ede21ee297f33f9ae843f9aacc650861d0ffeba3bfe75268293d56b488aebbd1d2b476b8154
-  data.tar.gz: '06797c919c865cbe5147cdb79412883a174ca3835f72706881f1f99b58becf65836a200be6afd1b9e85f5efeac4f19e98e5aaf9ca4a08811afbdbcc200f2df86'
+  metadata.gz: f7c91b8b36dcd52defb23ee391cc4f3f6a04fe47cb9d5495f8a737f10210e32b1c5929cbd6da138f617b3f0eb27727285eaec1dcd05cb245d7c95f3cbd97589d
+  data.tar.gz: a714178ff916f8c469df962a3cf6aa8905c537de2f9c39d0a71fda4487ba820f6862357a1c0028e93966e8c6276e5c796b07399eee0dd87d262d33aabc589e1a

data/.github/workflows/ruby.yml

@@ -9,9 +9,10 @@ jobs:
       fail-fast: false
       matrix:
         ruby:
-          - 2.6
-          - 2.7
-          - 3.0
+          - '3.0'
+          - '3.1'
+          - '3.2'
+          - '3.3'
           - jruby
           - truffleruby
     name: Ruby ${{ matrix.ruby }}

data/ChangeLog.md

@@ -1,3 +1,18 @@
+### 0.3.0 / 2024-06-23
+
+* Include `Enumerable` into {Masscan::OutputFile}.
+* Improvements to {Masscan::Command}:
+  * Added the `rotate` attribute for the `--rotate` option.
+  * Allow the `ports` attribute to accept a raw String value.
+  * Improve validation of String values passed to `ports`, `adapter_port`,
+    `range`, `shards`, and `ips` attributes.
+  * Correct the type used for the `exclude` attribute.
+
+### 0.2.3 / 2024-01-27
+
+* Switched to using `require_relative` to improve load-times.
+* Added `# frozen_string_literal: true` to all files.
+
 ### 0.2.2 / 2023-04-20
 
 * Corrected option definitions:

data/lib/masscan/banner.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Masscan
   #
   # Represents a banner record.

data/lib/masscan/command.rb

@@ -1,5 +1,9 @@
+# frozen_string_literal: true
+
 require 'command_mapper/command'
 
+require 'ipaddr'
+
 module Masscan
   #
   # Provides an interface for invoking the `masscan` utility.
@@ -86,20 +90,98 @@ module Masscan
   #
   class Command < CommandMapper::Command
 
-    class PortList < CommandMapper::Types::Num
+    #
+    # Represents a port number.
+    #
+    # @api private
+    #
+    # @since 0.3.0
+    #
+    class Port < CommandMapper::Types::Num
+
+      # Regular expression that validates a port number.
+      PORT_REGEXP = /[1-9][0-9]{0,3}|[1-5][0-9][0-9][0-9][0-9]|6[0-4][0-9][0-9][0-9]|65[0-4][0-9][0-9]|655[0-2][0-9]|6553[0-5]/
+
+      # Regular expression that validates either a port number or service name.
+      REGEXP = /\A#{PORT_REGEXP}\z/
 
+      #
+      # Initializes the port type.
+      #
+      def initialize
+        super(range: 1..65535)
+      end
+
+      #
+      # Validates the given value.
+      #
+      # @param [Object] value
+      #   The value to validate.
+      #
+      # @return [true, (false, String)]
+      #   Returns true if the value is valid, or `false` and a validation error
+      #   message if the value is not compatible.
+      #
       def validate(value)
         case value
-        when Array
-          value.each do |element|
-            valid, message = validate(element)
-
-            unless valid
-              return [valid, message]
-            end
+        when String
+          unless value =~ REGEXP
+            return [false, "must be a valid port number (#{value.inspect})"]
           end
 
           return true
+        else
+          super(value)
+        end
+      end
+
+      #
+      # Formats the given port number.
+      #
+      # @param [Integer, String] value
+      #   The given port number.
+      #
+      # @return [String]
+      #   The formatted port number.
+      #
+      def format(value)
+        case value
+        when String
+          value
+        else
+          super(value)
+        end
+      end
+
+    end
+
+    #
+    # Represents a port range.
+    #
+    # @api private
+    #
+    # @since 0.3.0
+    #
+    class PortRange < Port
+
+      # Regular expression to validate either a port or a port range.
+      PORT_RANGE_REGEXP = /#{PORT_REGEXP}-#{PORT_REGEXP}|#{PORT_REGEXP}/
+
+      # Regular expression to validate either a port or a port range.
+      REGEXP = /\A#{PORT_RANGE_REGEXP}\z/
+
+      #
+      # Validates the given port or port range value.
+      #
+      # @param [Object] value
+      #   The port or port range value to validate.
+      #
+      # @return [true, (false, String)]
+      #   Returns true if the value is valid, or `false` and a validation error
+      #   message if the value is not compatible.
+      #
+      def validate(value)
+        case value
         when Range
           valid, message = super(value.begin)
 
@@ -113,16 +195,29 @@ module Masscan
             return [valid, message]
           end
 
+          return true
+        when String
+          unless value =~ REGEXP
+            return [false, "must be a valid port range or port number (#{value.inspect})"]
+          end
+
           return true
         else
           super(value)
         end
       end
 
+      #
+      # Formats the given port or port range value.
+      #
+      # @param [Range, Integer, String] value
+      #   The port or port range value to format.
+      #
+      # @return [String]
+      #   The formatted port or port range.
+      #
       def format(value)
         case value
-        when Array
-          value.map(&method(:format)).join(',')
         when Range
           "#{value.begin}-#{value.end}"
         else
@@ -132,21 +227,135 @@ module Masscan
 
     end
 
+    #
+    # Represents the type for the `-p,--ports` option.
+    #
+    # @api private
+    #
+    class PortList < CommandMapper::Types::List
+
+      # Regular expression for validating a port or port range.
+      PORT_RANGE_REGEXP = PortRange::PORT_RANGE_REGEXP
+
+      # Regular expression that validates port list String values.
+      REGEXP = /\A(?:(?:U:)?#{PORT_RANGE_REGEXP})(?:,(?:U:)?#{PORT_RANGE_REGEXP})*\z/
+
+      #
+      # Initializes the port list type.
+      #
+      def initialize
+        super(type: PortRange.new)
+      end
+
+      #
+      # Validates a given value.
+      #
+      # @param [Array, Range, String, Object] value
+      #   The port list value.
+      #
+      # @return [true, (false, String)]
+      #   Returns true if the value is valid, or `false` and a validation error
+      #   message if the value is not compatible.
+      #
+      def validate(value)
+        case value
+        when Range
+          @type.validate(value)
+        when String
+          unless value =~ REGEXP
+            return [false, "not a valid port list (#{value.inspect})"]
+          end
+
+          return true
+        else
+          super(value)
+        end
+      end
+
+      #
+      # Formats a port list value into a String.
+      #
+      # @param [Array<String, Integer, Range>, Range<Integer,Integer>, String, #to_s] value
+      #   The port list value to format.
+      #
+      # @return [String]
+      #   The formatted port list string.
+      #
+      def format(value)
+        case value
+        when Range
+          # format an individual port range
+          @type.format(value)
+        when String
+          # pass strings directly through
+          value
+        else
+          super(value)
+        end
+      end
+
+    end
+
+    #
+    # Represents the type for the `--shards` option.
+    #
+    # @api private
+    #
     class Shards < CommandMapper::Types::Str
 
+      # Regular expression for validating `--shards` values.
+      REGEXP = %r{\A\d+/\d+\z}
+
+      #
+      # Validates a shards value.
+      #
+      # @param [Array, Rational, String, #to_s] value
+      #   The shards value to validate.
+      #
+      # @return [true, (false, String)]
+      #   Returns true if the value is valid, or `false` and a validation error
+      #   message if the value is not compatible.
+      #
       def validate(value)
         case value
         when Array
-          if value.length > 2
-            return [false, "cannot contain more tha two elements (#{value.inspect})"]
+          unless value.length == 2
+            return [false, "must contain two elements (#{value.inspect})"]
+          end
+
+          unless (value[0].kind_of?(Integer) && value[1].kind_of?(Integer))
+            return [false, "shard values must be Integers (#{value.inspect})"]
           end
 
+          return true
+        when Rational
           return true
         else
-          super(value)
+          valid, message = super(value)
+
+          unless valid
+            return [valid, message]
+          end
+
+          string = value.to_s
+
+          unless string =~ REGEXP
+            return [false, "invalid shards value (#{value.inspect})"]
+          end
+
+          return true
         end
       end
 
+      #
+      # Formats a shards value into a String.
+      #
+      # @param [(Integer, Integer), Rational, #to_s] value
+      #   The shards value to format.
+      #
+      # @return [String]
+      #   The formatted shards value.
+      #
       def format(value)
         case value
         when Array
@@ -158,8 +367,166 @@ module Masscan
 
     end
 
+    #
+    # Represents the type for the `--rotate` option.
+    #
+    # @api private
+    #
+    # @since 0.3.0
+    #
+    class RotateTime < CommandMapper::Types::Str
+
+      # Regular expression to validate the `--rotate` time value.
+      REGEXP = /\A(?:\d+|hourly|\d+hours|\d+min)\z/
+
+      #
+      # Validates a `--rotate` time value.
+      #
+      # @param [Integer, String, #to_s] value
+      #   The time value to validate.
+      #
+      # @return [true, (false, String)]
+      #   Returns true if the value is valid, or `false` and a validation error
+      #   message if the value is not compatible.
+      #
+      def validate(value)
+        case value
+        when Integer
+          return true
+        else
+          valid, message = super(value)
+
+          unless valid
+            return [valid, message]
+          end
+
+          string = value.to_s
+
+          unless string =~ REGEXP
+            return [false, "invalid rotation time (#{value.inspect})"]
+          end
+
+          return true
+        end
+      end
+
+    end
+
+    #
+    # Represents the type for the `--adapter-mac` and `--router-mac` options.
+    #
+    # @api private
+    #
+    # @since 0.3.0
+    #
+    class MACAddress < CommandMapper::Types::Str
+
+      # Regular expression to validate a MAC address.
+      REGEXP = /\A[A-Fa-f0-9]{2}(?::[A-Fa-f0-9]{2}){5}\z/
+
+      #
+      # Validates a MAC address value.
+      #
+      # @param [String, #to_s] value
+      #   The MAC address value to validate.
+      #
+      # @return [true, (false, String)]
+      #   Returns true if the value is valid, or `false` and a validation error
+      #   message if the value is not compatible.
+      #
+      def validate(value)
+        valid, message = super(value)
+
+        unless valid
+          return [valid, message]
+        end
+
+        string = value.to_s
+
+        unless string =~ REGEXP
+          return [false, "invalid MAC address (#{value.inspect})"]
+        end
+
+        return true
+      end
+
+    end
+
+    #
+    # Represents the type for the `--range` option and `ips` argument(s).
+    #
+    # @api private
+    #
+    # @since 0.3.0
+    #
+    class Target < CommandMapper::Types::Str
+
+      # Regular expression for validating decimal octets (0-255).
+      DECIMAL_OCTET_REGEXP = /(?<=[^\d]|^)(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9][0-9]|[0-9])(?=[^\d]|$)/
+
+      # Regular expression for validating IPv4 addresses or CIDR ranges.
+      IPV4_REGEXP = %r{#{DECIMAL_OCTET_REGEXP}(?:\.#{DECIMAL_OCTET_REGEXP}){3}(?:/\d{1,2})?}
+
+      # Regular expression for validating IPv6 addresses or CIDR ranges.
+      IPV6_REGEXP = %r{
+       (?:[0-9a-f]{1,4}:){6}#{IPV4_REGEXP}|
+       (?:[0-9a-f]{1,4}:){5}[0-9a-f]{1,4}:#{IPV4_REGEXP}|
+       (?:[0-9a-f]{1,4}:){5}:[0-9a-f]{1,4}:#{IPV4_REGEXP}|
+       (?:[0-9a-f]{1,4}:){1,1}(?::[0-9a-f]{1,4}){1,4}:#{IPV4_REGEXP}|
+       (?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,3}:#{IPV4_REGEXP}|
+       (?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,2}:#{IPV4_REGEXP}|
+       (?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,1}:#{IPV4_REGEXP}|
+       :(?::[0-9a-f]{1,4}){1,5}:#{IPV4_REGEXP}|
+       (?:(?:[0-9a-f]{1,4}:){1,5}|:):#{IPV4_REGEXP}|
+       (?:[0-9a-f]{1,4}:){1,1}(?::[0-9a-f]{1,4}){1,6}(?:/\d{1,3})?|
+       (?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,5}(?:/\d{1,3})?|
+       (?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,4}(?:/\d{1,3})?|
+       (?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,3}(?:/\d{1,3})?|
+       (?:[0-9a-f]{1,4}:){1,5}(?::[0-9a-f]{1,4}){1,2}(?:/\d{1,3})?|
+       (?:[0-9a-f]{1,4}:){1,6}(?::[0-9a-f]{1,4}){1,1}(?:/\d{1,3})?|
+       [0-9a-f]{1,4}(?::[0-9a-f]{1,4}){7}(?:/\d{1,3})?|
+       :(?::[0-9a-f]{1,4}){1,7}(?:/\d{1,3})?|
+       (?:(?:[0-9a-f]{1,4}:){1,7}|:):(?:/\d{1,3})?
+      }x
+
+      # Regular expression for validating masscan target IPs or IP ranges.
+      REGEXP = /\A(?:#{IPV4_REGEXP}|#{IPV6_REGEXP})\z/
+
+      #
+      # Validates a IP or IP range target value.
+      #
+      # @param [IPAddr, String, #to_s] value
+      #   The IP or IP range value to validate.
+      #
+      # @return [true, (false, String)]
+      #   Returns true if the value is valid, or `false` and a validation error
+      #   message if the value is not compatible.
+      #
+      def validate(value)
+        case value
+        when IPAddr
+          return true
+        else
+          valid, message = super(value)
+
+          unless valid
+            return [valid, message]
+          end
+
+          string = value.to_s
+
+          unless string =~ REGEXP
+            return [false, "invalid IP or IP range (#{value.inspect})"]
+          end
+
+          return true
+        end
+      end
+
+    end
+
     command "masscan" do
-      option '--range', name: :range, value: true, repeats: true
+      option '--range', name: :range, value: {type: Target.new}, repeats: true
       option '-p', name: :ports, value: {type: PortList.new}
       option '--banners', name: :banners
       option '--rate',    name: :rate, value: {type: Num.new}
@@ -168,12 +535,12 @@ module Masscan
       option '--echo',    name: :echo, value: true
       option '--adapter', name: :adapter, value: true
       option '--adapter-ip',   name: :adapter_ip, value: true
-      option '--adapter-port', name: :adapter_port, value: {type: Num.new}
-      option '--adapter-mac',  name: :adapter_mac, value: true
+      option '--adapter-port', name: :adapter_port, value: {type: PortRange.new}
+      option '--adapter-mac',  name: :adapter_mac, value: {type: MACAddress.new}
       option '--adapter-vlan', name: :adapter_vlan, value: true
-      option '--router-mac', name: :router_mac, value: true
+      option '--router-mac', name: :router_mac, value: {type: MACAddress.new}
       option '--ping', name: :ping
-      option '--exclude', name: :exclude, value: true, repeats: true
+      option '--exclude', name: :exclude, value: {type: Target.new}, repeats: true
       option '--excludefile', name: :exclude_file, value: {type: InputFile.new}, repeats: true
       option '--includefile', name: :include_file, value: {type: InputFile.new}, repeats: true
       option '--append-output', name: :append_output
@@ -203,7 +570,7 @@ module Masscan
       option '--resume-index', name: :resume_index
       option '--resume-count', name: :resume_count
       option '--shards', name: :shards, value: {type: Shards.new}
-      option '--rotate', name: :rotate, value: true
+      option '--rotate', name: :rotate, value: {type: RotateTime.new}
       option '--rotate-offset', name: :rotate_offset, value: true
       option '--rotate-size',   name: :rotate_size, value: true
       option '--rotate-dir',    name: :rotate_dir, value: {type: InputDir.new}
@@ -233,7 +600,7 @@ module Masscan
       option '-V', name: :version
       option '-h', name: :help
 
-      argument :ips, repeats: true
+      argument :ips, repeats: true, type: Target.new
     end
 
   end

data/lib/masscan/output_file.rb

@@ -1,6 +1,8 @@
-require 'masscan/parsers/list'
-require 'masscan/parsers/json'
-require 'masscan/parsers/binary'
+# frozen_string_literal: true
+
+require_relative 'parsers/list'
+require_relative 'parsers/json'
+require_relative 'parsers/binary'
 
 module Masscan
   #
@@ -15,6 +17,8 @@ module Masscan
   #
   class OutputFile
 
+    include Enumerable
+
     # Mapping of formats to parsers.
     #
     # @api semipublic

data/lib/masscan/parsers/binary.rb

@@ -1,5 +1,7 @@
-require 'masscan/status'
-require 'masscan/banner'
+# frozen_string_literal: true
+
+require_relative '../status'
+require_relative '../banner'
 
 require 'socket'
 

data/lib/masscan/parsers/json.rb

@@ -1,6 +1,8 @@
-require 'masscan/parsers/plain_text'
-require 'masscan/status'
-require 'masscan/banner'
+# frozen_string_literal: true
+
+require_relative 'plain_text'
+require_relative '../status'
+require_relative '../banner'
 
 require 'json'
 

data/lib/masscan/parsers/list.rb

@@ -1,6 +1,8 @@
-require 'masscan/parsers/plain_text'
-require 'masscan/status'
-require 'masscan/banner'
+# frozen_string_literal: true
+
+require_relative 'plain_text'
+require_relative '../status'
+require_relative '../banner'
 
 module Masscan
   module Parsers

data/lib/masscan/parsers/plain_text.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Masscan
   module Parsers
     #

data/lib/masscan/parsers.rb

@@ -1,3 +1,5 @@
-require 'masscan/parsers/binary'
-require 'masscan/parsers/list'
-require 'masscan/parsers/json'
+# frozen_string_literal: true
+
+require_relative 'parsers/binary'
+require_relative 'parsers/list'
+require_relative 'parsers/json'

data/lib/masscan/program.rb

@@ -1,4 +1,6 @@
-require 'masscan/command'
+# frozen_string_literal: true
+
+require_relative 'command'
 
 module Masscan
   #

data/lib/masscan/status.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Masscan
   #
   # Represents a port status record.

data/lib/masscan/version.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
+
 module Masscan
   # ruby-masscan version
-  VERSION = '0.2.2'
+  VERSION = '0.3.0'
 end

data/lib/masscan.rb

@@ -1,3 +1,5 @@
-require 'masscan/command'
-require 'masscan/program'
-require 'masscan/output_file'
+# frozen_string_literal: true
+
+require_relative 'masscan/command'
+require_relative 'masscan/program'
+require_relative 'masscan/output_file'

data/ruby-masscan.gemspec

@@ -7,10 +7,7 @@ Gem::Specification.new do |gem|
 
   gem.name    = gemspec.fetch('name')
   gem.version = gemspec.fetch('version') do
-                  lib_dir = File.join(File.dirname(__FILE__),'lib')
-                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
-
-                  require 'masscan/version'
+                  require_relative 'lib/masscan/version'
                   Masscan::VERSION
                 end
 

data/spec/command_spec.rb

@@ -2,6 +2,164 @@ require 'spec_helper'
 require 'masscan/command'
 
 describe Masscan::Command do
+  describe described_class::Port do
+    describe "#validate" do
+      context "when given an Integer" do
+        let(:value) { 443 }
+
+        it "must return true" do
+          expect(subject.validate(value)).to be(true)
+        end
+
+        context "but it's less than 1" do
+          let(:value) { 0 }
+
+          it "must return [false, \"(...) not within the range of acceptable values (1..65535)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "(#{value.inspect}) not within the range of acceptable values (1..65535)"]
+            )
+          end
+        end
+
+        context "but it's greater than 65535" do
+          let(:value) { 65536 }
+
+          it "must return [false, \"(...) not within the range of acceptable values (1..65535)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "(#{value.inspect}) not within the range of acceptable values (1..65535)"]
+            )
+          end
+        end
+      end
+
+      context "when given a String" do
+        context "and it's a number" do
+          let(:value) { '443' }
+
+          it "must return true" do
+            expect(subject.validate(value)).to be(true)
+          end
+
+          context "but it's less than 1" do
+            let(:value) { '0' }
+
+            it "must return [false, \"must be a valid port number (...)\"]" do
+              expect(subject.validate(value)).to eq(
+                [false, "must be a valid port number (#{value.inspect})"]
+              )
+            end
+          end
+
+          context "but it's greater than 65535" do
+            let(:value) { '65536' }
+
+            it "must return [false, \"must be a valid port number (...)\"]" do
+              expect(subject.validate(value)).to eq(
+                [false, "must be a valid port number (#{value.inspect})"]
+              )
+            end
+          end
+        end
+
+        context "but it contains numbers" do
+          let(:value) { "foo" }
+
+          it "must return [false, \"must be a valid port number (...)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "must be a valid port number (#{value.inspect})"]
+            )
+          end
+        end
+      end
+    end
+  end
+
+  describe described_class::PortRange do
+    describe "#validate" do
+      context "when given an Integer value" do
+        let(:value) { 443 }
+
+        it "must return true" do
+          expect(subject.validate(value)).to be(true)
+        end
+
+        context "but it's less than 1" do
+          let(:value) { 0 }
+
+          it "must return [false, \"(...) not within the range of acceptable values (1..65535)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "(#{value.inspect}) not within the range of acceptable values (1..65535)"]
+            )
+          end
+        end
+
+        context "but it's greater than 65535" do
+          let(:value) { 65536 }
+
+          it "must return [false, \"(...) not within the range of acceptable values (1..65535)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "(#{value.inspect}) not within the range of acceptable values (1..65535)"]
+            )
+          end
+        end
+      end
+
+      context "when given a String value" do
+        let(:value) { '443' }
+
+        it "must return true" do
+          expect(subject.validate(value)).to be(true)
+        end
+
+        context "but it's less than 1" do
+          let(:value) { '0' }
+
+          it "must return [false, \"must be a valid port range or port number (...)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "must be a valid port range or port number (#{value.inspect})"]
+            )
+          end
+        end
+
+        context "but it's greater than 65535" do
+          let(:value) { '65536' }
+
+          it "must return [false, \"must be a valid port range or port number (...)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "must be a valid port range or port number (#{value.inspect})"]
+            )
+          end
+        end
+      end
+
+      context "when given a Range of port numbers" do
+        let(:value) { (1..1024) }
+
+        it "must return true" do
+          expect(subject.validate(value)).to be(true)
+        end
+      end
+    end
+
+    describe "#format" do
+      context "when given a single port number" do
+        let(:value) { 443 }
+
+        it "must return the formatted port number" do
+          expect(subject.format(value)).to eq(value.to_s)
+        end
+      end
+
+      context "when given a Range of port numbers" do
+        let(:value) { 1..1024 }
+
+        it "must return the formatted port number range (ex: 1-102)" do
+          expect(subject.format(value)).to eq("#{value.begin}-#{value.end}")
+        end
+      end
+    end
+  end
+
   describe described_class::PortList do
     describe "#validate" do
       context "when given a single port number" do
@@ -35,6 +193,118 @@ describe Masscan::Command do
           end
         end
       end
+
+      context "when given a String" do
+        context "and it contains a single number" do
+          let(:value) { "443" }
+
+          it "must return true" do
+            expect(subject.validate(value)).to be(true)
+          end
+
+          context "and it's prefixed by 'U:'" do
+            let(:value) { "U:#{super()}" }
+
+            it "must return true" do
+              expect(subject.validate(value)).to be(true)
+            end
+          end
+        end
+
+        context "and it contains a range of ports" do
+          let(:value) { "1-1024" }
+
+          it "must return true" do
+            expect(subject.validate(value)).to be(true)
+          end
+
+          context "and it's prefixed by 'U:'" do
+            let(:value) { "U:#{super()}" }
+
+            it "must return true" do
+              expect(subject.validate(value)).to be(true)
+            end
+          end
+        end
+
+        context "and it contains a comma separated list of port numbers" do
+          let(:value) { "80,443" }
+
+          it "must return true" do
+            expect(subject.validate(value)).to be(true)
+          end
+
+          context "and it's prefixed by 'U:'" do
+            let(:value) { "U:#{super()}" }
+
+            it "must return true" do
+              expect(subject.validate(value)).to be(true)
+            end
+          end
+        end
+
+        context "and it contains a comma separated list of port ranges" do
+          let(:value) { "1-42,80-8080" }
+
+          it "must return true" do
+            expect(subject.validate(value)).to be(true)
+          end
+
+          context "and it's prefixed by 'U:'" do
+            let(:value) { "U:#{super()}" }
+
+            it "must return true" do
+              expect(subject.validate(value)).to be(true)
+            end
+          end
+        end
+
+        context "and it contains a comma separated list of port numbers and ranges" do
+          let(:value) { "1-42,50,60,70,80-8080,9000" }
+
+          it "must return true" do
+            expect(subject.validate(value)).to be(true)
+          end
+
+          context "and it's prefixed by 'U:'" do
+            let(:value) { "U:#{super()}" }
+
+            it "must return true" do
+              expect(subject.validate(value)).to be(true)
+            end
+          end
+        end
+
+        context "when it contains non-digits" do
+          let(:value) { "1,2,3,4,a,b,c" }
+
+          it "must return false and a validation error message" do
+            expect(subject.validate(value)).to eq(
+              [false, "not a valid port list (#{value.inspect})"]
+            )
+          end
+        end
+
+        context "when it contains whitespace" do
+          let(:value) { "1,2, 3,4" }
+
+          it "must return false and a validation error message" do
+            expect(subject.validate(value)).to eq(
+              [false, "not a valid port list (#{value.inspect})"]
+            )
+          end
+        end
+
+        context "when it contains new-lines" do
+          let(:value) { "1,2,\n3,4" }
+
+          it "must return false and a validation error message" do
+            expect(subject.validate(value)).to eq(
+              [false, "not a valid port list (#{value.inspect})"]
+            )
+          end
+        end
+      end
     end
 
     describe "#format" do
@@ -69,6 +339,14 @@ describe Masscan::Command do
           end
         end
       end
+
+      context "when given a String" do
+        let(:value) { "22,25,80,443" }
+
+        it "must return the String" do
+          expect(subject.format(value)).to eq(value)
+        end
+      end
     end
   end
 
@@ -89,12 +367,42 @@ describe Masscan::Command do
           expect(subject.validate(value)).to be(true)
         end
 
+        context "but the Array length is 1" do
+          let(:value) { [1] }
+
+          it "must return a validation error" do
+            expect(subject.validate(value)).to eq(
+              [false, "must contain two elements (#{value.inspect})"]
+            )
+          end
+        end
+
         context "but the Array length is > 2" do
           let(:value) { [1,2,3] }
 
           it "must return a validation error" do
             expect(subject.validate(value)).to eq(
-              [false, "cannot contain more tha two elements (#{value.inspect})"]
+              [false, "must contain two elements (#{value.inspect})"]
+            )
+          end
+        end
+      end
+
+      context "when given a String" do
+        context "and it matches X/Y" do
+          let(:value) { "1/2" }
+
+          it "must return true" do
+            expect(subject.validate(value)).to be(true)
+          end
+        end
+
+        context "but it does not match X/Y" do
+          let(:value) { "1" }
+
+          it "must return a validation error" do
+            expect(subject.validate(value)).to eq(
+              [false, "invalid shards value (#{value.inspect})"]
             )
           end
         end
@@ -139,4 +447,256 @@ describe Masscan::Command do
       end
     end
   end
+
+  describe described_class::RotateTime do
+    describe "#validate" do
+      context "when given an Integer" do
+        let(:value) { 42 }
+
+        it "must return true" do
+          expect(subject.validate(value)).to be(true)
+        end
+      end
+
+      context "when given a String" do
+        context "but the String is a number" do
+          let(:value) { '42' }
+
+          it "must return true" do
+            expect(subject.validate(value)).to be(true)
+          end
+        end
+
+        context "but the String is 'hourly'" do
+          let(:value) { 'hourly' }
+
+          it "must return true" do
+            expect(subject.validate(value)).to be(true)
+          end
+        end
+
+        context "but the String is '<N>hours'" do
+          let(:value) { '2hours' }
+
+          it "must return true" do
+            expect(subject.validate(value)).to be(true)
+          end
+        end
+
+        context "but the String is '<N>min'" do
+          let(:value) { '10min' }
+
+          it "must return true" do
+            expect(subject.validate(value)).to be(true)
+          end
+        end
+
+        context "but the String is not a number" do
+          let(:value) { "abc" }
+
+          it "must return a validation error" do
+            expect(subject.validate(value)).to eq([false, "invalid rotation time (#{value.inspect})"])
+          end
+        end
+
+        context "but the String contains a new-line" do
+          let(:value) { "10\nfoo" }
+
+          it "must return a validation error" do
+            expect(subject.validate(value)).to eq([false, "invalid rotation time (#{value.inspect})"])
+          end
+        end
+      end
+    end
+  end
+
+  describe described_class::MACAddress do
+    describe "#validate" do
+      context "when given a String" do
+        context "and it's a valid MAC address" do
+          let(:value) { "00:11:22:33:44:55" }
+
+          it "must return true" do
+            expect(subject.validate(value)).to be(true)
+          end
+        end
+
+        context "but an octent contains less than two hex digits" do
+          let(:value) { "0:11:22:33:44" }
+
+          it "must return [false, \"invalid MAC address (...)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "invalid MAC address (#{value.inspect})"]
+            )
+          end
+        end
+
+        context "but an octent contains more than two hex digits" do
+          let(:value) { "000:11:22:33:44" }
+
+          it "must return [false, \"invalid MAC address (...)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "invalid MAC address (#{value.inspect})"]
+            )
+          end
+        end
+
+        context "but it's contains less than six octets" do
+          let(:value) { "00:11:22:33:44" }
+
+          it "must return [false, \"invalid MAC address (...)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "invalid MAC address (#{value.inspect})"]
+            )
+          end
+        end
+
+        context "but it's contains more than six octets" do
+          let(:value) { "00:11:22:33:44:55:66" }
+
+          it "must return [false, \"invalid MAC address (...)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "invalid MAC address (#{value.inspect})"]
+            )
+          end
+        end
+
+        context "but it contains non-hex characters" do
+          let(:value) { "000:11:22:33:44:xx" }
+
+          it "must return [false, \"invalid MAC address (...)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "invalid MAC address (#{value.inspect})"]
+            )
+          end
+        end
+
+        context "but it is not separated by ':' characters" do
+          let(:value) { "00.11.22.33.44.55" }
+
+          it "must return [false, \"invalid MAC address (...)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "invalid MAC address (#{value.inspect})"]
+            )
+          end
+        end
+
+        context "but it contains spaces" do
+          let(:value) { "00:11:22: 33:44:55" }
+
+          it "must return [false, \"invalid MAC address (...)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "invalid MAC address (#{value.inspect})"]
+            )
+          end
+        end
+
+        context "but it contains new-line characters" do
+          let(:value) { "00:11:22:\n33:44:55" }
+
+          it "must return [false, \"invalid MAC address (...)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "invalid MAC address (#{value.inspect})"]
+            )
+          end
+        end
+      end
+    end
+  end
+
+  describe described_class::Target do
+    describe "#validate" do
+      context "when given an IPAddr object" do
+        let(:value) { IPAddr.new('127.0.0.1') }
+
+        it "must return true" do
+          expect(subject.validate(value)).to be(true)
+        end
+      end
+
+      context "when given a String" do
+        context "and it's an IPv4 address" do
+          let(:value) { '127.0.0.1' }
+
+          it "must return true" do
+            expect(subject.validate(value)).to be(true)
+          end
+        end
+
+        context "and it's an IPv4 range" do
+          let(:value) { '127.0.0.1/24' }
+
+          it "must return true" do
+            expect(subject.validate(value)).to be(true)
+          end
+        end
+
+        context "and it's an IPv6 address" do
+          context "but it's in compressed notation" do
+            let(:value) { '::1' }
+
+            it "must return true" do
+              expect(subject.validate(value)).to be(true)
+            end
+          end
+
+          context "and it's in full notation" do
+            let(:value) { '2606:2800:220:1:248:1893:25c8:1946' }
+
+            it "must return true" do
+              expect(subject.validate(value)).to be(true)
+            end
+          end
+        end
+
+        context "and it's an IPv6 range" do
+          context "but it's in compressed notation" do
+            let(:value) { '::1/32' }
+
+            it "must return true" do
+              expect(subject.validate(value)).to be(true)
+            end
+          end
+
+          context "and it's in full notation" do
+            let(:value) { '2606:2800:220:1:248:1893:25c8:1946/32' }
+
+            it "must return true" do
+              expect(subject.validate(value)).to be(true)
+            end
+          end
+        end
+
+        context "but it contains non-hex characters" do
+          let(:value) { '2606:2800:220:1:248:1893:25c8:xxxx/32' }
+
+          it "must return [false, \"invalid IP or IP range (...)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "invalid IP or IP range (#{value.inspect})"]
+            )
+          end
+        end
+
+        context "but it contains spaces" do
+          let(:value) { '2606:2800:220:1: 248:1893:25c8:1946/32' }
+
+          it "must return [false, \"invalid IP or IP range (...)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "invalid IP or IP range (#{value.inspect})"]
+            )
+          end
+        end
+
+        context "but it contains new-line characters" do
+          let(:value) { "2606:2800:220:1:\n248:1893:25c8:1946/32" }
+
+          it "must return [false, \"invalid IP or IP range (...)\"]" do
+            expect(subject.validate(value)).to eq(
+              [false, "invalid IP or IP range (#{value.inspect})"]
+            )
+          end
+        end
+      end
+    end
+  end
 end

data/spec/output_file_spec.rb

@@ -2,6 +2,8 @@ require 'spec_helper'
 require 'masscan/output_file'
 
 describe Masscan::OutputFile do
+  it { expect(described_class).to include(Enumerable) }
+
   describe ".infer_format" do
     subject { described_class.infer_format(path) }
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-masscan
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Postmodern
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-20 00:00:00.000000000 Z
+date: 2024-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: command_mapper
@@ -111,7 +111,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - masscan >= 1.0.0
-rubygems_version: 3.3.26
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: A Ruby interface to masscan.