ronin-masscan 0.1.0.rc1

data/lib/ronin/masscan/cli.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+#
+# ronin-masscan - A Ruby library and CLI for working with masscan.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-masscan is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-masscan is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-masscan.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/masscan/version'
+require 'ronin/core/cli/help/banner'
+
+require 'command_kit/commands'
+require 'command_kit/commands/auto_load'
+require 'command_kit/options/version'
+
+module Ronin
+  module Masscan
+    #
+    # The `ronin-masscan` command-line interface (CLI).
+    #
+    # @api private
+    #
+    class CLI
+
+      include CommandKit::Commands
+      include CommandKit::Commands::AutoLoad.new(
+        dir:       "#{__dir__}/cli/commands",
+        namespace: "#{self}::Commands"
+      )
+      include CommandKit::Options::Version
+      include Core::CLI::Help::Banner
+
+      command_name 'ronin-masscan'
+      version Ronin::Masscan::VERSION
+
+    end
+  end
+end

data/lib/ronin/masscan/converter.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+#
+# ronin-masscan - A Ruby library and CLI for working with masscan.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-masscan is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-masscan is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-masscan.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/masscan/converters'
+
+require 'masscan/output_file'
+
+module Ronin
+  module Masscan
+    #
+    # Handles converting masscan scan file into other formats.
+    #
+    # Supports the following formats:
+    #
+    # * JSON
+    # * CSV
+    #
+    # @api public
+    #
+    module Converter
+      # Mapping of file extension names to formats.
+      #
+      # @api private
+      FILE_FORMATS = {
+        '.json' => :json,
+        '.csv'  => :csv
+      }
+
+      #
+      # Converts an masscan scan file into another format.
+      #
+      # @param [String] src
+      #   The input masscan scan file path.
+      #
+      # @param [String] dest
+      #   The output file path.
+      #
+      # @param [:binary, :list, :json, :ndjson, nil] input_format
+      #   The explicit format of the input masscan scan file.
+      #   If not specified the input format will be inferred from the file's
+      #   extension.
+      #
+      # @param [:json, :csv] format
+      #   The format to convert the masscan scan file into. If not specified
+      #   it will be inferred from the output file's extension.
+      #
+      # @api public
+      #
+      def self.convert_file(src,dest, input_format: nil,
+                                      format:       infer_format_for(dest))
+        scan_file = if input_format
+                      ::Masscan::OutputFile.new(src, format: input_format)
+                    else
+                      ::Masscan::OutputFile.new(src)
+                    end
+
+        converter = Converters[format]
+
+        File.open(dest,'w') do |output|
+          converter.convert(scan_file,output)
+        end
+      end
+
+      #
+      # Converts parsed masscan scan file into the desired format.
+      #
+      # @param [::Masscan::OutputFile] masscan_file
+      #   The masscan scan file to convert.
+      #
+      # @param [IO, nil] output
+      #   Optional output to write the converted output to.
+      #
+      # @param [:json, :csv] format
+      #   The desired convert to convert the parsed masscan scan file to.
+      #
+      # @return [IO, String]
+      #   The converted masscan scan file.
+      #
+      # @api public
+      #
+      def self.convert(masscan_file,output=nil, format: )
+        if output
+          Converters[format].convert(masscan_file,output)
+        else
+          output = StringIO.new
+          convert(masscan_file,output, format: format)
+          output.string
+        end
+      end
+
+      #
+      # Infers the output format from the output file's extension.
+      #
+      # @param [String] path
+      #   The output file name.
+      #
+      # @return [:json, :csv]
+      #   The conversion format.
+      #
+      # @raise [ArgumentError]
+      #   The format could not be inferred from the path's file extension.
+      #
+      # @api private
+      #
+      def self.infer_format_for(path)
+        FILE_FORMATS.fetch(File.extname(path)) do
+          raise(ArgumentError,"cannot infer output format from path: #{path.inspect}")
+        end
+      end
+    end
+  end
+end

