Initial commit.

.document

@@ -0,0 +1,3 @@
+-
+ChangeLog.md
+LICENSE.txt

.editorconfig

@@ -0,0 +1,11 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+tab_width = 8
+trim_trailing_whitespace = true
+
+[{Gemfile,Rakefile,*.rb,*.gemspec,*.yml}]
+indent_style = space
+indent_size = 2

.github/workflows/ruby.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on: [ push, pull_request ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - 2.4
+          - 2.5
+          - 2.6
+          - 2.7
+          - 3.0
+          - jruby
+    name: Ruby ${{ matrix.ruby }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+      - name: Run tests
+        run: bundle exec rake test

.gitignore

@@ -0,0 +1,11 @@
+/Gemfile.lock
+/coverage
+/doc
+/pkg
+/.yardoc
+.DS_Store
+*.db
+*.log
+*.swp
+*~
+*.gem

.rspec

@@ -0,0 +1 @@
+--colour --format documentation

.yardopts

@@ -0,0 +1 @@
+--markup markdown --title 'Ruby Masscan Documentation' --protected

ChangeLog.md

@@ -0,0 +1,6 @@
+### 0.1.0 / 2021-08-31
+
+* Initial release:
+  * Provides a Ruby interface for running masscan.
+  * Supports parsing masscan Binary, List, and JSON output files.
+

Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'rake'
+  gem 'rubygems-tasks', '~> 0.2'
+  gem 'rspec',          '~> 3.0'
+
+  gem 'json'
+  gem 'simplecov',      '~> 0.7'
+  gem 'kramdown'
+  gem 'yard',           '~> 0.9'
+  gem 'yard-spellcheck', require: false
+end

LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2021 Hal Brodigan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,111 @@
+# ruby-masscan
+
+[![CI](https://github.com/postmodern/ruby-masscan/actions/workflows/ruby.yml/badge.svg)](https://github.com/postmodern/ruby-masscan/actions/workflows/ruby.yml)
+[![Code Climate](https://codeclimate.com/github/postmodern/ruby-masscan.svg)](https://codeclimate.com/github/postmodern/ruby-masscan)
+[![Gem Version](https://badge.fury.io/rb/ruby-masscan.svg)](https://badge.fury.io/rb/ruby-masscan)
+
+* [Source](https://github.com/postmodern/ruby-masscan/)
+* [Issues](https://github.com/postmodern/ruby-masscan/issues)
+* [Documentation](http://rubydoc.info/gems/ruby-masscan/frames)
+
+## Description
+
+A Ruby interface to [masscan], an Internet-scale port scanner.
+Allows automating masscan and parsing masscan Binary, List, and JSON output
+file formats.
+
+## Features
+
+* Provides a Ruby interface for running masscan.
+* Supports parsing masscan Binary, List, and JSON output files.
+
+## Examples
+
+Run `sudo masscan` from Ruby:
+
+```ruby
+require 'masscan/program'
+
+Masscan::Program.sudo_scan do |masscan|
+  masscan.output_format = :list
+  masscan.output_file   = 'masscan.txt'
+
+  masscan.ips   = '192.168.1.1/24'
+  masscan.ports = [20,21,22,23,25,80,110,443,512,522,8080,1080]
+end
+```
+
+Parse a `masscan` output file and guess the format:
+
+```ruby
+require 'masscan/output_file'
+
+output_file = Masscan::OutputFile.new('masscan.txt')
+output_file.each do |record|
+  case record
+  when Masscan::Status
+  when Masscan::Banner
+  end
+end
+```
+
+Parse `masscan` Binary output files:
+
+```ruby
+output_file = Masscan::OutputFile.new('masscan.scan', format: :binary)
+output_file.each do |record|
+  # ...
+end
+```
+
+Parse `masscan` simple list output files:
+
+```ruby
+output_file = Masscan::OutputFile.new('masscan.txt', format: :list)
+output_file.each do |record|
+  # ...
+end
+```
+
+Parse `masscan` JSON output files:
+
+```ruby
+output_file = Masscan::OutputFile.new('masscan.json', format: :json)
+output_file.each do |record|
+  # ...
+end
+```
+
+## Requirements
+
+* [ruby] >= 2.0.0
+* [masscan] >= 1.0.0
+* [rprogram] ~> 0.3
+
+## Install
+
+```shell
+$ gem install ruby-masscan
+```
+
+### gemspec
+
+```ruby
+gemspec.add_dependency 'ruby-masscan', '~> 0.1'
+```
+
+### Gemfile
+
+```ruby
+gem 'ruby-masscan', '~> 0.1'
+```
+
+## License
+
+Copyright (c) 2021 Hal Brodigan
+
+See {file:LICENSE.txt} for license information.
+
+[masscan]: https://github.com/robertdavidgraham/masscan#readme
+[ruby]: https://www.ruby-lang.org/
+[rprogram]: https://github.com/postmodern/rprogram#readme

Rakefile

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+require 'rubygems'
+
+begin
+  require 'bundler/setup'
+rescue LoadError => e
+  warn e.message
+  warn "Run `gem install bundler` to install Bundler"
+  exit -1
+end
+
+require 'rubygems/tasks'
+Gem::Tasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+task :test    => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new
+task :doc => :yard

gemspec.yml

@@ -0,0 +1,22 @@
+name: ruby-masscan
+summary: A Ruby interface to masscan.
+description:
+  A Ruby interface to masscan, an Internet-scale port scanner.
+  Allows automating masscan and parsing masscan Binary, List, JSON, and output
+  file formats.
+
+license: MIT
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: https://github.com/postmodern/ruby-masscan#readme
+has_yard: true
+
+required_ruby_version: ">= 2.0.0"
+
+requirements: masscan >= 1.0.0
+
+dependencies:
+  rprogram: ~> 0.3
+
+development_dependencies:
+  bundler: ~> 2.0

lib/masscan.rb

@@ -0,0 +1,2 @@
+require 'masscan/program'
+require 'masscan/output_file'

lib/masscan/banner.rb

@@ -0,0 +1,4 @@
+module Masscan
+  class Banner < Struct.new(:protocol,:port,:ip,:timestamp,:service,:banner)
+  end
+end

lib/masscan/output_file.rb

@@ -0,0 +1,86 @@
+require 'masscan/parsers/list'
+require 'masscan/parsers/json'
+require 'masscan/parsers/binary'
+
+module Masscan
+  #
+  # Represents an output file.
+  #
+  class OutputFile
+
+    PARSERS = {
+      binary: Parsers::Binary,
+      list:   Parsers::List,
+      json:   Parsers::JSON,
+      ndjson: Parsers::JSON,
+      # xml:    Parsers::XML,
+    }
+
+    # The path to the output file.
+    #
+    # @return [String]
+    attr_reader :path
+
+    # The format of the output file.
+    #
+    # @return [Symbol]
+    attr_reader :format
+
+    #
+    # Initializes the output file.
+    #
+    # @param [String] path
+    #
+    # @param [:binary, :list, :json, :ndjson] format
+    #
+    # @raise [ArgumentError]
+    #
+    def initialize(path, format: self.class.infer_format(path))
+      @path   = path
+      @format = format
+
+      @parser = PARSERS.fetch(format) do
+        raise(ArgumentError,"unknown format: #{format.inspect}")
+      end
+    end
+
+    #
+    # Infers the format from the output file's extension name.
+    #
+    # @param [String] path
+    #
+    # @return [:binary, :list, :json, :ndjson]
+    #
+    # @raise [ArgumentError]
+    #
+    def self.infer_format(path)
+      case File.extname(path)
+      when '.bin', '.dat'     then :binary
+      when '.txt', '.list'    then :list
+      when '.json'            then :json
+      when '.ndjson'          then :ndjson
+      when '.xml'             then :xml
+      else
+        raise(ArgumentError,"could not infer format of #{path}")
+      end
+    end
+
+    #
+    # Parses the contents of the output file.
+    #
+    # @yield [record]
+    #
+    # @yield [Status, Banner] record
+    #
+    # @return [Enumerator]
+    #
+    def each(&block)
+      return enum_for(__method__) unless block
+
+      @parser.open(@path) do |file|
+        @parser.parse(file,&block)
+      end
+    end
+
+  end
+end

lib/masscan/parsers.rb

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