tlsh 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 63d010fbc4b52053c4fea41c1daa49b7cbea5497
-  data.tar.gz: 3cdb12427e32dfea9846b4875330813848cf9386
+  metadata.gz: d43f01d277be3365206f071a36702940b7a5eb71
+  data.tar.gz: e41e735d37604cc3b59c6b7dded2a7dc0778198a
 SHA512:
-  metadata.gz: 803eb60a056ffd9ae91e1ce4aff7735e343ba2cf6d48359c01408975adcd8bf5cfa47092028e4014773e53fee103d06cf5ae7fc729e9fc43b32b546f812a7efb
-  data.tar.gz: 288c09c4bdcd5f9e5655f9ef2fc488d5bbe87e6724f1583e7f373bf9a0980eb4b1715dd4e70b3baa7a6810e0a955376386929f49ac5620a0c5da9417bc616a0d
+  metadata.gz: de6fba2a615128e8f9a76d5b0154a9253d69b7506d91370ee6c4dd9f85601dd547aa708a103ed95bb6226dadd92de40231566f4989c5668fc0a5e9074d3ba925
+  data.tar.gz: 6c4f65dc62069aad940f25b155dfe9603c7536131c9e8f33cdc8248f8076b130df1ac0298504faceb9841cbbbd933c03d20f00734dc7f320d92f3f1b33c9931d

data/CONTRIBUTING.md

@@ -0,0 +1,14 @@
+## Contributing
+
+1. Fork the repo.
+2. Run the tests. We only take pull requests with passing tests, and it's great to know that you have a clean slate.
+3. Add a test for your change. Only refactoring and documentation changes require no new tests. If you are adding functionality or fixing a bug, we need a test.
+4. Make the test pass.
+5. Push to your fork and submit a pull request.
+
+Some things that will increase the chance that your pull request is accepted,
+
+* Include tests that fail without your code, and pass with it
+* Update the documentation, the surrounding one, examples elsewhere, guides, whatever is affected by your contribution
+* Follow the existing style of the project
+

data/README.md

