Fingerprint¶

blotter Module¶

class FingerPrint.blotter.Blotter(name, fileList, processIDs, execCmd)[source]¶

This class creates a swirl file starting from:

• a list of binaries
• command lines that we want to execute and trace
• a list of pids

Parameters:

name (string) – a internal simbolic name for this swirl fileList (list) – a list of string containing aboslute or relative paths to the file that should be included in this Swirl for static analysis processIDs (string) – a list of comma separated PID which should be dynamically traced by this swirl execCmd (string) – a command line which should be launched and dynamically traced to create a swirl.

getSwirl()[source]¶

return the current swirl

Return type:	FingerPrint.swirl.Swirl
Returns:	return the current Swirl

composer Module¶

class FingerPrint.composer.Archiver(sergeant, archive_filename)[source]¶

Given an already created swirl it creates a Swirl archive

Parameters:	sergeant (FingerPrint.sergeant.Sergeant) – An instance of sergenat class pointing to the swirl we want to archive archive_filename (string) – string containing the output file name for the archive

archive()[source]¶

It triggers the creation of the archive.

Return type:	bool
Returns:	it returns false in case of failure

class FingerPrint.composer.Roller(archive_filename, roll_name)[source]¶

this class make a roll out of an fingerprint archive

Parameters:	archive_filename (string) – a path to the Swirl Archive file roll_name (string) – the name of the roll that we want to create

make_roll(fingerprint_base_path, use_remapping=False)[source]¶

It creates a roll from a swirl archive.

Parameters:	fingerprint_base_path (string) – a string pointing to the base path of the fingerprint source code. Used to find the remapper source code use_remapping (bool) – if True it will use the remapper technology when creating the roll
Return type:	bool
Returns:	it returns false in case of failure

FingerPrint.composer.is_special_file(path)[source]¶

Parameters:	path (string) – a path to a file
Return type:	bool
Returns:	it returns true if the path points to a file which contains personal data

FingerPrint.composer.make_mapping_file(sw_files, output_file, base_path)[source]¶

this function makes a mapping file for the remapper process

sergeant Module¶

class FingerPrint.sergeant.Sergeant(swirl, extraPath=[])[source]¶

Given an already existent Swirl:

• it detects if it can run on this system (check())
• it detects what has been changed (checkHash())
• print this swirl on the screen (print_swirl())
• print this swirl as a dot file for Graphviz (getDotFile())

Parameters:	swirl (FingerPrint.swirl.Swirl) – The Swirl that we want to test extraPath (list) – a list of string containing system path which should be included in the search of dependencies

check()[source]¶

It performs the check on the system and verifies that all the dependencies of this Swirl can be satisfied.

Return type:	bool
Returns:	True if the check passes False otherwise. The list of missing dependencies can be retrieved with getError()

checkDependencyPath(fileName)[source]¶

it returns a list of SwirlFiles which requires the given fileName, if the given file is not required in this swirl it returns an empty list []

Parameters:	fileName (string) – a path to a file
Return type:	list
Returns:	a list of FingerPrint.swirl.SwirlFile required by the fileName

checkHash(verbose=False)[source]¶

It checks if any dependency was modified since the swirl file creation (using checksumming)

Parameters:	verbose (bool) – if True it will generate more verbose error message
Return type:	bool
Returns:	True if the check passes False otherwise. The list of modified dependencies can be retrieved with :meth:getError()

getDotFile()[source]¶

return a dot representation of this swirl

Return type:	string
Returns:	a string with the dot representation of this swirl

getError()[source]¶

After running check or checkHash it return a list of the problems found

Return type:	list
Returns:	a lit of strings with all the problems encountered

getSwirl()[source]¶

return the current swirl

Return type:	FingerPrint.swirl.Swirl
Returns:	the current swirl

print_swirl(verbosity)[source]¶

return a string with the representation of this swirl

Parameters:	verbosity (int) – various verbosity level see FingerPrint.swirl.Swirl.printVerbose()
Return type:	string
Returns:	a human readable representation of this Swirl

