ssdeep

README

SSDEEP

Golang implementation based on the paper and implementation by Jesse Kornblum.

See the example in the app directory for the usage.

Tools

For CPU profiling: apt install graphviz

For banchmark comparison go install golang.org/x/perf/cmd/benchstat@latest

Documentation

Index

• Variables
• func Distance(hash1, hash2 string) (int, error)
• func FuzzyBytes(buffer []byte) (string, error)
• func FuzzyFile(f *os.File) (string, error)
• func FuzzyFilename(filename string) (string, error)
• func FuzzyReader(f io.Reader) (string, error)
• func New() *ssdeepState
• type Hash
• type Reader

Examples

• FuzzyBytes
• FuzzyFile
• FuzzyFilename
• FuzzyReader

Variables

var (
	// ErrEmptyHash is returned when no hash string is provided for scoring.
	ErrEmptyHash = errors.New("empty string")

	// ErrInvalidFormat is returned when a hash string is malformed.
	ErrInvalidFormat = errors.New("invalid ssdeep format")
)

var (
	ErrFileTooSmall      = errors.New("did not process files large enough to produce meaningful results")
	ErrBlockSizeTooSmall = errors.New("unable to establish a sufficient block size")
	ErrZeroBlockSize     = errors.New("reached zero block size, unable to compute hash")
	ErrFileTooBig        = errors.New("input file length exceeds max processable length")
)

var (

	// Force calculates the hash on invalid input
	Force = false
)

Functions

func Distance

func Distance(hash1, hash2 string) (int, error)

Distance computes the match score between two fuzzy hash signatures. Returns a value from zero to 100 indicating the match score of the two signatures. A match score of zero indicates the signatures did not match. Returns an error when one of the inputs are not valid signatures.

func FuzzyBytes

func FuzzyBytes(buffer []byte) (string, error)

FuzzyBytes computes the fuzzy hash of a slice of byte. It is the caller's responsibility to append the filename, if any, to result after computation. Returns an error when ssdeep could not be computed on the buffer.

Example

package main

import (
	"fmt"
	"log"
	"math/rand"

	"github.com/glaslos/ssdeep"
)

func main() {
	buffer := make([]byte, 4097)
	rand.Read(buffer)
	h, err := ssdeep.FuzzyBytes(buffer)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(h)
}

func FuzzyFile

func FuzzyFile(f *os.File) (string, error)

FuzzyFile computes the fuzzy hash of a file using os.File pointer. FuzzyFile will computes the fuzzy hash of the contents of the open file, starting at the beginning of the file. When finished, the file pointer is returned to its original position. If an error occurs, the file pointer's value is undefined. It is the callers's responsibility to append the filename to the result after computation. Returns an error when ssdeep could not be computed on the file.

Example

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/glaslos/ssdeep"
)

func main() {
	f, err := os.Open("file.txt")
	if err != nil {
		log.Fatal(err)
	}
	defer f.Close()

	h, err := ssdeep.FuzzyFile(f)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(h)
}

func FuzzyFilename

func FuzzyFilename(filename string) (string, error)

FuzzyFilename computes the fuzzy hash of a file. FuzzyFilename will opens, reads, and hashes the contents of the file 'filename'. It is the caller's responsibility to append the filename to the result after computation. Returns an error when the file doesn't exist or ssdeep could not be computed on the file.

Example

package main

import (
	"fmt"
	"log"

	"github.com/glaslos/ssdeep"
)

func main() {
	h, err := ssdeep.FuzzyFilename("file.txt")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(h)
}

func FuzzyReader

func FuzzyReader(f io.Reader) (string, error)

FuzzyReader computes the fuzzy hash of a Reader interface with a given input size. It is the caller's responsibility to append the filename, if any, to result after computation. Returns an error when ssdeep could not be computed on the Reader.

Example

package main

import (
	"bytes"
	"fmt"
	"log"
	"math/rand"

	"github.com/glaslos/ssdeep"
)

func main() {
	buffer := make([]byte, 4097)
	rand.Read(buffer)
	h, err := ssdeep.FuzzyReader(bytes.NewReader(buffer))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(h)
}

func New

func New() *ssdeepState

New instance of the SSDEEP hash

Types

type Hash

type Hash interface {
	io.Writer
	Sum(b []byte) []byte
}

type Reader

type Reader interface {
	io.Seeker
	io.Reader
}

Reader is the minimum interface that ssdeep needs in order to calculate the fuzzy hash. Reader groups io.Seeker and io.Reader.