vminspect package¶

Submodules¶

vminspect.comparator module¶

Module for comparing Virtual Machine Disk Images.

class vminspect.comparator.DiskComparator(disk0, disk1)¶

Bases: object

Performs an in depth comparison of two given disk images.

compare(concurrent=False, identify=False, size=False)¶

Compares the two disks according to flags.

Generates the following report:

{'created_files': [{'path': '/file/in/disk1/not/in/disk0',
                    'sha1': 'sha1_of_the_file'}],
 'deleted_files': [{'path': '/file/in/disk0/not/in/disk1',
                    'original_sha1': 'sha1_of_the_file'}],
 'modified_files': [{'path': '/file/both/disks/but/different',
                     'sha1': 'sha1_of_the_file_on_disk0',
                     'original_sha1': 'sha1_of_the_file_on_disk0'}]}

If concurrent is set to True, the logic will use multiple CPUs to speed up the process.

The identify and size keywords will add respectively the type and the size of the files to the results.

compare_registry(concurrent=False)¶

Compares the Windows Registry contained within the two File Systems.

It parses all the registry hive files contained within the disks and generates the following report.

{‘created_keys’: {‘RegKey’: ((‘Key’, ‘Type’, ‘Value’))}

‘deleted_keys’: [‘RegKey’, ...], ‘created_values’: {‘RegKey’: ((‘Key’, ‘Type’, ‘NewValue’))}, ‘deleted_values’: {‘RegKey’: ((‘Key’, ‘Type’, ‘OldValue’))}, ‘modified_values’: {‘RegKey’: ((‘Key’, ‘Type’, ‘NewValue’))}}

Only registry hives which are contained in both disks are compared. If the second disk contains a new registry hive, its content can be listed using winreg.RegistryHive.registry() method.

If the concurrent flag is True, two processes will be used speeding up the comparison on multiple CPUs.

extract(disk, files, path='.')¶

Extracts the given files from the given disk.

Disk must be an integer (1 or 2) indicating from which of the two disks to extract.

Files must be a list of dictionaries containing the keys ‘path’ and ‘sha1’.

Files will be extracted in path and will be named with their sha1.

Returns a dictionary.

{‘extracted_files’: [<sha1>, <sha1>],

‘extraction_errors’: [<sha1>, <sha1>]}

vminspect.comparator.compare_filesystems(fs0, fs1, concurrent=False)¶

Compares the two given filesystems.

fs0 and fs1 are two mounted GuestFS instances containing the two disks to be compared.

If the concurrent flag is True, two processes will be used speeding up the comparison on multiple CPUs.

Returns a dictionary containing files created, removed and modified.

{‘created_files’: [<files in fs1 and not in fs0>],

‘deleted_files’: [<files in fs0 and not in fs1>], ‘modified_files’: [<files in both fs0 and fs1 but different>]}

vminspect.comparator.compare_hives(fs0, fs1)¶: Compares all the windows registry hive files returning those which differ.

vminspect.comparator.compare_registries(fs0, fs1, concurrent=False)¶

Compares the Windows Registry contained within the two File Systems.

If the concurrent flag is True, two processes will be used speeding up the comparison on multiple CPUs.

Returns a dictionary.

{‘created_keys’: {‘RegKey’: ((‘Key’, ‘Type’, ‘Value’), ...)}

‘deleted_keys’: [‘RegKey’, ...], ‘created_values’: {‘RegKey’: ((‘Key’, ‘Type’, ‘NewValue’), ...)}, ‘deleted_values’: {‘RegKey’: ((‘Key’, ‘Type’, ‘OldValue’), ...)}, ‘modified_values’: {‘RegKey’: ((‘Key’, ‘Type’, ‘NewValue’), ...)}}

vminspect.comparator.compare_values(values0, values1)¶: Compares all the values of a single registry key.

vminspect.comparator.concurrent_parse_registries(filesystem, registries)¶

