emonti-rbkb 0.6.1.3 → 0.6.2

data/README.rdoc

@@ -1,74 +1,217 @@
+= rbkb
 
-= Ruby BlackBag (rbkb)
+* http://www.github.com/emonti/rbkb
+
+== DESCRIPTION:
+
+Ruby BlackBag (rbkb)
 
 A miscellaneous collection of command-line tools and ruby library helpers 
 related to pen-testing and reversing. 
 
-== Rationale
+=== 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).
+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 based on simplifying some repetetive task or desire for a new tool.
-
+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 (or ever). Similarly some of
+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 usage.txt for a bit of extra info on the various tools. 
+See usage.txt 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.
 
 
-== Installation
+=== 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"
+
+  ## 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
+
+
+Web 2."oh no you di'int!":
 
-==== Pre-Requirements Note
+  xss="<script>alert('helu ' + document.cookie)</script"
 
-For the plug based network stuff, you'll need EventMachine >= 0.12.2
-Installing the rbkb gem usually takes care of this automatically, but
-if you're doing a manual installation, run:
+  # URL percent-encode stuff
+  xss.urlenc 
+  #=> "%3cscript%3ealert%28%27helu%3a%20%27%20%2b%20document.cookie%29%3c%2fscript%3e"
 
-  gem install eventmachine
+  _.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 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.
+
+
+== REQUIREMENTS:
+
+* eventmachine >= 0.12.0
+
+
+== INSTALL:
 
 === Gem Installation
 
-RBkB is available as a gem from github:
+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
 
 
-==== Install Note
+==== Gem Install Note
 
-Installing 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 OS X 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' arbitrarily clobbering your files.
+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:
+either add them to your PATH or copy/symlink them somewhere else like 
+/usr/local/bin/ do this:
 
     gem contents emonti-rbkb
 
-
 === Manual installation:
 
 ... or ... you can also install manually without rubygems.
@@ -84,4 +227,28 @@ Run this to generate docs with rdoc the same way the gem would have:
 
   rdoc --main README.rdoc README.rdoc usage.txt lib
 
+== 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/bin/b64

@@ -1,57 +1,5 @@
 #!/usr/bin/env ruby
-# Author Eric Monti emonti at matasano
-#
-# b64 converts strings or raw data to base-64 encoding.
-#
-# Usage: b64 -h
-#
-require 'rbkb'
-require 'rbkb/command_line'
-require 'base64'
-
-include RBkB::CommandLine
-
-#-------------------------------------------------------------------------------
-# Init options and arg parsing
-OPTS = {}
-arg = bkb_stdargs(nil, OPTS)
-arg = bkb_inputargs(arg, OPTS)
-
-arg.banner += " <data | blank for stdin>"
-
-#------------------------------------------------------------------------------
-# Add local options
-arg.separator ""
-arg.separator "  Output options:"
-
-arg.on("-l", "--length LEN", Numeric, 
-  "Encode in lines of LEN characters") do |l|
-    (OPTS[:len] = l) > 15 or raise "length must be at least 16"
-end
-
-#------------------------------------------------------------------------------
-# Parse arguments
-arg.parse!(ARGV) rescue bail "Error: #{$!}\n#{arg}"
-
-# default string arg
-if OPTS[:indat].nil? and a=ARGV.shift
-	OPTS[:indat] = a.dup 
-end
-
-# catchall
-if ARGV.length != 0
-    bail "Error: bad arguments - #{ARGV.join(' ')}\n-h|--help for more info."
-end
-
-OPTS[:indat] ||= STDIN.read()
-
-#------------------------------------------------------------------------------
-# Do Stuff
-
-if OPTS[:len]
-    Base64.b64encode(OPTS[:indat], OPTS[:len])
-else
-    puts OPTS[:indat].b64
-end
 
+require "rbkb/cli/b64"
 
+Rbkb::Cli::B64.run()

data/bin/bgrep

@@ -1,91 +1,5 @@
 #!/usr/bin/env ruby
-# searches for a binary string in input
-# string is provided 'hexified'
-#
-# usage: bgrep 'deadbeef' file
-#
-# use -h for more info
 
