Troubleshooting

Introduction

This page contains some notes on troubleshooting issues in pytsk.

The pytsk Python-binding consists of predefined and generated code.

• The majority of the predefined code can be found in tsk3.c.
• The generated code is stored in pytsk3.c, which is generated from the SleuthKit header files by class_parser.py.

Notes regarding the generated code (pytsk3.c):

• setup.py will not overwrite pytsk3.c if it exists.
• generate_bindings.py will overwrite pytsk3.c if it exists.

Compilation and linking errors

GNU Compiler Collection (GCC)

If you're not familiar with building from source code and you encounter the following error:

error: command 'gcc' fails with exit status 1

This means the compilation failed. To determine the cause look for lines containing ": error: " e.g.

pytsk3.c: In function 'pyTSK_FS_NAME_getattr':
pytsk3.c:3273:22: error: 'TSK_FS_NAME' has no member named 'par_seq'
pytsk3.c: In function 'pyTSK_FS_DIR_getattr':
pytsk3.c:7553:18: error: 'TSK_FS_DIR' has no member named 'seq'

This indicates pytks3 is trying to reference SleuthKit struct members that do not exist. The most likely cause is that pytsk3.c was generated for a different version of the SleuthKit you are currently trying to build against. Make sure:

• you have only one version of the SleuthKit installed on your system;
• you delete pytsk3.c before building so it is generated for the right version of the SleuthKit.

TSK_IMG_TYPE_EXTERNAL

tsk3.c:167:29: error: 'TSK_IMG_TYPE_EXTERNAL' undeclared (first use in this function)

You'll need to apply the TSK_IMG_TYPE_EXTERNAL patch against the SleuthKit 4.1.3. See: Building SleuthKit

Unable to find libtalloc

ld: library not found for -ltalloc

Make sure setup.py knows where to find libtalloc. You can try explicitly setting the location of libtalloc, e.g.

LDFLAGS=-L/opt/local/lib python setup.py build

Memory usage

When troubleshooting memory usage issue in pytsk note that it deals with memory managed by three different sources:

• SleuthKit (malloc);
• pytsk (talloc);
• Python (PyMalloc).

talloc

Talloc provides built-in leak reporting. To enable open class_parser.py and find the line:

"// DEBUG: talloc_enable_leak_report_full();\n"

Change this to:

"talloc_enable_leak_report_full();\n"

and rebuild the pytsk Python module.

This will print an overview of the memory still in-use, by talloc, on unloading of the pytsk module.

The Python Object Graph module

The Python Object Graph module can help to troubleshoot referencing issues.

The Object Graph module can be found here:

https://pypi.python.org/pypi/objgraph

A way to use the Object Graph module is to set a break point in the python script:

import pdb; pdb.set_trace()

Once inside the Python debugger (pdb) import the Object Graph module:

import objgraph

To see the 20 most common used object types:

objgraph.show_most_common_types(limit=20)

dict               48711
function           32110
cell               30353
tuple              29557
list               17445
UInt16             7644
Dict               6728
UInt32             5464
frame              3554
generator          3539
weakref            3095
instancemethod     2865
Bit                2669
TSKFileSystemImage 2169
TSKFile            2164
Bits               2010
IndexOffset        2002
wrapper_descriptor 1633
type               1632
NullBytes          1443

To determine the back references to a specific object instance:

obj = objgraph.by_type('TSKFileSystemImage')[0]
objgraph.show_backrefs([obj], max_depth=10)

Known issues

• The thread local storage (TLS) version of error is not explicitly freed and will show up in the talloc report.

Crashes

First make sure your configuration is sane:

• no multiple installations of the SleuthKit
• no multiple installations of pytsk

Common locations on Linux:

• /usr/lib/
• /usr/lib/python2.7/site-packages/
• /usr/lib64/
• /usr/lib64/python2.7/site-packages/
• /usr/local/lib/
• /usr/local/lib/python2.7/site-packages/

Second make sure you are running the latest version in case the issue already has been fixed.

Third make sure your build is correctly. Run python (or equivalent):

import pytsk3

If a crash occurs here your build is likely to be broken.

Debug Symbols

SleuthKit

To compile the SleuthKit with debug symbols:

CPPCFLAGS=-g ./configure --prefix=/usr --disable-java
make
sudo make install

Microsoft Visual Studio

Build the executables using the Debug configuration and run the command via the Visual Studio debugger.

pytsk

To compile pytsk3 with debug symbols:

CPPCFLAGS=-g python setup.py build

Copy the pytsk3.so over the original.

Microsoft Visual Studio

Build the executables using the VSDebug configuration and run the command via the Visual Studio debugger.

Copy the pytsk3.pyd over the original.

Getting a back trace

Run the tools with a debugger:

gdb -ex r --args python myscript.py

Generating a back trace:

bt

Windows

See: MSDN: Debugging a User-Mode Process Using WinDbg