ffi-ssdeep 0.1.1

data/History.txt

@@ -0,0 +1,3 @@
+== 0.1.1 / 2010-07-13
+* Initial version
+

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Eric Monti
+
+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/README.rdoc

@@ -0,0 +1,27 @@
+= ffi-ssdeep
+
+Ruby FFI bindings for the ssdeep 'libfuzzy' library api. This API lets you do 
+fuzzy hash comparisons between files and arbitrary string buffers. Fuzzy 
+hashes are also known as context triggered piecewise hashes (CTPH).
+
+See the ssdeep homepage for more information:
+  http://ssdeep.sourceforge.net
+
+== Requirements
+
+* ffi >= 0.6.0
+* ssdeep's libfuzzy - http://ssdeep.sourceforge.net
+  The version of ssdeep known to work with ffi-ssdeep is 2.5.
+
+== Installation
+
+First ensure you have installed the ssdeep package and that libfuzzy is in your libpath.
+Then, just run 
+
+   (sudo)? gem install ffi-ssdeep
+
+== License
+
+See LICENSE.txt
+
+

data/Rakefile

@@ -0,0 +1,31 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+load 'tasks/setup.rb'
+
+ensure_in_path 'lib'
+
+task :default => 'spec:run'
+
+PROJ.name = 'ffi-ssdeep'
+PROJ.authors = 'Eric Monti'
+PROJ.email = 'emonti@trustwave.com'
+PROJ.description = 'FFI bindings for the ssdeep library "libfuzzy" for fuzzy hash comparisons'
+PROJ.url = nil
+PROJ.version = File.open("version.txt","r"){|f| f.readline.chomp}
+PROJ.readme_file = 'README.rdoc'
+
+PROJ.spec.opts << '--color'
+PROJ.rdoc.opts << '--line-numbers'
+PROJ.notes.tags << "X"+"XX" # muhah! so we don't note our-self
+
+# exclude rcov.rb and external libs from rcov report
+PROJ.rcov.opts += [
+  "--exclude",  "rcov", 
+  "--exclude",  "ffi", 
+]
+
+depend_on 'ffi', '>= 0.6.0'
+
+# EOF

data/lib/ssdeep.rb

@@ -0,0 +1,73 @@
+require 'ffi'
+
+require 'ssdeep/fuzzy_hash'
+
+module Ssdeep
+  extend FFI::Library
+
+  ffi_lib 'fuzzy'
+
+  typedef :pointer, :fuzzy_hash
+
+  # Compute the fuzzy hash of a buffer.
+  # 
+  # Computes the fuzzy hash of the first buf_len bytes of the buffer. It is the caller's 
+  # responsibility to append the filename, if any, to result after computation.
+  # 
+  # Parameters:
+  #     	buf 	The data to be fuzzy hashed
+  #     	buf_len 	The length of the data being hashed
+  #     	result 	Where the fuzzy hash of buf is stored. This variable 
+  #     	        must be allocated to hold at least FUZZY_MAX_RESULT bytes.
+  # 
+  # Returns:
+  #     Returns zero on success, non-zero on error. 
+  attach_function :fuzzy_hash_buf, [:pointer, :uint32, :fuzzy_hash], :int
+
+  # Compute the fuzzy hash of a file.
+  # 
+  # Opens, reads, and hashes the contents of the file 'filename' The 
+  # result must be allocated to hold FUZZY_MAX_RESULT characters. It 
+  # is the caller's responsibility to append the filename to the 
+  # result after computation.
+  # 
+  # Parameters:
+  #     	filename 	The file to be hashed
+  #     	result 	Where the fuzzy hash of the file is stored. This variable 
+  #     	        must be allocated to hold at least FUZZY_MAX_RESULT bytes.
+  # 
+  # Returns:
+  #     Returns zero on success, non-zero on error. 
+  attach_function :fuzzy_hash_filename, [:string, :fuzzy_hash], :int
+
+  # Computes the match score between two fuzzy hash signatures.
+  #
+  # Returns:
+  #   Returns a value from zero to 100 indicating the match score of the 
+  #   two signatures. A match score of zero indicates the sigantures did 
+  #   not match. When an error occurs, such as if one of the inputs is 
+  #   NULL, returns -1. 
+  attach_function :fuzzy_compare, [:fuzzy_hash, :fuzzy_hash], :int
+
+
+  def self.hash_string(str)
+    FuzzyHash.from_string(str)
+  end
+
+  def self.hash_file(fname)
+    FuzzyHash.from_file(fname)
+  end
+
+  def self.compare_hashes(h1, h2)
+    h1.compare(h2)
+  end
+
+  def self.compare_strings(s1, s2)
+    compare_hashes(hash_string(s1), hash_string(s2))
+  end
+
+  def self.compare_files(f1, f2)
+    compare_hashes(hash_file(f1), hash_file(f2))
+  end
+
+end

