emonti-rbkb 0.6.2 → 0.6.2.1

data/README.rdoc

@@ -40,145 +40,36 @@ When I get some spare time, I'll try and do up some examples of using all
 the tools.
 
 
-=== Monkey Patches
-
-Most 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. This will let you do things like the 
-following (just some samples, see rdoc for more).
-
-My dirty secret: I use IRB for like... everything
-
-Do stuff with strings:
-
-  ## sexify with hexify
-  foo = "helu foo"            #=> "helu foo"
-  foo.hexify                  #=> "68656c7520666f6f"
-
-  ## a little easier to read
-  foo.hexify(:delim => ' ')   #=> "68 65 6c 75 20 66 6f 6f"
-
-  # and back
-  _.unhexify                  #=> "helu foo"
-
-  ## break out your hexdump -C styles
-  foodump = "helu foo".hexdump(:out => StringIO.new)
-  #=> "00000000  68 65 6c 75 20 66 6f 6f  |helu foo|\n00000008\n"
-  puts foodump
-  # 00000000  68 65 6c 75 20 66 6f 6f  |helu foo|
-  # 00000008
-  # => nil
-  foo.hexdump(:out => $stdout)
-  # 00000000  68 65 6c 75 20 66 6f 6f  |helu foo|
-  # 00000008
-  # => nil
-
-  ## reverse a hexdump
-  foodump.dehexdump             #=> "helu foo"
-
-  ## 'strings' like /usr/bin/strings
-  dat = File.read("/bin/ls")
-  pp dat.strings
-  # [[4132, 4143, :ascii, "__PAGEZERO\000"],
-  #  [4188, 4195, :ascii, "__TEXT\000"],
-  # ...
-  #  [72427, 72470, :ascii, "*Apple Code Signing Certification Authority"],
-  #  [72645, 72652, :ascii, "X[N~EQ "]]
-
-
-  ## look for stuff in binaries
-  dat.bgrep("__PAGEZERO")         #=> [[4132, 4142, "__PAGEZERO"], [40996, 41006, "__PAGEZERO"]]
-  dat.bgrep(0xCAFEBABE.to_bytes)  #=> [[0, 4, "\312\376\272\276"]]
-
-
-Do stuff with numbers:
-
-  ## Do you have an irrational distaste for pack/unpack? I do.
-  0xff.to_bytes                     #=> "\000\000\000\377"
-  be = 0xff.to_bytes(:big)          #=> "\000\000\000\377"
-  le = 0xff.to_bytes(:little)       #=> "\377\000\000\000"
-  le16 = 0xff.to_bytes(:little,2)   #=> "\377\000"
+=== Plug
 
-  ## Strings can go the other way too
-  [be, le, le16].map {|n| n.dat_to_num(:big) } # default
-  #=> [255, 4278190080, 65280]
-  [be, le, le16].map {|n| n.dat_to_num(:little) }
-  #=> [4278190080, 255, 255]
+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'.
 
-  ## Calculate padding for a given alignment
-  10.pad(16)     #=> 6
-  16.pad(16)     #=> 0
-  30.pad(16)     #=> 2
-  32.pad(16)     #=> 0
+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).
 
-Web 2."oh no you di'int!":
+* '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.
 
-  xss="<script>alert('helu ' + document.cookie)</script"
+* '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.
 
-  # URL percent-encode stuff
-  xss.urlenc 
-  #=> "%3cscript%3ealert%28%27helu%3a%20%27%20%2b%20document.cookie%29%3c%2fscript%3e"
 
