iqeo-hostspec 0.1.0.pre1

data/README.md

@@ -0,0 +1,29 @@
+# Iqeo::Hostspec
+
+TODO: Write a gem description
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'iqeo-hostspec'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install iqeo-hostspec
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/hostspec

@@ -0,0 +1,131 @@
+#! /usr/bin/env ruby
+
+require 'iqeo/hostspec'
+
+class Runner
+
+  def self.run args, out: $stdout, err: $stderr
+
+    if args.empty?
+      err.puts "Error: No specs given"
+      return 1
+    end
+
+    if args.include?('-h') || args.include?('--help')
+      print_help err
+      return 0
+    end
+
+    if args.include?('-v') || args.include?('--version')
+      print_version err
+      return 0
+    end
+
+    cmd_sw_index = args.index('-c') || args.index('--cmd')
+    if cmd_sw_index
+      specs = args.take(cmd_sw_index)            # specs are before switch
+      cmd   = args.drop(cmd_sw_index+1).join ' ' # command components are after switch, join into string to pass to subshell
+      if cmd.empty?
+        err.puts "Error: No command given"
+        return 2
+      end
+    else 
+      specs = args
+      cmd = nil
+    end
+    
+    results = []
+    specs.each do |spec|
+      spec = spec.strip
+      begin
+        host_spec = Iqeo::Hostspec.new spec
+      rescue Exception => e
+        err.puts "Error: #{e.message}"
+        return 3
+      end
+      if cmd.nil?
+        host_spec.each { |address| out.puts address }
+      else
+        env = {
+          'HOSTSPEC_MASK'    => host_spec.mask,
+          'HOSTSPEC_MASKLEN' => host_spec.mask_length.to_s,
+          'HOSTSPEC_COUNT'   => host_spec.size.to_s
+        }
+        host_spec.each_with_index do |address,index|
+          env['HOSTSPEC_IP']    = address
+          env['HOSTSPEC_INDEX'] = (index+1).to_s
+          # this uses posix 'sh', to use bash user's cmd should be 'bash -c "echo \$HOSTSPEC_IP"' and deal with the weird nested quoting
+          results << system( env, cmd )
+        end
+      end
+    end
+    ( results.empty? || results.all? ) ? 0 : 4
+  end
+
+  def self.print_help io
+    io.puts "Usage: hostspec [ options ] specs... [ [ -c / --cmd ] command ]"
+    io.puts
+    io.puts "Prints all IP addresses for IP host specifications (see Specs:)."
+    io.puts "If specified, a command is executed for each IP address, with related values in environment variables (see Command:)."
+    io.puts
+    io.puts "Specs:"
+    io.puts "  Nmap-style IP host specifications, multiple specs separated by spaces."
+    io.puts "  Single host       : x.x.x.x or hostname"
+    io.puts "  Multiple hosts:"
+    io.puts "  - by mask length  : x.x.x.x/m or hostname/m"
+    io.puts "  - by octet values : x.x.x.a,b,c"
+    io.puts "  - by octet ranges : x.x.x.d-e"
+    io.puts "  Octet values and ranges may be combined or applied to any/multiple octets."
+    io.puts "  Examples:"
+    io.puts "    hostname         : localhost      => 127.0.0.1"
+    io.puts "    hostname w/mask  : localhost/24   => 127.0.0.0 127.0.0.1 ... 127.0.0.254 127.0.0.255"
+    io.puts "    address          : 1.1.1.1        => 1.1.1.1"
+    io.puts "    address w/mask   : 2.2.2.1/24     => 2.2.2.0 2.2.2.1 ... 2.2.2.254 2.2.2.255"
+    io.puts "    address w/values : 3.3.3.10,20,30 => 3.3.3.10 3.3.3.20 3.3.3.30"
+    io.puts "    address w/ranges : 4.4.4.40-50    => 4.4.4.40 4.4.4.41 ... 4.4.4.49 4.4.4.50"
+    io.puts "    address w/combo  : 5.5.5.2,4-6,8  => 5.5.5.2 5.5.5.4 5.5.5.5 5.5.5.6 5.5.5.8"
+    io.puts "    complex          : 6.1-2,3.4-5.6  => 6.1.4.6 6.1.5.6 6.2.4.6 6.2.5.6 6.3.4.6 6.3.5.6"
+    io.puts
+    io.puts "Command:"
+    io.puts "  A command to execute for each IP address may be specified following the command switch ( -c / --cmd )."
+    io.puts "  The command is executed in a separate shell for each IP address."
+    io.puts "  Environment variables are provided with values for each IP address command execution."
+    io.puts "  Quote these variables in the command to prevent substitution by the current shell."
+    io.puts "    $HOSTSPEC_IP      : IP address"
+    io.puts "    $HOSTSPEC_MASK    : Mask (255.255.255.255 if a mask length was not specified)"
+    io.puts "    $HOSTSPEC_MASKLEN : Mask length (32 if a mask length was not specified)"
+    io.puts "    $HOSTSPEC_COUNT   : Count of IP addresses"
+    io.puts "    $HOSTSPEC_INDEX   : Index of IP address (from 1 to Count)"
+    io.puts "  Examples:"
+    io.puts "    Print IP addresses and mask length with index and count:"
+    io.puts "      hostspec 1.1.1.1-3 --cmd echo '$HOSTSPEC_INDEX' of '$HOSTSPECT_COUNT' : '$HOSTSPEC_IP/$HOSTSPEC_MASKLEN'"
+    io.puts "      ..."
+    io.puts "      1 of 3 : 1.1.1.1/24"
+    io.puts "      2 of 3 : 1.1.1.2/24"
+    io.puts "      3 of 3 : 1.1.1.3/24"
+    io.puts "    Collect routing tables of all hosts on a network via ssh:"
+    io.puts "      hostspec 1.1.1.1-254 --cmd 'ssh me@$HOSTSPEC_IP route -n'"
+    io.puts "    Collect default web pages from all servers on a network via curl:"
+    io.puts "      hostspec 1.1.1.1-254 --cmd curl -o '$HOSTSPEC_IP.html' 'http://$HOSTSPEC_IP'"
+    io.puts "    Collect IP configuration info from multiple windows systems (run from a windows system):"
+    io.puts "      hostspec 1.1.1.1-254 --cmd psexec '\\%HOSTSPEC_IP%' ipconfig /all"
+    io.puts "    Collect IP configuration info from multiple windows systems (run from a linux system with kerberos):"
+    io.puts "      hostspec 1.1.1.1-254 --cmd winexe --kerberos yes //$(dig -x '$HOSTSPEC_IP' +short) ipconfig /all"
+    io.puts "    ...or any task that you would have to execute individually on multiple systems."
+    io.puts
+    io.puts "Options:"
+    io.puts "  -h / --help     : Display this helpful information"
+    io.puts "  -v / --version  : Display program version"
+    io.puts
+  end
+
+  def self.print_version io
+    io.puts "hostspec version #{Iqeo::Hostspec::VERSION}"
+  end
+  
+end
+
+if __FILE__ == $0
+  exit Runner.run ARGV
+end
+

