russdeep 1.0.0 → 1.1.0

data/.document

@@ -1,5 +1,6 @@
 README.rdoc
 lib/**/*.rb
+ext/**/*.c
 bin/*
 features/**/*.feature
 LICENSE

data/History.txt

@@ -0,0 +1,9 @@
+== 1.1.0 / 2011-03-21
+  * Added FuzzyComparable mixin
+  * Aliass for ffi-ssdeep backward compatability
+  * Moved to rspec 2
+  * Better rdoc/yard documentation
+
+== 1.0.0 / 2011-02-20
+  * Initial version published.
+

data/Rakefile

@@ -16,6 +16,7 @@ begin
 
     if RUBY_PLATFORM !~ /java/
       gem.extensions = FileList['ext/**/extconf.rb']
+      gem.extra_rdoc_files += FileList['ext/**/*.c']
     end
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
@@ -24,18 +25,20 @@ rescue LoadError
   puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
 end
 
-require 'spec/rake/spectask'
-Spec::Rake::SpecTask.new(:spec) do |spec|
-  spec.libs << 'lib' << 'spec'
-  spec.spec_files = FileList['spec/ssdeep_spec.rb', 'spec/**/*_spec.rb'].uniq
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/ssdeep_spec.rb', 'spec/**/*_spec.rb'].uniq
 end
 
 if RUBY_PLATFORM !~ /java/
   Rake::ExtensionTask.new("ssdeep_native")
 
+  CLEAN.include("doc")
+  CLEAN.include("rdoc")
+  CLEAN.include("coverage")
+  CLEAN.include("tmp")
   CLEAN.include("lib/*.bundle")
   CLEAN.include("lib/*.so")
-  CLEAN.include("tmp")
 
   task :spec => :compile
 end
@@ -53,4 +56,9 @@ Rake::RDocTask.new do |rdoc|
   rdoc.title = "russdeep #{version}"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.include('ext/**/*.c')
 end
+
+require 'yard'
+YARD::Rake::YardocTask.new
+

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0

data/ext/ssdeep_native/ssdeep_native.c

@@ -5,6 +5,17 @@
 static VALUE module_Ssdeep = Qnil;
 static VALUE error_HashError = Qnil;
 
