ronin-code-asm
Description
{Ronin::Code::ASM} is a Ruby DSL for crafting Assembly programs and Shellcode.
Features
- Provides a Ruby DSL for writing Assembly programs.
- Supports X86 and AMD64 instruction sets.
- Supports ATT and Intel syntax.
- Uses yasm to assemble the programs.
- Supports assembling Shellcode.
- Has 95% documentation coverage.
- Has 99% test coverage.
Examples
Create a program:
asm = Ronin::Code::ASM.new do
push ebx
mov eax, 0xc0ffee
pop ebx
hlt
end
puts asm.to_asm
# BITS 32
# section .text
# _start:
# push ebx
# mov eax, WORD 0xc0ffee
# pop ebx
# hlt
puts asm.to_asm(:att)
# .code32
# .text
# _start:
# pushl %ebx
# movl $0xc0ffee, %eax
# popl %ebx
# hlt
Create shellcode:
shellcode = Ronin::Code::ASM::Shellcode.new(arch: :x86) do
xor eax, eax
push eax
push 0x68732f2f
push 0x6e69622f
mov ebx, esp
push eax
push ebx
mov ecx, esp
xor edx, edx
mov al, 0xb
int 0x80
end
shellcode.assemble
# => "1\xC0Ph//shh/bin\x89\xDCPS\x89\xCC1\xD2\xB0\v\xCD\x80"
Immediate Operands
Immediate operands can be Integers or nil
:
mov eax, 0xff
mov ebx, nil
The size of the operand can also be specified explicitly:
push byte(0xff)
push word(0xffff)
push dword(0xffffffff)
push qword(0xffffffffffffffff)
Memory Operands
Memory operands can be expressed as arithmetic on registers:
mov ebx, esp+8
mov ebx, esp-8
mov ebx, esp+esi
mov ebx, esp+(esi*4)
Labels
Labels can be expressed with blocks:
_loop do
inc eax
cmp eax, 10
jl :_loop
end
Syscalls
If the :os
option is specified, then syscall numbers can be looked up via the
syscalls
Hash:
Ronin::Code::ASM.new(os: 'Linux') do
# ...
mov al, syscalls[:execve]
int 0x80
end
Requirements
Install
Ubuntu
sudo apt install -y yasm
gem install ronin-code-asm
Fedora
sudo dnf install -y yasm
gem install ronin-code-asm
OpenSUSE
sudo zypper -n in -l yasm
gem install ronin-code-asm
Arch
sudo pacman -Sy yasm
gem install ronin-code-asm
macOS
brew install yasm
gem install ronin-code-asm
FreeBSD
sudo pkg install -y yasm
gem install ronin-code-asm
Gemfile
gem 'ronin-code-asm', '~> 1.0'
gemspec
gem.add_dependency 'ronin-code-asm', '~> 1.0'
Development
- Fork It!
- Clone It!
cd ronin-code-asm/
bundle install
git checkout -b my_feature
- Code It!
bundle exec rake spec
git push origin my_feature
License
ronin-code-asm - A Ruby DSL for crafting Assembly programs and shellcode.
Copyright (c) 2007-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
ronin-code-asm is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
ronin-code-asm is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with ronin-code-asm. If not, see https://www.gnu.org/licenses/.