data/lib/ronin/masscan/converters/csv.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+#
+# ronin-masscan - A Ruby library and CLI for working with masscan.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-masscan is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-masscan is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-masscan.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'masscan/output_file'
+require 'csv'
+
+module Ronin
+  module Masscan
+    module Converters
+      #
+      # Handles converting masscan scan files into CSV.
+      #
+      # @api private
+      #
+      module CSV
+        #
+        # Converts the masscan scan file to CSV.
+        #
+        # @param [::Masscan::OutputFile] masscan_file
+        #   The opened masscan scan file.
+        #
+        # @param [StringIO, IO] output
+        #   Optional output stream to write the CSV to.
+        #
+        def self.convert(masscan_file,output)
+          masscan_file_to_csv(masscan_file,output)
+        end
+
+        #
+        # Converts a masscan scan file to CSV.
+        #
+        # @param [::Masscan::OutputFile] masscan_file
+        #   The masscan scan file to convert to CSV.
+        #
+        # @param [StringIO, IO] output
+        #   The optional output to write the CSV to.
+        #
+        #
+        def self.masscan_file_to_csv(masscan_file,output)
+          masscan_file_to_rows(masscan_file) do |row|
+            output << ::CSV.generate_line(row)
+          end
+
+          return output
+        end
+
+        # CSV rows header.
+        HEADER = %w[type status.status status.protocol status.port status.reason status.ttl status.ip status.timestamp banner.protocol banner.port banner.ip banner.timestamp banner.app_protocol banner.payload]
+
+        #
+        # Converts an opened masscan scan file to a series of rows.
+        #
+        # @param [::Masscan::OutputFile] masscan_file
+        #   The opened masscan scan file.
+        #
+        # @yield [row]
+        #   The given block will be passed each row.
+        #
+        # @yieldparam [Array] row
+        #   A row to be converted to CSV.
+        #
+        def self.masscan_file_to_rows(masscan_file)
+          yield HEADER
+
+          masscan_file.each do |record|
+            yield record_to_row(record)
+          end
+        end
+
+        def self.record_to_row(record)
+          case record
+          when ::Masscan::Status
+            status_record_to_row(record)
+          when ::Masscan::Banner
+            banner_record_to_row(record)
+          else
+            raise(NotImplementedError,"unable to convert masscan record: #{record.inspect}")
+          end
+        end
+
+        def self.status_record_to_row(status)
+          ['status', status.status, status.protocol, status.port, status.reason.join(','), status.ttl, status.ip, status.timestamp]
+        end
+
+        def self.banner_record_to_row(banner)
+          ['banner', nil, nil, nil, nil, nil, nil, nil, banner.protocol, banner.port, banner.ip, banner.timestamp, banner.app_protocol, banner.payload]
+        end
+      end
+    end
+  end
+end

