Metadata-Version: 2.4
Name: speakeasy-emulator
Version: 2.0.0
Summary: Speakeasy malware emulation framework
Author: Andrew Davis
License-Expression: MIT
Project-URL: Homepage, https://github.com/mandiant/speakeasy
Project-URL: Documentation, https://github.com/mandiant/speakeasy/blob/master/doc/index.md
Project-URL: Repository, https://github.com/mandiant/speakeasy
Project-URL: Issues, https://github.com/mandiant/speakeasy/issues
Keywords: emulator,malware,windows,reverse-engineering,security
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Security
Classifier: Typing :: Typed
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pefile>=2024.8.26
Requires-Dist: capstone>=5.0.3
Requires-Dist: lznt1>=0.2
Requires-Dist: unicorn<3,>=2.1.4
Requires-Dist: pycryptodome>=3.15.0
Requires-Dist: pydantic>=2.10
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff==0.17.3; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# Speakeasy

Speakeasy is a Windows malware emulation framework that executes binaries, drivers and shellcode in a modeled Windows runtime instead of a full VM. It emulates the Windows APIs, processes, threads, file system, registry and network that a sample uses, so the sample runs further than in a bare CPU emulator. The `speakeasy` CLI writes the report as JSON for triage, and the Python library returns the same report to your code.

For background, see Mandiant's [introduction to Speakeasy](https://cloud.google.com/blog/topics/threat-intelligence/emulation-of-malicious-shellcode-with-speakeasy/).

## Quick start

Install from PyPI:

```console
python3 -m pip install speakeasy-emulator
```

Emulate a sample and print some fields of the report. Replace `sample.dll` with your file:

```console
speakeasy -t sample.dll --no-mp -o report.json 2>/dev/null
jq '{sha256, arch, file_type, runs: (.runs | length)}' report.json
```

The values depend on the sample:

```json
{
  "sha256": "…",
  "arch": "x86",
  "file_type": "dll",
  "runs": 3
}
```

By default, Speakeasy turns on all its features: it runs the exports and the child processes, and the report has coverage, memory access counts and the final memory contents. Each feature has a `--no-` flag that turns it off, for example `--no-code-coverage`. A run with fewer features is faster and gives a smaller report. The [CLI reference](https://github.com/mandiant/speakeasy/blob/master/doc/cli-reference.md#config-flags) lists the flags.

## Documentation

Start with [installation](https://github.com/mandiant/speakeasy/blob/master/doc/install.md), [Python library usage](https://github.com/mandiant/speakeasy/blob/master/doc/library.md) and the [CLI reference](https://github.com/mandiant/speakeasy/blob/master/doc/cli-reference.md). The [documentation index](https://github.com/mandiant/speakeasy/blob/master/doc/index.md) lists all pages.

For help, see [doc/help.md](https://github.com/mandiant/speakeasy/blob/master/doc/help.md) or open an issue at [github.com/mandiant/speakeasy/issues](https://github.com/mandiant/speakeasy/issues).
