Quick Start

Overview

This guide will help you get Sogen up and running quickly. We’ll build the emulator, set up the required registry files, and run your first emulated program.

This quick start focuses on Windows with Visual Studio. For other platforms, see the Installation guide.

Prerequisites

Windows operating system
Visual Studio 2022 (with C++ development tools)
Git
Administrator privileges (for registry dump)

Step 1: Clone the Repository

First, clone Sogen with all its submodules:

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

Make sure to use --recurse-submodules as Sogen depends on several external libraries.

Step 2: Generate the Visual Studio Solution

Open an x64 Development Command Prompt and run:

cmake --preset=vs2022

This generates a Visual Studio solution at build/vs2022/emulator.sln.

The preset vs2022 is configured for Visual Studio 2022. The build system will automatically download and configure dependencies.

Step 3: Build the Project

You can build either from the command line or Visual Studio:

cmake --build --preset=release

Open build/vs2022/emulator.sln
Select Release configuration
Build -> Build Solution (or press F7)

The compiled binaries will be in build/vs2022/artifacts/ (or build/release/artifacts/ for command line builds).

Step 4: Create Registry Dump

Sogen needs access to Windows registry data to emulate programs correctly.

Run as Administrator

Right-click on Command Prompt and select “Run as administrator”

Navigate to Sogen Directory

cd path\to\sogen

Execute Registry Dump Script

src\tools\grab-registry.bat

This creates a registry folder with the following files:

SYSTEM
SECURITY
SOFTWARE
HARDWARE
SAM
NTUSER.DAT

Move Registry Folder

Copy the registry folder to the artifacts directory:

move registry build\vs2022\artifacts\registry

The grab-registry.bat script requires administrator privileges to access system registry hives.

Step 5: Run Your First Program

Now you’re ready to emulate a Windows program!

Using the Test Sample

Sogen includes a test sample that validates the emulator:

cd build\vs2022\artifacts
analyzer.exe test-sample.exe

You should see output similar to:

Using emulator backend: unicorn
Running test 'I/O': Success
Running test 'Dir I/O': Success
Running test 'APIs': Success
Running test 'Working Directory': Success
Running test 'Registry': Success
Running test 'System Info': Success
Running test 'Monitor Info': Success
Running test 'Time Zone': Success
Running test 'Threads': Success
Running test 'Threads WinAPI': Success
Running test 'Environment': Success
Running test 'Exceptions': Success
Running test 'Native Exceptions': Success
Running test 'Interrupts': Success
Running test 'TLS': Success
Running test 'Socket': Success
Running test 'APC': Success
Running test 'User Callback': Success
Running test 'Message Queue': Success
Emulation terminated with status: 0

Running Your Own Program

To emulate your own Windows executable:

analyzer.exe C:\path\to\your\program.exe

With Arguments

Pass arguments to the emulated program:

analyzer.exe C:\program.exe arg1 arg2 arg3

Common Options

Here are some useful command-line options:

# See detailed execution information
analyzer.exe -v C:\program.exe

# Launch GDB server on port 28960
analyzer.exe -d --port 28960 C:\program.exe

# Then connect with IDA Pro, GDB, or VS Code

# Monitor a specific DLL's behavior
analyzer.exe -m user32.dll -v C:\program.exe

# Log read/write access to executable memory
analyzer.exe -x C:\program.exe

# Use a custom file system root
analyzer.exe -e C:\emulation_root C:\program.exe

# Suppress most output
analyzer.exe -s C:\program.exe

Understanding the Output

By default, Sogen displays:

Emulator backend: Which CPU emulation engine is being used (Unicorn or Icicle)
Execution logs: System calls, API calls, and other notable events
Exit status: The program’s exit code (0 = success)

Example Output Analysis

Using emulator backend: unicorn
Loaded module: C:\program.exe at 0x140000000
Loaded module: C:\Windows\System32\ntdll.dll at 0x7FFE0000
Loaded module: C:\Windows\System32\kernel32.dll at 0x7FFD0000
Thread 1234 started
Emulation terminated with status: 0

This shows:

The emulator backend in use
Which modules (EXE and DLLs) were loaded and their base addresses
Thread creation
Successful termination (status 0)

Debugging with GDB

Sogen supports the GDB remote protocol, enabling debugging with popular tools:

Start Sogen in Debug Mode

analyzer.exe -d --port 28960 C:\program.exe

The emulator will wait for a debugger to connect.

Connect with Your Debugger

gdb
(gdb) target remote localhost:28960
(gdb) continue

Debugger -> Attach -> Remote GDB debugger
Hostname: localhost
Port: 28960

{
  "type": "cppdbg",
  "request": "launch",
  "name": "Attach to Sogen",
  "miDebuggerServerAddress": "localhost:28960",
  "miDebuggerPath": "/path/to/gdb"
}

Debug as Normal

Set breakpoints, step through code, inspect memory, and use all standard debugging features.

What’s Emulated?

Sogen emulates a comprehensive Windows environment including:

File System: Virtual file system with path mapping
Registry: Full registry access from dumped hives
Threading: Multi-threading with synchronization primitives
Exceptions: SEH (Structured Exception Handling)
Memory: Virtual memory allocation and protection
Networking: Socket operations (UDP/TCP)
Time: System time and timers
User Interface: Basic window messaging (HWND_MESSAGE)

Next Steps

Installation Guide

Learn how to build Sogen on Linux, macOS, and other platforms

Advanced Usage

Explore advanced features like state snapshots, Tenet tracing, and custom hooks

Troubleshooting

”Registry not found” Error

Make sure the registry folder is in the same directory as analyzer.exe, or specify its path:

analyzer.exe -r C:\path\to\registry C:\program.exe

“Failed to load module” Error

Ensure the program is a valid 64-bit Windows PE executable. Sogen currently focuses on x64 emulation.

Crashes or Unexpected Behavior

Try running with verbose logging to see what’s happening:

analyzer.exe -v C:\program.exe

If you encounter bugs, please report them on GitHub Issues.

Get Started

Core Concepts

Usage Guide

Advanced

Overview

Prerequisites

Step 1: Clone the Repository

Step 2: Generate the Visual Studio Solution

Step 3: Build the Project

Step 4: Create Registry Dump

Step 5: Run Your First Program

Using the Test Sample

Running Your Own Program

With Arguments

Common Options

Understanding the Output

Example Output Analysis

Debugging with GDB

What’s Emulated?

Next Steps

Installation Guide

Advanced Usage

Troubleshooting

”Registry not found” Error

“Failed to load module” Error

Crashes or Unexpected Behavior

​Overview

​Prerequisites

​Step 1: Clone the Repository

​Step 2: Generate the Visual Studio Solution

​Step 3: Build the Project

​Step 4: Create Registry Dump

​Step 5: Run Your First Program

​Using the Test Sample

​Running Your Own Program

​With Arguments

​Common Options

​Understanding the Output

​Example Output Analysis

​Debugging with GDB

​What’s Emulated?

​Next Steps

Installation Guide

Advanced Usage

​Troubleshooting

​”Registry not found” Error

​“Failed to load module” Error

​Crashes or Unexpected Behavior

Overview

Prerequisites

Step 1: Clone the Repository

Step 2: Generate the Visual Studio Solution

Step 3: Build the Project

Step 4: Create Registry Dump

Step 5: Run Your First Program

Using the Test Sample

Running Your Own Program

With Arguments

Common Options

Understanding the Output

Example Output Analysis

Debugging with GDB

What’s Emulated?

Next Steps

Troubleshooting

”Registry not found” Error

“Failed to load module” Error

Crashes or Unexpected Behavior