vminspect.comparator.concurrent_visit_filesystem(filesystem)¶

vminspect.comparator.extract_files(filesystem, files, path)¶

Extracts requested files.

files must be a list of files in the format

{“C:WindowsSystem32NTUSER.DAT”: “sha1_hash”} for windows {“/home/user/text.txt”: “sha1_hash”} for other FS.

files will be extracted into path which must exist beforehand.

Returns two dictionaries:

{“sha1”: “/local/path/sha1”} files successfully extracted {“sha1”: “C:..text.txt”} files which could not be extracted windows {“sha1”: “/../text.txt”} files which could not be extracted linux

vminspect.comparator.file_comparison(files0, files1)¶

Compares two dictionaries of files returning their difference.

{‘created_files’: [<files in files1 and not in files0>],: ‘deleted_files’: [<files in files0 and not in files1>], ‘modified_files’: [<files in both files0 and files1 but different>]}

vminspect.comparator.files_size(fs0, fs1, files)¶: Gets the file size of the given files.

vminspect.comparator.files_type(fs0, fs1, files)¶: Inspects the file type of the given files.

vminspect.comparator.makedirs(path)¶: Creates the directory tree if non existing.

vminspect.comparator.parse_registries(filesystem, registries)¶

Returns a dictionary with the content of the given registry hives.

{“RegistryKey”, ((“ValueKey”, “ValueType”, ValueValue))}

vminspect.comparator.registry_comparison(registry0, registry1)¶: Compares two dictionaries of registry keys returning their difference.

vminspect.comparator.user_registries(fs0, fs1)¶: Returns the list of user registries present on both FileSystems.

vminspect.comparator.visit_filesystem(filesystem)¶

Utility function for running the files iterator at once.

Returns a dictionary.

{‘/path/on/filesystem’: ‘file_hash’}

vminspect.filesystem module¶

GuestFS wrapper to facilitate File System analysis.

class vminspect.filesystem.FileSystem(disk_path)¶

Bases: object

Convenience wrapper over GuestFS instance.

Simplifies some common routines.

Automatically translates paths according to the contained File System.

checksum(path, hashtype='sha1')¶: Returns the checksum of the given path.

checksums(path, hashtype='sha1')¶

Iterates over the files hashes contained within the disk starting from the given path.

The hashtype keyword allows to choose the file hashing algorithm.

Yields the following values:

“C:WindowsSystem32NTUSER.DAT”, “hash” for windows “/home/user/text.txt”, “hash” for other FS

download(source, destination)¶: Downloads the file on the disk at source into destination.

exists(path)¶: Returns whether the path exists.

file(path)¶: Analogous to Unix file command. Returns the type of node at the given path.

fsroot¶: Returns the file system root.

ls(path)¶: Lists the content at the given path.

mount(readonly=True)¶: Mounts the given disk. It must be called before any other method.

nodes(path)¶

Iterates over the files and directories contained within the disk starting from the given path.

Yields the path of the nodes.

osname¶: Returns the Operating System name.

path(*segments)¶: Normalizes the path returned by guestfs in the File System format.

stat(path)¶

Retrieves the status of the node at the given path.

Returns a dictionary.

umount()¶

Unmounts the disk.

After this method is called no further action is allowed.

vminspect.filesystem.posix_path(*segments)¶

vminspect.timeline module¶

Analyse disk content to extract File System event timelines.

class vminspect.timeline.Dirent(inode, path, size, type, allocated, atime, mtime, ctime, crtime)¶

Bases: tuple

allocated¶: Alias for field number 4

atime¶: Alias for field number 5

crtime¶: Alias for field number 8

ctime¶: Alias for field number 7

inode¶: Alias for field number 0

mtime¶: Alias for field number 6

path¶: Alias for field number 1

size¶: Alias for field number 2

type¶: Alias for field number 3

class vminspect.timeline.Event(inode, path, size, allocated, timestamp, reason)¶

Bases: tuple

allocated¶: Alias for field number 3

