ssh_scan 0.0.20 → 0.0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7ed1c774b96d1bb34de978e7c39e82d2206e340f
-  data.tar.gz: 873692c2cd13f0aac4e1bc7842deb2cc6858af7e
+  metadata.gz: 504c40725362aee1beeb3795b3ea1fc7eb8af8a8
+  data.tar.gz: fcd896ac346c21474fab15b925562ec5a7c6c3e6
 SHA512:
-  metadata.gz: 25227d81b0b50a3576b8be8266a76fb70e7cac3d72b5c0ac3a764e57b0532fa2541e025e2322139517a1e4661dc049c26af6b6629090402783cf58819a7dcf4d
-  data.tar.gz: fb790b5ddccedcc27d781b9795b5c49b3ad51546fbb9e68b7d434239f5d58047d97e0e02a7c59a15a5f536b32aad7d92d8b981bf97b02e4886321f97566aa509
+  metadata.gz: ed59a66f3da720810d4834c4128c1e3b5effd68e572d46664a5d4151f89d5cc95f9a0094cdc69409d5413b1f643362fcf23289a1a9cfd4fc7f2857ffd31d199e
+  data.tar.gz: e7a761c9eb05247ec41d1fa8acb0b11d7265636934c7b5d76a940d7541212fe6a3675686ee4e8055d8f9fe3fe91d0e080ddd3e7c6cdc444ae7c589f987937879

data/README.md

