1PYTHONSSDEEP(1)                  python-ssdeep                 PYTHONSSDEEP(1)
2
3
4

NAME

6       pythonssdeep - Python ssdeep Documentation
7
8       This  is a straightforward Python wrapper for ssdeep by Jesse Kornblum,
9       which is a library for computing  context  triggered  piecewise  hashes
10       (CTPH).  Also  called fuzzy hashes, CTPH can match inputs that have ho‐
11       mologies. Such inputs have sequences of identical bytes in the same or‐
12       der, although bytes in between these sequences may be different in both
13       content and length.
14
15       You can install python-ssdeep with pip:
16
17          $ pip install ssdeep
18
19       See Installation for more information.
20
21       Contents:
22

INSTALLATION

24   Requirements
25       • Python
26
27         • Python 2.6, 2.7
28
29         • Python >= 3.2
30
31         • PyPy >= 2.0
32
33       • ssdeep/libfuzzy >= 2.10 (Some features might not  be  available  with
34         older versions. See ssdeep.Hash)
35
36       • cffi
37
38       • pip
39
40       • six
41
42   Install on CentOS 7
43   Python 2
44       Use included ssdeep lib
45
46       Install required packages.
47
48          $ sudo yum groupinstall "Development Tools"
49          $ sudo yum install epel-release
50          $ sudo yum install libffi-devel python-devel python-pip automake autoconf libtool
51
52       Build and install Python module.
53
54          $ sudo BUILD_LIB=1 pip install ssdeep
55
56       Use lib from epel
57
58       Install required packages.
59
60          $ sudo yum groupinstall "Development Tools"
61          $ sudo yum install epel-release
62          $ sudo yum install libffi-devel python-devel python-pip ssdeep-devel ssdeep-libs
63
64       Build and install Python module.
65
66          $ sudo pip install ssdeep
67
68   Install on Debian 7
69   Python 2
70       Use included ssdeep lib
71
72       Install required packages.
73
74          $ sudo apt-get install build-essential libffi-dev python python-dev python-pip automake autoconf libtool
75
76       Build and install Python module.
77
78          $ sudo BUILD_LIB=1 pip install ssdeep
79
80   Python 3
81       Use included ssdeep lib
82
83       Install required packages.
84
85          $ sudo apt-get install build-essential libffi-dev python3 python3-dev python3-pip automake autoconf libtool
86
87       Build and install Python module.
88
89          $ sudo BUILD_LIB=1 pip install ssdeep
90
91   Install on Debian 8/9
92   Python 2
93       Use included ssdeep lib
94
95       Install required packages.
96
97          $ sudo apt-get install build-essential libffi-dev python python-dev python-pip automake autoconf libtool
98
99       Build and install Python module.
100
101          $ sudo BUILD_LIB=1 pip install ssdeep
102
103       Use ssdeep from Debian repository
104
105       Install required packages.
106
107          $ sudo apt-get install build-essential libffi-dev python python-dev python-pip libfuzzy-dev
108
109       Build and install Python module.
110
111          $ sudo pip install ssdeep
112
113   Python 3
114       Use included ssdeep lib
115
116       Install required packages.
117
118          $ sudo apt-get install build-essential libffi-dev python3 python3-dev python3-pip automake autoconf libtool
119
120       Build and install Python module.
121
122          $ sudo BUILD_LIB=1 pip3 install ssdeep
123
124       Use ssdeep from Debian repository
125
126       Install required packages.
127
128          $ sudo apt-get install build-essential libffi-dev python3 python3-dev python3-pip libfuzzy-dev
129
130       Build and install Python module.
131
132          $ sudo pip3 install ssdeep
133
134   Install on Ubuntu 12.04
135   Python 2
136       Use included ssdeep lib
137
138       Install required packages.
139
140          $ sudo apt-get install build-essential libffi-dev python python-dev python-pip automake autoconf libtool
141
142       Build and install Python module.
143
144          $ sudo BUILD_LIB=1 pip install ssdeep
145
146   Python 3
147       Use included ssdeep lib
148
149       Install required packages.
150
151          $ sudo apt-get install build-essential libffi-dev python3 python3-dev python3-setuptools automake autoconf libtool
152
153       Build and install Python module.
154
155          $ sudo easy_install3 pip
156          $ sudo BUILD_LIB=1 pip3 install ssdeep
157
158   Install on Ubuntu 14.04
159   Python 2
160       Use included ssdeep lib
161
162       Install required packages.
163
164          $ sudo apt-get install build-essential libffi-dev python python-dev python-pip automake autoconf libtool
165
166       Build and install Python module.
167
168          $ sudo BUILD_LIB=1 pip install ssdeep
169
170   Python 3
171       Use included ssdeep lib
172
173       Install required packages.
174
175          $ sudo apt-get install build-essential libffi-dev python3 python3-dev python3-pip automake autoconf libtool
176
177       Build and install Python module.
178
179          $ sudo BUILD_LIB=1 pip3 install ssdeep
180
181   Install on Ubuntu 16.04
182   Python 2
183       Use lib from official Ubuntu repository (recommended)
184
185       Install required packages.
186
187          $ sudo apt-get install build-essential libffi-dev python python-dev python-pip libfuzzy-dev
188
189       Build and install Python module.
190
191          $ pip install ssdeep
192
193       Use included ssdeep lib
194
195       Install required packages.
196
197          $ sudo apt-get install build-essential libffi-dev python python-dev python-pip automake autoconf libtool
198
199       Build and install Python module.
200
201          $ BUILD_LIB=1 pip install ssdeep
202
203   Python 3
204       Use lib from official Ubuntu repository (recommended)
205
206       Install required packages.
207
208          $ sudo apt-get install build-essential libffi-dev python3 python3-dev python3-pip libfuzzy-dev
209
210       Build and install Python module.
211
212          $ pip3 install ssdeep
213
214       Use included ssdeep lib
215
216       Install required packages.
217
218          $ sudo apt-get install build-essential libffi-dev python3 python3-dev python3-pip automake autoconf libtool
219
220       Build and install Python module.
221
222          $ BUILD_LIB=1 pip3 install ssdeep
223
224   Install on Fedora 27
225   Python 2
226       Use lib from Fedora repository
227
228       Install required packages.
229
230          $ sudo dnf groupinstall "Development Tools"
231          $ sudo dnf install libffi-devel python-devel python-pip ssdeep-devel ssdeep-libs
232
233       Build and install Python module.
234
235          $ sudo pip install ssdeep
236
237   Python 3
238       Use lib from Fedora repository
239
240       Install required packages.
241
242          $ sudo dnf groupinstall "Development Tools"
243          $ sudo dnf install libffi-devel python3-devel python3-pip ssdeep-devel ssdeep-libs
244
245       Build and install Python module.
246
247          $ sudo pip3 install ssdeep
248

