sogen: a userspace emulator that runs real Windows DLLs

What sogen is for, and who actually needs it

Sogen answers a narrow question: what is this binary doing, instruction by instruction, without a real operating system underneath it. The README states the design goal directly: instead of reimplementing thousands of OS APIs, Sogen emulates binaries at CPU and syscall level and runs the real system DLLs. That single decision separates it from Wine-style compatibility layers, which reimplement API behaviour and therefore diverge from the real OS in ways that matter when you are analysing malware or studying undocumented internals.

The audience follows from that. Reverse engineers who want to watch a sample's memory accesses and API calls fall into the first group. So do researchers who need deterministic runs, since the README claims every run is reproducible down to the instruction, and full state serialization with fast in-memory snapshots. The README also pitches game sandboxing, with Direct3D 8 through 11 titles running through DXVK over a GPU bridge. That is a real capability, but it is the part of the project most dependent on your host hardware and backend choice, and the README does not quantify performance.

Real system DLLs plus a pluggable CPU backend

The architecture has two layers that are worth separating. The bottom layer is a CPU backend, and the README lists five: Unicorn Engine, icicle-emu, Hyper-V (WHP), KVM and FEX. The top layer is the Windows personality: PE loading with relocations and TLS, Windows memory types, SEH, threading, the registry, filesystem and networking. Because the real ntdll, kernel32 and user32 are loaded rather than stubbed, the emulator only has to get the syscall boundary and the memory model right, and the DLLs supply the rest.

That choice has consequences. Determinism is achievable because the CPU is interpreted or virtualised under your control, and hooking is possible at every level: memory, instructions, syscalls and API calls. It also means the emulation root, the directory holding the system files the DLLs need, is a hard requirement rather than a convenience. The README points at a downloadable root archive and at a wiki page titled Run The Emulator for building your own. The debugging story is the same idea applied to tooling: the README says the debugger runs at the emulator level, outside the process, so it stays invisible to anti-debug checks, and that IDA Pro or GDB can connect over the GDB protocol.

Installing the Python bindings and hooking an entry point

The fastest path into Sogen is the Python package, which the README says installs with pip. The pyproject.toml confirms the package name is sogen, requires Python 3.9 or later, and builds through scikit-build-core, so the wheel compiles the C++ core rather than shipping a pure-Python wrapper.

pip install sogen

Before any emulation runs you need an emulation root. The README offers two routes: download a ready-made root, or build your own following the wiki instructions. The example below assumes a root directory next to your script and a sample at c:/test-sample.exe.

import sogen

emu = sogen.windows.create_application("c:/test-sample.exe", emulation_root="./root")


def on_module_load(module):
    if module.name.lower() == "test-sample.exe":
        emu.hooks.memory_execution_at(module.entry_point, lambda address: print(f"hit entry point: 0x{address:x}"))

emu.callbacks.on_module_load = on_module_load
emu.start()
print(emu.process.exit_status)

What you should see is the entry point address printed once execution reaches it, followed by the process exit status after the emulator stops. The README points to examples/python/README.md for setup details and a larger example, and notes that Dart bindings live in a separate repository.

Building from source on Windows with the vs2022 preset

If you want the analyzer binary rather than the Python module, the README gives a Windows and Visual Studio quick start. The clone must be recursive because the CPU backends and other dependencies live in submodules.

git clone --recurse-submodules https://github.com/momo5502/sogen.git
cmake --preset=vs2022

Run the second command in an x64 Development Command Prompt inside the cloned directory. It generates a solution at build/vs2022/sogen.sln, which you then build. After that, the README asks for a registry dump produced by running grab-registry.bat as administrator, placed in the artifacts folder next to analyzer.exe. Only then does the final step work.

analyzer.exe C:\example.exe

Two things stand out here. The registry dump step is Windows-specific and administrator-only, so the quick start does not transfer to Linux or macOS even though the README lists those platforms as supported. And the wiki is the only documented route for the non-Windows build, which means the README alone will not get you running on a Linux host.

