binstruct 1.0.0

data/History.txt

@@ -0,0 +1,4 @@
+=== 1.0.0 / 2009-04-01
+
+* Although an unfortunate date, first public release.
+

data/Manifest.txt

@@ -0,0 +1,9 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/binstruct
+lib/binstruct.rb
+lib/fields.rb
+lib/objhax.rb
+test/test_binstruct.rb

data/README.txt

@@ -0,0 +1,106 @@
+= binstruct
+
+http://metafuzz.rubyforge.org/binstruct
+
+== DESCRIPTION:
+
+BinStruct is a small class for defining structures that can be used to parse /
+manipulate binary data. It is similar in concept to BitStruct, but supports
+some things that are difficult to do with a pure pack / unpack approach. It is
+mainly designed to work with the Metafuzz fuzzing tools, but would possibly be
+useful to anyone working with binary data.
+
+== FEATURES/PROBLEMS:
+
+* Parsing is done 'as you go' which means you can refer to previous fields or
+  values when making parser decisions (variable length fields etc)
+* Supports byte-swapped multi-byte bitfields for little endian file formats and
+  substructs for nested parsing
+* Full Ruby inside the class definition, with a little bit of syntactic sugar 
+  for field type definitions
+* All field data remains in the original binary internally, but get / setters 
+  are available for signed, unsigned, string, octets, hexstring and bitstring
+  and can be easily extended.
+* Key instance methods are get / setters for the fields (defined when the 
+  subclass is constructed), directly access the raw field object with #[:afield]
+  #each {|item| (item may be a substruct), #deep_each {|field| (for nested
+  structs), #flatten and of course #to_s to re-pack as a string.
+* Because this class was designed for use with a fuzzer it does not do very 
+  stringent checking of alignment, length matching etc, and raw contents are 
+  available where possible. This is either a bug or a feature, depending on 
+  your point of view.
+
+== SYNOPSIS:
+
+This example is from some Word binary file work...
+
+ class WordDgg < BinStruct
+    parse{ |bitbuf|
+        endian :little
+        # These two bytes will be swapped before they are carved up, and
+        # swapped back whenever to_s is called. The bitfield itself cannot
+        # be directly accessed, just the fields inside.
+        bitfield(bitbuf, 16) do |buf|
+            unsigned buf, :recInstance, 12, "Object Identifier"
+            unsigned buf, :recVer, 4, "Object version, 0xF for container"
+        end
+        # Normal field definitions take effect immediately, and consume
+        # the portion of the bit buffer they used.
+        unsigned bitbuf, :recType, 16, "RecType"
+        unsigned bitbuf, :recLen, 32, "Content length"
+        # Context sensitive parsing...
+        if self.recVer==0xF
+            substruct_name=:substruct0
+            # Manually manipulate the buffer parameter, if you like.
+            mychunk=[bitbuf.slice!(0,self.recLen*8)].pack('B*')
+            while mychunk.length > 0
+                # Nested parsing, here...
+                substruct(mychunk, substruct_name, mychunk.length, WordDgg)
+                substruct_name=substruct_name.succ
+            end
+        else
+            string bitbuf, :contents, self.recLen*8, "Contents"
+        end
+        # groups link sets of fields, using a given name. The groups are used
+        # by Metafuzz to create cartestian product output of the fuzz items 
+        # for all fields in the group.
+        if self[:contents]
+            group :tv, :recType, :contents
+        else
+            group :tl, :recType, :recLen
+        end
+    }
+ end
+
+== REQUIREMENTS:
+
+None.
+
+== INSTALL:
+
+Just install the gem.
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2006 Ben Nagy
+
+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,12 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/binstruct.rb'
+
+Hoe.new('binstruct', Binstruct::VERSION) do |p|
+  p.rubyforge_name = 'metafuzz' # if different than lowercase project name
+  p.developer('Ben Nagy', 'metafuzz@ben.iagu.net')
+end
+
+# vim: syntax=Ruby

data/bin/binstruct

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+abort "you need to write me"

data/lib/binstruct.rb

