Class Axecutor

Axecutor is the main struct that is used for emulation.

It can be instantiated in JavaScript using one of the following methods:

let ax = new Axecutor(code: Uint8Array, code_start_addr: bigint, initial_rip: bigint)
let ax = Axecutor.fromBinary(elf_binary: Uint8Array).

Afterwards, one can register hooks before/after instructions:

ax.hook_before_mnemonic(Mnemonic.Syscall, (axInstance: Axecutor) => {...});
ax.hook_after_mnemonic(Mnemonic.Syscall, (axInstance: Axecutor) => {...});

Hierarchy

Axecutor

Methods

call_stack

call_stack(): string
Give an overview of the current call stack. This works best when a symbol table has been provided, which is currently only the case for ELF binaries.

Returns

Returns string

commit

commit(): any
This function should be returned from a hook to indicate the state should be kept and execution should continue.

Returns

Returns any

execute

execute(): Promise<void>
Execute all instructions until execution has stopped. Execution might stop due to hooks stopping emulation via the stop() method, execution reaching the end of the code, or an error. This is the same as calling step in a loop, but staying in WASM should be more efficient.

Returns

Returns Promise<void>

`Static` from_binary

from_binary(binary: Uint8Array): Axecutor
Create a new Axecutor from the bytes of an ELF binary. This will load the .text section into memory and set the program counter to the entry point. One thing to note is that you might want to set up the stack via init_stack_program_start before running the binary.

Returns
Parameters
- binary: Uint8Array
Returns Axecutor

handle_syscalls

handle_syscalls(...syscalls: any): void
Register syscalls that the emulator should handle automatically. The function takes variadic arguments, where each argument is a number of one of the supported Syscalls
Parameters
- Rest ...syscalls: any
Returns void

hook_after_mnemonic

hook_after_mnemonic(mnemonic: number, cb: Function): void
Register a function to be called after a mnemonic is executed. The function will be called with the Axecutor object and mnemonic as arguments. The function may be sync or async and MUST return the result of one of the following functions:
- instance.commit(): Continue execution, keep data
- instance.stop(): Stop execution, keep data
- instance.unchanged(): Continue execution, but discard data changed in the hook You can register multiple functions for the same mnemonic, the order of execution is however not defined.
Parameters
- mnemonic: number
- cb: Function
Returns void

hook_before_mnemonic

hook_before_mnemonic(mnemonic: number, cb: Function): void
Register a function to be called before a mnemonic is executed. The function will be called with the Axecutor object and mnemonic as arguments. The function may be sync or async and MUST return the result of one of the following functions:
- instance.commit(): Continue execution, keep data
- instance.stop(): Stop execution, keep data
- instance.unchanged(): Continue execution, but discard data changed in the hook You can register multiple functions for the same mnemonic, the order of execution is however not defined.
Parameters
- mnemonic: number
- cb: Function
Returns void

init_stack

init_stack(length: bigint): bigint
Initializes the stack at a random location with the given length.

Returns
Parameters
- length: bigint
Returns bigint

init_stack_program_start

init_stack_program_start(length: bigint, argv: any[], envp: any[]): bigint
Initializes the stack with the given length, command-line arguments and environment variables according to the System V ABI. This is useful for emulating ELF binaries.

Returns
Parameters
- length: bigint
- argv: any[]
- envp: any[]
Returns bigint

mem_init_anywhere

mem_init_anywhere(data: Uint8Array, name?: string): bigint
Initialize a memory area with the given data at a random address. The start address is returned.

Returns
Parameters
- data: Uint8Array
- Optional name: string
Returns bigint

mem_init_area

mem_init_area(start: bigint, data: Uint8Array): void
Initialize a memory area with the given data.
Parameters
- start: bigint
- data: Uint8Array
Returns void

mem_init_area_named

mem_init_area_named(start: bigint, data: Uint8Array, name?: string): void
Initialize a memory area with the given data and name. The name is used for logging and debugging purposes.
Parameters
- start: bigint
- data: Uint8Array
- Optional name: string
Returns void

mem_init_zero

mem_init_zero(start: bigint, length: bigint): void
Initialize a memory area with the given length.
Parameters
- start: bigint
- length: bigint
Returns void

mem_init_zero_anywhere

mem_init_zero_anywhere(length: bigint): bigint
Initialize a memory area of the given length at a random address. The start address is returned.

