ronin-masscan 0.1.0.rc1

data/lib/ronin/masscan/importer.rb

@@ -0,0 +1,214 @@
+# 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/db'
+require 'masscan/output_file'
+
+module Ronin
+  module Masscan
+    #
+    # Handles importing masscan output files file into [ronin-db].
+    #
+    # [ronin-db]: https://github.com/ronin-rb/ronin-db#readme
+    #
+    # ## Examples
+    #
+    #     require 'ronin/masscan/importer'
+    #
+    #     Ronin::DB.connect
+    #     Ronin::Masscan::Importer.import_file('masscan.scan') do |record|
+    #       puts "Imported #{record.inspect}!"
+    #     end
+    #
+    module Importer
+      #
+      # Imports a masscan output file into the database.
+      #
+      # @param [String] path
+      #   The path to the masscan output file.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments for `Masscan::OutputFile#initialize`.
+      #
+      # @option kwargs [:binary, :list, :json, :ndjson] :format
+      #   The format of the output file. If not given, the format will be
+      #   inferred from the file extension.
+      #
+      # @yield [imported]
+      #   The given block will be passed each imported database record.
+      #
+      # @yieldparam [Ronin::DB::IPAddress, Ronin::DB::Port, Ronin::DB::OpenPort] imported
+      #
+      # @raise [ArgumentError]
+      #   The output format was not given and it cannot be inferred.
+      #
+      def self.import_file(path,**kwargs,&block)
+        output_file = ::Masscan::OutputFile.new(path,**kwargs)
+
+        import(output_file,&block)
+      end
+
+      #
+      # Imports the masscan output file.
+      #
+      # @param [::Masscan::OutputFile] output_file
+      #
+      # @yield [imported]
+      #   The given block will be passed each imported database record.
+      #
+      # @yieldparam [Ronin::DB::IPAddress, Ronin::DB::Port, Ronin::DB::OpenPort] imported
+      #
+      def self.import(output_file,&block)
+        return enum_for(__method__,output_file).to_a unless block
+
+        output_file.each do |record|
+          case record
+          when ::Masscan::Status
+            import_status(record,&block)
+          when ::Masscan::Banner
+            # TODO: somehow import the banner data
+          else
+            raise(NotImplementedError,"unable to import masscan record: #{record.inspect}")
+          end
+        end
+      end
+
+      #
+      # Imports a `Masscan::Status` record into the database.
+      #
+      # @param [::Masscan::Status] status
+      #   The `Masscan::Status` record.
+      #
+      # @yield [imported]
+      #   The given block will be passed each imported database record.
+      #
+      # @yieldparam [Ronin::DB::IPAddress, Ronin::DB::Port, Ronin::DB::OpenPort] imported
+      #   An imported IP address, port number, or open port record.
+      #
+      # @return [Ronin::DB::OpenPort, Ronin::DB::IPAddress, nil]
+      #   The imported open port, or an IP address if the status was an ICMP
+      #   probe, or `nil` if the status did not represent an open port.
+      #
+      def self.import_status(status,&block)
+        # only import open ports
+        if status.status == :open
+          if status.protocol == :icmp
+            # only import the IP address for ICMP statuses
+            import_ip_address(status.ip,&block)
+          else
+            import_open_port_status(status,&block)
+          end
+        end
+      end
+
+      #
+      # Imports an open port `Masscan::Status` record into the database.
+      #
+      # @param [::Masscan::Status] status
+      #   The `Masscan::Status` record.
+      #
+      # @yield [imported]
+      #   The given block will be passed each imported database record.
+      #
+      # @yieldparam [Ronin::DB::IPAddress, Ronin::DB::Port, Ronin::DB::OpenPort] imported
+      #   An imported IP address, port number, or open port record.
+      #
+      # @return [Ronin::DB::OpenPort]
+      #   The imported open port.
+      #
+      def self.import_open_port_status(status,&block)
+        imported_ip_address = import_ip_address(status.ip,&block)
+        imported_port       = import_port(status.port,status.protocol,&block)
+        imported_open_port  = DB::OpenPort.transaction do
+                                DB::OpenPort.find_or_create_by(
+                                  ip_address: imported_ip_address,
+                                  port:       imported_port
+                                )
+                              end
+
+        imported_open_port.update(last_scanned_at: status.timestamp)
+
+        yield imported_open_port if block_given?
+        return imported_open_port
+      end
+
+      #
+      # Imports an IP address into the database.
+      #
+      # @param [IPAddr] ip_addr
+      #   The IP address object to import.
+      #
+      # @yield [imported]
+      #   The given block will be passed the imported IP address record.
+      #
+      # @yieldparam [Ronin::DB::IPAddress] imported
+      #   The imported IP address record.
+      #
+      # @return [Ronin::DB::IPAddress]
+      #   The imported IP address record.
+      #
+      def self.import_ip_address(ip_addr,&block)
+        ip_version = if ip_addr.ipv6? then 6
+                     else                  4
+                     end
+
+        imported_ip_address = DB::IPAddress.transaction do
+                                DB::IPAddress.find_or_create_by(
+                                  version: ip_version,
+                                  address: ip_addr.to_s
+                                )
+                              end
+
+        yield imported_ip_address if block_given?
+        return imported_ip_address
+      end
+
+      #
+      # Imports the port.
+      #
+      # @param [Integer] port
+      #   The port number to import.
+      #
+      # @param [:tcp, :udp] protocol
+      #   The protocol of the port.
+      #
+      # @yield [imported]
+      #   The given block will be passed the imported port record.
+      #
+      # @yieldparam [Ronin::DB::Port] imported
+      #   The imported port record.
+      #
+      # @return [Ronin::DB::Port]
+      #   The imported port record.
+      #
+      def self.import_port(port,protocol,&block)
+        imported_port = DB::Port.transaction do
+                          DB::Port.find_or_create_by(
+                            protocol: protocol,
+                            number:   port
+                          )
+                        end
+
+        yield imported_port if block_given?
+        return imported_port
+      end
+    end
+  end
+end

