williballenthin · Nov 4, 2026 · Nov 4, 2026 · Nov 4, 2026 · Nov 4, 2026 · Nov 4, 2026
diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
 # 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.
+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.
 
-Background context: [Mandiant's overview post](https://cloud.google.com/blog/topics/threat-intelligence/emulation-of-malicious-shellcode-with-speakeasy/).
+For background, see Mandiant's [introduction to Speakeasy](https://cloud.google.com/blog/topics/threat-intelligence/emulation-of-malicious-shellcode-with-speakeasy/).
 
 ## Quick start
 
@@ -12,55 +12,26 @@ Install from PyPI:
 python3 -m pip install speakeasy-emulator
 ```
 
-Run a sample and inspect high-level report fields (replace `sample.dll` with your target):
+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, entry_points: (.entry_points | length)}' report.json
 ```
 
+The values depend on the sample:
+
 ```json
 {
-  "sha256": "30ec092d122a90441a2560f6778ef8233c98079cd34b7633f7bbc2874c8d7a45",
+  "sha256": "…",
   "arch": "x86",
   "file_type": "dll",
   "entry_points": 3
 }
 ```
 
-## Documentation map
-
-### Start here
-
-- [Installation](https://github.com/mandiant/speakeasy/blob/master/doc/install.md)
-- [Python library usage](https://github.com/mandiant/speakeasy/blob/master/doc/library.md)
-- [Help and troubleshooting](https://github.com/mandiant/speakeasy/blob/master/doc/help.md)
-- [Documentation index](https://github.com/mandiant/speakeasy/blob/master/doc/index.md)
-
-### CLI usage
-
-- [CLI reference](https://github.com/mandiant/speakeasy/blob/master/doc/cli-reference.md)
-- [CLI analysis recipes](https://github.com/mandiant/speakeasy/blob/master/doc/cli-analysis-recipes.md)
-- [CLI environment overrides](https://github.com/mandiant/speakeasy/blob/master/doc/cli-environment-overrides.md)
-- [CLI execution controls](https://github.com/mandiant/speakeasy/blob/master/doc/cli-execution-controls.md)
-
-### Reports, configuration, and runtime behavior
-
-- [Configuration walkthrough](https://github.com/mandiant/speakeasy/blob/master/doc/configuration.md)
-- [Report walkthrough](https://github.com/mandiant/speakeasy/blob/master/doc/reporting.md)
-- [Memory management](https://github.com/mandiant/speakeasy/blob/master/doc/memory.md)
-- [Limitations](https://github.com/mandiant/speakeasy/blob/master/doc/limitations.md)
-
-### Debugging and extension
-
-- [GDB debugging reference](https://github.com/mandiant/speakeasy/blob/master/doc/gdb.md)
-- [Mounting host files with `--volume`](https://github.com/mandiant/speakeasy/blob/master/doc/volumes.md)
-- [Adding API handlers](https://github.com/mandiant/speakeasy/blob/master/doc/api-handlers.md)
-- [Examples directory](https://github.com/mandiant/speakeasy/tree/master/examples)
-- [Speakeasy 2 walkthrough outline](https://github.com/mandiant/speakeasy/blob/master/doc/speakeasy2-walkthrough.md)
-
-## Questions and help
+## Documentation
 
-Start with [doc/help.md](https://github.com/mandiant/speakeasy/blob/master/doc/help.md).
+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.
 
-If you still need help, open an issue at [github.com/mandiant/speakeasy/issues](https://github.com/mandiant/speakeasy/issues).
+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).
diff --git a/doc/api-handlers.md b/doc/api-handlers.md
diff --git a/doc/architecture.md b/doc/architecture.md
diff --git a/doc/cli-analysis-recipes.md b/doc/cli-analysis-recipes.md
@@ -1,121 +1,92 @@
 # CLI analysis recipes
 
-This page focuses on practical flag combinations for common analysis outputs.
+Each recipe gives the flags for one kind of analysis output and a command that checks the output.
 
 <a id="recipe-memory-snapshots"></a>
 ## In-report memory snapshots (`--snapshot-memory-regions`)
 
-Command:
-
 ```bash
 speakeasy -t sample.exe --snapshot-memory-regions -o report.json
 ```
 
-Expected artifact:
-- `entry_points[*].memory.layout[*].data_ref` populated with SHA-256 refs
-- top-level `data` populated with `base64(zlib(raw_bytes))` entries
-
-Quick verification:
+The memory regions in `entry_points[*].memory.layout` get a `data_ref`, the SHA-256 of their bytes. Stack and heap regions do not get one. The top-level `data` object maps each SHA-256 to the bytes, compressed with zlib and encoded with base64. To list the regions that have data:
 
 ```bash
 jq '.entry_points[].memory.layout[] | select(.data_ref != null) | .tag' report.json
 ```
 
-Tradeoff:
-- report size increases, but repeated payloads deduplicate across runs
+The report gets larger. Regions with the same bytes share one entry in `data`, also across runs.
 
 <a id="recipe-analysis-coverage"></a>
 ## Coverage collection (`--analysis-coverage`)
 
-Command:
-
 ```bash
 speakeasy -t sample.exe --analysis-coverage -o report.json
 ```
 
-Expected artifact:
-- `entry_points[*].coverage` contains executed instruction addresses
-
-Quick verification:
+`entry_points[*].coverage` has the addresses of the instructions that each run executed. To count them:
 
 ```bash
 jq '.entry_points[] | {start_address, coverage_count: (.coverage // [] | length)}' report.json
 ```
 
-Tradeoff:
-- extra tracing overhead increases runtime
+The emulator runs a hook for each instruction, so emulation is slower.
 
 <a id="recipe-memory-tracing"></a>
 ## Memory tracing (`--analysis-memory-tracing`)
 
-Command:
-
 ```bash
 speakeasy -t sample.exe --analysis-memory-tracing -o report.json
 ```
 
-Expected artifact:
-- per-region access counters in `memory.layout[*].accesses`
-- symbol access summaries in `symbol_accesses`
-
-Quick verification:
+The regions in `entry_points[*].memory.layout` that the run accessed get `accesses`, with the counts of reads, writes and executes. `entry_points[*].symbol_accesses` has the counts for each symbol. To count the symbols that each run accessed:
 
 ```bash
 jq '.entry_points[] | {start_address, symbol_accesses: (.symbol_accesses // [] | length)}' report.json
 ```
 
-Tradeoff:
-- substantial runtime impact on memory-heavy samples
+The emulator runs a hook for each instruction, memory read and memory write. A sample that accesses much memory runs much slower.
 
 <a id="recipe-analysis-strings"></a>
 ## String extraction controls (`--analysis-strings` / `--no-analysis-strings`)
 
-Enable:
+String extraction is on by default, so `--analysis-strings` has an effect only when a `--config` file turns it off:
 
 ```bash
 speakeasy -t sample.exe --analysis-strings -o report.json
 ```
 
-Disable:
+`--no-analysis-strings` turns it off:
 
 ```bash
 speakeasy -t sample.exe --no-analysis-strings -o report.json
 ```
 
-Quick verification:
+The strings are in the top-level `strings` object. Without string extraction, the report has no `strings`:
 
 ```bash
 jq '.strings' report.json
 ```
 
-Tradeoff:
-- disabling strings reduces report size and post-processing time
+Without string extraction, the report is smaller and Speakeasy finishes sooner.
 
 <a id="recipe-dropped-files"></a>
 ## Dropped files archive (`--dropped-files-path`)
 
-Command:
-
 ```bash
 speakeasy -t sample.exe --dropped-files-path dropped.zip
 ```
 
-Expected artifact:
-- `dropped.zip` with files written during emulation and a manifest
-
-Quick verification:
+`dropped.zip` has the files that the sample wrote and `speakeasy_manifest.json`, which gives the emulated path, size and SHA-256 of each file. If the sample wrote no files, the CLI does not make the archive. To list the archive:
 
 ```bash
 unzip -l dropped.zip
 ```
 
-Tradeoff:
-- captures useful payload artifacts but adds archive creation overhead
-
 <a id="recipe-combined-triage"></a>
 ## Combined triage profile
 
-Command:
+This command collects all the outputs of this page in one run. `--max-run-time 30` limits each run to 30 seconds:
 
 ```bash
 speakeasy -t sample.exe \
@@ -127,8 +98,6 @@ speakeasy -t sample.exe \
   -o report.json
 ```
 
-Use this profile when you want broad telemetry and artifact capture in one run.
-
 ## Related docs
 
 - [Project README](../README.md)

diff --git a/doc/cli-environment-overrides.md b/doc/cli-environment-overrides.md
@@ -1,18 +1,10 @@
 # CLI environment overrides
 
-This page covers flags that shape the emulated host environment and behavior determinism.
+These flags set the identity of the emulated host, the process environment, DNS answers, module loading and API hammering mitigation. At the start of each emulation, Speakeasy logs the active config to stderr, so you can check the values in the log.
 
-## Host, user, and OS identity
+## Host, user and OS identity
 
-Primary flags:
-- `--hostname`
-- `--domain`
-- `--user-name`
-- `--user-is-admin` / `--no-user-is-admin`
-- `--user-sid`
-- `--os-ver-major`, `--os-ver-minor`, `--os-ver-build`
-
-Example: enterprise-like identity profile
+The flags are `--hostname`, `--domain`, `--user-name`, `--user-is-admin` / `--no-user-is-admin`, `--user-sid`, `--os-ver-major`, `--os-ver-minor` and `--os-ver-build`. This example gives a workstation in a corporate domain, with a user that is not an administrator:
 
 ```bash
 speakeasy -t sample.exe \
@@ -27,45 +19,35 @@ speakeasy -t sample.exe \
   -v -o report.json 2> run.log
 ```
 
-Quick verification:
+To check the values:
 
 ```bash
 rg "(hostname|domain|user\.name|user\.sid|user\.is_admin|os_ver\.)" run.log
 ```
 
 ## Process context and environment variables
 
-Primary flags:
-- `--current-dir`
-- `--command-line`
-- `--env KEY=VALUE` (repeatable)
-
-Names are not case-sensitive, and the config stores them in lower case, so `--env TEMP=...` replaces the default `temp`.
-
-Example:
+The flags are `--current-dir`, `--command-line` and `--env KEY=VALUE`. `--env` is repeatable, and each value adds or replaces one variable. The config stores variable names in lower case, because Windows variable names are not case-sensitive. So `--env TEMP=...` replaces the default `temp`.
 
 ```bash
 speakeasy -t sample.exe \
-  --current-dir 'C:\\ProgramData\\Microsoft' \
+  --current-dir 'C:\ProgramData\Microsoft' \
   --command-line 'svchost.exe -k netsvcs -p' \
   --env TEMP=C:\\Windows\\Temp \
   --env APPDATA=C:\\Users\\jdoe\\AppData\\Roaming \
   --env COMPUTERNAME=WS-3471 \
   -v -o report.json 2> run.log
 ```
 
-Quick verification:
+To check the values:
 
 ```bash
 rg "(current_dir|command_line|env =)" run.log
 ```
 
 ## DNS override mappings
 
-Primary flag:
-- `--network-dns-names HOST=IP` (repeatable)
-
-Example: force known C2 host resolutions
+`--network-dns-names HOST=IP` sets the address that a DNS lookup gives for a host name. The flag is repeatable. This example gives addresses for two C2 hosts:
 
 ```bash
 speakeasy -t sample.exe \
@@ -74,23 +56,21 @@ speakeasy -t sample.exe \
   -o report.json
 ```
 
-Quick verification:
+Each lookup gives a `net_dns` event in the report:
 
 ```bash
 jq '.entry_points[].events[]? | select(.event == "net_dns") | {query, response}' report.json
 ```
 
 ## Module load policy and module directories
 
-Some samples (especially shellcode) parse PE export tables directly to resolve API pointers. When expected modules or exports are missing, these controls let you choose strict or permissive behavior.
+By default, `LoadLibrary` fails for a DLL that Speakeasy does not know. With `--modules-always-exist`, the emulator makes a synthetic module for the DLL.
+
+By default, `GetProcAddress` fails for a function that Speakeasy does not know, and a call to such a function ends the run with an `unsupported_api` error. With `--modules-functions-always-exist`, `GetProcAddress` gives an address for the function, and a call to it returns 1.
 
-Primary flags:
-- `--modules-always-exist` / `--no-modules-always-exist`
-- `--modules-functions-always-exist` / `--no-modules-functions-always-exist`
-- `--module-directory-x86`
-- `--module-directory-x64`
+`--module-directory-x86` and `--module-directory-x64` give the directories of real x86 and x64 DLLs. The emulator loads a DLL from the directory of the input architecture in place of its synthetic API module.
 
-Example: relaxed unresolved-import policy with native DLL directories
+This example allows unknown modules and functions, and loads real DLLs from two directories:
 
 ```bash
 speakeasy -t sample.exe \
@@ -101,16 +81,11 @@ speakeasy -t sample.exe \
   -o report.json
 ```
 
-Use this when triaging samples that otherwise stop early on missing modules/APIs.
+Use these flags when a sample stops early because a module or a function is missing.
 
 ## API hammering controls
 
-Primary flags:
-- `--api-hammering-enabled` / `--no-api-hammering-enabled`
-- `--api-hammering-threshold`
-- `--api-hammering-allow-list VALUE` (repeatable)
-
-Example:
+Some samples call an API many times in a loop to make emulation slow. With `--api-hammering-enabled`, the emulator counts the calls to each API from each call site. When the count reaches `--api-hammering-threshold`, the emulator patches an x86 call site so that the call gives 0 and does not run the API. The emulator does not patch x64 code. `--api-hammering-allow-list` gives an API in the form `dll.name` that the emulator does not patch. The flag is repeatable, and its values replace the default allow list.
 
 ```bash
 speakeasy -t sample.exe \
@@ -121,7 +96,7 @@ speakeasy -t sample.exe \
   -o report.json
 ```
 
-This is useful when balancing anti-loop containment with legitimate hot API usage.
+Increase the threshold if the emulator patches calls that the sample needs.
 
 ## Related docs