+/* call-seq: from_string(buf)
+ *
+ * Create a fuzzy hash from a ruby string
+ *
+ * @param  String buf   The string to hash
+ *
+ * @return String       The fuzzy hash of the string
+ *
+ * @raise HashError  
+ *   An exception is raised if the libfuzzy library encounters an error.
+ */
 VALUE ssdeep_from_string(VALUE klass, VALUE buf) {
   char hash[FUZZY_MAX_RESULT];
   int ret;
@@ -17,6 +28,17 @@ VALUE ssdeep_from_string(VALUE klass, VALUE buf) {
     rb_raise(error_HashError, "An error occurred hashing a string: ret=%i", ret);
 }
 
+/* call-seq: from_file(filename)
+ *
+ * Create a fuzzy hash from a file
+ *
+ * @param  String fielname  The file to read and hash
+ *
+ * @return String           The fuzzy hash of the file input
+ *
+ * @raise HashError  
+ *   An exception is raised if the libfuzzy library encounters an error.
+ */
 VALUE ssdeep_from_filename(VALUE klass, VALUE filename) {
   char hash[FUZZY_MAX_RESULT];
   int ret;
@@ -29,6 +51,17 @@ VALUE ssdeep_from_filename(VALUE klass, VALUE filename) {
     rb_raise(error_HashError, "An error occurred the file: %s -- ret=%i", RSTRING_PTR(filename), ret);
 }
 
+/* call-seq: from_fileno(fileno)
+ *
+ * Create a fuzzy hash from a file descriptor fileno
+ *
+ * @param  Integer fileno  The file descriptor to read and hash
+ * 
+ * @return String          The fuzzy hash of the file descriptor input
+ *
+ * @raise HashError  
+ *   An exception is raised if the libfuzzy library encounters an error.
+ */
 VALUE ssdeep_from_fileno(VALUE klass, VALUE fileno) {
   char hash[FUZZY_MAX_RESULT];
   int ret, fd;
@@ -50,6 +83,17 @@ VALUE ssdeep_from_fileno(VALUE klass, VALUE fileno) {
     rb_raise(error_HashError, "An error occurred the fileno: %i -- ret=%i", fd, ret);
 }
 
+/* call-seq: compare(sig1, sig2)
+ *
+ * Compare two hashes
+ *
+ * @param String sig1  A fuzzy hash which will be compared to sig2
+ *
+ * @param String sig2  A fuzzy hash which will be compared to sig1
+ *
+ * @return Integer
+ *   A value between 0 and 100 indicating the percentage of similarity.
+ */
 VALUE ssdeep_compare(VALUE klass, VALUE sig1, VALUE sig2) {
   int ret;
 

data/lib/ffi/ssdeep.rb

@@ -27,6 +27,14 @@ module Ssdeep
   attach_function :fdopen, [:int, :string], :pointer
 
 
+  # Create a fuzzy hash from a ruby string
+  #
+  # @param  String buf   The string to hash
+  #
+  # @return String       The fuzzy hash of the string
+  #
+  # @raise HashError  
+  #   An exception is raised if the libfuzzy library encounters an error.
   def self.from_string(buf)
     bufp = FFI::MemoryPointer.new(buf.size)
     bufp.write_string(buf)
@@ -40,6 +48,14 @@ module Ssdeep
     end
   end
 
+  # Create a fuzzy hash from a file descriptor fileno
+  #
+  # @param  Integer fileno  The file descriptor to read and hash
+  # 
+  # @return String          The fuzzy hash of the file descriptor input
+  #
+  # @raise HashError  
+  #   An exception is raised if the libfuzzy library encounters an error.
   def self.from_fileno(fileno)
     if (not fileno.kind_of?(Integer)) or (file=fdopen(fileno, "r")).null?
       raise(HashError, "Unable to open file descriptor: #{fileno}")
@@ -54,6 +70,14 @@ module Ssdeep
     end
   end
 
+  # Create a fuzzy hash from a file
+  #
+  # @param  String fielname  The file to read and hash
+  #
+  # @return String           The fuzzy hash of the file input
+  #
+  # @raise HashError  
+  #   An exception is raised if the libfuzzy library encounters an error.
   def self.from_file(filename)
     File.stat(filename)
     out = FFI::MemoryPointer.new(FUZZY_MAX_RESULT)
@@ -65,6 +89,14 @@ module Ssdeep
     end
   end
 
+  # Compare two hashes
+  #
+  # @param String sig1  A fuzzy hash which will be compared to sig2
+  #
+  # @param String sig2  A fuzzy hash which will be compared to sig1
+  #
+  # @return Integer
+  #   A value between 0 and 100 indicating the percentage of similarity.
   def self.compare(sig1, sig2)
     psig1 = FFI::MemoryPointer.from_string(sig1)
     psig2 = FFI::MemoryPointer.from_string(sig2)

data/lib/russdeep.rb

@@ -1,3 +1,48 @@
 require 'ssdeep'
 
+
+module Ssdeep
+  # The FuzzyComparable module adds mixins for doing fuzzy hash comparisons.
+  # The object extending must simply implement the 'ssdeep' method, which
+  # should return a string containing a fuzzy CTPH hash.
+  module FuzzyComparable
+    # Returns a CTPH comparison score between this object and another's
+    # fuzzy hash.
+    #
+    # @param String,Object other
+    #   The hash string or other object to compare to. If other is not
+    #   a string, it just needs to implement the 'ssdeep' method.
+    #
+    def fuzzy_score(other)
+      other_hash=
+        if other.is_a? String
+          other
+        elsif other.respond_to? :ssdeep
+          other.ssdeep
+        else
+          raise(TypeError, "can't handle type for other: #{other.class}")
+        end
+
+      Ssdeep.compare(self.ssdeep, other_hash)
+    end
+
+    # Returns true/false whether the sample matches a CTPH (fuzzy hash)
+    # with a score above a specified threshold
+    #
+    # @param String,Object other
+    #   The hash string or other object to compare to. If other is not
+    #   a string, it just needs to implement the 'ssdeep' method.
+    #
+    # @param Integer threshold
+    #   The theshold above-which a match is considered true. If a threshold
+    #   is supplied above 100, it is treated as 100.
+    #
+    # @return true,false
+    #   Whether a match occurred.
+    def fuzzy_match(other, threshold=25)
+      return (fuzzy_score(other) >= [threshold, 100].min)
+    end
+  end
+end
+
 RuSsdeep = Ssdeep

data/lib/ssdeep.rb

@@ -5,3 +5,54 @@ else
   require 'ssdeep_native'
 end
 
+module Ssdeep
+  # The FuzzyComparable module adds mixins for doing fuzzy hash comparisons.
+  # To mix in the module your object must simply implement the 'ssdeep'
+  # method, which should return a string containing a fuzzy CTPH hash.
+  module FuzzyComparable
+    # Returns a CTPH comparison score between this object and another's
+    # fuzzy hash.
+    #
+    # @param String,Object other
+    #   The hash string or other object to compare to. If other is not
+    #   a string, it just needs to implement the 'ssdeep' method.
+    #
+    def fuzzy_score(other)
+      other_hash=
+        if other.is_a? String
+          other
+        elsif other.respond_to? :ssdeep
+          other.ssdeep
+        else
+          raise(TypeError, "can't handle type for other: #{other.class}")
+        end
+
+      Ssdeep.compare(self.ssdeep, other_hash)
+    end
+
+    # Returns true/false whether the sample matches a CTPH (fuzzy hash)
+    # with a score above a specified threshold
+    #
+    # @param String,Object other
+    #   The hash string or other object to compare to. If other is not
+    #   a string, it just needs to implement the 'ssdeep' method.
+    #
+    # @param Integer threshold
+    #   The theshold above-which a match is considered true. If a threshold
+    #   is supplied above 100, it is treated as 100.
+    #
+    # @return true,false
+    #   Whether a match occurred.
+    def fuzzy_match(other, threshold=25)
+      return (fuzzy_score(other) >= [threshold, 100].min)
+    end
+  end
+
+  class << self
+    alias :hash_string :from_string
+    alias :hash_file :from_file
+    alias :hash_fileno :from_fileno
+  end
+end
+
+

data/spec/fuzzy_comparable_spec.rb

@@ -0,0 +1,21 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require 'ssdeep'
+
+class TestFuzzyComparable
+  include Ssdeep::FuzzyComparable
+
+  def ssdeep
+    '96:tQWAFF4IMtG6z4FEmYqGPUyukJM4kbqkTKL+LGw6b8f/EZMhJvybtSryfubB:tO4a68FZYqyG4w2+Bbzhpybg6u9'
+  end
+end
+
+describe Ssdeep::FuzzyComparable do
+  before :all do
+    @obj = TestFuzzyComparable.new
+  end
+
+  it "should compare itself to another fuzzy hash string" do
+    @obj.fuzzy_score(Ssdeep.from_file sample_file("sample1.txt")).should == 100
+    @obj.fuzzy_match(Ssdeep.from_file sample_file("sample1.txt")).should be_true
+  end
+end

data/spec/spec_helper.rb

@@ -1,7 +1,6 @@
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
-require 'spec'
-require 'spec/autorun'
+require 'rspec'
 require File.expand_path(File.dirname(__FILE__) + '/ssdeep_behaviors')
 
 

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 1
+  - 1
   - 0
-  - 0
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors: 
 - Eric Monti
@@ -14,13 +14,14 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-20 00:00:00 -06:00
+date: 2011-03-22 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rspec
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
@@ -35,6 +36,7 @@ dependencies:
   name: ffi
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
@@ -52,8 +54,11 @@ extensions:
 extra_rdoc_files: 
 - LICENSE
 - README.rdoc
+- ext/ssdeep_native/ssdeep_native.c
 files: 
 - .document
+- .rspec
+- History.txt
 - LICENSE
 - README.rdoc
 - Rakefile
@@ -65,9 +70,9 @@ files:
 - lib/ssdeep.rb
 - lib/ssdeep_ffi.rb
 - spec/ffi_ssdeep_spec.rb
+- spec/fuzzy_comparable_spec.rb
 - spec/samples/sample1.txt
 - spec/samples/sample2.txt
-- spec/spec.opts
 - spec/spec_helper.rb
 - spec/ssdeep_behaviors.rb
 - spec/ssdeep_spec.rb
@@ -81,6 +86,7 @@ rdoc_options: []
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
@@ -88,6 +94,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
@@ -97,12 +104,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.6
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Ruby bindings for libfuzzy (from ssdeep)
 test_files: 
 - spec/ffi_ssdeep_spec.rb
+- spec/fuzzy_comparable_spec.rb
 - spec/spec_helper.rb
 - spec/ssdeep_behaviors.rb
 - spec/ssdeep_spec.rb