README.md

Changes

This package is a fork of Speakeasy published as speakeasy-emulator-refined on PyPI. No modifications have been made to the code; the only difference is that this fork publishes releases to PyPI while the upstream package does not.

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 APIs, process/thread behavior, filesystem, registry, and network activity so samples can keep moving through realistic execution paths. You can run it from the speakeasy CLI for fast triage or embed it as a Python library and consume structured JSON reports.

Background context: Mandiant's overview post.

Quick start

Install from PyPI:

python3 -m pip install speakeasy-emulator

Run a sample and inspect high-level report fields (replace sample.dll with your target):

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

{
  "sha256": "30ec092d122a90441a2560f6778ef8233c98079cd34b7633f7bbc2874c8d7a45",
  "arch": "x86",
  "filetype": "dll",
  "entry_points": 3
}

Executable proof for this snippet: doc/readme-quickstart-showboat.md.

Documentation map

Start here

• Installation and Docker usage
• Python library usage
• Help and troubleshooting
• Documentation index

CLI usage

• CLI reference
• CLI analysis recipes
• CLI environment overrides
• CLI execution controls
• CLI help snapshot (showboat)

Reports, configuration, and runtime behavior

• Configuration walkthrough
• Report walkthrough
• Memory management
• Limitations

Debugging and extension

• GDB debugging reference
• GDB sessions (showboat)
• Mounting host files with --volume
• Adding API handlers
• Examples directory
• Speakeasy 2 walkthrough outline

Questions and help

Start with doc/help.md.

If you still need help, open an issue at github.com/mandiant/speakeasy/issues.