Install Runtime

Kestrel runs in a Python environment on Linux, macOS, or Windows. On Windows, please use Python inside Windows Subsystem for Linux (WSL).

General Requirements

Python 3.8 is required. Follow the Python installation guide to install or upgrade Python.

OS-specific Requirements

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

  • Alpine 3.6

  • Archlinux

  • Debian 10

  • Fedora 33

  • Gentoo

  • openSUSE 15.2

  • Ubuntu 20.04

  • RedHat 8

Otherwise, check the SQLite version in a terminal with command sqlite3 --version and upgrade sqlite3 >= 3.24 as needed, which is required by firepit, a Kestrel dependency, with default config.

Full installation of Xcode is required, especially for Mac with Apple silicon (M1/M2/…).

The basic xcode-select --install may not install Python header files, or set incorrect architecture argument for dependent package compilation, so the full installation of Xcode is required.

Nothing needed.

Choose Where to Install

It is a good practice to install Kestrel in a Python virtual environment so there will be no dependency conflict with Python packages in the system, plus all dependencies will be the latest.

To setup and activate a Python virtual environment named huntingspace:

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

If you don’t like Python virtual environment or think it is too complicated, you can directly install Kestrel under a user.

There is nothing you need to do in this step besides opening a terminal under that user, or login to the remote host under that user.

The downside is all Python packages under that user are in the same namespace. If Kestrel requires a specific version of a library package, and another application requires a different version of the same library package, that will cause a conflict (pip in the next step will give a warning if happens).

It is not recommended to install Kestrel as system packages since the configurations of Kestrel is under the user who runs it. However, it is possible to install Kestrel as system package, just open a terminal and swtich to root as follows:

$ sudo -i

Kestrel Runtime Installation

Execute the command in the terminal you opened in the last step. If you use Python virtual environment, the virtual environment should be activated for any newly opened terminal.

$ pip install kestrel-lang

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

Kestrel Front-End Setup

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

Choose one and execute the command to install/use them in the terminal you opened in the last step. If you use Python virtual environment, the virtual environment should be activated for any newly opened terminal.

This is the most popular front-end for Kestrel and it provides an interactive way to develop Hunt Flow and Huntbook. You can install the Jupyter front-end by:

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

Then, you can start the Jupyter Notebook and dive into Kestrel + Jupyter:

$ jupyter nbclassic

The kestrel command is installed along with the Kestrel runtime installation in the last step. This is designed for batch execution and hunting automation. You can use it right away like:

$ kestrel myfirsthuntflow.hf

Check out the Hello World Hunt for more information.

You can use/call Kestrel from any Python program.

What’s to Do Next