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

• Exploit development: Confirming exact byte-length of an instruction before calculating jump/return offsets in a buffer overflow payload.
• Shellcode debugging: Cross-referencing disassembled bytes found in a debugger (like a hex dump from GDB or radare2) against expected NASM output to verify a payload assembled correctly.
• Reverse engineering / malware analysis: Manually re-deriving what a small sequence of raw opcode bytes corresponds to in assembly, when a disassembler’s output looks ambiguous.
• Security training/CTFs: Teaching students how instructions map to machine code, which builds intuition for reading raw shellcode.

Integration with Other Tools

• msfvenom: After generating a payload with msfvenom, you can spot-check individual instruction encodings with msf-nasm_shell if you’re hand-modifying shellcode.
• radare2 / GDB: Compare disassembly output from these debuggers against msf-nasm_shell‘s NASM-verified encoding when something looks off.
• Custom exploit scripts (Python/Ruby): When manually building ROP chains or shellcode byte arrays, use msf-nasm_shell to validate each gadget/instruction’s byte representation before hardcoding it into your script.

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

• Always set the correct bits mode (16/32/64) before checking encodings — mismatched modes will produce incorrect opcode lengths.
• Cross-check critical shellcode bytes with a second tool (like objdump or radare2) before using them in a real exploit proof-of-concept.
• Keep a personal cheat-sheet of frequently used instruction encodings (NOP, syscalls, common register operations) to speed up development.

Troubleshooting

• “command not found”: Ensure NASM is installed separately; msf-nasm_shell depends on it being present in $PATH.
• Unexpected opcode length: Double-check you’re in the correct bits mode — 16-bit, 32-bit, and 64-bit encodings differ for the same mnemonic.
• Instruction rejected/syntax error: NASM syntax is strict; verify operand order and register names match NASM (not AT&T/GAS) syntax.

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

• Metasploit Framework GitHub: https://github.com/rapid7/metasploit-framework
• NASM official documentation: https://www.nasm.us/docs.php
• Metasploit Unleashed (Offensive Security): https://www.offsec.com/metasploit-unleashed/