portfinder 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1224fc61bf2be0a705dbf19dad118f5607099ccd
-  data.tar.gz: 9be215ec8b6ee0f1d959a57acd8d22a5529623c8
+  metadata.gz: 68802b1d01723c118d38ca4c6b34099bda3d73bf
+  data.tar.gz: f3c807ed4f77a5f3e24a36e3160fd7601cdb7eac
 SHA512:
-  metadata.gz: a3167a159694a5617264a8aaf1d018f1a0d55ba6e4848bfc03bf814c5a2007079609db025faf79f7b845e7f74ca598046af036ea408532177b79c2906c5f796f
-  data.tar.gz: 88cab29ed42fc366214600d709d0772817c84367e8e2d001af9670a4c9619e368f38536c13bd2ab5ba89c18aea24c8968c9eb2e6f6817dbda2ef848a568d25c8
+  metadata.gz: 2a7c66777be78c5268037be60ca0a472ac053330ad6a3af54159fcac1c688764eb16550072b30e29c155bc2bffffe17f8625819792fb8b2fcfd3708010d756b6
+  data.tar.gz: ace35b8a20fc2d9014e70d10f906c8ecdc871441f8fe1cb70312a8e6ce7747c99ae6eedea9b8274ca148d684f6317f4002bf08cbd4318d88118c3b3eb045deef

data/.codeclimate.yml

