ronin-masscan 0.1.0.rc1

data/lib/ronin/masscan/cli/commands/scan.rb

@@ -0,0 +1,206 @@
+# 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/cli/command'
+require 'ronin/masscan/cli/importable'
+require 'ronin/masscan/converter'
+require 'ronin/core/cli/logging'
+
+require 'tempfile'
+require 'set'
+
+module Ronin
+  module Masscan
+    class CLI
+      module Commands
+        #
+        # Runs masscan and outputs data as JSON or CSV or imports into the
+        # database.
+        #
+        # ## Usage
+        #
+        #     ronin-masscan scan [options] -- [masscan_options]
+        #
+        # ## Options
+        #
+        #         --db NAME                    The database to connect to (Default: default)
+        #         --db-uri URI                 The database URI to connect to
+        #         --sudo                       Runs the masscan command under sudo
+        #     -o, --output FILE                The output file
+        #     -F, --output-format json|csv     The output format
+        #         --import                     Imports the scan results into the database
+        #     -h, --help                       Print help information
+        #
+        # ## Arguments
+        #
+        #     masscan_options ...              Additional arguments for masscan
+        #
+        # ## Examples
+        #
+        #     ronin-masscan scan -o scan.json -- 192.168.1.1
+        #     ronin-masscan scan --import -- 192.168.1.1
+        #
+        class Scan < Command
+
+          include Importable
+          include Core::CLI::Logging
+
+          usage '[options] -- [masscan_options]'
+
+          option :sudo, desc: 'Runs the masscan command under sudo'
+
+          option :output, short: '-o',
+                          value: {
+                            type:  String,
+                            usage: 'FILE'
+                          },
+                          desc: 'The output file'
+
+          option :output_format, short: '-F',
+                                 value: {
+                                   type: [:json, :csv]
+                                 },
+                                 desc: 'The output format'
+
+          option :import, desc: 'Imports the scan results into the database'
+
+          argument :masscan_args, required: true,
+                               repeats:  true,
+                               usage:    'masscan_options',
+                               desc:     'Additional arguments for masscan'
+
+          description 'Runs masscan and outputs data as JSON or CSV or imports into the database'
+
+          examples [
+            '-o scan.json -- 192.168.1.1',
+            '--import -- 192.168.1.1'
+          ]
+
+          man_page 'ronin-masscan-scan.1'
+
+          #
+          # Runs the `ronin-masscan scan` command.
+          #
+          # @param [Array<String>] masscan_args
+          def run(*masscan_args)
+            if (output = options[:output])
+              output_format = options.fetch(:output_format) do
+                                infer_output_format(output)
+                              end
+
+              if output_format.nil?
+                print_error "cannot infer the output format of the output file (#{output.inspect}), please specify --output-format"
+                exit(1)
+              end
+            end
+
+            tempfile = Tempfile.new(['ronin-masscan', '.bin'])
+
+            log_info "Running masscan #{masscan_args.join(' ')} ..."
+
+            unless run_masscan(*masscan_args, output: tempfile.path)
+              print_error "failed to run masscan"
+              exit(1)
+            end
+
+            if output
+              log_info "Saving #{output_format.upcase} output to #{output} ..."
+              save_output(tempfile.path,output, format: output_format)
+            end
+
+            if options[:import]
+              log_info "Importing masscan output ..."
+              import_scan(tempfile.path)
+            end
+          end
+
+          #
+          # Runs the `masscan` command.
+          #
+          # @param [Array<String>] masscan_args
+          #   Additional arguments for `masscan`.
+          #
+          # @param [String] output
+          #   The output file to save the scan data to.
+          #
+          # @return [Boolean, nil]
+          #   Indicates whether the `masscan` command was successful.
+          #
+          def run_masscan(*masscan_args, output: )
+            masscan_command = ['masscan', '-v', *masscan_args, '-oB', output]
+            masscan_command.unshift('sudo') if options[:sudo]
+
+            return system(*masscan_command)
+          end
+
+          #
+          # Saves the masscan scan results to an output file in the given
+          # format.
+          #
+          # @param [String] path
+          #   The path to the masscan output file.
+          #
+          # @param [String] output
+          #   The path to the desired output file.
+          #
+          # @param [:json, :csv] format
+          #   The desired output format.
+          #
+          def save_output(path,output, format: )
+            # the format has been explicitly specified
+            Converter.convert_file(path,output, format: format)
+          end
+
+          #
+          # Imports a masscan output file.
+          #
+          # @param [String] path
+          #   The path to the output file.
+          #
+          def import_scan(path)
+            db_connect
+            import_file(path)
+          end
+
+          # Supported output formats.
+          OUTPUT_FORMATS = {
+            '.json' => :json,
+            '.csv'  => :csv
+          }
+
+          #
+          # Infers the output format from the given path's file extension.
+          #
+          # @param [String] path
+          #   The path to infer the output format from.
+          #
+          # @return [:json, :csv, nil]
+          #   The output format or `nil` if the path's file extension is
+          #   unknown.
+          #
+          def infer_output_format(path)
+            OUTPUT_FORMATS[File.extname(path)]
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/masscan/cli/filtering_options.rb

