ronin-post_ex

Description

ronin-post_ex is a Ruby API for Post-Exploitation.

This library is used by ronin-payloads, ronin-c2, and ronin-exploits to provide a Post-Exploitation API around payloads, C2 sessions, or even exploits.

ronin-post_ex is part of the ronin-rb project, a Ruby toolkit for security research and development.

Features

Defines a syscall-like API for Post-Exploitation.
Provides classes for interacting with the Post-Exploitation API.
- Ronin::PostEx::System - allows interacting with a remote system.
- Ronin::PostEx::System::FS - allows interacting with the file-system.
- Ronin::PostEx::System::Process - allows manipulating the current process or child processes.
- Ronin::PostEx::System::Shell - allows interacting with an interactive shell..
- Ronin::PostEx::RemoteFile - allows reading/writing files.
- Ronin::PostEx::RemoteDir - allows reading the contents of directories.
- Ronin::PostEx::RemoteProcess - allows reading/writing to an running command.
Supports interacting with interactive shell commands.
Provides interactive command shells for interacting with systems.
Supports Linux/BSD/UNIX systems.
Provides common post-exploitation session classes for interacting with shells, bind shells, and reverse shells.
Supports defining custom post-exploitation session classes.

Limitations

Does not currently support Windows systems.
Does not fully support bidirectional fully interactive shell commands.

Examples

Bind Shell

session = Ronin::PostEx::Sessions::BindShell.connect(host,port)
system  = session.system

system.shell.ls('/')
# => "..."

Reverse Shell

session = Ronin::PostEx::Sessions::ReverseShell.listen(host,port)
system  = session.system

system.shell.ls('/')
# => "..."

Custom Session Class

Define a custom session class which defines the Post-Exploitation API methods:

class RATSession < Ronin::PostEx::Sessions::Session

  def initialize(host,port)
    # ...
  end

  def rpc_call(method,*arguments)
    # ...
  end

  def fs_read(path)
    rpc_call("fs_read",path)
  end

  def shell_exec(command)
    rpc_call("shell_exec",command)
  end

  # ...

end

session = RATSession.new
system  = session.system

System

Interact with the system's remote files as if they were local files:

file = system.fs.open('/etc/passwd')

file.each_line do |line|
  user, x, uid, gid, name, home_dir, shell = line.split(':')

  puts "User Detected: #{user} (id=#{uid})"
end

Get information about the current process:

system.process.pid
# => 1234

system.process.getuid
# => 1001

system.process.environ
# => {"HOME"=>"...", "PATH"=>"...", ...}

Execute commands on the remote system:

system.shell.ls('/')
# => "bin\nboot\ndev\netc\nhome\nlib\nlib64\nlost+found\nmedia\nmnt\nopt\nproc\nroot\nrun\nsbin\nsnap\nsrv\nsys\ntmp\nusr\nvar\n"

system.shell.exec("find -type f -name '*.xls' /srv") do |path|
  puts "Found XLS file: #{path}"
end

Spawn an interactive command shell:

system.shell.interact
$

Spawn an interactive post-exploitation system shell:

system.interact

ronin-post_ex> help
  help [COMMAND]                    Prints the list of commands or additional help
  fs.chdir DIR                      Changes the current working directory
  fs.pwd                            Prints the current working directory
  fs.readfile FILE                  Reads the contents of a given FILE
  fs.readlink SYMLINK               Reads the destination path of a symlink
  fs.readdir DIR                    Reads the contents of a given directory
  fs.hexdump FILE                   Hexdumps a given file
  fs.copy SRC DEST                  Copies the SRC file to the DEST path
  fs.unlink FILE                    Deletes a given file
  fs.rmdir DIR                      Removes a given directory
  fs.mv SRC DEST                    Moves or renames a given file or directory
  fs.link SRC DEST                  Creates a link from the source to the destination
  fs.chown USER PATH                Changes the owner of a given file or directory
  fs.chgrp GROUP PATH               Changes the group of a given file or directory
  fs.chmod MODE PATH                Changes the permission mode of a given file or directory
  fs.stat PATH                      Prints file system information about a given file or directory
  fs.open PATH [MODE]               Opens a file for reading or writing
  files                             Lists opened files
  file.seek FILE_ID POS [WHENCE]    Seeks to a position within the file
  file.read FILE_ID LENGTH          Reads LENGTH of data from an opened file
  file.write FILE_ID DATA           Writes data to an opened file
  file.close FILE_ID                Closes an open file
ronin-post_ex>

Requirements

Ruby >= 3.0.0
fake_io ~> 0.1
hexdump ~> 1.0
ronin-core ~> 0.1

Install

$ gem install ronin-post_ex

Gemfile

gem 'ronin-post_ex', '~> 0.1'

gemspec

gem.add_dependency 'ronin-post_ex', '~> 0.1'

Development

Fork It!
Clone It!
cd ronin-post_ex/
bundle install
git checkout -b my_feature
Code It!
bundle exec rake spec
git push origin my_feature

License

ronin-post_ex 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-post_ex 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-post_ex. If not, see https://www.gnu.org/licenses/.