searchModules()[source]¶

It searches for missing dependencies using the ‘module’ command line. check() should be called before this

Return type:	string
Returns:	with a human readable list of module which can satisfy missing dependencies

setExtraPath(path)[source]¶

These paths will be added to the search list when looking for dependency, they overwrite the extraPath passed at the constructor

Parameters:	path (string) – a string containing a list of path separated by :

setFilename(filename)[source]¶

TODO remove this function

FingerPrint.sergeant.getHash(fileName, fileType)[source]¶

It return a md5 checksum of the given file name. If we are running on a system which prelink binaries (aka RedHat based) the command prelink must be on the PATH

Parameters:	fileName (string) – a path to the file which we want to checksum fileType (string) – the file type (the only recognized value is EFL for triggering the prelink on RHEL base system)
Return type:	string
Returns:	an hexdadeciaml representation of the md5sum checksum

FingerPrint.sergeant.getShortPath(path)[source]¶

Given a full path it shorten it leaving only /bin/../filename

Parameters:	path (string) – a long absolute path to the file
Return type:	string
Returns:	the shortened path

FingerPrint.sergeant.is_special_folder(path)[source]¶

return true if path is to be considered special, which means it should be skipped from archivingi, checksumming, etc.

Parameters:	path (string) – an absolute path to the file
Return type:	bool
Returns:	True if the given path is special

FingerPrint.sergeant.readFromPickle(fileName)[source]¶

helper function to get a swirl from a filename

Parameters:	fileName (string) – a relative or absolute path to the file to read
Return type:	FingerPrint.swirl.Swirl
Returns:	the Swirl read from the file

serializer Module¶

class FingerPrint.serializer.PickleSerializer(fd)[source]¶

this class serialize a swirl into a pickle file format

Parameters:	fd (file) – the file descritor to be used for serialization or deserialization

load()[source]¶

Return the Swirl read from the given file descriptor

Return type:	FingerPrint.swirl.Swirl
Returns:	the Swirl read from fd

save(swirl)[source]¶

Saves the given swirl to the file descriptor

Parameters:	swirl (FingerPrint.swirl.Swirl) – the Swirl to be serialized

class FingerPrint.serializer.XmlSerializer(fd)[source]¶

this serilizes the swirl into xml we can have multiple classes for serializing in other format. TODO it doesnot work. Unused at the moment.

read()[source]¶

this should implement the read from xml

save(swirl)[source]¶

save_depset(dependencySet)[source]¶

swirl Module¶

class FingerPrint.swirl.Arch[source]¶

old style classes for backward compability

is32bits()[source]¶

is64bits()[source]¶

set32bits()[source]¶

set 32 bit architecture

set64bits()[source]¶

set 64 bit architecture

class FingerPrint.swirl.Dependency(major, minor=None, hwcap=None)[source]¶

Bases: FingerPrint.swirl.Arch

this class reperesent a dependency declarations, it can be used to represent either a dependency or a provides in a swirlFile. It is an abstract representation of a shared library as used inside the POSIX loader.

Parameters:	major (string) – it is the ‘soname’ of this dependency (e.g. libc.so.6, libacl.so.1, ...) minor (string) – it is an entry in the version symbol table (e.g. GLIBC_2.11, GLIBC_2.12, etc.) hwcap (string) – it stores special hardware capabilities (like sse3 or avx) this is a feature of the linux linker to support different instruction set

classmethod fromString(string)[source]¶

Create a dependency from a string returned by find-require find-provide

Parameters:	string (string) – a line of output from the FingerPrint/plugin/find-requires or FingerPrint/plugin/find-provides
Return type:	FingerPrint.swirl.Dependency
Returns:	a new instance of Dependency which represent the given input string

getMajor()[source]¶

Return type:	string
Returns:	the major of this dependency

getMinor()[source]¶

Return type:	string
Returns:	the minor of this dependency

getName()[source]¶

