ether_shell 0.9.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.project

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>ether_shell</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>com.aptana.ide.core.unifiedBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>com.aptana.ruby.core.rubynature</nature>
+	</natures>
+</projectDescription>

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "rspec", "~> 2.5.0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,28 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+    rcov (0.9.9)
+    rspec (2.5.0)
+      rspec-core (~> 2.5.0)
+      rspec-expectations (~> 2.5.0)
+      rspec-mocks (~> 2.5.0)
+    rspec-core (2.5.1)
+    rspec-expectations (2.5.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.5.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.5.2)
+  rcov
+  rspec (~> 2.5.0)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Victor Costan
+
+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.rdoc

@@ -0,0 +1,54 @@
+= ether_shell
+
+ether_shell installs an IRB session with a DSL for testing Ethernet devices.
+
+== Usage
+
+Installing the gem will give you an ether_shell binary. The binary can be
+launched standalone to get to the IRB session, or it can be given a script that
+it will execute. Here is how I use it.
+
+    ether_shell < example.esh
+    
+Here is an example.esh that describes the DSL by example.
+
+    # All commands will log to standard output.
+    verbose
+    # IP's Ethernet II protocol number is 0x0800
+    connect 'eth0', 0x0800, '0x112233445566'
+    disconnect
+    # The device's Ethernet MAC can be specified in a number of ways.
+    connect 'eth0', 0x0800, 'BADMAC'
+    disconnect
+    connect 'eth0', 0x0800, '112233445566'
+    disconnect
+    # Sends a packet to the device.
+    out "This is short and will be padded"
+    # Again, multiple ways of specifying a packet are supported.
+    out "0xCAFEBABE"
+    out [0xDE, 0xAD, 0xBE, 0xAF]
+    # Receives a packet and compares it with a golden value.
+    # If the device echoed packets, these would be valid expectations. 
+    expect "This is short and will be padded"
+    expect "0xCAFEBABE000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
+    expect [0xDE, 0xAD, 0xBE, 0xAF] + [0x00] * 42
+    disconnect
+    exit
+
+The code should have full RSpec coverage, and the RSpecs can be used for
+documetation. You're most likely interested in the spec for ShellDsl.
+
+== Contributing to ether_shell
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 Massachusetts Institute of Technology. See LICENSE.txt for
+further details.

data/Rakefile