@@ -0,0 +1,312 @@
+# 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/cli/port_list'
+
+module Ronin
+  module Masscan
+    class CLI
+      #
+      # Mixin which adds nmap target filtering options to commands.
+      #
+      module FilteringOptions
+        #
+        # Adds filtering options to the command class including
+        # {FilteringOptions}.
+        #
+        # @param [Class<Command>] command
+        #   The command class including {FilteringOptions}.
+        #
+        def self.included(command)
+          command.option :protocol, short: '-P',
+                                    value: {
+                                      type: [:tcp, :udp]
+                                    },
+                                    desc: 'Filters the targets by protocol' do |proto|
+                                      @protocols << proto
+                                    end
+
+          command.option :ip, value: {
+                                type:  String,
+                                usage: 'IP'
+                              },
+                              desc: 'Filters the targets by IP' do |ip|
+                                @ips << ip
+                              end
+
+          command.option :ip_range, value: {
+                                      type:  String,
+                                      usage: 'CIDR'
+                                    },
+                                    desc: 'Filters the targets by IP range' do |ip_range|
+                                      @ip_ranges << IPAddr.new(ip_range)
+                                    end
+
+          command.option :ports, short: '-p',
+                                 value: {
+                                   type: /\A(?:\d+|\d+-\d+)(?:,(?:\d+|\d+-\d+))*\z/,
+                                   usage: '{PORT | PORT1-PORT2},...'
+                                 },
+                                 desc: 'Filter targets by port number' do |ports|
+                                   @ports << PortList.parse(ports)
+                                 end
+
+          command.option :with_app_protocol, value: {
+                                               type:  /\A[a-z][a-z0-9_-]*\z/,
+                                               usage: 'APP_PROTOCOL[,...]'
+                                             },
+                                             desc: 'Filters targets with the app protocol' do |app_protocol|
+                                               @with_app_protocols << app_protocol.to_sym
+                                             end
+
+          command.option :with_payload, value: {
+                                          type:  String,
+                                          usage: 'STRING'
+                                        },
+                                        desc: 'Filters targets containing the payload' do |string|
+                                          @with_payloads << string
+                                        end
+
+          command.option :with_payload_regex, value: {
+                                                type:  Regexp,
+                                                usage: '/REGEX/'
+                                              },
+                                              desc: 'Filters targets with the matching payload' do |regexp|
+                                                @with_payloads << regexp
+                                              end
+        end
+
+        # The protocols to filter the targets by.
+        #
+        # @return [Set<:tcp, :udp>]
+        attr_reader :protocols
+
+        # The IPs to filter the targets by.
+        #
+        # @return [Set<String>]
+        attr_reader :ips
+
+        # The IP ranges to filter the targets by.
+        #
+        # @return [Set<IPAddr>]
+        attr_reader :ip_ranges
+
+        # The ports to filter the targets by.
+        #
+        # @return [Set<PortList>]
+        attr_reader :ports
+
+        # The app protocols to filter the targets by.
+        #
+        # @return [Set<String>]
+        attr_reader :with_app_protocols
+
+        # The payload Strings or Regexps to filter the targets by.
+        #
+        # @return [Set<String, Regexp>]
+        attr_reader :with_payloads
+
+        #
+        # Initializes the command.
+        #
+        # @param [Hash{Symbol => String}] kwargs
+        #   Additional keywords for the command.
+        #
+        def initialize(**kwargs)
+          super(**kwargs)
+
+          @protocols = Set.new
+          @ips       = Set.new
+          @ip_ranges = Set.new
+          @ports     = Set.new
+
+          # Masscan::Banner filtering options
+          @with_app_protocols = Set.new
+          @with_payloads      = Set.new
+        end
+
+        #
+        # Filters the masscan records.
+        #
+        # @param [::Masscan::OutputFile] output_file
+        #   The parsed nmap xml data to filter.
+        #
+        # @return [Enumerator::Lazy]
+        #   A lazy enumerator of the filtered records.
+        #
+        def filter_records(output_file)
+          records = output_file.each.lazy
+
+          unless @protocols.empty?
+            records = filter_records_by_protocol(records)
+          end
+
+          unless @ips.empty?
+            records = filter_records_by_ip(records)
+          end
+
+          unless @ip_ranges.empty?
+            records = filter_records_by_ip_range(records)
+          end
+
+          unless @ports.empty?
+            records = filter_records_by_port(records)
+          end
+
+          unless @with_app_protocols.empty?
+            records = filter_records_by_app_protocol(records)
+          end
+
+          unless @with_payloads.empty?
+            records = filter_records_by_payload(records)
+          end
+
+          return records
+        end
+
+        #
+        # Filter `Masscan::Status` records.
+        #
+        # @param [Enumerator::Lazy] records
+        #   The records to filter.
+        #
+        # @return [Enumerator::Lazy]
+        #   The filtered records.
+        #
+        def filter_status_records(records)
+          records.filter do |record|
+            record.kind_of?(::Masscan::Status)
+          end
+        end
+
+        #
+        # Filter `Masscan::Banner` records.
+        #
+        # @param [Enumerator::Lazy] records
+        #   The records to filter.
+        #
+        # @return [Enumerator::Lazy]
+        #   The filtered records.
+        #
+        def filter_banner_records(records)
+          records.filter do |record|
+            record.kind_of?(::Masscan::Banner)
+          end
+        end
+
+        #
+        # Filters the records by protocol
+        #
+        # @param [Enumerator::Lazy] records
+        #   The records to filter.
+        #
+        # @return [Enumerator::Lazy]
+        #   A lazy enumerator of the filtered records.
+        #
+        def filter_records_by_protocol(records)
+          records.filter do |record|
+            @protocols.include?(record.protocol)
+          end
+        end
+
+        #
+        # Filters the records by IP address.
+        #
+        # @param [Enumerator::Lazy] records
+        #   The records to filter.
+        #
+        # @return [Enumerator::Lazy]
+        #   A lazy enumerator of the filtered records.
+        #
+        def filter_records_by_ip(records)
+          records.filter do |record|
+            @ips.include?(record.ip)
+          end
+        end
+
+        #
+        # Filters the records by an IP rangeo.
+        #
+        # @param [Enumerator::Lazy] records
+        #   The records to filter.
+        #
+        # @return [Enumerator::Lazy]
+        #   A lazy enumerator of the filtered records.
+        #
+        def filter_records_by_ip_range(records)
+          records.filter do |record|
+            @ip_ranges.any? do |ip_range|
+              ip_range.include?(record.ip)
+            end
+          end
+        end
+
+        #
+        # Filters the records by port number.
+        #
+        # @param [Enumerator::Lazy] records
+        #   The records to filter.
+        #
+        # @return [Enumerator::Lazy]
+        #   A lazy enumerator of the filtered records.
+        #
+        def filter_records_by_port(records)
+          records.filter do |record|
+            @ports.include?(record.port)
+          end
+        end
+
+        #
+        # Filters the records by app-protocol IDs.
+        #
+        # @param [Enumerator::Lazy] records
+        #   The records to filter.
+        #
+        # @return [Enumerator::Lazy]
+        #   A lazy enumerator of the filtered records.
+        #
+        def filter_records_by_app_protocol(records)
+          records.filter do |record|
+            record.kind_of?(::Masscan::Banner) &&
+              @with_app_protocols.include?(record.app_protocol)
+          end
+        end
+
+        #
+        # Filters the records by payload contents.
+        #
+        # @param [Enumerator::Lazy] records
+        #   The records to filter.
+        #
+        # @return [Enumerator::Lazy]
+        #   A lazy enumerator of the filtered records.
+        #
+        def filter_records_by_payload(records)
+          regexp = Regexp.union(@with_payloads.to_a)
+
+          records.filter do |record|
+            record.kind_of?(::Masscan::Banner) &&
+              record.payload =~ regexp
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/masscan/cli/importable.rb

@@ -0,0 +1,68 @@
+# 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/importer'
+require 'ronin/db/cli/database_options'
+require 'ronin/db/cli/printing'
+require 'ronin/core/cli/logging'
+
+module Ronin
+  module Masscan
+    class CLI
+      #
+      # Mixin module which adds the ability to import masscan scan files into
+      # the [ronin-db] database.
+      #
+      # [ronin-db]: https://github.com/ronin-rb/ronin-db#readme
+      #
+      module Importable
+        include DB::CLI::Printing
+        include Core::CLI::Logging
+
+        #
+        # Includes `Ronin::DB::CLI::DatabaseOptions` into the including command
+        # class.
+        #
+        # @param [Class<Command>] command
+        #   The command class including {Importable}.
+        #
+        def self.included(command)
+          command.include DB::CLI::DatabaseOptions
+        end
+
+        #
+        # Imports an masscan scan file into the [ronin-db] database.
+        #
+        # [ronin-db]: https://github.com/ronin-rb/ronin-db#readme
+        #
+        # @param [String] masscan_file
+        #   The path to the masscan scan file to import.
+        #
+        def import_file(masscan_file,**kwargs)
+          Importer.import_file(masscan_file,**kwargs) do |record|
+            if (type = record_type(record))
+              log_info "Imported #{type}: #{record}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/masscan/cli/port_list.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+#
+# ronin-nmap - A Ruby library for automating nmap and importing nmap scans.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-nmap 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-nmap 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-nmap.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'set'
+
+module Ronin
+  module Masscan
+    class CLI
+      #
+      # Represents a list of port numbers and port ranges.
+      #
+      class PortList
+
+        # Port numbers.
+        #
+        # @return [Array<Integer>]
+        attr_reader :numbers
+
+        # Port ranges.
+        #
+        # @return [Array<Range>]
+        attr_reader :ranges
+
+        #
+        # Initialize the port list.
+        #
+        # @param [Array<Integer, Range>] ports
+        #   The port numbers and ranges.
+        #
+        # @raise [ArgumentError]
+        #   One of the ports was not an Integer or Range object.
+        #
+        def initialize(ports)
+          @numbers = Set.new
+          @ranges  = Set.new
+
+          ports.each do |port|
+            case port
+            when Integer then @numbers << port
+            when Range   then @ranges  << port
+            else
+              raise(ArgumentError,"port must be an Integer or Range: #{port.inspect}")
+            end
+          end
+        end
+
+        #
+        # Parses the port list.
+        #
+        # @param [String] ports
+        #   The port list to parse.
+        #
+        # @return [PortList]
+        #   The port numbers and port ranges.
+        #
+        def self.parse(ports)
+          new(
+            ports.split(',').map do |port|
+              if port.include?('-')
+                start, stop = port.split('-',2)
+
+                Range.new(start.to_i,stop.to_i)
+              else
+                port.to_i
+              end
+            end
+          )
+        end
+
+        #
+        # Determines if the port is in the port list.
+        #
+        # @param [Integer] port
+        #
+        # @return [Boolean]
+        #
+        def include?(port)
+          @numbers.include?(port) ||
+            @ranges.any? { |range| range.include?(port) }
+        end
+
+      end
+    end
+  end
+end