ronin-rb/ronin-code-asm

A Ruby DSL for crafting assmebly programs and shellcode.

ronin-code-asm

• Source
• Issues
• Documentation
• Discord | Mastodon

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

• Ruby >= 3.0.0
• yasm >= 0.6.0
• ruby-yasm ~> 0.3

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

1. Fork It!
2. Clone It!
3. cd ronin-code-asm/
4. bundle install
5. git checkout -b my_feature
6. Code It!
7. bundle exec rake spec
8. 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/.

ronin-code-asm's Issues

Intel syntax support

http://www.quickmeme.com/meme/3tnkoi/

Re-enable JRuby in the CI matrix

Now that JRuby 9.4 has been released, we can re-add it to the CI matrix.

Add truffleruby to the CI

Officially support TruffleRuby.

Remove data_paths dependency

Add `push_string` method to `Ronin::ASM::Shellcode`

Add a push_string helper that pushes bytes of a string onto the stack.

Switch DSL argument order to match Intel syntax

Switch the argument order to that of Intel ASM syntax. Intel syntax won.

ROP gadget search

Any possibility to do that now ? Input a binary and come out with a set of useful gadgets or allow to search given a regular expression of the syntax i.e. "pop.+pop.+ret"

Add bin/ronin-asm

Add a bin/ronin-asm script that starts the ronin console with ronin/asm loaded.

Add rubocop

Add rubocop to the repository.

• Add the rubocop and rubocop-ronin gems to the Gemfile.
• Start with the template rubocop.yml file which closely matches Ronin's general code style.
• Add the rubocop task and add it to the CI.

Replace `options={}` with keyword arguments

Replace options={} with individual keyword arguments. Also, update the @option YARD tags.

Rename project to `ronin-code-asm`

It should be clear that the goal of the project is to generate Assembly code.

Add aliases for byte/word/dword/qword

Need to add aliases to the byte, word, dword and qword methods, for ANSI C types.

• uint8 -> byte
• uint16 -> word
• uint32 -> dword
• uint64 -> qword

Spec everything

Need RSpec tests for every Class.

bundle exec rake spec:yasm can't run

Hey, I was tinkering around the other day with the Rakefile and noticed I couldn't get yasm: true tests to run. I think there's actually a typo in the pattern line. It runs when I change the pattern line to

t.pattern    = ['spec/program_spec.rb', 'spec/shellcode_spec.rb']

Make the default syntax Intel

Change the default syntax for Program#to_asm to :intel.

Add a Disassembler ontop of ffi-udis86

Add a Disassembler that can create Ronin::ASM::Instructions using ffi-uids86.

Release ronin-code-asm 1.0.0.beta1

Release ronin-code-asm 1.0.0

Add ANSI C types

If an ASM Program selects both an Arch and an OS, ANSI C types should be defined as methods.

• char()
• short()
• int()
• long()
• long_long()
• uchar()
• ushort()
• uint()
• ulong()
• ulong_long()

Add commands similar to ShellNoob

Add useful commands similar to ShellNoob.