inode¶: Alias for field number 0

path¶: Alias for field number 1

reason¶: Alias for field number 5

size¶: Alias for field number 2

timestamp¶: Alias for field number 4

class vminspect.timeline.FSTimeline(disk)¶

Bases: object

checksum¶

Identifies the file type.

Caches the result to reduce overhead on duplicated events.

file¶

Identifies the file type.

Caches the result to reduce overhead on duplicated events.

timeline()¶

class vminspect.timeline.JrnlEvent(inode, parent_inode, name, timestamp, changes, attributes)¶

Bases: tuple

attributes¶: Alias for field number 5

changes¶: Alias for field number 4

inode¶: Alias for field number 0

name¶: Alias for field number 2

parent_inode¶: Alias for field number 1

timestamp¶: Alias for field number 3

class vminspect.timeline.NTFSTimeline(disk)¶

Bases: vminspect.timeline.FSTimeline

Inspect NTFS filesystem in order to extract a timeline of events containing the information related to files/directories changes.

This feature depends on a special build of Libguestfs available at:: https://github.com/noxdafox/libguestfs/tree/forensics

usnjrnl_timeline()¶

Iterates over the changes occurred within the filesystem.

Yields UsnJrnlEvent namedtuples containing:

file_reference_number: known in Unix FS as inode. path: full path of the file. size: size of the file in bytes if recoverable. allocated: whether the file exists or it has been deleted. timestamp: timespamp of the change. changes: list of changes applied to the file. attributes: list of file attributes.

vminspect.timeline.UsnJrnlEvent¶: alias of Event

vminspect.timeline.generate_timeline(usnjrnl, content)¶: Aggregates the data collected from the USN journal and the filesystem content.

vminspect.timeline.journal_event(events)¶: Group multiple events into a single one.

vminspect.timeline.lookup_dirent(event, content)¶

vminspect.timeline.parse_journal(journal)¶: Parses the USN Journal content removing duplicates and corrupted records.

vminspect.timeline.timestamp(secs, nsecs)¶

vminspect.usnjrnl module¶

Module for parsing Windows Update Sequence Number Journal.

class vminspect.usnjrnl.CorruptedUsnRecord(index)¶

Bases: tuple

index¶: Alias for field number 0

class vminspect.usnjrnl.UsnRecord(length, version, file_reference_number, file_reference_number_sequence, parent_file_reference_number, parent_file_reference_number_sequence, update_sequence_number, timestamp, reasons, source_info, security_id, file_attributes, file_name)¶

Bases: tuple

file_attributes¶: Alias for field number 11

file_name¶: Alias for field number 12

file_reference_number¶: Alias for field number 2

file_reference_number_sequence¶: Alias for field number 3

length¶: Alias for field number 0

parent_file_reference_number¶: Alias for field number 4

parent_file_reference_number_sequence¶: Alias for field number 5

reasons¶: Alias for field number 8

security_id¶: Alias for field number 10

source_info¶: Alias for field number 9

timestamp¶: Alias for field number 7

update_sequence_number¶: Alias for field number 6

version¶: Alias for field number 1

vminspect.usnjrnl.parse_journal_file(journal_file)¶: Iterates over the journal’s file taking care of paddings.

vminspect.usnjrnl.parse_record(header, record)¶: Parses a record according to its version.

vminspect.usnjrnl.read_next_block(infile, block_size=8192)¶: Iterates over the file in blocks.

vminspect.usnjrnl.remove_nullchars(block)¶: Strips NULL chars taking care of bytes alignment.

vminspect.usnjrnl.unpack_flags(value, flags)¶: Multiple flags might be packed in the same field.

vminspect.usnjrnl.usn_journal(path)¶: Iterates over the Windows Update Sequence Number entries contained in the file at the given path.

vminspect.usnjrnl.usn_v2_record(header, record)¶: Extracts USN V2 record information.

