ruby-masscan 0.1.0

data/lib/masscan/parsers/json.rb

@@ -0,0 +1,106 @@
+require 'masscan/parsers/plain_text'
+require 'masscan/status'
+require 'masscan/banner'
+
+require 'json'
+
+module Masscan
+  module Parsers
+    #
+    # Parses the `masscan -oJ` and `masscan --output-format ndjson` output
+    # formats.
+    #
+    # @api semipublic
+    #
+    module JSON
+      extend PlainText
+
+      #
+      # Opens a JSON file for parsing.
+      #
+      # @param [String] path
+      #   The path to the file.
+      #
+      # @yield [file]
+      #   If a block is given, it will be passed the opened file.
+      #   Once the block returns, the file will be closed.
+      #
+      # @yieldparam [File] file
+      #   The opened file.
+      #
+      # @return [File]
+      #   If no block was given, the opened file will be returned.
+      #
+      def self.open(path,&block)
+        File.open(path,&block)
+      end
+
+      #
+      # Parses the masscan JSON or ndjson data.
+      #
+      # @param [#each_line] io
+      #   The IO object to read from.
+      #
+      # @yield [record]
+      #   If a block is given, it will be passed each parsed record.
+      #
+      # @yieldparam [Status, Banner] record
+      #   A parsed record, either a {Status} or a {Banner} object.
+      #
+      # @return [Enumerator]
+      #   If no block is given, it will return an Enumerator.
+      #
+      def self.parse(io)
+        return enum_for(__method__,io) unless block_given?
+
+        io.each_line do |line|
+          line.chomp!
+
+          if line == "," || line == "[" || line == "]"
+            # skip
+          else
+            json = ::JSON.parse(line)
+
+            ip        = parse_ip(json['ip'])
+            timestamp = parse_timestamp(json['timestamp'])
+
+            if (ports_json = json['ports'])
+              if (port_json = ports_json.first)
+                proto  = parse_ip_protocol(port_json['proto'])
+                port   = port_json['port']
+
+                if (service_json = port_json['service'])
+                  service_name   = parse_app_protocol(service_json['name'])
+                  service_banner = service_json['banner']
+
+                  yield Banner.new(
+                    proto,
+                    port,
+                    ip,
+                    timestamp,
+                    service_name,
+                    service_banner
+                  )
+                else
+                  status = parse_status(port_json['status'])
+                  ttl    = port_json['ttl']
+                  reason = parse_reason(port_json['reason'])
+
+                  yield Status.new(
+                    status,
+                    proto,
+                    port,
+                    reason,
+                    ttl,
+                    ip,
+                    timestamp
+                  )
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/masscan/parsers/list.rb