data/lib/ssdeep/fuzzy_hash.rb

@@ -0,0 +1,88 @@
+
+require 'ffi'
+
+module Ssdeep
+  SPAMSUM_LENGTH = 64
+  FUZZY_MAX_RESULT = (SPAMSUM_LENGTH + (SPAMSUM_LENGTH/2 + 20)) 
+
+  class FuzzyHash < FFI::MemoryPointer
+    def initialize()
+      super(FUZZY_MAX_RESULT)
+    end
+
+    # returns the computed fuzzy hash as a string
+    def to_s
+      self.read_string()
+    end
+
+    # implements a _dump method for Marshal
+    def _dump(depth)
+      self.to_s
+    end
+
+    # @return [Integer]
+    #   Returns a value from zero to 100 indicating the match score of the 
+    #   two signatures. A match score of zero indicates the sigantures did 
+    #   not match. 
+    #
+    # @return [
+    #   When an error occurs, such as if one of the inputs is NULL.
+    def compare(other)
+      unless other.is_a?(FuzzyHash)
+        raise(TypeError, "a FuzzyHash can only be compared to another FuzzyHash")
+      end
+      if self.to_s == other.to_s
+        return 100
+      elsif (ret=Ssdeep.fuzzy_compare(self, other)) > -1
+        return ret
+      else
+        raise(StandardError, "unknown fuzzy hash comparison error")
+      end
+    end
+
+    # implements a _load method for Marshal
+    def self._load(raw)
+      from_hash(raw)
+    end
+
+    # Restores a fuzzy hash that has already been generated and supplied
+    # as a string as a instance of a FuzzyHash object.
+    def self.from_hash(raw)
+      fh = new()
+      fh.write_string( 
+        if raw.size < FUZZY_MAX_RESULT 
+          raw + "\x00" 
+        else 
+          raw[0,FUZZY_MAX_RESULT]
+        end )
+      return fh
+    end
+
+    # Creates a new fuzzy hash from a string buffer.
+    def self.from_string(buf)
+      fh = new()
+      p = FFI::MemoryPointer.new(buf.size)
+      p.write_string(buf)
+      ret = Ssdeep.fuzzy_hash_buf(p, buf.size, fh)
+      if ret == 0
+        return fh
+      else
+        fh.free
+        raise(StandardError, "An error occurred hashing a string")
+      end
+    end
+
+    # Creates a new fuzzy hash from the contents of 'filename'
+    def self.from_file(filename)
+      fh = new()
+      ret = Ssdeep.fuzzy_hash_filename(filename, fh)
+      if ret == 0
+        return fh
+      else
+        fh.free
+        raise(StandardError, "An error occurred hashing file: #{filename.inspect}")
+      end
+    end
+
+  end
+end

