rbkb 0.6.10

data/History.txt

@@ -0,0 +1,74 @@
+== 0.6.10 / 2009-09-30
+  * added -b/--blitsrv argument to plugsrv
+  * added --target-tls/--server-tls arguments to plugsrv for TLS support
+
+== 0.6.9.1 / 2009-09-08
+  * fixed a typo in random_string()
+
+== 0.6.9 / 2009-09-01
+* Enhancements
+  * telson and feed now support -s/--source address:port using TCP with 
+    bind_connect via eventmachine
+  * random_string and random_alphanum helper methods added 
+* Bug-Fix
+  * Plug's PeerList.find_peers was returning nil resulting in problems for 
+    blit -l amongst other things.
+
+== 0.6.8.1 / 2009-06-12
+* Enhancements
+  * Added String.rotate_bytes per request for a rotation cypher by 
+    wardwouts@github. I pilfered this implementation mostly from Timur Duehr.
+
+== 0.6.8 / 2009-06-04
+* Enhancements
+  * 0.6.8 is geared towards beginning to make rbkb compatible with ruby 1.9.x 
+    (tested on 1.9.1). Had to sacrifice the 'uuid' helper method 
+    since something happened to SHA1 in ruby 1.9. It may make a comeback if 
+    anybody yells about this.
+* Known Issues:
+  * There are problems with binary releases of eventmachine with 1.9.1 on win32
+    this does not appear to be caused by rbkb, however we're keeping an eye on 
+    it. For now, this is causing the plug tools to crash and test cases to 
+    fail on 1.9.1 win32.
+
+== 0.6.7
+* Enhancements
+  * Http::Parameters was given the same treatement as headers got in 0.6.6. 
+    Technically params are supposed to be unique, but we try to stay flexible 
+    in Rbkb. 
+* Bug-fix:
+  * Fixed a silly typing bug in Http::Parameters.set_param introduced
+    around 0.6.6
+
+== 0.6.6
+* Bug-fix:
+  * Http library improperly made headers unique by name. The library has
+    been changed so that headers no longer tries to pretend to be a hash.
+
+== 0.6.5.2 
+* Enhancements
+  * d64 and b64 now support the -f option for input files as rdoc indicates
+    Thanks to Cory Scott for catching this doc error and for his patch.
+
+== 0.6.5.1 
+* Minor bug-fix
+  * fixed a problem with the gem, version bump is for github visibility
+
+== 0.6.5 / 2009-03-24
+
+* Enhancements
+  * Added a http protocol library (Rbkb::Http)
+  * Added TLS support to telson (-S/--start-tls in cli)
+  * Added raw dump output to telson (-d raw/hex in cli : hex is default)
+
+== 0.6.4 / 2009-03-20
+
+* Enhancements
+  * Added unit tests for all cli utilities. Most are fairly complete.
+
+== 0.6.3 / 2009-03-10
+
+* Enhancements
+  * Started using bones to help manage this mess. History.txt is born!
+  * begun adding test cases for cli utils
+  * crc32 takes an optional filename argument as first arg

data/README.rdoc