-require 'rbkb'
-require 'rbkb/command_line'
-
-include RBkB::CommandLine
-
-#-------------------------------------------------------------------------------
-# Init options and arg parsing
-OPTS = {
-  :start_off => 0, 
-  :end_off => -1, 
-  :align => nil
-}
-
-arg = bkb_stdargs(nil, OPTS)
-
-arg.banner += " <subject> <file | blank for stdin>"
-
-arg.on("-x", "--[no-]hex", "Specify subject as hex (default: false)") do |x|
-  OPTS[:hex] = x
-end
-
-arg.on("-r", "--[no-]regex", "Specify subject as regex (default: false)") do |r|
-  OPTS[:rx] = r
-end
-
-arg.on("-a", "--align=BYTES", Numeric, 
-       "Only match on alignment boundary") do |a|
-  OPTS[:align] = a
-end
-
-arg.on("-n", "--[no-]filename", "Suppress prefixing of filenames.") do |n|
-  OPTS[:suppress_fname] = n
-end
-
-
-#------------------------------------------------------------------------------
-# Parse arguments
-begin
-  arg.parse!
-
-  unless find = ARGV.shift
-    raise "need subject argument"
-  end
-
-  if OPTS[:hex] and OPTS[:rx]
-    raise "-r and -x are mutually exclusive"
-  end
-
-  if OPTS[:hex]
-    raise "you specified -x for hex and the subject isn't" unless find.ishex?
-    find = find.unhexify
-  elsif OPTS[:rx]
-    find = Regexp.new(find, Regexp::MULTILINE)
-  end
-
-  align = OPTS[:align]
-
-  if fname=ARGV.shift
-    dat = File.read(fname)
-    fname = nil unless ARGV[0]  # only print filename for multiple files
-  else
-    fname = nil
-    dat = STDIN.read
-  end
-
-  loop do 
-    dat.bgrep(find, align) do |hit_start, hit_end, match|
-      print "#{fname}:" if fname and not OPTS[:suppress_fname]
-
-      puts("#{(hit_start).to_hex.rjust(8,"0")}:"+
-           "#{(hit_end).to_hex.rjust(8,"0")}:b:"+
-           "#{match.inspect}")
-    end
-
-    break unless fname=ARGV.shift
-    dat = File.read(fname)
-  end
-
-rescue
-  STDERR.puts $!, "  use -h for help"
-  exit 1
-end
+require "rbkb/cli/bgrep"
 
+Rbkb::Cli::Bgrep.run()

data/bin/blit

@@ -1,97 +1,5 @@
 #!/usr/bin/env ruby
-#
-# 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.
-#
-# Usage: blit [options] <data | blank for stdin>
-#     -h, --help                       Show this message
-#     -v, --version                    Show version and exit
-#     -f, --file FILENAME              Input from FILENAME
-#     -t, --trans-protocol=PROTO       Blit transport protocol TCP/UDP
-#     -b, --blitsrv=ADDR:PORT          Where to send blit messages
-#     -i, --peer-index=IDX             Index for remote peer to receive
-#     -l, --list-peers                 Lists the peer array for the target
-#     -k, --kill                       Stops the remote event loop.
-# 
 
