Zelos (Zeropoint Emulated Lightweight Operating System) is a python-based binary emulation platform. One use of zelos is to quickly assess the dynamic behavior of binaries via command-line or python scripts. All syscalls are emulated to isolate the target binary. Linux x86_64 (32- and 64-bit), ARM and MIPS binaries are supported. Unicorn provides CPU emulation.

Full documentation is available here.

Use the package manager pip to install zelos.

pip install zelos

To emulate a binary with default options:

$ zelos my_binary

To view the instructions that are being executed, add the -v flag:

$ zelos -v my_binary

You can print only the first time each instruction is executed, rather than every execution, using --fasttrace:

$ zelos -v --fasttrace my_binary

By default, syscalls are emitted on stdout. To write syscalls to a file instead, use the --strace flag:

$ zelos --strace path/to/file my_binary

Specify any command line arguments after the binary name:

$ zelos my_binary arg1 arg2

import zelos

z = zelos.Zelos("my_binary")
z.start(timeout=3)

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

First, create a new python virtual environment. This will ensure no package version conflicts arise:

$ python3 -m venv ~/.venv/zelos
$ source ~/.venv/zelos/bin/activate

Now clone the repository and change into the zelos directory:

(zelos) $ git clone [email protected]:zeropointdynamics/zelos.git
(zelos) $ cd zelos

Install an editable version of zelos into the virtual environment. This makes import zelos available, and any local changes to zelos will be effective immediately:

(zelos) $ pip install -e '.[dev]'

At this point, tests should pass and documentation should build:

(zelos) $ pytest
(zelos) $ cd docs
(zelos) $ make html

Built documentation is found in docs/_build/html/.

Install zelos pre-commit hooks to ensure code style compliance:

(zelos) $ pre-commit install

In addition to automatically running every commit, you can run them anytime with:

(zelos) $ pre-commit run --all-files

Commands vary slightly on Windows:

C:\> python3 -m venv zelos_venv
C:\> zelos_venv\Scripts\activate.bat
(zelos) C:\> pip install -e .[dev]

AGPL v3