This release is a pre-release and may not be stable for production use.
Sogen exposes Python bindings for Windows and Linux userspace emulation. The Python API is meant for scripting runs, building small analysis helpers, and quickly iterating on callbacks; Windows bindings also expose hooks for deeper analysis.
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)
Linux quick start:
import sogen
app = sogen.linux.create_application(
"/bin/true",
emulation_root="/",
backend=sogen.Backend.unicorn,
)
app.start()
print("exit status:", app.process.exit_status)
sogen.linux does not use the root-level sogen.create_application(...) compatibility alias.
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(), sogen.windows.create_application(), and sogen.linux.create_application() accept backend=sogen.Backend.unicorn.
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
Windows entry points:
sogen.windows.create_empty(...)sogen.windows.create_application(...)
Linux entry point:
sogen.linux.create_application(...)
Windows compatibility aliases currently remain at top level:
sogen.create_empty(...)sogen.create_application(...)
Objects exposed by the Windows bindings:
sogen.windows.Emulator/sogen.windows.WindowsEmulatorProcessContextThreadMemoryManagerHooksCallbacks
Linux-specific objects exposed by the bindings:
sogen.linux.Emulator/sogen.linux.LinuxEmulatorsogen.linux.ProcessContextsogen.linux.MemoryManagersogen.linux.Callbacks
Common Windows workflows:
- 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 examples:
examples/python/basic_usage.pyfor Windowsexamples/python/linux_true.pyfor Linux
Example setup notes:
examples/python/README.md
Current limitations / expectations
- Windows bindings require an emulation root
- Windows samples in this repo assume Windows-style guest paths like
c:/... - Windows 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.dev4433
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.dev4433.tar.gz | 46.4 MB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| sogen-0.0.1.dev4433-cp39-cp39-win_amd64.whl | CPython 3.9 | CPython 3.9 | Windows x86-64 | Details |
| sogen-0.0.1.dev4433-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.dev4433-cp39-cp39-macosx_11_0_arm64.whl | CPython 3.9 | CPython 3.9 | macOS 11.0+ ARM64 | Details |
| sogen-0.0.1.dev4433-cp39-cp39-macosx_10_13_x86_64.whl | CPython 3.9 | CPython 3.9 | macOS 10.13+ x86-64 | Details |
Total release size: 73.4 MB
Release files / sogen-0.0.1.dev4433.tar.gz
| Download URL | sogen-0.0.1.dev4433.tar.gz |
|---|---|
| Size | 46.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
caff64806ca90b7b22b816d817c99b99c3ae673e12ef3e10debeb264acc43155
|
|
BLAKE2b-256 checksum How to use checksums |
46b2743859a1635b23ccc246b5671d6ccae85f3d8e4c3806e586fc8dd8bfca82
|
| 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 Jul 2, 2026.
Transparency logRelease files / sogen-0.0.1.dev4433-cp39-cp39-win_amd64.whl
| Download URL | sogen-0.0.1.dev4433-cp39-cp39-win_amd64.whl |
|---|---|
| Size | 5.1 MB |
| Tags | CPython 3.9 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
5faed844b5a60d56d13805a2942832d934ea0efd1a841fb6183e643740f253eb
|
|
BLAKE2b-256 checksum How to use checksums |
e33d81508c227a52fc35ecc1204bf6729dd9e143cbf5d512882d5a3202116b41
|
| 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 Jul 2, 2026.
Transparency logRelease files / sogen-0.0.1.dev4433-cp39-cp39-manylinux_2_39_x86_64.whl
| Download URL | sogen-0.0.1.dev4433-cp39-cp39-manylinux_2_39_x86_64.whl |
|---|---|
| Size | 9.0 MB |
| Tags | CPython 3.9 Linux glibc 2.39+ x86-64 |
|
SHA-256 checksum How to use checksums |
d25fc520c92b174c1110a52e3c17debfdbbbc879100f6517f09155521b3e5ac2
|
|
BLAKE2b-256 checksum How to use checksums |
4a5f8183930253c99b76b3b1fca54ddd24ea1a578a91ace19045340831e4bd06
|
| 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 Jul 2, 2026.
Transparency logRelease files / sogen-0.0.1.dev4433-cp39-cp39-macosx_11_0_arm64.whl
| Download URL | sogen-0.0.1.dev4433-cp39-cp39-macosx_11_0_arm64.whl |
|---|---|
| Size | 6.0 MB |
| Tags | CPython 3.9 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
6b42901ff8e756e473d765f885c05787708997d20fa5920365ed340483d4e7d1
|
|
BLAKE2b-256 checksum How to use checksums |
711363ed8ba04f5e30304f7aef4f4efaa0891c8246295bdac57b7d4372a466ca
|
| 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 Jul 2, 2026.
Transparency logRelease files / sogen-0.0.1.dev4433-cp39-cp39-macosx_10_13_x86_64.whl
| Download URL | sogen-0.0.1.dev4433-cp39-cp39-macosx_10_13_x86_64.whl |
|---|---|
| Size | 7.0 MB |
| Tags | CPython 3.9 macOS 10.13+ x86-64 |
|
SHA-256 checksum How to use checksums |
6625de56f47334b8ebc62c25cab0f48ebbbb221ee42d601a4285d49a017c677d
|
|
BLAKE2b-256 checksum How to use checksums |
cf2f92ce1365fbfca55afee37e014e1f3f795d43d2fea2158a03b075e463557d
|
| 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 Jul 2, 2026.
Transparency log
