hexcore-unicorn 1.2.0

package/README.md

@@ -0,0 +1,307 @@
+# HexCore Unicorn
+
+Modern Node.js bindings for the [Unicorn Engine](https://www.unicorn-engine.org/) CPU emulator using N-API.
+
+Part of the **HikariSystem HexCore** binary analysis IDE.
+
+## Features
+
+- Full Unicorn Engine API support
+- Modern N-API bindings (ABI stable)
+- Async emulation with Promises
+- TypeScript definitions included
+- Hook system with ThreadSafeFunction
+- Support for all architectures: x86, ARM, ARM64, MIPS, SPARC, PPC, M68K, RISC-V
+- Context save/restore
+- Memory mapping and protection
+- **Native Breakpoints (O(1) lookup)**
+- **Shared Memory Support (GC Safe)**
+- **State Snapshotting (Save/Restore)**
+
+## Installation
+
+```bash
+npm install hexcore-unicorn
+```
+
+**Note:** You need to have the Unicorn library installed on your system or place the library files in the `deps/unicorn/` directory.
+
+### Building from source
+
+```bash
+git clone https://github.com/LXrdKnowkill/hexcore-unicorn.git
+cd hexcore-unicorn
+npm install
+npm run build
+```
+
+## Quick Start
+
+```javascript
+const { Unicorn, ARCH, MODE, PROT, X86_REG } = require('hexcore-unicorn');
+
+// Create x86-64 emulator
+const uc = new Unicorn(ARCH.X86, MODE.MODE_64);
+
+// Map memory for code and stack
+uc.memMap(0x1000n, 0x1000, PROT.ALL);  // Code
+uc.memMap(0x2000n, 0x1000, PROT.ALL);  // Stack
+
+// Write x86-64 code: mov rax, 0x1234; ret
+const code = Buffer.from([
+    0x48, 0xC7, 0xC0, 0x34, 0x12, 0x00, 0x00,  // mov rax, 0x1234
+    0xC3                                        // ret
+]);
+uc.memWrite(0x1000n, code);
+
+// Set up stack pointer
+uc.regWrite(X86_REG.RSP, 0x2800n);
+
+// Run emulation
+uc.emuStart(0x1000n, 0x1008n);
+
+// Read result
+const rax = uc.regRead(X86_REG.RAX);
+console.log(`RAX = 0x${rax.toString(16)}`);  // RAX = 0x1234
+
+// Clean up
+uc.close();
+```
+
+## API Reference
+
+### Creating an Emulator
+
+```javascript
+const uc = new Unicorn(arch, mode);
+```
+
+- `arch`: Architecture constant (e.g., `ARCH.X86`, `ARCH.ARM64`)
+- `mode`: Mode constant (e.g., `MODE.MODE_64`, `MODE.UC_MODE_ARM`)
+
+### Memory Operations
+
+```javascript
+// Map memory
+uc.memMap(address, size, permissions);
+
+// Read memory
+const buffer = uc.memRead(address, size);
+
+// Write memory
+uc.memWrite(address, buffer);
+
+// Unmap memory
+uc.memUnmap(address, size);
+
+// Change permissions
+uc.memProtect(address, size, permissions);
+
+// Get mapped regions
+const regions = uc.memRegions();
+// Returns: [{ begin: bigint, end: bigint, perms: number }, ...]
+```
+
+### Register Operations
+
+```javascript
+// Read register
+const value = uc.regRead(X86_REG.RAX);
+
+// Write register
+uc.regWrite(X86_REG.RAX, 0x1234n);
+
+// Batch operations
+const values = uc.regReadBatch([X86_REG.RAX, X86_REG.RBX]);
+uc.regWriteBatch([X86_REG.RAX, X86_REG.RBX], [0x1111n, 0x2222n]);
+```
+
+### Emulation Control
+
+```javascript
+// Synchronous emulation
+uc.emuStart(begin, until, timeout, count);
+
+// Asynchronous emulation
+await uc.emuStartAsync(begin, until, timeout, count);
+
+// Stop emulation (from hook)
+uc.emuStop();
+```
+
+### Hooks
+
+```javascript
+// Code execution hook
+const handle = uc.hookAdd(HOOK.CODE, (address, size) => {
+    console.log(`Executing: 0x${address.toString(16)}`);
+});
+
+// Memory access hook
+uc.hookAdd(HOOK.MEM_WRITE, (type, address, size, value) => {
+    console.log(`Memory write at 0x${address.toString(16)}`);
+});
+
+// Interrupt hook
+uc.hookAdd(HOOK.INTR, (intno) => {
+    console.log(`Interrupt: ${intno}`);
+});
+
+// Remove hook
+uc.hookDel(handle);
+```
+
+### Context Management
+
+```javascript
+// Save context
+const ctx = uc.contextSave();
+
+// Restore context
+uc.contextRestore(ctx);
+
+// Free context
+ctx.free();
+```
+
+### Native Breakpoints (High Performance)
+
+```javascript
+// Add a native breakpoint (Zero overhead until hit)
+uc.breakpointAdd(0x1000n);
+
+// Remove breakpoint
+uc.breakpointDel(0x1000n);
+```
+
+### Shared Memory (Zero-Copy & GC Safe)
+
+```javascript
+// Create shared buffer
+const sab = new SharedArrayBuffer(4096);
+const buffer = Buffer.from(sab);
+
+// Map it (Unicorn keeps a reference to prevent GC)
+uc.memMapPtr(0x10000n, buffer, PROT.ALL);
+
+// usage: write to 'buffer' in JS, read instanly in Unicorn
+```
+
+### State Snapshotting (Time Travel)
+
+```javascript
+// Save full state (Context + RAM)
+const snapshot = uc.stateSave();
+
+// ... execute more code ...
+
+// Restore state (Rewind)
+uc.stateRestore(snapshot);
+```
+
+### Utility Functions
+
+```javascript
+// Get version
+const ver = version();
+console.log(`Unicorn ${ver.string}`);
+
+// Check architecture support
+if (archSupported(ARCH.ARM64)) {
+    console.log('ARM64 is supported');
+}
+
+// Get error message
+const msg = strerror(errorCode);
+```
+
+## Constants
+
+### Architectures (ARCH)
+
+- `ARCH.X86` - x86/x64
+- `ARCH.ARM` - ARM
+- `ARCH.ARM64` - ARM64 (AArch64)
+- `ARCH.MIPS` - MIPS
+- `ARCH.SPARC` - SPARC
+- `ARCH.PPC` - PowerPC
+- `ARCH.M68K` - Motorola 68K
+- `ARCH.RISCV` - RISC-V
+
+### Modes (MODE)
+
+- `MODE.MODE_16` - 16-bit mode
+- `MODE.MODE_32` - 32-bit mode
+- `MODE.MODE_64` - 64-bit mode
+- `MODE.LITTLE_ENDIAN` - Little-endian
+- `MODE.BIG_ENDIAN` - Big-endian
+
+### Memory Permissions (PROT)
+
+- `PROT.NONE` - No permissions
+- `PROT.READ` - Read permission
+- `PROT.WRITE` - Write permission
+- `PROT.EXEC` - Execute permission
+- `PROT.ALL` - All permissions
+
+### Hook Types (HOOK)
+
+- `HOOK.CODE` - Code execution
+- `HOOK.BLOCK` - Basic block
+- `HOOK.INTR` - Interrupts
+- `HOOK.MEM_READ` - Memory read
+- `HOOK.MEM_WRITE` - Memory write
+- `HOOK.MEM_FETCH` - Memory fetch
+
+### Registers
+
+- `X86_REG` - x86/x64 registers (RAX, RBX, RCX, etc.)
+- `ARM_REG` - ARM registers (R0-R12, SP, LR, PC, etc.)
+- `ARM64_REG` - ARM64 registers (X0-X30, SP, PC, etc.)
+- `MIPS_REG` - MIPS registers (V0, A0-A3, T0-T9, etc.)
+
+## TypeScript
+
+Full TypeScript definitions are included:
+
+```typescript
+import { Unicorn, ARCH, MODE, PROT, X86_REG, version } from 'hexcore-unicorn';
+
+const uc = new Unicorn(ARCH.X86, MODE.MODE_64);
+const rax: bigint | number = uc.regRead(X86_REG.RAX);
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Unicorn Engine library
+
+### Installing Unicorn
+
+**Windows:**
+Download from [Unicorn releases](https://github.com/unicorn-engine/unicorn/releases) and place `unicorn.dll` and `unicorn.lib` in `deps/unicorn/`.
+
+**Linux:**
+```bash
+sudo apt install libunicorn-dev
+# Or build from source
+```
+
+**macOS:**
+```bash
+brew install unicorn
+```
+
+## License
+
+MIT License - See [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Related Projects
+
+- [hexcore-capstone](https://www.npmjs.com/package/hexcore-capstone) - Capstone disassembler bindings
+- [hexcore-keystone](https://www.npmjs.com/package/hexcore-keystone) - Keystone assembler bindings (Older version, No Working)
+- [Unicorn Engine](https://www.unicorn-engine.org/) - The underlying emulation framework

package/binding.gyp

@@ -0,0 +1,91 @@
+{
+  "targets": [
+    {
+      "target_name": "hexcore_unicorn",
+      "sources": [
+        "src/main.cpp",
+        "src/unicorn_wrapper.cpp"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "deps/unicorn/include"
+      ],
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').gyp\")"
+      ],
+      "defines": [
+        "NAPI_VERSION=8",
+        "NAPI_CPP_EXCEPTIONS",
+        "NODE_ADDON_API_DISABLE_DEPRECATED"
+      ],
+      "cflags!": ["-fno-exceptions"],
+      "cflags_cc!": ["-fno-exceptions"],
+      "conditions": [
+        ["OS=='win'", {
+          "libraries": [
+            "<(module_root_dir)/deps/unicorn/unicorn-import.lib"
+          ],
+          "copies": [
+            {
+              "destination": "<(module_root_dir)/build/Release/",
+              "files": [
+                "<(module_root_dir)/deps/unicorn/unicorn.dll"
+              ]
+            }
+          ],
+          "msvs_settings": {
+            "VCCLCompilerTool": {
+              "ExceptionHandling": 1,
+              "AdditionalOptions": ["/std:c++17"]
+            }
+          },
+          "defines": [
+            "_HAS_EXCEPTIONS=1"
+          ]
+        }],
+        ["OS=='linux'", {
+          "libraries": [
+            "-L<(module_root_dir)/deps/unicorn",
+            "-lunicorn",
+            "-Wl,-rpath,'$$ORIGIN'"
+          ],
+          "cflags_cc": [
+            "-std=c++17",
+            "-fexceptions"
+          ],
+          "copies": [
+            {
+              "destination": "<(module_root_dir)/build/Release/",
+              "files": [
+                "<(module_root_dir)/deps/unicorn/libunicorn.so",
+                "<(module_root_dir)/deps/unicorn/libunicorn.so.2"
+              ]
+            }
+          ]
+        }],
+        ["OS=='mac'", {
+          "libraries": [
+            "-L<(module_root_dir)/deps/unicorn",
+            "-lunicorn",
+            "-Wl,-rpath,@loader_path"
+          ],
+          "xcode_settings": {
+            "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+            "CLANG_CXX_LIBRARY": "libc++",
+            "CLANG_CXX_LANGUAGE_STANDARD": "c++17",
+            "MACOSX_DEPLOYMENT_TARGET": "10.15"
+          },
+          "copies": [
+            {
+              "destination": "<(module_root_dir)/build/Release/",
+              "files": [
+                "<(module_root_dir)/deps/unicorn/libunicorn.dylib",
+                "<(module_root_dir)/deps/unicorn/libunicorn.2.dylib"
+              ]
+            }
+          ]
+        }]
+      ]
+    }
+  ]
+}

package/deps/unicorn/include/unicorn/arm.h

@@ -0,0 +1,235 @@
+/* Unicorn Engine */
+/* By Nguyen Anh Quynh <aquynh@gmail.com>, 2015-2017 */
+/* This file is released under LGPL2.
+   See COPYING.LGPL2 in root directory for more details
+*/
+
+#ifndef UNICORN_ARM_H
+#define UNICORN_ARM_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifdef _MSC_VER
+#pragma warning(disable : 4201)
+#endif
+
+//> ARM CPU
+typedef enum uc_cpu_arm {
+    UC_CPU_ARM_926 = 0,
+    UC_CPU_ARM_946,
+    UC_CPU_ARM_1026,
+    UC_CPU_ARM_1136_R2,
+    UC_CPU_ARM_1136,
+    UC_CPU_ARM_1176,
+    UC_CPU_ARM_11MPCORE,
+    UC_CPU_ARM_CORTEX_M0,
+    UC_CPU_ARM_CORTEX_M3,
+    UC_CPU_ARM_CORTEX_M4,
+    UC_CPU_ARM_CORTEX_M7,
+    UC_CPU_ARM_CORTEX_M33,
+    UC_CPU_ARM_CORTEX_R5,
+    UC_CPU_ARM_CORTEX_R5F,
+    UC_CPU_ARM_CORTEX_A7,
+    UC_CPU_ARM_CORTEX_A8,
+    UC_CPU_ARM_CORTEX_A9,
+    UC_CPU_ARM_CORTEX_A15,
+    UC_CPU_ARM_TI925T,
+    UC_CPU_ARM_SA1100,
+    UC_CPU_ARM_SA1110,
+    UC_CPU_ARM_PXA250,
+    UC_CPU_ARM_PXA255,
+    UC_CPU_ARM_PXA260,
+    UC_CPU_ARM_PXA261,
+    UC_CPU_ARM_PXA262,
+    UC_CPU_ARM_PXA270,
+    UC_CPU_ARM_PXA270A0,
+    UC_CPU_ARM_PXA270A1,
+    UC_CPU_ARM_PXA270B0,
+    UC_CPU_ARM_PXA270B1,
+    UC_CPU_ARM_PXA270C0,
+    UC_CPU_ARM_PXA270C5,
+    UC_CPU_ARM_MAX,
+
+    UC_CPU_ARM_ENDING
+} uc_cpu_arm;
+
+// ARM coprocessor registers, use this with UC_ARM_REG_CP_REG to
+// in call to uc_reg_write/read() to access the registers.
+typedef struct uc_arm_cp_reg {
+    uint32_t cp;   // The coprocessor identifier
+    uint32_t is64; // Is it a 64 bit control register
+    uint32_t sec;  // Security state
+    uint32_t crn;  // Coprocessor register number
+    uint32_t crm;  // Coprocessor register number
+    uint32_t opc1; // Opcode1
+    uint32_t opc2; // Opcode2
+    uint64_t val;  // The value to read/write
+} uc_arm_cp_reg;
+
+//> ARM registers
+typedef enum uc_arm_reg {
+    UC_ARM_REG_INVALID = 0,
+    UC_ARM_REG_APSR,
+    UC_ARM_REG_APSR_NZCV,
+    UC_ARM_REG_CPSR,
+    UC_ARM_REG_FPEXC,
+    UC_ARM_REG_FPINST,
+    UC_ARM_REG_FPSCR,
+    UC_ARM_REG_FPSCR_NZCV,
+    UC_ARM_REG_FPSID,
+    UC_ARM_REG_ITSTATE,
+    UC_ARM_REG_LR,
+    UC_ARM_REG_PC,
+    UC_ARM_REG_SP,
+    UC_ARM_REG_SPSR,
+    UC_ARM_REG_D0,
+    UC_ARM_REG_D1,
+    UC_ARM_REG_D2,
+    UC_ARM_REG_D3,
+    UC_ARM_REG_D4,
+    UC_ARM_REG_D5,
+    UC_ARM_REG_D6,
+    UC_ARM_REG_D7,
+    UC_ARM_REG_D8,
+    UC_ARM_REG_D9,
+    UC_ARM_REG_D10,
+    UC_ARM_REG_D11,
+    UC_ARM_REG_D12,
+    UC_ARM_REG_D13,
+    UC_ARM_REG_D14,
+    UC_ARM_REG_D15,
+    UC_ARM_REG_D16,
+    UC_ARM_REG_D17,
+    UC_ARM_REG_D18,
+    UC_ARM_REG_D19,
+    UC_ARM_REG_D20,
+    UC_ARM_REG_D21,
+    UC_ARM_REG_D22,
+    UC_ARM_REG_D23,
+    UC_ARM_REG_D24,
+    UC_ARM_REG_D25,
+    UC_ARM_REG_D26,
+    UC_ARM_REG_D27,
+    UC_ARM_REG_D28,
+    UC_ARM_REG_D29,
+    UC_ARM_REG_D30,
+    UC_ARM_REG_D31,
+    UC_ARM_REG_FPINST2,
+    UC_ARM_REG_MVFR0,
+    UC_ARM_REG_MVFR1,
+    UC_ARM_REG_MVFR2,
+    UC_ARM_REG_Q0,
+    UC_ARM_REG_Q1,
+    UC_ARM_REG_Q2,
+    UC_ARM_REG_Q3,
+    UC_ARM_REG_Q4,
+    UC_ARM_REG_Q5,
+    UC_ARM_REG_Q6,
+    UC_ARM_REG_Q7,
+    UC_ARM_REG_Q8,
+    UC_ARM_REG_Q9,
+    UC_ARM_REG_Q10,
+    UC_ARM_REG_Q11,
+    UC_ARM_REG_Q12,
+    UC_ARM_REG_Q13,
+    UC_ARM_REG_Q14,
+    UC_ARM_REG_Q15,
+    UC_ARM_REG_R0,
+    UC_ARM_REG_R1,
+    UC_ARM_REG_R2,
+    UC_ARM_REG_R3,
+    UC_ARM_REG_R4,
+    UC_ARM_REG_R5,
+    UC_ARM_REG_R6,
+    UC_ARM_REG_R7,
+    UC_ARM_REG_R8,
+    UC_ARM_REG_R9,
+    UC_ARM_REG_R10,
+    UC_ARM_REG_R11,
+    UC_ARM_REG_R12,
+    UC_ARM_REG_S0,
+    UC_ARM_REG_S1,
+    UC_ARM_REG_S2,
+    UC_ARM_REG_S3,
+    UC_ARM_REG_S4,
+    UC_ARM_REG_S5,
+    UC_ARM_REG_S6,
+    UC_ARM_REG_S7,
+    UC_ARM_REG_S8,
+    UC_ARM_REG_S9,
+    UC_ARM_REG_S10,
+    UC_ARM_REG_S11,
+    UC_ARM_REG_S12,
+    UC_ARM_REG_S13,
+    UC_ARM_REG_S14,
+    UC_ARM_REG_S15,
+    UC_ARM_REG_S16,
+    UC_ARM_REG_S17,
+    UC_ARM_REG_S18,
+    UC_ARM_REG_S19,
+    UC_ARM_REG_S20,
+    UC_ARM_REG_S21,
+    UC_ARM_REG_S22,
+    UC_ARM_REG_S23,
+    UC_ARM_REG_S24,
+    UC_ARM_REG_S25,
+    UC_ARM_REG_S26,
+    UC_ARM_REG_S27,
+    UC_ARM_REG_S28,
+    UC_ARM_REG_S29,
+    UC_ARM_REG_S30,
+    UC_ARM_REG_S31,
+
+    UC_ARM_REG_C1_C0_2,  // Depreciated, use UC_ARM_REG_CP_REG instead
+    UC_ARM_REG_C13_C0_2, // Depreciated, use UC_ARM_REG_CP_REG instead
+    UC_ARM_REG_C13_C0_3, // Depreciated, use UC_ARM_REG_CP_REG instead
+
+    UC_ARM_REG_IPSR,
+    UC_ARM_REG_MSP,
+    UC_ARM_REG_PSP,
+    UC_ARM_REG_CONTROL,
+    UC_ARM_REG_IAPSR,
+    UC_ARM_REG_EAPSR,
+    UC_ARM_REG_XPSR,
+    UC_ARM_REG_EPSR,
+    UC_ARM_REG_IEPSR,
+    UC_ARM_REG_PRIMASK,
+    UC_ARM_REG_BASEPRI,
+    UC_ARM_REG_BASEPRI_MAX,
+    UC_ARM_REG_FAULTMASK,
+    UC_ARM_REG_APSR_NZCVQ,
+    UC_ARM_REG_APSR_G,
+    UC_ARM_REG_APSR_NZCVQG,
+    UC_ARM_REG_IAPSR_NZCVQ,
+    UC_ARM_REG_IAPSR_G,
+    UC_ARM_REG_IAPSR_NZCVQG,
+    UC_ARM_REG_EAPSR_NZCVQ,
+    UC_ARM_REG_EAPSR_G,
+    UC_ARM_REG_EAPSR_NZCVQG,
+    UC_ARM_REG_XPSR_NZCVQ,
+    UC_ARM_REG_XPSR_G,
+    UC_ARM_REG_XPSR_NZCVQG,
+    UC_ARM_REG_CP_REG,
+	// A pseudo-register for fetching the exception syndrome
+	// from the CPU state. This is not a real register.
+    UC_ARM_REG_ESR,
+    UC_ARM_REG_ENDING, // <-- mark the end of the list or registers
+
+    //> alias registers
+    UC_ARM_REG_R13 = UC_ARM_REG_SP,
+    UC_ARM_REG_R14 = UC_ARM_REG_LR,
+    UC_ARM_REG_R15 = UC_ARM_REG_PC,
+
+    UC_ARM_REG_SB = UC_ARM_REG_R9,
+    UC_ARM_REG_SL = UC_ARM_REG_R10,
+    UC_ARM_REG_FP = UC_ARM_REG_R11,
+    UC_ARM_REG_IP = UC_ARM_REG_R12,
+} uc_arm_reg;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif