ronin-masscan 0.1.0.rc1

data/data/templates/script.rb.erb

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+
+require 'ronin/masscan'
+
+<%- if @script_type == :parser -%>
+<%-   if @output_file -%>
+output_file = Ronin::Masscan.parse(<%= @output_file.inspect %>)
+<%-   else -%>
+output_file = Ronin::Masscan.parse(ARGV[0])
+<%-   end -%>
+<%- else -%>
+output_file = Ronin::Masscan.scan do |masscan|
+<%-   case @ips.length -%>
+<%-   when 0 -%>
+  masscan.ips         = ARGV
+<%-   when 1 -%>
+  masscan.ips         = <%= @ips[0].inspect %>
+<%-   else -%>
+  masscan.ips         = <%= @ips.inspect %>
+<%-   end -%>
+<%-   if @ports -%>
+  masscan.ports       = <%= @ports.inspect %>
+<%-   else -%>
+  # masscan.ports       = [22, 80, 443, 8000..9000]
+<%-   end -%>
+<%-   if @output_file -%>
+  masscan.output_file = <%= @output_file.inspect %>
+<%-   else -%>
+  # masscan.output_file = "path/to/masscan.bin"
+<%-   end -%>
+end
+<%- end -%>
+<% if @features[:printing] -%>
+
+output_file.each do |record|
+  p record
+end
+<%- end -%>
+<%- if @features[:import] -%>
+
+Ronin::DB.connect
+Ronin::Masscan::Importer.import(output_file)
+<%- end -%>

data/gemspec.yml

@@ -0,0 +1,42 @@
+name: ronin-masscan
+summary: A Ruby library and CLI for working with masscan.
+description: |
+  ronin-masscan is a Ruby library for working with masscan. ronin-masscan can
+  parse masscan scan files, convert masscan files into JSON or CSV, or import
+  masscan scan data into the ronin-db database.
+
+license: LGPL-3.0
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: https://ronin-rb.dev/
+has_yard: true
+
+metadata:
+  documentation_uri: https://ronin-rb.dev/docs/ronin-masscan
+  source_code_uri:   https://github.com/ronin-rb/ronin-masscan
+  bug_tracker_uri:   https://github.com/ronin-rb/ronin-masscan/issues
+  changelog_uri:     https://github.com/ronin-rb/ronin-masscan/blob/main/ChangeLog.md
+  rubygems_mfa_required: 'true'
+
+generated_files:
+ - data/completions/ronin-masscan
+ - man/ronin-masscan.1
+ - man/ronin-masscan-completion.1
+ - man/ronin-masscan-convert.1
+ - man/ronin-masscan-dump.1
+ - man/ronin-masscan-grep.1
+ - man/ronin-masscan-import.1
+ - man/ronin-masscan-new.1
+ - man/ronin-masscan-print.1
+ - man/ronin-masscan-scan.1
+
+required_ruby_version: ">= 3.0.0"
+
+dependencies:
+  ruby-masscan: ~> 0.1
+  # Ronin dependencies:
+  ronin-core: ~> 0.2.0.rc1
+  ronin-db: ~> 0.2.0.rc1
+
+development_dependencies:
+  bundler: ~> 2.0

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