@@ -99,6 +99,12 @@ Examples:
 - See here for [example output](https://github.com/mozilla/ssh_scan/blob/master/examples/192.168.1.1.json)
 - See here for [example policies](https://github.com/mozilla/ssh_scan/blob/master/config/policies)
 
+## ssh_scan as a service/api?
+
+This project is soley for ssh_scan engine/command-line usage.
+
+If you would like to run ssh_scan as a service, please refer to [the ssh_scan_api project](https://github.com/mozilla/ssh_scan_api)
+
 ## Rubies Supported
 
 This project is integrated with [travis-ci](http://about.travis-ci.org/) and is regularly tested to work with the following rubies:

data/lib/ssh_scan/banner.rb

@@ -7,10 +7,19 @@ module SSHScan
       @string = string
     end
 
+    # Create {SSHScan::Banner} object based on target's SSH banner.
+    # @param string [String] String from which the banner should be
+    #   constructed.
+    # @return [SSHScan::Banner] {SSHScan::Banner} object
+    #   constructed from string.
     def self.read(string)
       return SSHScan::Banner.new(string)
     end
 
+    # Guess target's SSH version.
+    # @return [String] If SSH version string looks like "SSH-1.81"
+    #   or "SSH-number" then return the number, else return
+    #   "unknown"
     def ssh_version()
       if version = @string.match(/SSH-(\d+[\.\d+]+)/)[1]
         return version.to_f
@@ -19,6 +28,10 @@ module SSHScan
       end
     end
 
+    # Guess target's SSH Library (OpenSSH, LibSSH ...).
+    # See {SSHScan::SSHLib} for a list of SSH libraries supported.
+    # @return [SSHScan::SSHLib] Guessed {SSHScan::SSHLib} instance,
+    #   otherwise {SSHScan::SSHLib::Unknown} instance.
     def ssh_lib_guess()
       case @string
       when /OpenSSH/i
@@ -54,6 +67,10 @@ module SSHScan
       end
     end
 
+    # Guess target's OS (Ubuntu, CentOS ...).
+    # See {SSHScan::OS} for a list of OS(s) supported.
+    # @return [SSHScan::OS] Guessed {SSHScan::OS} instance,
+    #   otherwise {SSHScan::OS::Unknown} instance. 
     def os_guess()
       case @string
       when /Ubuntu/i

data/lib/ssh_scan/constants.rb

@@ -3,6 +3,7 @@ require 'ssh_scan/banner'
 require 'ssh_scan/protocol'
 
 module SSHScan
+  # House all the constants we need.
   module Constants
     DEFAULT_CLIENT_BANNER = SSHScan::Banner.new("SSH-2.0-ssh_scan")
     DEFAULT_SERVER_BANNER = SSHScan::Banner.new("SSH-2.0-server")

data/lib/ssh_scan/crypto.rb

@@ -3,13 +3,18 @@ require 'sshkey'
 require 'base64'
 
 module SSHScan
+  # All cryptography related methods.
   module Crypto
+    # House methods helpful in analysing SSH public keys.
     class PublicKey
       def initialize(key)
         @key = key
       end
 
       # Is the current key known to be in our known bad key list
+      # @return [Boolean] true if this {SSHScan::Crypto::PublicKey}
+      #   instance's key is also in {SSHScan::Crypto}'s
+      #   bad_public_keys, otherwise false
       def bad_key?
         SSHScan::Crypto.bad_public_keys.each do |other_key|
           if self.fingerprint_sha256 == other_key.fingerprint_sha256
@@ -20,14 +25,20 @@ module SSHScan
         return false
       end
 
+      # Generate MD5 fingerprint for this {SSHScan::Crypto::PublicKey} instance.
+      # @return [String] formatted MD5 fingerprint
       def fingerprint_md5
         OpenSSL::Digest::MD5.hexdigest(::Base64.decode64(@key)).scan(/../).join(':')
       end
 
+      # Generate SHA1 fingerprint for this {SSHScan::Crypto::PublicKey} instance.
+      # @return [String] formatted SHA1 fingerprint
       def fingerprint_sha1
         OpenSSL::Digest::SHA1.hexdigest(::Base64.decode64(@key)).scan(/../).join(':')
       end
 
+      # Generate SHA256 fingerprint for this {SSHScan::Crypto::PublicKey} instance.
+      # @return [String] formatted SHA256 fingerprint
       def fingerprint_sha256
         OpenSSL::Digest::SHA256.hexdigest(::Base64.decode64(@key)).scan(/../).join(':')
       end

data/lib/ssh_scan/error/closed_connection.rb

@@ -1,5 +1,6 @@
 module SSHScan
   module Error
+    # Connection closed from the other side.
     class ClosedConnection < RuntimeError
       def to_s
         "#{self.class.to_s.split('::')[-1]}"

data/lib/ssh_scan/error/connect_timeout.rb

@@ -1,5 +1,6 @@
 module SSHScan
   module Error
+    # Timed out trying to connect.
     class ConnectTimeout < RuntimeError
       def initialize(message)
         @message = message

data/lib/ssh_scan/error/connection_refused.rb

@@ -1,5 +1,6 @@
 module SSHScan
   module Error
+    # Target refused connection attempt.
     class ConnectionRefused < RuntimeError
       def initialize(message)
         @message = message

data/lib/ssh_scan/error/disconnected.rb

@@ -1,5 +1,6 @@
 module SSHScan
   module Error
+    # Got disconnected somehow.
     class Disconnected < RuntimeError
       def initialize(message)
         @message = message

data/lib/ssh_scan/error/no_banner.rb

@@ -1,5 +1,6 @@
 module SSHScan
   module Error
+    # Target did not respond with an SSH banner.
     class NoBanner < RuntimeError
       def initialize(message)
         @message = message

data/lib/ssh_scan/error/no_kex_response.rb

@@ -1,5 +1,6 @@
 module SSHScan
   module Error
+    # Failed to do key exchange.
     class NoKexResponse < RuntimeError
       def initialize(message)
         @message = message

data/lib/ssh_scan/fingerprint_database.rb

@@ -1,17 +1,24 @@
 require 'yaml/store'
 
 module SSHScan
+  # Create and/or maintain a fingerprint database using YAML Store.
   class FingerprintDatabase
     def initialize(database_name)
       @store = YAML::Store.new(database_name)
     end
 
+    # Empty the fingerprints database for given IP.
+    # @param ip [String] IP for which fingerprints should be
+    #   cleared.
     def clear_fingerprints(ip)
       @store.transaction do
         @store[ip] = []
       end
     end
 
+    # Insert a (fingerprint, IP) record.
+    # @param fingerprint [String] fingerprint to insert
+    # @param ip [String] IP for which fingerprint has to be added
     def add_fingerprint(fingerprint, ip)
       @store.transaction do
         @store[ip] = [] if @store[ip].nil?
@@ -19,6 +26,11 @@ module SSHScan
       end
     end
 
+    # Find IPs that have the given fingerprint.
+    # @param fingerprint [String] fingerprint for which search
+    #   should be performed
+    # @return [Array<String>] return unique IPs for which the given
+    #   fingerprint has an entry
     def find_fingerprints(fingerprint)
       ip_matches = []
 

data/lib/ssh_scan/os/raspbian.rb

@@ -18,6 +18,11 @@ module SSHScan
         @version = Raspbian::Version.new(raspbian_version_guess)
       end
 
+      # Guess Raspbian OS version. Typically, Raspbian banners 
+      # are like "SSH-2.0-Raspbian-something", where something 
+      # is the Raspbian version.
+      # @return [String] version string matched from banner, nil
+      #   if not matched
       def raspbian_version_guess
         return nil if @banner.nil?
         match = @banner.match(/SSH-2.0-Raspbian-(\d+)/)

data/lib/ssh_scan/os/ubuntu.rb

@@ -217,6 +217,10 @@ module SSHScan
         "ubuntu"
       end
 
+      # Get the FINGERPRINTS constant hash, generated from the
+      # scraping script.
+      # @return [Hash<String, Array<String>>] FINGERPRINTS constant
+      #   hash
       def fingerprints
         OS::Ubuntu::FINGERPRINTS
       end

data/lib/ssh_scan/policy.rb

@@ -1,6 +1,8 @@
 require 'yaml'
 
 module SSHScan
+  # Policy methods that deal with key exchange, macs, encryption methods,
+  # compression methods and more.
   class Policy
     attr_reader :name, :kex, :macs, :encryption, :compression,
                 :references, :auth_methods, :ssh_version
@@ -16,11 +18,19 @@ module SSHScan
       @ssh_version = opts['ssh_version'] || false
     end
 
+    # Generate a {SSHScan::Policy} object from YAML file.
+    # @param file [String] filepath
+    # @return [SSHScan::Policy] new instance with parameters loaded
+    #   from YAML file
     def self.from_file(file)
       opts = YAML.load_file(file)
       self.new(opts)
     end
 
+    # Generate a {SSHScan::Policy} object from YAML string.
+    # @param string [String] YAML string
+    # @return [SSHScan::Policy] new instance with parameters loaded
+    #   from given string
     def self.from_string(string)
       opts = YAML.load(string)
       self.new(opts)

data/lib/ssh_scan/policy_manager.rb

@@ -1,4 +1,5 @@
 module SSHScan
+  # Policy management methods, compliance checking and recommendations.
   class PolicyManager
     def initialize(result, policy)
       @policy = policy
@@ -145,48 +146,48 @@ module SSHScan
 
       # Add these items to be compliant
       if missing_policy_kex.any?
-        recommendations << "Add these Key Exchange Algos: \
+        recommendations << "Add these key exchange algorithms: \
 #{missing_policy_kex.join(",")}"
       end
 
       if missing_policy_macs.any?
-        recommendations << "Add these MAC Algos: \
+        recommendations << "Add these MAC algorithms: \
 #{missing_policy_macs.join(",")}"
       end
 
       if missing_policy_encryption.any?
-        recommendations << "Add these Encryption Ciphers: \
+        recommendations << "Add these encryption ciphers: \
 #{missing_policy_encryption.join(",")}"
       end
 
       if missing_policy_compression.any?
-        recommendations << "Add these Compression Algos: \
+        recommendations << "Add these compression algorithms: \
 #{missing_policy_compression.join(",")}"
       end
 
       # Remove these items to be compliant
       if out_of_policy_kex.any?
-        recommendations << "Remove these Key Exchange Algos: \
+        recommendations << "Remove these key exchange algorithms: \
 #{out_of_policy_kex.join(", ")}"
       end
 
       if out_of_policy_macs.any?
-        recommendations << "Remove these MAC Algos: \
+        recommendations << "Remove these MAC algorithms: \
 #{out_of_policy_macs.join(", ")}"
       end
 
       if out_of_policy_encryption.any?
-        recommendations << "Remove these Encryption Ciphers: \
+        recommendations << "Remove these encryption ciphers: \
 #{out_of_policy_encryption.join(", ")}"
       end
 
       if out_of_policy_compression.any?
-        recommendations << "Remove these Compression Algos: \
+        recommendations << "Remove these compression algorithms: \
 #{out_of_policy_compression.join(", ")}"
       end
 
       if out_of_policy_auth_methods.any?
-        recommendations << "Remove these Authentication Methods: \
+        recommendations << "Remove these authentication methods: \
 #{out_of_policy_auth_methods.join(", ")}"
       end
 

data/lib/ssh_scan/protocol.rb

@@ -200,6 +200,7 @@ module SSHScan
     end
 
     # Summarize as Hash
+    # @return [Hash] summary
     def to_hash
       {
         :cookie => self.cookie.hexify,
@@ -220,6 +221,10 @@ module SSHScan
       }
     end
 
+    # Generate a {SSHScan::KeyExchangeInit} object from given Ruby hash.
+    # @param opts [Hash] options
+    # @return [SSHScan::KeyExchangeInit] {SSHScan::KeyExchangeInit}
+    #   instance initialized using passed opts
     def self.from_hash(opts)
       kex_init = SSHScan::KeyExchangeInit.new()
       kex_init.cookie = opts[:cookie]
@@ -244,6 +249,7 @@ module SSHScan
     end
 
     # Summarize as JSON
+    # @return [String] JSON representation for summary hash
     def to_json
       self.to_hash.to_json
     end

data/lib/ssh_scan/scan_engine.rb

@@ -6,8 +6,13 @@ require 'net/ssh'
 require 'logger'
 
 module SSHScan
+  # Handle scanning of targets.
   class ScanEngine
 
+    # Scan a single target.
+    # @param socket [String] ip:port specification
+    # @param opts [Hash] options (timeout, ...)
+    # @return [Hash] result
     def scan_target(socket, opts)
       target, port = socket.chomp.split(':')
       if port.nil?
@@ -119,6 +124,10 @@ module SSHScan
       return result
     end
 
+    # Utilize multiple threads to scan multiple targets, combine
+    # results and check for compliance.
+    # @param opts [Hash] options (sockets, threads ...)
+    # @return [Hash] results
     def scan(opts)
       sockets = opts["sockets"]
       threads = opts["threads"] || 5

data/lib/ssh_scan/target_parser.rb

@@ -2,7 +2,12 @@ require 'netaddr'
 require 'string_ext'
 
 module SSHScan
+  # Enumeration methods for IP notations.
   class TargetParser
+    # Enumerate CIDR addresses, single IPs and IP ranges.
+    # @param ip [String] IP address
+    # @param port [Fixnum] port
+    # @return [Array] array of enumerated addresses
     def enumerateIPRange(ip,port)
       if ip.fqdn?
         if port.nil?

data/lib/ssh_scan/update.rb

@@ -4,6 +4,7 @@ require 'ssh_scan/version'
 require 'net/http'
 
 module SSHScan
+  # Handle {SSHScan} updates.
   class Update
     def initialize
       @errors = []
@@ -33,6 +34,9 @@ module SSHScan
       return [major_num.to_s, "0", "0"].join(".")
     end
 
+    # Returns true if the given gem version exists.
+    # @param version [String] version string
+    # @return [Boolean] true if given gem exists, else false
     def gem_exists?(version = SSHScan::VERSION)
       uri = URI("https://rubygems.org/gems/ssh_scan/versions/#{version}")
 
@@ -54,6 +58,11 @@ module SSHScan
       @errors.uniq
     end
 
+    # Tries to check if the next patch, minor or major version
+    # is available or not. If so, returns true.
+    # @param version [String] version string
+    # @return [Boolean] true if next major/minor version available,
+    #   else false
     def newer_gem_available?(version = SSHScan::VERSION)
       if gem_exists?(next_patch_version(version))
         return true

data/lib/ssh_scan/version.rb

@@ -1,3 +1,3 @@
 module SSHScan
-  VERSION = '0.0.20'
+  VERSION = '0.0.21'
 end

data/ssh_scan.gemspec

@@ -28,6 +28,7 @@ Gem::Specification.new do |s|
   s.summary = 'Ruby-based SSH Scanner'
   s.description = 'A Ruby-based SSH scanner for configuration and policy scanning'
   s.homepage = 'http://rubygems.org/gems/ssh_scan'
+  s.metadata["yard.run"] = "yri" # use "yard" to build full HTML docs
 
   s.add_dependency('bindata', '~> 2.0')
   s.add_dependency('netaddr')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ssh_scan
 version: !ruby/object:Gem::Version
-  version: 0.0.20
+  version: 0.0.21
 platform: ruby
 authors:
 - Jonathan Claudius
@@ -12,7 +12,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-05-12 00:00:00.000000000 Z
+date: 2017-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bindata
@@ -391,7 +391,8 @@ files:
 homepage: http://rubygems.org/gems/ssh_scan
 licenses:
 - ruby
-metadata: {}
+metadata:
+  yard.run: yri
 post_install_message: 
 rdoc_options: []
 require_paths: