Tutorial

This document presents a short walkthrough on how to use Thumbtack. Please refer to the links throughout the document for further information.

Installation

In order to install Thumbtack, you should use a virtual environment, which will allow you to keep Thumbtack dependencies separate from system Python packages.

Note

Due to restrictions of several disk-mounting utilities, Thumbtack should be installed and run as the root user.

Create and activate the virtual environment:

sudo apt-get install python3-venv
python -m venv ./thumbtack

Once you have a virtual environment created and activated, use pip to install the Thumbtack server.

source ./thumbtack/bin/activate
pip install thumbtack

Install Imagemounter Dependencies

Thumbtack uses the imagemounter library, which has a set of dependencies required to mount different types of disk images. Follow the imagemounter install instructions to install required dependencies. You can also run imount --check to get a list of dependencies as well as install status.

$ imount --check
The following commands are used by imagemounter internally. Without most commands, imagemounter works perfectly fine, but may lack some detection or mounting capabilities.
-- Mounting base disk images (at least one required, first three recommended) --
MISSING   xmount              needed for several types of disk images, part of the xmount package
MISSING   ewfmount            needed for EWF images (partially covered by xmount), part of the ewf-tools package
MISSING   affuse              needed for AFF images (partially covered by xmount), part of the afflib-tools package
MISSING   vmware-mount        needed for VMWare disks
MISSING   mountavfs           needed for compressed disk images, part of the avfs package
MISSING   qemu-nbd            needed for Qcow2 images, part of the qemu-utils package
-- Detecting volumes and volume types (at least one required) --
MISSING   mmls                part of the sleuthkit package
MISSING   pytsk3              install using pip
INSTALLED parted
-- Detecting volume types (all recommended, first two highly recommended) --
MISSING   fsstat              part of the sleuthkit package
INSTALLED file
INSTALLED blkid
MISSING   python-magic        install using pip
MISSING   disktype            part of the disktype package
-- Mounting volumes (install when needed) --
INSTALLED xfs
INSTALLED ntfs
MISSING   lvm                 needed for LVM volumes, part of the lvm2 package
MISSING   vmfs-fuse           needed for VMFS volumes, part of the vmfs-tools package
INSTALLED jffs2
INSTALLED squashfs
MISSING   mdadm               needed for RAID volumes, part of the mdadm package
MISSING   cryptsetup          needed for LUKS containers, part of the cryptsetup package
MISSING   bdemount            needed for Bitlocker Drive Encryption volumes, part of the libbde-utils package
MISSING   vshadowmount        needed for NTFS volume shadow copies, part of the libvshadow-utils package
MISSING   photorec            needed for carving free space, part of the testdisk package

Create Directory of Disk Images

You will need to have a directory of disk images that Thumbtack will be configured to monitor. Thumbtack will automatically assume that every file in this directory is a disk image, so be advised that other filetypes will automatically fail to mount. You may use the following script from the Thumbtack repository to download some test images from DFTT or Digital Corpora. The script will give estimated download size and ask permission before downloading.

mkdir disk_images
cd disk_images
wget https://raw.githubusercontent.com/mitre/thumbtack/master/tests/download-test-images.py
python download_test_images.py

Run the Server

Here’s the easy part! Just make sure to be in the directory where your disk images are as mentioned above in the Create Directory of Disk Images section.

thumbtack

The Thumbtack server is now listening on port 8208, and can be accessed from a web browser at http://127.0.0.1:8208

There are a few options that the thumbtack command can take, allowing you to change the host, port, image directory, and sqlite database file. See them below.

$ thumbtack --help
Usage: thumbtack [OPTIONS]

Options:
  -d, --debug                   Run the Thumbtack server in debug mode
  -h, --host TEXT               Host to run Thumbtack server on  [default: 127.0.0.1]
  -p, --port TEXT               Port to run Thumbtack server on  [default: 8208]
  -i, --image-dir TEXT          Directory of disk images for Thumbtack server to
                                monitor  [default: $CWD]
  --db TEXT                     SQLite database to store mount state  [default:
                                database.db]
  -b, --base-url TEXT           Base URL where Thumbtack is hosted on the server
  --path-contains TEXT          Only select files containing specified string in the path
  -s, --skip-subdirectory TEXT  Subdirectory to ignore when monitoring files
  --help                        Show this message and exit.

Development Environment

If you are planning to contribute to the development of Thumbtack, you should clone the repository from GitHub rather than installing a released version from PyPI. Vagrant is recommended and a fully functioning Vagrantfile is provided at the top level of the repo. It will install an Ubuntu 16.04 VirtualBox VM locally with all libraries required as well as Thumbtack.

# Install Vagrant
# Install VirtualBox
git clone https://github.com/mitre/thumbtack.git
cd thumbtack
vagrant up
vagrant ssh

# inside Vagrant machine
cd /vagrant/tests
python download_test_images.py
cd test_images
thumbtack -h 0.0.0.0

The Vagrant VM will be running the Thumbtack server on port 8208, and is set up to automatically forward the port to your localhost. You should be able to access the web interface via http://127.0.0.1:8208 now.

Thumbtack in Docker

Thumbtack can be run in a docker container. A template docker-compose file is included in the thumbtack repository.

apt-get install docker.io docker-compose
git clone https://github.com/mitre/thumbtack.git

Copy and fill out the docker-compose.yml file. Replace all instances of image_dir with the absolute path the the image directory. Replace all instances of mount_dir with the absolute path to the directory where images should be mounted. You may add additional options to the command as needed.

cd docker
cp docker-compose.yml.template docker-compose.yml

After filling out the docker-compose template, start the docker container.

docker-compose up

Navigate to http://127.0.0.1:8208 to use thumbtack.

Note

To enable mounting lvm volumes within docker, you must install the lvm2 package on the host system.

sudo apt-get install lvm2

Pseudo-Production Environment

If you would like to get Thumbtack to work with a webserver like Nginx or Apache, a wsgi.py file is provided at the top level of the repo. Once again, for more information on deploying Flask applications, please refer to Flask’s deployment documentation.

Including FUSE for EWF images

In order to mount EWF images, the libewf package needs to be installed and configured to support FUSE. The following steps can be used to install the package.

sudo apt install autoconf automake autopoint libtool pkg-config libfuse-dev zlib1g-dev
wget https://github.com/libyal/libewf/releases/download/20201230/libewf-experimental-20201230.tar.gz
tar -xavf libewf-experimental-20201230.tar.gz
cd libewf-20201230/
./configure --enable-python3 --with-libfuse
make
sudo make install