{"id":24349124,"url":"https://github.com/x0reaxeax/ns2eb","last_synced_at":"2026-02-06T20:32:40.741Z","repository":{"id":272999597,"uuid":"918426388","full_name":"x0reaxeax/NS2EB","owner":"x0reaxeax","description":"EFI MSR Fuzzer","archived":false,"fork":false,"pushed_at":"2025-01-30T20:42:00.000Z","size":819,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-19T03:14:01.275Z","etag":null,"topics":["cpu","edk2","efi","fuzzer","fuzzing","gnu-efi","msr","tianocore-edk2","undocumented","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/x0reaxeax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-17T22:59:16.000Z","updated_at":"2025-04-12T20:32:33.000Z","dependencies_parsed_at":"2025-04-15T05:48:59.752Z","dependency_job_id":"5829f8fd-1547-468e-8d50-8c70c6dddbf9","html_url":"https://github.com/x0reaxeax/NS2EB","commit_stats":null,"previous_names":["x0reaxeax/ns2eb"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/x0reaxeax/NS2EB","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x0reaxeax%2FNS2EB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x0reaxeax%2FNS2EB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x0reaxeax%2FNS2EB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x0reaxeax%2FNS2EB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/x0reaxeax","download_url":"https://codeload.github.com/x0reaxeax/NS2EB/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x0reaxeax%2FNS2EB/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29175229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T20:14:21.878Z","status":"ssl_error","status_checked_at":"2026-02-06T20:14:21.443Z","response_time":59,"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":["cpu","edk2","efi","fuzzer","fuzzing","gnu-efi","msr","tianocore-edk2","undocumented","x86-64"],"created_at":"2025-01-18T12:31:38.388Z","updated_at":"2026-02-06T20:32:40.723Z","avatar_url":"https://github.com/x0reaxeax.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EFI MSR FUZZER (NS2EB)\n\n### A UEFI MSR Fuzzer for uncovering processor secrets and undocumented MSRs (GNU-EFI version)\n\nNS2EB is a small EFI application for fuzzing Model-Specific Registers (MSRs) in x86_64 processors. Leveraging the fan-favorite [Time Stamp Counter](https://en.wikipedia.org/wiki/Time_Stamp_Counter) (`RDTSC`), custom General Protection Fault interrupt handler, and optionally a disassembly backing via [Zydis-Amalgamated](https://github.com/zyantific/zydis).\n\nAlso comes in **[EDK2 version](https://github.com/x0reaxeax/NS2EB/tree/EDK2)**.\n\n## Table of contents\n * [Features](#features)\n * [Why \"NS2EB\"?](#why-ns2eb)\n * [Getting Started](#getting-started)\n * [Log file](#log-file)\n\t * [Sample Log Format](#sample-log-format)\n* [Graph](#graph)\n* [Anomaly Extraction](#anomaly-extraction)\n* [Customizations](#customizations)\n* [Important Info](#important-info)\n* [Credits](#credits)\n* [Disclaimer](#disclaimer)\n\n### Features\n- **Brute-Force MSR Analysis:** Reads all MSRs from a given range of values (valid and invalid).\n- **Custom GP Fault Handling:** Able to execute invalid MSRs reads by handling GP Faults.\n- **EFI-Based:** Runs natively in UEFI environments, fully isolated from OS-level services overhead.\n- **Performance Modes:** Change testing ranges, verbosity and speed via `NEED_MORE_SPEED` and `MAX_MSR`.\n- **Disassembler-Backed Analysis:** Optionally disassembles faulting instructions for insights.\n- **Graph result overview:** Includes a separate script to visualize execution time flukes.\n\n### Why \"NS2EB\"?\nThis project is fully inspired by Christopher Domas' ([@xoreaxeaxeax](https://github.com/xoreaxeaxeax)) [Project Nightshyft](https://www.youtube.com/watch?v=XH0F9r0siTI), although the original Project Nightshyft was never made public, and was only demonstrated during a conference talk.\nTherefore the super-creative name \"Nightshyft 2: Electric Boogaloo\" was used, however, it should be noted that this program **CANNOT** replicate the quality and functionality of the original project.\nPlease refer to the following picture for technical explanation:\n![supercomputer-generated-explanation](https://i.imgur.com/uHVAxOx.jpeg)\n\n\n### Getting Started\n\n1. **Clone the repo:**\n   ```bash\n   $ git clone https://github.com/x0reaxeax/NS2EB.git\n   $ cd NS2EB\n   ```\n2. **Build the binary:**\n\t```bash\n\t$ make\n\t```\n3. **Copy the binary to a disk or an image on the target system:**\n\tFor testing under QEMU, `Mtools`' `mcopy` can be used to easily write to an image file:\n\t```bash\n\t$ mcopy -i disk.img /path/to/target/efi.efi ::\n\t```\n\tOr deploy to a UEFI-supported system.\n\n\t**NOTE:** QEMU does **NOT** read any actual MSRs from the host system, and all of the MSR support is emulated (unless running in a KVM-accelerated VM, see [Important Info](#important-info)). Observed anomalies are therefore just flukes, and no meaningful data should be expected from emulated runs. \n\t\n4. **Run the EFI application from an EFI Shell:**\n\t```bash\n\t$ efi.efi\n\t```\n \tPreview:\n \t![rundemo](https://i.imgur.com/WRQEo4w.png)\n### Log File\nA logfile with a default name `ns2be.log` is generated on the same drive and directory where the application is located.\n\nThe logfile can be used for creating a graph interpretation of the test.\nSee [Graph](#graph) section for more information.\n\n#### Sample Log Format:\n```\nI=0x00;T=0x1020\nV=0x01;T=0x0F80\nI=0x02;T=0x2280\nI=0x03;T=0x11E0\nI=0x04;T=0x1080\nI=0x05;T=0x0FC0\nI=0x06;T=0x0FE0\nI=0x07;T=0x1200\nI=0x08;T=0x1280\nI=0x09;T=0x1120\nI=0x0A;T=0x12C0\nI=0x0B;T=0x1220\nI=0x0C;T=0x1180\nI=0x0D;T=0x1140\nI=0x0E;T=0x10C0\nI=0x0F;T=0x10C0\nV=0x10;T=0x0CC0\nV=0x11;T=0x0CC0\nV=0x12;T=0x0C40\nI=0x13;T=0x14E0\nI=0x14;T=0x11E0\n``` \n\n`I/V` indicates invalid/valid MSR, and `T` represents the execution timing in cycles.\n\n### Graph\nA standalone Python3 script is included with the project, which can be used to generate a graph of the testing results:\n![qemugraphdemo](https://i.imgur.com/vAUPEf8.png)\n(QEMU demo)\n\nTo build a graph from the results, use the [graph-gen.py](https://github.com/x0reaxeax/NS2EB/blob/main/graph-gen.py) script, with the generated logfile present in the same directory as the script:\n```bash\n$ python3 graph-gen.py\n```\n### Anomaly Extraction\nAnother included script [extract-anomalies.py](https://github.com/x0reaxeax/NS2EB/blob/main/extract-anomalies.py) can help extract anomalies of high-spike clock cycles from the generated logfile.\nSimply run\n```bash\n$ python3 extract-anomalies.py\n```\nwith the logfile present in the same folder as the script.\n\n### Customizations\n\n#### `NEED_MORE_SPEED`\nBy default, a `NEED_MORE_SPEED` mode is active, which limits the number of console outputs when testing the MSRs.\nYou can disable this by commenting the line `#define NEED_MORE_SPEED` in [efi.c](https://github.com/x0reaxeax/NS2EB/blob/main/efi.c), which will allow for displaying the values of all tested MSRs in real-time.\nHowever, since most firmwares are sadly incapable of implementing a well-optimized `SIMPLE_TEXT_OUTPUT` protocol, the testing time will likely increase astronomically:\n\nQEMU virtualized environment with OVMF firmware:\n\n - 65536 (0x10000) MSRs with `NEED_MORE_SPEED`: 3.54 seconds\n - 65536 (0x10000) MSRs without `NEED_MORE_SPEED`: 1 minute 32 seconds\n\nSo yes, just by writing console output in real-time, the testing time increased over 30 times.\n\n#### `MSR_MIN` \u0026 `MSR_MAX`\n\nThese constants control the starting MSR and maximum MSR values to run in the testing loop.\nThis will directly impact the size of the produced logfile.\nSee [Important Info](#important-info) section before changing these.\n\n#### `ZYDIS_DISASM_BACKING`\n\nThis hidden configuration within [CPU.asm](https://github.com/x0reaxeax/NS2EB/blob/main/CPU.asm) will enable [Zydis](https://github.com/zyantific/zydis)-backed verification of fault-generating instructions from within the Interrupt Handler.\n\nThe tool was written on top of this support in the beginning, however, to cut down execution times, it was switched to this naïve error-prone check:\n```c\nif (0x320F == *(UINT16 *) RIP) {\n   /* for sure RDMSR, source: trust me bro */\n}\n```\nYou can re-enable this by adding the following line next to any existing `%define` directive in [CPU.asm](https://github.com/x0reaxeax/NS2EB/blob/main/CPU.asm):\n```\n%define ZYDIS_DISASM_BACKING\n```\n\n### Important Info\n\n* #### Logfile Size\n\t* In order to prevent the logfile growing to massive sizes on the disk, the default `MSR_MAX` value is set to `0x100000` (1'048'576) MSRs, which will consume roughly **19.2MB** of disk space.\n\tIf the value is increased to maximum amount - `0xFFFFFFFF`, it should be expected the logfile growing to around **78.645GB**.\n\tIt is obviously recommended to test with smaller chunks.\n* #### Interrupt Handler and benchmarking\n\t* The Interrupt Handler takes over execution on each attempt to read an invalid MSR, however, it should be noted that the Interrupt Handler executes all of its shenanigans first, before executing the second (closing) `RDTSC` instruction, to calculate a clock diff.\n\t\tThis should hopefully have no significant impact on the results, besides the invalid MSR times having a higher execution time ground.\n\t* This can be also avoided almost completely by placing the `RDTSC` instruction at the top of the Interrupt Handler.\n* #### Testing on a KVM-accelerated VM\n\t* If NS2EB is running inside a KVM-accelerated VM, be aware that some MSRs might be actually passed through to the host system instead of being fully emulated. This means that certain MSRs (e.g., TSC, APERF, MPERF,..) might (probably) return real host values, while other MSRs might be virtualized (e.g., VMX, MTRRs,..) and return fake values.\n* #### Testing on real hardware\n\t* I hope it's fairly obvious that this tool should be used on your own risk, and that I am **NOT** responsible for any damages caused by this educational-purposes-based project.\n\tThis hacky superglued code can go haywire at any moment.\n* #### `ExecFlag` force-termination\n  \t* The displayed `ExecFlag` variable is an `int32` flag that controls the execution of the fuzz loop.\n  \t* Since there's no `CTRL-C`-like event handler, the flag can be used to gracefully terminate the loop early via a debugger or DMA.\n  \t* The displayed value is the address of this flag.\n\n### Credits\n\n - Christopher Domas ([@xoreaxeaxeax](https://github.com/xoreaxeaxeax)) for the idea and the [incredible presentation](https://www.youtube.com/watch?v=XH0F9r0siTI).\n - [Zydis](https://github.com/zyantific/zydis) for amalgamated version of Zydis disassembler\n - [OSDev Wiki](https://wiki.osdev.org/) for technical descriptions\n - GNU-EFI for a lightweight alternative to EDK2\n - ChatGPT for Python scripts, help with EDK2 adaptation, and for mental support 🧡\n\n### Disclaimer\nThis project is licensed under the **MIT License**. The content of this repository exists purely for **educational purposes**, and the author is not responsible for any damages caused by this software.\n\n### License\n\n**MIT License**\n\nCopyright (c) 2025 x0reaxeax\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fx0reaxeax%2Fns2eb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fx0reaxeax%2Fns2eb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fx0reaxeax%2Fns2eb/lists"}