data/iqeo-hostspec.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib/', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'iqeo/hostspec'
+
+Gem::Specification.new do |spec|
+
+  spec.name          = "iqeo-hostspec"
+  spec.version       = Iqeo::Hostspec::VERSION
+  spec.authors       = ["Gerard Fowley"]
+  spec.email         = ["gerard.fowley@iqeo.net"]
+  spec.description   = %q{Write a gem description}
+  spec.summary       = %q{Write a gem summary}
+  spec.homepage      = ""
+  spec.license       = "GPLv3"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rspec"
+
+end

data/lib/iqeo/hostspec.rb

@@ -0,0 +1,180 @@
+require 'resolv'
+
+module Iqeo
+
+  class HostspecException < Exception ; end
+
+  class Hostspec
+
+    VERSION = '0.1.0.pre1'
+
+    include Enumerable
+
+    attr_reader :string, :mask, :mask_length, :address_spec, :hostname
+
+    def initialize spec_str
+      @string = spec_str
+      raise HostspecException, 'spec cannot be empty' if spec_str.empty?
+      host_str, mask_str = split_on_slash spec_str
+      raise HostspecException, 'host cannot be empty' if host_str.empty?
+      parse_mask mask_str
+      begin
+        parse_address_spec host_str
+      rescue HostspecException
+        parse_hostname host_str
+      end
+      raise HostspecException, 'complex spec cannot have mask length' if @mask_specified && @address_spec.any? { |octet| octet.size > 1 }
+      mask_address_spec
+    end
+
+    def split_on_slash str
+      case str.count '/'
+      when 0 then [ str.strip, '' ]
+      when 1 then str.strip.split '/'
+      else raise 'bad format, expected 0 or 1 "/"'
+      end
+    end
+
+    def parse_mask str
+      if str.empty?
+        @mask = '255.255.255.255'
+        @mask_length = 32
+        @mask_specified = false
+        return
+      end
+      if match = str.match( /^\d+$/ )
+        @mask_length = match[0].to_i
+        raise "bad mask length (#{@mask_length}), expected between 0 ad 32" unless @mask_length.between? 0,32
+        mask_int = ((2**@mask_length)-1) << (32-@mask_length)
+        @mask = [24,16,8,0].collect { |n| ( mask_int & ( 255 << n ) ) >> n }.join '.'
+        @mask_specified = true
+      else
+        raise "bad format, expected mask length after '/'"
+      end
+    end
+
+    def mask_address_spec
+      @address_spec.each_with_index do |octet,index|
+        high_bit_position = ( index * 8 ) + 1 
+        low_bit_position = ( index + 1 ) * 8
+        @address_spec[index] = case
+        when @mask_length >= low_bit_position then octet
+        when @mask_length < high_bit_position then [0..255]
+        else
+          octet_mask_length = @mask_length % 8
+          octet_mask = ( ( 2 ** octet_mask_length ) - 1 ) << ( 8 - octet_mask_length )
+          octet_mask_inverted = octet_mask ^ 255
+          octet_min = octet_mask & octet[0]
+          octet_max = octet_min | octet_mask_inverted
+          [octet_min..octet_max]
+        end
+      end
+    end
+
+    def parse_address_spec str
+      octet_strs = str.split '.'
+      raise HostspecException, 'bad ip, expected 4 octets' unless octet_strs.size == 4    
+      octets = octet_strs.collect { |octet_str| parse_octet octet_str }
+      @address_spec = octets
+    end
+
+    def parse_octet str
+      values = str.split ','
+      values.collect { |value_str| parse_octet_value value_str }
+    end
+
+    def parse_octet_value str
+      # values may be dash denoted ranges, possibilities...
+      #   n   : just a number         :   'n'.split '-' == ['n']       <= same = problem!    'n'.split '-', -1 == [ "n"       ] 
+      #   n-m : range from n to m     : 'n-m'.split '-' == ['n','m']                       'n-m'.split '-', -1 == [ "n" , "m" ]
+      #   n-  : range from n to 255   :  'n-'.split '-' == ['n']       <= same = problem!   'n-'.split '-', -1 == [ "n" , ""  ]
+      #   -m  : range from 0 to m     :  '-m'.split '-' == ['','m']                         '-m'.split '-', -1 == [ ""  , "m" ]
+      #   -   : range from 0 to 255   :   '-'.split '-' == []                                '-'.split '-', -1 == [ ""  , ""  ]
+      numbers = str.split '-', -1 # maximize return fields to distinguish 'n' from '-m'
+      case numbers.size
+      when 1 then
+        check_octet_value numbers[0]
+        numbers[0].to_i
+      when 2 then
+        numbers[0] =   '0' if numbers[0].empty?
+        numbers[1] = '255' if numbers[1].empty?
+        check_octet_value numbers[0]
+        check_octet_value numbers[1]
+        range_start = numbers[0].to_i
+        range_finish = numbers[1].to_i
+        raise HostspecException, "bad ip, reversed range in octet value: #{str}" if range_start > range_finish
+        range_start..range_finish
+      else
+        raise HostspecException, "bad ip, invalid octet value: #{str}"
+      end
+    end
+
+    def check_octet_value str
+      match = str.match /^(25[0-5]|2[0-4]\d|[0-1]\d\d|\d\d|\d)$/
+      raise HostspecException, "bad ip, octet value is not a number in 0-255: #{str}" unless match
+    end
+
+    def parse_hostname str
+      @hostname = str
+      parse_address_spec Resolv.getaddress(str)
+    end
+
+    def recursively_iterate_octets octet_index = 0, address = [], &block
+      @address_spec[octet_index].each do |item|
+        if item.respond_to? :each
+          item.each do |value|
+            address.push value
+            octet_index == 3 ? yield( address.join '.' ) : recursively_iterate_octets( octet_index + 1, address, &block )
+            address.pop
+          end
+        else
+          address.push item
+          octet_index == 3 ? yield( address.join '.' ) : recursively_iterate_octets( octet_index + 1, address, &block )
+          address.pop
+        end
+      end
+    end
+
+    def each_address 
+      if block_given?
+        recursively_iterate_octets do |address_str|
+          yield address_str
+        end
+      else
+        return to_enum( :each_address ) { size }
+      end
+    end
+  
+    alias_method :each, :each_address
+
+    def size
+      if @mask_length == 32
+        @address_spec.inject(1) { |oc,o| oc * o.inject(0) { |vc,v| vc + ( v.respond_to?(:each) ? v.size : 1 ) } }
+      else
+        2**(32-@mask_length)
+      end
+    end
+
+    def min
+      first
+    end
+
+    def last
+      address = nil
+      each { |addr| address = addr }
+      address
+    end
+
+    def max
+      last
+    end
+
+    def minmax
+      [first,last]
+    end
+
+  end
+
+end
+
+