data/lib/ronin/masscan/converters/json.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+#
+# ronin-masscan - A Ruby library and CLI for working with masscan.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-masscan is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-masscan is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-masscan.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'masscan/output_file'
+require 'json'
+
+module Ronin
+  module Masscan
+    module Converters
+      #
+      # Handles converting masscan scan files into JSON.
+      #
+      # @api private
+      #
+      module JSON
+        #
+        # Converts the masscan scan file to JSON.
+        #
+        # @param [::Masscan::OutputFile] masscan_file
+        #   The opened masscan scan file.
+        #
+        # @param [IO, StringIO] output
+        #   Optional output stream to write the JSON to.
+        #
+        def self.convert(masscan_file,output)
+          masscan_file_to_json(masscan_file,output)
+        end
+
+        #
+        # Converts the masscan scan file to JSON.
+        #
+        # @param [::Masscan::OutputFile] masscan_file
+        #   The opened masscan scan file.
+        #
+        # @param [IO, StringIO] output
+        #   Optional output stream to write the JSON to.
+        #
+        def self.masscan_file_to_json(masscan_file,output)
+          ::JSON.dump(masscan_file_as_json(masscan_file),output)
+        end
+
+        #
+        # Converts a masscan scan file into JSON representation.
+        #
+        # @param [::Masscan::OutputFile] output_file
+        #   The opened masscan file.
+        #
+        # @return [Array<Hash{Symbol => Object}>]
+        #   The JSON representation of the masscan scan file.
+        #
+        def self.masscan_file_as_json(output_file)
+          output_file.each.map do |record|
+            record_as_json(record)
+          end
+        end
+
+        #
+        # Converts a masscan record into a JSON representation.
+        #
+        # @param [::Masscan::Status, ::Masscan::Banner] record
+        #   The masscan status or banner record to convert.
+        #
+        # @return [Hash{Symbol => Object}]
+        #   The JSON representation of the record.
+        #
+        def self.record_as_json(record)
+          case record
+          when ::Masscan::Status
+            status_as_json(record)
+          when ::Masscan::Banner
+            banner_as_json(record)
+          else
+            raise(NotImplementedError,"unable to convert masscan record: #{record.inspect}")
+          end
+        end
+
+        #
+        # Converts a masscan status record into a JSON representation.
+        #
+        # @param [::Masscan::Status] status
+        #   The masscan status record to convert.
+        #
+        # @return [Hash{Symbol => Object}]
+        #   The JSON representation of the record.
+        #
+        def self.status_as_json(status)
+          hash = {
+            status:    status.status,
+            protocol:  status.protocol,
+            port:      status.port,
+            reason:    status.reason,
+            ttl:       status.ttl,
+            ip:        status.ip,
+            timestamp: status.timestamp
+          }
+
+          # omit the `mac` field if it's nil
+          hash[:mac] = status.mac if status.mac
+
+          return hash
+        end
+
+        #
+        # Converts a masscan record into a JSON representation.
+        #
+        # @param [::Masscan::Banner] banner
+        #   The masscan banner record to convert.
+        #
+        # @return [Hash{Symbol => Object}]
+        #   The JSON representation of the record.
+        #
+        def self.banner_as_json(banner)
+          {
+            protocol:     banner.protocol,
+            port:         banner.port,
+            ip:           banner.ip,
+            timestamp:    banner.timestamp,
+            app_protocol: banner.app_protocol,
+            payload:      banner.payload
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ronin/masscan/converters.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+#
+# ronin-masscan - A Ruby library and CLI for working with masscan.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-masscan is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-masscan is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-masscan.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/masscan/converters/json'
+require 'ronin/masscan/converters/csv'
+
+module Ronin
+  module Masscan
+    #
+    # @api private
+    #
+    module Converters
+      # Mapping of formats to converter modules.
+      FORMATS = {
+        json: JSON,
+        csv:  CSV
+      }
+
+      #
+      # Fetches the converter for the given format.
+      #
+      # @param [:json, :csv] format
+      #
+      # @return [Converters::JSON, Converters::CSV]
+      #   The converter module.
+      #
+      # @raise [ArgumentError]
+      #   The given format is unsupported.
+      #
+      def self.[](format)
+        FORMATS.fetch(format) do
+          raise(ArgumentError,"unsupported format: #{format.inspect}")
+        end
+      end
+    end
+  end
+end

data/lib/ronin/masscan/exceptions.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+#
+# ronin-masscan - A Ruby library and CLI for working with masscan.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-masscan is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-masscan is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-masscan.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Masscan
+    #
+    # Base class for all {Ronin::Masscan} exceptions.
+    #
+    # @api public
+    #
+    class Exception < RuntimeError
+    end
+
+    #
+    # Indicates that the `masscan` command is not installed.
+    #
+    # @api public
+    #
+    class NotInstalled < Exception
+    end
+
+    #
+    # Indicates that the `masscan` scan failed.
+    #
+    # @api public
+    #
+    class ScanFailed < Exception
+    end
+  end
+end