@@ -1,3 +1,4 @@
+[![Gem Version](https://badge.fury.io/rb/tlsh.svg)](https://badge.fury.io/rb/tlsh)
 [![Build Status](https://travis-ci.org/adamliesko/tlsh.svg?branch=master)](https://travis-ci.org/adamliesko/tlsh)
 [![Coverage Status](https://coveralls.io/repos/github/adamliesko/tlsh/badge.svg?branch=master)](https://coveralls.io/github/adamliesko/tlsh?branch=master)
 
@@ -10,14 +11,6 @@ The computed hash is 35 bytes long (output as 70 hexadecimal characters). The fi
 DISCLAIMER: Based on [Trendmicro's TLSH](https://github.com/trendmicro/tlsh) and work of [glaslos](https://github.com/glaslos) Go port [tlsh](https://github.com/glaslos/tlsh).
 ## Installation
 
-Add this line to your application's Gemfile and execute bundler:
-
-```ruby
-gem 'tlsh' && bundle
-```
-
-Or install it yourself as:
-
     $ gem install tlsh
 
 ## Usage

data/lib/tlsh.rb

@@ -1,6 +1,7 @@
 require 'tlsh/digest_hash/pearson'
 require 'tlsh/distance/distance'
 require 'tlsh/distance/precomputed_bits'
+require 'tlsh/errors'
 require 'tlsh/buckets'
 require 'tlsh/quartiles'
 require 'tlsh/tlsh'

data/lib/tlsh/digest_hash/pearson.rb

@@ -20,6 +20,9 @@ module DigestHash
              51, 65, 28, 144, 254, 221, 93, 189, 194, 139, 112, 43, 71, 109, 184, 209].freeze
 
     def pearson_hash(salt, keys)
+      raise Tlsh::MalformedInputError, 'Missing keys for pearson_hash' if keys.nil? || keys.empty?
+      raise Tlsh::MalformedInputError, 'Missing salt for pearson_hash' if salt.nil?
+
       h = 0
       h = TABLE[h ^ salt]
       h = TABLE[h ^ keys[0]]

data/lib/tlsh/errors.rb

@@ -0,0 +1,7 @@
+module Tlsh
+  class MalformedInputError < StandardError
+  end
+
+  class InputTooSmallError < StandardError
+  end
+end

data/lib/tlsh/tlsh.rb

@@ -10,6 +10,11 @@ module Tlsh
   LOG1_1 = 0.095310180
 
   class << self
+    ##
+    # Computes TLSH based diff between two files.
+    #
+    # The closer to 0, the smaller the diff. If files are not found, error is raised.
+
     def diff_files(filename, other_filename)
       file_a = File.read(filename)
       file_b = File.read(other_filename)
@@ -19,12 +24,19 @@ module Tlsh
       tslh_a.diff(tslh_b)
     end
 
-    # hash_file calculates the TLSH for the input file
+    ##
+    # Computes TLSH based diff between two files.
+    #
+    # The closer to 0, the smaller the diff. If files are not found, error is raised.
+
     def hash_file(filename)
       file = File.read(filename)
       tlsh_hash(file.bytes)
     end
 
+    ##
+    # Computes TLSH of an bytes input.
+
     def hash_bytes(blob)
       tlsh_hash(blob)
     end
@@ -32,6 +44,7 @@ module Tlsh
     private
 
     def tlsh_hash(input)
+      raise Tlsh::InputTooSmallError if input.size < 256
       buckets, checksum, filesize = Buckets.fill_buckets(input)
 
       # get the quartiles and their ratio

data/lib/tlsh/tlsh_instance.rb

@@ -1,8 +1,11 @@
 module Tlsh
-  # TlshInstance represents single TLSH instance
+  # TlshInstance represents single TLSH instance.
   class TlshInstance
     attr_accessor :checksum, :l_value, :q1_ratio, :q2_ratio, :q_ratio, :body
 
+    ##
+    # Creates new instance of TlshInstance from the named arguments.
+
     def initialize(params = {})
       params.each do |key, value|
         setter = "#{key}="
@@ -10,17 +13,29 @@ module Tlsh
       end
     end
 
-    # returns diff against another TlshInstance. The closer to 0, the smaller the diff.
+    ##
+    # Returns diff (or similarity) against another TlshInstance.
+    #
+    # The closer to 0, the smaller the diff. Both instances have to be comparable for comparison. If not, -1 is returned.
+
     def diff(other)
       Distance.diff_total(self, other, true)
     end
 
-    # returns the binary representation of the hash
+    ##
+    # Returns the binary representation of the TLSH hash.
+    #
+    # It's constructed as a concatenation of hash metadata and body,
+
     def binary
       [swap_byte(checksum), swap_byte(l_value), q_ratio] + body
     end
 
-    # returns the string representation of the hash
+    ##
+    # Returns the string representation of the TLSH hash.
+    #
+    # It's constructed from the binary representation of the hash, converted to hex
+
     def string
       binary.map { |i| i.to_i.to_s(16) }.join('')
     end

data/lib/tlsh/version.rb

@@ -1,3 +1,3 @@
 module Tlsh
-  VERSION = '0.1.1'.freeze
+  VERSION = '0.1.3'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tlsh
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - adamliesko
@@ -99,6 +99,7 @@ files:
 - ".rubocop.yml"
 - ".travis.yml"
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -110,6 +111,7 @@ files:
 - lib/tlsh/digest_hash/pearson.rb
 - lib/tlsh/distance/distance.rb
 - lib/tlsh/distance/precomputed_bits.rb
+- lib/tlsh/errors.rb
 - lib/tlsh/quartiles.rb
 - lib/tlsh/tlsh.rb
 - lib/tlsh/tlsh_instance.rb