sogen 0.0.1.dev4399

Sogen Windows user-space emulator bindings

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:

• https://sogen.dev/root.zip

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.unicorn
• sogen.Backend.icicle
• sogen.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.WindowsEmulator
• ProcessContext
• Thread
• MemoryManager
• Hooks
• Callbacks

Linux-specific objects exposed by the bindings:

• sogen.linux.Emulator / sogen.linux.LinuxEmulator
• sogen.linux.ProcessContext
• sogen.linux.MemoryManager
• sogen.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_stdout
• app.callbacks.on_syscall
• app.callbacks.on_memory_violate
• app.callbacks.on_module_load
• app.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.py for Windows
• examples/python/linux_true.py for 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.exe and hook-sample.exe
• backend availability depends on platform and how Sogen was built