USAGE

250       Import the required module.
251
252          >>> import ssdeep
253
254       Use the ssdeep.hash() function to compute a fuzzy hash.
255
256          >>> hash1 = ssdeep.hash('Also called fuzzy hashes, Ctph can match inputs that have homologies.')
257          >>> hash1
258          '3:AXGBicFlgVNhBGcL6wCrFQEv:AXGHsNhxLsr2C'
259          >>> hash2 = ssdeep.hash('Also called fuzzy hashes, CTPH can match inputs that have homologies.')
260          >>> hash2
261          '3:AXGBicFlIHBGcL6wCrFQEv:AXGH6xLsr2C'
262
263       The  ssdeep.compare()  function  returns the match score of two hashes.
264       The score is an integer value from 0 (no match) to 100.
265
266          >>> ssdeep.compare(hash1, hash2)
267          22
268
269       The ssdeep.hash_from_file() function accepts a filename as argument and
270       calculates the hash of the contents of the file.
271
272          >>> ssdeep.hash_from_file('/etc/resolv.conf')
273          '3:S3yE29cFrrMOoiECAaHJgvn:S3m+COoiUCuvn'
274
275       The ssdeep.Hash class provides a hashlib like interface.
276
277          >>> h = ssdeep.Hash()
278          >>> h.update('Also called fuzzy hashes, ')
279          >>> h.digest()
280          '3:AXGBicFlF:AXGHR'
281          >>> h.update('Ctph can match inputs that have homologies.')
282          >>> h.digest()
283          '3:AXGBicFlgVNhBGcL6wCrFQEv:AXGHsNhxLsr2C'
284

API REFERENCE

