Skip to content

Emulate a function

Run a single function with the arguments you choose and see what it returns, writes and calls. Emulation interprets the code in a private copy of the image: sample instructions never run on your CPU, and imports are stubs that return fixed values.

Run a function

# Call a function with two arguments
binfera sample.exe --emulate 0x140001000 --emulate-arg 6 --emulate-arg 3

# Run every call site of a function
binfera sample.exe --emulate 0x140001000 --emulate-call-sites --emulate-max-sites 32

# Raw shellcode starts at address 0
binfera raw.bin -f sc64 --os linux --emulate 0 --emulate-arg 42

# Full control with a request file
binfera sample.exe --emulate 0x140001000 --emulate-request < request.json

Output is JSON. Arguments accept decimal or 0x hex. --emulate-max-steps and --emulate-timeout-ms override the budgets.

Request file

Every field is optional. Addresses are numbers, memory is a byte array.

{
  "args": [1048576, 4],
  "memory": [{"address": 1048576, "data": [65, 66, 67, 0]}],
  "capture": [{"address": 1048576, "size": 4}],
  "import_returns": {"GetTickCount": 123},
  "max_steps": 100000
}
Field What it does
address Function address. Must match --emulate.
args Integer or pointer arguments, one machine word each.
registers Register values, applied after arguments. Use FS_OFFSET / GS_OFFSET for x86 segment bases.
memory Bytes to place in memory before the run.
capture Memory ranges to read back after the run.
import_returns Return value per import, by name or location. Default 0.
import_stack_pops Stack bytes an unknown x86 import pops.
max_steps, timeout_ms, max_calls, max_write_bytes Budgets (see Limits).

Unknown fields are rejected. Pass negative numbers as their unsigned machine-word value.

Calling conventions

Platform Arguments Return
Windows x64 RCX, RDX, R8, R9, then stack RAX
System V / macOS x64 RDI, RSI, RDX, RCX, R8, R9, then stack RAX
x86 stack EAX
AArch64 x0–x7, then stack x0
ARM32 r0–r3, then stack r0
MIPS32 o32 a0–a3, then stack v0

Floating-point arguments, structs and special ABIs (Go, Delphi, Borland) need explicit registers and memory.

Results

Field Content
stop Why the run ended
return_value Value in the return register
steps Instructions and import stubs executed
registers Selected final registers
calls Import calls with their arguments
writes Memory ranges written, with final bytes
memory Ranges you asked to capture
warnings Approximations made during the run
Stop Meaning
returned The function returned normally
caller_returned Call-site mode: the caller returned
fetch, read_fault, write_fault Jump or access to unmapped memory
step_limit, work_limit, timeout, call_limit A budget ran out
trap, decode_error, unsupported Instruction that cannot be emulated
unknown_import_abi x86 import with unknown stack cleanup: set import_stack_pops

Call sites

--emulate-call-sites runs each call to the function from its caller. Each site starts fresh, runs the caller from its entry with your args, then runs through the call. A site the caller never reaches reports reached: false. Supported on x86, x64 and AArch64.

Limits

Budget Default Maximum
Steps 100,000 10,000,000
Time 1 s 60 s
Import calls 256 4,096
Captured write bytes 64 KiB 1 MiB

Not supported:

  • Syscalls and interrupts: the run stops.
  • Self-modifying code: the run stops as unsupported.
  • Read-only memory: writes to it succeed instead of faulting.
  • Indirect calls through registers in call-site mode.
  • External calls in object files (.o): they stop as fetch.

From an agent

The MCP tools emulate_function and emulate_call_sites take a project_id, a hex address and an optional request with the fields above. emulate_call_sites also takes max_sites (default 32, max 128). Each call runs in a separate process with a 120-second limit and leaves annotations unchanged. See Connect an AI agent.

From Rust

use binfera::emulate::{Emulator, Request};

let mut emu = Emulator::open(bytes, &BatchOptions::default())?;
let result = emu.run(&request)?;            // or emu.call_sites(&request, max_sites)

Every run starts from fresh memory and zeroed registers.