Installation

The installation process for most operating systems follows the same set of steps for the most part. I prefer to keep things maintained in a python virtual environment. These install steps will guide you through setting up a virtual environment for each OS which you may skip if you don’t want.

OS X

Virtualenv Setup

Before You Begin

First up, you’ll need Xcode. You can find it in the app store, but it’s huge (like 4GB) so it’ll take a while to download. Once you have it, install the command line tools with

xcode-select --install

Once Xcode is all taken care of, get homebrew

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

You should already have python, but if you’d like a different version, you may install one from brew.

Setting up the Virtualenv

pip install virtualenv
pip install virtualenvwrapper
echo 'export WORKON_HOME="$HOME/.virtualenvs"' >> ~/.bash_profile
echo 'source $(which virtualenvwrapper.sh)' >> ~/.bash_profile
source ~/.bash_profile

Now you will have a bunch of bash helper functions for using/managing virtual environments. The one’s you will use most are:

mkvirtualenv <env name> # creates a new virtual env
rmvirtualenv <env name> # deletes a virtual env
mktmpenv # creates a virtual env that is deleted when `deactivate` is run
workon <env name> # sets the current virtual env
deactivate # unsets the current virtual env

Setting up ThreatShell

Installing the requirements for ThreatShell is as simple as

python setup.py install

You can run tests with

python setup.py test

# or with coverage included like so
python setup.py test --pytest-args="--cov=threatshell"

To begin using it

python threatshell.py

Running ThreatShell for the first time will trigger some setup/configuration prompts. Just follow along and you’ll be hunting in no time.

Readline Caveat!

OS X doesn’t ship with libreadline. Instead, you get libedit which kinda sucks. The main issue with libedit is that it doesn’t honor the libreadline escape characters, therefore, it will fail to properly read the shell line with its color sequences, and scrolling through history causes buggy command display issues.

This can be solved by simply using easy_install to install readline, or by using brew to install the GNU readline and force linking it in. I recommend just using the easy_install readline. You will know when you have the right readline library working because Threatshell won’t complain about libedit being detected ;)