LinuxUserspaceEmulator

LinuxUserspaceEmulator is a small experimental Linux x86_64 userspace emulator. It loads ELF64 guest programs, interprets x86_64 instructions in software, keeps a separate guest address space, and translates guest Linux syscalls to host Linux syscalls.

The project is inspired by the architecture of SerenityOS UserspaceEmulator, but it is not a port of SerenityOS code.

Status

This is a learning and research project, not a production sandbox.

Currently supported:

• static Linux x86_64 ELF programs
• simple dynamically linked glibc programs
• basic virtual memory, brk, mmap, mremap, and file-backed mappings
• common file, time, polling, socket, and signal syscalls
• basic guest signal handling and host signal forwarding
• symbolic guest backtraces for loaded ELF images
• byte-level shadow memory plus register/flags taint propagation, with non-fatal reports for uninitialized memory reads, uninitialized pointer dereferences, and conditional branches that depend on uninitialized data
• x87 FPU and SSE/SSE2 floating-point: scalar and packed single/double arithmetic, integer<->float conversions, and ordered compares, so glibc's printf float formatting and real floating-point guest code run
• malloc tracing for heap overflow writes, use-after-free writes and reads, reads of never-initialized heap, and leaks classified by a reachability graph (definitely lost vs. still reachable)

Known limitations:

• incomplete x86_64 instruction coverage
• no thread or process model for clone, fork, or execve
• taint propagation is whole-result (not bit-precise) and does not cover the x87/SSE register file; no production-grade heap sanitizer
• no full POSIX signal semantics
• no security isolation guarantee

Build

Linux is the intended host platform.

cmake -S . -B build
cmake --build build -j"$(nproc)"

Run

./build/LinuxUserspaceEmulator [options] <program> [args...]

Useful options:

./build/LinuxUserspaceEmulator --help
./build/LinuxUserspaceEmulator --trace-syscalls ./guest-program
./build/LinuxUserspaceEmulator --backtrace-on-exit ./guest-program
./build/LinuxUserspaceEmulator --malloc-trace ./guest-program

Example:

cc -O0 -o /tmp/lue-hello tests/hello-c.c
./build/LinuxUserspaceEmulator /tmp/lue-hello

Expected output:

hello from C guest

Tests

bash tests/run-smoke.sh

The smoke suite builds small guest programs and checks static ELF loading, dynamic glibc startup, arguments and environment, file I/O, mmap/mremap/brk, signal delivery, host signal forwarding, syscall coverage, TLS basics, and symbolic backtraces.

Notes

Unsupported guest instructions or syscalls stop the emulator with the guest RIP, opcode bytes, registers, a symbolic backtrace when available, and mapped memory regions. This makes the next missing piece visible and keeps development incremental.

License

This project is licensed under the MIT License. See LICENSE.