vminspect.usnjrnl.usn_v3_record(header, record)¶: Extracts USN V3 record information.

vminspect.usnjrnl.usn_v4_record(header, record)¶: Extracts USN V4 record information.

vminspect.vtscan module¶

class vminspect.vtscan.VTReport(path, hash, detections)¶

Bases: tuple

detections¶: Alias for field number 2

hash¶: Alias for field number 1

path¶: Alias for field number 0

class vminspect.vtscan.VTScanner(disk, apikey)¶

Bases: object

VirusTotal scanner.

Allows to scan the given disk content and query VirusTotal.

disk must contain the path of a valid disk image. apikey must be a valid VT API key.

The attribute batchsize controls the amount of object per VT query.

apikey¶

filetype_filter(files, filetypes=None)¶

parse_response(files, response)¶

parse_result(result, files)¶

scan(filetypes=None)¶

Iterates over the content of the disk and queries VirusTotal to determine whether it’s malicious or not.

filetypes is a list containing regular expression patterns. If given, only the files which type will match with one or more of the given patterns will be queried against VirusTotal.

For each file which is unknown by VT or positive to any of its engines, the method yields a namedtuple:

VTReport(path -> C:WindowsSystem32infected.dll: hash -> ab231... detections) -> dictionary engine -> detection

Files unknown by VirusTotal will contain the string ‘unknown’ in the detection field.

vminspect.vtscan.chunks(iterable, size=1)¶: Splits iterator in chunks.

vminspect.vtscan.vtquery(apikey, checksums)¶: Performs the query dealing with errors and throttling requests.

vminspect.vulnscan module¶

class vminspect.vulnscan.Application(name, version)¶

Bases: tuple

name¶: Alias for field number 0

version¶: Alias for field number 1

class vminspect.vulnscan.VulnApp(name, version, vulnerabilities)¶

Bases: tuple

name¶: Alias for field number 0

version¶: Alias for field number 1

vulnerabilities¶: Alias for field number 2

class vminspect.vulnscan.VulnScanner(disk, url)¶

Bases: object

Vulnerability scanner.

Allows to scan the given disk content and query a CVE DB for vulnerabilities.

disk must contain the path of a valid disk image. url must be a valid URL to a REST vulnerability service.

applications()¶

query_vulnerabilities(application)¶

scan(concurrency=1)¶

Iterates over the applications installed within the disk and queries the CVE DB to determine whether they are vulnerable.

Concurrency controls the amount of concurrent queries against the CVE DB.

For each vulnerable application the method yields a namedtuple:

VulnApp(name -> application name: version -> application version vulnerabilities) -> list of Vulnerabilities
Vulnerability(id -> CVE Id: summary) -> brief description of the vulnerability

class vminspect.vulnscan.Vulnerability(id, summary)¶

Bases: tuple

id¶: Alias for field number 0

summary¶: Alias for field number 1

vminspect.vulnscan.lookup_vulnerabilities(app_version, vulnerabilities)¶

vminspect.winreg module¶

Module for parsing Windows Registry hive files.

class vminspect.winreg.RegistryHive(filename, verbose=False, debug=False, write=False)¶

Bases: hivex.Hivex

RegistryHive class.

Allows to visit a registry hive file given its path.

This class is a subclass of hivex.Hivex class.

keys()¶

Iterates over the hive’s keys.

Yields WinRegKey namedtuples containing:

path: path of the key “RootKeyKey...” timestamp: date and time of last modification values: list of values ((“ValueKey”, “ValueType”, ValueValue), ... )

rootkey¶: Returns the Registry Root Key.

class vminspect.winreg.WinRegKey(path, timestamp, values)¶

Bases: tuple

path¶: Alias for field number 0

timestamp¶: Alias for field number 1

values¶: Alias for field number 2

vminspect.winreg.registries_path(fsroot)¶

Iterates over the registry hives locations.

fsroot must contain the file system root, ex: C:

vminspect.winreg.registry_root(path)¶: Guesses the registry root from the file name.

