asmx

A small commandline tool that wraps zig, nasm, qemu, and gdb to quickly compile, run, and debug code across architectures. Useful for quickly running small test programs across different architectures (use a single command to run a program from source rather than remembering the arch triple you need to pass to zig cc and needing to open two terminals to run qemu and gdb).

Inspired by helpful functions in pwntools (asm, gdb.attach) and pwndbg.

Quick start

# Examples
## Compile and run inline assembly code. --debug/-d opens GDB
asmx --arch aarch64 --asm "nop;nop;nop;nop" --vma 0x9000 --debug

## Compile and run code from an assembly file
asmx --arch amd64 --file shellcode.S -d

## If you omit --arch, it defaults to the host architecture
## Note that you can choose the path to GDB, which is 'gdb' by default.
## In this case, we set it to 'pwndbg'
asmx --asm "nop" -d pwndbg

## Run and debug a pre-compiled ELF file
asmx -i mips32_hello_world -d

## Run (but do not debug with GDB) a pre-compiled ELF file
asmx -i riscv64_hello_world -r

## Compile a program with loongarch64 and debug it. `--libc` statically links it with musl
asmx --arch loongarch64 -i hello_world.c --libc -d

By default, the tool will use zig cc under the hood. This supports the assembly syntax supported by Clang.

To use nasm instead (for x86), you can add --nasm

## Note that you must have `nasm` findable on your PATH for this to work.
## Add the --nasm flag to use nasm syntax
## It defaults to the host architecture (likely x86_64)
asmx --nasm --asm "mov rax, -1" -d

## This works with files, as well
asmx --nasm -i asm.S -d

## It supports 32-bit and 64-bit x86
asmx --nasm --asm "mov eax, 10000" -d --arch x86

Command reference

The repo provides the asmexec command (and the asmx alias).

asmx <options>

# Options
--arch <arch_name>
    Name of the architecture you want to compile and execute

--asm <source_code>
    A string containing the code you want to compile and run

    Example:
        --asm "nop; nop; nop"

-r
    Run the compiled source code

-d [gdb_path]
    Open the program in a gdb. By default, it uses `gdb` as the path to the debugger,
    but you can provide an explicit path, such as `pwndbg`, to override this

-i, --file <filename>
    Path to file with assembly source code or a valid ELF. It will detect if it's an ELF based on the magic header bytes.
    
    If it's source code, it will compile it and execute it. The --arch flag is needed in the case.
    
    If it's an ELF file, the architecture is automatically detected, but can be overriden with --arch.

-o <filename>
    Save the compiled code to this file

--vma <address>
    Specify the virtual address to place the code at. This is optional. If omitted, it uses whatever the compiles chooses.

    Note that qemu cannot load certain architectures at low addresses. If you get an qemu error, try increasing the vma. 

    Example:
        asmx --arch rv32 --asm "nop" --vma 0x90000 GDB

--libc
    Add this flag when compiling c source code, and you want to statically link with musl.

--nasm
    Compile with nasm. This works for x86 architectures.

--syntax <intel, att>
    If compiling x86 assembly code, note which syntax style you are using. This defaults to `intel` 

--arch-list
    Print supported architecture names

It will automatically cache the compiled files, so subsequent runs with the same input are faster.

Install

From GitHub

Install with uv

uv tool install git+https://github.com/OBarronCS/asmexec.git

For local development

uv tool install --editable .