data/lib/ronin/masscan/root.rb

@@ -0,0 +1,28 @@
+# 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
+    # Path to `ronin-masscan` root directory.
+    #
+    # @api private
+    ROOT = File.expand_path(File.join(__dir__,'..','..','..'))
+  end
+end

data/lib/ronin/masscan/version.rb

@@ -0,0 +1,26 @@
+# 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
+    # ronin-masscan version
+    VERSION = '0.1.0.rc1'
+  end
+end

data/lib/ronin/masscan.rb

@@ -0,0 +1,114 @@
+# 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/exceptions'
+require 'ronin/masscan/importer'
+require 'ronin/core/home'
+require 'masscan/command'
+require 'masscan/output_file'
+
+require 'tempfile'
+require 'fileutils'
+
+module Ronin
+  #
+  # Top-level methods for `ronin-masscan`.
+  #
+  module Masscan
+    # The `~/.cache/ronin-masscan` cache directory.
+    #
+    # @api private
+    CACHE_DIR = Core::Home.cache_dir('ronin-masscan')
+
+    #
+    # Runs `masscan` and parses the saved output data.
+    #
+    # @param [Array<#to_s>] ips
+    #   The IP addresses to scan.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments for `masscan`.
+    #
+    # @return [::Masscan::OutputFile]
+    #   If the `masscan` command was sucessful, the parsed masscan data will be
+    #   returned.
+    #
+    # @raise [NotInstalled]
+    #   The `masscan` command is not installed.
+    #
+    # @raise [ScanFailed]
+    #   The `masscan` scan failed.
+    #
+    # @see https://rubydoc.info/gems/ruby-masscan/Masscan/OutputFile
+    #
+    # @api public
+    #
+    def self.scan(*ips,**kwargs,&block)
+      masscan = ::Masscan::Command.new(ips: ips, **kwargs,&block)
+
+      masscan.ips ||= ips
+
+      unless masscan.output_file
+        FileUtils.mkdir_p(CACHE_DIR)
+        tempfile = Tempfile.new(['masscan', '.json'], CACHE_DIR)
+
+        masscan.output_file = tempfile.path
+      end
+
+      status = masscan.run_command
+
+      case status
+      when nil
+        raise(NotInstalled,"the masscan command is not installed")
+      when false
+        raise(ScanFailed,"masscan scan failed: #{masscan.command_argv.join(' ')}")
+      else
+        parse(masscan.output_file)
+      end
+    end
+
+    #
+    # Parses a masscan output file.
+    #
+    # @param [String] path
+    #   The path to the output file.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments for `::Masscan::OutputFile.new`.
+    #
+    # @option kwargs [:binary, :list, :json, :ndjson] :format
+    #   The format of the output file. If not specified, the format will be
+    #   inferred from the path's file extension.
+    #
+    # @return [::Masscan::OutputFile]
+    #   The parsed masscan output file.
+    #
+    # @raise [ArgumentError]
+    #   The output format was not given and it cannot be inferred.
+    #
+    # @see https://rubydoc.info/gems/ruby-masscan/Masscan/OutputFile
+    #
+    # @api public
+    #
+    def self.parse(path,**kwargs)
+      ::Masscan::OutputFile.new(path,**kwargs)
+    end
+  end
+end