vminspect.winreg.user_registries_path(fsroot, user)¶

Iterates over the user registry hives locations.

fsroot must contain the file system root, ex: C:

Module contents¶

class vminspect.FileSystem(disk_path)¶

Bases: object

Convenience wrapper over GuestFS instance.

Simplifies some common routines.

Automatically translates paths according to the contained File System.

checksum(path, hashtype='sha1')¶: Returns the checksum of the given path.

checksums(path, hashtype='sha1')¶

Iterates over the files hashes contained within the disk starting from the given path.

The hashtype keyword allows to choose the file hashing algorithm.

Yields the following values:

“C:WindowsSystem32NTUSER.DAT”, “hash” for windows “/home/user/text.txt”, “hash” for other FS

download(source, destination)¶: Downloads the file on the disk at source into destination.

exists(path)¶: Returns whether the path exists.

file(path)¶: Analogous to Unix file command. Returns the type of node at the given path.

fsroot¶: Returns the file system root.

ls(path)¶: Lists the content at the given path.

mount(readonly=True)¶: Mounts the given disk. It must be called before any other method.

nodes(path)¶

Iterates over the files and directories contained within the disk starting from the given path.

Yields the path of the nodes.

osname¶: Returns the Operating System name.

path(*segments)¶: Normalizes the path returned by guestfs in the File System format.

stat(path)¶

Retrieves the status of the node at the given path.

Returns a dictionary.

umount()¶

Unmounts the disk.

After this method is called no further action is allowed.

class vminspect.RegistryHive(filename, verbose=False, debug=False, write=False)¶

Bases: hivex.Hivex

RegistryHive class.

Allows to visit a registry hive file given its path.

This class is a subclass of hivex.Hivex class.

keys()¶

Iterates over the hive’s keys.

Yields WinRegKey namedtuples containing:

path: path of the key “RootKeyKey...” timestamp: date and time of last modification values: list of values ((“ValueKey”, “ValueType”, ValueValue), ... )

rootkey¶: Returns the Registry Root Key.

vminspect.registry_root(path)¶: Guesses the registry root from the file name.

vminspect.registries_path(fsroot)¶

Iterates over the registry hives locations.

fsroot must contain the file system root, ex: C:

vminspect.user_registries_path(fsroot, user)¶

Iterates over the user registry hives locations.

fsroot must contain the file system root, ex: C:

vminspect.usn_journal(path)¶: Iterates over the Windows Update Sequence Number entries contained in the file at the given path.

class vminspect.DiskComparator(disk0, disk1)¶

Bases: object

Performs an in depth comparison of two given disk images.

compare(concurrent=False, identify=False, size=False)¶

Compares the two disks according to flags.

Generates the following report:

{'created_files': [{'path': '/file/in/disk1/not/in/disk0',
                    'sha1': 'sha1_of_the_file'}],
 'deleted_files': [{'path': '/file/in/disk0/not/in/disk1',
                    'original_sha1': 'sha1_of_the_file'}],
 'modified_files': [{'path': '/file/both/disks/but/different',
                     'sha1': 'sha1_of_the_file_on_disk0',
                     'original_sha1': 'sha1_of_the_file_on_disk0'}]}

If concurrent is set to True, the logic will use multiple CPUs to speed up the process.

The identify and size keywords will add respectively the type and the size of the files to the results.

compare_registry(concurrent=False)¶

Compares the Windows Registry contained within the two File Systems.

It parses all the registry hive files contained within the disks and generates the following report.

{‘created_keys’: {‘RegKey’: ((‘Key’, ‘Type’, ‘Value’))}

‘deleted_keys’: [‘RegKey’, ...], ‘created_values’: {‘RegKey’: ((‘Key’, ‘Type’, ‘NewValue’))}, ‘deleted_values’: {‘RegKey’: ((‘Key’, ‘Type’, ‘OldValue’))}, ‘modified_values’: {‘RegKey’: ((‘Key’, ‘Type’, ‘NewValue’))}}