@@ -0,0 +1,252 @@
+require 'fields'
+require 'objhax'
+
+# There are two main classes of methods for a Binstruct, but because of the
+# implementation they are all actually instance methods. The "construction"
+# methods are +endian+, +bitfield+, +substruct+ and all the builders for field
+# subtypes. Each class in the Fields module has a builder, so UnsignedField is
+# just unsigned. Those methods are created at runtime, so they can't be 
+# seen by rdoc, but they all look like:
+#    unsigned, buffer_name, :accessor_sym, length_in_bits, "Description"
+# Inside a parse block, the buffer name used for the field builders should match
+# the block parameter, unless you are manually messing with the buffer. The
+# same applies to fields created inside the blocks for substructs and bitfields.
+#
+# The other methods are 'proper' instance methods, to work with the structure
+# once it is created and filled with data. Each field creates a getter and 
+# setter method matching its symbol, and also a direct access via [:field_sym]
+# that returns the field itself, which gives you access to the field's own
+# instance methods like +set_raw+ (see Fields).
+class Binstruct
+    VERSION="1.0.0"
+
+    class Bitfield < Binstruct # :nodoc:
+    end
+    attr_reader :groups
+    attr_accessor :fields, :endian
+    #---------------CONSTRUCTION-------------------
+
+    # Set the endianness for the whole structure. Default is +:big+, options
+    # are +:big+ or +:little+. Fields created after this method is invoked in
+    # a construction block will be created with the new endianness. You can also
+    # set the endianness after construction with <code>somestruct.endian=:little
+    # </code>.
+    def endian( sym )
+        unless sym==:little || sym==:big
+            raise RuntimeError, "Binstruct: Construction: Unknown endianness #{sym.to_s}"
+        end
+        @endian=sym
+        meta_def :endian do @endian end
+        meta_def :endianness do @endian end
+    end
+
+    # In little endian structures, byte-swaps 16, 32 or 64 bits and presents
+    # them for carving into fields. Only really neccessary for non-byte aligned
+    # field sets in little endian structures. The bitfield itself is invisible
+    # but the fields are created with the usual accessors.
+    def bitfield(bitbuf, len, &blk)
+        if @endian==:little
+            unless len==16||len==32||len==64
+                raise RuntimeError, "Binstruct: Bitfield: Don't know how to endian swap #{len} bits. :("
+            end
+            instr=bitbuf.slice!(0,len).scan(/.{8}/).reverse.join
+        else
+            instr=bitbuf.slice!(0,len)
+        end
+        new=Bitfield.new([instr].pack('B*'), &blk)
+        if @endian==:little
+            # This is so we know to flip the bytes back in #to_s
+            new.instance_variable_set :@endian_flip_hack, true
+        end
+        @fields << new
+        # Add direct references and accessor methods to the containing Binstruct
+        new.fields.each {|f| 
+            unless f.is_a? Fields::Field
+                raise RuntimeError, "Binstruct: Construction: Illegal content #{f.class} in bitfield - use only Fields"
+            end
+            @hash_references[f.name]=f
+            meta_def f.name do f.get_value end
+            meta_def (f.name.to_s + '=').to_sym do |val| f.set_value(val) end
+        }
+    end
+
+    # Creates a nested structure, and a direct accesor for it that returns the 
+    # structure itself, so accessors like <code>main.sub1.sub2.some_val</code>
+    # are possible.
+    # When iterating over the Binstruct contents, see +#each+, which will pass
+    # substructs to the block and +#deep_each+ which recursively enters 
+    # substructs and passes only Fields.
+    def substruct(strbuf, name, len, klass)
+        new=klass.new(strbuf)
+        @fields << new
+        @hash_references[name]=new
+        meta_def name do new end
+        # More informative than the NoMethodError they would normally get.
+        meta_def (name.to_s + '=').to_sym do raise NoMethodError, "Binstruct: Illegal call of '=' on a substruct." end
+    end
+
+    #fieldtype builders
+    Fields::Field_Subtypes.each {|fieldname|
+        field_klass=Fields.const_get(fieldname.capitalize.to_s+"Field")
+        define_method fieldname do |*args|
+            bitbuf, name, len, desc=args
+            @fields << thisfield=field_klass.new(bitbuf.slice!(0,len),name,len,desc,nil,@endian||:big)
+            @hash_references[name.to_sym]=thisfield
+            meta_def name do thisfield.get_value end
+            meta_def (name.to_s + '=').to_sym do |val| thisfield.set_value(val) end
+        end
+    }
+
+    # Groups a list of fields under +:groupname+. Designed for use in Metafuzz.
+    # +somestruct.groups+ will return the hash of <code>{:group_sym=>[field1,
+    # field2...]}</code>
+    def group( groupname, *fieldsyms )
+        @groups[groupname] << fieldsyms
+    end
+
+    class << self
+        attr_reader :init_block
+    end
+
+    # There are two ways to create a Binstruct subclass, one is by calling
+    # parse inside the structure definition:
+    #   class Foo < Binstruct
+    #       parse {|buffer_as_binary|
+    #           #definitions here
+    #       }
+    #   end
+    # and the other is by just supplying a block to new:
+    #   quick_struct=Binstruct.new {|b| string, b, :foo, 32, "Some String"}
+    # Otherwise, +Binstruct.new+ will just create a blank structure (this can
+    # be useful if you want to fill in the fields at runtime).
+    def self.parse( &blk )
+        @init_block=blk
+    end
+    
+    #------------END CONSTRUCTION------------------
+    
+    def initialize(buffer=nil, &blk)
+        @fields=[]
+        @hash_references={}
+        @endian_flip_hack=false
+        @groups=Hash.new {|h,k| h[k]=[]}
+        buffer||=""
+        @bitbuf=buffer.unpack('B*').join
+        if block_given?
+            instance_exec(@bitbuf, &blk)
+        elsif self.class.init_block
+            instance_exec(@bitbuf, &self.class.init_block)
+        else
+            # do nothing, user probably just wants a blank struct to manually add fields.
+        end
+        endian :big unless @endian
+        @groups.each {|group, contents|
+            unless contents.flatten.all? {|sym| @hash_references.keys.any? {|othersym| othersym==sym}}
+                raise RuntimeError, "Binstruct: Construction: group #{group} contains invalid field name(s)"
+            end
+        }
+        # This is not ideal for structures that aren't byte aligned, but raising an exception 
+        # would be less flexible.
+        buffer.replace @bitbuf.scan(/.{8}/).map {|e| e.to_i(2).chr}.join unless buffer.nil?
+    end
+
+    #----------------INSTANCE----------------------
+    
+    # return an object, specified by symbol. May be a field or a substruct.
+    # not designed for bitfields, since they're supposed to be invisible
+    # containers.
+    def []( sym )
+        @hash_references[sym]
+    end
+
+    # yield each object to the block. This is a little messy, because
+    # substructs are not Fields::Field types. For Bitfields, just silently
+    # yield each component, not the container field. The upshot of all this
+    # is that the caller needs to be prepared for a Field or a Binstruct in the
+    # block. This is the 'shallow' each.
+    def each( &blk ) #:yields: a Field or a Bitstruct
+        @fields.each {|atom|
+            if atom.is_a? Bitfield
+                atom.fields.each {|f| yield f}
+            else
+                yield atom
+            end
+        }
+
+    end
+
+    # yield all fields in the structure, entering nested substructs as necessary
+    def deep_each( &blk ) #:yields: a Field
+        @fields.each {|atom|
+            if atom.is_a? Binstruct
+                atom.deep_each &blk unless atom.fields.empty?
+            else
+                yield atom
+            end
+        }
+    end
+
+    # Searches a Binstruct, recursing through nested structures as neccessary,
+    # and replaces a given object with a new object. Note that this replaces 
+    # the object that ==oldthing, so a reference to it is needed first.
+    def replace(oldthing, newthing)
+        k,v=@hash_references.select {|k,v| v==oldthing}.flatten
+        @hash_references[k]=newthing
+        @fields.map! {|atom|
+            if atom==oldthing
+                newthing
+            else
+                if atom.is_a? Binstruct
+                    atom.replace(oldthing,newthing)
+                end
+                atom
+            end
+        }
+    end
+
+    # Flattens all fields in nested structures into an array, preserving order.
+    # In some cases (eg little endian structures with bitfields) this will mean
+    # that struct.flatten.join will not be the same as struct.to_s.
+    def flatten
+        a=[]
+        self.deep_each {|f| a << f}
+        a
+    end
+
+    #pack current struct as a string - for Fields, it will use the bitstring, 
+    #for anything else (including Bitfields and Binstructs) it will use 
+    #<code>to_s.unpack('B*')</code>. Via a filthy internal hack, bitfields 
+    #get byte-swapped
+    #back in here. Finally, once the bitstring is assembled, it is right-padded
+    #with 0 and packed as a string.
+    def to_s
+        bits=@fields.inject("") {|str,field| 
+            field.kind_of?(Fields::Field) ?  str << field.bitstring : str << field.to_s.unpack('B*').join
+        } 
+        unless bits.length % 8 == 0
+            #puts "Warning, structure not byte aligned, right padding with 0"
+        end
+        return "" if bits.empty?
+        bytearray=bits.scan(/.{1,8}/)
+        # If not byte aligned, right pad with 0
+        bytearray.last << '0'*(8-bytearray.last.length) if bytearray.last.length < 8
+        # This only happens for Binstructs that have the endian_flip_hack ivar
+        # set, so only inside the to_s of a Bitfield when little endian.
+        bytearray=bytearray.reverse if @endian_flip_hack
+        bytearray.map {|byte| "" << byte.to_i(2)}.join
+    end
+
+    # Packed length in bytes.
+    def length
+        self.to_s.length
+    end
+    
+    # Returns an array of terse field descriptions which show the index, field
+    # class, name and length in bits, plus a hexdumped snippet of the contents.
+    def inspect
+        # This could possibly be more readable...
+        self.flatten.map {|field| "<IDX:#{self.flatten.index(field)}><#{field.class.to_s.match(/::(.+)Field/)[1]}><#{field.name}><#{field.length}><#{field.to_s[0..12].each_byte.to_a.map {|b| "%.2x" % b}.join(' ') + (field.to_s.length>12?"...":"")}>"}
+    end
+end
+
+