data/man/ronin-masscan-completion.1

@@ -0,0 +1,76 @@
+.\" Generated by kramdown-man 1.0.1
+.\" https://github.com/postmodern/kramdown-man#readme
+.TH ronin-masscan-completion 1 "2024-01-01" Ronin Masscan "User Manuals"
+.SH NAME
+.PP
+ronin\-masscan\-completion \- Manages shell completion rules for \fBronin\-masscan\fR
+.SH SYNOPSIS
+.PP
+\fBronin\-masscan completion\fR \[lB]\fIoptions\fP\[rB]
+.SH DESCRIPTION
+.PP
+The \fBronin\-masscan completion\fR command can print, install, or uninstall shell
+completion rules for the \fBronin\-masscan\fR command\.
+.PP
+Supports installing completion rules for Bash or Zsh shells\.
+Completion rules for the Fish shell is currently not supported\.
+.SS ZSH SUPPORT
+.PP
+Zsh users will have to add the following lines to their \fB\[ti]\[sl]\.zshrc\fR file in
+order to enable Zsh\[cq]s Bash completion compatibility layer:
+.PP
+.RS 4
+.EX
+autoload \-Uz \[pl]X compinit && compinit
+autoload \-Uz \[pl]X bashcompinit && bashcompinit
+.EE
+.RE
+.SH OPTIONS
+.TP
+\fB\-\-print\fR
+Prints the shell completion file\.
+.TP
+\fB\-\-install\fR
+Installs the shell completion file\.
+.TP
+\fB\-\-uninstall\fR
+Uninstalls the shell completion file\.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Prints help information\.
+.SH ENVIRONMENT
+.TP
+\fIPREFIX\fP
+Specifies the root prefix for the file system\.
+.TP
+\fIHOME\fP
+Specifies the home directory of the user\. Ronin will search for the
+\fB\[ti]\[sl]\.cache\[sl]ronin\-masscan\fR cache directory within the home directory\.
+.TP
+\fIXDG\[ru]DATA\[ru]HOME\fP
+Specifies the data directory to use\. Defaults to \fB\[Do]HOME\[sl]\.local\[sl]share\fR\.
+.SH FILES
+.TP
+\fB\[ti]\[sl]\.local\[sl]share\[sl]bash\-completion\[sl]completions\[sl]\fR
+The user\-local installation directory for Bash completion files\.
+.TP
+\fB\[sl]usr\[sl]local\[sl]share\[sl]bash\-completion\[sl]completions\[sl]\fR
+The system\-wide installation directory for Bash completions files\.
+.TP
+\fB\[sl]usr\[sl]local\[sl]share\[sl]zsh\[sl]site\-functions\[sl]\fR
+The installation directory for Zsh completion files\.
+.SH EXAMPLES
+.TP
+\fBronin\-masscan completion \-\-print\fR
+Prints the shell completion rules instead of installing them\.
+.TP
+\fBronin\-masscan completion \-\-install\fR
+Installs the shell completion rules for \fBronin\-masscan\fR\.
+.TP
+\fBronin\-masscan completion \-\-uninstall\fR
+Uninstalls the shell completion rules for \fBronin\-masscan\fR\.
+.SH AUTHOR
+.PP
+Postmodern 
+.MT postmodern\.mod3\[at]gmail\.com
+.ME

data/man/ronin-masscan-completion.1.md

