Metadata-Version: 2.4
Name: zelos
Version: 0.2.1.dev0
Summary: A comprehensive binary emulation platform.
Home-page: https://github.com/zeropointdynamics/zelos
Author: Zeropoint Dynamics
Author-email: zelos@zeropointdynamics.com
Maintainer: Zeropoint Dynamics
Maintainer-email: zelos@zeropointdynamics.com
License: AGPLv3
Project-URL: Documentation, https://zelos.zeropointdynamics.com/
Project-URL: Bug Tracker, https://github.com/zeropointdynamics/zelos/issues
Project-URL: Source Code, https://github.com/zeropointdynamics/zelos
Keywords: emulation,dynamic analysis,binary analysis
Classifier: Development Status :: 4 - Beta
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.6.0
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: wheel
Requires-Dist: colorama
Requires-Dist: termcolor
Requires-Dist: capstone
Requires-Dist: sortedcontainers
Requires-Dist: verboselogs
Requires-Dist: dnslib
Requires-Dist: hexdump
Requires-Dist: dpkt
Requires-Dist: coloredlogs
Requires-Dist: configargparse
Requires-Dist: pypacker
Requires-Dist: lief
Requires-Dist: zebracorn
Requires-Dist: lark-parser
Provides-Extra: docs
Requires-Dist: docutils==0.16; extra == "docs"
Requires-Dist: sphinx==2.4.4; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Requires-Dist: sphinxcontrib-apidoc; extra == "docs"
Requires-Dist: recommonmark; extra == "docs"
Requires-Dist: sphinx-argparse; extra == "docs"
Provides-Extra: tests
Requires-Dist: coverage; extra == "tests"
Requires-Dist: hypothesis; extra == "tests"
Requires-Dist: pympler; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Requires-Dist: pytest>=4.3.0; extra == "tests"
Requires-Dist: pytest-xdist; extra == "tests"
Requires-Dist: filelock; extra == "tests"
Requires-Dist: yara-python; extra == "tests"
Requires-Dist: mock; extra == "tests"
Provides-Extra: dev
Requires-Dist: coverage; extra == "dev"
Requires-Dist: hypothesis; extra == "dev"
Requires-Dist: pympler; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest>=4.3.0; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: filelock; extra == "dev"
Requires-Dist: yara-python; extra == "dev"
Requires-Dist: mock; extra == "dev"
Requires-Dist: docutils==0.16; extra == "dev"
Requires-Dist: sphinx==2.4.4; extra == "dev"
Requires-Dist: sphinx_rtd_theme; extra == "dev"
Requires-Dist: sphinxcontrib-apidoc; extra == "dev"
Requires-Dist: recommonmark; extra == "dev"
Requires-Dist: sphinx-argparse; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: tox; extra == "dev"
Provides-Extra: azure-pipelines
Requires-Dist: coverage; extra == "azure-pipelines"
Requires-Dist: hypothesis; extra == "azure-pipelines"
Requires-Dist: pympler; extra == "azure-pipelines"
Requires-Dist: pytest-cov; extra == "azure-pipelines"
Requires-Dist: pytest>=4.3.0; extra == "azure-pipelines"
Requires-Dist: pytest-xdist; extra == "azure-pipelines"
Requires-Dist: filelock; extra == "azure-pipelines"
Requires-Dist: yara-python; extra == "azure-pipelines"
Requires-Dist: mock; extra == "azure-pipelines"
Requires-Dist: pytest-azurepipelines; extra == "azure-pipelines"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