-  _.b64
-  #=> "JTNjc2NyaXB0JTNlYWxlcnQlMjglMjdoZWx1JTNhJTIwJTI3JTIwJTJiJTIwZG9jdW1lbnQuY29va2llJTI5JTNjJTJmc2NyaXB0JTNl"
-
-  ## And back
-  _.d64
-  #=> "%3cscript%3ealert%28%27helu%3a%20%27%20%2b%20document.cookie%29%3c%2fscript%3e"
-
-  _.urldec
-  #=> "<script>alert('helu: ' + document.cookie)</script>"
-
-
-Miscellaneous stuff:
-
-  # rediculous laziness!
-  0x41.printable?         #=> true
-  0x01.printable?         #=> false
-
-  # Make random gobbledygook and insults
-  "helu foo".randomize    #=> "ouofleh "
-  "helu foo".randomize    #=> "foul hoe"
-
-
-Pretend (badly) to be smart:
-
-  # Cletus say's he's "sneaky"
-  cletus = "my secrets are safe".xor("sneaky")
-  #=> "\036\027E\022\016\032\001\v\021\022K\030\001\vE\022\n\037\026"
-
-  # Only not really so sneaky
-  cletus.xor "my secrets"     #=> "sneakysnea&a!x qxzb"
-  cletus.xor "my secrets are" #=> "sneakysneakysn(k*ls"
-  cletus.xor "sneaky"         #=> "my secrets are safe"
-
-  # Now make Cletus feel worse. With... MATH!
-  # (ala entropy scores)
-  "A".entropy                               #=> 0.0
-  "AB".entropy                              #=> 1.0
-  "BC".entropy                              #=> 1.0
-  (0..255).map {|x| x.chr}.join.entropy     #=> 8.0
-
-  # "You see, Cletus, you might have done this..."
-  sdat = "my secrets are very secret "*60
-  require 'openssl'
-  c = OpenSSL::Cipher::Cipher.new("aes-256-cbc")
-  c.encrypt
-  c.key = Digest::SHA1.hexdigest("sneaky")
-  c.iv = c.random_iv
+=== Monkey Patches
 
-  # "So, Cletus, when you say 'sneaky'... this is exactly how 'sneaky' you are"
-  c.update(sdat).entropy
-  #=> 7.64800383393901
-  sdat.xor("sneaky").entropy
-  #=> 3.77687372599433
-  sdat.entropy
-  #=> 3.07487577558377
-  
-I do recommend the rdoc if you're interested in more of these little helpers. 
-I'll to keep the comments useful and up to date.
+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_fun.rdoc' for more info.
 
 
 == REQUIREMENTS:
@@ -212,6 +103,7 @@ either add them to your PATH or copy/symlink them somewhere else like
 
     gem contents emonti-rbkb
 
+
 === Manual installation:
 
 ... or ... you can also install manually without rubygems.

data/bin/plugsrv

@@ -1,18 +1,22 @@
 #!/usr/bin/env ruby
-# TODO refactor into rbkb/plug and add blit support
+# 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'
-
-def bail(*msg)
-  STDERR.puts msg
-  exit 1
-end
+require 'rbkb/plug'
 
-class PlugSrv
+class BlitPlug
   module UI
     def log( *msg )
       unless PLUG_OPTS[:quiet]
@@ -23,16 +27,24 @@ class PlugSrv
   end
 
   class Controller
-    attr_accessor :tgtaddr, :tgtport, :tgtclient
-    @@controllers=nil
+    attr_accessor :tgtaddr, :tgtport, :tgtclient, :blit, :peers
+    @@controller = nil
 
     def initialize(tgtaddr, tgtport, tgtclient)
-
       @tgtaddr = tgtaddr
       @tgtport = tgtport
       @tgtclient = tgtclient
 
-      @@controllers = self
+      @@controller = self
+
+      @peers = Array.new
+
+      ## Just tack on a blit server???
+      @blit = EventMachine::start_server(
+        Plug::Blit::DEFAULT_IPADDR, Plug::Blit::DEFAULT_PORT, Plug::Blit,
+        :TCP, self
+      )
+
     end
 
     ##----------------------------------------
@@ -50,7 +62,7 @@ class PlugSrv
     ##----------------------------------------
 
     def self.proxy(cli)
-      unless (ctrl = @@controllers)
+      unless (ctrl = @@controller)
         raise "No controller exists for this connection: #{cli.sock_peername}"
       end
 
@@ -62,9 +74,12 @@ class PlugSrv
       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 PlugSrv::Controller
