nmunch 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+results.html
+pkg
+html
+*.gem

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in nmunch.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,33 @@
+PATH
+  remote: .
+  specs:
+    nmunch (1.0.0)
+      methadone (~> 1.2.3)
+      paint
+      pcap
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    methadone (1.2.3)
+      bundler
+    paint (0.8.5)
+    pcap (0.7.7)
+    rake (0.9.5)
+    rspec (2.12.0)
+      rspec-core (~> 2.12.0)
+      rspec-expectations (~> 2.12.0)
+      rspec-mocks (~> 2.12.0)
+    rspec-core (2.12.1)
+    rspec-expectations (2.12.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.12.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  nmunch!
+  rake (~> 0.9.2)
+  rspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Michael Henriksen
+
+MIT License
+
+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,103 @@
+# Nmunch
+
+![OM NOM NOM NOM](https://dl.dropbox.com/u/70881769/omnomnomnom.jpg)
+
+Nmunch is a simple passive network discovery tool to find live nodes just by
+listening to [ARP][arp] and broadcast packets on a network interface.
+
+The main reason why I built this tool was mostly to have an excuse to play around
+with the [ruby-pcap gem][ruby-pcap], but it turned out to be quite useful and the
+architecture is flexible enough to extend the tool to do pretty much anything
+with a discovered node.
+
+## Requirements
+
+ - Ruby 1.9
+ - libpcap (<http://www.tcpdump.org/>)
+
+## Installation
+
+    gem install nmunch
+
+## Usage
+
+![Nmunch munching](https://dl.dropbox.com/u/70881769/nmunch.png "Nmunch munching packets on a network")
+
+Nmunch is pretty straight-forward and supports two different methods:
+
+### Listen on a network device
+
+    nmunch -i <device name>
+
+To find the names of your network devices, use `ifconfig` in a terminal. Usually,
+they are called `eth0`, `en1`, etc.
+
+To stop listening, simply press `Ctrl`+`C` to interrupt. It might take a couple of
+seconds before it reacts.
+
+
+### Analyze a PCAP capture file
+
+Nmunch can also find nodes from a `pcap` capture file:
+
+    nmunch -f <path/to/pcap/file.pcap>
+
+### See all options
+
+To see all options for Nmunch, type:
+
+    nmunch --help
+
+## Extending Nmunch
+
+I have tried to keep the architecture pretty flexible with a simple *publish/subscribe* pattern for handling the discovered nodes. So if you want all nodes to be pwned by your secret 0day spl0itz, you can write a new node subscriber to do that for you. Have a look at `Nmunch::Subscriber::Stdout` for an example of how to write a node subscriber
+
+### *Y U NO capture [insert protocol name] to find more nodes!?!1*
+
+The current version of Nmunch only looks for [ARP][arp] and broadcast IP packets which captures quite a lot of nodes, but if you have more ideas, you can easily make a new packet dissector to handle it. see `Nmunch::Dissectors::Arp` for an example of how to write a packet dissector.
+
+## Roadmap
+
+This is what I have on the roadmap for Nmunch:
+
+### ▢ More tests
+### ▢ Improve documentation
+### ▢ Export results in formats compatible with other tools
+### ▢ Easier way to register custom node subscribers
+### ▢ Extract more interesting information apart from live nodes
+### ▢ Make a [Metasploit] Auxiliary module version of Nmunch
+
+## Contributing
+
+Feel free to file an issue, even if you don't have time to submit a patch.
+
+Please try to include tests for any patch you submit.  If you don't include tests, I'll have to write one, and it'll take longer to get your code in.
+
+## License
+
+Copyright (c) 2012 Michael Henriksen
+
+MIT License
+
+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.
+
+[arp]: http://en.wikipedia.org/wiki/Address_Resolution_Protocol "Address Resolution Protocol"
+[ruby-pcap]: https://github.com/ahobson/ruby-pcap
+[metasploit]: http://www.metasploit.com/ "Metasploit penetration testing framework"

data/Rakefile

@@ -0,0 +1,44 @@
+def dump_load_path
+  puts $LOAD_PATH.join("\n")
+  found = nil
+  $LOAD_PATH.each do |path|
+    if File.exists?(File.join(path,"rspec"))
+      puts "Found rspec in #{path}"
+      if File.exists?(File.join(path,"rspec","core"))
+        puts "Found core"
+        if File.exists?(File.join(path,"rspec","core","rake_task"))
+          puts "Found rake_task"
+          found = path
+        else
+          puts "!! no rake_task"
+        end
+      else
+        puts "!!! no core"
+      end
+    end
+  end
+  if found.nil?
+    puts "Didn't find rspec/core/rake_task anywhere"
+  else
+    puts "Found in #{path}"
+  end
+end
+require 'bundler'
+require 'rake/clean'
+
+begin
+  require 'rspec/core/rake_task'
+rescue LoadError
+  dump_load_path
+  raise
+end
+
+include Rake::DSL
+
+Bundler::GemHelper.install_tasks
+
+RSpec::Core::RakeTask.new do |t|
+  # Put spec opts in a file named .rspec in root
+end
+
+task :default => [:spec]

data/bin/nmunch

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'methadone'
+require 'pcap'
+require 'paint'
+require 'ipaddr'
+require 'nmunch'
+
+class App
+  include Methadone::Main
+  include Methadone::CLILogging
+
+  main do
+    begin
+      if !options[:interface] && !options[:file]
+        help_now!("You must specify an interface or a PCAP file.")
+      end
+
+      logger.debug("Command-line options: #{options.inspect}")
+
+      logger.debug("Setting up report")
+      report = Nmunch::Report.new(options)
+
+      logger.debug("Registering STDOUT node subscriber")
+      report.register_subscriber(Nmunch::Subscribers::Stdout.new(options))
+
+      # Disable output coloring if specified in options
+      if options.include?('no-color')
+        logger.debug("Disabling output coloring")
+        Paint.mode = 0
+      end
+
+      if !options.include?('no-banner')
+        puts Paint[Nmunch.banner, :blue]
+        puts Paint[" Munching on packets om nom nom nom...\n", :blue]
+      end
+
+      # Start munching packets and find live nodes...
+      logger.debug("Munching packets now...")
+      Nmunch.munch!(options) do |node|
+        logger.debug("Found node: #{node.ip_address} (#{node.mac_address})")
+        report.publish_node(node)
+      end
+
+      logger.debug("Done, printing summary")
+      puts "\n#{report.summary}"
+
+    rescue Exception => e
+      if !e.is_a?(Interrupt)
+        logger.debug("Caught exception!")
+        logger.debug(e.inspect)
+        puts Paint[" Warp Core Breach!", :red]
+        puts Paint[" [#{e.class}] #{e.message}", :red]
+      else
+        logger.debug("Caught interrupt")
+        puts "\n#{report.summary}"
+        exit!
+      end
+    end
+  end
+
+  on("-i INTERFACE", "--interface", "Interface to munch packets on")
+  on("-f FILE", "--file",           "Path to PCAP file to analyze")
+  on("--no-prefix-lookup",          "Disable MAC prefix lookups")
+  on("--no-banner",                 "Don't display awesome Nmunch banner")
+  on("--no-color",                  "Don't colorize output")
+
+  description "A passive network discovery tool."
+  version Nmunch::VERSION
+
+  use_log_level_option
+
+  go!
+end

data/lib/nmunch.rb

@@ -0,0 +1,60 @@
+require "nmunch/version"
+require "nmunch/dissectors/base"
+require "nmunch/dissectors/ip"
+require "nmunch/dissectors/arp"
+require "nmunch/subscribers/base"
+require "nmunch/subscribers/stdout"
+require "nmunch/node"
+require "nmunch/report"
+require "nmunch/mac_oui_lookup"
+
+# Public: Main Nmunch module
+#
+# Acts as a facade in front of the ruby-pcap gem and abstracts away the packet analysis.
+module Nmunch
+
+  # Internal: PCAP filter expression to only get ARP and broadcast packets
+  CAPTURE_FILTER = 'arp or broadcast'
+
+  # Public: Start munching on packets on interface or from PCAP file
+  #
+  # options - Hash of command line options
+  #
+  # Yields an Nmunch::Node with IP and MAC address information
+  def self.munch!(options)
+    create_capture_object(options).each_packet do |packet|
+      dissector = Nmunch::Dissectors::Base.factory(packet)
+      yield Nmunch::Node.create_from_dissector(dissector)
+    end
+  end
+
+  # Internal: Get the awesome Nmunch ASCII banner
+  #
+  # Returns ASCII banner
+  def self.banner
+    banner = <<EOB
+
+ 88b 88 8b    d8 88   88 88b 88  dP""b8 88  88
+ 88Yb88 88b  d88 88   88 88Yb88 dP   `" 88  88
+ 88 Y88 88YbdP88 Y8   8P 88 Y88 Yb      888888
+ 88  Y8 88 YY 88 `YbodP' 88  Y8  YboodP 88  88
+EOB
+  end
+
+  private
+
+  # Internal: Create a capture object from options
+  #
+  # options - Hash of command line options
+  #
+  # Returns a Pcap::Capture object on interface or a PCAP file
+  def self.create_capture_object(options)
+    if options[:interface]
+      capture = Pcap::Capture.open_live(options[:interface])
+    else
+      capture = Pcap::Capture.open_offline(options[:file])
+    end
+    capture.setfilter(CAPTURE_FILTER)
+    capture
+  end
+end

data/lib/nmunch/dissectors/arp.rb

@@ -0,0 +1,26 @@
+module Nmunch
+  module Dissectors
+
+    # Public: Address Resolution Protocol dissector
+    #
+    # Extracts IP and MAC address from an ARP packet
+    #
+    # See http://en.wikipedia.org/wiki/Address_Resolution_Protocol for protocol details
+    class Arp < Nmunch::Dissectors::Base
+
+      # Public: Get sender IP address from ARP packet
+      #
+      # Returns IP address
+      def ip_address
+        @ip_address ||= IPAddr.new(raw_data[28..31].join.hex, Socket::AF_INET).to_s
+      end
+
+      # Public: Get sender MAC address from ARP packet
+      #
+      # Returns MAC address
+      def mac_address
+        @mac_address ||= raw_data[22..27].join(':')
+      end
+    end
+  end
+end

data/lib/nmunch/dissectors/base.rb

@@ -0,0 +1,46 @@
+module Nmunch
+  module Dissectors
+
+    # Public: Base dissector class
+    class Base
+      attr_reader :pcap_packet, :raw_data
+
+      # Public: Initializer
+      #
+      # pcap_packet - An instance of Pcap::Packet
+      #
+      # Stores the packet and extracts to raw packet data in a way that makes
+      # it easy to dissect
+      #
+      # Returns nothing
+      def initialize(pcap_packet)
+        @pcap_packet = pcap_packet
+        extract_raw_packet_data
+      end
+
+      # Public: Dissector factory
+      #
+      # pcap_packet - An instance of Pcap::Packet
+      #
+      # Returns an instance of a dissector
+      def self.factory(pcap_packet)
+        if pcap_packet.ip?
+          Nmunch::Dissectors::Ip.new(pcap_packet)
+        else
+          Nmunch::Dissectors::Arp.new(pcap_packet)
+        end
+      end
+
+      private
+
+      # Internal: Extract raw packet data and store it in @raw_data
+      #
+      # Unpacks data to HEX and splits it into an array of bytes
+      #
+      # Returns nothing
+      def extract_raw_packet_data
+        @raw_data = pcap_packet.raw_data.unpack('H*').first.scan(/.{2}/)
+      end
+    end
+  end
+end

data/lib/nmunch/dissectors/ip.rb

@@ -0,0 +1,26 @@
+module Nmunch
+  module Dissectors
+
+    # Public: Internet Protocol dissector
+    #
+    # Extracts IP and MAC address from IP packet
+    #
+    # See http://en.wikipedia.org/wiki/Internet_Protocol for protocol details
+    class Ip < Nmunch::Dissectors::Base
+
+      # Public: Get sender IP address from IP packet
+      #
+      # Returns IP address
+      def ip_address
+        @ip_address ||= pcap_packet.ip_src.to_s
+      end
+
+      # Public: Get sender MAC address from IP packet
+      #
+      # Returns MAC address
+      def mac_address
+        @mac_address ||= raw_data[6..11].join(':')
+      end
+    end
+  end
+end