{"id":20961233,"url":"https://github.com/jbouron/x86lab","last_synced_at":"2026-04-15T18:02:04.365Z","repository":{"id":230339740,"uuid":"582898153","full_name":"JBouron/x86Lab","owner":"JBouron","description":"A playground for x86 assembly programming.","archived":false,"fork":false,"pushed_at":"2024-03-29T03:48:15.000Z","size":1030,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-07T14:59:23.709Z","etag":null,"topics":["assembly","x86","x86-64"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JBouron.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-12-28T07:06:42.000Z","updated_at":"2024-04-01T17:52:36.000Z","dependencies_parsed_at":"2024-03-29T05:48:56.630Z","dependency_job_id":null,"html_url":"https://github.com/JBouron/x86Lab","commit_stats":null,"previous_names":["jbouron/x86lab"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/JBouron/x86Lab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JBouron%2Fx86Lab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JBouron%2Fx86Lab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JBouron%2Fx86Lab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JBouron%2Fx86Lab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JBouron","download_url":"https://codeload.github.com/JBouron/x86Lab/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JBouron%2Fx86Lab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31853279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembly","x86","x86-64"],"created_at":"2024-11-19T02:01:59.961Z","updated_at":"2026-04-15T18:02:04.346Z","avatar_url":"https://github.com/JBouron.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# x86Lab\n\nA playground for x86 assembly programming.\n\n## What is it?\nx86Lab is an application that allows you to execute an x86 assembly snippet\nstep-by-step while showing in real time the effect each instruction has on the\nstate of the CPU and memory.\n\nThe main goal is to make it easy to explore and experiment with x86 assembly\nprogramming. This is a tool that can be useful as part of learning x86\nprogramming, reverse-engineering, or simply to quickly check the behaviour of a\nparticular instruction.\n\n![Alt text](/screenshots/screenshot1.png?raw=true \"x86Lab\")\n\n\u003e Disclaimer: This project is still in a Work-In-Progress state. While most of\n\u003e the basic functionalities are implemented, the UI is still rough around the\n\u003e edges, the implementation is a bit of a mess and there are still a few bugs to\n\u003e squash. Despite this, x86Lab still managed to prove itself useful to me, hence\n\u003e I am planning on continuing its development.\n\n## Why?\nImagine you have a small snippet of x86 assembly, maybe this is some code that\nyou found while reverse-engineering, or maybe this is some code you came up with\nyourself and that you want to check for correctness. You are interested in\nunderstanding how this code works and how each instruction it contains affects\nthe state of the CPU registers and memory.\n\nx86Lab allows you to do just that in an easy and fast manner.\n\nPrior to x86Lab the solution typically involved compiling the snippet with NASM\n(or other assembler) and running it under `gdb` in order to be able to execute\nthe code step-by-step. You would then be able to analyze the state of the CPU\nregisters and memory using `gdb`'s interactive command line. This setup,\nhowever, has a lot of downsides:\n- You need to write the snippet in such a way that it can be assembled into an\n  ELF executable, i.e. you need to define a global `_start` label, a `.text`\n  section, ...\n- For this particular use case, `gdb`'s interface is a bit clunky. You have to\n  manually input the `x` and `info registers` commands in order to get the state\n  of the CPU/memory after every step.\n- `gdb` does not provide backward step-by-step execution, at least not by\n  default.\n- Since the assembly code is running in a user-space process, the code cannot\n  execute any privileged instructions. It also cannot execute 16-bit/real-mode\n  code.\n\nThe motivation behind x86Lab was to make this process as painless as possible:\nyou input the assembly snippet and you can immediately start executing it\nstep-by-step forward and backward, all while seeing in real time the effect each\ninstruction has on the CPU and memory. On top of this, x86Lab also supports\nrunning 16, 32 and 64 bit code at any privilege level.\n\n## How does it work?\nx86Lab takes a path to an assembly snippet as argument, this snippet must be\ncompatible with the [Netwide Assembler (NASM)](https://www.nasm.us/) however it\ndoes not need to define any section or even a `_start` label, the file can\nsimply contain a listing of instructions. x86Lab assembles the assembly snippet\nusing NASM and loads the resulting machine code into a small KVM virtual\nmachine. The user-interface then allows you to execute the assembled code\nstep-by-step forward and backward all while showing the current state of the CPU\nand memory.\n\nBecause the code is executed within a KVM virtual machine, it can execute\nprivileged instructions and switch to real-mode, 32-bit mode or 64-bit mode.\n\nAssembly snippets run within x86Lab are expected to be typically small,\ntherefore the KVM virtual machine instantiated by x86Lab is very light: a single\nvirtual core with a few kilobytes of memory.\n\n## Features\nThe main features currently implemented are:\n- Forward and backward step-by-step execution.\n- Running the VM in 16, 32 and 64 bit mode.\n- Display the state of the current stack.\n- Display the content of the memory (physical and virtual addressing mode) with\n  multiple formatting options (bytes, words, dwords, qwords, floats and\n  doubles).\n- Display the state of the CPU general purpose registers, MMX/SSE/AVX registers\n  (including AVX-512/zmm), control registers, segment registers.\n- Display the state of the GDT and IDT pointed by the GDTR and IDTR\n  respectively.\n- Display the state of the page-table structure currently loaded into CR3.\n\nA few features that I plan on eventually adding (non-exhaustive list):\n- Add a text editor to input the snippet instead of having to load a file from\n  disk. This would make the experience much nicer.\n- Display the state of the APIC registers.\n- Display the state of the x87 floating point registers (this would be a\n  formatting option in the MMX tab).\n- A way to modify a register's value or a memory location through the UI.\n- Display the state of the CPU's Task Register.\n\nBefore introducing new features, the code needs a good clean-up and the UI some\nrefinements.\n\n## Building\n\nThe program has a few dependencies:\n- SDL2 for the UI, install `libsdl2-dev` on Ubuntu or `sdl2` on Arch Linux.\n- Capstone for the disassembler, install `libcapstone-dev` on Ubuntu or\n  `capstone` on Arch Linux.\n\nCompiling is as simple as running `make`. It is recommended that you also run\nthe tests using `make test`.\n\n## Usage\nThe program takes a single argument, the path to the file that contains the\nassembly code to be assembled and analyzed.\n\nThe program provides keyboard shortcuts for the most common operations:\n- `q` to quit\n- `s` to step one instruction forward\n- `r` to step one instruction backward\n\nThe `example/` directory contains an assembly snippet that starts in real-mode\nand jumps into protected mode and then 64-bit mode. You can execute it as\nfollows:\n```\n./x86lab examples/jumpToProtectedAndLongModes.asm\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbouron%2Fx86lab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjbouron%2Fx86lab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbouron%2Fx86lab/lists"}