$ show mandiant/speakeasy
Speakeasy is a Windows malware emulation framework developed by Mandiant (FireEye). It executes Windows PE executables, DLLs, drivers, and shellcode in a fully emulated Windows environment, intercepting API calls via a large set of stub handlers that model kernel32, ntdll, ws2_32, user32, ntoskrnl, and many other DLLs. The emulation is powered by Unicorn (CPU emulation) and Capstone (disassembly). It provides both a CLI tool (`speakeasy`) and a Python library (`Speakeasy` class) for programmatic use. Key features include: user-mode and kernel-mode emulation, GDB remote debugging support, configurable file system, registry, network, and process models, SEH handling, API hammering detection, and structured JSON reports with profiling events, memory captures, and artifact deduplication. The architecture is a monolithic Python package with a core emulator class, platform-specific emulators (Win32Emulator, WinKernelEmulator), and a large set of API handler modules organized by DLL. Dependencies include unicorn, capstone, pefile, pydantic, rich, and pyelftools. The project is primarily used for automated malware analysis and reverse engineering.
The LLM identified 5 files worth highlighting for reuse:
Provides `EmuStruct` and `EmuUnion` metaclass-based classes that dynamically generate ctypes structures with configurable pointer size and packing. This pattern allows defining Windows structures in a declarative way and serializing them to/from memory. It is self-contained and can be reused in any project that needs to model C-style structures with variable pointer sizes.
Implements `ArtifactStore`, a deduplicating binary artifact storage that uses SHA256 hashing to avoid storing duplicate binary blobs, with optional base64+zlib compression. It provides a clean API to add, retrieve, and query artifacts. This component can be extracted and reused in any application that needs to manage a set of unique binary payloads (e.g., sandbox outputs, file collectors).
Contains `HandleAllocator`, a simple sequential handle generator that allocates handles per type, and `ObjectManager`, which manages kernel objects (Driver, Device, Thread, Process) by address, name, or handle. The handle allocator is a standalone utility class that can be reused in any system needing handle-based resource management.
Implements a GDB Remote Serial Protocol server (`GdbServer`) that allows interactive debugging of emulated binaries. It handles breakpoints, watchpoints, memory/register access, XML target descriptions, and library loading notifications. The class is modular and could be adapted to provide GDB debugging for other emulators or simulators with minimal changes.
Provides a `ConfigCliFieldSpec` system that maps CLI arguments (e.g., `--hostname`, `--dns-server`) to nested fields in the Pydantic configuration model (`SpeakeasyConfig`). This allows deep configuration overrides from the command line without boilerplate. The pattern is reusable in any CLI application that needs to override complex nested configuration structures.