data/spec/hostspec_runner_spec.rb

@@ -0,0 +1,109 @@
+load './bin/hostspec'
+
+require 'stringio'
+
+describe Runner do
+
+  it 'expects an array of arguments' do
+    expect { Runner.run           }.to raise_error
+    expect { Runner.run nil       }.to raise_error
+    expect { Runner.run '1.1.1.1' }.to raise_error
+    expect { Runner.run [], out: StringIO.new, err: StringIO.new }.to_not raise_error
+  end
+
+  it 'accepts single host spec for argument with no switches' do
+    Runner.run( ['10.20.30.40'],                out: StringIO.new, err: StringIO.new ).should eq 0
+    Runner.run( ['10.20.30.40/24'],             out: StringIO.new, err: StringIO.new ).should eq 0
+    Runner.run( ['10,11.20-29.30,31-38,39.40'], out: StringIO.new, err: StringIO.new ).should eq 0
+    Runner.run( ['localhost'],                  out: StringIO.new, err: StringIO.new ).should eq 0
+  end
+
+  it 'accepts multiple host specs for arguments with no switches' do
+    Runner.run( ['10.20.30.40/24','11.22.33.44'],                out: StringIO.new, err: StringIO.new ).should eq 0
+    Runner.run( ['10,11.20-29.30,31-38,39.40','11.22.33.44/28'], out: StringIO.new, err: StringIO.new ).should eq 0
+    Runner.run( ['localhost','1.2.3.4/26','11.22.33.44-55'],     out: StringIO.new, err: StringIO.new ).should eq 0
+  end
+
+  it 'expects valid single host spec or prints error' do
+    error = StringIO.new
+    Runner.run( ['no-such-host/xyz'], out: StringIO.new, err: error ).should eq 3
+    error.string.should include 'Error'
+  end
+
+  it 'expects valid multiple host specs or prints error' do
+    error = StringIO.new
+    Runner.run( ['no-such-host/xyz','5.5.5.5'], out: StringIO.new, err: error ).should eq 3
+    error.string.should include 'Error'
+  end
+
+  it 'lists single host spec IP addresses to stdout for no command (-c/--cmd) switch' do
+    output = StringIO.new
+    Runner.run( ['1.1.1.1-5'], out: output )
+    output.string.should eq "1.1.1.1\n1.1.1.2\n1.1.1.3\n1.1.1.4\n1.1.1.5\n"
+  end
+
+  it 'lists multiple host spec IP addresses to stdout for no command (-c/--cmd) switch' do
+    output = StringIO.new
+    Runner.run( ['1.1.1.1-5','2.2.2.4,6,8'], out: output )
+    output.string.should eq "1.1.1.1\n1.1.1.2\n1.1.1.3\n1.1.1.4\n1.1.1.5\n2.2.2.4\n2.2.2.6\n2.2.2.8\n"
+  end
+
+  it 'accepts host specs for arguments before command (-c/--cmd) switch' do
+    Runner.run( ['1.1.1.1','2.2.2.2','-c'   ,'#'], out: StringIO.new, err: StringIO.new ).should eq 0
+    Runner.run( ['1.1.1.1','2.2.2.2','--cmd','#'], out: StringIO.new, err: StringIO.new ).should eq 0
+  end
+
+  it 'expects a command argument after command (-c/--cmd) switch or prints error' do
+    [['-c'],['-c',nil],['-c',''],['--cmd'],['--cmd',nil],['--cmd','']].each do |args|
+      error = StringIO.new
+      Runner.run( ['1.1.1.1','2.2.2.2',*args], out: StringIO.new, err: error ).should eq 2
+      error.string.should include 'Error'
+    end
+  end
+
+  it 'prints an error message to stderr for no arguments' do
+    error = StringIO.new
+    Runner.run( [], out: StringIO.new, err: error ).should eq 1
+    error.string.should include 'Error'
+  end
+
+  it 'prints a helpful message to stderr for help (-h/--help) switch' do
+    [['-h'],['1.2.3.4','-h'],['-h','1.2.3.4'],['1.2.3.4','-h','5.6.7.8'],['--help'],['1.2.3.4','--help'],['--help','1.2.3.4'],['1.2.3.4','--help','5.6.7.8']].each do |args|
+      error = StringIO.new
+      Runner.run( args, out: StringIO.new, err: error ).should eq 0
+      error.string.should include 'hostspec'
+    end
+  end
+
+  it 'prints version info to stderr for version (-v/--version) switch' do
+    [['-v'],['1.2.3.4','-v'],['-v','1.2.3.4'],['1.2.3.4','-v','5.6.7.8'],['--version'],['1.2.3.4','--version'],['--version','1.2.3.4'],['1.2.3.4','--version','5.6.7.8']].each do |args|
+      error = StringIO.new
+      Runner.run( args, out: StringIO.new, err: error ).should eq 0
+      error.string.should include 'hostspec'
+      error.string.should include Iqeo::Hostspec::VERSION 
+    end
+  end
+
+  it 'executes the argument after the command (-c/--cmd) switch as a shell command' do
+    File.delete 'test.txt' if File.exists? 'test.txt'
+    Runner.run( ['1.1.1.1-3','2.2.2.1-3','-c','echo X >> test.txt'] ).should eq 0
+    File.read('test.txt').should eq "X\n" * 6
+    File.delete 'test.txt' if File.exists? 'test.txt'
+  end
+
+  it 'provides hostspec values to command via environment variables $HOSTSPEC_IP, $HOSTSPEC_MASK, $HOSTSPEC_MASKLEN, $HOSTSPEC_COUNT, $HOSTSPEC_INDEX' do
+    File.delete 'test.txt' if File.exists? 'test.txt'
+    Runner.run( ['1.1.1.1-3','2.2.2.1-3','-c','echo $HOSTSPEC_IP $HOSTSPEC_MASK $HOSTSPEC_MASKLEN $HOSTSPEC_COUNT $HOSTSPEC_INDEX >> test.txt'] )
+    File.read('test.txt').should eq "1.1.1.1 255.255.255.255 32 3 1\n1.1.1.2 255.255.255.255 32 3 2\n1.1.1.3 255.255.255.255 32 3 3\n2.2.2.1 255.255.255.255 32 3 1\n2.2.2.2 255.255.255.255 32 3 2\n2.2.2.3 255.255.255.255 32 3 3\n" 
+    File.delete 'test.txt' if File.exists? 'test.txt'
+  end
+
+  it 'returns 0 on successful execution of commands' do
+    Runner.run( ['1.1.1.1-10','-c','echo'] ).should eq 0
+  end
+
+  it 'returns 4 on failure of execution of any command' do
+    Runner.run( ['1.1.1.1-10','-c',"no-way-this-is-a-valid-command-#{rand(99999999)}"] ).should eq 4
+  end
+  
+end