data/lib/fields.rb

@@ -0,0 +1,310 @@
+#If you add new Field subclasses, you need to name them with a capitalized 'Field' at the end, eg CrazyField, and use it in Binstruct by declaring the
+#first half in lower case. Like this:
+# module Fields
+# 	class CrazyField < StringField
+#		# I act just like a StringField, only crunchy!
+# 	end
+# end
+#
+# class MyStruct < Binstruct
+# 	crazy :field_name, 32, "A Crazy Field!"
+#	[...]
+#
+#Take a look at the documentation for Fields::Field for some other guidlines on creating new Field subclasses that can't trivially
+#inherit one of the base classes like Fields::StringField or Fields::HexstringField.
+module Fields
+
+    #Subclasses of Fields::Field should probably at least overload <tt>input_to_bitstring</tt> and <tt>get_value</tt> and
+    #set <tt>@length_type</tt>. Check the source code for the base subclasses for ideas. Remember that for the
+    #purposes of fuzzing you can probably get away with
+    #inheriting from one of the base classes a lot of the time - an EmailField can probably just inherit StringField unless you want
+    #stringent checking in your parser.
+    class Field
+
+        attr_reader :bitstring, :desc, :length, :type, :default_value, :name, :length_type, :endianness
+
+        def initialize(bitstring, name, length, desc, default, endian)
+            @name=name
+            @length=length
+            @desc=desc
+            default&&=self.input_to_bitstring(default)
+            @default_value=default # can still be nil
+            @bitstring=self.parse_buffer(bitstring)
+            @type=self.class.to_s[/\w+(?=Field)/].downcase #fricking ugly
+            @endianness=endian
+            unless @endianness.downcase==:big or @endianness.downcase==:little
+                raise ArgumentError, "#{self.class.to_s[/\w+$/]} (#{@name}): Unknown endianness #{endianness}, use :little or :big (default)."
+            end
+        end
+
+        # Provided for classes that require strict lengths. Left pads with 0 to @length
+        # if the input buffer is incomplete. Truncates at @length if too long. Called by <tt>parse_buffer</tt> internally.
+        def parse_buffer_strict( bitstring )
+            return "" unless bitstring
+            bitstring||=""
+            unless bitstring.is_a? String and bitstring=~/^[10]*$/
+                raise ArgumentError, "Field: <Internal> bitstring buffer borked?? #{bitstring.inspect}"
+            end
+            if bitstring.length <= @length
+        "0"*(@length-bitstring.length)+bitstring
+            elsif bitstring.length > @length
+                bitstring.slice(0,@length)
+            else
+                raise RuntimeError, "Universe Broken Error: value neither less/equal nor greater"
+            end
+        end
+
+        # Provided for classes that don't care about length matching
+        # when assigning the contents. Called by <tt>parse_buffer</tt> internally.
+        def parse_buffer_lazy( bitstring )
+            return "" unless bitstring
+            bitstring||=""
+            unless bitstring.is_a? String and bitstring=~/^[10]*$/
+                raise ArgumentError, "#{self.class.to_s[/\w+$/]} (#{@name}): <Internal> bitstring buffer borked??"
+            end
+            bitstring
+        end
+
+        # Placeholder, subclasses should probably redefine for clarity. Defaults to calling parse_buffer_strict, but uses
+        # parse_buffer_lazy for variable length fields.
+        def parse_buffer( bitstring )
+            return self.parse_buffer_lazy( bitstring ) if self.length_type=="variable"
+            self.parse_buffer_strict( bitstring ) # default to this for subclasses that forget to define @length_type
+        end
+
+        #Sets the raw field contents. Can be useful if the set_value method does inconvenient checking when you want
+        #to set crazy values.
+        def set_raw( bitstring )
+            @bitstring=self.parse_buffer( bitstring )
+        end
+
+        # Placeholder, classes should override as neccessary.
+        # Parse a value in whatever format is determined by the class
+        # and return a bitstring.
+        # This default does zero checking, so expects a bitstring as input
+        def input_to_bitstring( value )
+            value
+        end
+
+        # Randomize the bitstring for this field, bit by bit
+        def randomize!
+            random_bitstring=Array.new(self.length).map {|e| e=rand(2).to_s}.join
+            if self.length_type=="variable"
+                slice=random_bitstring[0,(rand((self.length/8)+1)*8)]
+                set_raw(slice)
+            else
+                set_raw(random_bitstring)
+            end
+        end
+
+        #Set the field value. Calls self.input_to_bitstring which is expected to return a binary string.
+        def set_value(new_val)
+            @bitstring=self.input_to_bitstring(new_val)
+        end
+
+        #Subclasses should override this. This default returns the raw bitstring.
+        def get_value
+            @bitstring
+        end
+
+        # This really only makes sense for fields that are byte aligned, but what the hey. For the rest it effectively
+        # packs them as left padded with zeroes to a byte boundary (so a 3 bit field "110" will pack as \006)
+        def to_s
+            @bitstring.reverse.scan(/.{1,8}/).map {|s| s.reverse}.reverse.map {|bin| "" << bin.to_i(2)}.join
+        end
+
+    end # Field
+
+    #Accepts negative numbers on assignment, but stores them as 2s complement.
+    class UnsignedField < Field
+
+        def initialize *args
+            @length_type="fixed"
+            super
+        end
+
+        def input_to_bitstring( value )
+            unless value.kind_of? Integer
+                raise ArgumentError, "UnsignedField (#{@name}): attempted to assign non-integer"
+            end
+            if value.to_s(2).length > @length
+                # works for negative assignments as well, since to_s(2) adds a '-' to the start of the binary string
+                raise ArgumentError, "UnsignedField (#{@name}): value too big for field length"
+            end
+            # accept negative numbers, but store them as their two's complement representation for this bitlength
+            # (get_value will return the positive interpretation)
+            unpadded=value < 0 ? (("1"+"0"*@length).to_i(2)-value.abs).to_s(2) : value.to_s(2)
+            value="0"*(@length-unpadded.length)+unpadded # left pad with zeroes to full length
+            if self.endianness==:little
+                if value.length > 8 && value.length % 8 ==0
+                    value=value.scan(/.{8}/).reverse.join
+                end
+            end
+            value
+        end
+
+        def get_value
+            tempstring=@bitstring
+            if self.endianness==:little
+                if tempstring.length > 8 && tempstring.length % 8 ==0
+                    tempstring=tempstring.scan(/.{8}/).reverse.join
+                end
+            end
+            tempstring.to_i(2)
+        end
+
+    end #UnsignedField
+
+    #For IP addresses etc
+    class OctetstringField < Field
+
+        def initialize(*args)
+            raise ArgumentError, "OctetstringField  (#{args[1]})(CREATE): Length must be a multiple of 8 bits" unless args[2]%8==0
+            @length_type="fixed"
+            super
+        end
+
+        def input_to_bitstring( value )
+            # Expects [0-255][.0-255] .....
+            begin
+                unless value.split('.').all? {|elem| Integer(elem)<256 && Integer(elem) >= 0}
+                    raise ArgumentError, "OctetstringField (#{@name})(PARSE): Unable to parse input value"
+                end
+            rescue
+                raise ArgumentError, "OctetstringField (#{@name})(PARSE): Unable to parse input value"
+            end
+            octets=value.split('.')
+            raise ArgumentError, "OctetstringField (#{@name}): Not enough octets?" if (octets.length)*8 < @length
+            raise ArgumentError, "OctetstringField (#{@name}): Too many octets?" if (octets.length*8) > @length
+            octets.inject("") do |str,num| 
+                str << "%.8b"%num
+            end
+        end
+
+        def get_value
+            @bitstring.scan(/.{8}/).map {|e| e.to_i(2).to_s}.join('.')
+        end
+    end #OctetstringField
+
+
+    #For getting and setting via hex strings.
+    class HexstringField < Field
+
+        def initialize *args
+            @length_type="variable"
+            super
+        end
+
+        def input_to_bitstring( value )
+            if (value.respond_to? :to_int) and value >= 0
+                bs=value.to_int.to_s(2)
+            elsif (value.respond_to? :to_str) and value.to_str=~/^[a-f0-9\s]*$/
+                bs=value.to_str.gsub(/\s/,'').to_i(16).to_s(2)
+            else
+                raise ArgumentError, "HexstringField (#{@name}): Unable to parse input value."
+            end
+            (bs.length % 8 != 0) && bs=("0"*(8-bs.length%8) + bs)
+            bs
+        end
+
+        def get_value
+            return '' if @bitstring==""
+            unless @bitstring.length > 8 && @bitstring.length % 8 == 0
+                #do the best we can..
+                hexstring=@bitstring.to_i(2).to_s(16)
+                (hexstring.length % 2 == 1) && hexstring="0"+hexstring
+            else
+                hexstring=bitstring.scan(/.{8}/).map {|e| "%.2x" % e.to_i(2)}.join
+            end
+            hexstring
+        end
+
+    end #HexstringField
+
+    class SignedField < Field
+
+        def initialize *args
+            @length_type="fixed"
+            super
+        end
+
+        def input_to_bitstring( value )
+            unless value.kind_of? Integer
+                raise ArgumentError, "SignedField (#{@name}): attempted to assign non-integer"
+            end
+            if value < 0 and value.to_s(2).length > @length
+                # int.to_s(2) will return "-1001001" etc for negative numbers in binary, so this length check will work.
+                raise ArgumentError, "SignedField (#{@name}): negative value too long for field length"
+            end
+            if value > 0 and value.to_s(2).length > @length-1 # positive integers shouldn't overflow the sign bit
+                raise ArgumentError, "SignedField (#{@name}): positive value too long for field length"
+            end
+            unpadded=value <= 0 ? (("1"+"0"*@length).to_i(2)-value.abs).to_s(2) : value.to_s(2)
+            value="0"*(@length-unpadded.length)+unpadded # left pad with zeroes to full length
+            if self.endianness==:little
+                if value.length > 8 && value.length % 8==0
+                    value=value.scan(/.{8}/).reverse.join
+                end
+            end
+            value
+        end
+
+        def get_value
+            tempstring=@bitstring
+            if self.endianness==:little
+                if tempstring.length > 8 && tempstring.length % 8 ==0
+                    tempstring=tempstring.scan(/.{8}/).reverse.join
+                end
+            end
+            if tempstring.slice(0,1)=="1" #sign bit set
+                0-(("1"+"0"*@length).to_i(2)-tempstring.to_i(2))
+            elsif  @bitstring.slice(0,1)=="0"
+                tempstring.to_i(2)
+            else	
+                raise RuntimeError, "SignedField: Ouch, internal contents screwed somehow."
+            end
+        end			  
+
+    end # SignedField
+
+    class StringField < Field
+        def initialize *args
+            @length_type="variable"
+            super
+        end
+
+        def input_to_bitstring( value )
+            unless value.respond_to? :to_str 
+                raise ArgumentError, "StringField(#{@name}): Input value not a string."
+            end
+            value.to_str.unpack('B*').join
+        end
+
+        def get_value
+            return @bitstring if @bitstring==""
+            [@bitstring].pack('B*')
+        end
+    end # StringField
+
+    #For getting and setting via binary strings
+    class BitstringField < Field
+
+        def initialize *args
+            @length_type="fixed"
+            super
+        end
+
+        def input_to_bitstring( value )
+            unless value.respond_to? :to_str  and value.to_str=~/^[01\s]*$/
+                raise ArgumentError, "BitstringField(#{@name}) (PARSE): Input value not a bitstring."
+            end
+            parse_buffer(value.to_str.gsub(/\s/,''))
+        end
+
+        def get_value
+            @bitstring
+        end
+    end #BitstringField
+
+    Field_Subtypes=self.constants.map {|const| const.to_s.sub(/Field/,'').downcase.to_sym if const=~/^.+Field/}.compact
+end # Fields

