FingerPrint internal API¶
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
- class FingerPrint.composer.Roller(archive_filename, roll_name)[source]¶
this class make a roll out of an fingerprint archive
Parameters:
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
- 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: 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
swirl Module¶
- 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
- 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
- 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: - 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
- 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: 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)
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
- 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]
- 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: 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).
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.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)