Returns
Parameters
- length: bigint
Returns bigint

mem_init_zero_named

mem_init_zero_named(start: bigint, length: bigint, name: string): void
Initialize a memory area with the given length and name.
Parameters
- start: bigint
- length: bigint
- name: string
Returns void

mem_prot

mem_prot(section_start: bigint, prot: number): void
Set the access permissions of the memory area with the given start address. The access permissions are a bitmask of PROT_READ (1), PROT_WRITE (2), and PROT_EXEC (4). A value of 0 means no access. By default, all memory areas are initialized with PROT_READ | PROT_WRITE.
Parameters
- section_start: bigint
- prot: number
Returns void

mem_read_128

mem_read_128(address: bigint): bigint
Reads an 128-bit value from memory at address

Returns
Parameters
- address: bigint
Returns bigint

mem_read_16

mem_read_16(address: bigint): bigint
Reads a 16-bit value from memory at address

Returns
Parameters
- address: bigint
Returns bigint

mem_read_32

mem_read_32(address: bigint): bigint
Reads a 32-bit value from memory at address

Returns
Parameters
- address: bigint
Returns bigint

mem_read_64

mem_read_64(address: bigint): bigint
Reads a 64-bit value from memory at address

Returns
Parameters
- address: bigint
Returns bigint

mem_read_8

mem_read_8(address: bigint): bigint
Reads an 8-bit value from memory at address

Returns
Parameters
- address: bigint
Returns bigint

mem_read_bytes

mem_read_bytes(address: bigint, length: bigint): Uint8Array
Reads length bytes from memory at address

Returns
Parameters
- address: bigint
- length: bigint
Returns Uint8Array

mem_resize_section

mem_resize_section(start_addr: bigint, new_size: bigint): void
Resize the already existing section of memory with start address start_addr to new_size The code section cannot be resized.
Parameters
- start_addr: bigint
- new_size: bigint
Returns void

mem_write_128

mem_write_128(address: bigint, data: bigint): void
Writes an 128-bit value to memory at address
Parameters
- address: bigint
- data: bigint
Returns void

mem_write_16

mem_write_16(address: bigint, data: bigint): void
Writes a 16-bit value to memory at address
Parameters
- address: bigint
- data: bigint
Returns void

mem_write_32

mem_write_32(address: bigint, data: bigint): void
Writes a 32-bit value to memory at address
Parameters
- address: bigint
- data: bigint
Returns void

mem_write_64

mem_write_64(address: bigint, data: bigint): void
Writes a 64-bit value to memory at address
Parameters
- address: bigint
- data: bigint
Returns void

mem_write_8

mem_write_8(address: bigint, data: bigint): void
Writes an 8-bit value to memory at address
Parameters
- address: bigint
- data: bigint
Returns void

mem_write_bytes

mem_write_bytes(address: bigint, data: Uint8Array): void
Writes bytes of data to memory at address
Parameters
- address: bigint
- data: Uint8Array
Returns void

read_fs

read_fs(): bigint
Reads the value of the FS segment register.

Returns

Returns bigint

read_gs

read_gs(): bigint
Reads the value of the GS segment register.

Returns

Returns bigint

reg_read_128

reg_read_128(reg: number): bigint
Reads an 128-bit value from an 128-bit wide register. Invalid registers lead to exceptions.

Returns
Parameters
- reg: number
Returns bigint

reg_read_16

reg_read_16(reg: number): bigint
Reads a 16-bit value from a 16-bit wide register. Invalid registers lead to exceptions.

Returns
Parameters
- reg: number
Returns bigint

reg_read_32

reg_read_32(reg: number): bigint
Reads a 32-bit value from a 32-bit wide register. Invalid registers lead to exceptions.

Returns
Parameters
- reg: number
Returns bigint

reg_read_64

reg_read_64(reg: number): bigint
Reads a 64-bit value from a 64-bit wide register. Invalid registers lead to exceptions.

Returns
Parameters
- reg: number
Returns bigint

reg_read_8

reg_read_8(reg: number): bigint
Reads an 8-bit value from a 8-bit wide register. Invalid registers lead to exceptions.

Returns
Parameters
- reg: number
Returns bigint

reg_write_128

reg_write_128(reg: number, value: bigint): void
Writes an 128-bit value to an 128-bit wide register. Out-of-range values or invalid registers lead to exceptions.
Parameters
- reg: number
- value: bigint
Returns void