@@ -0,0 +1,40 @@
+# 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/root'
+
+require 'ronin/core/cli/command'
+
+module Ronin
+  module Masscan
+    class CLI
+      #
+      # Base class for all other `ronin-masscan` commands.
+      #
+      class Command < Core::CLI::Command
+
+        man_dir File.join(ROOT,'man')
+
+        bug_report_url 'https://github.com/ronin-rb/ronin-masscan/issues/new'
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# 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/root'
+require 'ronin/core/cli/completion_command'
+
+module Ronin
+  module Masscan
+    class CLI
+      module Commands
+        #
+        # Manages the shell completion rules for `ronin-masscan`.
+        #
+        # ## Usage
+        #
+        #     ronin-masscan completion [options]
+        #
+        # ## Options
+        #
+        #         --print                      Prints the shell completion file
+        #         --install                    Installs the shell completion file
+        #         --uninstall                  Uninstalls the shell completion file
+        #     -h, --help                       Print help information
+        #
+        # ## Examples
+        #
+        #     ronin-masscan completion --print
+        #     ronin-masscan completion --install
+        #     ronin-masscan completion --uninstall
+        #
+        class Completion < Core::CLI::CompletionCommand
+
+          completion_file File.join(ROOT,'data','completions','ronin-masscan')
+
+          man_dir File.join(ROOT,'man')
+          man_page 'ronin-masscan-completion.1'
+
+          description 'Manages the shell completion rules for ronin-masscan'
+
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,133 @@
+# 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/converter'
+
+module Ronin
+  module Masscan
+    class CLI
+      module Commands
+        #
+        # Converts an masscan scan file to JSON or CSV.
+        #
+        # ## Usage
+        #
+        #     ronin-masscan convert [options] INPUT_FILE [OUTPUT_FILE]
+        #
+        # ## Option
+        #
+        #     -I binary|list|json|ndjson,      The input format
+        #         --input-format
+        #     -F, --format json|csv            The desired output format
+        #     -h, --help                       Print help information
+        #
+        # ## Arguments
+        #
+        #     INPUT_FILE                       The input masscan scan file to parse
+        #     OUTPUT_FILE                      The output file
+        #
+        class Convert < Command
+
+          usage '[options] MASSCAN_FILE [OUTPUT_FILE]'
+
+          option :input_format, short: '-I',
+                                value: {
+                                  type: [:binary, :list, :json, :ndjson]
+                                },
+                                desc: 'The input format'
+
+          option :format, short: '-F',
+                          value: {
+                            type:     [:json, :csv],
+                            required: true
+                          },
+                          desc: 'The desired output format'
+
+          argument :input_file, required: true,
+                                desc:     'The input masscan scan file to convert'
+
+          argument :output_file, required: false,
+                                 desc:     'The output file'
+
+          description "Converts an masscan scan file to JSON or CSV"
+
+          man_page 'ronin-masscan-convert.1'
+
+          #
+          # Runs the `ronin-masscan convert` command.
+          #
+          # @param [String] input_file
+          #   The masscan scan file to parse.
+          #
+          # @param [String] output_file
+          #   The output file to write to.
+          #
+          def run(input_file,output_file=nil)
+            unless File.file?(input_file)
+              print_error "no such file or directory: #{input_file}"
+              exit(-1)
+            end
+
+            masscan_file = open_masscan_file(input_file)
+
+            if output_file
+              format = options.fetch(:format) do
+                         Converter.infer_format_for(output_file)
+                       end
+
+              File.open(output_file,'w') do |output|
+                Converter.convert(masscan_file,output, format: format)
+              end
+            else
+              unless (format = options[:format])
+                print_error "must specify a --format if no output file is given"
+                exit(-1)
+              end
+
+              Converter.convert(masscan_file,stdout, format: format)
+            end
+          end
+
+          #
+          # Opens a masscan scan file.
+          #
+          # @param [String] path
+          #   The path to the masscan scan file.
+          #
+          # @return [::Masscan::OutputFile]
+          #   The opened masscan scan file.
+          #
+          def open_masscan_file(path)
+            if options[:input_format]
+              ::Masscan::OutputFile.new(path, format: options[:input_format])
+            else
+              ::Masscan::OutputFile.new(path)
+            end
+          rescue ArgumentError => error
+            print_error(error.message)
+            exit(1)
+          end
+
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,194 @@
+# 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 'set'
+
+module Ronin
+  module Masscan
+    class CLI
+      module Commands
+        #
+        # Dumps the scanned ports from masscan scan file(s).
+        #
+        # ## Usage
+        #
+        #     ronin-masscan dump [options] MASSCAN_FILE [...]
+        #
+        # ## Options
+        #
+        #         --print-ips                  Print all IP addresses
+        #         --print-hosts                Print all hostnames
+        #         --print-ip-ports             Print IP:PORT pairs. (Default)
+        #         --print-host-ports           Print HOST:PORT pairs
+        #         --print-uris                 Print URIs
+        #     -P, --protocol tcp|udp           Filters the targets by protocol
+        #         --ip IP                      Filters the targets by IP
+        #         --ip-range CIDR              Filter the targets by IP range
+        #         -p, --ports {PORT | PORT1-PORT2},...
+        #                                      Filter targets by port number
+        #     -h, --help                       Print help information
+        #
+        # ## Arguments
+        #
+        #     MASSCAN_FILE ...                 The masscan scan file(s) to parse
+        #
+        # ## Examples
+        #
+        #     ronin-masscan dump --print-ip-ports masscan.bin
+        #     ronin-masscan dump --print-ip-ports --ports 22,80,443 masscan.bin
+        #     ronin-masscan dump --print-host-ports masscan.bin
+        #     ronin-masscan dump --print-hosts --with-port 22 masscan.bin
+        #     ronin-masscan dump --print-uris masscan.bin
+        #
+        class Dump < Command
+
+          usage '[options] MASSCAN_FILE [...]'
+
+          option :print_ips, desc: 'Print all IP addresses' do
+            @mode = :ips
+          end
+
+          option :print_hosts, desc: 'Print all hostnames' do
+            @mode = :hostnames
+          end
+
+          option :print_ip_ports, desc: 'Print IP:PORT pairs. (Default)' do
+            @mode = :ip_ports
+          end
+
+          option :print_host_ports, desc: 'Print HOST:PORT pairs' do
+            @mode = :host_ports
+          end
+
+          option :print_uris, desc: 'Print URIs' do
+            @mode = :uris
+          end
+
+          include FilteringOptions
+
+          argument :masscan_file, required: true,
+                                  repeats:  true,
+                                  desc:     'The masscan scan file(s) to parse'
+
+          examples [
+            '--print-ip-ports masscan.bin',
+            '--print-ip-ports --ports 22,80,443 masscan.bin',
+            '--print-host-ports masscan.bin',
+            '--print-hosts --with-port 22 masscan.bin',
+            '--print-uris masscan.bin'
+          ]
+
+          description 'Dumps the scanned ports from masscan scan file(s)'
+
+          man_page 'ronin-masscan-dump.1'
+
+          #
+          # Initializes the command.
+          #
+          # @param [Hash{Symbol => Object}] kwargs
+          #   Additional keywords for the command.
+          #
+          def initialize(**kwargs)
+            super(**kwargs)
+
+            @mode = :ip_ports
+          end
+
+          #
+          # Runs the `ronin-masscan dump` command.
+          #
+          # @param [Array<String>] masscan_files
+          #   The masscan scan file(s) 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
+
+              filter_records(output_file).each do |target|
+                print_target(target)
+              end
+            end
+          end
+
+          #
+          # Prints the target.
+          #
+          # @param [::Masscan::Status, ::Masscan::Banner] host
+          #
+          def print_target(host)
+            case @mode
+            when :ips      then print_ip(host)
+            when :ip_ports then print_ip_ports(host)
+            when :uris     then print_uri(host)
+            end
+          end
+
+          #
+          # Prints the IPs for the target.
+          #
+          # @param [::Masscan::Status, ::Masscan::Banner] target
+          #
+          def print_ip(target)
+            puts target.ip
+          end
+
+          #
+          # Prints the `IP:PORT` pair for the target.
+          #
+          # @param [::Masscan::Status, ::Masscan::Banner] target
+          #
+          def print_ip_ports(target)
+            puts "#{target.ip}:#{target.port}"
+          end
+
+          #
+          # Prints the URIs for the target.
+          #
+          # @param [::Masscan::Status, ::Masscan::Banner] target
+          #
+          def print_uri(target)
+            case target.port
+            when 80
+              puts URI::HTTP.build(
+                host: target.ip.to_s,
+                port: target.port
+              )
+            when 443
+              puts URI::HTTPS.build(
+                host: target.ip.to_s,
+                port: target.port
+              )
+            end
+          end
+
+        end
+      end
+    end
+  end
+end