Offensive Security Researcher & Quantum Cryptography Analyst

msf-nasm_shell: A Metasploit tool for writing and testing shellcode

Abdul Wahab Junaid
msf-nasm_shell: A Metasploit tool for writing and testing shellcode

Whenever I’m working through exploit development and need to quickly check what opcodes a given assembly instruction produces, I don’t open a full IDE — I just type msf-nasm_shell. It’s a small, unassuming tool bundled with Metasploit, but it’s saved me a lot of time double-checking instruction encoding while building or debugging shellcode.

What Is msf-nasm_shell?

msf-nasm_shell is a command-line utility included with the Metasploit Framework that provides an interactive interface to the NASM (Netwide Assembler). It lets you type in x86/x64 assembly instructions and immediately see their corresponding machine code (opcodes) in hex — and vice versa in some workflows, useful for verifying shellcode byte sequences during exploit development.

Architecture and Internal Working

Under the hood, msf-nasm_shell is a thin Ruby wrapper script that pipes your typed assembly instructions to the NASM assembler binary, captures the resulting object code, and extracts the raw opcode bytes for display. It doesn’t reimplement an assembler — it literally shells out to NASM to guarantee accurate, standards-compliant instruction encoding for whichever architecture mode you set (16-bit, 32-bit, or 64-bit).

This makes it valuable specifically because the encoding you see is exactly what NASM (a legitimate, widely trusted assembler) would produce, not an approximation.

Installation

msf-nasm_shell ships automatically with the Metasploit Framework. On Kali Linux:

sudo apt install metasploit-framework

Verify it’s available:

which msf-nasm_shell

You also need NASM installed on the system (usually a dependency, but you can confirm it):

sudo apt install nasm
nasm -v

Basic Usage

Launch it:

msf-nasm_shell

You’ll see:

nasm >

Practical Command Examples

1. Encoding a simple instruction:

nasm > mov eax, ebx
00000000  89D8              mov eax,ebx

2. Checking encoding for a NOP:

nasm > nop
00000000  90                nop

3. Verifying a common shellcode instruction sequence (zeroing a register):

nasm > xor eax, eax
00000000  31C0              xor eax,eax

4. Switching to 64-bit mode:

nasm > bits 64
nasm > mov rax, rbx
00000000  4889D8            mov rax,rbx

5. Encoding a jump instruction to check its byte length (important for calculating offsets in shellcode):

nasm > jmp short 0x10
00000000  EB0E              jmp short 0x10

6. Checking int 0x80 syscall encoding (classic Linux x86 syscall):

nasm > int 0x80
00000000  CD80              int 0x80

7. Exiting the shell:

nasm > exit

Real-World Use Cases

Integration with Other Tools

Workflow Example

A common exploit-dev workflow I follow:

msf-nasm_shell
nasm > bits 32
nasm > push ebx
nasm > pop eax
nasm > xor ecx, ecx

Then I copy the resulting opcodes directly into a Python payload builder:

payload = b"\x53\x58\x31\xC9"  # push ebx; pop eax; xor ecx,ecx

Best Practices

Troubleshooting

Common Mistakes

  1. Forgetting to switch bits 64 when working on modern 64-bit targets, leading to incorrect 32-bit encodings.
  2. Assuming instruction byte-length without verifying — this breaks jump offset calculations in hand-crafted shellcode.
  3. Confusing NASM (Intel syntax) with GAS/AT&T syntax when copying instructions from other sources like objdump.

FAQ

Is msf-nasm_shell only useful with Metasploit? No — while it’s bundled with Metasploit, it’s really just a convenient front-end to NASM and useful any time you need to hand-verify x86/x64 instruction encoding, independent of any Metasploit module.

Can it disassemble raw bytes back into instructions? Not directly — msf-nasm_shell assembles (instruction → bytes). For the reverse direction (bytes → instruction), use a disassembler like ndisasm (also part of the NASM suite), objdump, or radare2’s rasm2 -d.

Do I need Metasploit installed just to check assembly encoding? Not strictly — you could use NASM directly, but msf-nasm_shell‘s interactive prompt is faster for quick one-off checks during exploit dev sessions.

Lab Example

  1. Write a small buffer overflow proof-of-concept in a local, deliberately vulnerable C program (compiled with protections disabled for learning purposes) running in an isolated VM.
  2. Use msf-nasm_shell to verify the exact byte sequence of a small “jmp esp” or register-zeroing instruction you plan to use in your payload.
  3. Insert the confirmed bytes into your exploit script and test against your own vulnerable binary in the VM, observing the resulting control flow.

Summary

msf-nasm_shell is a small but genuinely useful utility for anyone doing exploit development or low-level shellcode work. Because it wraps NASM directly, the encodings it produces are trustworthy and exact, making it a fast way to sanity-check instruction bytes without spinning up a full assembler project. It pairs naturally with msfvenom, radare2, and manual exploit-writing workflows.

References

Exit mobile version