mirror of
https://github.com/mandiant/speakeasy.git
synced 2026-10-12 02:18:47 +00:00
Willi BallenthinandClaude Fable 5
84615cdd6d
The pid payload added in d43f82e was documented as "NULL when the target is
the actor itself", but record_process_event always copied proc.id, so a
purely local VirtualAlloc or CreateThread looked identical to a cross-process
operation. Null the payload centrally in record_process_event when the target
process matches the actor's pos.pid, so a populated pid always means the
operation crossed a process boundary. Thread events keep tid, which is real
data (the created thread) even for a local create.
- profiler.py: pid payload is None when proc.id == pos.pid.
- profiler_events.py: ThreadInjectEvent.pid documents the NULL case, matching
the other process-scoped events.
- doc/reporting.md: event examples show the actor in pos with the target as a
pid payload, including the local (omitted pid) cases; report_version in the
examples refreshed to 4.0.0.
- tests: local vs cross-process pid payloads for mem_alloc, thread_create,
and thread_inject.
get_json_report uses exclude_none, so a local operation omits the pid key
entirely rather than emitting an explicit null.
Co-Authored-By: Claude Fable 5 <[email protected]>
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
CLI usage
- CLI reference
- CLI analysis recipes
- CLI environment overrides
- CLI execution controls
- CLI help snapshot (showboat)
Reports, configuration, and runtime behavior
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.