FingerPrint internal API

blotter Module

class FingerPrint.blotter.Blotter(name, fileList, processIDs, execCmd)

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()

return the current swirl

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

composer Module

class FingerPrint.composer.Archiver(sergeant, archive_filename)

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()

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)

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)

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)

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)

this function makes a mapping file for the remapper process

sergeant Module

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

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()

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)

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)

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()

return a dot representation of this swirl

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

getError()

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()

return the current swirl

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

print_swirl(verbosity)

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()

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)

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)

TODO remove this function

FingerPrint.sergeant.getHash(fileName, fileType)

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)

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)

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)

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)

this class serialize a swirl into a pickle file format

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

load()

Return the Swirl read from the given file descriptor

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

save(swirl)

Saves the given swirl to the file descriptor

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

class FingerPrint.serializer.XmlSerializer(fd)

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()

this should implement the read from xml

save(swirl)

save_depset(dependencySet)

swirl Module

class FingerPrint.swirl.Arch

old style classes for backward compability

is32bits()

is64bits()

set32bits()

set 32 bit architecture

set64bits()

set 64 bit architecture

class FingerPrint.swirl.Dependency(major, minor=None, hwcap=None)

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)

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()

Return type:string Returns:the major of this dependency

getMinor()

Return type:string Returns:the minor of this dependency

getName()

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()

return true if this is the loader

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

class FingerPrint.swirl.Swirl(name, creationDate)

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)

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()

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()

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=[])

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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()

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()

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

isELFExecutable()

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

isLoader()

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

isYourPath(path)

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='')

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)

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)

update the list of symbolic links pointing to this swirl file

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

setPluginName(name)

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)

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)

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)

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()

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

class FingerPrint.syscalltracer.SyscallTracer

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)

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)

test()

class FingerPrint.syscalltracer.TracerControlBlock(pid)

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()

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()

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

getProcessName()

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)

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()

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

updateProcessInfo()

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()

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)

FingerPrint.utils.any(iterable)

FingerPrint.utils.getLDLibraryPath(env)

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)

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)

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

Subpackages

• plugins Package
  • plugins Package
  • elf Module
• ptrace Package
  • cpu_info Module
  • ctypes_errno Module
  • ctypes_libc Module
  • ctypes_tools Module
  • error Module
  • func Module
  • linux_struct Module
  • os_tools Module
  • signames Module