data/spec/fuzzy_hash_spec.rb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+
+describe Ssdeep::FuzzyHash do
+  context "basic features" do
+    before(:all) do
+      @fh1 = Ssdeep::FuzzyHash.from_file(sample_file("ssdeep.gemspec"))
+    end
+
+    it "should support a from_string class method to hash from a string buffer" do
+      Ssdeep::FuzzyHash.from_file(sample_file("ssdeep.gemspec")).should be_kind_of(Ssdeep::FuzzyHash)
+    end
+
+    it "should support a from_string class method to hash from a string buffer" do
+      Ssdeep::FuzzyHash.from_string("helu").should be_kind_of(Ssdeep::FuzzyHash)
+    end
+
+    it "should support a compare method to compare one FuzzyHash to another" do
+      fh2 = Ssdeep.hash_file(sample_file("ffi-ssdeep.gemspec"))
+      sh = Ssdeep.hash_string("helu")
+      @fh1.compare(@fh1).should == 100
+      @fh1.compare(fh2).should > 90
+      @fh1.compare(sh).should == 0
+    end
+
+    it "should raise an exception when comparing null hash data" do
+      hh = Ssdeep::FuzzyHash.new()
+      lambda{ @fh1.compare(hh)}.should raise_error(StandardError)
+      lambda{ hh.compare(@fh1)}.should raise_error(StandardError)
+    end
+  end
+
+  context "marshal serialization" do
+    before(:all) do
+      @fh = Ssdeep::FuzzyHash.from_file(sample_file("ssdeep.gemspec"))
+      @ser = Marshal.dump(@fh)
+    end
+
+    it "should be serializable with Marshal.dump()" do
+      @ser.should be_kind_of(String)
+      @ser.should_not be_empty
+      @ser.index(@fh.to_s).should_not be_nil
+    end
+
+    it "should be unserializable with Marshal.load()" do
+      fh_restore = Marshal.load(@ser)
+      fh_restore.should be_kind_of(Ssdeep::FuzzyHash)
+      fh_restore.compare(@fh).should == 100
+    end
+  end
+end

data/spec/spec.opts

@@ -0,0 +1,2 @@
+--format specdoc
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+SPEC_DIR = File.expand_path(File.dirname(__FILE__))
+
+$LOAD_PATH.unshift(SPEC_DIR)
+$LOAD_PATH.unshift(File.join(SPEC_DIR, '..', 'lib'))
+
+require 'ssdeep'
+require 'spec'
+require 'spec/autorun'
+
+SAMPLE_DIR = File.join(SPEC_DIR, 'samples')
+
+def sample_message(filename)
+  dat = File.read(sample_file(filename))
+  dat.force_encoding('ASCII-8BIT') if RUBY_VERSION >= "1.9"
+  dat
+end
+
+def sample_file(filename)
+  File.join(SAMPLE_DIR, filename)
+end
+
+Spec::Runner.configure do |config|
+end

data/spec/ssdeep_spec.rb

@@ -0,0 +1,69 @@
+require 'spec_helper'
+
+describe Ssdeep do
+
+  it "should have a compare_strings method that compares two strings" do
+    str1 = File.read(__FILE__)
+    str2 = str1.dup; str2[10,0]="insert some other junk"
+    Ssdeep.compare_strings(str1, str1).should == 100
+    Ssdeep.compare_strings(str2, str1).should < 100
+    Ssdeep.compare_strings(str2, str1).should >= 80
+    Ssdeep.compare_strings(str1, "something else").should == 0
+    Ssdeep.compare_strings(str2, "something else").should == 0
+  end
+
+  it "should have a compare_files method that compares two files" do
+    f1 = __FILE__
+    f2 = File.join(File.dirname(__FILE__), "spec_helper.rb")
+    Ssdeep.compare_files(f1, f1).should == 100
+    Ssdeep.compare_files(f1, f2 ).should < 20
+    Ssdeep.compare_files(f1, f2 ).should >= 0
+  end
+
+  it "should raise an error when compare_files is given a bad filename" do
+    f1 = __FILE__
+    f2 = sample_file("bogus_file.dat")
+    lambda{ Ssdeep.compare_files(f1,f2) }.should raise_error(StandardError)
+    lambda{ Ssdeep.compare_files(f2,f1) }.should raise_error(StandardError)
+  end
+
+  it "should have a compare_hashes method that compares two hashes" do
+    str1 = File.read(__FILE__)
+    str2 = str1.dup; str2[10,0]="insert some other junk"
+    h1 = Ssdeep::FuzzyHash.from_string(str1)
+    h2 = Ssdeep::FuzzyHash.from_string(str2)
+    h3 = Ssdeep::FuzzyHash.from_string("something_else")
+    Ssdeep.compare_hashes(h1, h1).should == 100
+    Ssdeep.compare_hashes(h2, h2).should == 100
+    Ssdeep.compare_hashes(h1, h2).should < 100
+    Ssdeep.compare_hashes(h1, h2).should >= 80
+    Ssdeep.compare_hashes(h1, h3).should == 0
+    Ssdeep.compare_hashes(h2, h3).should == 0
+  end
+
+  it "should raise an exception when compare_hashes is given a bad argument" do
+    h1 = Ssdeep::FuzzyHash.from_string("some_data")
+    lambda{ Ssdeep.compare_hashes(h1, "not a hash") }.should raise_error(TypeError)
+    lambda{ Ssdeep.compare_hashes("not a hash", h1) }.should raise_error(StandardError)
+  end
+
+  it "should have a hash_string method that generates a fuzzy hash from a string" do
+    fh = Ssdeep.hash_string("this is a test string")
+    fh.should be_kind_of Ssdeep::FuzzyHash
+    fh.to_s.should == "3:YKEpFZ2:YfrI"
+  end
+
+  it "should have a hash_file method that generates a fuzzy hash from a filename" do
+    fh = Ssdeep.hash_file(sample_file("ssdeep.gemspec"))
+    fh.should be_kind_of Ssdeep::FuzzyHash
+    fh.to_s.should == "24:ZkR5abenafgr2ph4glPlXeh/Tzj1wfgrUERNvnNyx/7/i/vA:fbenDr2ph9S/TzjvrUQvnoh/i/I"
+  end
+
+  it "should raise an error when hash_file is given a bad filename" do
+    f1 = sample_file("bogus_file.dat")
+    lambda{ Ssdeep.hash_file(f1) }.should raise_error(StandardError)
+  end
+
+
+end
+

