Skip to main content

​
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
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.
1

Run as Administrator

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

Navigate to Sogen Directory

cd path\to\sogen
3

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
4

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

​
Understanding the Output

By default, Sogen displays:
  1. Emulator backend: Which CPU emulation engine is being used (Unicorn or Icicle)
  2. Execution logs: System calls, API calls, and other notable events
  3. 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:
1

Start Sogen in Debug Mode

analyzer.exe -d --port 28960 C:\program.exe
The emulator will wait for a debugger to connect.
2

Connect with Your Debugger

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

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.

Build docs developers (and LLMs) love

Get started for freeTalk to us