ruby-masscan 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 221aba609e42676f60a8ff8ca50017f52b107ce4bbfd09b2d17fac243e876db8
+  data.tar.gz: 92ffeee1fd37297f5a1731fb2af18d5409c99ceda7704beab4f762e9270e85e3
+SHA512:
+  metadata.gz: f3cb61b85ec433a38a77e5f3993902fb48c340ee8eb6a2476ad98afc8369f33a55ade52fb75f55bcde9f36251da1cea84e5215f717b33821af733744d22087e6
+  data.tar.gz: 4224460de4162eeb091db2d5d194e66eec3c81bea585c64101adadbfc9c959dfdecae482c7c607717d828f2922ef82b99c2d52f99a0b146153cafe3b8e724add

data/.document

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

data/.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

data/.github/workflows/ruby.yml

@@ -0,0 +1,29 @@
+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
+          - truffleruby
+    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

data/.gitignore

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

data/.rspec

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

data/.yardopts

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

data/ChangeLog.md

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

data/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

data/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.

data/README.md

@@ -0,0 +1,139 @@
+# 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)
+[![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 the `masscan` command.
+* 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.format
+# => :list
+```
+
+Parse `masscan` Binary output files:
+
+```ruby
+output_file = Masscan::OutputFile.new('masscan.scan', format: :binary)
+output_file.each do |record|
+  p record
+end
+```
+
+```
+#<struct Masscan::Status status=:open, protocol=:tcp, port=80, reason=[:syn, :ack], ttl=54, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-26 16:07:33 -0700, mac=nil>
+#<struct Masscan::Status status=:open, protocol=:tcp, port=443, reason=[:syn, :ack], ttl=54, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-26 16:07:33 -0700, mac=nil>
+#<struct Masscan::Status status=:open, protocol=:icmp, port=0, reason=[], ttl=54, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-26 16:07:33 -0700, mac=nil>
+#<struct Masscan::Banner protocol=:tcp, port=443, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-26 16:07:35 -0700, app_protocol=:ssl3, payload="TLS/1.1 cipher:0xc013, www.example.org, www.example.org, example.com, example.edu, example.net, example.org, www.example.com, www.example.edu, www.example.net">
+#<struct Masscan::Banner protocol=:tcp, port=443, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-26 16:07:35 -0700, app_protocol=:x509_cert, payload="MIIG1TCCBb2gAwIBAgIQD74IsIVNBXOKsMzhya/uyTANBgkqhkiG9w0BAQsFADBPMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMSkwJwYDVQQDEyBEaWdpQ2VydCBUTFMgUlNBIFNIQTI1NiAyMDIwIENBMTAeFw0yMDExMjQwMDAwMDBaFw0yMTEyMjUyMzU5NTlaMIGQMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLTG9zIEFuZ2VsZXMxPDA6BgNVBAoTM0ludGVybmV0IENvcnBvcmF0aW9uIGZvciBBc3NpZ25lZCBOYW1lcyBhbmQgTnVtYmVyczEYMBYGA1UEAxMPd3d3LmV4YW1wbGUub3JnMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuvzuzMoKCP8Okx2zvgucA5YinrFPEK5RQP1TX7PEYUAoBO6i5hIAsIKFmFxtW2sghERilU5rdnxQcF3fEx3sY4OtY6VSBPLPhLrbKozHLrQ8ZN/rYTb+hgNUeT7NA1mP78IEkxAj4qG5tli4Jq41aCbUlCt7equGXokImhC+UY5IpQEZS0tKD4vu2ksZ04Qetp0k8jWdAvMA27W3EwgHHNeVGWbJPC0Dn7RqPw13r7hFyS5TpleywjdY1nB7ad6kcZXZbEcaFZ7ZuerA6RkPGE+PsnZRb1oFJkYoXimsuvkVFhWeHQXCGC1cuDWSrM3cpQvOzKH2vS7d15+zGls4IwIDAQABo4IDaTCCA2UwHwYDVR0jBBgwFoAUt2ui6qiqhIx56rTaD5iyxZV2ufQwHQYDVR0OBBYEFCYa+OSxsHKEztqBBtInmPvtOj0XMIGBBgNVHREEejB4gg93d3cuZXhhbXBsZS5vcmeCC2V4YW1wbGUuY29tggtleGFtcGxlLmVkdYILZXhhbXBsZS5uZXSCC2V4YW1wbGUub3Jngg93d3cuZXhhbXBsZS5jb22CD3d3dy5leGFtcGxlLmVkdYIPd3d3LmV4YW1wbGUubmV0MA4GA1UdDwEB/wQEAwIFoDAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwgYsGA1UdHwSBgzCBgDA+oDygOoY4aHR0cDovL2NybDMuZGlnaWNlcnQuY29tL0RpZ2lDZXJ0VExTUlNBU0hBMjU2MjAyMENBMS5jcmwwPqA8oDqGOGh0dHA6Ly9jcmw0LmRpZ2ljZXJ0LmNv">
+#<struct Masscan::Banner protocol=:tcp, port=80, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-26 16:07:35 -0700, app_protocol=:http_server, payload="ECS (sec/97A6)">
+#<struct Masscan::Banner protocol=:tcp, port=80, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-26 16:07:35 -0700, app_protocol=:html_title, payload="404 - Not Found">
+#<struct Masscan::Banner protocol=:tcp, port=80, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-26 16:07:35 -0700, app_protocol=:http, payload="HTTP/1.0 404 Not Found\r\nContent-Type: text/html\r\nDate: Thu, 26 Aug 2021 23:07:35 GMT\r\nServer: ECS (sec/97A6)\r\nContent-Length: 345\r\nConnection: close\r\n\r">
+```
+
+Parse `masscan` simple list output files:
+
+```ruby
+output_file = Masscan::OutputFile.new('masscan.txt', format: :list)
+output_file.each do |record|
+  p record
+end
+```
+
+```
+#<struct Masscan::Status status=:open, protocol=:tcp, port=443, reason=nil, ttl=nil, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:47:50 -0700, mac=nil>
+#<struct Masscan::Status status=:open, protocol=:tcp, port=80, reason=nil, ttl=nil, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:47:50 -0700, mac=nil>
+#<struct Masscan::Status status=:open, protocol=:icmp, port=0, reason=nil, ttl=nil, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:47:50 -0700, mac=nil>
+#<struct Masscan::Banner protocol=:tcp, port=443, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:47:52 -0700, app_protocol=:ssl3, payload="TLS/1.1 cipher:0xc013, www.example.org, www.example.org, example.com, example.edu, example.net, example.org, www.example.com, www.example.edu, www.example.net">
+#<struct Masscan::Banner protocol=:tcp, port=443, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:47:52 -0700, app_protocol=:x509, payload="MIIG1TCCBb2gAwIBAgIQD74IsIVNBXOKsMzhya/uyTANBgkqhkiG9w0BAQsFADBPMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMSkwJwYDVQQDEyBEaWdpQ2VydCBUTFMgUlNBIFNIQTI1NiAyMDIwIENBMTAeFw0yMDExMjQwMDAwMDBaFw0yMTEyMjUyMzU5NTlaMIGQMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLTG9zIEFuZ2VsZXMxPDA6BgNVBAoTM0ludGVybmV0IENvcnBvcmF0aW9uIGZvciBBc3NpZ25lZCBOYW1lcyBhbmQgTnVtYmVyczEYMBYGA1UEAxMPd3d3LmV4YW1wbGUub3JnMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuvzuzMoKCP8Okx2zvgucA5YinrFPEK5RQP1TX7PEYUAoBO6i5hIAsIKFmFxtW2sghERilU5rdnxQcF3fEx3sY4OtY6VSBPLPhLrbKozHLrQ8ZN/rYTb+hgNUeT7NA1mP78IEkxAj4qG5tli4Jq41aCbUlCt7equGXokImhC+UY5IpQEZS0tKD4vu2ksZ04Qetp0k8jWdAvMA27W3EwgHHNeVGWbJPC0Dn7RqPw13r7hFyS5TpleywjdY1nB7ad6kcZXZbEcaFZ7ZuerA6RkPGE+PsnZRb1oFJkYoXimsuvkVFhWeHQXCGC1cuDWSrM3cpQvOzKH2vS7d15+zGls4IwIDAQABo4IDaTCCA2UwHwYDVR0jBBgwFoAUt2ui6qiqhIx56rTaD5iyxZV2ufQwHQYDVR0OBBYEFCYa+OSxsHKEztqBBtInmPvtOj0XMIGBBgNVHREEejB4gg93d3cuZXhhbXBsZS5vcmeCC2V4YW1wbGUuY29tggtleGFtcGxlLmVkdYILZXhhbXBsZS5uZXSCC2V4YW1wbGUub3Jngg93d3cuZXhhbXBsZS5jb22CD3d3dy5leGFtcGxlLmVkdYIPd3d3LmV4YW1wbGUubmV0MA4GA1UdDwEB/wQEAwIFoDAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwgYsGA1UdHwSBgzCBgDA+oDygOoY4aHR0cDovL2NybDMuZGlnaWNlcnQuY29tL0RpZ2lDZXJ0VExTUlNBU0hBMjU2MjAyMENBMS5jcmwwPqA8oDqGOGh0dHA6Ly9jcmw0LmRpZ2ljZXJ0LmNv">
+#<struct Masscan::Banner protocol=:tcp, port=80, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:47:52 -0700, app_protocol=:http_server, payload="ECS (sec/974D)">
+#<struct Masscan::Banner protocol=:tcp, port=80, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:47:52 -0700, app_protocol=:html_title, payload="404 - Not Found">
+#<struct Masscan::Banner protocol=:tcp, port=80, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:47:52 -0700, app_protocol=:http, payload="HTTP/1.0 404 Not Found\\x0d\\x0aContent-Type: text/html\\x0d\\x0aDate: Thu, 26 Aug 2021 06:47:52 GMT\\x0d\\x0aServer: ECS (sec/974D)\\x0d\\x0aContent-Length: 345\\x0d\\x0aConnection: close\\x0d\\x0a\\x0d">
+```
+
+Parse `masscan` JSON output files:
+
+```ruby
+output_file = Masscan::OutputFile.new('masscan.json', format: :json)
+output_file.each do |record|
+  p record
+end
+```
+
+```
+#<struct Masscan::Status status=:open, protocol=:tcp, port=80, reason=[:syn, :ack], ttl=54, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:50:21 -0700, mac=nil>
+#<struct Masscan::Status status=:open, protocol=:tcp, port=443, reason=[:syn, :ack], ttl=54, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:50:21 -0700, mac=nil>
+#<struct Masscan::Status status=:open, protocol=:icmp, port=0, reason=["none"], ttl=54, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:50:22 -0700, mac=nil>
+#<struct Masscan::Banner protocol=:tcp, port=80, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:50:24 -0700, app_protocol=:http_server, payload="ECS (sec/974D)">
+#<struct Masscan::Banner protocol=:tcp, port=80, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:50:24 -0700, app_protocol=:html_title, payload="404 - Not Found">
+#<struct Masscan::Banner protocol=:tcp, port=80, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:50:24 -0700, app_protocol=:http, payload="HTTP/1.0 404 Not Found\r\nContent-Type: text/html\r\nDate: Thu, 26 Aug 2021 06:50:24 GMT\r\nServer: ECS (sec/974D)\r\nContent-Length: 345\r\nConnection: close\r\n\r">
+#<struct Masscan::Banner protocol=:tcp, port=443, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:50:33 -0700, app_protocol=:ssl3, payload="TLS/1.1 cipher:0xc013, www.example.org, www.example.org, example.com, example.edu, example.net, example.org, www.example.com, www.example.edu, www.example.net">
+#<struct Masscan::Banner protocol=:tcp, port=443, ip=#<IPAddr: IPv4:93.184.216.34/255.255.255.255>, timestamp=2021-08-25 23:50:33 -0700, app_protocol=:x509, payload="MIIG1TCCBb2gAwIBAgIQD74IsIVNBXOKsMzhya/uyTANBgkqhkiG9w0BAQsFADBPMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMSkwJwYDVQQDEyBEaWdpQ2VydCBUTFMgUlNBIFNIQTI1NiAyMDIwIENBMTAeFw0yMDExMjQwMDAwMDBaFw0yMTEyMjUyMzU5NTlaMIGQMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLTG9zIEFuZ2VsZXMxPDA6BgNVBAoTM0ludGVybmV0IENvcnBvcmF0aW9uIGZvciBBc3NpZ25lZCBOYW1lcyBhbmQgTnVtYmVyczEYMBYGA1UEAxMPd3d3LmV4YW1wbGUub3JnMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuvzuzMoKCP8Okx2zvgucA5YinrFPEK5RQP1TX7PEYUAoBO6i5hIAsIKFmFxtW2sghERilU5rdnxQcF3fEx3sY4OtY6VSBPLPhLrbKozHLrQ8ZN/rYTb+hgNUeT7NA1mP78IEkxAj4qG5tli4Jq41aCbUlCt7equGXokImhC+UY5IpQEZS0tKD4vu2ksZ04Qetp0k8jWdAvMA27W3EwgHHNeVGWbJPC0Dn7RqPw13r7hFyS5TpleywjdY1nB7ad6kcZXZbEcaFZ7ZuerA6RkPGE+PsnZRb1oFJkYoXimsuvkVFhWeHQXCGC1cuDWSrM3cpQvOzKH2vS7d15+zGls4IwIDAQABo4IDaTCCA2UwHwYDVR0jBBgwFoAUt2ui6qiqhIx56rTaD5iyxZV2ufQwHQYDVR0OBBYEFCYa+OSxsHKEztqBBtInmPvtOj0XMIGBBgNVHREEejB4gg93d3cuZXhhbXBsZS5vcmeCC2V4YW1wbGUuY29tggtleGFtcGxlLmVkdYILZXhhbXBsZS5uZXSCC2V4YW1wbGUub3Jngg93d3cuZXhhbXBsZS5jb22CD3d3dy5leGFtcGxlLmVkdYIPd3d3LmV4YW1wbGUubmV0MA4GA1UdDwEB/wQEAwIFoDAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwgYsGA1UdHwSBgzCBgDA+oDygOoY4aHR0cDovL2NybDMuZGlnaWNlcnQuY29tL0RpZ2lDZXJ0VExTUlNBU0hBMjU2MjAyMENBMS5jcmwwPqA8oDqGOGh0dHA6Ly9jcmw0LmRpZ2ljZXJ0LmNv">
+```
+
+## 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

data/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

data/gemspec.yml

@@ -0,0 +1,28 @@
+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
+
+metadata:
+  documentation_uri: https://rubydoc.info/gems/ruby-masscan
+  source_code_uri:   https://github.com/postmodern/ruby-masscan
+  bug_tracker_uri:   https://github.com/postmodern/ruby-masscan/issues
+  changelog_uri:     https://github.com/postmodern/ruby-masscan/blob/master/ChangeLog.md
+
+required_ruby_version: ">= 2.0.0"
+
+requirements: masscan >= 1.0.0
+
+dependencies:
+  rprogram: ~> 0.3
+
+development_dependencies:
+  bundler: ~> 2.0

data/lib/masscan/banner.rb

@@ -0,0 +1,11 @@
+module Masscan
+  #
+  # Represents a banner record.
+  #
+  class Banner < Struct.new(:protocol,:port,:ip,:timestamp,:app_protocol,:payload)
+
+    alias service app_protocol
+    alias banner payload
+
+  end
+end

data/lib/masscan/output_file.rb

@@ -0,0 +1,100 @@
+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
+
+    # The parser for the output file format.
+    #
+    # @return [Parsers::Binary, Parsers::JSON, Parsers::List]
+    attr_reader :parser
+
+    #
+    # Initializes the output file.
+    #
+    # @param [String] path
+    #   The path to the output file.
+    #
+    # @param [:binary, :list, :json, :ndjson] format
+    #   The format of the output file. Defaults to {infer_format}.
+    #
+    # @raise [ArgumentError]
+    #   The output format was not given and it cannot be inferred.
+    #
+    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
+    #   The path to the output file.
+    #
+    # @return [:binary, :list, :json, :ndjson]
+    #   The output format inferred from the file's extension name.
+    #
+    # @raise [ArgumentError]
+    #   The output format could not be inferred from the file's name.
+    #
+    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]
+    #   If a block is given, it will be passed each parsed record.
+    #
+    # @yield [Status, Banner] record
+    #   A parsed record, either a {Status} or a {Banner}.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an Enumerator will be returned.
+    #
+    def each(&block)
+      return enum_for(__method__) unless block
+
+      @parser.open(@path) do |file|
+        @parser.parse(file,&block)
+      end
+    end
+
+  end
+end

data/lib/masscan/parsers/binary.rb

@@ -0,0 +1,591 @@
+require 'masscan/status'
+require 'masscan/banner'
+
+require 'socket'
+
+module Masscan
+  module Parsers
+    #
+    # Parses the `masscan -oB` output format.
+    #
+    # @note Ported from https://github.com/robertdavidgraham/masscan/blob/1.3.2/src/in-binary.c
+    #
+    # @api semipublic
+    #
+    module Binary
+      #
+      # Opens a binary 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]
+      #   The opened file.
+      #
+      # @return [File]
+      #   If no block was given, the opened file will be returned.
+      #
+      def self.open(path,&block)
+        File.open(path,'rb',&block)
+      end
+
+      class CorruptedFile < RuntimeError
+      end
+
+      # Maximum buffer length for a single record.
+      BUF_MAX = 1024 * 1024
+
+      #
+      # Parses masscan binary data.
+      #
+      # @param [IO] 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?
+
+        pseudo = read_pseudo_record(io)
+
+        # look for the start time
+        if (match = pseudo.match(/s:(\d+)/))
+          start_time = decode_timestamp(match[1].to_i)
+        end
+
+        total_records = 0
+
+        # read all records
+        loop do
+          # read the TYPE field
+          unless (type = read_multibyte_uint(io))
+            return
+          end
+
+          # read the LENGTH field
+          unless (length = read_multibyte_uint(io))
+            return
+          end
+
+          if length > BUF_MAX
+            raise(CorruptedFile,"file corrupted")
+          end
+
+          # read the remainder of the record
+          buffer = io.read(length)
+
+          if buffer.length < length
+            return
+          end
+
+          # parse the specific record type
+          record = case type
+                   when 1 # STATUS: open
+                     parse_status(buffer,:open)
+                   when 2 # STATUS: closed
+                     parse_status(buffer,:closed)
+                   when 3 # BANNER
+                     parse_banner3(buffer)
+                   when 4
+                     io.getbyte
+                     parse_banner4(buffer)
+                   when 5
+                     parse_banner4(buffer)
+                   when 6 # STATUS: open
+                     parse_status2(buffer,:open)
+                   when 7 # STATUS: closed
+                     parse_status2(buffer,:closed)
+                   when 9
+                     parse_banner9(buffer)
+                   when 10 # Open6
+                     parse_status6(buffer,:open)
+                   when 11 # Closed6
+                     parse_status6(buffer,:closed)
+                   when 13 # Banner6
+                     parse_banner6(buffer)
+                   when 109 # 'm'.ord # FILEHEADER
+                     next
+                   else
+                     raise(CorruptedFile,"unknown type: #{type.inspect}")
+                   end
+
+          if record
+            start_time ||= record.timestamp
+
+            yield record
+
+            total_records += 1
+          end
+        end
+
+        return total_records
+      end
+
+      # The "pseudo record" length
+      PSEUDO_RECORD_SIZE = 99 # 'a'.ord + 2
+
+      # Masscan binary format version compatibility.
+      MASSCAN_VERSION_FAMILY = "1.1"
+
+      # The `masscan` binary format magic string.
+      MASSCAN_MAGIC = "masscan/#{MASSCAN_VERSION_FAMILY}"
+
+      #
+      # Reads the "pseudo record" at the beginning of the file.
+      #
+      # @param [IO] io
+      #   The IO object to read from.
+      #
+      # @return [String]
+      #   The read buffer.
+      #
+      def self.read_pseudo_record(io)
+        buffer = io.read(PSEUDO_RECORD_SIZE)
+
+        if buffer.length < PSEUDO_RECORD_SIZE
+          raise(CorruptedFile,"invalid masscan binary format")
+        end
+
+        unless buffer.start_with?(MASSCAN_MAGIC)
+          raise(CorruptedFile,"unknown file format (expected #{MASSCAN_MAGIC})")
+        end
+
+        return buffer
+      end
+
+      #
+      # Reads a multi-byte unsigned integer.
+      #
+      # @param [IO] io
+      #   The IO object to read from.
+      #
+      # @return [Integer, nil]
+      #   The unsigned integer, or `nil` if End-of-Stream was reached.
+      #
+      def self.read_multibyte_uint(io)
+        unless (b = io.getbyte)
+          return
+        end
+
+        type = b & 0x7f
+
+        while (b & 0x80) != 0
+          unless (b = io.getbyte)
+            return
+          end
+
+          type = (type << 7) | (b & 0x7f)
+        end
+
+        return type
+      end
+
+      #
+      # Decodes a timestamp from an integer.
+      #
+      # @param [Integer] timestamp
+      #   The raw UNIX timestamp integer.
+      #
+      # @return [Time]
+      #   The decoded time value.
+      #
+      def self.decode_timestamp(timestamp)
+        Time.at(timestamp)
+      end
+
+      #
+      # Decodes an IPv4 address from an integer.
+      #
+      # @param [Integer] ip
+      #   The IP in raw integer form.
+      #
+      # @return [IPAddr]
+      #   The decoded IPv4 address.
+      #
+      def self.decode_ipv4(ip)
+        IPAddr.new(ip,Socket::AF_INET)
+      end
+
+      #
+      # Decodes an IPv6 address from two 64bit integers.
+      #
+      # @param [Integer] ipv6_hi
+      #   The top-half of the 128bit IPv6 address.
+      #
+      # @param [Integer] ipv6_lo
+      #   The top-half of the 128bit IPv6 address.
+      #
+      # @return [IPAddr]
+      #   The decoded IPv6 address.
+      #
+      def self.decode_ipv6(ipv6_hi,ipv6_lo)
+        IPAddr.new((ipv6_hi << 64) | ipv6_lo,Socket::AF_INET6)
+      end
+
+      # Mapping of IP protocol numbers to keywords.
+      IP_PROTOCOLS = {
+        Socket::IPPROTO_ICMP   => :icmp,
+        Socket::IPPROTO_ICMPV6 => :icmp,
+
+        Socket::IPPROTO_TCP => :tcp,
+        Socket::IPPROTO_UDP => :udp,
+
+        132 => :sctp # Socket::IPPROTO_SCTP might not always be defined
+      }
+
+      #
+      # Looks up an IP protocol number.
+      #
+      # @param [Integer] proto
+      #   The IP protocol number.
+      #
+      # @return [:icmp, :tcp, :udp, :sctp, nil]
+      #   The IP protocol keyword.
+      #
+      # @see IP_PROTOCOLS
+      #
+      def self.lookup_ip_protocol(proto)
+        IP_PROTOCOLS[proto]
+      end
+
+      #
+      # Decodes a reason bitflag.
+      #
+      # @param [Integer] reason
+      #   The reason bitflag.
+      #
+      # @return [Array<:fin, :syn, :rst, :psh, :ack, :urg, :ece, :cwr>]
+      #   The reason flags.
+      #
+      def self.decode_reason(reason)
+        flags = []
+        flags << :fin if (reason & 0x01) != 0
+        flags << :syn if (reason & 0x02) != 0
+        flags << :rst if (reason & 0x04) != 0
+        flags << :psh if (reason & 0x08) != 0
+        flags << :ack if (reason & 0x10) != 0
+        flags << :urg if (reason & 0x20) != 0
+        flags << :ece if (reason & 0x40) != 0
+        flags << :cwr if (reason & 0x80) != 0
+        flags
+      end
+
+      # List of application protocol keywords.
+      APP_PROTOCOLS = [
+        nil,
+        :heur,
+        :ssh1,
+        :ssh2,
+        :http,
+        :ftp,
+        :dns_versionbind,
+        :snmp,             # simple network management protocol, udp/161
+        :nbtstat,          # netbios, udp/137
+        :ssl3,
+        :smb,              # SMB tcp/139 and tcp/445
+        :smtp,
+        :pop3,
+        :imap4,
+        :udp_zeroaccess,
+        :x509_cert,
+        :html_title,
+        :html_full,
+        :ntp,              # network time protocol, udp/123
+        :vuln,
+        :heartbleed,
+        :ticketbleed,
+        :vnc_rfb,
+        :safe,
+        :memcached,
+        :scripting,
+        :versioning,
+        :coap,         # constrained app proto, udp/5683, RFC7252
+        :telnet,
+        :rdp,          # Microsoft Remote Desktop Protocol tcp/3389
+        :http_server,  # HTTP "Server:" field
+      ]
+
+      #
+      # Looks up an application protocol number.
+      #
+      # @param [Integer] proto
+      #   The application protocol number.
+      #
+      # @return [Symbol, nil]
+      #   The application protocol keyword.
+      #
+      # @see APP_PROTOCOLS
+      #
+      def self.lookup_app_protocol(proto)
+        APP_PROTOCOLS[proto]
+      end
+
+      #
+      # Parses a status record.
+      #
+      # @param [String] buffer
+      #   The buffer to parse.
+      #
+      # @param [:open, :closed] status
+      #   Indicates whether the port status is open or closed.
+      #
+      # @return [Status]
+      #   The parsed status record.
+      #
+      def self.parse_status(buffer,status)
+        if buffer.length < 12
+          return
+        end
+
+        timestamp, ip, port, reason, ttl = buffer.unpack("L>L>S>CC")
+
+        timestamp = decode_timestamp(timestamp)
+        ip        = decode_ipv4(ip)
+        reason    = decode_reason(reason)
+
+        # if ARP, there will be a MAC address after the record
+        mac = if ip == 0 && buffer.length >= 12+6
+                buffer[12+6,6]
+              end
+
+        protocol = case port
+                   when 53, 123, 137, 161 then  :udp
+                   when 36422, 36412, 2905 then :sctp
+                   else                         :tcp
+                   end
+
+        return Status.new(
+          status,
+          protocol,
+          port,
+          ip,
+          timestamp,
+          mac
+        )
+      end
+
+      #
+      # Parses a banner record.
+      #
+      # @param [String] buffer
+      #   The buffer to parse.
+      #
+      # @return [Buffer]
+      #   The parsed buffer record.
+      #
+      def self.parse_banner3(buffer)
+        timestamp, ip, port, app_proto, payload = buffer.unpack('L>L>S>S>A*')
+
+        timestamp = decode_timestamp(timestamp)
+        ip        = decode_ipv4(ip)
+        app_proto = lookup_app_protocol(app_proto)
+
+        # defaults
+        ip_proto = :tcp
+        ttl = 0
+
+        return Banner.new(
+          ip_proto,
+          port,
+          ip,
+          timestamp,
+          app_proto,
+          payload
+        )
+      end
+
+      #
+      # Parses a banner record.
+      #
+      # @param [String] buffer
+      #   The buffer to parse.
+      #
+      # @return [Buffer]
+      #   The parsed buffer record.
+      #
+      def self.parse_banner4(buffer)
+        if buffer.length < 13
+          return
+        end
+
+        timestamp, ip, ip_prot, port, app_proto, payload = buffer.unpack('L>L>CS>S>A*')
+
+        timestamp = decode_timestamp(timestamp)
+        ip        = decode_ipv4(ip)
+        ip_proto  = lookup_ip_protocol(ip_proto)
+        app_proto = lookup_app_protocol(app_proto)
+
+        # defaults
+        ttl = 0
+
+        return Banner.new(
+          ip_proto,
+          port,
+          ip,
+          timestamp,
+          app_proto,
+          payload
+        )
+      end
+
+      #
+      # Parses a status record.
+      #
+      # @param [String] buffer
+      #   The buffer to parse.
+      #
+      # @param [:open, :closed] status
+      #   Indicates whether the port status is open or closed.
+      #
+      # @return [Status]
+      #   The parsed status record.
+      #
+      def self.parse_status2(buffer,status)
+        if buffer.length < 13
+          return
+        end
+
+        timestamp, ip, ip_proto, port, reason, ttl = buffer.unpack('L>L>CS>CC')
+        timestamp = decode_timestamp(timestamp)
+        ip        = decode_ipv4(ip)
+        ip_proto  = lookup_ip_protocol(ip_proto)
+        reason    = decode_reason(reason)
+
+        mac = if ip == 0 && buffer.length >= 13+6
+                buffer[13,6]
+              end
+
+        return Status.new(
+          status,
+          ip_proto,
+          port,
+          reason,
+          ttl,
+          ip,
+          timestamp,
+          mac
+        )
+      end
+
+      #
+      # Parses a banner record.
+      #
+      # @param [String] buffer
+      #   The buffer to parse.
+      #
+      # @return [Buffer]
+      #   The parsed buffer record.
+      #
+      def self.parse_banner9(buffer)
+        if buffer.length < 14
+          return
+        end
+
+        timestamp, ip, ip_proto, port, app_proto, ttl, payload = buffer.unpack('L>L>CS>S>CA*')
+        timestamp = decode_timestamp(timestamp)
+        ip        = decode_ipv4(ip)
+        ip_proto  = lookup_ip_protocol(ip_proto)
+        app_proto = lookup_app_protocol(app_proto)
+
+        return Banner.new(
+          ip_proto,
+          port,
+          ip,
+          timestamp,
+          app_proto,
+          payload
+        )
+      end
+
+      #
+      # Parses a status record.
+      #
+      # @param [String] buffer
+      #   The buffer to parse.
+      #
+      # @param [:open, :closed] status
+      #   Indicates whether the port status is open or closed.
+      #
+      # @return [Status]
+      #   The parsed status record.
+      #
+      def self.parse_status6(buffer,status)
+        timestamp, ip_proto, port, reason, ttl, ip_version, ipv6_hi, ipv6_lo = buffer.unpack('L>CS>CCCQ>Q>')
+        timestamp  ||= 0xffffffff
+        ip_proto   ||= 0xff
+        port       ||= 0xffff
+        reason     ||= 0xff
+        ttl        ||= 0xff
+        ip_version ||= 0xff
+        ipv6_hi    ||= 0xffffffff_ffffffff
+        ipv6_lo    ||= 0xffffffff_ffffffff
+
+        unless ip_version == 6
+          raise(CorruptedFile,"expected ip_version to be 6: #{ip_version.inspect}")
+        end
+
+        timestamp = decode_timestamp(timestamp)
+        ip_proto  = lookup_ip_protocol(ip_proto)
+        reason    = decode_reason(reason)
+        ipv6      = decode_ipv6(ipv6_hi,ipv6_lo)
+
+        return Status.new(
+          status,
+          ip_proto,
+          port,
+          reason,
+          ttl,
+          ipv6,
+          timestamp
+        )
+      end
+
+      #
+      # Parses a banner record.
+      #
+      # @param [String] buffer
+      #   The buffer to parse.
+      #
+      # @return [Buffer]
+      #   The parsed buffer record.
+      #
+      def self.parse_banner6(buffer)
+        timestamp, ip_proto, port, app_proto, ttl, ip_version, ipv6_hi, ipv6_lo, payload = buffer.unpack('L>CS>S>CCQ>Q>A*')
+        timestamp  ||= 0xffffffff
+        protocol   ||= 0xff
+        port       ||= 0xffff
+        app_proto  ||= 0xffff
+        ttl        ||= 0xff
+        ip_version ||= 0xff
+        ipv6_hi    ||= 0xffffffff_ffffffff
+        ipv6_lo    ||= 0xffffffff_ffffffff
+
+        timestamp = decode_timestamp(timestamp)
+        ip_proto  = lookup_ip_protocol(ip_proto)
+        app_proto = lookup_app_protocol(app_proto)
+        ipv6      = decode_ipv6(ipv6_hi,ipv6_lo)
+
+        return Banner.new(
+          ip_proto,
+          port,
+          ipv6,
+          timestamp,
+          app_proto,
+          payload
+        )
+      end
+
+    end
+  end
+end