Where sogen is the wrong tool

Sogen is not a general-purpose way to run Windows software on Linux. The emulation root is a prerequisite you must assemble, the registry snapshot has to come from a real Windows installation, and the README does not describe a fallback for applications that depend on drivers or kernel-mode components, which a userspace emulator cannot provide by construction.

There is also a build-level caveat worth reading closely. The pyproject.toml disables link-time optimisation for the wheel build with SOGEN_ENABLE_LTO = "OFF", and the comment above that setting explains why: LTO has been observed to break the api_hook intercept's RIP redirect inside the UC_HOOK_CODE callback, where writes succeed and the readback shows the new value but the Unicorn JIT keeps executing the original instruction. That is a documented correctness hazard tied to one backend and one optimisation setting, and it tells you the hooking layer is sensitive to how the binary is compiled. If you build your own wheel or change that flag, treat hook behaviour as something to re-verify rather than assume.

The game sandboxing claim is the other place to be careful. The README says Direct3D 8 through 11 titles run through DXVK, which translates Direct3D to Vulkan on top of the GPU bridge, and that the Hyper-V backend runs code natively on the CPU. It gives no frame rates, no list of tested titles, and no hardware requirements. Anyone whose reason for looking at Sogen is gaming should treat that as unverified.

How it compares with Unicorn Engine alone

Unicorn Engine is the closest point of reference because Sogen uses it as one of its CPU backends. Unicorn gives you a CPU and memory, and nothing else: no PE loader, no ntdll, no registry, no threading model. You write the loader and the syscall handlers yourself, which is fine for shellcode and firmware fragments and painful for a full Windows executable that expects a filesystem and a registry.

Sogen takes that same CPU layer and puts a Windows personality on top, which is the whole reason the real DLLs can run. The trade-off is weight. A Unicorn script is a pip install and a few dozen lines. Sogen needs an emulation root, and on Windows a registry dump, before the first instruction executes. If your target is a self-contained blob with no OS dependencies, Unicorn is the smaller tool and you should reach for it first. If your target is a PE that calls into kernel32, Sogen is doing work you would otherwise have to write.

Licence and the cost of staying current

Sogen is GPL-2.0, and the Python package metadata declares GPL-2.0-only. That matters more than usual here because the project is a library as well as an application. Linking the emulator into a proprietary analysis tool, or shipping a modified build inside a closed product, runs into the copyleft terms, and the repository does not offer an alternative licence. If your use is internal research or a GPL-compatible tool, the licence is not an obstacle. If you plan to redistribute a product built on it, read the GPL-2.0 text and talk to whoever handles licensing at your organisation. This is a description of the terms, not legal advice.

On maintenance, the last push to the default branch was on 2026-09-22, and the repository is not archived. Upgrade cost is dominated by the submodules in deps/ and by the CMake presets. A recursive clone ties you to whatever revisions the submodules point at, so pulling a new commit can move the Unicorn, icicle-emu or SDL3 revisions underneath you. The pyproject.toml also carries a Linux-specific workaround, SDL_UNIX_CONSOLE_BUILD = "ON", so that source installs succeed on headless systems where X11 and Wayland development libraries are absent. Expect that kind of platform fix to keep appearing in the build configuration rather than in release notes, since the repository has no published releases.

Editorial conclusion

Adopt sogen if you need instruction-level visibility into a Windows binary, deterministic replay, or state snapshots that a real debugger cannot give you, and you are comfortable building a C++ project with CMake presets or installing the pip package. Do not adopt it if you want a drop-in way to run arbitrary Windows software on Linux, because it is an emulator with an emulation root you must provision yourself. Before committing, verify which CPU backend fits your host, confirm that the registry dump step applies to your platform, and check whether the Python wheel builds cleanly on your machine given that the pyproject.toml disables LTO for the wheel build.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. momo5502/sogen on GitHub
4. Project website
5. README