reg_write_16

reg_write_16(reg: number, value: bigint): void
Writes a 16-bit value to a 16-bit wide register. Out-of-range values or invalid registers lead to exceptions.
Parameters
- reg: number
- value: bigint
Returns void

reg_write_32

reg_write_32(reg: number, value: bigint): void
Writes a 32-bit value to a 32-bit wide register. Out-of-range values or invalid registers lead to exceptions. Note that on x86-64 writes to 32-bit registers clear the upper 32 bits of the corresponding 64-bit register.
Parameters
- reg: number
- value: bigint
Returns void

reg_write_64

reg_write_64(reg: number, value: bigint): void
Writes a 64-bit value to a 64-bit wide register. Out-of-range values or invalid registers lead to exceptions.
Parameters
- reg: number
- value: bigint
Returns void

reg_write_8

reg_write_8(reg: number, value: bigint): void
Writes an 8-bit value to a 8-bit wide register. Out-of-range values or invalid registers lead to exceptions.
Parameters
- reg: number
- value: bigint
Returns void

resolve_symbol

resolve_symbol(addr: bigint): undefined | string
Get the symbol name for a given address. This only works if the ELF binary contains a symbol table. If no symbol is found, None or undefined is returned.

Returns
Parameters
- addr: bigint
Returns undefined | string

set_max_instructions

set_max_instructions(max: bigint): void
Sets an upper limit on the number of instructions that can be executed.
Parameters
- max: bigint
Returns void

step

step(): Promise<boolean>
Execute the next instruction (including all registered hooks), returning if execution has stopped

Returns

Returns Promise<boolean>

stop

stop(): any
This function should be returned from a hook to indicate the state should be kept and execution should stop. You can also call this function from ouside of a hook, it will however not stop any running hooks.

Returns

Returns any

toString

toString(): string
Returns a string representation of the Axecutor instance that can be useful for debugging

Returns

Returns string

trace

trace(): string
Generate a trace of the current execution state. This trace is a list of all executed jumps, calls and returns. Conditional jumps that were not taken are not included in the trace. This works best when a symbol table has been provided, which is currently only the case for ELF binaries.

Returns

Returns string

unchanged

unchanged(): any
This function should be returned from a hook to indicate the state should not be kept, but execution should continue.

Returns

Returns any

write_fs

write_fs(value: bigint): void
Writes a value to the FS segment register.
Parameters
- value: bigint
Returns void

write_gs

write_gs(value: bigint): void
Writes a value to the GS segment register.
Parameters
- value: bigint
Returns void

Constructors

constructor

new Axecutor(code: Uint8Array, code_start_addr: bigint, initial_rip: bigint): Axecutor
Creates a new Axecutor instance from the given x86-64 instruction bytes, writing the code to memory at code_start_addr and setting the initial RIP to initial_rip.
Parameters
- code: Uint8Array
- code_start_addr: bigint
- initial_rip: bigint
Returns Axecutor

Class Axecutor

Hierarchy

Index

Methods

Constructors

Methods

call_stack

Returns

Returns string

commit

Returns

Returns any

execute

Returns

Returns Promise<void>

Static from_binary

Returns

Parameters

binary: Uint8Array

Returns Axecutor

handle_syscalls

Parameters

Rest ...syscalls: any

Returns void

hook_after_mnemonic

Parameters

mnemonic: number

cb: Function

Returns void

hook_before_mnemonic

Parameters

mnemonic: number

cb: Function

Returns void

init_stack

Returns

Parameters

length: bigint

Returns bigint

init_stack_program_start

Returns

Parameters

length: bigint

argv: any[]

envp: any[]

Returns bigint

mem_init_anywhere

Returns

Parameters

data: Uint8Array

Optional name: string

Returns bigint

mem_init_area

Parameters

start: bigint

data: Uint8Array

Returns void

mem_init_area_named

Parameters

start: bigint

data: Uint8Array

Optional name: string

Returns void

mem_init_zero

Parameters

start: bigint

length: bigint

Returns void

mem_init_zero_anywhere

Returns

Parameters

length: bigint

Returns bigint

mem_init_zero_named

Parameters

start: bigint

length: bigint

name: string

Returns void

mem_prot

`Static` from_binary

`Rest` ...syscalls: any

`Optional` name: string

`Optional` name: string