Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ronin-rb/ronin-code-asm

A Ruby DSL for crafting assmebly programs and shellcode.
https://github.com/ronin-rb/ronin-code-asm

asm assembly dsl infosec ronin-rb ruby shellcode yasm

Last synced: about 13 hours ago
JSON representation

A Ruby DSL for crafting assmebly programs and shellcode.

Host: GitHub
URL: https://github.com/ronin-rb/ronin-code-asm
Owner: ronin-rb
License: lgpl-3.0
Created: 2010-01-30T02:23:30.000Z (almost 15 years ago)
Default Branch: main
Last Pushed: 2024-08-04T20:45:52.000Z (6 months ago)
Last Synced: 2024-10-29T14:22:26.533Z (3 months ago)
Topics: asm, assembly, dsl, infosec, ronin-rb, ruby, shellcode, yasm
Language: Ruby
Homepage: https://ronin-rb.dev
Size: 522 KB
Stars: 49
Watchers: 7
Forks: 11
Open Issues: 8
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog.md
- License: COPYING.txt

Awesome Lists containing this project

README

# ronin-code-asm

[![CI](https://github.com/ronin-rb/ronin-code-asm/actions/workflows/ruby.yml/badge.svg)](https://github.com/ronin-rb/ronin-asm/actions/workflows/ruby.yml)
[![Code Climate](https://codeclimate.com/github/ronin-rb/ronin-code-asm.svg)](https://codeclimate.com/github/ronin-rb/ronin-asm)
[![Gem Version](https://badge.fury.io/rb/ronin-code-asm.svg)](https://badge.fury.io/rb/ronin-code-asm)

* [Source](https://github.com/ronin-rb/ronin-code-asm)
* [Issues](https://github.com/ronin-rb/ronin-code-asm/issues)
* [Documentation](https://ronin-rb.dev/docs/ronin-code-asm/frames)
* [Discord](https://discord.gg/6WAb3PsVX9) |
[Mastodon](https://infosec.exchange/@ronin_rb)

## 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:

```ruby
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:

```ruby
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`:

```ruby
mov eax, 0xff
mov ebx, nil
```

The size of the operand can also be specified explicitly:

```ruby
push byte(0xff)
push word(0xffff)
push dword(0xffffffff)
push qword(0xffffffffffffffff)
```

### Memory Operands

Memory operands can be expressed as arithmetic on registers:

```ruby
mov ebx, esp+8
mov ebx, esp-8
mov ebx, esp+esi
mov ebx, esp+(esi*4)
```

### Labels

Labels can be expressed with blocks:

```ruby
_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:

```ruby
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

```shell
sudo apt install -y yasm
gem install ronin-code-asm
```

### Fedora

```shell
sudo dnf install -y yasm
gem install ronin-code-asm
```

### OpenSUSE

```shell
sudo zypper -n in -l yasm
gem install ronin-code-asm
```

### Arch

```shell
sudo pacman -Sy yasm
gem install ronin-code-asm
```

### macOS

```shell
brew install yasm
gem install ronin-code-asm
```

### FreeBSD

```shell
sudo pkg install -y yasm
gem install ronin-code-asm
```

### Gemfile

```ruby
gem 'ronin-code-asm', '~> 1.0'
```

### gemspec

```ruby
gem.add_dependency 'ronin-code-asm', '~> 1.0'
```

## Development

1. [Fork It!](https://github.com/ronin-rb/ronin-code-asm/fork)
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.

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 .

[Ruby]: https://www.ruby-lang.org
[yasm]: https://yasm.tortall.net/
[ruby-yasm]: https://github.com/sophsec/ruby-yasm#readme