286   Classes
287       class ssdeep.Hash
288              Hashlib  like  object. It is only supported with ssdeep/libfuzzy
289              >= 2.10.
290
291              Raises
292
293                     • InternalError -- If lib returns internal error
294
295                     • NotImplementedError  --  Required  functions  are   not
296                       available
297
298              property block_size
299                     The  block size used to calculate the hash.  This depends
300                     on the length of the source string.
301
302                     Returns
303                            block size
304
305              copy() Create a copy of this hash object.
306
307                     Returns
308                            Return a copy of the hash object.
309
310                     Return type
311                            Hash
312
313                     Raises InternalError -- If the lib  returns  an  internal
314                            error
315
316              digest(elimseq=False, notrunc=False)
317                     Obtain the fuzzy hash.
318
319                     This  operation  does not change the state at all. It re‐
320                     ports the hash for the concatenation of the  data  previ‐
321                     ously fed using update().
322
323                     Returns
324                            The fuzzy hash
325
326                     Return type
327                            String
328
329                     Raises InternalError -- If lib returns an internal error
330
331              property name
332                     The canonical name of this hash
333
334                     Returns
335                            ssdeep
336
337              update(buf, encoding='utf-8')
338                        Feed  the  data  contained  in the given buffer to the
339                        state.
340
341                     Parameters
342
343                            • buf (String|Byte) -- The data to be hashed
344
345                            • encoding (String) -- Encoding is used if buf  is
346                              String
347
348                     Raises
349
350                            • InternalError  -- If lib returns an internal er‐
351                              ror
352
353                            • TypeError -- If buf is not Bytes, String or Uni‐
354                              code
355
356       class ssdeep.PseudoHash
357              Hashlib  like  object.  Use this class only if Hash() isn't sup‐
358              ported by your ssdeep/libfuzzy library. This  class  stores  the
359              provided data in memory, so be careful when hashing large files.
360
361              property block_size
362                     The  block size used to calculate the hash.  This depends
363                     on the length of the source string.
364
365                     Returns
366                            block size
367
368              copy() Create a copy of this hash object.
369
370                     Returns
371                            Return a copy of the hash object.
372
373                     Return type
374                            PseudoHash
375
376                     Raises InternalError -- If the lib  returns  an  internal
377                            error
378
379              digest(elimseq=False, notrunc=False)
380                     Obtain the fuzzy hash.
381
382                     This  operation  does not change the state at all. It re‐
383                     ports the hash for the concatenation of the  data  previ‐
384                     ously fed using update().
385
386                     Returns
387                            The fuzzy hash
388
389                     Return type
390                            String
391
392              property name
393                     The canonical name of this hash
394
395                     Returns
396                            ssdeep
397
398              update(buf, encoding='utf-8')
399                        Feed  the  data  contained  in the given buffer to the
400                        state.
401
402                     Parameters
403
404                            • buf (String|Byte) -- The data to be hashed
405
406                            • encoding (String) -- Encoding is used if buf  is
407                              String
408
409                     Raises TypeError  --  If buf is not Bytes, String or Uni‐
410                            code
411
412   Functions
413       ssdeep.compare(sig1, sig2)
414              Computes the match score between two fuzzy hash signatures.
415
416              Returns a value from zero to 100 indicating the match  score  of
417              the  two  signatures. A match score of zero indicates the signa‐
418              tures did not match.
419
420              Parameters
421
422                     • sig1 (Bytes|String) -- First fuzzy hash signature
423
424                     • sig2 (Bytes|String) -- Second fuzzy hash signature
425
426              Returns
427                     Match score (0-100)
428
429              Return type
430                     Integer
431
432              Raises
433
434                     • InternalError -- If lib returns an internal error
435
436                     • TypeError -- If sig is not String, Unicode or Bytes
437
438       ssdeep.hash(buf, encoding='utf-8')
439              Compute the fuzzy hash of a buffer
440
441              Parameters
442                     buf (String|Bytes) -- The data to be fuzzy hashed
443
444              Returns
445                     The fuzzy hash
446
447              Return type
448                     String
449
450              Raises
451
452                     • InternalError -- If lib returns an internal error
453
454                     • TypeError -- If buf is not String or Bytes
455
456       ssdeep.hash_from_file(filename)
457              Compute the fuzzy hash of a file.
458
459              Opens, reads, and hashes the contents of the file 'filename'
460
461              Parameters
462                     filename (String|Bytes) -- The name of  the  file  to  be
463                     hashed
464
465              Returns
466                     The fuzzy hash of the file
467
468              Return type
469                     String
470
471              Raises
472
473                     • IOError -- If Python is unable to read the file
474
475                     • InternalError -- If lib returns an internal error
476
477   Exceptions
478       exception ssdeep.BaseError
479              The base for all other Exceptions
480
481       exception ssdeep.InternalError
482              Raised if lib returns internal error
483