@@ -0,0 +1,78 @@
+# ronin-masscan-completion 1 "2024-01-01" Ronin Masscan "User Manuals"
+
+## NAME
+
+ronin-masscan-completion - Manages shell completion rules for `ronin-masscan`
+
+## SYNOPSIS
+
+`ronin-masscan completion` [*options*]
+
+## DESCRIPTION
+
+The `ronin-masscan completion` command can print, install, or uninstall shell
+completion rules for the `ronin-masscan` command.
+
+Supports installing completion rules for Bash or Zsh shells.
+Completion rules for the Fish shell is currently not supported.
+
+### ZSH SUPPORT
+
+Zsh users will have to add the following lines to their `~/.zshrc` file in
+order to enable Zsh's Bash completion compatibility layer:
+
+    autoload -Uz +X compinit && compinit
+    autoload -Uz +X bashcompinit && bashcompinit
+
+## OPTIONS
+
+`--print`
+: Prints the shell completion file.
+
+`--install`
+: Installs the shell completion file.
+
+`--uninstall`
+: Uninstalls the shell completion file.
+
+`-h`, `--help`
+: Prints help information.
+
+## ENVIRONMENT
+
+*PREFIX*
+: Specifies the root prefix for the file system.
+
+*HOME*
+: Specifies the home directory of the user. Ronin will search for the
+  `~/.cache/ronin-masscan` cache directory within the home directory.
+
+*XDG_DATA_HOME*
+: Specifies the data directory to use. Defaults to `$HOME/.local/share`.
+
+## FILES
+
+`~/.local/share/bash-completion/completions/`
+: The user-local installation directory for Bash completion files.
+
+`/usr/local/share/bash-completion/completions/`
+: The system-wide installation directory for Bash completions files.
+
+`/usr/local/share/zsh/site-functions/`
+: The installation directory for Zsh completion files.
+
+## EXAMPLES
+
+`ronin-masscan completion --print`
+: Prints the shell completion rules instead of installing them.
+
+`ronin-masscan completion --install`
+: Installs the shell completion rules for `ronin-masscan`.
+
+`ronin-masscan completion --uninstall`
+: Uninstalls the shell completion rules for `ronin-masscan`.
+
+## AUTHOR
+
+Postmodern <postmodern.mod3@gmail.com>
+

data/man/ronin-masscan-convert.1

@@ -0,0 +1,37 @@
+.\" Generated by kramdown-man 1.0.1
+.\" https://github.com/postmodern/kramdown-man#readme
+.TH ronin-masscan-convert 1 "2023-03-01" Ronin Masscan "User Manuals"
+.SH NAME
+.PP
+ronin\-masscan\-convert \- Converts an masscan scan file to JSON or CSV
+.SH SYNOPSIS
+.PP
+\fBronin\-masscan convert\fR \[lB]\fB\-\-format\fR \fBjson\fR\[or]\fBcsv\fR\[rB] \fIINPUT\[ru]FILE\fP \[lB]\fIOUTPUT\[ru]FILE\fP\[rB]
+.SH DESCRIPTION
+.PP
+Converts an masscan scan file to JSON or CSV\.
+.SH ARGUMENTS
+.TP
+\fIINPUT\[ru]FILE\fP
+The masscan scan file to import\.
+.TP
+\fIOUTPUT\[ru]FILE\fP
+The optional output file to write to\.
+.SH OPTIONS
+.TP
+\fB\-I\fR, \fB\-\-input\-format\fR \fBbinary\fR\[or]\fBlist\fR\[or]\fBjson\fR\[or]\fBndjson\fR
+Specifies the format of the \fIINPUT\[ru]FILE\fP\. If not specified the input format
+will be inferred from the \fIINPUT\[ru]FILE\fP file extension\.
+.TP
+\fB\-F\fR, \fB\-\-format\fR \fBjson\fR\[or]\fBcsv\fR
+Sets the output conversion format to JSON or CSV\. If the option is not given,
+the output conversion format Will be inferred from the \fIOUTPUT\[ru]FILE\fP file
+extension\.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help information
+.SH AUTHOR
+.PP
+Postmodern 
+.MT postmodern\.mod3\[at]gmail\.com
+.ME

data/man/ronin-masscan-convert.1.md

@@ -0,0 +1,40 @@
+# ronin-masscan-convert 1 "2023-03-01" Ronin Masscan "User Manuals"
+
+## NAME
+
+ronin-masscan-convert - Converts an masscan scan file to JSON or CSV
+
+## SYNOPSIS
+
+`ronin-masscan convert` [`--format` `json`\|`csv`] *INPUT_FILE* [*OUTPUT_FILE*]
+
+## DESCRIPTION
+
+Converts an masscan scan file to JSON or CSV.
+
+## ARGUMENTS
+
+*INPUT_FILE*
+: The masscan scan file to import.
+
+*OUTPUT_FILE*
+: The optional output file to write to.
+
+## OPTIONS
+
+`-I`, `--input-format` `binary`\|`list`\|`json`\|`ndjson`
+: Specifies the format of the *INPUT_FILE*. If not specified the input format
+  will be inferred from the *INPUT_FILE* file extension.
+
+`-F`, `--format` `json`|`csv`
+: Sets the output conversion format to JSON or CSV. If the option is not given,
+  the output conversion format Will be inferred from the *OUTPUT_FILE* file
+  extension.
+
+`-h`, `--help`
+: Print help information
+
+## AUTHOR
+
+Postmodern <postmodern.mod3@gmail.com>
+