![PyPI](https://img.shields.io/pypi/v/zelos)
[![Build Status](https://dev.azure.com/kevin0853/zelos/_apis/build/status/zeropointdynamics.zelos?branchName=master)](https://dev.azure.com/kevin0853/zelos/_build/latest?definitionId=1&branchName=master)
[![codecov](https://codecov.io/gh/zeropointdynamics/zelos/branch/master/graph/badge.svg)](https://codecov.io/gh/zeropointdynamics/zelos)
[![Documentation Status](https://readthedocs.org/projects/zelos/badge/?version=latest)](https://zelos.readthedocs.io/en/latest/?badge=latest)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/zelos)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>

# Zelos
Zelos (**Z**eropoint **E**mulated **L**ightweight **O**perating **S**ystem) 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](https://github.com/unicorn-engine/unicorn) provides CPU emulation.

![Image](https://raw.githubusercontent.com/zeropointdynamics/zelos/master/docs/_static/demo.gif)

[Full documentation](https://zelos.readthedocs.io/en/latest/index.html) is available [here](https://zelos.readthedocs.io/en/latest/index.html).

## Installation

Use the package manager [pip](https://pip.pypa.io/en/stable/) to install zelos.

```bash
pip install zelos
```

## Basic Usage

### Command-line
To emulate a binary with default options:

```console
$ zelos my_binary
```

To view the instructions that are being executed, add the `--inst` flag:
```console
$ zelos --inst my_binary
```

You can print only the first time each instruction is executed, rather than *every* execution, using `--fasttrace`:
```console
$ zelos --inst --fasttrace my_binary
```

By default, syscalls are emitted on stdout. To write syscalls to a file instead, use the `--trace_file` flag:
```console
$ zelos --trace_file path/to/file my_binary
```

Specify any command line arguments after the binary name:
```console
$ zelos my_binary arg1 arg2
```

### Programmatic
```python
import zelos

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

## Plugins

Zelos supports first- and third-party [plugins](https://zelos.readthedocs.io/en/latest/tutorials/04_writing_plugins.html). Some notable plugins thus far:

- [crashd](https://github.com/zeropointdynamics/zelos-crashd) crash analyzer combining execution trace, dataflow and memory sanitization.
- [overlay (ida plugin)](https://zelos.readthedocs.io/en/latest/tutorials/06_snapshot_overlay.html): highlights `zelos` execution trace in IDA with instruction-level comments added.
- [angr integration](https://github.com/zeropointdynamics/angr-zelos-target): enables symbolic execution in `zelos`.
- [zdbserver](https://github.com/zeropointdynamics/zelos/tree/master/src/zelos/tools/zdbserver): remote control and debugging of emulated binaries.
- [syscall limiter](https://zelos.readthedocs.io/en/latest/tutorials/05_syscall_limit_plugin.html): demonstrates event hooking and provides syscall-based execution and termination options.

## Contributing
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:

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

Now clone the repository and change into the `zelos` directory:

```console
(zelos) $ git clone git@github.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:

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

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

```console
(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:

```console
(zelos) $ pre-commit install
```

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

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

#### Windows Development:

Commands vary slightly on Windows:

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

## License
[AGPL v3](https://www.gnu.org/licenses/agpl-3.0.en.html)


# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Version 0.2.0] - 2020-08-04

### Added

- 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

### Changed

- 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

### Removed

- Verbosity command line flag (now handled via other flags)

## [Version 0.1.0] - 2020-05-29

### Added

- Plugins: IDA overlays, remote debug server
- Additional plugin APIs

### Changed

- Minor syscall emulation improvements
- Memory management overhaul

### Removed

- N/A

## [Version 0.0.1] - 2020-03-03

### Added

- N/A

### Changed

- Updated documentation

### Removed

- N/A

## [Version 0.0.0] - 2020-03-02

Initial public release.

### Added

- Initial open source commit.

### Changed

- N/A

### Removed

- N/A

[0.0.0]: https://github.com/zeropointdynamics/zelos/releases/tag/v0.0.0


# The Core Zelos Team

* [Kevin Valakuzhy](//www.linkedin.com/in/kevin-valakuzhy-319a5447/) - Research Engineer, Developer
* [Ryan C. Court](//www.linkedin.com/in/rccourt) - Research Engineer, Developer
* [Kevin Z. Snow](//www.linkedin.com/in/kevinsnow/) - 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
