Metadata-Version: 2.1
Name: sogen
Version: 0.0.1.dev3458
Summary: Sogen Windows user-space emulator bindings
Author: momo5502
License: GPL-2.0-only
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Requires-Python: >=3.12
Description-Content-Type: text/markdown

<h1 align="center">
	<a href="https://github.com/momo5502/sogen"><img src="https://momo5502.com/sogen/banner.png" height="300" /></a>
	<br>
	<a href="https://github.com/momo5502/sogen?tab=GPL-2.0-1-ov-file"><img src="https://img.shields.io/github/license/momo5502/sogen?color=00B0F8"/></a>
	<a href="https://github.com/momo5502/sogen/actions"><img src="https://img.shields.io/github/actions/workflow/status/momo5502/sogen/build.yml?branch=main&label=build"/></a>
	<a href="https://github.com/momo5502/sogen/issues"><img src="https://img.shields.io/github/issues/momo5502/sogen?color=F8B000"/></a>
	<img src="https://img.shields.io/github/commit-activity/m/momo5502/sogen?color=FF3131"/>
</h1>

Sogen is a high-performance Windows user space emulator that operates at syscall level, providing full control over process execution through comprehensive hooking capabilities.

Perfect for security research, malware analysis, and DRM research where fine-grained control over process execution is required.

Built in C++ and powered by the backend of your choice:

- [Unicorn Engine](https://github.com/unicorn-engine/unicorn)
- [icicle-emu](https://github.com/icicle-emu/icicle-emu)
- [Hyper-V (WHP)](https://learn.microsoft.com/en-us/virtualization/api/hypervisor-platform/hypervisor-platform)

Try it out: <a href="https://sogen.dev">sogen.dev</a>

<hr>

> [!WARNING]  
> Caution is advised when analyzing malware in Sogen, as host isolation might not be perfect.  
> To mitigate potential risk, use the <a href="https://sogen.dev/#/playground">web version</a> to benefit from the additional safety provided by your browser's sandbox.

## Key Features

- 🔄 **Syscall-Level Emulation**
  - Instead of reimplementing Windows APIs, the emulator operates at the syscall level, allowing it to leverage existing system DLLs
- 📝 **Advanced Memory Management**
  - Supports Windows-specific memory types including reserved, committed, built on top of Unicorn's memory management
- 📦 **Complete PE Loading**
  - Handles executable and DLL loading with proper memory mapping, relocations, and TLS
- ⚡ **Exception Handling**
  - Implements Windows structured exception handling (SEH) with proper exception dispatcher and unwinding support
- 🧵 **Threading Support**
  - Provides a scheduled (round-robin) threading model
- 💾 **State Management**
  - Supports both full state serialization and fast in-memory snapshots
- 💻 **Debugging Interface**
  - Implements GDB serial protocol for integration with common debugging tools (IDA Pro, GDB, LLDB, VS Code, ...)

## Preview

![Preview](https://momo5502.com/sogen/preview.svg)

## YouTube Overview

<a href="https://www.youtube.com/watch?v=wY9Q0DhodOQ" target="_blank">
  <img src="https://momo5502.com/sogen/video.png" alt="YouTube Video" width="600" />
</a>

Click <a href="https://docs.google.com/presentation/d/1pha4tFfDMpVzJ_ehJJ21SA_HAWkufQBVYQvh1IFhVls/edit">here</a> for the slides.

## Python Bindings

Install with:

```bash
pip install sogen
```

Example:

```python
import sogen

emu = sogen.create_application("c:/test-sample.exe", None, 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)
```

See `examples/python/README.md` for a slightly larger example.

## Quick Start (Windows + Visual Studio)

> [!TIP]  
> Checkout the [Wiki](https://github.com/momo5502/sogen/wiki) for more details on how to build & run the emulator on Windows, Linux, macOS, ...

1\. Checkout the code:

```bash
git clone --recurse-submodules https://github.com/momo5502/sogen.git
```

2\. Run the following command in an x64 Development Command Prompt in the cloned directory:

```bash
cmake --preset=vs2022
```

3\. Build the solution that was generated at `build/vs2022/emulator.sln`

4\. Create a registry dump by running the [grab-registry.bat](https://github.com/momo5502/sogen/blob/main/src/tools/grab-registry.bat) as administrator and place it in the artifacts folder next to the `analyzer.exe`

5\. Run the program of your choice:

```bash
analyzer.exe C:\example.exe
```
