rbkb 0.6.10

data/bin/rex

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+#
+# lazy form of ruby -e "xxxx". All commandline arguments get smeared to
+# pure ruby.
+
+require 'pp'
+require 'rbkb'
+
+eval ARGV.join(' ');
+

data/bin/rstrings

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

data/bin/slice

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

data/bin/telson

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

data/bin/unhexify

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

data/bin/urldec

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

data/bin/urlenc

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

data/bin/xor

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

data/cli_usage.rdoc

@@ -0,0 +1,285 @@
+== Command Line Tools
+
+Below is a list of the command line utilities with short descriptions and
+usage information. Examples to come.
+
+=== b64
+
+Base64 encode data supplied via an argument, file, or standard input.
+
+Usage: b64 [options] <data | blank for stdin>
+    -h, --help                       Show this message
+    -v, --version                    Show version and exit
+    -f, --file FILENAME              Input from FILENAME
+    -l, --length LEN                 Output LEN chars per line
+
+
+=== bgrep
+
+Binary grep. Prints 'inspected' matches and offset information.
+
+  Usage: bgrep [options] <subject> <file | blank for stdin>
+    -h, --help                       Show this message
+    -v, --version                    Show version and exit
+    -x, --[no-]hex                   Specify subject as hex (default: false)
+    -r, --[no-]regex                 Specify subject as regex (default: false)
+    -a, --align=BYTES                Only match on alignment boundary
+    -n, --[no-]filename              Suppress prefixing of filenames.
+
+
+=== blit
+
+Sends data through any plugboard that implements a Plug::Blit listener for
+out-of band input.
+
+See also: telson
+
+  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.
+
+
+=== c
+
+Prints a character n-times.
+
+  Usage: c 100 A; # print 100 A's'
+
+
+=== crc32
+
+Generates a crc32 checksum for data provided via stdin or 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
+
+
+=== d64
+
+Base64 decode an encoded chunk supplied via argument, file, or standard input.
+
+Usage: d64 [options] <data | blank for stdin>
+    -h, --help                       Show this message
+    -v, --version                    Show version and exit
+    -f, --file FILENAME              Input from FILENAME
+
+
+=== dedump
+
+Reverses a hexdump back to raw data. Designed to work with hexdumps created 
+by Unix utilities like 'xxd' as well as 'hexdump -C'.
+
+  Usage: dedump [options] <input-file | blank for stdin>
+    -h, --help                       Show this message
+    -v, --version                    Show version and exit
+    -l, --length LEN                 Bytes per line in hexdump (default: 16)
+
+
+=== feed
+
+This is a plug-board message feeder from static data sources.
+The "feed" handles messages opaquely and just plays them as a server or
+client in the given sequence.
+
+Feed can do the following things with minimum fuss: 
+* Import messages from files, yaml, or pcap
+* Inject custom/modified messages with "blit"
+* Run as a server or client using UDP or TCP
+* Bootstrap protocols without a lot of work up front
+* Skip uninteresting messages and focus attention on the fun ones.
+* Replay conversations for relatively unfamiliar protocols.
+* Observe client/server behaviors using different messages at 
+  various phases of a conversation.
+
+  Usage: feed [options] host:port
+      -h, --help                       Show this message
+      -v, --version                    Show version and exit
+      -o, --output=FILE                Output to file
+      -l, --listen=(ADDR:?)PORT        Server - on port (and addr?)
+      -s, --source=(ADDR:?)PORT        Bind client on port and addr
+      -b, --blit=(ADDR:)?PORT          Where to listen for blit
+      -i, --[no-]initiate              Send the first message on connect
+      -e, --[no-]end                   End connection when feed is exhausted
+          --[no-]step                  'Continue' prompt between messages
+      -u, --udp                        Use UDP instead of TCP
+      -r, --reconnect                  Attempt to reconnect endlessly.
+      -q, --quiet                      Suppress verbose messages/dumps
+      -Q, --squelch-exhausted          Squelch 'FEED EXHAUSTED' messages
+    Sources: (can be combined)
+      -f, --from-files=GLOB            Import messages from raw files
+      -x, --from-hex=FILE              Import messages from hexdumps
+      -y, --from-yaml=FILE             Import messages from yaml
+      -p, --from-pcap=FILE[:FILTER]    Import messages from pcap
+
+
+
+=== hexify
+
+Converts a string or raw data to hex characters. Input can be supplied via 
+stdin, a string argument, or a file (with -f).
+
+  Usage: hexify [options] <data | blank for stdin>
+    -h, --help                       Show this message
+    -v, --version                    Show version and exit
+    -f, --file FILENAME              Input from FILENAME
+    -l, --length LEN                 Hexify in lines of LEN bytes
+    -d, --delim=DELIMITER            DELIMITER between each byte
+    -p, --prefix=PREFIX              PREFIX before each byte
+    -s, --suffix=SUFFIX              SUFFIX after each byte
+
+
+=== len
+
+Takes input from a blob of data and output it with its binary length prepended.
+
+  Usage: len [options] <data | blank for stdin>
+    -h, --help                       Show this message
+    -v, --version                    Show version and exit
+    -f, --file FILENAME              Input from FILENAME
+    -n, --nudge INT                  Add integer to length
+    -s, --size=SIZE                  Size of length field in bytes
+    -x, --[no-]swap                  Swap endianness. Default=big
+    -t, --[no-]total                 Include size word in size
+    -l, --length=LEN                 Ignore all else and use LEN
+
+
+=== plugsrv
+
+A blit-able reverse TCP proxy. Displays traffic hexdumps.
+
+  Usage: 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.
+      -b, --blit ADDR:PORT             specify blit listener [address:]port
+                                       (default: 127.0.0.1:25195)
+          --[no-]target-tls            enable/disable TLS to target
+          --[no-]server-tls            enable/disable TLS to clients
+      -h, --help                       Show this message
+
+
+=== rex
+
+  Lazy shortcut for ruby -e "..."
+
+  All commandline arguments get smeared into a ruby statement via 'eval()'.
+
+
+=== rstrings
+
+A utility much like Unix 'strings' -- implemented in ruby.
+
+  Usage: rstrings [options] <file | blank for stdin>
+    -h, --help                       Show this message
+    -v, --version                    Show version and exit
+    -s, --start=OFFSET               Start at offset
+    -e, --end=OFFSET                 End at offset
+    -t, --encoding-type=TYPE         Encoding: ascii/unicode/both (default=both)
+    -l, --min-length=NUM             Minimum length of strings (default=6)
+    -a, --align=ALIGNMENT            Match only on alignment (default=none)
+
+
+=== slice
+
+Returns a slice from input. Just a shell interface to a string slice operation.
+
+  Usage: slice [options] start (no args when using -r|-x)
+    -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
+
+
+=== telson
+
+This is an implementation of the original blackbag "telson" using ruby and 
+eventmachine. 
+
+Telson is for doing the following things with minimum fuss: 
+
+* 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.
+
+  Usage: telson [options] host:port
+      -h, --help                       Show this message
+      -v, --version                    Show version and exit
+      -o, --output=FILE                Output to file
+      -q, --quiet                      Turn off verbose logging
+      -d, --dump-format=hex/raw        Output conversations in hexdump or raw
+      -b, --blit=ADDR:PORT             Where to listen for blit
+      -u, --udp                        UDP mode
+      -S, --start-tls                  Initiate TLS
+      -r, --reconnect                  Attempt to reconnect endlessly.
+      -s, --source=(ADDR:?)PORT        Bind client on port and addr
+
+
+=== unhexify
+
+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).
+
+  Usage: unhexify [options] <data | blank for stdin>
+    -h, --help                       Show this message
+    -v, --version                    Show version and exit
+    -f, --file FILENAME              Input from FILENAME
+    -d, --delim DELIMITER            DELIMITER regex between hex chunks
+
+
+=== urldec
+
+Decodes a url percent-encoded string. 
+Input from stdin, file, or command-line argument.
+
+  Usage: urldec [options] <data | blank for stdin>
+    -h, --help                       Show this message
+    -v, --version                    Show version and exit
+    -f, --file FILENAME              Input from FILENAME
+    -p, --[no-]plus                  Convert '+' to space (default is true)
+
+
+=== urlenc
+
+Encodes data as a url percent-encoded string.
+Input from stdin, file, or command-line argument.
+
+  Usage: urlenc [options] <data | blank for stdin>
+    -h, --help                       Show this message
+    -v, --version                    Show version and exit
+    -f, --file FILENAME              Input from FILENAME
+    -p, --[no-]plus                  Convert spaces to '+' (default is false)
+
+
+=== xor
+
+Repeating string xor. Takes input and XOR's it against a string. 
+String can be provided in hex.
+
+  Usage: xor [options] -k|-s <key> <data | stdin>
+    -h, --help                       Show this message
+    -v, --version                    Show version and exit
+    -f, --file FILENAME              Input from FILENAME
+
+  Key options (one of the following is required):
+    -s, --strkey STRING              xor against bare STRING
+    -x, --hexkey HEXSTR              xor against decoded HEXSTR
+
+