data/tasks/ann.rake

@@ -0,0 +1,80 @@
+
+begin
+  require 'bones/smtp_tls'
+rescue LoadError
+  require 'net/smtp'
+end
+require 'time'
+
+namespace :ann do
+
+  # A prerequisites task that all other tasks depend upon
+  task :prereqs
+
+  file PROJ.ann.file do
+    ann = PROJ.ann
+    puts "Generating #{ann.file}"
+    File.open(ann.file,'w') do |fd|
+      fd.puts("#{PROJ.name} version #{PROJ.version}")
+      fd.puts("    by #{Array(PROJ.authors).first}") if PROJ.authors
+      fd.puts("    #{PROJ.url}") if PROJ.url.valid?
+      fd.puts("    (the \"#{PROJ.release_name}\" release)") if PROJ.release_name
+      fd.puts
+      fd.puts("== DESCRIPTION")
+      fd.puts
+      fd.puts(PROJ.description)
+      fd.puts
+      fd.puts(PROJ.changes.sub(%r/^.*$/, '== CHANGES'))
+      fd.puts
+      ann.paragraphs.each do |p|
+        fd.puts "== #{p.upcase}"
+        fd.puts
+        fd.puts paragraphs_of(PROJ.readme_file, p).join("\n\n")
+        fd.puts
+      end
+      fd.puts ann.text if ann.text
+    end
+  end
+
+  desc "Create an announcement file"
+  task :announcement => ['ann:prereqs', PROJ.ann.file]
+
+  desc "Send an email announcement"
+  task :email => ['ann:prereqs', PROJ.ann.file] do
+    ann = PROJ.ann
+    from = ann.email[:from] || Array(PROJ.authors).first || PROJ.email
+    to   = Array(ann.email[:to])
+
+    ### build a mail header for RFC 822
+    rfc822msg =  "From: #{from}\n"
+    rfc822msg << "To: #{to.join(',')}\n"
+    rfc822msg << "Subject: [ANN] #{PROJ.name} #{PROJ.version}"
+    rfc822msg << " (#{PROJ.release_name})" if PROJ.release_name
+    rfc822msg << "\n"
+    rfc822msg << "Date: #{Time.new.rfc822}\n"
+    rfc822msg << "Message-Id: "
+    rfc822msg << "<#{"%.8f" % Time.now.to_f}@#{ann.email[:domain]}>\n\n"
+    rfc822msg << File.read(ann.file)
+
+    params = [:server, :port, :domain, :acct, :passwd, :authtype].map do |key|
+      ann.email[key]
+    end
+
+    params[3] = PROJ.email if params[3].nil?
+
+    if params[4].nil?
+      STDOUT.write "Please enter your e-mail password (#{params[3]}): "
+      params[4] = STDIN.gets.chomp
+    end
+
+    ### send email
+    Net::SMTP.start(*params) {|smtp| smtp.sendmail(rfc822msg, from, to)}
+  end
+end  # namespace :ann
+
+desc 'Alias to ann:announcement'
+task :ann => 'ann:announcement'
+
+CLOBBER << PROJ.ann.file
+
+# EOF