56 lines
2.9 KiB
Markdown
56 lines
2.9 KiB
Markdown
# LuaHooks32
|
|
Basic x86-32 hooks library for Lua
|
|
|
|
## How to Install for Blockland+BlockLua
|
|
- Install RedBlocklandLoader and BlockLua
|
|
- Copy `luahooks32.lua` and `luahooks32core.dll` into the `modules/lualib` folder inside your Blockland install folder (you may have to create it)
|
|
|
|
## Quick Reference
|
|
|
|
`hk = require('luahooks32')` - Load the library
|
|
|
|
### Basic Scanning and Patching
|
|
`addr = hk.scan('01 02 ? ff FF')` - Scan the application binary for a pattern
|
|
`hk.patch(addr, '01 02 03')` - Patch executable code with a series of bytes
|
|
|
|
### Hooking
|
|
`hk.hook(addr, function(regs) ... end)` - Insert hook into binary code. Registers can be modified inside the hook. Registers are:
|
|
`regs.eax` `regs.ebx` `regs.ecx` `regs.edx` `regs.esi` `regs.edi` `regs.esp` `regs.ebp` `regs.eip` `regs.flags`
|
|
There is also `regs.brk`, which if set to 1 inside the hook, will cause the hook to execute a `retn` immediately after completing, returning out of whatever function the hook is inside.
|
|
Hooks can be inserted anywhere, provided there are at least 5 bytes of position-independent instructions that can be overwritten with a trampoline. Overwritten instructions are then copied into the hook routine.
|
|
If the basic builtin disassembler fails to detect the length of instructions to overwrite, a third argument to `bl.hook` can be used to manually specify the trampoline length.
|
|
|
|
`hk.unhook(addr)` - Remove a previously inserted hook.
|
|
`hk.unhookAll()` - Remove all hooks.
|
|
|
|
### Memory Access
|
|
|
|
`hk.write(addr, '01 02 03')` - Write a series of bytes
|
|
|
|
`str = hk.readStr(addr)` - Read a null-terminated C-style string from a memory address, and return its contents as a Lua string
|
|
`hk.writeStr(addr, 'hello\0')` - Write a Lua string to memory. Does NOT null-terminate, so you'll have to append `\0` yourself if you want that.
|
|
`val = hk.readInt(addr)` - Read a 32-bit signed integer from a memory address (little-endian)
|
|
`hk.writeInt(addr, val)`
|
|
`val = hk.readFloat(addr)`
|
|
`hk.writeFloat(addr, val)`
|
|
`val = hk.readChar(addr)`
|
|
`hk.writeChar(addr, val)`
|
|
`val = hk.readShort(addr)`
|
|
`hk.writeShort(addr, val)`
|
|
`val = hk.readDouble(addr)`
|
|
`hk.writeDouble(addr, val)`
|
|
Note that these functions can only write into writeable memory (i.e. stack/heap, not code). Use `hk.patch` to write into protected/executable memory.
|
|
|
|
`ptr = hk.getStrPtr('str')` - Convert a Lua string into null-terminated C-style and return a pointer to it
|
|
`print(hk.hex(val))` - Simple utility to convert a number (usually an address) into 32-bit hexadecimal
|
|
|
|
`ptr = hk.malloc(numBytes)` - Allocate memory and return a pointer to it
|
|
`hk.free(ptr)` - Free previously allocated memory
|
|
|
|
## Compiling
|
|
|
|
With any *32-bit* variant of GCC installed (such as MinGW or MSYS2), run the following command in the repo directory:
|
|
`g++ luahooks32core.cpp -o luahooks32core.dll -m32 -shared -static-libgcc -Iinc/lua -lpsapi -Linc/lua -llua5.1`
|
|
|
|
LuaJIT (lua5.1.dll) can be obtained from https://luajit.org/
|