data/lib/rbkb.rb

@@ -0,0 +1,51 @@
+
+module Rbkb
+
+  # :stopdoc:
+  VERSION = '0.6.10'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to require all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+
+end  # module Rbkb
+
+#Rbkb.require_all_libs_relative_to(__FILE__)
+
+require 'rbkb/extends'
+
+# EOF

data/lib/rbkb/cli.rb

@@ -0,0 +1,219 @@
+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.
+  class Executable
+
+    def self.run(param={})
+      new(param).go
+    end
+
+    attr_accessor :stdout, :stderr, :stdin, :argv, :opts, :oparse
+    attr_reader   :exit_status
+
+    # Instantiates a new Executable object.
+    #
+    # The 'param' argument is a named value hash. The following keys are
+    # significant:
+    #
+    #  :argv   - An array of cli arguments (default ARGV)
+    #  :opts    - executable/function options for use when running 'go'
+    #  :stdout, - IO redirection (mostly for unit tests)
+    #  :stderr,   
+    #  :stdin
+    #
+    #
+    # The above keys are deleted from the 'param' hash and stored as instance
+    # variables with attr_accessors.  All other parameters are ignored.
+    def initialize(param={})
+      @argv   ||= param.delete(:argv) || ARGV
+      @stdout ||= param.delete(:stdout) || STDOUT
+      @stderr ||= param.delete(:stderr) || STDERR
+      @stdin  ||= param.delete(:stdin) || STDIN
+      @opts   ||= param.delete(:opts) || {}
+      @parser_got_range=nil
+      yield self if block_given?
+      make_parser()
+    end
+
+
+    # Wrapper for Kernel.exit() so we can unit test cli tools
+    def exit(ret)
+      @exit_status = ret
+      if defined? Rbkb::Cli::TESTING
+        throw(((ret==0)? :exit_zero : :exit_err), ret)
+      else
+        Kernel.exit(ret)
+      end
+    end
+
+
+    # This method exits with a message on stderr
+    def bail(msg)
+      @stderr.puts msg if msg
+      self.exit(1)
+    end
+
+
+    # This method wraps a 'bail' with a basic argument error mesage and hint
+    # for the '-h or --help' flag
+    # The 'arg_err'  parameter is a string with the erroneous arguments
+    def bail_args(arg_err)
+      bail "Error: bad arguments - #{arg_err}\n  Hint: Use -h or --help"
+    end
+
+
+    # Prepares an OptionsParser object with blackbag standard options
+    # This is called from within initialize() and should be overridden in
+    # inherited classes to add additional OptionParser-based parsers.
+    #
+    # See parse for actual parsing.
+    def make_parser
+      @oparse ||= OptionParser.new 
+      @oparse.banner = "Usage: #{File.basename $0} [options]"
+
+      @oparse.on("-h", "--help", "Show this message") do
+        bail(@oparse)
+      end
+
+      @oparse.on("-v", "--version", "Show version and exit") do
+        @stdout.puts("Ruby BlackBag version #{Rbkb::VERSION}")
+        self.exit(0)
+      end
+
+      return @oparse
+    end
+
+
+    # Abstract argument parser. Override this method with super() from 
+    # inherited executables. The base method just calls OptionParser.parse!
+    # on the internal @oparse object.
+    def parse
+      # parse flag arguments
+      @oparse.parse!(@argv) rescue(bail_args($!))
+      @parsed=true
+
+      # the overriding class may implement additional arguments from here
+    end
+    
+
+    # Abstract 'runner'. Override this method with super() from inherited
+    # executables. The base method just slurps in an optional argv and
+    # runs 'parse' if it hasn't already
+    def go(argv=nil)
+      @exit_status = nil
+      @argv = argv if argv 
+
+      parse
+
+      # the overriding class implements actual functionality beyond here
+    end
+
+
+    private
+
+    # Wraps a file read with a standard bail error message
+    def do_file_read(f)
+      File.read(f) rescue(bail "File Read Error: #{$!}")
+    end
+
+
+    # Implements a basic input file argument. File reading is handled
+    # by do_file_read().
+    #
+    # Takes one argument, which is the @opts hash keyname to store
+    # the file data into.
+    # (Used commonly throughout several executables)
+    def add_std_file_opt(inkey)
+      @oparse.on("-f", "--file FILENAME", "Input from FILENAME") do |f|
+        @opts[inkey] = do_file_read(f)
+      end
+      return @oparse
+    end
+
+
+    # Implements numeric and hex range options via '-r' and '-x'
+    #
+    # Takes two arguments which are the @opts hash key names for
+    # first and last parameters.
+    #
+    # (Used commonly throughout several executables)
+    def add_range_opts(fkey, lkey)
+      @oparse.on("-r", "--range=START[:END]", 
+                 "Start and optional end range") do |r|
+
+        raise "-x and -r are mutually exclusive" if @parser_got_range
+        @parser_got_range=true
+
+        unless m=/^(-?[0-9]+)(?::(-?[0-9]+))?$/.match(r)
+          raise "invalid range #{r.inspect}"
+        end
+
+        @opts[fkey] = $1.to_i
+        @opts[lkey] = $2.to_i if $2
+      end
+
+      @oparse.on("-x", "--hexrange=START[:END]", 
+                 "Start and optional end range in hex") do |r|
+
+        raise "-x and -r are mutually exclusive" if @parser_got_range
+        @parser_got_range=true
+
+        unless m=/^(-?[0-9a-f]+)(?::(-?[0-9a-f]+))?$/i.match(r)
+          raise "invalid range #{r.inspect}"
+        end
+
+        @opts[fkey] = 
+          if ($1[0,1] == '-')
+            ($1[1..-1]).hex_to_num * -1
+          else
+            $1.hex_to_num
+          end
+
+        if $2
+          @opts[lkey] = 
+            if($2[0,1] == '-')
+              $2[1..-1].hex_to_num * -1
+            else
+              $2.hex_to_num
+            end
+        end
+      end
+    end
+
+
+    # Conditionally parses a string argument. Uses 'key' to first check for 
+    # then store it in @opts hash if it is not yet there.
+    # (Used commonly throughout several executables)
+    def parse_string_argument(key)
+      if @opts[key].nil? and s=@argv.shift
+        @opts[key] = s.dup 
+      end
+    end
+
+
+    # Conditionally parses a file argument. Uses 'key' to first check for 
+    # then store it in @opts hash if it is not yet there.
+    # (Used commonly throughout several executables)
+    def parse_file_argument(key)
+      if @opts[key].nil? and f=@argv.shift
+        @opts[key] = do_file_read(f)
+      end
+    end
+
+    # For use at the end of a parser - calls bail_args with remaining
+    # arguments if there are extra arguments.
+    # (Used commonly throughout several executables)
+    def parse_catchall
+      bail_args(@argv.join(' ')) if(@argv.length != 0)
+    end
+
+  end
+end
+