A comprehensive binary emulation platform.
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.
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
$ zelos --inst my_binary
You can print only the first time each instruction is executed, rather than every execution, using
$ zelos --inst --fasttrace my_binary
By default, syscalls are emitted on stdout. To write syscalls to a file instead, use the
$ zelos --trace_file 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)
Zelos supports first- and third-party plugins. Some notable plugins thus far:
- crashd crash analyzer combining execution trace, dataflow and memory sanitization.
- overlay (ida plugin): highlights
zelosexecution trace in IDA with instruction-level comments added.
- angr integration: enables symbolic execution in
- zdbserver: remote control and debugging of emulated binaries.
- syscall limiter: demonstrates event hooking and provides syscall-based execution and termination options.
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.
Local Development Environment
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) $ git clone email@example.com: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
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]
All notable changes to this project will be documented in this file.
[Version 0.2.0] - 2020-08-04
- Plugins: Yarascan
- Introduction of Zelos Manipulation Language (ZML), used for specifying events on the command line and in scripts. New zml_hook function in api
- Ability to redirect input to stdin
- Hooks for internal memory reads, writes, and maps
- Linked to crashd plugin, containing separate plugins for heap memory guards, static analysis via IDA Pro, and dataflow using QEMU TCG
- Moved to different command line flags for specifying what degree of information (instructions or syscalls) is printed while running
- Better support for lists in command line arguments
- Flags can be passed to the emulated program via the command line
- Misc. bug fixes (thanks to seth1002)
- General improvements to syscalls
- Verbosity command line flag (now handled via other flags)
[Version 0.1.0] - 2020-05-29
- Plugins: IDA overlays, remote debug server
- Additional plugin APIs
- Minor syscall emulation improvements
- Memory management overhaul
[Version 0.0.1] - 2020-03-03
- Updated documentation
[Version 0.0.0] - 2020-03-02
Initial public release.
- Initial open source commit.
The Core Zelos Team
- Kevin Valakuzhy - Research Engineer, Developer
- Ryan C. Court - Research Engineer, Developer
- Kevin Z. Snow - Co-Founder, Developer
Special Thanks To
- Fabian Monrose - Co-Founder
- Ann Cox - DHS Program Manager
- Angelos Keromytis - DARPA Program Manager (Former)
- Dustin Fraze - DARPA Program Manager
- Suyup Kim - Intern
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Hashes for zelos-0.2.0-py2.py3-none-any.whl