@@ -0,0 +1,18 @@
+engines:
+  rubocop:
+    enabled: true
+    channel: rubocop-0-48
+  markdownlint:
+    enabled: true
+  bundler-audit:
+    enabled: false
+  fixme:
+    enabled: true
+
+ratings:
+  paths:
+  - bin/**
+  - lib/**
+  - "**.rb"
+exclude_paths:
+  - test/**

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/rdoc/
+/pkg/
+/spec/reports/
+/tmp/
+/gemfiles/*.gemfile.lock
+/gemfiles/.bundle

data/.reek

@@ -0,0 +1,26 @@
+# FIXME: Remove
+TooManyStatements:
+  max_statements: 20
+UtilityFunction:
+  enabled: false
+TooManyMethods:
+  max_methods: 20
+TooManyInstanceVariables:
+  max_instance_variables: 15
+NestedIterators:
+  max_allowed_nesting: 3
+LongParameterList:
+  max_params: 5
+ControlParameter:
+  enabled: false
+BooleanParameter:
+  enabled: false
+TooManyConstants:
+  max_constants: 20
+Attribute:
+  enabled: false
+DuplicateMethodCall:
+  enabled: false
+
+exclude_paths:
+  - test

data/.rubocop.yml

@@ -0,0 +1,19 @@
+AllCops:
+  TargetRubyVersion: 2.2
+  Exclude:
+  - "portfinder.gemspec"
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+Style/UnneededCapitalW:
+  Enabled: false
+Style/MethodDefParentheses:
+  Enabled: false
+Metrics/MethodLength:
+  Max: 20
+Metrics/ClassLength:
+  Max: 200
+Metrics/AbcSize:
+  Enabled: false
+# FIXME: Remove
+Performance/RedundantBlockCall:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,29 @@
+sudo: false
+language: ruby
+rvm:
+- 2.2.7
+- 2.3.4
+- 2.4.1
+- ruby-head
+gemfile:
+- gemfiles/slop_4.5.0.gemfile
+- gemfiles/slop_4.4.0.gemfile
+matrix:
+  allow_failures:
+  - rvm: ruby-head
+  fast_finish: true
+cache: bundler
+before_install: gem install bundler
+addons:
+  code_climate:
+    repo_token: ac8817e9eb34cc305959d1b0951195e3615ba8efb80d393c5c8b62baafaac369
+after_success:
+- bundle exec codeclimate-test-reporter
+deploy:
+  provider: rubygems
+  api_key:
+    secure: mZCsES86YL9bLz7X4IzZgGIZjEhfRDSe6v69gwB+HrotdJM2+jUY+MwTGv5KEfcAvlc8nB9EQ0NuX/9bZU77XlajCjdkhpg4+wVxJ9yzo2eoS9eYi6KycFqbw1zMTTOPjA9V9jHtxX+FsmASu/ci1aEQ0qtq6b08XnMdrmhZpwDqmf3XaIHMhPKQxTq0XlnMUZOo0EsuW7jXP6M3D+aEdC+lQi4ObBHXX0b2EZyzKwCCZWqhEMquOr6TL9xLIFWg87uV4DtLcmgGqczvCC0dmUAqS4ZTgkwC8IGec47cIQUTCX4NkirabsdBTFlCz0vd6VCoLZ8CT+9dHkCHJjkobcxeLwhsG0im0TzFh6jyok9gLvhSMHqWxfkTymBh/DHgRx1lXM61UPeIZYih0N/c152FXw0GgrWh6+ikGcNQRwpTEWpvNASqIxllsj8Y0S6SaC1Us5yR/WaV836aUFa2R9ip16oUOWM4LadxYi/IOWu6dzP2fHNXGQf8M1IjDczqzxVT5OBa/vj6m+yyd8jORZHPA2dXFi4pCnZgBr3ps/+HiYNbYEonvHODSORSDweeAXtvFBp8GUvkerGp2szROT9S6k2K8XtG8etA14R0jjBLqQRfoMpzNS9Sn/dQ+Z3z1SQ0yTLz1oVI0KG0QAv5QpRoos8sMEwkbZvY2vwbto4=
+  gem: portfinder
+  on:
+    tags: true
+    repo: at-shakil/portfinder

data/Appraisals

@@ -0,0 +1,7 @@
+appraise "slop-4.5.0" do
+  gem "slop", "~> 4.5.0"
+end
+
+appraise "slop-4.4.0" do
+  gem "slop", "~> 4.4.0"
+end

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Tahmid Shakil
+
+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,174 @@
+# Portfinder
+
+[![Build Status](https://travis-ci.org/at-shakil/portfinder.svg?branch=master)](https://travis-ci.org/at-shakil/portfinder)
+[![Gem Version](https://badge.fury.io/rb/portfinder.svg)](https://badge.fury.io/rb/portfinder)
+[![Dependency Status](https://gemnasium.com/badges/github.com/at-shakil/portfinder.svg)](https://gemnasium.com/github.com/at-shakil/portfinder)
+[![Test Coverage](https://codeclimate.com/github/at-shakil/portfinder/badges/coverage.svg)](https://codeclimate.com/github/at-shakil/portfinder/coverage)
+[![Inline docs](http://inch-ci.org/github/at-shakil/portfinder.svg?branch=master)](http://inch-ci.org/github/at-shakil/portfinder)
+[![Code Climate](https://codeclimate.com/github/at-shakil/portfinder/badges/gpa.svg)](https://codeclimate.com/github/at-shakil/portfinder)
+[![Issue Count](https://codeclimate.com/github/at-shakil/portfinder/badges/issue_count.svg)](https://codeclimate.com/github/at-shakil/portfinder)
+
+## Summary
+
+Portfinder is a ruby based port scanner with features like network/CIDR
+scanning, port randomization, hostname discovery and banner grabbing.
+
+## Installation
+
+Portfinder installation is as simple as a gem installation can get.
+
+```sh
+gem install portfinder
+```
+
+## Usage
+
+### As a CLI tool
+
+```sh
+portfinder <host> [--port=PORT] [--thread=THREAD] [--randomize]
+  [--out=OUT_FILE] [--verbose]
+```
+
+`portfinder` can also be invoked using it's aliased form `pf`.
+
+To it's simplest form, single port of a host can be scanned.
+
+```sh
+portfinder 192.168.1.1 -p 80
+```
+
+It is possible to scan multiple ports of a host. In this case, ports can be a
+*range*,
+
+```sh
+portfinder 192.168.1.1 -p 1-1024
+```
+
+Or, a list of *selections*:
+
+```sh
+portfinder 192.168.1.1 -p 22,80,8080,443
+```
+
+Similarly, a scan can be performed on a selection of hosts,
+
+```sh
+portfinder 192.168.1.1,192.168.1.100,192.168.1.101 -p 1-65535
+```
+
+or, a range of hosts,
+
+```sh
+portfinder 192.168.1.1-10 -p 1-65535
+```
+
+or, on an entire network block, if you like.
+
+```sh
+portfinder 192.168.1.0/24 -p 1-65535
+```
+
+If a large number of host needs to be scanned, you may choose to increase the
+number of concurrent scanners using the available `--thread` option.
+
+```sh
+portfinder 192.168.1.0/24 -p 1-65535 -t 20
+```
+
+By default, ten scanner threads are spawned at max.
+
+When multiple ports are being scanned, they get scanned in the ascending order,
+or in the provided port selection order. If a randomized scan order is expected,
+`--randomize` flag can be utilized.
+
+```sh
+portfinder 192.168.1.0/24 -r
+```
+
+### As an API
+
+A minimal usage example,
+
+```ruby
+require "portfinder"
+
+scanner = Portfinder::Scanner.new("192.168.1.1", [22, 80, 8080], threads = 5)
+scanner.scan
+puts "\nOpen ports detected: #{scanner.result[host]}"
+puts "Raw scan result: #{scanner.result}"
+yml_stream = scanner.report_as "yml"
+json_stream = scanner.json_report
+```
+
+It is possible to use the API in different modes,
+
+#### Mode 1: Blocking mode with monitoring
+
+```ruby
+scanner =
+  Portfinder::Scanner.new(
+    hosts, ports,
+    randomize: false, threaded: true, threads: 10, thread_for: :port
+  )
+
+scanner.log do |monitor|
+  puts "Active threads:\t#{monitor.threads}\nScanning now:\n"
+  while true
+    print "\tHost:\t#{monitor.host}\tPort:\t#{monitor.port}\tStatus: #{
+      monitor.state}\r"
+    sleep 0.1
+  end
+end
+
+scanner.scan
+puts "\nScan complete!\n\nResult: #{scanner.generate_result}"
+
+format = "json"
+file = open("export.#{format}", "wb")
+file.write scanner.report_as format.to_sym
+file.close
+```
+
+#### Mode 2: Partial blocking (join during result invocation)
+
+```ruby
+scanner = Portfinder::Scanner.new("192.168.0.101", 1..65535)
+#logger can be placed here...
+
+scanner.scan synchronus = false
+
+# logger can be placed here...
+puts "\nScan complete!\n\nResult: #{scanner.generate_result}"
+```
+
+#### Mode 3 (GUI): Non-blocking (callback invocation upon completion)
+
+(NOTE: Parent thread must be alive to receive callback)
+
+```ruby
+scanner = Portfinder::Scanner.new("192.168.0.101", 1..65535)
+
+scanner.scan(false) do
+  puts "\nScan complete!\n\nResult: #{scanner.generate_result}"
+end
+
+# logger can be placed here...
+
+sleep 10
+```
+
+Please note that the default scanner scans TCP ports using a full handshake
+(which is not, well..., stealthy. But, if you were expecting this feature, it's
+gonna be available on the TCP SYN scanner release).
+
+It's also worth noting that, the current implementation doesn't check for host
+status (alive/dead). So, scan can be considerably slow for dead hosts.
+
+## Contributing
+
+If you are interested in contributing, please [submit a pull request](https://help.github.com/articles/about-pull-requests/).
+
+## License
+
+[MIT](http://opensource.org/licenses/MIT)

data/Rakefile

@@ -0,0 +1,32 @@
+require "rubygems"
+require "bundler/setup"
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rdoc/task"
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.main = "README.md"
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title    = "Portfinder"
+  rdoc.markup = "markdown"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("README.md")
+  rdoc.rdoc_files.include(
+    [
+      "lib/portfinder.rb", "lib/portfinder/scanner.rb",
+      "lib/portfinder/version.rb"
+    ]
+  )
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :appraise do
+  exec "appraisal install && appraisal rake"
+end
+
+task default: :test

data/bin/pf

@@ -0,0 +1,101 @@
+#!/usr/bin/env ruby
+require "slop"
+require "portfinder"
+require "portfinder/option"
+
+module Portfinder
+  # Portfinder command-line interface base class
+  class CLI
+    def self.start argv
+      new(argv).start
+    end
+
+    def initialize argv
+      @host, options = preprocess argv
+      @options, @help_str = prepare_options options, @host
+    end
+
+    def start
+      @host ? scan(@options) : help
+    end
+
+    def scan options
+      scanner =
+        Portfinder::Scanner.new(
+          options[:host], options[:port],
+          randomize: options[:randomize], threaded: true,
+          threads: options[:thread], thread_for: :port
+        )
+      scanner.scan
+      puts scanner.generate_result true
+    end
+
+    def help
+      puts @help_str
+    end
+
+    def version
+      puts "v#{Portfinder::VERSION}"
+      exit
+    end
+
+    private
+
+    def preprocess argv
+      default_options = ["-h", "--help"]
+      host = argv[0]
+      if default_options.include? host
+        host = nil
+        options = argv
+      else
+        options = argv[1..-1] || []
+      end
+
+      [host, options]
+    end
+
+    # rubocop:disable Style/MethodLength
+    def option_parser
+      opts = Slop::Options.new
+      opts.banner = "Commands:"
+      opts.separator "    portfinder         # Display available options"
+      opts.separator(
+        "    portfinder <host>  # Scans host(s) for provided options"
+      )
+      opts.separator ""
+      opts.separator "Options:"
+      opts.port(
+        "-p", "--port", "# Specify a single port, range or selections",
+        default: 1..1024
+      )
+      opts.int "-t", "--thread", "# Specify threads to spawn", default: 10
+      opts.bool "-r", "--randomize", "# Randomize port scan order"
+      opts.out(
+        "-o", "--out", "# Dump scan result to the specified file",
+        default: "#{@host ? @host.gsub(%r{[./]}, '_') : 'export'}.json"
+      )
+      opts.bool "-v", "--verbose", "# More information during scan"
+      opts.bool "-h", "--help", "# Describe available commands and options"
+
+      Slop::Parser.new opts
+    end
+
+    # Refactor
+    def prepare_options options, host
+      version_opt = ["-V", "--version"]
+      version if version_opt.include?(host)
+
+      parsed = option_parser.parse options
+      parsed_hash = parsed.to_h
+      if host && /^[^-]+/ =~ host
+        parsed_hash.merge!(
+          Slop.parse ["--host", host] { |opt| opt.host "--host" }
+        )
+      end
+
+      [parsed_hash, parsed.to_s]
+    end
+  end
+end
+
+Portfinder::CLI.start ARGV