+  end # class BlitPlug::Controller
 
 
   module BaseTCP
@@ -78,6 +93,14 @@ class PlugSrv
       @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, "%"
@@ -89,12 +112,14 @@ class PlugSrv
 
 
     def notify_connection
-      log "%#{kind.to_s.upcase}-#{@sock_peername}-CONNECTED"
+      @name = "#{kind.to_s.upcase}-#{sock_peername}"
+      log "%#{@name}-CONNECTED"
     end
 
 
     def unbind
-      log "%#{kind.to_s.upcase}-#{@sock_peername}-CLOSED"
+      @name = "#{kind.to_s.upcase}-#{sock_peername}"
+      log "%#{@name}-CLOSED"
 
       cret = (@controller and @controller.dispatch_close(self))
 
@@ -107,7 +132,7 @@ class PlugSrv
 
 
   module TCPListener
-    include PlugSrv::BaseTCP
+    include BlitPlug::BaseTCP
     attr_accessor :tgtaddr, :tgtport
 
     def post_init
@@ -116,7 +141,7 @@ class PlugSrv
       @sock_peer = Socket.unpack_sockaddr_in(get_peername).reverse
       @sock_peername = @sock_peer.join(':')
 
-      @controller = PlugSrv::Controller.proxy(self)
+      @controller = BlitPlug::Controller.proxy(self)
 
       notify_connection
     end
@@ -125,7 +150,7 @@ class PlugSrv
 
 
   module TCPClient
-    include PlugSrv::BaseTCP
+    include BlitPlug::BaseTCP
     attr_accessor :connected
 
     def post_init
@@ -141,16 +166,22 @@ class PlugSrv
 
   end # module TCPClient
 
-end # module PlugSrv
+end # module BlitPlug
 
 PLUG_OPTS={ :quiet => false, :out => STDOUT }
 
+def bail(*msg)
+  STDERR.puts msg
+  exit 1
+end
+
+
 
 #############################################################################
 ### MAIN
 #############################################################################
 #
-# Get arguments
+# Get option arguments
 opts = OptionParser.new do |opts|
   opts.banner = "Usage: #{$0} [options] target:tport[@[laddr:]lport]\n",
                 "  <target:tport>  = the address of the target service\n",
@@ -203,13 +234,15 @@ PLUG_OPTS[:svraddr] ||= (m[3] || "0.0.0.0")
 PLUG_OPTS[:svrport] ||= (m[4] || PLUG_OPTS[:tgtport]).to_i
 
 