FAQ

485       If comparing two hashes the result is always 0
486
487       The  result  depends on the algorithms in the ssdeep library. There are
488       some issues if the length of provided data is too short or if the algo‐
489       rithm could not find enough patterns.
490
491       The following example must not return the expected value.
492
493          >>> hash1 = ssdeep.hash('foo' * 4096)
494          >>> hash2 = ssdeep.hash('foo' * 4096)
495          >>> ssdeep.compare(hash1, hash2)
496          0
497

CONTRIBUTING

499       First  of  all,  thank  you  for  your interest in contributing to this
500       project!
501
502   Filing bug reports
503       Bug reports are very welcome.  Please file them  on  the  GitHub  issue
504       tracker.   Good bug reports come with extensive descriptions of the er‐
505       ror and how to reproduce it.  Try to use the provided  issue  template,
506       it should be displayed by the GitHub website when creating a new issue.
507
508   Patches
509       All  patches  should  be  submitted in the form of pull requests to the
510       main repository, DinoTools/python-ssdeep.  These pull  requests  should
511       satisfy the following properties:
512
513   Code
514       • A pull request should focus on one particular improvement or change.
515
516       • Create different pull requests for unrelated features or bugfixes.
517
518       • Python  code  should  follow  PEP  8, especially in the "do what code
519         around you does" sense.
520
521       • Add test if possible
522
523   Documentation
524       When introducing new functionality, please remember to write documenta‐
525       tion.
526
527   Review
528       Finally,  pull  requests must be reviewed before merging.  Everyone can
529       perform reviews; this is a very valuable  way  to  contribute,  and  is
530       highly encouraged.
531

CHANGELOG

533   3.x (master)
534       NOTE:
535          This version is not yet released and is under development.
536
537   3.4 (2019-10-01)
538       • Update documentation
539
540       • Replace Jenkins and Travis CI with Drone CI
541
542       • Add new copy() function to Hash() and PseudoHash() class
543
544       • Add  new  attributes  to  Hash()  and  PseudoHash()  class  *  name *
545         block_size
546
547   3.3 (2018-01-10)
548       • Update ssdeep lib to 2.14.1
549
550       • Fix issues with Travis CI
551
552       • Add additional CI test with Python 3.6
553
554       • Build docs during CI builds
555
556       • Remove deprecated PKGBUILD
557
558   3.2 (2016-11-27)
559       • Update ssdeep lib to 2.13(thanks to Charles Lindsay)
560
561       • Update install instructions
562
563       • Add additional CI tests on CentOS 7, Debian 8 and Ubuntu 14.04/16.04
564
565   3.1.1 (2014-12-20)
566       • Updated ssdeep lib to 2.12
567
568       • Added additional tests
569
570       • Fixed build issues on Windows(thanks to Paul Chaignon)
571
572       • Added option to run tests with PyPy3
573
574       • Fixed build to prevent automake version missmatch errors
575
576       • Updated documentation
577
578   3.1 (2014-08-07)
579       • Fix build issue with ssdeep < 2.10
580
581   3.0 (2014-06-25)
582       • Completely rewritten to use CFFI
583
584       • Interface in the spirit of hashlib
585
586       • Use pytest and tox for tests
587
588       • Use installed fuzzy lib by default
589
590   2.9-0.3 (2013-03-12)
591       • Fix build issue with Python 2.6
592
593   2.9-0.2 (2012-10-11)
594       • Fixing small bug in setup.py
595
596   2.9-0.1 (2012-08-01)
597       • Updated ssdeep from 2.5 to 2.9
598
599       • Added Python 3.x support
600
601   2.5 (2010-09-03)
602       • Initial release
603
604       • The initial version was published in 2010 by Denis  Bilenko  on  bit‐
605         bucket.
606
607       • Since 2012 the source is maintained by PhiBo (DinoTools) and has been
608         published on github.
609
610       • In 2014 the wrapper has been rewritten to use cffi.
611
612       • Index
613
614       • Module Index
615
616       • Search Page
617

AUTHOR

619       DinoTools
620

622       2014-2022, DinoTools
623
624
625
626
6273.4                              Jul 22, 2022                  PYTHONSSDEEP(1)
Impressum