Installation

Install the Kestrel runtime plus the Kestrel Jupyter front-end.

Operating Systems

Currently, Kestrel is supported on Linux and macOS.

Requirements

Python

This project builds on Python 3. Refer to the Python installation guide if you do not have Python 3.

SQLite

If you are using following Linux distributions or newer, the SQLite requirement is already met:

Archlinux
Debian 10
Fedora 33
Gentoo
openSUSE Leap 15.2
RedHat 8
Ubuntu 20.04 LTS

Otherwise, check the SQLite version in a terminal and upgrade sqlite3 >= 3.24 as needed, which is required by firepit, a Kestrel dependency, in its default configuration:

$ sqlite3 --version

Runtime Installation

You can install Kestrel runtime from stable release or nightly built version (source code). Either way installs all packages in the kestrel-lang repository, and dependent packages, such as firepit and STIX-shifter.

It is a good practice to install Kestrel in a Python virtual environment so all dependencies will be the latest. You can easily setup, activate, and update a Python virtual environment named huntingspace:

$ python -m venv huntingspace
$ . huntingspace/bin/activate
$ pip install --upgrade pip setuptools wheel

Stable Release

Run this command in your terminal (huntingspace activated):

$ pip install kestrel-lang

Nightly Built Version (Source Code)

Run this command in your terminal (huntingspace activated):

$ git clone git://github.com/opencybersecurityalliance/kestrel-lang
$ cd kestrel-lang && pip install .

Front-Ends Installation

Kestrel runtime currently supports three front-ends (Kestrel in a Nutshell):

Command-line execution utility kestrel: Installed with the package kestrel.

$ kestrel [-h] [-v] [--debug] hunt101.hf

Kestrel Jupyter Notebook kernel: Must install and set up the kestrel-jupyter package (Jupyter Notebook dependencies will be automatically installed if they do not exist):

$ pip install kestrel-jupyter
$ python -m kestrel_jupyter_kernel.setup

Python API:

Start a Kestrel session in Python directly. See more at Kestrel Session.
Use magic command in iPython environment. Check kestrel-jupyter package for usage.

Kestrel in Action

Now the Kestrel runtime is set up and you can run a Kestrel huntflow with the command-line utility or launch a Jupyter service for developing a huntbook interactively (huntingspace activated):

$ jupyter notebook

Optional: Kestrel Analytics

Want to have some Kestrel analytics ready at your fingertip? Threat intelligence enrichments like SANS API? Domain name lookup for IP addresses? Finding IP geolocations and pin them on an interactive map? Invoking machine learning inference function? Clone the community-contributed Kestrel analytics repo to start:

$ git clone https://github.com/opencybersecurityalliance/kestrel-analytics.git

Go to the analytics directory and build the analytics docker containers to APPLY in your hunt.