Only registry hives which are contained in both disks are compared. If the second disk contains a new registry hive, its content can be listed using winreg.RegistryHive.registry() method.

If the concurrent flag is True, two processes will be used speeding up the comparison on multiple CPUs.

extract(disk, files, path='.')¶

Extracts the given files from the given disk.

Disk must be an integer (1 or 2) indicating from which of the two disks to extract.

Files must be a list of dictionaries containing the keys ‘path’ and ‘sha1’.

Files will be extracted in path and will be named with their sha1.

Returns a dictionary.

{‘extracted_files’: [<sha1>, <sha1>],

‘extraction_errors’: [<sha1>, <sha1>]}

class vminspect.FSTimeline(disk)¶

Bases: object

checksum¶

Identifies the file type.

Caches the result to reduce overhead on duplicated events.

file¶

Identifies the file type.

Caches the result to reduce overhead on duplicated events.

timeline()¶

class vminspect.NTFSTimeline(disk)¶

Bases: vminspect.timeline.FSTimeline

Inspect NTFS filesystem in order to extract a timeline of events containing the information related to files/directories changes.

This feature depends on a special build of Libguestfs available at:: https://github.com/noxdafox/libguestfs/tree/forensics

usnjrnl_timeline()¶

Iterates over the changes occurred within the filesystem.

Yields UsnJrnlEvent namedtuples containing:

file_reference_number: known in Unix FS as inode. path: full path of the file. size: size of the file in bytes if recoverable. allocated: whether the file exists or it has been deleted. timestamp: timespamp of the change. changes: list of changes applied to the file. attributes: list of file attributes.

class vminspect.VulnScanner(disk, url)¶

Bases: object

Vulnerability scanner.

Allows to scan the given disk content and query a CVE DB for vulnerabilities.

disk must contain the path of a valid disk image. url must be a valid URL to a REST vulnerability service.

applications()¶

query_vulnerabilities(application)¶

scan(concurrency=1)¶

Iterates over the applications installed within the disk and queries the CVE DB to determine whether they are vulnerable.

Concurrency controls the amount of concurrent queries against the CVE DB.

For each vulnerable application the method yields a namedtuple:

VulnApp(name -> application name: version -> application version vulnerabilities) -> list of Vulnerabilities
Vulnerability(id -> CVE Id: summary) -> brief description of the vulnerability

class vminspect.VTScanner(disk, apikey)¶

Bases: object

VirusTotal scanner.

Allows to scan the given disk content and query VirusTotal.

disk must contain the path of a valid disk image. apikey must be a valid VT API key.

The attribute batchsize controls the amount of object per VT query.

apikey¶

filetype_filter(files, filetypes=None)¶

parse_response(files, response)¶

parse_result(result, files)¶

scan(filetypes=None)¶

Iterates over the content of the disk and queries VirusTotal to determine whether it’s malicious or not.

filetypes is a list containing regular expression patterns. If given, only the files which type will match with one or more of the given patterns will be queried against VirusTotal.

For each file which is unknown by VT or positive to any of its engines, the method yields a namedtuple:

VTReport(path -> C:WindowsSystem32infected.dll: hash -> ab231... detections) -> dictionary engine -> detection

Files unknown by VirusTotal will contain the string ‘unknown’ in the detection field.

class vminspect.WinEventLog(disk)¶

Bases: object

WinEventLog class.

Allows to retrieve the Events contained within Windows Event Log files.

eventlog(path)¶

Iterates over the Events contained within the log at the given path.

For each Event, yields a XML string.

vminspect package¶

Submodules¶

vminspect.comparator module¶

vminspect.filesystem module¶

vminspect.timeline module¶

vminspect.usnjrnl module¶

vminspect.vtscan module¶

vminspect.vulnscan module¶

vminspect.winreg module¶

Module contents¶

Table Of Contents

Related Topics

This Page