@@ -0,0 +1,149 @@
+= rbkb
+
+* http://emonti.github.com/rbkb
+
+== DESCRIPTION:
+
+Ruby BlackBag (rbkb)
+
+A miscellaneous collection of command-line tools and ruby library helpers 
+related to pen-testing and reversing. 
+
+=== Rationale
+
+    Disclaimer: 
+    Most of what's in the black bag came from a desire to do less typing.
+    But there might be a few clever things that were added by accident.
+
+rbkb is inspired by Matasano BlackBag (a set of similar tools written in C).
+
+See:
+* http://www.matasano.com/log/1048/blackbag-091-new-link-and-minor-fixes/
+* http://www.matasano.com/log/552/code-release-blackbag-09-binary-protocol-reversing-unix-thingies/
+
+Things go into the black bag as they are stolen (as a compliment!) or dreamed 
+up, usually for simplifying some repetetive task or a desire for a new tool.
+
+Along the way, some of tools in the blackbag spirit make their way into 'rbkb' 
+that may or may not make it to 'bkb' right away (if ever). Similarly some of
+the things in 'bkb' have not yet made it to 'rbkb' (and may not).
+
+
+== SYNOPSIS:
+
+=== Command Line Tools
+
+The tools almost all support '-h', but I'll admit this only goes so far.
+See cli_usage.rdoc for usage and a bit of extra info on the various tools. 
+
+When I get some spare time, I'll try and do up some examples of using all
+the tools.
+
+
+=== Plug
+
+Black Bag includes several tools for testing network protocols using plugboard
+proxies. Users of the original Matasano BlackBag may be familiar with the
+commands 'bkb replug', 'bkb telson', and 'bkb blit'.
+
+Ruby BlackBag has a similar set of network tools:
+
+* 'blit'  : Uses a simple homegrown OOB IPC mechanism (local socket) to 
+  communicate with 'blit-capable' tools like telson and plugsrv and send
+  data to network endpoints through them. Use 'blit' to send raw 
+  messages to servers or clients then watch how they respond (see below).
+
+* 'telson' : Similar to 'bkb telson'. Opens a TCP or UDP client connection 
+  which is little more than a receiver for 'blit' messages. Use this to
+  pretend to be a client and send raw messages to some service while observing 
+  raw replies.
+
+* 'plugsrv' : Similar to 'bkb replug'. Sits as a reverse TCP proxy between 
+  one or more clients and a server. Accepts 'blit' messages which can be 
+  directed at client or server ends of a conversation. The original 'replug'
+  didn't do this, which makes plugsrv kindof neat.
+
+
+=== Monkey Patches
+
+Much of rbkb is implemented as a bunch of monkeypatches to Array, String, 
+Numeric and other base classes. If this suits your fancy (some people despise
+monkeypatches, this is not their fancy) then you can 'require "rbkb"' from 
+your irb sessions and own scripts. See 'lib_usage.rdoc' for more info.
+
+
+== REQUIREMENTS:
+
+* eventmachine >= 0.12.8
+
+
+== INSTALL:
+
+=== Gem Installation
+
+rbkb is available as a gem from github:
+
+    gem sources -a http://gems.github.com #(you only have to do this once)
+    gem install emonti-rbkb
+
+
+==== Gem Install Note
+
+Installing the gem as root may be risky depending on your rubygems 
+configuration so I don't really recommend using 'sudo gem install'. 
+Worst case scenario I know of is I blew away my OSX-shipped '/usr/bin/crc32' 
+this way. It was written in perl, so I considered this providence and didn't 
+look back. But you may feel differently about 'rubygems' clobbering a file in 
+/usr/bin.
+
+When installing as a regular user, however, rubygems may stick rbkb's 
+executable bin/* files somewhere unexpected. To find out where these are and 
+either add them to your PATH or copy/symlink them somewhere else like 
+/usr/local/bin/ do this:
+
+    gem contents emonti-rbkb
+
+
+=== Manual installation:
+
+  git clone git://github.com/emonti/rbkb.git
+  cd rbkb
+  rake gem:install
+
+
+or ... you can also install manually without rubygems.
+
+You can access the rbkb project at github. You'll want git installed:
+
+  cp -r rbkb/lib/* /usr/lib/ruby/1.8/site_ruby/1.8 # or another ruby libdir
+  cp bin/* ~/bin      # or wherever else in your PATH
+
+Run this to generate docs with rdoc the same way the gem would have:
+
+  rake doc:rdoc
+
+== LICENSE:
+
+(The MIT License) 
+
+Copyright (c) 2009 Eric Monti, Matasano Security
+
+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/Rakefile

@@ -0,0 +1,47 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  begin
+    load 'tasks/setup.rb'
+  rescue LoadError
+    raise RuntimeError, '### please install the "bones" gem ###'
+  end
+end
+
+ensure_in_path 'lib'
+require 'rbkb'
+
+task :default => 'test:run'
+
+PROJ.name = 'rbkb'
+PROJ.authors = 'Eric Monti'
+PROJ.email = 'emonti@matasano.com'
+PROJ.description = 'Rbkb is a collection of ruby-based pen-testing and reversing tools. Inspired by Matasano Blackbag.'
+PROJ.url = 'http://emonti.github.com/rbkb'
+PROJ.version = Rbkb::VERSION
+PROJ.rubyforge.name = 'rbkb'
+PROJ.readme_file = 'README.rdoc'
+
+PROJ.spec.opts << '--color'
+
+PROJ.rdoc.opts << '--line-numbers'
+
+#PROJ.rdoc.opts << '--diagram'
+PROJ.notes.tags << "X"+"XX" # muhah! so we don't note our-self
+
+# exclude rcov.rb and external libs from rcov report
+PROJ.rcov.opts += [
+  "--exclude",  "rcov.rb", 
+  "--exclude", "eventmachine",
+  "--exclude", "pcap_misc.rb",
+  "--exclude", "pcaplet.rb"
+]
+
+depend_on 'eventmachine', '>= 0.12.8'
+
+# EOF

data/bin/b64

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "rbkb/cli/b64"
+
+Rbkb::Cli::B64.run()

data/bin/bgrep

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "rbkb/cli/bgrep"
+
+Rbkb::Cli::Bgrep.run()

data/bin/blit

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "rbkb/cli/blit"
+
+Rbkb::Cli::Blit.run()

data/bin/c

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "rbkb/cli/chars"
+
+Rbkb::Cli::Chars.run()

data/bin/crc32

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "rbkb/cli/crc32"
+
+Rbkb::Cli::Crc32.run()

data/bin/d64

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "rbkb/cli/d64"
+
+Rbkb::Cli::D64.run()

data/bin/dedump

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "rbkb/cli/dedump"
+
+Rbkb::Cli::Dedump.run()

data/bin/feed

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "rbkb/cli/feed"
+
+Rbkb::Cli::Feed.run()

data/bin/hexify

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "rbkb/cli/hexify"
+
+Rbkb::Cli::Hexify.run()

data/bin/len

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "rbkb/cli/len"
+
+Rbkb::Cli::Len.run()

data/bin/plugsrv

@@ -0,0 +1,271 @@
+#!/usr/bin/env ruby
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
+# A blit-able reverse TCP proxy. Displays traffic hexdumps. Currently uses
+# the default blit port for its blit receiver.
+#
+# XXX TODO - refactor me!
+
+begin
+  require 'rubygems'
+rescue LoadError
+end
+require 'eventmachine'
+require 'socket'
+require 'optparse'
+require 'rbkb/plug'
+
+class BlitPlug
+  module UI
+    def log( *msg )
+      unless PLUG_OPTS[:quiet]
+        PLUG_OPTS[:out].puts msg
+      end
+    end
+    module_function :log
+  end
+
+  class Controller
+    attr_accessor :tgtaddr, :tgtport, :tgtclient, :blit, :peers
+    @@controller = nil
+
+    def initialize(tgtaddr, tgtport, tgtclient)
+      @tgtaddr = tgtaddr
+      @tgtport = tgtport
+      @tgtclient = tgtclient
+
+      @@controller = self
+
+      @peers = Array.new
+
+      ## Just tack on a blit server???
+      @blit = EventMachine::start_server(
+        PLUG_OPTS[:blit_addr], PLUG_OPTS[:blit_port], Plug::Blit, :TCP, self
+      )
+
+    end
+
+    ##----------------------------------------
+
+    def dispatch_rcv(snder, data)
+      data # for now
+    end
+
+    ##----------------------------------------
+
+    def dispatch_close(snder)
+      nil # for now
+    end
+
+    ##----------------------------------------
+
+    def self.proxy(cli)
+      unless (ctrl = @@controller)
+        raise "No controller exists for this connection: #{cli.sock_peername}"
+      end
+
+      tgtaddr = ctrl.tgtaddr
+      tgtport = ctrl.tgtport
+      tgtclient = ctrl.tgtclient
+
+      srv = EventMachine::connect(tgtaddr, tgtport, tgtclient)
+      srv.plug_peers.push cli
+      cli.plug_peers.push srv
+
+      ctrl.peers.push srv
+      ctrl.peers.push cli ### I suppose this is probably useful too..
+
+      srv.controller = cli.controller = ctrl
+    end
+  end # class BlitPlug::Controller
+
+
+  module BaseTCP
+    include UI
+
+    attr_accessor :plug_peers, :controller, :kind
+    attr_reader :sock_peer, :sock_peername
+
+    def post_init
+      @plug_peers = Array.new
+      @kind = :conn  # default
+    end
+ 
+    def name
+      @name
+    end
+
+    def say(data, sender)
+      log "%#{sender.kind.to_s.upcase}-SAYS", data.hexdump(:out => StringIO.new), "%"
+      send_data data 
+    end
+
+    def receive_data data
+      log "%#{kind.to_s.upcase}-#{sock_peername}-SAYS", data.hexdump, "%"
+      if @controller and (data = @controller.dispatch_rcv(self, data)).nil?
+        return
+      end
+      @plug_peers.each {|p| p.send_data data}
+    end
+
+
+    def notify_connection
+      @name = "#{kind.to_s.upcase}-#{sock_peername}"
+      log "%#{@name}-CONNECTED"
+    end
+
+
+    def unbind
+      @name = "#{kind.to_s.upcase}-#{sock_peername}"
+      log "%#{@name}-CLOSED"
+
+      cret = (@controller and @controller.dispatch_close(self))
+
+      @plug_peers.each do |p| 
+        p.plug_peers.delete(self)
+        p.close_connection unless cret
+      end
+    end
+  end
+
+
+  module TCPListener
+    include BlitPlug::BaseTCP
+    attr_accessor :tgtaddr, :tgtport
+
+    def post_init
+      super
+      @kind = :client
+      @sock_peer = Socket.unpack_sockaddr_in(get_peername).reverse
+      @sock_peername = @sock_peer.join(':')
+
+      @controller = BlitPlug::Controller.proxy(self)
+
+      start_tls if PLUG_OPTS[:svr_tls]
+
+      notify_connection
+    end
+
+  end # module TCPListener
+
+
+  module TCPClient
+    include BlitPlug::BaseTCP
+    attr_accessor :connected
+
+    def post_init
+      super
+      @kind = :server
+    end
+
+    def connection_completed
+      @sock_peer = Socket.unpack_sockaddr_in(get_peername).reverse
+      @sock_peername = @sock_peer.join(':')
+      notify_connection
+      start_tls if PLUG_OPTS[:tgt_tls]
+    end
+
+  end # module TCPClient
+
+end # module BlitPlug
+
+PLUG_OPTS={ 
+  :quiet => false, 
+  :out => STDOUT,
+  :blit_addr => Plug::Blit::DEFAULT_IPADDR, 
+  :blit_port => Plug::Blit::DEFAULT_PORT,
+}
+
+def bail(*msg)
+  STDERR.puts msg
+  exit 1
+end
+
+
+
+#############################################################################
+### MAIN
+#############################################################################
+#
+# Get option arguments
+opts = OptionParser.new do |opts|
+  opts.banner = "Usage: #{File.basename $0} [options] target:tport[@[laddr:]lport]\n",
+                "  <target:tport>  = the address of the target service\n",
+                "  <@laddr:lport> = optional address and port to listen on\n"
+
+  opts.separator ""
+  opts.separator "Options:"
+
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts
+    exit 1
+  end
+
+  opts.on("-o", "--output FILE", "send output to a file") do |o|
+    PLUG_OPTS[:out] = File.open(o, "w") rescue (bail $!)
+  end
+
+  opts.on("-l", "--listen ADDR:PORT", 
+          "optional listener address:port", 
+          "(default: 0.0.0.0:<tport>)"
+         ) do |addr|
+
+    unless m = /^([\w\.]+)?(?::(\d+))?$/.match(addr)
+      STDERR.puts "invalid listener address"
+      exit 1
+    end
+    PLUG_OPTS[:svraddr] = m[1]
+    PLUG_OPTS[:svrport] = (m[2])? m[2].to_i : nil
+  end
+
+  opts.on("-q", "--[no-]quiet", "Suppress/Enable conversation dumps.") do |q|
+    PLUG_OPTS[:quiet] = q
+  end
+
+  opts.on("-b", "--blitsrv ADDR:PORT", 
+          "specify blit listener [address:]port", 
+          "(default: #{PLUG_OPTS[:blit_addr]}:#{PLUG_OPTS[:blit_port]})"
+         ) do |addr|
+
+    unless m = /^(?:([\w\.]+):)?(\d+)$/.match(addr)
+      STDERR.puts "invalid blit listener argument"
+      exit 1
+    end
+    PLUG_OPTS[:blit_addr] = m[1] if m[1]
+    PLUG_OPTS[:blit_port] = m[2].to_i
+  end
+
+  opts.on("--[no-]target-tls", "enable/disable TLS to target") {|t| PLUG_OPTS[:tgt_tls] = t }
+  opts.on("--[no-]server-tls", "enable/disable TLS to clients") {|t| PLUG_OPTS[:svr_tls] = t }
+
+end
+
+opts.parse!(ARGV) rescue (STDERR.puts $!; exit 1)
+
+
+# Get target/listen argument
+rx = /^([\w\.]+):(\d+)(?:@(?:([\w\.]+):)?(\d+))?$/
+unless (m = rx.match(ARGV.shift)) and ARGV.shift.nil?
+  $stderr.puts opts.banner
+  exit 1
+end
+
+PLUG_OPTS[:tgtaddr] = m[1]
+PLUG_OPTS[:tgtport] = m[2].to_i
+PLUG_OPTS[:svraddr] ||= (m[3] || "0.0.0.0")
+PLUG_OPTS[:svrport] ||= (m[4] || PLUG_OPTS[:tgtport]).to_i
+
+
+EventMachine::run {
+  # Instantiate controller
+  ctrl = BlitPlug::Controller.new(PLUG_OPTS[:tgtaddr], PLUG_OPTS[:tgtport], BlitPlug::TCPClient)
+
+  # Start event loop
+  BlitPlug::UI.log "%Starting TCP PlugServer #{PLUG_OPTS[:svraddr]}:#{PLUG_OPTS[:svrport]} -> #{PLUG_OPTS[:tgtaddr]}:#{PLUG_OPTS[:tgtport]}"
+
+  
+  EventMachine::start_server(PLUG_OPTS[:svraddr], PLUG_OPTS[:svrport], BlitPlug::TCPListener)
+}
+
+