return a string representation of this dependency which is the same format used by the find-require find-provides (e.g. soname(minor_version)(arch)

Return type:	string
Returns:	a representation of this Dependency

isLoader()[source]¶

return true if this is the loader

Return type:	bool
Returns:	true if this dependency is a loader

class FingerPrint.swirl.Swirl(name, creationDate)[source]¶

Bases: object

Swirl hold in memory the representation of a swirl. It is made of a list of SwirlFiles aka files tracked by this swirl. There is one instance of this class for each fingerprint process.

Parameters:	name (string) – a internal simbolic name for this swirl creationDate (datetime.datetime) – the creation time of this Swirl

createSwirlFile(fileName)[source]¶

given a fileName it return the associated swirlFile if present otherwise it creates a new one with all the symlinks resolved

Parameters:	fileName (string) – the path of the file to add to this swirl
Return type:	FingerPrint.swirl.SwirlFile
Returns:	a SwirlFile for the given fileName

getDateString()[source]¶

return the creation time in a readable format

Return type:	string
Returns:	a string with the representation of the creation time of this swirl

getDependencies()[source]¶

return a list with all the dependencies in this swirl

Return type:	list
Returns:	a list of FingerPrint.swirl.Dependency which are needed inside by all the binaries inside this Swirl

getListSwirlFileProvide(dependencies, excludeSwirlFile=[])[source]¶

return a list of FingerPrint.swirl.SwirlFile from the current Swirl which can satisfy the given list of dependencies

This function does not find recursive dependencies like getListSwirlFilesDependentStatic and getListSwirlFilesDependentStaticAndDynamic

Parameters:	dependencies (list) – a list of FingerPrint.swirl.Dependency exludeSwirlFile (list) – a list of FingerPrint.swirl.SwirlFile which should be excluded from the returned list
Return type:	list
Returns:	a list of FingerPrint.swirl.SwirlFile which can satisfy the list of dependencies

getListSwirlFilesDependentStatic(swirlFile)[source]¶

Given a swirlFile it return a list of all the recursively required dependent swirlFiles (only static).

It _recursively_ find all the required swirlFile invoking getListSwirlFile until all dependencies and dependencies of dependencies are resolved (when the loader start program ‘a’ which depend on lib ‘b’ which in its turn depends on lib ‘c’, the loader will load a, b, and c at the same time).

Parameters:	swirlFile (FingerPrint.swirl.SwirlFile) – a swirlFile which is part of this Swirl
Return type:	list
Returns:	a list of FingerPrint.swirl.SwirlFile which are all the static dependencies of the input swirlFile

getListSwirlFilesDependentStaticAndDynamic(swirlFile)[source]¶

Given a swirlFile it returns a list of all its required swirlfiles. It includes both static recursive and dynamic dependencies

Parameters:	swirlFile (FingerPrint.swirl.SwirlFile) – a swirlFile which is part of this Swirl
Return type:	list
Returns:	a list of FingerPrint.swirl.SwirlFile which are all the dependencies of the input swirlFile

getLoader(swirlFile)[source]¶

return a swirlfile which is the loader of the given swirlFile

Parameters:	swirlFile (FingerPrint.swirl.SwirlFile) – a swirlFile which is part of this Swirl
Return type:	FingerPrint.swirl.SwirlFile
Returns:	a SwirlFile which is the loader of the input swirlFile or None in case the input swirlFile is static

getSwirlFileByProv(dependency)[source]¶

find the swirl file which provides the given dependency

Parameters:	dependency (FingerPrint.swirl.Dependency) – the dependency which should be satisfied
Return type:	FingerPrint.swirl.SwirlFile
Returns:	a SwirlFile which provides the given dependency None if it could not be found

isFileTracked(fileName)[source]¶

return true if fileName is already tracked by this swirl

Parameters:	fileName (string) – the path of the file to look up
Return type:	bool
Returns:	true if fileName is tracked by this swirl

printVerbose(verbosity=1)[source]¶

return a string representation of this swirl. This method is called by the -d flags

Parameters:	verbosity (int) – the level of verbosity 0 minimum 2 maximum
Return type:	string
Returns:	a string with a representation of this Swirl

class FingerPrint.swirl.SwirlFile(path, links)[source]¶

Bases: FingerPrint.swirl.Arch

Encapsulate all the info we need to track for each file. At the moment only ELF aka binary file are really supported everything else is considered ‘data’.

There is only 1 swirlFile instance for each file in a given swirl for example if libabc is used by /bin/ls and /bin/ps they will both point to the same instance of libabc

Parameters:	path (string) – The aboslute path of this SwirlFile this is the identificative key for this SwirlFile links (list) – a list of string with all the discovered simbolic links pointing to this SwirlFile

addDependency(dependency)[source]¶

if dependency is not already in the static dependency of this swirl file it gets added

Parameters:	dependency (FingerPrint.swirl.Dependency) – an instance of Dependency to be added

addProvide(dependency)[source]¶

if dependency is not already in the provides of this SwirlFile it gets added

Parameters:	dependency (FingerPrint.swirl.Dependency) – an instance of Dependency to be added

getDependenciesDict(provides=False)[source]¶

Return a dictionary containing the dependencies or the provides of this SwirlFile

Parameters:	provides (bool) – if provides is equal to True this function returns what this SwirlFile provides instead of what it requires
Return type:	dict
Returns:	a dict where the keys are sonames of the values are lists of library versions (e.g. {‘libc.so.6’ : [‘GLIBC_2.10’, ‘GLIBC_2.11’, ‘GLIBC_2.12’]})

getPaths()[source]¶

return a list of path used by this SwirlFile (it includes all the symbolic links)

Return type:	list
Returns:	return a list of strings

getProvidesDict()[source]¶

Return type:	dict
Returns:	a dict which represent all the Dependecy provided by this class see getDependenciesDict for the format of the dictionary

isELFExecutable()[source]¶

Return type:	bool
Returns:	true if this SwirlFile is executable

isLoader()[source]¶

Return type:	bool
Returns:	return True if this SwirlFile is a loader

isYourPath(path)[source]¶

check if this path is part of this swirlFile looking into the links as well

Parameters:	path (string) – a file path
Return type:	bool
Returns:	true if the given path is part of this SwirlFile

printOpenedFiles(execFile, tabs='')[source]¶

return a string of opened file by the given executable path execFile

Parameters:	execFile (string) – used to get the list of opened file by a specific executable, shared libs can open different file when loaded under different executable tabs (string) – used to indent the output, it will be placed at the beginning of each line
Return type:	string
Returns:	a string with all the opened file of this SwirlFile (used by the -d flags)

printVerbose(separator='', dynamic='', verbosity=1)[source]¶

returns a string represeting this SwrilFile

Parameters:	seprator (string) – used to indent the output, it will be placed at the beginning of each line dynamic (string) – used to add a string to the first output line. Currently it is used to put the –dyn– if this SwirlFile was a dynamic loaded file verbosity (int) – verbosity level. 0 for the lower level 1 or 2 to get more info
Return type:	string
Returns:	a detailed representation of this SwirlFile (used by the -d flags)

setLinks(links)[source]¶

update the list of symbolic links pointing to this swirl file

Parameters:	links (list) – a list of string with file path names

setPluginName(name)[source]¶

Set the plugin type of this file (at the moment we have only elf plugin)

Parameters:	name (string) – the plugin name as in FingerPrint/plugins

syscalltracer Module¶

class FingerPrint.syscalltracer.ObjectFile(filename)[source]¶

This class wraps an elf object file and its assembler code used by the stack tracing facility. This class depend on objdump to disassemble binaries. This class need several optimization (uses a lot of memory and CPU time).

Parameters:	filename (string) – the path to the binary will be disassembled

getInstruction(vma)[source]¶

it decodes the instruction at the given virtual memory address

Parameters:	vma (string) – the virtual memory address in an hexadecimal format
Return type:	tuple
Returns:	a tuple of tree strings where the first string is the opcode at the given address vma, the second is the address referred by the instruction and the third is the symbolic name referred by the address

getPrevInstruction(vma)[source]¶

it decodes the previous instruction at the given virtual memory address

Parameters:	vma (string) – the virtual memory address in an hexadecimal format
Return type:	tuple
Returns:	a tuple of tree strings where the first string is the opcode at the given address vma, the second is the address referred by the instruction and the third is the symbolic name referred by the address

isDynamic()[source]¶

Return type:	bool
Returns:	true if this is a dynamic object aka a shared library

class FingerPrint.syscalltracer.SyscallTracer[source]¶

this class can spawn a process and trace its’ execution to record what are its dynamic dependency requirements

Usage:

tracer = SyscallTracer()
execcmd = shlex.split(execcmd)
tracer.main(execcmd)
# output will in the TracerControlBlock static variables
TracerControlBlock.[files|dependencies|env|cmdline]

main(command)[source]¶

start the trace with the given command

Parameters:	command (string) – command line to trace passed through shlex.split
Return type:	bool
Returns:	false if something went wrong

readCString(address, pid)[source]¶

test()[source]¶

class FingerPrint.syscalltracer.TracerControlBlock(pid)[source]¶

This class hold data needed for tracing a processes. Inspired by strace code (struct tcb).

PS: I don’t really like this solution of static variable but for the moment ti does its job

Parameters:	pid (int) – the PID of the process that we are tracing

cmdline = {}¶

dictionary that keeps track of the executed command line. Keys are the full path to the executable and values are a list of strings containing all the token of the command line

dependencies = {}¶

Dictionary of shared libraries used by the various processes. E.g.: `{ 'binarypath': [list of file it depends to], '/bin/bash': ['/lib/x86_64-linux-gnu/libnss_files-2.15.so', '/lib/x86_64-linux-gnu/libnss_nis-2.15.so']}`

env = {}¶

Dictionary that keeps track of process environment variables. Keys are the full path to the executable of the process and values are a list of strings containing all the variables

files = {}¶

Dictionary of dictionary of opened files by the various processes. E.g. files[libraryA][executableB] and files[libraryA][executableC] return respectively the list of opened file by the libraryA when run under executableB and when run under executableC.

getFileOpener()[source]¶

if Fingerprint is compiled with the stack tracer module it will find the file object who contains the code which initiated this open system call if not it will return the path to the current process. This function is called after each open system call.

Return type:	string
Returns:	the path of the library who triggered the current open system call

getProcessCWD()[source]¶

Return type:	string
Returns:	return the current working directory of this process

getProcessName()[source]¶

Return type:	string
Returns:	the process name (this is used in all the static attribute of this class as a key)

classmethod get_env_variable(process_name, variable_name)[source]¶

returns the value of the variable_name if found int he process_name environment

Parameters:	process_name (string) – the full path to the executable representing this process variable_name (string) – the name of the variable
Return type:	string
Returns:	a environment variable value

classmethod set_trace_function()[source]¶

This class method load the function needed to set up the stack tracer which require the external shared library. Called only once.

updateProcessInfo()[source]¶

This method updates the process information into the global static variables TracerControlBlock.cmdline, TracerControlBlock.env of this class. This method is called only once when this instance is created (aka when the process is created).

updateSharedLibraries()[source]¶

This method scans the procfs to find the shared libraries loaded by this process and it updates the static TracerControlBlock.dependencies variable accordingly. This function is called every time the process invoke the mmap system call.

utils Module¶

FingerPrint.utils.all(iterable)[source]¶

FingerPrint.utils.any(iterable)[source]¶

FingerPrint.utils.getLDLibraryPath(env)[source]¶

given a list of environment variables it return a list of absolute path defined in LD_LIBRARY_PATH (if a path is relative it will be transformed in an absolute with PWD)

FingerPrint.utils.getOutputAsList(binary, inputString=None)[source]¶

run popen pipe inputString and return a touple of (the stdout as a list of string, return value of the command)

FingerPrint.utils.which(program, extra_paths=None)[source]¶

extra path is a string containing a list of path separated by : which

Subpackages¶