Kestrel runs in a Python environment on Linux, macOS, or Windows. On Windows, please use Python inside Windows Subsystem for Linux (WSL).
Python 3 is required.
- End-of-life Python versions are not supported. Check Python releases.
- Follow the Python installation guide to install or upgrade Python.
.. tab-set::
.. tab-item:: Linux
If you are using following Linux distributions or newer, the requirement is
already met:
.. grid:: 4
:margin: 0
.. grid-item::
- Alpine 3.6
.. grid-item::
- Archlinux
.. grid-item::
- Debian 10
.. grid-item::
- Fedora 33
.. grid-item::
- Gentoo
.. grid-item::
- openSUSE 15.2
.. grid-item::
- Ubuntu 20.04
.. grid-item::
- 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.
.. tab-item:: macOS
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.
.. tab-item:: Windows (WSL)
Nothing needed.
.. tab-set::
.. tab-item:: In a Python Virtual Environment [Recommended]
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``:
.. code-block:: console
$ python3 -m venv huntingspace
$ . huntingspace/bin/activate
$ pip install --upgrade pip setuptools wheel
.. tab-item:: User-wide
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).
.. tab-item:: OS-wide
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:
.. code-block:: console
$ sudo -i
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.
.. tab-set::
.. tab-item:: Stable Version
.. code-block:: console
$ pip install kestrel-jupyter
$ kestrel_jupyter_setup
.. tab-item:: Nightly Built
.. code-block:: console
$ git clone git://github.com/opencybersecurityalliance/kestrel-lang
$ cd kestrel-lang
$ make install
Kestrel runtime currently supports three front-ends (:ref:`overview/index:Kestrel in a Nutshell`). Use the following command to invoke any of them:
.. tab-set::
.. tab-item:: Jupyter Notebook
This is the most popular front-end for Kestrel and it provides an
interactive way to develop :ref:`language/tac:Hunt Flow` and
:ref:`language/tac:Huntbook`. Start the Jupyter Notebook and dive into
:ref:`tutorial:Kestrel + Jupyter`:
.. code-block:: console
$ jupyter nbclassic
.. tab-item:: Command-line Utility
The ``kestrel`` command is designed for batch execution and hunting
automation. Use it right away in a terminal:
.. code-block:: console
$ kestrel myfirsthuntflow.hf
Check out the :ref:`tutorial:Hello World Hunt` for more information.
.. tab-item:: Python API
You can use/call Kestrel from any Python program.
- Start a Kestrel session in Python directly. See more at :doc:`../source/kestrel.session`.
- Use `magic command`_ in iPython environment. Check `kestrel-jupyter`_ package for usage.