-require 'rbkb'
-require 'rbkb/plug'
-require 'rbkb/command_line.rb'
-
-require 'socket'
-
-include RBkB::CommandLine
-
-#------------------------------------------------------------------------------
-# Init options and arg parsing
-
-OPTS = {
-  :b_addr => Plug::Blit::DEFAULT_IPADDR,
-  :b_port => Plug::Blit::DEFAULT_PORT,
-  :bp_proto => :TCP,
-  :b_peeridx => 0,
-}
-
-blit_msg = nil
-
-arg = bkb_stdargs(nil, OPTS)
-arg = bkb_inputargs(arg, OPTS)
-
-arg.banner += " <data | blank for stdin>"
-
-
-#------------------------------------------------------------------------------
-# Add local options here
-
-arg.on("-t", "--trans-protocol=PROTO", "Blit transport protocol TCP/UDP") do |t|
-  OPTS[:b_proto] = t.upcase.to_sym
-end
-
-arg.on("-b", "--blitsrv=ADDR:PORT", "Where to send blit messages") do |b|
-  unless(m=/^(?:([\w\.]+):)?(\d+)$/.match(b))
-    bail "invalid blit address/port"
-  end
-  OPTS[:b_port] = m[2].to_i
-  OPTS[:b_port] = m[1] if m[1]
-end
-
-arg.on("-i", "--peer-index=IDX", Numeric, "Index for remote peer to receive") do |i|
-  OPTS[:b_peeridx] = i
-end
-
-arg.on("-l", "--list-peers", "Lists the peer array for the target") do
-  blit_msg = Plug::Blit.make_list_peers
-end
-
-arg.on("-k", "--kill", "Stops the remote event loop.") do
-  blit_msg = Plug::Blit.make_kill
-end
-
-#------------------------------------------------------------------------------
-# Parse arguments
-arg.parse!(ARGV) rescue bail "Error: #{$!}\nUse -h|--help for more info."
-
-unless blit_msg
-  if OPTS[:indat].nil?
-    OPTS[:indat] = (ARGV.length > 0)?  ARGV.join(" ") : STDIN.read()
-  end
-  blit_msg = Plug::Blit.make_sendmsg(OPTS[:b_peeridx], OPTS[:indat]) 
-end
-
-#------------------------------------------------------------------------------
-# Do stuff
-
-begin
-  Plug::Blit.blit_init(
-    :addr => OPTS[:b_addr],
-    :port => OPTS[:b_port],
-    :protocol => OPTS[:b_proto]
-  )
-
-  Plug::Blit.blit_raw(blit_msg)
-
-rescue
-  bail $!
-  exit 1
-end
+require "rbkb/cli/blit"
 
+Rbkb::Cli::Blit.run()

data/bin/c

@@ -1,14 +1,5 @@
 #!/usr/bin/env ruby
-# Author Eric Monti (emonti at matasano)
 
-require 'rbkb'
-require 'rbkb/command_line'
-
-include RBkB::CommandLine
-
-if ARGV[0] !~ /[1-9][0-9]*/ or ARGV[1].nil? or ARGV.size > 2 
-    bail "Usage: #{$0} 100 A; # print 100 A's'\n"
-end
-
-print ARGV[1] * ARGV[0].to_i
+require "rbkb/cli/chars"
 
+Rbkb::Cli::Chars.run()

data/bin/crc32

@@ -1,60 +1,5 @@
 #!/usr/bin/env ruby
-# (emonti at matasano) Matasano Security LLC
-#
-# crc32.rb : returns a crc32 checksum in hex from stdin or a file
-# 
-# Usage: crc32 [options]
-#     -h, --help                       Show this message
-#     -v, --version                    Show version and exit
-#     -f, --file FILENAME              Input from FILENAME
-#     -r, --range=START[:END]          Start and optional end range
-#     -x, --hexrange=START[:END]       same, but in hex
 
-require 'rbkb'
-require 'rbkb/command_line'
-
-include RBkB::CommandLine
-
-OPTS = {:first => 0, :last => -1}
-arg = bkb_stdargs(nil, OPTS)
-arg = bkb_inputargs(arg, OPTS)
-
-arg.on("-r", "--range=START[:END]", "Start and optional end range") do |r|
-
-  raise "-x and -r are mutually exclusive" if OPTS[:first]
-
-  unless m=/^(-?[0-9]+)(?::(-?[0-9]+))?$/.match(r)
-    raise "invalid range #{r.inspect}"
-  end
-
-  OPTS[:first] = $1.to_i
-  OPTS[:last] = $2.to_i if $2
-end
-
-arg.on("-x", "--hexrange=START[:END]", "same, but in hex") do |r|
-
-  raise "-x and -r are mutually exclusive" if OPTS[:first]
-
-  unless m=/^(-?[0-9a-f]+)(?::(-?[0-9a-f]+))?$/i.match(r)
-    raise "invalid range #{r.inspect}"
-  end
-
-  OPTS[:first]=($1[0,1] == '-')? ($1[1..-1]).hex_to_num * -1 : $1.hex_to_num
-  if $2
-    OPTS[:last]=($2[0,1] == '-')? ($2[1..-1]).hex_to_num * -1 : $2.hex_to_num
-  end
-end
-
-begin
-  arg.parse!
-
-  raise "bad arguments #{ARGV.join(" ").inspect}" unless (ARGV.length == 0)
-
-  OPTS[:indat] ||= STDIN.read()
-
-  puts OPTS[:indat][ OPTS[:first] .. OPTS[:last] ].crc32.to_hex
-
-rescue
-  bail "Error: #{$!}\n#{arg}"
-end
+require "rbkb/cli/crc32"
 
+Rbkb::Cli::Crc32.run()

data/bin/d64

@@ -1,41 +1,5 @@
 #!/usr/bin/env ruby
-# Author Eric Monti (emonti at matasano)
-#
-# d64 converts a base-64 encoded string back to its orginal form.
-#
-# Usage: d64 -h
-#
-require 'rbkb'
-require 'rbkb/command_line'
 
-include RBkB::CommandLine
-
-#-------------------------------------------------------------------------------
-# Init options and arg parsing
-OPTS = {}
-arg = bkb_stdargs(nil, OPTS)
-arg = bkb_inputargs(arg, OPTS)
-
-arg.banner += " <data | blank for stdin>"
-
-#------------------------------------------------------------------------------
-# Parse arguments
-arg.parse!(ARGV) rescue bail "Error: #{$!}\n#{arg}"
-
-# default string arg
-if OPTS[:indat].nil? and a=ARGV.shift
-	OPTS[:indat] = a.dup 
-end
-
-# catchall
-if ARGV.length != 0 
-    bail "Error: bad arguments - #{ARGV.join(' ')}\n-h|--help for more info."
-end
-
-OPTS[:indat] ||= STDIN.read()
-
-#------------------------------------------------------------------------------
-# Do Stuff
-
-print OPTS[:indat].d64
+require "rbkb/cli/d64"
 
+Rbkb::Cli::D64.run()

data/bin/dedump

@@ -1,53 +1,5 @@
 #!/usr/bin/env ruby
-# Author Eric Monti (emonti at matasano)
-#
-# Reverses a hexdump back to raw data. Designed to work with hexdumps created 
-# by Unix utilities like 'xxd' as well as 'hexdump -C'.
-
-require 'rbkb'
-require 'rbkb/command_line'
-
-include RBkB::CommandLine
-
-#------------------------------------------------------------------------------
-# Init options and arg parsing
-OPTS = {:len => 16}
-arg = bkb_stdargs(nil, OPTS)
-
-arg.banner += " <input-file | blank for stdin>"
-
-#------------------------------------------------------------------------------
-# Add local options
-
-arg.on("-l", "--length LEN", Numeric, 
-  "Bytes per line in hexdump (default: #{OPTS[:len]})") do |l|
-    bail("Length must be greater than zero") unless (OPTS[:len] = l) > 0
-end
-
-#------------------------------------------------------------------------------
-# Parse arguments
-arg.parse!(ARGV) rescue bail "Error: #{$!}\nUse -h|--help for more info."
-
-if OPTS[:indat].nil? and a=ARGV.shift
-  OPTS[:indat] = File.open(a, "rb") rescue "Error: Can't open file '#{a}'"
-end
-
-# catchall
-if ARGV.length != 0 
-    bail "Error: bad arguments - #{ARGV.join(' ')}\n-h|--help for more info."
-end
-
-# Default to standard input
-OPTS[:indat] ||= STDIN.read() 
-
-#------------------------------------------------------------------------------
-# Do stuff
-
-exit 1 unless((OPTS[:len] ||= OPTS[:indat].length) > 0)
-
-OPTS[:indat].dehexdump(
-  :len => OPTS[:len], 
-  :out => STDOUT
-) rescue bail "Error: #{$!}"
 
+require "rbkb/cli/dedump"
 
+Rbkb::Cli::Dedump.run()