-# Start controller
-ctrl = PlugSrv::Controller.new(PLUG_OPTS[:tgtaddr], PLUG_OPTS[:tgtport], PlugSrv::TCPClient)
+EventMachine::run {
+  # Instantiate controller
+  ctrl = BlitPlug::Controller.new(PLUG_OPTS[:tgtaddr], PLUG_OPTS[:tgtport], BlitPlug::TCPClient)
 
-# Start event loop
-PlugSrv::UI.log "%Starting TCP PlugServer #{PLUG_OPTS[:svraddr]}:#{PLUG_OPTS[:svrport]} -> #{PLUG_OPTS[:tgtaddr]}:#{PLUG_OPTS[:tgtport]}"
+  # Start event loop
+  BlitPlug::UI.log "%Starting TCP PlugServer #{PLUG_OPTS[:svraddr]}:#{PLUG_OPTS[:svrport]} -> #{PLUG_OPTS[:tgtaddr]}:#{PLUG_OPTS[:tgtport]}"
 
-EventMachine::run {
-  EventMachine::start_server(PLUG_OPTS[:svraddr], PLUG_OPTS[:svrport], PlugSrv::TCPListener)
+  
+  EventMachine::start_server(PLUG_OPTS[:svraddr], PLUG_OPTS[:svrport], BlitPlug::TCPListener)
 }
 
+

data/{usage.txt → cli_usage.rdoc}

@@ -117,6 +117,23 @@ Takes input from a blob of data and output it with its binary length prepended.
     -l, --length=LEN                 Ignore all else and use LEN
 
 
+=== plugsrv
+
+A blit-able reverse TCP proxy. Displays traffic hexdumps. Currently uses
+the default blit port for its blit receiver.
+
+    Usage: /usr/bin/plugsrv [options] target:tport[@[laddr:]lport]
+      <target:tport>  = the address of the target service
+      <@laddr:lport> = optional address and port to listen on
+
+    Options:
+        -o, --output FILE                send output to a file
+        -l, --listen ADDR:PORT           optional listener address:port
+                                         (default: 0.0.0.0:<tport>)
+        -q, --[no-]quiet                 Suppress/Enable conversation dumps.
+        -h, --help                       Show this message
+
+
 === rex
 
   Lazy shortcut for ruby -e "..."
@@ -157,8 +174,9 @@ eventmachine.
 
 Telson is for doing the following things with minimum fuss: 
 
-* Run as a server or client using UDP or TCP
-* Debugging network protocols
+* Run as a stubbed network client using UDP or TCP
+* Use blit to communicate with the other side.
+* Debug network protocols
 * Observe client/server behaviors using different messages at various phases 
   of a conversation.
 

data/lib/rbkb/cli/b64.rb

@@ -1,5 +1,8 @@
 require 'rbkb/cli'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # b64 converts strings or raw data to base-64 encoding.
 class Rbkb::Cli::B64 < Rbkb::Cli::Executable
   def make_parser

data/lib/rbkb/cli/bgrep.rb

@@ -1,5 +1,8 @@
 require 'rbkb/cli'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # searches for a binary string in input. string can be provided 'hexified'
 class Rbkb::Cli::Bgrep < Rbkb::Cli::Executable
   def initialize(*args)

data/lib/rbkb/cli/blit.rb

@@ -1,6 +1,9 @@
 require 'rbkb/cli'
 require 'rbkb/plug'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # blit is for use with any of the "plug" tools such as telson, feed, blitplug.
 # It is used to send data over a socket via their OOB blit listener.
 class Rbkb::Cli::Blit < Rbkb::Cli::Executable

data/lib/rbkb/cli/chars.rb

@@ -1,5 +1,8 @@
 require 'rbkb/cli'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # Repeats an argument N times
 class Rbkb::Cli::Chars < Rbkb::Cli::Executable
   def make_parser

data/lib/rbkb/cli/crc32.rb

@@ -1,5 +1,8 @@
 require 'rbkb/cli'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # crc32 returns a crc32 checksum in hex from stdin or a file
 class Rbkb::Cli::Crc32 < Rbkb::Cli::Executable
   def initialize(*args)

data/lib/rbkb/cli/d64.rb

@@ -1,5 +1,8 @@
 require 'rbkb/cli'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # d64 converts a base-64 encoded string back to its orginal form.
 class Rbkb::Cli::D64 < Rbkb::Cli::Executable
   def make_parser

data/lib/rbkb/cli/dedump.rb

@@ -1,5 +1,8 @@
 require 'rbkb/cli'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # Reverses a hexdump back to raw data. Designed to work with hexdumps created 
 # by Unix utilities like 'xxd' as well as 'hexdump -C'.
 class Rbkb::Cli::Dedump < Rbkb::Cli::Executable

data/lib/rbkb/cli/hexify.rb

@@ -1,7 +1,8 @@
-#!/usr/bin/env ruby
-
 require 'rbkb/cli'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # The hexify command converts a string or raw data to hex characters. 
 # Input can be supplied via stdin, a string argument, or a file (with -f).
 class Rbkb::Cli::Hexify < Rbkb::Cli::Executable

data/lib/rbkb/cli/len.rb

@@ -1,5 +1,8 @@
 require 'rbkb/cli'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # len prepends a binary length number in front of its input and outputs
 # raw on STDOUT
 class Rbkb::Cli::Len < Rbkb::Cli::Executable

data/lib/rbkb/cli/rstrings.rb

@@ -1,5 +1,8 @@
 require 'rbkb/cli'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # rstrings is Unix "strings" in ruby... with some extra stuff
 class Rbkb::Cli::Rstrings < Rbkb::Cli::Executable
   def initialize(*args)

data/lib/rbkb/cli/slice.rb

@@ -1,5 +1,8 @@
 require 'rbkb/cli'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # Returns a slice from input. This is just a shell interface to a String.slice 
 # operation.
 class Rbkb::Cli::Slice < Rbkb::Cli::Executable

data/lib/rbkb/cli/telson.rb

@@ -2,12 +2,14 @@ require 'rbkb/cli'
 require 'rbkb/plug'
 require 'eventmachine'
 
-
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # This is an implementation of the original blackbag "telson" around 
 # ruby and eventmachine. 
 #
 # Telson can do the following things with minimum fuss: 
-#   - Run as a server or client using UDP or TCP
+#   - Run as a "stubbed" network client using UDP or TCP
 #   - Debugging network protocols
 #   - Observe client/server behaviors using different messages at
 #     various phases of a conversation.

data/lib/rbkb/cli/unhexify.rb

@@ -1,7 +1,8 @@
-#!/usr/bin/env ruby
-
 require 'rbkb/cli'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # unhexify converts a string of hex bytes back to raw data. Input can be 
 # supplied via stdin, a hex-string argument, or a file containing hex (use -f).
 class Rbkb::Cli::Unhexify < Rbkb::Cli::Executable

data/lib/rbkb/cli/urldec.rb

@@ -1,5 +1,8 @@
 require 'rbkb/cli'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # urldec converts a url percent-encoded string back to its raw form.
 # Input can be supplied via stdin, a string argument, or a file (with -f).
 # (url percent-encoding is just fancy hex encoding)

data/lib/rbkb/cli/urlenc.rb

@@ -1,5 +1,8 @@
 require 'rbkb/cli'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # urlenc converts a string or raw data to a url percent-encoded string 
 # Input can be supplied via stdin, a string argument, or a file (with -f).
 # (url percent-encoding is just fancy hex encoding)

data/lib/rbkb/cli/xor.rb

@@ -1,6 +1,9 @@
 #!/usr/bin/env ruby
 require 'rbkb/cli'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 # Repeating string xor. Takes input from a string, stdin, or a file (-f).
 class Rbkb::Cli::Xor < Rbkb::Cli::Executable
   def make_parser()

data/lib/rbkb/cli.rb

@@ -1,6 +1,9 @@
 require 'rbkb'
 require 'optparse'
 
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 module Rbkb::Cli
   # Rbkb::Cli::Executable is an abstract class for creating command line
   # executables using the Ruby Black Bag framework.
@@ -11,6 +14,7 @@ module Rbkb::Cli
     end
 
     attr_accessor :stdout, :stderr, :stdin, :argv, :opts, :oparse
+    attr_reader   :exit_status
 
     # Instantiates a new Executable object.
     #
@@ -39,6 +43,7 @@ module Rbkb::Cli
 
     # Wrapper for Kernel.exit() so we can unit test cli tools
     def exit(ret)
+      @exit_status = ret
       if defined? Rbkb::Cli::TESTING
         raise("Exited with return code: #{ret}") if ret != 0
       else

data/lib/rbkb/extends.rb

@@ -1,4 +1,6 @@
-# Author Eric Monti (emonti at matasano)
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 require "stringio"
 require 'zlib'
 require 'open3'

data/lib/rbkb/plug/blit.rb

@@ -1,4 +1,6 @@
-
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 module Plug
   module Blit
     include Base

data/lib/rbkb/plug/peer.rb

@@ -1,3 +1,7 @@
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
+
 require 'socket'
 
 module Plug

data/lib/rbkb/plug/plug.rb

@@ -1,3 +1,6 @@
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 
 require "rbkb/plug/peer.rb"
 require 'stringio'

data/lib/rbkb/plug/proxy.rb

@@ -1,3 +1,6 @@
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 
 module Plug
   module Proxy

data/lib/rbkb/plug.rb

@@ -1,3 +1,6 @@
+# Copyright 2009 emonti at matasano.com 
+# See README.rdoc for license information
+#
 
 require "rbkb.rb"
 

data/lib_usage.rdoc

@@ -0,0 +1,176 @@
+
+=== Using the rbkb library's 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. 
+
+The monkey-patches were designed to let you approximate use of the rbkb shell 
+commands from IRB or ruby scripts.
+
+(My dirty secret: I use IRB for like... everything!)
+
+Using the rbkb library in ruby will let you do things like the following (just 
+some samples, see rdoc for more info).
+
+
+Do stuff with strings:
+
+  ## sexify with hexify
+  foo = "helu foo"            #=> "helu foo"
+  foo.hexify                  #=> "68656c7520666f6f"
+
+  ## a little easier to read
+  foo.hexify(:delim => ' ')   #=> "68 65 6c 75 20 66 6f 6f"
+
+  # and back
+  _.unhexify                  #=> "helu foo"
+
+  ## break out your hexdump -C styles
+  foodump = "helu foo".hexdump(:out => StringIO.new)
+  #=> "00000000  68 65 6c 75 20 66 6f 6f  |helu foo|\n00000008\n"
+  puts foodump
+  # 00000000  68 65 6c 75 20 66 6f 6f  |helu foo|
+  # 00000008
+  # => nil
+  foo.hexdump(:out => $stdout)
+  # 00000000  68 65 6c 75 20 66 6f 6f  |helu foo|
+  # 00000008
+  # => nil
+
+  ## reverse a hexdump
+  foodump.dehexdump             #=> "helu foo"
+
+  ## 'strings' like /usr/bin/strings
+  dat = File.read("/bin/ls")
+  pp dat.strings
+  # [[4132, 4143, :ascii, "__PAGEZERO\000"],
+  #  [4188, 4195, :ascii, "__TEXT\000"],
+  # ...
+  #  [72427, 72470, :ascii, "*Apple Code Signing Certification Authority"],
+  #  [72645, 72652, :ascii, "X[N~EQ "]]
+
+  ## look for stuff in binaries
+  dat.bgrep("__PAGEZERO")         #=> [[4132, 4142, "__PAGEZERO"], [40996, 41006, "__PAGEZERO"]]
+  dat.bgrep(0xCAFEBABE.to_bytes)  #=> [[0, 4, "\312\376\272\276"]]
+
+
+Do stuff with numbers:
+
+  ## Do you have an irrational distaste for pack/unpack? I do.
+  0xff.to_bytes                     #=> "\000\000\000\377"
+  be = 0xff.to_bytes(:big)          #=> "\000\000\000\377"
+  le = 0xff.to_bytes(:little)       #=> "\377\000\000\000"
+  le16 = 0xff.to_bytes(:little,2)   #=> "\377\000"
+
+  ## Strings can go the other way too
+  [be, le, le16].map {|n| n.dat_to_num(:big) } # default
+  #=> [255, 4278190080, 65280]
+  [be, le, le16].map {|n| n.dat_to_num(:little) }
+  #=> [4278190080, 255, 255]
+
+  ## Calculate padding for a given alignment
+  10.pad(16)     #=> 6
+  16.pad(16)     #=> 0
+  30.pad(16)     #=> 2
+  32.pad(16)     #=> 0
+
+
+Interact with 'telson' and 'plugsrv' directly from IRB:
+
+  ## In a separate window from your irb session do something like:
+  # 
+  #  $ telson rubyforge.com:80 -r
+  #  ** TELSON-192.168.11.2:58118(TCP) Started
+  #  ** BLITSRV-127.0.0.1:25195(TCP) Started
+  #  ** TELSON-192.168.11.2:58118(TCP) CONNECTED TO PEER-205.234.109.19:80(TCP)
+
+  ## You can blit any string from within IRB!
+
+  ## A minor setup step is required... (I put this in my .irbrc)
+  Plug::Blit.blit_init              #=> nil
+
+  "GET / HTTP/1.0\r\n\r\n".blit                 #=> 28 
+  ## Watch the basic HTTP request get made and responded to in the 
+  ## other window.
+
+  ("GET /"+ "A"*30 +" HTTP/1.0\r\n\r\n").blit   #=> 58 
+  ## Watch the bogus HTTP request get made and responded to in the 
+  ## other window.
+
+
+Some simple web encoding stuff:
+
+  xss="<script>alert('helu ' + document.cookie)</script"
+
+  # URL percent-encode stuff
+  xss.urlenc 
+  #=> "%3cscript%3ealert%28%27helu%3a%20%27%20%2b%20document.cookie%29%3c%2fscript%3e"
+
+  # Base64 encode stuff
+  _.b64
+  #=> "JTNjc2NyaXB0JTNlYWxlcnQlMjglMjdoZWx1JTNhJTIwJTI3JTIwJTJiJTIwZG9jdW1lbnQuY29va2llJTI5JTNjJTJmc2NyaXB0JTNl"
+
+  ## And back
+  _.d64
+  #=> "%3cscript%3ealert%28%27helu%3a%20%27%20%2b%20document.cookie%29%3c%2fscript%3e"
+
+  _.urldec
+  #=> "<script>alert('helu: ' + document.cookie)</script>"
+
+
+Miscellaneous stuff:
+
+  # rediculous laziness!
+  0x41.printable?         #=> true
+  0x01.printable?         #=> false
+
+  # Make random gobbledygook and insults
+  "helu foo".randomize    #=> "ouofleh "
+  "helu foo".randomize    #=> "foul hoe"
+
+
+Pretend (badly) to be smart:
+
+  # Cletus say's he's "sneaky"
+  cletus = "my secrets are safe".xor("sneaky")
+  #=> "\036\027E\022\016\032\001\v\021\022K\030\001\vE\022\n\037\026"
+
+  # Only not really so sneaky
+  cletus.xor "my secrets"     #=> "sneakysnea&a!x qxzb"
+  cletus.xor "my secrets are" #=> "sneakysneakysn(k*ls"
+  cletus.xor "sneaky"         #=> "my secrets are safe"
+
+  # Now make Cletus feel worse. With... MATH!
+  # (ala entropy scores)
+  "A".entropy                               #=> 0.0
+  "AB".entropy                              #=> 1.0
+  "BC".entropy                              #=> 1.0
+  (0..255).map {|x| x.chr}.join.entropy     #=> 8.0
+
+  # "You see, Cletus, you might have done this..."
+  sdat = "my secrets are very secret "*60
+  require 'openssl'
+  c = OpenSSL::Cipher::Cipher.new("aes-256-cbc")
+  c.encrypt
+  c.key = Digest::SHA1.hexdigest("sneaky")
+  c.iv = c.random_iv
+
+  # "So, Cletus, when you say 'sneaky'... this is exactly how 'sneaky' you are"
+  c.update(sdat).entropy
+  #=> 7.64800383393901
+  sdat.xor("sneaky").entropy
+  #=> 3.77687372599433
+  sdat.entropy
+  #=> 3.07487577558377
+  
+
+
+I recommend reading some of the rdoc if you're interested in more of these 
+little helpers.  Time permitting, I'll try to keep the docs useful and up 
+to date. 
+
+Comments are welcome.
+
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: emonti-rbkb
 version: !ruby/object:Gem::Version 
-  version: 0.6.2
+  version: 0.6.2.1
 platform: ruby
 authors: 
 - Eric Monti
@@ -49,7 +49,8 @@ extra_rdoc_files: []
 
 files: 
 - README.rdoc
-- usage.txt
+- cli_usage.rdoc
+- lib_usage.rdoc
 - bin/b64
 - bin/bgrep
 - bin/blit
@@ -102,7 +103,8 @@ rdoc_options:
 - README.rdoc
 - --line-numbers
 - README.rdoc
-- usage.txt
+- cli_usage.rdoc
+- lib_usage.rdoc
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement