arp_scan 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3da5c794b3e060ebcdf1e64e9b4b4e3c2a962168
-  data.tar.gz: 8cb575fb34d6afed2e5a385fd0a7dc771fe0aedc
+  metadata.gz: b7b960cabf68bf289134ad75739ab76573745ed6
+  data.tar.gz: 9b5cce94f3350b24e70053d6e0e4aa8045436403
 SHA512:
-  metadata.gz: 157feb33e07f5b02ec025a23285165d7a80f42be28302e03ea2080e7c788e5682578ece77efa4ceb22449d29b2bc94f164e9ab5f32bf3f6176919ec6c0867fab
-  data.tar.gz: de4f4b8e85030c3da59dc48f5b24ea6f59c301ec9630ae5ba563a7516e0a55f70ff59a7a36dd7610417068cfea8be7cca6c4828e0e0f190a6cabf38f6c82a760
+  metadata.gz: 42b6b7058c6dd4d2f5fbae4c0a3a3c0dca2f1fbf09bf52151f9c3a11191d0b43a06bbe927794611637a424155cae7924f671b501d51d8e536e7627633d976289
+  data.tar.gz: b9a8177864994bb4eef7993f638e1a6772f54ff5e4febe0211e691fb6a366c3b2700719a8a6f277f7a86717987dfd7624bff738e217f9e1f271e7a6ad478f496

data/Gemfile

@@ -1,5 +1,9 @@
 source 'https://rubygems.org'
 
+group :test do
+  gem 'rspec'
+  gem 'rspec-support', '~>3.0.0'
+end
 
 # Specify your gem's dependencies in arp_scan.gemspec
-gemspec
+#gemspec

data/README.md

@@ -24,8 +24,8 @@ should probably go with the `/etc/sudoers` method.
 
 ## Notes
 
-This code is partially tested.
-
+There are some tests now, but output containing host names instead of IP
+addresses will not be properly parsed. This might be fixed soon.
 
 ## Installation
 

data/arp_scan.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["mikebrodrigues@gmail.com"]
   spec.summary       = %q{A ruby wrapper for the arp-scan utility.}
   spec.description   = %q{Easily use the arp-scan utility from within your ruby programs.}
-  spec.homepage      = ""
+  spec.homepage      = "https://github.com/mikerodrigues/arp_scan"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")

data/lib/arp_scan/arp_scanner.rb

@@ -1,12 +1,15 @@
 require_relative './scan_result_processor'
 
 module ARPScan
+  # This module manages finding the arp-scan binary and running the scan. It
+  # delegates the parsing of the scan results to the ScanResultProcessor module.
+  #
   module ARPScanner
-
     # I got this method from: http://stackoverflow.com/questions/2108727
     # Cross-platform way of finding an executable in the $PATH.
     #
     #   which('ruby') #=> /usr/bin/ruby
+    #
     def self.which(cmd)
       exts = ENV['PATHEXT'] ? ENV['PATHEXT'].split(';') : ['']
       ENV['PATH'].split(File::PATH_SEPARATOR).each do |path|
@@ -18,6 +21,10 @@ module ARPScan
       return nil
     end
 
+    # This method runs the actual scan by passing the arguments to the arp-scan
+    # binary. The results are passed to the ScanResultProcessor and a ScanReport
+    # is returned.
+    #
     def self.scan(argument_string = nil)
       result_string = `#{which 'arp-scan'} #{argument_string}`
       ScanResultProcessor.process(result_string)

data/lib/arp_scan/host.rb

@@ -1,13 +1,20 @@
 module ARPScan
+  # Abstracts replying hosts from the arp-scan output.
+  #
   class Host
     attr_reader :ip_addr, :mac, :oui
 
+    # Create a new hsot. IP address, MAC address and OUI information are
+    # expected.
+    #
     def initialize(ip_addr, mac, oui)
       @ip_addr = ip_addr
       @mac = mac
       @oui = oui
     end
 
+    # Returns a hash representation of the Host object.
+    #
     def to_hash
       { :ip_addr => @ip_addr,
         :mac     => @mac,
@@ -15,6 +22,8 @@ module ARPScan
       }
     end
 
+    # Returns an array representation of the Host object.
+    #
     def to_array
       [ @ip_addr,
         @mac,

data/lib/arp_scan/scan_report.rb

@@ -1,8 +1,15 @@
 module ARPScan
+
+  # This class abstracts the string output from arp-scan into an Object. A
+  # ScanReports are usually created through the ScanResultProcessor module.
+  #
   class ScanReport
 
     attr_reader :hosts, :interface, :datalink, :version, :range_size, :scan_time, :scan_rate, :reply_count
 
+    # Create a new scan report, passing in every attribute. The best way to do
+    # this is with the ScanResultProcessor module.
+    #
     def initialize(hash)
       @hosts = hash[:hosts]
       @interface = hash[:interface]
@@ -14,6 +21,9 @@ module ARPScan
       @reply_count = Integer(hash[:reply_count])
     end
 
+    # Returns an array representation of the ScanReport. Metadata about the
+    # scan, and an array of Host arrays comprise the array.
+    #
     def to_array
       self.instance_variables.map do |var|
         if var == :@hosts
@@ -24,6 +34,9 @@ module ARPScan
       end
     end
 
+    # Returns a hash representation of the ScanReport. Metadata about the scan,
+    # and array of Host hashes comprise the hash.
+    #
     def to_hash
       { :hosts => @hosts.map {|host| host.to_hash},
         :interface => @interface,

data/lib/arp_scan/scan_result_processor.rb

@@ -2,12 +2,21 @@ require_relative './host'
 require_relative './scan_report'
 
 module ARPScan
+  # This module is an interface for creating ScanReport objects from arp-scan
+  # output.
+  #
   module ScanResultProcessor
 
+    # Regexes for parsing the arp-scan output.
+    #
     Host_Entry_Regex = /(\d+.\d+.\d+.\d+)\s(\w\w:\w\w:\w\w:\w\w:\w\w:\w\w)\s(.*)/
     Interface_Summary_Regex = /Interface: (?<interface>.+), datalink type: (?<datalink>.*$)/
     Scan_Summary_Regex = /Ending arp-scan (?<version>.*): (?<range_size>.*) hosts scanned in (?<scan_time>.*) seconds \((?<scan_rate>.*) hosts\/sec\). (?<reply_count>.*) responded/
 
+    # This method does the actual processing of the arp-scan result string. It
+    # uses the Regexes to capture data then passes the results to ScanRepor.new
+    # to return a ScanReport object.
+    #
     def self.process(string)
       results = {}
       results[:hosts] = string.scan(Host_Entry_Regex).map {|entry| Host.new(*entry)}

data/lib/arp_scan/version.rb

@@ -1,3 +1,3 @@
 module ARPScan
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/lib/arp_scan.rb

@@ -4,10 +4,14 @@ require_relative "./arp_scan/scan_report"
 require_relative "./arp_scan/scan_result_processor"
 require_relative "./arp_scan/host"
 
-module ARPScan
-
-end
+# This module just acts as a namespace for the gem.
+#
+module ARPScan; end
 
+# The main interface for the gem. This method accepts arp-scan arguments in the
+# form of a single string. Currently only IP addresses (no hostnames) are
+# supported.
+#
 def ARPScan(argument_string = nil)
   ARPScan::ARPScanner.scan argument_string
 end

data/spec/arp_scan_spec.rb

@@ -1,18 +1,8 @@
-require '../lib/arp_scan'
 require_relative './spec_helper.rb'
 
 RSpec.describe ARPScan do
   report = ARPScan('-l')
-
-  it "is a method you can pass arp-scan arguments to as a string" do
-    expect(ARPScan('-l').class).to eq(ARPScan::ScanReport)
-  end
-
-  it "returns a nested hash of attributes" do
-    expect(report.to_hash.class).to eq(Hash)
-  end
-
-  it "returns a nested array of attributes" do
-    expect(report.to_array.class).to eq(Array)
+  it "is a method" do
+    expect(ARPScan.respond_to?('__send__')).to eq(true)
   end
 end

data/spec/arp_scanner_spec.rb

@@ -1,11 +1,11 @@
-require '../lib/arp_scan'
 require_relative './spec_helper'
 
-RSpec.describe ARPScan::ARPScanner do
-
-  it "has a #scan method to pass arp-scan arguments to as a string" do
-    expect(ARPScan::ARPScanner.scan('-l').class).to eq(ARPScan::ScanReport)
+module ARPScan
+  describe ARPScanner do
+    describe "#scan" do
+      it "accepts arp-scan arguments as a string" do
+        expect(ARPScanner.scan('-l').class).to eq(ScanReport)
+      end
+    end
   end
-  
 end
-

data/spec/host_spec.rb

@@ -1,20 +1,27 @@
-require '../lib/arp_scan'
 require_relative './spec_helper'
 
-RSpec.describe ARPScan::Host do
+module ARPScan
+  describe Host do
 
-  host = ARPScan::Host.new('10.0.0.1', '00:11:22:33:44:55', "NIC Manufacturer")
+    host = Host.new('10.0.0.1', '00:11:22:33:44:55', "NIC Manufacturer")
 
-  it "contains the host's IP address" do
-    expect(host.ip_addr).to eq('10.0.0.1')
-  end
+    describe "#ip_addr" do
+      it "returns the host's IP address" do
+        expect(host.ip_addr).to eq('10.0.0.1')
+      end
+    end
 
-  it "contains the host's MAC address" do
-    expect(host.mac).to eq('00:11:22:33:44:55')
-  end
+    describe "#mac" do
+      it "returns the host's MAC address" do
+        expect(host.mac).to eq('00:11:22:33:44:55')
+      end
+    end
 
-  it "contians the host's OUI information" do
-    expect(host.oui).to eq('NIC Manufacturer')
-  end
+    describe "#oui" do
+      it "returns the host's OUI information" do
+        expect(host.oui).to eq('NIC Manufacturer')
+      end
+    end
 
+  end
 end

data/spec/scan_report_spec.rb

@@ -1,52 +1,68 @@
-require '../lib/arp_scan'
 require_relative './spec_helper'
 
-RSpec.describe ARPScan::ScanReport do
+module ARPScan
+  describe ScanReport do
 
-  report_hash = {
-    :hosts => [ARPScan::Host.new(*['10.0.0.1', '00:11:22:33:44:55', 'NIC Manufacturer'])],
-    :interface => "eth0",
-    :datalink => "EN10MB (Ethernet)",
-    :version => "1.8.1",
-    :range_size => 256,
-    :scan_time => 1.503,
-    :scan_rate => 170.33,
-    :reply_count => 1
-  }
+    report_hash = {
+      :hosts => [Host.new(*['10.0.0.1', '00:11:22:33:44:55', 'NIC Manufacturer'])],
+      :interface => "eth0",
+      :datalink => "EN10MB (Ethernet)",
+      :version => "1.8.1",
+      :range_size => 256,
+      :scan_time => 1.503,
+      :scan_rate => 170.33,
+      :reply_count => 1
+    }
 
-  scan_report = ARPScan::ScanReport.new(report_hash)
+    scan_report = ScanReport.new(report_hash)
 
-  it "has a list of zero or more responding hosts" do
-    expect(scan_report.hosts.first.class).to eq(ARPScan::Host)
-  end
+    describe "#hosts" do
+      it "returns an Array of Host objects" do
+        expect(scan_report.hosts.class).to eq(Array)
+        expect(scan_report.hosts.first.class).to eq(Host)
+      end
+    end
 
-  it "reports the network interface used to scan" do
-    expect(scan_report.interface).to eq("eth0")
-  end
+    describe "#interface" do
+      it "returns the network interface used to scan" do
+        expect(scan_report.interface).to eq("eth0")
+      end
+    end
 
-  it "reports the datalink type of the network interface used to scan" do
-    expect(scan_report.datalink).to eq('EN10MB (Ethernet)')
-  end
+    describe "#datalink" do
+      it "returns the datalink type of the network interface used to scan" do
+        expect(scan_report.datalink).to eq('EN10MB (Ethernet)')
+      end
+    end
 
-  it "reports the version of `arp-scan` used for the scan" do
-    expect(scan_report.version).to eq('1.8.1')
-  end
+    describe "#version" do
+      it "returns the version of `arp-scan` used for the scan" do
+        expect(scan_report.version).to eq('1.8.1')
+      end
+    end
 
-  it "reports the size of the range of scanned IPs" do
-    expect(scan_report.range_size).to eq(256)
-  end
+    describe "#range_size" do
+      it "returns the size of the range of scanned IPs" do
+        expect(scan_report.range_size).to eq(256)
+      end
+    end
 
-  it "reports the duration of the scan in seconds" do
-    expect(scan_report.scan_time).to eq(1.503)
-  end
+    describe "#scan_time" do
+      it "returns the duration of the scan in seconds" do
+        expect(scan_report.scan_time).to eq(1.503)
+      end
+    end
 
-  it "reports the scan rate in hosts per second" do
-    expect(scan_report.scan_rate).to eq(170.33)
-  end
+    describe "#scan_rate" do
+      it "returns the scan rate in hosts per second" do
+        expect(scan_report.scan_rate).to eq(170.33)
+      end
+    end
 
-  it "reports the number of hosts that responded" do
-    expect(scan_report.reply_count).to eq(1)
+    describe "#reply_count" do
+      it "returns the number of hosts that responded" do
+        expect(scan_report.reply_count).to eq(1)
+      end
+    end
   end
-
-
 end

data/spec/scan_result_processor_spec.rb

@@ -1,45 +1,48 @@
-require '../lib/arp_scan'
 require_relative './spec_helper'
 
-RSpec.describe ARPScan::ScanResultProcessor do
+module ARPScan
+  describe ScanResultProcessor do
 
-  report_string = File.read './test_output.txt'
-  report = ARPScan::ScanResultProcessor.process(report_string)
-  
-  it "processes arp-scan output to create a ScanReport object" do
-    expect(report.class).to eq(ARPScan::ScanReport)
-  end
+    report_string = File.read './test_output.txt'
+    report = ARPScan::ScanResultProcessor.process(report_string)
 
-  it "builds an array of Host objects" do
-    expect(report.hosts[0].class).to eq(ARPScan::Host)
-  end
+    describe "#process" do
+      it "processes arp-scan output to create a ScanReport object" do
+        expect(report.class).to eq(ARPScan::ScanReport)
+      end
 
-  it "parses the scan interface name" do
-    expect(report.interface).to eq("eth0")
-  end
 
-  it "parses the datalink type information" do
-    expect(report.datalink).to eq("EN10MB (Ethernet)")
-  end
+      it "builds an array of Host objects" do
+        expect(report.hosts[0].class).to eq(ARPScan::Host)
+      end
 
-  it "parses the version of arp-scan that ran the scan" do
-    expect(report.version).to eq('1.8.1')
-  end
+      it "parses the scan interface name" do
+        expect(report.interface).to eq("eth0")
+      end
 
-  it "parses the number of hosts scanned" do
-    expect(report.range_size).to eq(256)
-  end
+      it "parses the datalink type information" do
+        expect(report.datalink).to eq("EN10MB (Ethernet)")
+      end
 
-  it "parses the duration of the scan in seconds" do
-    expect(report.scan_time).to eq(1.494)
-  end
+      it "parses the version of arp-scan that ran the scan" do
+        expect(report.version).to eq('1.8.1')
+      end
 
-  it "parses the rate of the scan in hosts per second" do
-    expect(report.scan_rate).to eq(171.35)
-  end
+      it "parses the number of hosts scanned" do
+        expect(report.range_size).to eq(256)
+      end
+
+      it "parses the duration of the scan in seconds" do
+        expect(report.scan_time).to eq(1.494)
+      end
 
-  it "parses the number of hosts that responded to the scan" do
-    expect(report.reply_count).to eq(1)
+      it "parses the rate of the scan in hosts per second" do
+        expect(report.scan_rate).to eq(171.35)
+      end
+
+      it "parses the number of hosts that responded to the scan" do
+        expect(report.reply_count).to eq(1)
+      end
+    end
   end
 end
-

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require '../lib/arp_scan'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: arp_scan
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Michael Rodrigues
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-10 00:00:00.000000000 Z
+date: 2014-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -62,7 +62,7 @@ files:
 - spec/scan_result_processor_spec.rb
 - spec/spec_helper.rb
 - spec/test_output.txt
-homepage: ''
+homepage: https://github.com/mikerodrigues/arp_scan
 licenses:
 - MIT
 metadata: {}
@@ -82,7 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.1
 signing_key: 
 specification_version: 4
 summary: A ruby wrapper for the arp-scan utility.