ruby-masscan 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f03fa94f7c501646be712a24b98fe07a6dd156c054c7ae27714cac80b1fbb5e8
-  data.tar.gz: a346c7b055da689cad8571a38383b43a5e797889d6206b85ca7d2a64e25b904f
+  metadata.gz: 064d7200b60b80a1ed4f0459239235d21f96587a3199833988dd5953728cd168
+  data.tar.gz: 619757cb909fcec538c63ef5d37d2cb1f1029509d71e957be9aa6f74726ad4ea
 SHA512:
-  metadata.gz: ecdea1cc3b62cf1d0dbb2b7771807c05f2e6339b573f6208dcfb21e94fdaad160e51adc077e158ec6c4b4bc9426c7925dfd376d53d455922c5e318e6ee999936
-  data.tar.gz: 88bbf9a1332946ae7688fae852a1a3565269a853eff17434dc8e0b1fd7eae2c3e14b09cc64fa3fc80a06781f3fd644b97e5f97fcc52ccd2aa71cbc2a32b15f3c
+  metadata.gz: 9d9fa47ab80653e00c4d3f16b02e1cbe824575d0979b43596f7a52c703b9eda0616882e8bd7effdb77a3f9bfafe40b50043ace08a06f4725b59335dab724fee2
+  data.tar.gz: ad559b68f9af88c2c2e1b66711a93b3bceda9962cd0b3f1f478400a0f1dd7d79a7a87eab81eef4ff9c1cca426c135732d05437affb757fdc3d1ebcfc64b681b2

data/.github/workflows/ruby.yml

@@ -9,8 +9,6 @@ jobs:
       fail-fast: false
       matrix:
         ruby:
-          - 2.4
-          - 2.5
           - 2.6
           - 2.7
           - 3.0

data/ChangeLog.md

@@ -1,3 +1,16 @@
+### 0.2.1 / 2023-03-15
+
+* Unescape `\\xXX` hex escaped characters in payload strings parsed from `.list`
+  masscan files.
+
+### 0.2.0 / 2021-11-30
+
+* Replaced the `rprogram` dependency with [command_mapper].
+* Fixed a typo in the mapping of the `-oJ` option flag.
+* Added {Masscan::OutputFile#to_s}.
+
+[command_mapper]: https://github.com/postmodern/command_mapper.rb#readme
+
 ### 0.1.1 / 2021-09-09
 
 * Added missing {Masscan::Banner#ttl}.

data/Gemfile

@@ -2,14 +2,16 @@ source 'https://rubygems.org'
 
 gemspec
 
+# gem 'command_mapper', '~> 0.1', github: 'postmodern/command_mapper.rb'
+
 group :development do
   gem 'rake'
   gem 'rubygems-tasks', '~> 0.2'
   gem 'rspec',          '~> 3.0'
-
-  gem 'json'
   gem 'simplecov',      '~> 0.7'
+
   gem 'kramdown'
+  gem 'redcarpet',       platform: :mri
   gem 'yard',           '~> 0.9'
   gem 'yard-spellcheck', require: false
 end

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2021 Hal Brodigan
+Copyright (c) 2021-2023 Hal Brodigan
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -15,17 +15,22 @@ file formats.
 
 ## Features
 
-* Provides a Ruby interface for running the `masscan` command.
-* Supports parsing masscan Binary, List, and JSON output files.
+* Provides a [Ruby interface][Masscan::Command] for running the `masscan`
+  utility.
+* Supports [parsing][Masscan::OutputFile] masscan Binary, List, and JSON output
+  files.
+
+[Masscan::Command]: https://rubydoc.info/gems/ruby-masscan/Masscan/Command
+[Masscan::OutputFile]: https://rubydoc.info/gems/ruby-masscan/Masscan/OutputFile
 
 ## Examples
 
 Run `sudo masscan` from Ruby:
 
 ```ruby
-require 'masscan/program'
+require 'masscan/command'
 
-Masscan::Program.sudo_scan do |masscan|
+Masscan::Command.sudo do |masscan|
   masscan.output_format = :list
   masscan.output_file   = 'masscan.txt'
 
@@ -108,7 +113,7 @@ end
 
 * [ruby] >= 2.0.0
 * [masscan] >= 1.0.0
-* [rprogram] ~> 0.3
+* [command_mapper] ~> 0.1
 
 ## Install
 
@@ -119,21 +124,21 @@ $ gem install ruby-masscan
 ### gemspec
 
 ```ruby
-gemspec.add_dependency 'ruby-masscan', '~> 0.1'
+gemspec.add_dependency 'ruby-masscan', '~> 0.2'
 ```
 
 ### Gemfile
 
 ```ruby
-gem 'ruby-masscan', '~> 0.1'
+gem 'ruby-masscan', '~> 0.2'
 ```
 
 ## License
 
-Copyright (c) 2021 Hal Brodigan
+Copyright (c) 2021-2023 Hal Brodigan
 
 See {file:LICENSE.txt} for license information.
 
 [masscan]: https://github.com/robertdavidgraham/masscan#readme
 [ruby]: https://www.ruby-lang.org/
-[rprogram]: https://github.com/postmodern/rprogram#readme
+[command_mapper]: https://github.com/postmodern/command_mapper.rb#readme

data/gemspec.yml

@@ -16,13 +16,14 @@ metadata:
   source_code_uri:   https://github.com/postmodern/ruby-masscan
   bug_tracker_uri:   https://github.com/postmodern/ruby-masscan/issues
   changelog_uri:     https://github.com/postmodern/ruby-masscan/blob/master/ChangeLog.md
+  rubygems_mfa_required: 'true'
 
 required_ruby_version: ">= 2.0.0"
 
 requirements: masscan >= 1.0.0
 
 dependencies:
-  rprogram: ~> 0.3
+  command_mapper: ~> 0.1
 
 development_dependencies:
   bundler: ~> 2.0

data/lib/masscan/command.rb

@@ -0,0 +1,240 @@
+require 'command_mapper/command'
+
+module Masscan
+  #
+  # Provides an interface for invoking the `masscan` utility.
+  #
+  # ## Example
+  #
+  #     require 'masscan/command'
+  #     
+  #     Masscan::Command.sudo do |masscan|
+  #       masscan.output_format = :list
+  #       masscan.output_file   = 'masscan.txt'
+  #     
+  #       masscan.ips   = '192.168.1.1/24'
+  #       masscan.ports = [20,21,22,23,25,80,110,443,512,522,8080,1080]
+  #     end
+  #
+  # ## `masscan` options:
+  #
+  # * `--range` - `masscan.range`
+  # * `-p` - `masscan.ports`
+  # * `--banners` - `masscan.banners`
+  # * `--rate` - `masscan.rate`
+  # * `--conf` - `masscan.config_file`
+  # * `--resume` - `masscan.resume`
+  # * `--echo` - `masscan.echo`
+  # * `--adapter` - `masscan.adapter`
+  # * `--adapter-ip` - `masscan.adapter_ip`
+  # * `--adapter-port` - `masscan.adapter_port`
+  # * `--adapter-mac` - `masscan.adapter_mac`
+  # * `--adapter-vlan` - `masscan.adapter_vlan`
+  # * `--router-mac` - `masscan.router_mac`
+  # * `--ping` - `masscan.ping`
+  # * `--exclude` - `masscan.exclude`
+  # * `--excludefile` - `masscan.exclude_file`
+  # * `--includefile` - `masscan.include_file`
+  # * `--append-output` - `masscan.append_output`
+  # * `--iflist` - `masscan.list_interfaces`
+  # * `--retries` - `masscan.retries`
+  # * `--nmap` - `masscan.nmap_help`
+  # * `--pcap-payloads` - `masscan.pcap_payloads`
+  # * `--nmap-payloads` - `masscan.nmap_payloads`
+  # * `--http-method` - `masscan.http_method`
+  # * `--http-url` - `masscan.http_url`
+  # * `--http-version` - `masscan.http_version`
+  # * `--http-host` - `masscan.http_host`
+  # * `--http-user-agent` - `masscan.http_user_agent`
+  # * `--http-field` - `masscan.http_field`
+  # * `--http-field-remove` - `masscan.http_field_remove`
+  # * `--http-cookie` - `masscan.http_cookie`
+  # * `--http-payload` - `masscan.http_payload`
+  # * `--show` - `masscan.show`
+  # * `--noshow` - `masscan.hide`
+  # * `--pcap` - `masscan.pcap`
+  # * `--packet-trace` - `masscan.packet_trace`
+  # * `--pfring` - `masscan.pfring`
+  # * `--resume-index` - `masscan.resume_index`
+  # * `--resume-count` - `masscan.resume_count`
+  # * `--shards` - `masscan.shards`
+  # * `--rotate` - `masscan.rotate`
+  # * `--rotate-offset` - `masscan.rotate_offset`
+  # * `--rotate-size` - `masscan.rotate_size`
+  # * `--rotate-dir` - `masscan.rotate_dir`
+  # * `--seed` - `masscan.seed`
+  # * `--regress` - `masscan.regress`
+  # * `--ttl` - `masscan.ttl`
+  # * `--wait` - `masscan.wait`
+  # * `--offline` - `masscan.offline`
+  # * `-sL` - `masscan.print_list`
+  # * `--interactive` - `masscan.interactive`
+  # * `--output-format` - `masscan.output_format`
+  # * `--output-filename` - `masscan.output_file`
+  # * `-oB` - `masscan.output_binary`
+  # * `-oX` - `masscan.output_xml`
+  # * `-oG` - `masscan.output_grepable`
+  # * ` -oJ` - `masscan.output_json`
+  # * `-oL` - `masscan.output_list`
+  # * `--readscan` - `masscan.read_scan`
+  # * `-V` - `masscan.version`
+  # * `-h` - `masscan.help`
+  #
+  # @see https://github.com/robertdavidgraham/masscan/blob/master/doc/masscan.8.markdown
+  #
+  # @since 0.2.0
+  #
+  class Command < CommandMapper::Command
+
+    class PortList < CommandMapper::Types::Num
+
+      def validate(value)
+        case value
+        when Array
+          value.each do |element|
+            valid, message = validate(element)
+
+            unless valid
+              return [valid, message]
+            end
+          end
+
+          return true
+        when Range
+          valid, message = super(value.begin)
+
+          unless valid
+            return [valid, message]
+          end
+
+          valid, message = super(value.end)
+
+          unless valid
+            return [valid, message]
+          end
+
+          return true
+        else
+          super(value)
+        end
+      end
+
+      def format(value)
+        case value
+        when Array
+          value.map(&method(:format)).join(',')
+        when Range
+          "#{value.begin}-#{value.end}"
+        else
+          super(value)
+        end
+      end
+
+    end
+
+    class Shards < CommandMapper::Types::Str
+
+      def validate(value)
+        case value
+        when Array
+          if value.length > 2
+            return [false, "cannot contain more tha two elements (#{value.inspect})"]
+          end
+
+          return true
+        else
+          super(value)
+        end
+      end
+
+      def format(value)
+        case value
+        when Array
+          "#{value[0]}/#{value[1]}"
+        else
+          super(value)
+        end
+      end
+
+    end
+
+    command "masscan" do
+      option '--range', name: :range, value: {type: List.new}
+      option '-p', name: :ports, value: {type: PortList.new}
+      option '--banners', name: :banners
+      option '--rate',    name: :rate, value: {type: Num.new}
+      option '--conf',    name: :config_file, value: {type: InputFile.new}
+      option '--resume',  name: :resume, value: {type: InputFile.new}
+      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-vlan', name: :adapter_vlan, value: true
+      option '--router-mac', name: :router_mac, value: true
+      option '--ping', name: :ping
+      option '--exclude', name: :exclude, value: {type: List.new}
+      option '--excludefile', name: :exclude_file, value: {type: InputFile.new}
+      option '--includefile', name: :include_file, value: {type: InputFile.new}
+      option '--append-output', name: :append_output
+      option '--iflist', name: :list_interfaces
+      option '--retries', name: :retries
+      option '--nmap', name: :nmap_help
+      option '--pcap-payloads', name: :pcap_payloads
+      option '--nmap-payloads', name: :nmap_payloads, value: {type: InputFile.new}
+
+      option '--http-method',     name: :http_method, value: true
+      option '--http-url',        name: :http_url, value: true
+      option '--http-version',    name: :http_version, value: true
+      option '--http-host',       name: :http_host, value: true
+      option '--http-user-agent', name: :http_user_agent, value: true
+
+      option '--http-field', value: {type: KeyValue.new}, repeats: true
+
+      option '--http-field-remove', name: :http_field_remove
+      option '--http-cookie', name: :http_cookie
+      option '--http-payload', name: :http_payload
+
+      option '--show', name: :show
+      option '--noshow', name: :hide
+      option '--pcap', name: :pcap, value: true
+      option '--packet-trace', name: :packet_trace
+      option '--pfring', name: :pfring
+      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-offset', name: :rotate_offset, value: true
+      option '--rotate-size',   name: :rotate_size, value: true
+      option '--rotate-dir',    name: :rotate_dir, value: {type: InputDir.new}
+      option '--seed', name: :seed, value: {type: Num.new}
+      option '--regress', name: :regress
+      option '--ttl', name: :ttl, value: {type: Num.new}
+      option '--wait', name: :wait, value: {type: Num.new}
+      option '--offline', name: :offline
+      option '-sL', name: :print_list
+      option '--interactive', name: :interactive
+      option '--output-format', name: :output_format, value: {
+                                                        type: Enum[
+                                                          :xml,
+                                                          :binary,
+                                                          :grepable,
+                                                          :list,
+                                                          :JSON
+                                                        ]
+                                                      }
+      option '--output-filename', name: :output_file, value: true
+      option '-oB', name: :output_binary, value: true
+      option '-oX', name: :output_xml, value: true
+      option '-oG', name: :output_grepable, value: true
+      option '-oJ', name: :output_json, value: true
+      option '-oL', name: :output_list, value: true
+      option '--readscan', name: :read_scan, value: {type: InputFile.new}
+      option '-V', name: :version
+      option '-h', name: :help
+
+      argument :ips, repeats: true
+    end
+
+  end
+end

data/lib/masscan/output_file.rb

@@ -6,8 +6,18 @@ module Masscan
   #
   # Represents an output file.
   #
+  # ## Example
+  #
+  #     output_file = Masscan::OutputFile.new('masscan.json')
+  #     output_file.each do |record|
+  #       p record
+  #     end
+  #
   class OutputFile
 
+    # Mapping of formats to parsers.
+    #
+    # @api semipublic
     PARSERS = {
       binary: Parsers::Binary,
       list:   Parsers::List,
@@ -29,6 +39,8 @@ module Masscan
     # The parser for the output file format.
     #
     # @return [Parsers::Binary, Parsers::JSON, Parsers::List]
+    #
+    # @api private
     attr_reader :parser
 
     #
@@ -52,6 +64,22 @@ module Masscan
       end
     end
 
+    # Mapping of file extensions to formats
+    #
+    # @api semipublic
+    FILE_FORMATS = {
+      '.bin' => :binary,
+      '.dat' => :binary,
+
+      '.txt' => :list,
+      '.list' => :list,
+
+      '.json'   => :json,
+      '.ndjson' => :ndjson,
+
+      '.xml' => :xml
+    }
+
     #
     # Infers the format from the output file's extension name.
     #
@@ -64,14 +92,10 @@ module Masscan
     # @raise [ArgumentError]
     #   The output format could not be inferred from the file's name.
     #
+    # @api semipublic
+    #
     def self.infer_format(path)
-      case File.extname(path)
-      when '.bin', '.dat'     then :binary
-      when '.txt', '.list'    then :list
-      when '.json'            then :json
-      when '.ndjson'          then :ndjson
-      when '.xml'             then :xml
-      else
+      FILE_FORMATS.fetch(File.extname(path)) do
         raise(ArgumentError,"could not infer format of #{path}")
       end
     end
@@ -96,5 +120,17 @@ module Masscan
       end
     end
 
+    #
+    # Converts the output file to a String.
+    #
+    # @return [String]
+    #   The path to the output file.
+    #
+    # @since 0.2.0
+    #
+    def to_s
+      @path
+    end
+
   end
 end

data/lib/masscan/parsers/list.rb

@@ -64,7 +64,7 @@ module Masscan
               timestamp: parse_timestamp(timestamp)
             )
           elsif line.start_with?('banner ')
-            type, ip_proto, port, ip, timestamp, app_proto, banner = line.split(' ',7)
+            type, ip_proto, port, ip, timestamp, app_proto, payload = line.split(' ',7)
 
             yield Banner.new(
               protocol:     parse_ip_protocol(ip_proto),
@@ -72,11 +72,28 @@ module Masscan
               ip:           parse_ip(ip),
               timestamp:    parse_timestamp(timestamp),
               app_protocol: parse_app_protocol(app_proto),
-              payload:      banner
+              payload:      parse_payload(payload)
             )
           end
         end
       end
+
+      #
+      # Parses a payload string and removes any `\\xXX` hex escaped characters.
+      #
+      # @param [String] payload
+      #   The payload string to unescape.
+      #
+      # @return [String]
+      #   The raw payload string.
+      #
+      # @api private
+      #
+      def self.parse_payload(payload)
+        payload.gsub(/\\x[0-9a-f]{2}/) do |hex_escape|
+          hex_escape[2..].to_i(16).chr
+        end
+      end
     end
   end
 end

data/lib/masscan/program.rb

@@ -1,99 +1,50 @@
-require 'masscan/task'
-
-require 'rprogram/program'
+require 'masscan/command'
 
 module Masscan
   #
-  # Represents the `masscan` program.
+  # @deprecated Please use {Command} instead.
   #
-  class Program < RProgram::Program
-
-    name_program 'masscan'
+  class Program < Command
 
     #
-    # Finds the `masscan` program and performs a scan.
+    # Runs `masscan`.
     #
     # @param [Hash{Symbol => Object}] options
     #   Additional options for masscan.
     #
-    # @param [Hash{Symbol => Object}] exec_options
-    #   Additional exec-options.
-    #
-    # @yield [task]
-    #   If a block is given, it will be passed a task object
+    # @yield [masscan]
+    #   If a block is given, it will be passed the new masscan instance
     #   used to specify options for masscan.
     #
-    # @yieldparam [Task] task
-    #   The masscan task object.
+    # @yieldparam [Masscan] masscan
+    #   The masscan instance.
     #
     # @return [Boolean]
     #   Specifies whether the command exited normally.
     #
-    # @example Specifying `masscan` options via a Hash.
-    #   Masscan::Program.scan(
+    # @example Specifying `masscan` options via a Hash:
+    #   Masscan::Command.scan(
     #     ips: '192.168.1.1/24',
     #     ports: [22, 80, 443],
     #   )
     #
-    # @example Specifying `masscan` options via a {Task} object.
-    #   Masscan::Program.scan do |masscan|
+    # @example Specifying `masscan` options via a block:
+    #   Masscan::Command.scan do |masscan|
     #     masscan.ips = '192.168.1.1/24'
     #     masscan.ports = [22, 80, 443]
     #   end
     #
-    # @see #scan
-    #
-    def self.scan(options={},exec_options={},&block)
-      find.scan(options,exec_options,&block)
+    def self.scan(options={},&block)
+      run(options,&block)
     end
 
     #
-    # Finds the `masscan` program and performs a scan, but runs `masscan` under
-    # `sudo`.
+    # Runs `masscan` but under `sudo`.
     #
     # @see scan
     #
-    # @since 0.8.0
-    #
-    def self.sudo_scan(options={},exec_options={},&block)
-      find.sudo_scan(options,exec_options,&block)
-    end
-
-    #
-    # Performs a scan.
-    #
-    # @param [Hash{Symbol => Object}] options
-    #   Additional options for masscan.
-    #
-    # @param [Hash{Symbol => Object}] exec_options
-    #   Additional exec-options.
-    #
-    # @yield [task]
-    #   If a block is given, it will be passed a task object
-    #   used to specify options for masscan.
-    #
-    # @yieldparam [Task] task
-    #   The masscan task object.
-    #
-    # @return [Boolean]
-    #   Specifies whether the command exited normally.
-    #
-    # @see http://rubydoc.info/gems/rprogram/0.3.0/RProgram/Program#run-instance_method
-    #   For additional exec-options.
-    #
-    def scan(options={},exec_options={},&block)
-      run_task(Task.new(options,&block),exec_options)
-    end
-
-    #
-    # Performs a scan and runs `masscan` under `sudo`.
-    #
-    # @see #scan
-    #
-    # @since 0.8.0
-    #
-    def sudo_scan(options={},exec_options={},&block)
-      sudo_task(Task.new(options,&block),exec_options)
+    def self.sudo_scan(options={},&block)
+      sudo(options,&block)
     end
 
   end

data/lib/masscan/version.rb

@@ -1,4 +1,4 @@
 module Masscan
   # ruby-masscan version
-  VERSION = '0.1.1'
+  VERSION = '0.2.1'
 end

data/lib/masscan.rb

@@ -1,2 +1,3 @@
+require 'masscan/command'
 require 'masscan/program'
 require 'masscan/output_file'

data/spec/command_spec.rb

@@ -0,0 +1,142 @@
+require 'spec_helper'
+require 'masscan/command'
+
+describe Masscan::Command do
+  describe described_class::PortList do
+    describe "#validate" do
+      context "when given a single port number" do
+        let(:value) { 443 }
+
+        it "must return true" do
+          expect(subject.validate(value)).to be(true)
+        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
+
+      context "when given an Array of port numbers" do
+        let(:value) { [80, 443] }
+
+        it "must return true" do
+          expect(subject.validate(value)).to be(true)
+        end
+
+        context "and the Array contains Ranges" do
+          let(:value) { [80, (1..42), 443] }
+
+          it "must return true" do
+            expect(subject.validate(value)).to be(true)
+          end
+        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
+
+      context "when given an Array of port numbers" do
+        let(:value) { [80, 443] }
+
+        it "must return the formatted list of port numbers" do
+          expect(subject.format(value)).to eq(value.join(','))
+        end
+
+        context "and the Array contains Ranges" do
+          let(:value) { [80, (1..42), 443] }
+
+          it "must return the formatted list of port numbers and port ranges" do
+            expect(subject.format(value)).to eq("#{value[0]},#{value[1].begin}-#{value[1].end},#{value[2]}")
+          end
+        end
+      end
+    end
+  end
+
+  describe described_class::Shards do
+    describe "#validate" do
+      context "when given a Rational value" do
+        let(:value) { (1/2r) }
+
+        it "must return true" do
+          expect(subject.validate(value)).to be(true)
+        end
+      end
+
+      context "when given an Array value" do
+        let(:value) { [1, 2] }
+
+        it "must return true" do
+          expect(subject.validate(value)).to be(true)
+        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})"]
+            )
+          end
+        end
+      end
+
+      context "otherwise" do
+        let(:value) { :"1/2" }
+
+        it "must return true" do
+          expect(subject.validate(value)).to be(true)
+        end
+      end
+    end
+
+    describe "#format" do
+      context "when given a Rational value" do
+        let(:value) { (1/2r) }
+
+        it "must format it into \#{numerator}/\#{denominator}" do
+          expect(subject.format(value)).to eq(
+            "#{value.numerator}/#{value.denominator}"
+          )
+        end
+      end
+
+      context "when given an Array value" do
+        let(:value) { [1, 2] }
+
+        it "must format it into \#{array[0]}/\#{array[1]}" do
+          expect(subject.format(value)).to eq(
+            "#{value[0]}/#{value[1]}"
+          )
+        end
+      end
+
+      context "otherwise" do
+        let(:value) { :"1/2" }
+
+        it "must convert the value to a String" do
+          expect(subject.format(value)).to eq(value.to_s)
+        end
+      end
+    end
+  end
+end

data/spec/output_file_spec.rb

@@ -68,6 +68,38 @@ describe Masscan::OutputFile do
     end
   end
 
+  describe "FILE_FORMATS" do
+    subject { described_class::FILE_FORMATS }
+
+    describe ".bin" do
+      it { expect(subject['.bin']).to be(:binary) }
+    end
+
+    describe ".dat" do
+      it { expect(subject['.dat']).to be(:binary) }
+    end
+
+    describe ".txt" do
+      it { expect(subject['.txt']).to be(:list) }
+    end
+
+    describe ".list" do
+      it { expect(subject['.list']).to be(:list) }
+    end
+
+    describe ".json" do
+      it { expect(subject['.json']).to be(:json) }
+    end
+
+    describe ".ndjson" do
+      it { expect(subject['.ndjson']).to be(:ndjson) }
+    end
+
+    describe ".xml" do
+      it { expect(subject['.xml']).to be(:xml) }
+    end
+  end
+
   describe "#initialize" do
     let(:path) { "/path/to/file.json" }
 
@@ -100,7 +132,9 @@ describe Masscan::OutputFile do
     end
   end
 
-  subject { described_class.new(Fixtures.join('masscan.list')) }
+  let(:path) { Fixtures.join('masscan.list') }
+
+  subject { described_class.new(path) }
 
   describe "#each" do
     context "when given a block" do
@@ -132,4 +166,10 @@ describe Masscan::OutputFile do
       end
     end
   end
+
+  describe "#to_s" do
+    it "must return #path" do
+      expect(subject.to_s).to eq(path)
+    end
+  end
 end

data/spec/parsers/list_spec.rb

@@ -104,6 +104,31 @@ describe Masscan::Parsers::List do
         expect(yielded_banner.service).to eq(service_keyword)
         expect(yielded_banner.payload).to  eq(payload)
       end
+
+      context "when the payload field contains '\\xXX' hex escaped characters" do
+        let(:escaped_payload) do
+          "HTTP/1.0 404 Not Found\\x0d\\x0aContent-Type: text/html\\x0d\\x0aDate: Thu, 26 Aug 2021 06:47:52 GMT\\x0d\\x0aServer: ECS (sec/974D)\\x0d\\x0aContent-Length: 345\\x0d\\x0aConnection: close\\x0d\\x0a\\x0d"
+        end
+        let(:unescaped_payload) do
+          "HTTP/1.0 404 Not Found\r\nContent-Type: text/html\r\nDate: Thu, 26 Aug 2021 06:47:52 GMT\r\nServer: ECS (sec/974D)\r\nContent-Length: 345\r\nConnection: close\r\n\r"
+        end
+
+        let(:line) do
+          "banner #{protocol} #{port} #{ip} #{timestamp.to_i} #{service_name} #{escaped_payload}"
+        end
+
+        it "must unescape the '\\xXX' hex escaped characters" do
+          yielded_records = []
+
+          subject.parse(io) do |record|
+            yielded_records << record
+          end
+
+          yielded_banner = yielded_records.first
+
+          expect(yielded_banner.payload).to eq(unescaped_payload)
+        end
+      end
     end
   end
 end

data/spec/spec_helper.rb

@@ -1,4 +1,4 @@
-require 'spec_helper'
+require 'rspec'
 require 'simplecov'
 SimpleCov.start
 

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: ruby-masscan
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Postmodern
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-09-10 00:00:00.000000000 Z
+date: 2023-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rprogram
+  name: command_mapper
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -62,6 +62,7 @@ files:
 - gemspec.yml
 - lib/masscan.rb
 - lib/masscan/banner.rb
+- lib/masscan/command.rb
 - lib/masscan/output_file.rb
 - lib/masscan/parsers.rb
 - lib/masscan/parsers/binary.rb
@@ -70,9 +71,9 @@ files:
 - lib/masscan/parsers/plain_text.rb
 - lib/masscan/program.rb
 - lib/masscan/status.rb
-- lib/masscan/task.rb
 - lib/masscan/version.rb
 - ruby-masscan.gemspec
+- spec/command_spec.rb
 - spec/fixtures/masscan.bin
 - spec/fixtures/masscan.json
 - spec/fixtures/masscan.list
@@ -85,7 +86,6 @@ files:
 - spec/parsers/parser_examples.rb
 - spec/parsers/plain_text_spec.rb
 - spec/spec_helper.rb
-- spec/task_spec.rb
 homepage: https://github.com/postmodern/ruby-masscan#readme
 licenses:
 - MIT
@@ -94,6 +94,7 @@ metadata:
   source_code_uri: https://github.com/postmodern/ruby-masscan
   bug_tracker_uri: https://github.com/postmodern/ruby-masscan/issues
   changelog_uri: https://github.com/postmodern/ruby-masscan/blob/master/ChangeLog.md
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -110,7 +111,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - masscan >= 1.0.0
-rubygems_version: 3.2.22
+rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
 summary: A Ruby interface to masscan.

data/lib/masscan/task.rb

@@ -1,179 +0,0 @@
-require 'rprogram/task'
-
-module Masscan
-  #
-  # ## `masscan` options:
-  #
-  # * `--range` - `masscan.range`
-  # * `-p` - `masscan.ports`
-  # * `--banners` - `masscan.banners`
-  # * `--rate` - `masscan.rate`
-  # * `--conf` - `masscan.config_file`
-  # * `--resume` - `masscan.resume`
-  # * `--echo` - `masscan.echo`
-  # * `--adapter` - `masscan.adapter`
-  # * `--adapter-ip` - `masscan.adapter_ip`
-  # * `--adapter-port` - `masscan.adapter_port`
-  # * `--adapter-mac` - `masscan.adapter_mac`
-  # * `--adapter-vlan` - `masscan.adapter_vlan`
-  # * `--router-mac` - `masscan.router_mac`
-  # * `--ping` - `masscan.ping`
-  # * `--exclude` - `masscan.exclude`
-  # * `--excludefile` - `masscan.exclude_file`
-  # * `--includefile` - `masscan.include_file`
-  # * `--append-output` - `masscan.append_output`
-  # * `--iflist` - `masscan.list_interfaces`
-  # * `--retries` - `masscan.retries`
-  # * `--nmap` - `masscan.nmap_help`
-  # * `--pcap-payloads` - `masscan.pcap_payloads`
-  # * `--nmap-payloads` - `masscan.nmap_payloads`
-  # * `--http-method` - `masscan.http_method`
-  # * `--http-url` - `masscan.http_url`
-  # * `--http-version` - `masscan.http_version`
-  # * `--http-host` - `masscan.http_host`
-  # * `--http-user-agent` - `masscan.http_user_agent`
-  # * `--http-field` - `masscan.http_field`
-  # * `--http-field-remove` - `masscan.http_field_remove`
-  # * `--http-cookie` - `masscan.http_cookie`
-  # * `--http-payload` - `masscan.http_payload`
-  # * `--show` - `masscan.show`
-  # * `--noshow` - `masscan.hide`
-  # * `--pcap` - `masscan.pcap`
-  # * `--packet-trace` - `masscan.packet_trace`
-  # * `--pfring` - `masscan.pfring`
-  # * `--resume-index` - `masscan.resume_index`
-  # * `--resume-count` - `masscan.resume_count`
-  # * `--shards` - `masscan.shards`
-  # * `--rotate` - `masscan.rotate`
-  # * `--rotate-offset` - `masscan.rotate_offset`
-  # * `--rotate-size` - `masscan.rotate_size`
-  # * `--rotate-dir` - `masscan.rotate_dir`
-  # * `--seed` - `masscan.seed`
-  # * `--regress` - `masscan.regress`
-  # * `--ttl` - `masscan.ttl`
-  # * `--wait` - `masscan.wait`
-  # * `--offline` - `masscan.offline`
-  # * `-sL` - `masscan.print_list`
-  # * `--interactive` - `masscan.interactive`
-  # * `--output-format` - `masscan.output_format`
-  # * `--output-filename` - `masscan.output_file`
-  # * `-oB` - `masscan.output_binary`
-  # * `-oX` - `masscan.output_xml`
-  # * `-oG` - `masscan.output_grepable`
-  # * ` -oJ` - `masscan.output_json`
-  # * `-oL` - `masscan.output_list`
-  # * `--readscan` - `masscan.read_scan`
-  # * `-V` - `masscan.version`
-  # * `-h` - `masscan.help`
-  #
-  # @see https://github.com/robertdavidgraham/masscan/blob/master/doc/masscan.8.markdown
-  #
-  class Task < RProgram::Task
-
-    long_option flag: '--range', name: :range, separator: ','
-    short_option flag: '-p', name: :ports do |opt,value|
-      unless value.empty?
-        [opt.flag, format_port_list(value)]
-      end
-    end
-    long_option flag: '--banners', name: :banners
-    long_option flag: '--rate',    name: :rate
-    long_option flag: '--conf',    name: :config_file
-    long_option flag: '--resume',  name: :resume
-    long_option flag: '--echo',    name: :echo
-    long_option flag: '--adapter', name: :adapter
-    long_option flag: '--adapter-ip',   name: :adapter_ip
-    long_option flag: '--adapter-port', name: :adapter_port
-    long_option flag: '--adapter-mac',  name: :adapter_mac
-    long_option flag: '--adapter-vlan', name: :adapter_vlan
-    long_option flag: '--router-mac', name: :router_mac
-    long_option flag: '--ping', name: :ping
-    long_option flag: '--exclude', name: :exclude, separator: ','
-    long_option flag: '--excludefile', name: :exclude_file
-    long_option flag: '--includefile', name: :include_file
-    long_option flag: '--append-output', name: :append_output
-    long_option flag: '--iflist', name: :list_interfaces
-    long_option flag: '--retries', name: :retries
-    long_option flag: '--nmap', name: :nmap_help
-    long_option flag: '--pcap-payloads', name: :pcap_payloads
-    long_option flag: '--nmap-payloads', name: :nmap_payloads
-
-    long_option flag: '--http-method',     name: :http_method
-    long_option flag: '--http-url',        name: :http_url
-    long_option flag: '--http-version',    name: :http_version
-    long_option flag: '--http-host',       name: :http_host
-    long_option flag: '--http-user-agent', name: :http_user_agent
-
-    long_option flag: '--http-field', multiple: true do |opt,value|
-      name, value = value.first
-
-      [opt.flag, "#{name}:#{value}"]
-    end
-
-    long_option flag: '--http-field-remove', name: :http_field_remove
-    long_option flag: '--http-cookie', name: :http_cookie
-    long_option flag: '--http-payload', name: :http_payload
-
-    long_option flag: '--show', name: :show
-    long_option flag: '--noshow', name: :hide
-    long_option flag: '--pcap', name: :pcap
-    long_option flag: '--packet-trace', name: :packet_trace
-    long_option flag: '--pfring', name: :pfring
-    long_option flag: '--resume-index', name: :resume_index
-    long_option flag: '--resume-count', name: :resume_count
-    long_option flag: '--shards', name: :shards do |opt,value|
-      case value.length
-      when 2 then [opt.flag, "#{value[0]}/#{value[1]}"]
-      when 1 then [opt.flag, "#{value[0]}"]
-      else
-        raise(ArgumentError,"#{self}#shards= does not accept more than two values")
-      end
-    end
-    long_option flag: '--rotate', name: :rotate
-    long_option flag: '--rotate-offset', name: :rotate_offset
-    long_option flag: '--rotate-size',   name: :rotate_size
-    long_option flag: '--rotate-dir',    name: :rotate_dir
-    long_option flag: '--seed', name: :seed
-    long_option flag: '--regress', name: :regress
-    long_option flag: '--ttl', name: :ttl
-    long_option flag: '--wait', name: :wait
-    long_option flag: '--offline', name: :offline
-    short_option flag: '-sL', name: :print_list
-    long_option flag: '--interactive', name: :interactive
-    long_option flag: '--output-format', name: :output_format
-    long_option flag: '--output-filename', name: :output_file
-    short_option flag: '-oB', name: :output_binary
-    short_option flag: '-oX', name: :output_xml
-    short_option flag: '-oG', name: :output_grepable
-    short_option flag:' -oJ', name: :output_json
-    short_option flag: '-oL', name: :output_list
-    long_option flag: '--readscan', name: :read_scan
-    short_option :flag => '-V', :name => :version
-    short_option :flag => '-h', :name => :help
-
-    non_option :tailing => true, :name => :ips
-
-    private
-
-    #
-    # Formats a port list.
-    #
-    # @param [Array<Integer,Range>] ports
-    #   The port ranges.
-    #
-    # @return [String]
-    #   Comma separated string.
-    #
-    def self.format_port_list(ports)
-      ports.map { |port|
-        case port
-        when Range
-          "#{port.first}-#{port.last}"
-        else
-          port.to_s
-        end
-      }.join(',')
-    end
-
-  end
-end

data/spec/task_spec.rb

@@ -1,121 +0,0 @@
-require 'spec_helper'
-require 'masscan/task'
-
-describe Masscan::Task do
-  describe "#ports=" do
-    context "when given an empty Array" do
-      before { subject.ports = [] }
-
-      it "should ignore empty port Arrays" do
-        subject.ports = []
-
-        expect(subject.arguments).to eq([])
-      end
-    end
-
-    context "when given a String" do
-      let(:ports) { '80,21,25' }
-
-      before { subject.ports = ports }
-
-      it "should emit the String as is" do
-        expect(subject.arguments).to eq(['-p', ports])
-      end
-    end
-
-    context "when given an Array of Strings" do
-      let(:ports) { %w[80 21 25] }
-
-      before { subject.ports = ports }
-
-      it "should format an Array of String ports" do
-        expect(subject.arguments).to eq(['-p', ports.join(',')])
-      end
-    end
-
-    context "when given an Array of Integers" do
-      let(:ports) { [80, 21, 25] }
-
-      before { subject.ports = ports }
-
-      it "should format an Array of Integer ports" do
-        expect(subject.arguments).to eq(['-p', ports.join(',')])
-      end
-    end
-
-    context "when given an Array containing a Range" do
-      let(:ports) { [80, 21..25] }
-
-      before { subject.ports = ports }
-
-      it "should format the Range" do
-        expect(subject.arguments).to eq([
-          '-p', "#{ports[0]},#{ports[1].begin}-#{ports[1].end}"
-        ])
-      end
-    end
-  end
-
-  describe "#shards=" do
-    context "when given a Rational value" do
-      let(:rational) { (1/2r) }
-
-      before { subject.shards = rational }
-
-      it "must format it into \#{numerator}/\#{denominator}" do
-        expect(subject.arguments).to eq([
-          "--shards", "#{rational.numerator}/#{rational.denominator}"
-        ])
-      end
-    end
-
-    context "when given an Array value" do
-      let(:array) { [1, 2] }
-
-      before { subject.shards = array }
-
-      it "must format it into \#{array[0]}/\#{array[1]}" do
-        expect(subject.arguments).to eq([
-          "--shards", "#{array[0]}/#{array[1]}"
-        ])
-      end
-
-      context "but the Array length is > 2" do
-        let(:array) { [1,2,3] }
-
-        before { subject.shards = array }
-
-        it do
-          expect {
-            subject.arguments
-          }.to raise_error(ArgumentError,"#{described_class}#shards= does not accept more than two values")
-        end
-      end
-    end
-
-    context "otherwise" do
-      let(:object) { :"1/2" }
-
-      before { subject.shards = object }
-
-      it "must convert the value to a String" do
-        expect(subject.arguments).to eq([
-          "--shards", object.to_s
-        ])
-      end
-    end
-  end
-
-  describe "#http_field=" do
-    let(:name)  { 'X-Foo' }
-    let(:value) { 'bar'   }
-
-    before { subject.http_field = [ [name, value] ] }
-
-    it "must join two values together with a ':'" do
-      expect(subject.arguments).to eq([
-        "--http-field", "#{name}:#{value}"
-      ])
-    end
-  end
-end