ronin-masscan 0.1.0.rc1

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

@@ -0,0 +1,235 @@
+# 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/filtering_options'
+
+require 'command_kit/colors'
+require 'command_kit/printing/indent'
+require 'masscan/output_file'
+
+module Ronin
+  module Masscan
+    class CLI
+      module Commands
+        #
+        # Greps the scanned services from masscan scan file(s) for the given
+        # pattern.
+        #
+        # ## Usage
+        #
+        #     ronin-masscan grep [options] PATTERN MASSCAN_FILE [...]
+        #
+        # ## Options
+        #
+        #     -P, --protocol tcp|udp           Filters the targets by protocol
+        #         --ip IP                      Filters the targets by IP
+        #         --ip-range CIDR              Filters the targets by IP range
+        #         -p, --ports {PORT | PORT1-PORT2},...
+        #                                      Filters targets by port number
+        #         --with-app-protocol APP_PROTOCOL[,...]
+        #                                      Filters targets with the app protocol
+        #         --with-payload STRING        Filters targets containing the payload
+        #         --with-payload-regex /REGEX/ Filters targets with the matching payload
+        #     -h, --help                       Print help information
+        #
+        # ## Arguments
+        #
+        #     PATTERN                          The pattern to search for
+        #     MASSCAN_FILE ...                 The masscan scan file(s) to parse
+        #
+        class Grep < Command
+
+          usage '[options] PATTERN MASSCAN_FILE [...]'
+
+          include CommandKit::Colors
+          include CommandKit::Printing::Indent
+          include FilteringOptions
+
+          argument :pattern, required: true,
+                             desc:     'The pattern to search for'
+
+          argument :masscan_file, required: true,
+                                  repeats:  true,
+                                  desc:     'The masscan scan file(s) to parse'
+
+          description 'Greps the scanned services from masscan scan file(s)'
+
+          man_page 'ronin-masscan-grep.1'
+
+          #
+          # Runs the `ronin-masscan grep` command.
+          #
+          # @param [String] pattern
+          #   The pattern to search for.
+          #
+          # @param [Array<String>] masscan_files
+          #   The nmap `.xml` files to parse.
+          #
+          def run(pattern,*masscan_files)
+            masscan_files.each do |masscan_file|
+              unless File.file?(masscan_file)
+                print_error "no such file or directory: #{masscan_file}"
+                next
+              end
+
+              output_file = begin
+                              ::Masscan::OutputFile.new(masscan_file)
+                            rescue ArgumentError => error
+                              print_error(error.message)
+                              exit(1)
+                            end
+
+              records = grep_records(output_file,pattern)
+
+              highlight_records(records,pattern)
+            end
+          end
+
+          #
+          # Greps the masscan output file for the pattern.
+          #
+          # @param [::Masscan::OutputFile] output_file
+          #   The masscan output file to search.
+          #
+          # @param [String] pattern
+          #   The pattern to search for.
+          #
+          def grep_records(output_file,pattern)
+            records = filter_records(output_file)
+
+            records.filter { |record| match_record(record,pattern) }
+          end
+
+          #
+          # Determines if the masscan record includes the pattern.
+          #
+          # @param [::Masscan::Status, ::Masscan::Banner] record
+          #   The masscan record to search.
+          #
+          # @param [String] pattern
+          #   The pattern to search for.
+          #
+          # @return [Boolean]
+          #   Indicates whether the masscan record contains the pattern.
+          #
+          def match_record(record,pattern)
+            case record
+            when ::Masscan::Banner
+              record.app_protocol.match(pattern) ||
+                record.payload.match(pattern)
+            end
+          end
+
+          #
+          # Prints the open ports for the IP.
+          #
+          # @param [Array<::Masscan::Status, ::Masscan::Banner>] records
+          #   The masscan records to print.
+          #
+          # @param [String] pattern
+          #   The pattern to highlight.
+          #
+          def highlight_records(records,pattern)
+            records.group_by(&:ip).each do |ip,records_for_ip|
+              puts "[ #{ip} ]"
+              puts
+
+              records_for_ip.group_by { |record|
+                [record.port, record.protocol]
+              }.each do |(port,protocol),records_for_port|
+                indent do
+                  puts "#{port}/#{protocol}"
+
+                  indent do
+                    records_for_port.each do |record|
+                      highlight_record(record,pattern)
+                    end
+                  end
+                end
+              end
+
+              puts
+            end
+          end
+
+          #
+          # Prints the masscan record with the pattern highlighted.
+          #
+          # @param [::Masscan:Status, ::Masscan::Banner] record
+          #   The masscan record to print.
+          #
+          # @param [String] pattern
+          #   The pattern to highlight.
+          #
+          def highlight_record(record,pattern)
+            case record
+            when ::Masscan::Banner
+              highlight_banner_record(record,pattern)
+            end
+          end
+
+          #
+          # Prints the masscan banner record with the pattern highlighted.
+          #
+          # @param [::Masscan::Banner] banner
+          #   The masscan banner record to print.
+          #
+          # @param [String] pattern
+          #   The pattern to highlight.
+          #
+          def highlight_banner_record(banner,pattern)
+            payload      = highlight(banner.payload,pattern)
+            app_protocol = highlight(banner.app_protocol,pattern)
+
+            if payload.include?("\n") # multiline?
+              puts app_protocol
+
+              indent do
+                payload.chomp.each_line(chomp: true) do |line|
+                  puts line
+                end
+              end
+            else
+              puts "#{app_protocol}\t#{payload}"
+            end
+          end
+
+          #
+          # Highlights the pattern in the text.
+          #
+          # @param [String] text
+          #   The text to modify.
+          #
+          # @param [String] pattern
+          #   The pattern to highlight.
+          #
+          # @return [String]
+          #   The modified text.
+          #
+          def highlight(text,pattern)
+            text.to_s.gsub(pattern,colors.red(pattern))
+          end
+
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# 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'
+
+module Ronin
+  module Masscan
+    class CLI
+      module Commands
+        #
+        # The `ronin-masscan import` command.
+        #
+        # ## Usage
+        #
+        #   ronin-masscan import [options] MASSCAN_FILE
+        #
+        # ## Options
+        #
+        #         --db NAME                    The database to connect to (Default: default)
+        #         --db-uri URI                 The database URI to connect to
+        #     -F binary|list|json|ndjson,      Specifies the format of the scan file
+        #         --format
+        #     -h, --help                       Print help information
+        #
+        # ## Arguments
+        #
+        #     MASSCAN_FILE                     The masscan scan file to import
+        #
+        class Import < Command
+
+          include Importable
+
+          usage '[options] MASSCAN_FILE'
+
+          option :format, short: '-F',
+                          value: {
+                            type: ::Masscan::OutputFile::PARSERS.keys
+                          },
+                          desc: 'Specifies the format of the scan file'
+
+          argument :masscan_file, required: true,
+                                  desc:     'The masscan scan file to import'
+
+          description 'Imports a masscan scan file into ronin-db'
+
+          man_page 'ronin-masscan-import.1'
+
+          #
+          # Runs the `ronin-masscan import` command.
+          #
+          # @param [String] masscan_file
+          #   The masscan scan file to import.
+          #
+          def run(masscan_file)
+            unless File.file?(masscan_file)
+              print_error "no such file or directory: #{masscan_file}"
+              exit(1)
+            end
+
+            require 'ronin/db'
+            require 'ronin/masscan/importer'
+
+            DB.connect
+
+            if options[:format]
+              import_file(masscan_file, format: options[:format])
+            else
+              import_file(masscan_file)
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,203 @@
+# 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/root'
+
+require 'ronin/core/cli/generator'
+
+module Ronin
+  module Masscan
+    class CLI
+      module Commands
+        #
+        # ## Usage
+        #
+        #     ronin-masscan new [options] FILE
+        #
+        # ## Options
+        #
+        #         --parser                     Generate a masscan output file parser script
+        #         --scanner                    Generate a masscan scanner script
+        #         --printing                   Adds additional printing of the masscan scan data
+        #         --import                     Also import the masscan scan data
+        #         --output-file OUTPUT_FILE    Sets the output file to write to or parse
+        #     -p {PORT | [PORT1]-[PORT2]},..., Sets the port range to scan
+        #         --ports
+        #         --ips {IP | IP-range}[,..]   Sets the targets to scan (Defaults: ARGV[0])
+        #     -h, --help                       Print help information
+        #
+        # ## Arguments
+        #
+        #     PATH                             The path to the new masscan ruby script
+        #
+        # ## Examples
+        #
+        #     ronin-masscan new scanner.rb --ports 22,80,443,8000-9000 --ips '192.168.1.*'
+        #     ronin-masscan new parser.rb --parser --output-file path/to/masscan.bin --printing
+        #
+        class New < Command
+
+          include Core::CLI::Generator
+
+          template_dir File.join(ROOT,'data','templates')
+
+          usage '[options] FILE'
+
+          option :parser, desc: 'Generate a masscan output file parser script' do
+            @script_type = :parser
+          end
+
+          option :scanner, desc: 'Generate a masscan scanner script' do
+            @script_type = :scanner
+          end
+
+          option :printing, desc: 'Adds additional printing of the masscan scan data' do
+            @features[:printing] = true
+          end
+
+          option :import, desc: 'Also import the masscan scan data' do
+            @features[:import] = true
+          end
+
+          option :output_file, value: {
+                                 type:  String,
+                                 usage: 'OUTPUT_FILE'
+                               },
+                               desc: 'Sets the output file to write to or parse' do |file|
+                                 @output_file = file
+                               end
+
+          option :ports, short: '-p',
+                         value: {
+                           type:  String,
+                           usage: '{PORT | [PORT1]-[PORT2]},...'
+                         },
+                         desc: 'Sets the port range to scan' do |ports|
+                           @ports = parse_port_range(ports)
+                         rescue ArgumentError => error
+                           raise(OptionParser::InvalidArgument,error.message)
+                         end
+
+          option :ips, value: {
+                         type:  String,
+                         usage: '{IP | IP-range}[,..]'
+                       },
+                       desc: 'Sets the IPs to scan (Defaults: ARGV)' do |ips|
+                         @ips << ips
+                       end
+
+          argument :path, desc: 'The path to the new masscan ruby script'
+
+          description 'Generates a new masscan ruby script'
+
+          man_page 'ronin-masscan-new.1'
+
+          examples [
+            "scanner.rb --ports 22,80,443,8000-9000 --ips '192.168.1.*'",
+            "parser.rb --parser --output-file path/to/masscan.bin --printing"
+          ]
+
+          # The script type.
+          #
+          # @return [:scanner, :parser]
+          attr_reader :script_type
+
+          # The optioanl output file to write to or parse.
+          #
+          # @return [String, nil]
+          attr_reader :output_file
+
+          # The optional ports to scan.
+          #
+          # @return [Array<Integer, Range(Integer,Integer)>, nil]
+          attr_reader :ports
+
+          # The IP addresses or ranges to scan.
+          #
+          # @return [Array<String>]
+          attr_reader :ips
+
+          # Additional features.
+          #
+          # @return [Hash{Symbol => Boolean}]
+          attr_reader :features
+
+          #
+          # Initializes the `ronin-masscan new` command.
+          #
+          # @param [Hash{Symbol => Object}] kwargs
+          #   Additional keyword arguments for the command.
+          #
+          def initialize(**kwargs)
+            super(**kwargs)
+
+            @script_type = :scanner
+            @ips         = []
+            @features    = {}
+          end
+
+          #
+          # Runs the `ronin-masscan new` command.
+          #
+          # @param [String] file
+          #   The path to the new masscan ruby script.
+          #
+          def run(file)
+            @directory  = File.dirname(file)
+
+            mkdir @directory unless File.directory?(@directory)
+
+            erb "script.rb.erb", file
+            chmod '+x', file
+          end
+
+          #
+          # Parses a port range.
+          #
+          # @param [String] ports
+          #   The port range to parse.
+          #
+          # @return [Array<Integer, Range(Integer,Integer)>]
+          #   The parsed port range.
+          #
+          # @raise [ArgumentError]
+          #   An invalid port range was given.
+          #
+          def parse_port_range(ports)
+            ports.split(',').map do |port|
+              case port
+              when /\A\d+-\d+\z/
+                start, stop = port.split('-',2)
+
+                (start.to_i..stop.to_i)
+              when /\A\d+\z/
+                port.to_i
+              else
+                raise(ArgumentError,"invalid port range: #{ports.inspect}")
+              end
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,162 @@
+# 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/filtering_options'
+
+require 'masscan/output_file'
+require 'command_kit/printing/indent'
+
+module Ronin
+  module Masscan
+    class CLI
+      module Commands
+        #
+        # Prints the scanned IPs and ports from masscan scan file(s).
+        #
+        # ## Usage
+        #
+        #     ronin-masscan print [options] MASSCAN_FILE [...]
+        #
+        # ## Options
+        #
+        #     -P, --protocol tcp|udp           Filters the targets by protocol
+        #         --ip IP                      Filters the targets by IP
+        #         --ip-range CIDR              Filters the targets by IP range
+        #         -p, --ports {PORT | PORT1-PORT2},...
+        #                                      Filter targets by port number
+        #         --with-app-protocol APP_PROTOCOL[,...]
+        #                                      Filters targets with the app protocol
+        #         --with-payload STRING        Filters targets containing the payload
+        #         --with-payload-regex /REGEX/ Filters targets with the matching payload
+        #     -h, --help                       Print help information
+        #
+        # ## Arguments
+        #
+        #     MASSCAN_FILE ...                 The masscan scan file(s) to parse
+        #
+        class Print < Command
+
+          usage '[options] MASSCAN_FILE [...]'
+
+          include CommandKit::Printing::Indent
+          include FilteringOptions
+
+          argument :masscan_file, required: true,
+                                  repeats:  true,
+                                  desc:     'The masscan scan file(s) to parse'
+
+          description 'Prints the scanned IPs and ports from masscan scan file(s)'
+
+          man_page 'ronin-masscan-print.1'
+
+          #
+          # Runs the `ronin-masscan print` command.
+          #
+          # @param [Array<String>] masscan_files
+          #   The nmap `.xml` files to parse.
+          #
+          def run(*masscan_files)
+            masscan_files.each do |masscan_file|
+              output_file = begin
+                              ::Masscan::OutputFile.new(masscan_file)
+                            rescue ArgumentError => error
+                              print_error(error.message)
+                              exit(1)
+                            end
+
+              records = filter_records(output_file)
+
+              print_records(records)
+            end
+          end
+
+          #
+          # Prints the open ports for the IP.
+          #
+          # @param [Array<::Masscan::Status, ::Masscan::Banner>] records
+          #
+          def print_records(records)
+            records.group_by(&:ip).each do |ip,records_for_ip|
+              puts "[ #{ip} ]"
+              puts
+
+              records_for_ip.group_by { |record|
+                [record.port, record.protocol]
+              }.each_value do |records_for_port|
+                status  = records_for_port.first
+                banners = records_for_port[1..]
+
+                indent do
+                  print_status_record(status)
+
+                  unless banners.empty?
+                    indent do
+                      banners.each do |banner|
+                        print_banner_record(banner)
+                      end
+                    end
+
+                    puts
+                  end
+                end
+              end
+            end
+          end
+
+          #
+          # Prints a masscan status record.
+          #
+          # @param [::Masscan::Status] status
+          #   The status record that indicates whether a port is open or not.
+          #
+          def print_status_record(status)
+            puts "#{status.port}/#{status.protocol}\t#{status.status}"
+          end
+
+          #
+          # Prints a masscan banner record.
+          #
+          # @param [::Masscan::Banner] banner
+          #   The banner record that contains additional information about the
+          #   port's service.
+          #
+          def print_banner_record(banner)
+            payload      = banner.payload
+            app_protocol = banner.app_protocol
+
+            if payload.include?("\n") # multiline?
+              puts app_protocol
+
+              indent do
+                payload.chomp.each_line(chomp: true) do |line|
+                  puts line
+                end
+              end
+            else
+              puts "#{app_protocol}\t#{payload}"
+            end
+          end
+
+        end
+      end
+    end
+  end
+end