@@ -0,0 +1,50 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "ether_shell"
+  gem.homepage = "http://github.com/pwnall/ether_shell"
+  gem.license = "MIT"
+  gem.summary = %Q{IRB session specialized for testing Ethernet devices}
+  gem.description = %Q{IRB session specialized for testing Ethernet devices}
+  gem.email = "victor@costan.us"
+  gem.authors = ["Victor Costan"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "ether_shell #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.9.0

data/bin/ether_shell

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'ether_shell'
+
+require 'irb'
+
+include EtherShell::ShellDsl
+IRB.start __FILE__

data/ether_shell.gemspec

@@ -0,0 +1,85 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{ether_shell}
+  s.version = "0.9.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Victor Costan"]
+  s.date = %q{2011-03-22}
+  s.default_executable = %q{ether_shell}
+  s.description = %q{IRB session specialized for testing Ethernet devices}
+  s.email = %q{victor@costan.us}
+  s.executables = ["ether_shell"]
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+    ".project",
+    ".rspec",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "bin/ether_shell",
+    "ether_shell.gemspec",
+    "lib/ether_shell.rb",
+    "lib/ether_shell/expectation_error.rb",
+    "lib/ether_shell/high_socket.rb",
+    "lib/ether_shell/raw_socket.rb",
+    "lib/ether_shell/shell_dsl.rb",
+    "spec/ether_shell/high_socket_spec.rb",
+    "spec/ether_shell/raw_socket_spec.rb",
+    "spec/ether_shell/shell_dsl_spec.rb",
+    "spec/ether_shell_spec.rb",
+    "spec/spec_helper.rb",
+    "spec/support/raw_socket_stub.rb",
+    "spec/support/shell_stub.rb"
+  ]
+  s.homepage = %q{http://github.com/pwnall/ether_shell}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.6.0}
+  s.summary = %q{IRB session specialized for testing Ethernet devices}
+  s.test_files = [
+    "spec/ether_shell/high_socket_spec.rb",
+    "spec/ether_shell/raw_socket_spec.rb",
+    "spec/ether_shell/shell_dsl_spec.rb",
+    "spec/ether_shell_spec.rb",
+    "spec/spec_helper.rb",
+    "spec/support/raw_socket_stub.rb",
+    "spec/support/shell_stub.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, ["~> 2.5.0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, ["> 1.2.3"])
+    else
+      s.add_dependency(%q<rspec>, ["~> 2.5.0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<rspec>, ["> 1.2.3"])
+    end
+  else
+    s.add_dependency(%q<rspec>, ["~> 2.5.0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<rspec>, ["> 1.2.3"])
+  end
+end
+

data/lib/ether_shell.rb

@@ -0,0 +1,8 @@
+# Documentation here.
+module EtherShell
+end
+
+require 'ether_shell/expectation_error.rb'
+require 'ether_shell/high_socket.rb'
+require 'ether_shell/raw_socket.rb'
+require 'ether_shell/shell_dsl.rb'

data/lib/ether_shell/expectation_error.rb

@@ -0,0 +1,9 @@
+# :nodoc: namespace
+module EtherShell
+
+# Raised by ShellDsl#expect if the received packet doesn't match the pattern.
+class ExpectationError < StandardError
+
+end  # class EtherShell::ExpectationError
+
+end  # namespace EtherShell

data/lib/ether_shell/high_socket.rb

@@ -0,0 +1,122 @@
+# :nodoc: namespace
+module EtherShell
+
+# Wraps an Ethernet socket and abstracts away the Ethernet II frame.
+class HighSocket
+  # Creates a wrapper around a raw Ethernet socket.
+  #
+  # Args:
+  #   raw_socket_or_device:: a raw Ethernet socket or a string containing an
+  #                          Ethernet device name
+  #   ether_type:: 2-byte Ethernet packet type number
+  #   mac_address:: 6-byte MAC address for the Ethernet socket (optional if
+  #                 raw_socket_or_device is an Ethernet device name)
+  #
+  # Raises:
+  #   RuntimeError:: if mac isn't exactly 6-bytes long
+  def initialize(raw_socket_or_device, ether_type, mac_address = nil)
+    check_mac mac_address if mac_address
+    
+    if raw_socket_or_device.respond_to? :to_str
+      @source_mac = mac_address || RawSocket.mac(raw_socket_or_device)
+      @socket = RawSocket.socket raw_socket_or_device, ether_type
+    else
+      raise 'MAC address needed with raw socket' unless mac_address
+      @source_mac = mac_address.dup
+      @socket = raw_socket_or_device
+    end
+    
+    @dest_mac = nil
+    @ether_type = [ether_type].pack('n')
+  end
+
+  # Sets the destination MAC address for future calls to send.
+  #
+  # Args:
+  #   mac:: 6-byte MAC address for the Ethernet socket
+  #
+  # Raises:
+  #   RuntimeError:: if mac isn't exactly 6-bytes long
+  def connect(mac_address)
+    check_mac mac_address
+    @dest_mac = mac_address
+  end
+  
+  # Closes the underlying socket.
+  def close
+    @socket.close
+  end
+  
+  # Sends an Ethernet II frame.
+  #
+  # Args:
+  #   data:: the data bytes to be sent
+  #
+  # Raises:
+  #   RuntimeError:: if connect wasn' previously called
+  def send(data, send_flags = 0)
+    raise "Not connected" unless @dest_mac
+    send_to @dest_mac, data, send_flags
+  end
+  
+  # Sends an Ethernet II frame.
+  #
+  # Args:
+  #   mac_address:: the destination MAC address
+  #   data:: the data bytes to be sent
+  #
+  # Raises:
+  #   RuntimeError:: if connect wasn' previously called
+  def send_to(mac_address, data, send_flags = 0)
+    check_mac mac_address
+
+    padding = (data.length < 46) ? "\0" * (46 - data.length) : ''
+    packet = [mac_address, @source_mac, @ether_type, data, padding].join
+    @socket.send packet, send_flags
+  end
+  
+  # Receives an Ethernet II frame.
+  #
+  # Args:
+  #   buffer_size:: optional maximum packet size argument passed to the raw
+  #                 socket's recv method
+  #
+  # Returns the data and the source MAC address in the frame.
+  #
+  # This will discard incoming frames that don't match the MAC address that the
+  # socket is connected to, or the Ethernet packet type.
+  def recv(buffer_size = 8192)
+    raise "Not connected" unless @dest_mac
+    loop do
+      data, mac_address = recv_from buffer_size
+      return data if @dest_mac == mac_address
+    end
+  end
+  
+  # Receives an Ethernet II frame.
+  #
+  # Args:
+  #   buffer_size:: optional maximum packet size argument passed to the raw
+  #                 socket's recv method
+  #
+  # Returns the data in the frame.
+  #
+  # This will discard incoming frames that don't match the MAC address that the
+  # socket is connected to, or the Ethernet packet type.
+  def recv_from(buffer_size = 8192)
+    loop do
+      packet = @socket.recv buffer_size
+      next unless packet[12, 2] == @ether_type
+      next unless packet[0, 6] == @source_mac
+      return packet[14..-1], packet[6, 6]
+    end
+  end
+  
+  # Raises an exception if the given MAC address is invalid.
+  def check_mac(mac_address)
+    raise "Invalid MAC address" unless mac_address.length == 6
+  end
+  private :check_mac
+end  # class EtherShell::HighSocket
+
+end  # namespace EtherShell

data/lib/ether_shell/raw_socket.rb

@@ -0,0 +1,102 @@
+require 'socket'
+
+# :nodoc: namespace
+module EtherShell
+
+# Low-level socket creation functionality.
+module RawSocket
+  # A raw socket will receive all Ethernet frames, and send raw frames.
+  #
+  # Args:
+  #   eth_device:: device name for the Ethernet card, e.g. 'eth0'
+  #   ether_type:: Ethernet protocol number
+  def self.socket(eth_device = nil, ether_type = nil)
+    ether_type ||= all_ethernet_protocols
+    socket = Socket.new raw_address_family, Socket::SOCK_RAW, htons(ether_type)
+    socket.setsockopt Socket::SOL_SOCKET, Socket::SO_BROADCAST, true
+    set_socket_eth_device(socket, eth_device, ether_type) if eth_device
+    socket
+  end
+  
+  # The MAC address for an Ethernet card.
+  #
+  # Args:
+  #   eth_device:: device name for the Ethernet card, e.g. 'eth0'
+  def self.mac(eth_device)
+    case RUBY_PLATFORM
+    when /linux/
+      # /usr/include/net/if.h, structure ifreq
+      ifreq = [eth_device].pack 'a32'
+      # 0x8927 is SIOCGIFHWADDR in /usr/include/bits/ioctls.h
+      socket.ioctl 0x8927, ifreq
+      ifreq[18, 6]
+    else
+      raise "Unsupported platform #{RUBY_PLATFORM}"
+    end
+  end
+
+  class <<self
+    # Sets the Ethernet interface and protocol type for a socket.
+    def set_socket_eth_device(socket, eth_device, ether_type)
+      case RUBY_PLATFORM
+      when /linux/
+        if_number = get_interface_number eth_device
+        # struct sockaddr_ll in /usr/include/linux/if_packet.h
+        socket_address = [raw_address_family, htons(ether_type), if_number,
+                          0xFFFF, 0, 0, ""].pack 'SSISCCa8'
+        socket.bind socket_address
+      else
+        raise "Unsupported platform #{RUBY_PLATFORM}"
+      end
+      socket
+    end
+    private :set_socket_eth_device
+    
+    # The interface number for an Ethernet interface.
+    def get_interface_number(eth_device)
+      case RUBY_PLATFORM
+      when /linux/
+        # /usr/include/net/if.h, structure ifreq
+        ifreq = [eth_device].pack 'a32'
+        # 0x8933 is SIOCGIFINDEX in /usr/include/bits/ioctls.h
+        socket.ioctl 0x8933, ifreq
+        ifreq[16, 4].unpack('I').first
+      else
+        raise "Unsupported platform #{RUBY_PLATFORM}"
+      end
+    end
+    private :get_interface_number
+    
+    # The protocol number for listening to all ethernet protocols.
+    def all_ethernet_protocols
+      case RUBY_PLATFORM
+      when /linux/
+        3
+      else
+        raise "Unsupported platform #{RUBY_PLATFORM}"
+      end
+    end
+    private :all_ethernet_protocols
+    
+    # The AF / PF number for raw sockets.
+    def raw_address_family
+      case RUBY_PLATFORM
+      when /linux/
+        17  # cat /usr/include/bits/socket.h | grep PF_PACKET
+      when /darwin/
+        18  # cat /usr/include/sys/socket.h | grep AF_LINK
+      else
+        raise "Unsupported platform #{RUBY_PLATFORM}"
+      end
+    end
+    private :raw_address_family
+  
+    # Converts a 16-bit integer from host-order to network-order.
+    def htons(short_integer)
+      [short_integer].pack('n').unpack('S').first
+    end
+    private :htons
+  end
+end  # module EtherShell::RawSocket
+
+end  # namespace EtherShell

data/lib/ether_shell/shell_dsl.rb

@@ -0,0 +1,151 @@
+# :nodoc: namespace
+module EtherShell
+
+# Provides the Ethernet shell DSL.
+#
+# Include this in the evaluation context where you want the Ethernet shell DSL.
+module ShellDsl
+  # Creates a Ethernet socket for this shell.
+  #
+  # Args:
+  #   eth_device:: an Ethernet device name, e.g. 'eth0'
+  #   ether_type:: 2-byte Ethernet packet type number
+  #   dest_mac:: MAC address of the endpoint to be tested; it can be a raw
+  #              6-byte string, 
+  def connect(eth_device, ether_type, dest_mac)
+    raise "Already connected. did you forget to call disconnect?" if @_socket
+    mac_bytes = EtherShell::ShellDsl.parse_mac_data dest_mac
+    @_socket = EtherShell::HighSocket.new eth_device, ether_type
+    @_socket.connect mac_bytes
+    if @_verbose
+      print ['Connected to ', mac_bytes.unpack('H*').first, ' using ',
+             '%04x' % ether_type, ' via ', eth_device, "\n"].join
+    end
+    @_nothing = ''
+    class <<@_nothing
+      def inspect
+        ''
+      end
+    end
+    EtherShell::ShellDsl.nothing
+  end
+
+  # Disconnects this shell's Ethernet socket.
+  #
+  # A socket should have been connected previously, using connect or socket. The
+  # shell can take further connect and socket calls.
+  def disconnect
+    raise "Not connected. did you forget to call connect?" unless @_socket
+    @_socket.close
+    @_socket = nil
+    print "Disconnected\n" if @_verbose
+    EtherShell::ShellDsl.nothing
+  end
+  
+  # Connects this shell to a pre-created socket
+  #
+  # Args:
+  #   high_socket:: socket that behaves like an EtherShell::HighSocket
+  def socket(high_socket)
+    raise "Already connected. did you forget to call disconnect?" if @_socket
+    @_socket = high_socket
+    print "Connected directly to socket\n" if @_verbose
+    EtherShell::ShellDsl.nothing
+  end
+  
+  # Enables or disables the console output in out and expect.
+  #
+  # Args:
+  #   true_or_false:: if true, out and expect will produce console output
+  def verbose(true_or_false = true)
+    @_verbose = true_or_false
+    EtherShell::ShellDsl.nothing
+  end
+  
+  # Outputs a packet.
+  #
+  # Args:
+  #   packet_data:: an Array of integers (bytes), a hex string starting with 0x,
+  #                 or a string of raw bytes
+  #
+  # Raises:
+  #   RuntimeError:: if the shell was not connected to a socket by a call to
+  #                  connect or socket
+  def out(packet_data)
+    raise "Not connected. did you forget to call connect?" unless @_socket
+    bytes = EtherShell::ShellDsl.parse_packet_data packet_data
+    
+    
+    print "Sending #{bytes.unpack('H*').first}... " if @_verbose
+    @_socket.send bytes
+    print "OK\n" if @_verbose
+    EtherShell::ShellDsl.nothing
+  end
+  
+  # Receives a packet and matches it against an expected value.
+  #
+  # Args:
+  #   packet_data:: an Array of integers (bytes), a hex string starting with 0x,
+  #                 or a string of raw bytes
+  #
+  # Raises:
+  #   RuntimeError:: if the shell was not connected to a socket by a call to
+  #                  connect or socket
+  #   RuntimeError:: if the received packet doesn't match the expected value
+  def expect(packet_data)
+    raise "Not connected. did you forget to call connect?" unless @_socket
+    expected_bytes = EtherShell::ShellDsl.parse_packet_data packet_data
+    
+    print "Receiving... " if @_verbose
+    bytes = @_socket.recv
+    print " #{bytes.unpack('H*').first} " if @_verbose
+    if bytes == expected_bytes
+      print "OK\n" if @_verbose
+    else
+      print "!= #{expected_bytes.unpack('H*').first} ERROR\n" if @_verbose
+      raise EtherShell::ExpectationError,
+          "#{bytes.unpack('H*').first} != #{expected_bytes.unpack('H*').first}"
+    end
+    EtherShell::ShellDsl.nothing
+  end
+  
+  # :nodoc: turns a packet pattern into a string of raw bytes
+  def self.parse_packet_data(packet_data)
+    if packet_data.kind_of? Array
+      # Array of integers.
+      packet_data.pack('C*')
+    elsif packet_data.kind_of? String
+      if packet_data[0, 2] == '0x'
+        [packet_data[2..-1]].pack('H*')
+      else
+        packet_data
+      end
+    end
+  end
+
+  # :nodoc: turns a packet pattern into a string of raw bytes
+  def self.parse_mac_data(mac_data)
+    if mac_data.length == 12
+      [mac_data].pack('H*')
+    elsif mac_data.length == 14 && mac_data[0, 2] == '0x'
+      [mac_data[2, 12]].pack('H*')
+    elsif mac_data.kind_of? Array
+      mac_data.pack('C*')
+    else
+      mac_data
+    end
+  end
+  
+  # :nodoc: value that doesn't show up in irb
+  def self.nothing
+    @nothing ||= Nothing.new
+  end
+  
+  class Nothing
+    def inspect
+      ''
+    end
+  end
+end  # module EtherShell::ShellDsl
+
+end  # namespace EtherShell

data/spec/ether_shell/high_socket_spec.rb

@@ -0,0 +1,102 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe 'HighSocket' do
+  let(:eth_device) { 'eth0' }
+  let(:eth_type) { 0x0800 }
+  let(:mac) { EtherShell::RawSocket.mac eth_device }
+  let(:dest_mac) { "\x00\x11\x22\x33\x44\x55" }
+  let(:bcast_mac) { "\xff" * 6 }
+  
+  shared_examples_for 'a real socket' do
+    it 'should output a packet' do
+      @socket.send_to dest_mac, "\r\n"
+    end
+
+    it 'should receive some network noise' do
+      @socket.recv_from.first.should_not be_empty
+    end
+  end
+
+  describe 'on eth0' do
+    before { @socket = EtherShell::HighSocket.new eth_device, eth_type }
+    after { @socket.close }
+
+    it_should_behave_like 'a real socket'
+  end
+  
+  describe 'from raw socket' do
+    before do
+      raw_socket = EtherShell::RawSocket.socket eth_device, eth_type
+      @socket = EtherShell::HighSocket.new raw_socket, eth_type, mac
+    end
+    after { @socket.close }
+
+    it_should_behave_like 'a real socket'
+  end
+  
+  describe 'stubbed' do
+    let(:socket_stub) do
+      RawSocketStub.new([
+        [mac, dest_mac, "\x88\xB7", 'Wrong Ethernet type'].join,
+        [bcast_mac, dest_mac, [eth_type].pack('n'), 'Wrong dest MAC'].join,
+        [mac, bcast_mac, [eth_type].pack('n'), 'Bcast'].join,
+        [mac, dest_mac, [eth_type].pack('n'), 'Correct'].join,
+      ])
+    end
+    let(:socket) { EtherShell::HighSocket.new socket_stub, eth_type, mac }
+    
+    shared_examples_for 'after a small send call' do
+      it 'should send a single packet' do
+        socket_stub.sends.length.should == 1
+      end
+      it 'should pad the packet' do
+        socket_stub.sends.first.length.should == 60
+      end
+      it 'should assemble packet correctly in send' do
+        gold = [dest_mac, mac, [eth_type].pack('n'), 'Send data'].join
+        socket_stub.sends.first[0, gold.length].should == gold
+      end
+    end
+    
+    describe 'send_to' do
+      before { socket.send_to dest_mac, 'Send data' }
+      it_should_behave_like 'after a small send call'
+    end
+    
+    describe 'recv_from' do
+      it 'should filter down to the correct packet' do
+        socket.recv_from.should == ['Bcast', bcast_mac]
+      end
+    end
+    
+    describe 'unconnected' do
+      it 'should complain in recv' do
+        lambda { socket.recv }.should raise_error(RuntimeError)
+      end
+
+      it 'should complain in send' do
+        lambda { socket.send 'Send data' }.should raise_error(RuntimeError)
+      end
+    end
+    
+    describe 'connected' do
+      before { socket.connect dest_mac }
+      
+      describe 'send' do
+        before { socket.send 'Send data' }
+        it_should_behave_like 'after a small send call'
+      end
+      
+      describe 'recv' do
+        it 'should filter down to the correct packet' do
+          socket.recv.should == 'Correct'
+        end
+      end
+    end
+    
+    it 'should delegate close' do
+      socket_stub.should_receive(:close).once
+      socket.close
+    end
+  end
+end

data/spec/ether_shell/raw_socket_spec.rb

@@ -0,0 +1,41 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe 'RawSocket' do
+  let(:eth_device) { 'eth0' }
+  let(:mac) { EtherShell::RawSocket.mac eth_device }
+  
+  describe 'mac' do
+    let(:golden_mac) do
+      hex_mac = `ifconfig #{eth_device}`[/HWaddr .*$/][7..-1]
+      [hex_mac.gsub(':', '').strip].pack('H*')
+    end
+    
+    it 'should have 6 bytes' do
+      mac.length.should == 6
+    end
+    
+    it 'should match ifconfig output' do
+      mac.should == golden_mac
+    end
+  end
+  
+  describe 'socket' do
+    let(:eth_type) { 0x88B7 }
+    
+    before { @socket = EtherShell::RawSocket.socket eth_device }
+    after { @socket.close }
+    
+    it 'should be able to receive data' do
+      @socket.should respond_to(:recv)
+    end
+    
+    it 'should output a packet' do
+      packet = [mac, mac, [eth_type].pack('n'), "\r\n" * 32].join
+      @socket.send packet, 0
+    end
+
+    it 'should receive some network noise' do
+      @socket.recv(8192).should_not be_empty
+    end
+  end
+end

data/spec/ether_shell/shell_dsl_spec.rb

@@ -0,0 +1,198 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe 'ShellDsl' do
+  let(:eth_device) { 'eth0' }
+  let(:eth_type) { 0x0800 }
+  let(:eth_type_hex) { '0800' }
+  let(:mac) { EtherShell::RawSocket.mac eth_device }
+  let(:dest_mac) { "\x00\x11\x22\x33\x44\x55" }
+  let(:dest_mac_hex) { '001122334455' }
+  let(:bcast_mac) do
+    string = "\xff" * 6
+    # Awful hack so the MAC matches any packet.
+    class <<string
+      def ==(other)
+        other.respond_to?(:length) && other.length == 6
+      end
+    end
+    string
+  end
+
+  let(:shell) { ShellStub.new }
+
+  shared_examples_for 'a connected shell' do
+    it 'should be able to send a packet' do
+      shell.out 'Shell test packet'
+    end
+    
+    it 'should be able to receive noise' do
+      lambda {
+        shell.expect 'Impossible pattern'
+      }.should raise_error(EtherShell::ExpectationError)
+    end
+    
+    it 'should not connect again' do
+      lambda {
+        shell.connect eth_device, eth_type, bcast_mac
+      }.should raise_error(RuntimeError)
+    end
+    
+    it 'should not accept a socket again' do
+      raw_socket = EtherShell::HighSocket.new eth_device, eth_type
+      lambda {
+        shell.socket raw_socket
+      }.should raise_error(RuntimeError)
+      raw_socket.close
+    end
+  end
+
+  describe 'connected to new socket' do
+    before { shell.connect eth_device, eth_type, bcast_mac }
+    after { shell.disconnect }
+    
+    it_should_behave_like 'a connected shell'
+  end
+  
+  describe 'connected to a live socket' do
+    let(:live_socket) do
+      socket = EtherShell::HighSocket.new eth_device, eth_type
+      socket.connect bcast_mac
+      socket
+    end
+    before { shell.socket live_socket }
+    after { shell.disconnect }
+    
+    it_should_behave_like 'a connected shell'
+  end
+  
+  
+  describe 'disconnected' do
+    it 'should not send packets' do
+      lambda {
+        shell.out 'Will never go out'
+      }.should raise_error(RuntimeError)
+    end
+    
+    it 'should not expect packets' do
+      lambda {
+        shell.expect 'Impossible pattern'
+      }.should raise_error(RuntimeError)
+    end
+  end
+  
+  describe 'connected to stubs' do
+    let(:socket_stub) do
+      RawSocketStub.new([
+        [mac, dest_mac, "\x88\xB7", 'Wrong Ethernet type'].join,
+        [bcast_mac, dest_mac, [eth_type].pack('n'), 'Wrong dest MAC'].join,
+        [mac, bcast_mac, [eth_type].pack('n'), 'Bcast'].join,
+        [mac, dest_mac, [eth_type].pack('n'), "\xC0\xDE\xAA\x13\x37"].join,
+      ])
+    end
+    let(:stubbed_shell_socket) do
+      socket = EtherShell::HighSocket.new socket_stub, eth_type, mac
+      socket.connect dest_mac
+      socket
+    end
+    before { shell.socket stubbed_shell_socket }
+    
+    let(:golden_sends) do
+      [
+        [dest_mac, mac, [eth_type].pack('n'), "\x13\x37\xAA\xC0\xDE",
+         "\0" * 41].join
+      ]
+    end
+    
+    it 'should send raw packet' do
+      shell.out "\x13\x37\xAA\xC0\xDE"
+      socket_stub.sends.should == golden_sends
+    end
+    
+    it 'should send array packet' do
+      shell.out [0x13, 0x37, 0xAA, 0xC0, 0xDE]
+      socket_stub.sends.should == golden_sends
+    end
+
+    it 'should send hex packet' do
+      shell.out '0x1337AAC0DE'
+      socket_stub.sends.should == golden_sends
+    end
+
+    it 'should expect raw packet' do
+      lambda {
+        shell.expect "\xC0\xDE\xAA\x13\x37"
+      }.should_not raise_error
+    end
+    
+    it 'should expect array packet' do
+      lambda {
+        shell.expect [0xC0, 0xDE, 0xAA, 0x13, 0x37]
+      }.should_not raise_error
+    end
+
+    it 'should expect hex packet' do
+      lambda {
+        shell.expect '0xC0DEAA1337'
+      }.should_not raise_error
+    end
+    
+    it 'should raise on expectation mismatch' do
+      lambda {
+        shell.expect '0xC0DEAA1338'
+      }.should raise_error(EtherShell::ExpectationError)
+    end
+    
+    describe 'with verbosity enabled' do
+      before do
+        shell.verbose
+        shell.allow_console
+      end
+      
+      it 'should log disconnects' do
+        shell.disconnect
+        shell.console.should include('Disconnect')
+      end
+      
+      it 'should log direct connects' do
+        shell.disconnect
+        shell.socket stubbed_shell_socket
+        shell.console.should include('Connected')
+        shell.console.should include('directly to socket')
+      end
+      
+      it 'should log socket connects' do
+        shell.disconnect
+        shell.connect eth_device, eth_type, dest_mac
+        shell.console.should include('Connected')
+        shell.console.should include(eth_device)
+        shell.console.should include(eth_type_hex)
+        shell.console.should include(dest_mac_hex)
+      end
+      
+      it 'should log packet transmissions' do
+        shell.out '0x1337AAC0DE'
+        shell.console.should include('Sending')
+        shell.console.should include('OK')
+        shell.console.should include('1337aac0de')
+      end
+      
+      it 'should log successful expectations' do
+        shell.expect '0xC0DEAA1337'
+        shell.console.should include('Receiving')
+        shell.console.should include('OK')
+        shell.console.should include('c0deaa1337')
+      end
+      
+      it 'should log failed expectations' do
+        lambda {
+          shell.expect '0xC0DEAA1338'
+        }.should raise_error(EtherShell::ExpectationError)
+        shell.console.should include('Receiving')
+        shell.console.should include('ERROR')
+        shell.console.should include('c0deaa1337')
+        shell.console.should include('c0deaa1338')
+        shell.console.should include('!=')
+      end
+    end
+  end
+end

data/spec/ether_shell_spec.rb

@@ -0,0 +1,4 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "EtherShell" do
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+require 'ether_shell'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  
+end

data/spec/support/raw_socket_stub.rb

@@ -0,0 +1,23 @@
+class RawSocketStub
+  def initialize(recv_data)
+    @packets = recv_data
+    @sends = []
+  end
+  
+  def recv(buffer_size)
+    raise 'recv called too many times' if @packets.empty?
+    @packets.shift
+  end
+  
+  def send(data, flags)
+    raise 'Weird flags' if flags != 0
+    @sends << data
+  end
+  
+  def close
+    @packets = nil
+    @sends = nil
+  end
+
+  attr_reader :sends
+end

data/spec/support/shell_stub.rb

@@ -0,0 +1,17 @@
+class ShellStub
+  include EtherShell::ShellDsl
+  
+  def initialize()
+    @console = nil
+  end
+  attr_reader :console
+  
+  def print(output)
+    raise "Console output not allowed" unless @console
+    @console << output
+  end
+  
+  def allow_console
+    @console ||= ''
+  end
+end

metadata

@@ -0,0 +1,173 @@
+--- !ruby/object:Gem::Specification 
+name: ether_shell
+version: !ruby/object:Gem::Version 
+  hash: 59
+  prerelease: 
+  segments: 
+  - 0
+  - 9
+  - 0
+  version: 0.9.0
+platform: ruby
+authors: 
+- Victor Costan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-03-22 00:00:00 -04:00
+default_executable: ether_shell
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 2
+        - 5
+        - 0
+        version: 2.5.0
+  version_requirements: *id001
+  name: rspec
+  prerelease: false
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  version_requirements: *id002
+  name: bundler
+  prerelease: false
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 1
+        - 5
+        - 2
+        version: 1.5.2
+  version_requirements: *id003
+  name: jeweler
+  prerelease: false
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id004
+  name: rcov
+  prerelease: false
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        hash: 25
+        segments: 
+        - 1
+        - 2
+        - 3
+        version: 1.2.3
+  version_requirements: *id005
+  name: rspec
+  prerelease: false
+description: IRB session specialized for testing Ethernet devices
+email: victor@costan.us
+executables: 
+- ether_shell
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.rdoc
+files: 
+- .document
+- .project
+- .rspec
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.rdoc
+- Rakefile
+- VERSION
+- bin/ether_shell
+- ether_shell.gemspec
+- lib/ether_shell.rb
+- lib/ether_shell/expectation_error.rb
+- lib/ether_shell/high_socket.rb
+- lib/ether_shell/raw_socket.rb
+- lib/ether_shell/shell_dsl.rb
+- spec/ether_shell/high_socket_spec.rb
+- spec/ether_shell/raw_socket_spec.rb
+- spec/ether_shell/shell_dsl_spec.rb
+- spec/ether_shell_spec.rb
+- spec/spec_helper.rb
+- spec/support/raw_socket_stub.rb
+- spec/support/shell_stub.rb
+has_rdoc: true
+homepage: http://github.com/pwnall/ether_shell
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.0
+signing_key: 
+specification_version: 3
+summary: IRB session specialized for testing Ethernet devices
+test_files: 
+- spec/ether_shell/high_socket_spec.rb
+- spec/ether_shell/raw_socket_spec.rb
+- spec/ether_shell/shell_dsl_spec.rb
+- spec/ether_shell_spec.rb
+- spec/spec_helper.rb
+- spec/support/raw_socket_stub.rb
+- spec/support/shell_stub.rb