data/lib/objhax.rb

@@ -0,0 +1,42 @@
+# A collection of useful code bits that have been pilfered from various sources 
+# on the Interweb.
+
+class Object # :nodoc: all
+    #Return the metaclass of an object.
+    def metaclass 
+        class << self
+            self 
+        end 
+    end
+
+    #Run a  block in the context of the metaclass.
+    def meta_eval &blk; metaclass.instance_eval &blk; end
+
+    # Adds methods to a metaclass
+    def meta_def name, &blk
+        meta_eval { define_method name, &blk }
+    end
+
+    # Defines an instance method within a class
+    def class_def name, &blk
+        class_eval { define_method name, &blk }
+    end
+
+    # Deep copy of objects that can be handled with Marshal
+    def deep_copy
+        Marshal.load(Marshal.dump(self))
+    end
+
+    #Define, run and then undefine a method to fake instance_eval with arguments
+    #(not needed on 1.9)
+    def instance_exec(*args, &block)
+        mname = "__instance_exec_#{Thread.current.object_id.abs}"
+        class << self; self end.class_eval{ define_method(mname, &block) }
+        begin
+            ret = send(mname, *args)
+        ensure
+            class << self; self end.class_eval{ undef_method(mname) } rescue nil
+        end
+        ret
+    end
+end

data/test/test_binstruct.rb

@@ -0,0 +1,8 @@
+require "test/unit"
+require "binstruct"
+
+class TestBinstruct < Test::Unit::TestCase
+  def test_sanity
+    flunk "write tests or I will kneecap you"
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: binstruct
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Ben Nagy
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-02 00:00:00 +08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.12.1
+    version: 
+description: BinStruct is a small class for defining structures that can be used to parse / manipulate binary data. It is similar in concept to BitStruct, but supports some things that are difficult to do with a pure pack / unpack approach. It is mainly designed to work with the Metafuzz fuzzing tools, but would possibly be useful to anyone working with binary data.
+email: 
+- metafuzz@ben.iagu.net
+executables: 
+- binstruct
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- bin/binstruct
+- lib/binstruct.rb
+- lib/fields.rb
+- lib/objhax.rb
+- test/test_binstruct.rb
+has_rdoc: true
+homepage: http://metafuzz.rubyforge.org/binstruct
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: metafuzz
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: BinStruct is a small class for defining structures that can be used to parse / manipulate binary data
+test_files: 
+- test/test_binstruct.rb