@@ -0,0 +1,84 @@
+require 'masscan/parsers/plain_text'
+require 'masscan/status'
+require 'masscan/banner'
+
+module Masscan
+  module Parsers
+    #
+    # Parses the `masscan -oL` output format.
+    #
+    # @api semipublic
+    #
+    module List
+      extend PlainText
+
+      #
+      # Opens a list file for parsing.
+      #
+      # @param [String] path
+      #   The path to the file.
+      #
+      # @yield [file]
+      #   If a block is given, it will be passed the opened file.
+      #   Once the block returns, the file will be closed.
+      #
+      # @yieldparam [File] file
+      #   The opened file.
+      #
+      # @return [File]
+      #   If no block was given, the opened file will be returned.
+      #
+      def self.open(path,&block)
+        File.open(path,&block)
+      end
+
+      #
+      # Parses the masscan simple list data.
+      #
+      # @param [#each_line] io
+      #   The IO object to read from.
+      #
+      # @yield [record]
+      #   If a block is given, it will be passed each parsed record.
+      #
+      # @yieldparam [Status, Banner] record
+      #   A parsed record, either a {Status} or a {Banner} object.
+      #
+      # @return [Enumerator]
+      #   If no block is given, it will return an Enumerator.
+      #
+      def self.parse(io)
+        return enum_for(__method__,io) unless block_given?
+
+        io.each_line do |line|
+          line.chomp!
+
+          if line.start_with?('open ') || line.start_with?('closed ')
+            type, ip_proto, port, ip, timestamp = line.split(' ',5)
+
+            yield Status.new(
+              parse_status(type),
+              parse_ip_protocol(ip_proto),
+              port.to_i,
+              nil,
+              nil,
+              parse_ip(ip),
+              parse_timestamp(timestamp)
+            )
+          elsif line.start_with?('banner ')
+            type, ip_proto, port, ip, timestamp, app_proto, banner = line.split(' ',7)
+
+            yield Banner.new(
+              parse_ip_protocol(ip_proto),
+              port.to_i,
+              parse_ip(ip),
+              parse_timestamp(timestamp),
+              parse_app_protocol(app_proto),
+              banner
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/masscan/parsers/plain_text.rb

@@ -0,0 +1,151 @@
+module Masscan
+  module Parsers
+    #
+    # Common methods for parsing plain-text data.
+    #
+    # @api private
+    #
+    module PlainText
+      # Mapping of status strings to their keywords.
+      STATUSES = {
+        'open'   => :open,
+        'closed' => :closed
+      }
+
+      #
+      # Parses a status string.
+      #
+      # @param [String] status
+      #   The status string to parse.
+      #
+      # @return [:open, :closed, String]
+      #   The status keyword or a String if the status wasn't in {STATUSES}.
+      #
+      def parse_status(status)
+        STATUSES[status] || status
+      end
+
+      REASONS = {
+        'fin' => :fin,
+        'syn' => :syn,
+        'rst' => :rst,
+        'psh' => :psh,
+        'ack' => :ack,
+        'urg' => :urg,
+        'ece' => :ece,
+        'cwr' => :cwr
+      }
+
+      #
+      # Parses a reason string.
+      #
+      # @param [String] reason
+      #   The reason string to parse.
+      #
+      # @return [Array<:fin, :syn, :rst, :psh, :ack, :urg, :ece, :cwr>]
+      #   The reason keywords or a String if the flag wasn't in {REASONS}.
+      #
+      def parse_reason(reason)
+        flags = reason.split('-')
+        flags.map! { |flag| REASONS[flag] || flag }
+        flags
+      end
+
+      # Mapping of IP protocol names to their keywords.
+      IP_PROTOCOLS = {
+        'tcp'  => :tcp,
+        'udp'  => :udp,
+        'icmp' => :icmp,
+        'sctp' => :sctp
+      }
+
+      #
+      # Parses an IP protocol name.
+      #
+      # @param [String] proto
+      #   The IP protocol name.
+      #
+      # @return [:tcp, :udp, :icmp, :sctp, String]
+      #   The IP protocol keyword or a String if the IP protocol wasn't in
+      #   {IP_PROTOCOLS}.
+      #
+      def parse_ip_protocol(proto)
+        IP_PROTOCOLS[proto] || proto
+      end
+
+      # Mapping of application protocol names to their keywords.
+      APP_PROTOCOLS = {
+        "ssh1" => :ssh1,
+        "ssh2" => :ssh2,
+        "ssh"  => :ssh,
+        "http" => :http,
+        "ftp"  => :ftp,
+        "dns-ver" => :dns_ver,
+        "snmp" => :smtp,
+        "nbtstat" => :nbtstat,
+        "ssl" => :ssl3,
+        "smtp" => :smtp,
+        "smb" => :smb,
+        "pop" => :pop,
+        "imap" => :imap,
+        "X509" => :x509,
+        "zeroaccess" => :zeroaccess,
+        "title" => :html_title,
+        "html" => :html,
+        "ntp" => :ntp,
+        "vuln" => :vuln,
+        "heartbleed" => :heartbleed,
+        "ticketbleed" => :ticketbleed,
+        "vnc" => :vnc,
+        "safe" => :safe,
+        "memcached" => :memcached,
+        "scripting" => :scripting,
+        "versioning" => :versioning,
+        "coap"        => :coap,
+        "telnet"      => :telnet,
+        "rdp"         => :rdp,
+        "http.server" => :http_server
+      }
+
+      #
+      # Parses an application protocol name.
+      #
+      # @param [String] proto
+      #   The application protocol name.
+      #
+      # @return [Symbol, String]
+      #   The IP protocol keyword or a String if the application protocol wasn't
+      #   in {APP_PROTOCOLS}.
+      #
+      def parse_app_protocol(proto)
+        APP_PROTOCOLS[proto] || proto
+      end
+
+      #
+      # Parses a timestamp.
+      #
+      # @param [String] timestamp
+      #   The numeric timestamp value.
+      #
+      # @return [Time]
+      #   The parsed timestamp value.
+      #
+      def parse_timestamp(timestamp)
+        Time.at(timestamp.to_i)
+      end
+
+      #
+      # Parses an IP address.
+      #
+      # @param [String] ip
+      #   The string representation of the IP address.
+      #
+      # @return [IPAddr]
+      #   The parsed IP address.
+      #
+      def parse_ip(ip)
+        IPAddr.new(ip)
+      end
+    end
+  end
+end

data/lib/masscan/parsers.rb

@@ -0,0 +1,3 @@
+require 'masscan/parsers/binary'
+require 'masscan/parsers/list'
+require 'masscan/parsers/json'

data/lib/masscan/program.rb

@@ -0,0 +1,100 @@
+require 'masscan/task'
+
+require 'rprogram/program'
+
+module Masscan
+  #
+  # Represents the `masscan` program.
+  #
+  class Program < RProgram::Program
+
+    name_program 'masscan'
+
+    #
+    # Finds the `masscan` program and performs a scan.
+    #
+    # @param [Hash{Symbol => Object}] options
+    #   Additional options for masscan.
+    #
+    # @param [Hash{Symbol => Object}] exec_options
+    #   Additional exec-options.
+    #
+    # @yield [task]
+    #   If a block is given, it will be passed a task object
+    #   used to specify options for masscan.
+    #
+    # @yieldparam [Task] task
+    #   The masscan task object.
+    #
+    # @return [Boolean]
+    #   Specifies whether the command exited normally.
+    #
+    # @example Specifying `masscan` options via a Hash.
+    #   Masscan::Program.scan(
+    #     ips: '192.168.1.1/24',
+    #     ports: [22, 80, 443],
+    #   )
+    #
+    # @example Specifying `masscan` options via a {Task} object.
+    #   Masscan::Program.scan do |masscan|
+    #     masscan.ips = '192.168.1.1/24'
+    #     masscan.ports = [22, 80, 443]
+    #   end
+    #
+    # @see #scan
+    #
+    def self.scan(options={},exec_options={},&block)
+      find.scan(options,exec_options,&block)
+    end
+
+    #
+    # Finds the `masscan` program and performs a scan, but runs `masscan` under
+    # `sudo`.
+    #
+    # @see scan
+    #
+    # @since 0.8.0
+    #
+    def self.sudo_scan(options={},exec_options={},&block)
+      find.sudo_scan(options,exec_options,&block)
+    end
+
+    #
+    # Performs a scan.
+    #
+    # @param [Hash{Symbol => Object}] options
+    #   Additional options for masscan.
+    #
+    # @param [Hash{Symbol => Object}] exec_options
+    #   Additional exec-options.
+    #
+    # @yield [task]
+    #   If a block is given, it will be passed a task object
+    #   used to specify options for masscan.
+    #
+    # @yieldparam [Task] task
+    #   The masscan task object.
+    #
+    # @return [Boolean]
+    #   Specifies whether the command exited normally.
+    #
+    # @see http://rubydoc.info/gems/rprogram/0.3.0/RProgram/Program#run-instance_method
+    #   For additional exec-options.
+    #
+    def scan(options={},exec_options={},&block)
+      run_task(Task.new(options,&block),exec_options)
+    end
+
+    #
+    # Performs a scan and runs `masscan` under `sudo`.
+    #
+    # @see #scan
+    #
+    # @since 0.8.0
+    #
+    def sudo_scan(options={},exec_options={},&block)
+      sudo_task(Task.new(options,&block),exec_options)
+    end
+
+  end
+end