This release is a pre-release and may not be stable for production use.
Sogen exposes Python bindings for its Windows userspace emulator. The Python API is meant for scripting runs, building small analysis helpers, and quickly iterating on callbacks and hooks without rebuilding C++.
Install from PyPI:
pip install sogen
Project links:
- PyPI: https://pypi.org/project/sogen/
- Repository: https://github.com/momo5502/sogen
- Ready-made emulation root: https://sogen.dev/root.zip
What you need
The Python package still needs an emulation root at runtime. Download ready-made root here:
Extract it somewhere convenient, for example:
./root
Most examples in this document use:
emulation_root="./root"
Quick start
import sogen
app = sogen.windows.create_application(
"c:/test-sample.exe",
emulation_root="./root",
)
app.callbacks.on_stdout = lambda text: print(text, end="")
app.start()
print("exit status:", app.process.exit_status)
Minimal example with file + port mappings
from pathlib import Path
import sogen
app = sogen.windows.create_application(
"c:/test-sample.exe",
emulation_root="./root",
path_mappings={"c:/a.txt": Path("./a.txt")},
port_mappings={28970: 28980},
)
app.callbacks.on_stdout = lambda text: print(text, end="")
app.start()
print("exit status:", app.process.exit_status)
Choosing backend
sogen.windows.create_empty() and sogen.windows.create_application() accept an explicit backend.
import sogen
emu = sogen.windows.create_empty(
emulation_root="./root",
backend=sogen.Backend.unicorn,
)
Available values:
sogen.Backend.unicornsogen.Backend.iciclesogen.Backend.whp(Windows)sogen.Backend.kvm(Linux x86_64)
Default is sogen.Backend.unicorn.
High-level structure
Main entry points:
sogen.windows.create_empty(...)sogen.windows.create_application(...)
Compatibility aliases currently remain at top level:
sogen.create_empty(...)sogen.create_application(...)
Common objects exposed by the bindings:
sogen.windows.Emulator/sogen.windows.WindowsEmulatorProcessContextThreadMemoryManagerHooksCallbacks
Common things you will do:
- run application with
app.start() - watch output with
app.callbacks.on_stdout - react to module loads with
app.callbacks.on_module_load - intercept WinAPI calls with
app.hooks.apis[...] - read/write emulator memory with
read_memory()/write_memory() - save and restore state with
save_snapshot()/restore_snapshot()
Callbacks
Example: print loaded modules.
import sogen
app = sogen.windows.create_application(
"c:/test-sample.exe",
emulation_root="./root",
)
def on_module_load(module):
print(f"loaded {module.name} @ 0x{module.entry_point:x}")
app.callbacks.on_module_load = on_module_load
app.start()
Useful callback slots include:
app.callbacks.on_stdoutapp.callbacks.on_syscallapp.callbacks.on_memory_violateapp.callbacks.on_module_loadapp.callbacks.on_module_unload
API hooks
API hooks are registered through app.hooks.apis.
Use @sogen.windows.api_call(...) to describe calling convention and parameters.
Top-level sogen.api_call(...) remains as compatibility alias.
Observe API call, then run original
import ctypes
import sogen
app = sogen.windows.create_application(
"c:/test-sample.exe",
emulation_root="./root",
)
@sogen.windows.api_call(cc=sogen.CallingConvention.stdcall, params=[ctypes.c_uint32])
def on_sleep(call, params):
print(f"Sleep({params[0]})")
app.hooks.apis["Sleep"] = on_sleep
app.start()
Intercept API call and return custom value
import sogen
app = sogen.windows.create_application(
"c:/hook-sample.exe",
emulation_root="./root",
)
@sogen.windows.api_call(cc=sogen.CallingConvention.stdcall, params=[])
def on_get_current_process_id(call, params):
call.return_value = 0xC0FFEE01
return sogen.ApiContinuation.intercept
app.hooks.apis["GetCurrentProcessId"] = on_get_current_process_id
app.start()
print(app.process.exit_status)
Hook keys can be either:
- bare API name, for example
"Sleep" - qualified module form, for example
"kernel32!Sleep"
Memory and state
The emulator exposes direct state access.
import sogen
emu = sogen.windows.create_empty(emulation_root="./root")
base = emu.memory.allocate_memory(0x1000, sogen.MemoryPermission.read_write)
emu.write_memory(base, b"ABCD")
print(emu.read_memory(base, 4))
state = emu.serialize_state()
emu.write_memory(base, b"WXYZ")
emu.deserialize_state(state)
print(emu.read_memory(base, 4))
For checkpoint-style workflows, use snapshots:
emu.save_snapshot()
# ... mutate state ...
emu.restore_snapshot()
Examples
Small runnable example:
examples/python/basic_usage.py
Example setup notes:
examples/python/README.md
Current limitations / expectations
- bindings require an emulation root
- samples in this repo assume Windows-style guest paths like
c:/... - some workflows are easiest to validate against repo sample binaries such as
test-sample.exeandhook-sample.exe - backend availability depends on platform and how Sogen was built
1 maintainer
Metadata
1 maintainer
Release files for sogen 0.0.1.dev4300
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sogen-0.0.1.dev4300.tar.gz | 44.9 MB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| sogen-0.0.1.dev4300-cp39-cp39-win_amd64.whl | CPython 3.9 | CPython 3.9 | Windows x86-64 | Details |
| sogen-0.0.1.dev4300-cp39-cp39-manylinux_2_39_x86_64.whl | CPython 3.9 | CPython 3.9 | Linux glibc 2.39+ x86-64 | Details |
| sogen-0.0.1.dev4300-cp39-cp39-macosx_11_0_arm64.whl | CPython 3.9 | CPython 3.9 | macOS 11.0+ ARM64 | Details |
| sogen-0.0.1.dev4300-cp39-cp39-macosx_10_13_x86_64.whl | CPython 3.9 | CPython 3.9 | macOS 10.13+ x86-64 | Details |
Total release size: 71.4 MB
Release files / sogen-0.0.1.dev4300.tar.gz
| Download URL | sogen-0.0.1.dev4300.tar.gz |
|---|---|
| Size | 44.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b1ffabaa18a2ecc5ebfe463a688f052d4ed4979a8842f1b24080a5ec35d0cbdb
|
|
BLAKE2b-256 checksum How to use checksums |
529ca0a82018a8c930bb7ad7d0e1f6f73653c72670b024ecab086b6fabe6e3cf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / sogen-0.0.1.dev4300-cp39-cp39-win_amd64.whl
| Download URL | sogen-0.0.1.dev4300-cp39-cp39-win_amd64.whl |
|---|---|
| Size | 5.0 MB |
| Tags | CPython 3.9 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
a21a4cccec71fccbef2b48670cff15c441bf38aed8a1adbf47a36649aab430ab
|
|
BLAKE2b-256 checksum How to use checksums |
acc3325293f72b0ce60839b6bd2adb589e78504d4a26fdf46baf3809763f1a44
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / sogen-0.0.1.dev4300-cp39-cp39-manylinux_2_39_x86_64.whl
| Download URL | sogen-0.0.1.dev4300-cp39-cp39-manylinux_2_39_x86_64.whl |
|---|---|
| Size | 8.8 MB |
| Tags | CPython 3.9 Linux glibc 2.39+ x86-64 |
|
SHA-256 checksum How to use checksums |
160a72a61118dcc90d4a6b2f7eee62ae8a4e38554c136bb9e20baf4e94e472cd
|
|
BLAKE2b-256 checksum How to use checksums |
91896adc5f7155d7a9c97ce7e6b45c1f46c3734227ffdfe290a06fc6670e3fc3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / sogen-0.0.1.dev4300-cp39-cp39-macosx_11_0_arm64.whl
| Download URL | sogen-0.0.1.dev4300-cp39-cp39-macosx_11_0_arm64.whl |
|---|---|
| Size | 5.9 MB |
| Tags | CPython 3.9 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
e9ae217d2c4031206aa6bcab45af41b100cf81a1b01e9595409319ecfc195268
|
|
BLAKE2b-256 checksum How to use checksums |
20de53a8b1908e70686529867ace054f4b6b808b3b72850d43eb2da4f7c99da2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / sogen-0.0.1.dev4300-cp39-cp39-macosx_10_13_x86_64.whl
| Download URL | sogen-0.0.1.dev4300-cp39-cp39-macosx_10_13_x86_64.whl |
|---|---|
| Size | 6.9 MB |
| Tags | CPython 3.9 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
61b1ad4f217c1962f12399c696a6c26b81c8a6f97a73e3c0470860770be52687
|
|
BLAKE2b-256 checksum How to use checksums |
f79aceb0f1d2b9a94e2becd0846d919aaa0c999cf1a438e212e5d1f2122d2404
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency log
