Installation

Install the Kestrel runtime plus additional front ends such as Kestrel Jupyter Notebook kernel.

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.

The preferred way to install Kestrel is with pip. You must upgrade pip to the latest version before you install:

$ pip install --upgrade pip

SQLite

By default, Kestrel uses sqlite3 as the storage back-end (more details in firepit package), and firepit requires sqlite3 >= 3.24. However, sqlite3 is not a standalone Python package in Python 3, and Python version, e.g., 3.6, is not coupled with sqlite3 version, e.g., 3.22.

This means Python installer such as pip cannot resolve sqlite3 version requirement. You need manually run the following command in a terminal to check your sqlite3 version and upgrade sqlite3 if needed.

$ sqlite3 --version

Among popular Linux distributions, the minimal distribution versions with out-of-box Linux installations that satisfy the sqlite3 version requirement are:

  • Archlinux

  • Debian 10

  • Fedora 33

  • Gentoo

  • openSUSE Leap 15.2

  • RedHat 8

  • Ubuntu 20.04 LTS

Runtime Installation

You can install Kestrel runtime from stable release or source code (nightly built version). Either way installs all packages in the kestrel-lang repository, and dependent packages, such as firepit and stix-shifter. See the architecture section in What is Kestrel? to understand more.

It is a good practice to install Kestrel in a Python virtual environment. You can easily setup and activate one named huntingspace:

$ python -m venv huntingspace
$ . huntingspace/bin/activate

Stable Release

Run this command in your terminal:

$ pip install kestrel-lang

Source Code (Nightly Built Version)

  1. Install and upgrade Python building packages setuptools and wheel:

$ pip install --upgrade pip setuptools wheel

  1. Clone the source from the Github repo:

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

  1. Install all packages from the repo:

$ pip install .

Runtime Front Ends

Kestrel runtime currently supports three front ends (see architecture figure in What is Kestrel?):

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

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

  1. 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

  1. Python API:

    • Start a Kestrel session in Python directly. See more at Kestrel Session.

    • Use magic command in iPython environment. kestrel-jupyter required.