ronin-post_ex 0.1.0.beta1

data/README.md

@@ -0,0 +1,245 @@
+# ronin-post_ex
+
+[![CI](https://github.com/ronin-rb/ronin-post_ex/actions/workflows/ruby.yml/badge.svg)](https://github.com/ronin-rb/ronin-post_ex/actions/workflows/ruby.yml)
+[![Code Climate](https://codeclimate.com/github/ronin-rb/ronin-post_ex.svg)](https://codeclimate.com/github/ronin-rb/ronin-post_ex)
+
+* [Website](https://ronin-rb.dev/)
+* [Source](https://github.com/ronin-rb/ronin-post_ex)
+* [Issues](https://github.com/ronin-rb/ronin-post_ex/issues)
+* [Documentation](https://ronin-rb.dev/docs/ronin-post_ex/frames)
+* [Discord](https://discord.gg/6WAb3PsVX9) |
+  [Twitter](https://twitter.com/ronin_rb) |
+  [Mastodon](https://infosec.exchange/@ronin_rb)
+
+## 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][API Spec].
+* 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
+
+```ruby
+session = Ronin::PostEx::Sessions::BindShell.connect(host,port)
+system  = session.system
+
+system.shell.ls('/')
+# => "..."
+```
+
+### Reverse Shell
+
+```ruby
+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][API Spec]:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+system.process.pid
+# => 1234
+
+system.process.getuid
+# => 1001
+
+system.process.environ
+# => {"HOME"=>"...", "PATH"=>"...", ...}
+```
+
+Execute commands on the remote system:
+
+```ruby
+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:
+
+```ruby
+system.shell.interact
+$
+```
+
+Spawn an interactive post-exploitation system shell:
+
+```ruby
+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
+
+```shell
+$ gem install ronin-post_ex
+```
+
+### Gemfile
+
+```ruby
+gem 'ronin-post_ex', '~> 0.1'
+```
+
+### gemspec
+
+```ruby
+gem.add_dependency 'ronin-post_ex', '~> 0.1'
+```
+
+## Development
+
+1. [Fork It!](https://github.com/ronin-rb/ronin-post_ex/fork)
+2. Clone It!
+3. `cd ronin-post_ex/`
+4. `bundle install`
+5. `git checkout -b my_feature`
+6. Code It!
+7. `bundle exec rake spec`
+8. `git push origin my_feature`
+
+## License
+
+Copyright (c) 2007-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+
+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/>.
+
+[Ruby]: https://www.ruby-lang.org
+[ronin-rb]: https://ronin-rb.dev
+
+[fake_io]: https://github.com/postmodern/fake_io.rb#readme
+[hexdump]: https://github.com/postmodern/hexdump.rb#readme
+[ronin-core]: https://github.com/ronin-rb/ronin-core#readme
+[ronin-payloads]: https://github.com/ronin-rb/ronin-payloads#readme
+[ronin-c2]: https://github.com/ronin-rb/ronin-c2#readme
+[ronin-exploits]: https://github.com/ronin-rb/ronin-exploits#readme
+
+[API Spec]: https://github.com/ronin-rb/ronin-post_ex/blob/main/API_SPEC.md

data/Rakefile

@@ -0,0 +1,34 @@
+require 'rubygems'
+
+begin
+  require 'bundler'
+rescue LoadError => e
+  warn e.message
+  warn "Run `gem install bundler` to install Bundler"
+  exit -1
+end
+
+begin
+  Bundler.setup(:development)
+rescue Bundler::BundlerError => e
+  warn e.message
+  warn "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rake'
+
+require 'rubygems/tasks'
+Gem::Tasks.new(sign: {checksum: true, pgp: true})
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+task :test    => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new
+task :docs => :yard
+
+require 'kramdown/man/task'
+Kramdown::Man::Task.new

data/examples/bind_shell.rb

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'ronin/post_ex/sessions/shell_session'
+require 'ronin/post_ex/system'
+require 'socket'
+
+# run `nc -l -p 1337 -e /bin/sh` in another terminal
+socket = begin
+           TCPSocket.new('localhost',1337)
+         rescue
+           warn "Please run 'nc -l -p 1337 -e /bin/sh' in another terminal"
+           exit(-1)
+         end
+
+session = Ronin::PostEx::Sessions::ShellSession.new(socket)
+system  = Ronin::PostEx::System.new(session)
+
+system.interact

data/gemspec.yml

@@ -0,0 +1,25 @@
+name: ronin-post_ex
+summary: Ruby API for Post-Exploitation
+description: ronin-post_ex is a Ruby API for Post-Exploitation.
+license: LGPL-3.0
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: https://ronin-rb.dev/
+has_yard: true
+
+metadata:
+  documentation_uri: https://rubydoc.info/gems/ronin-post_ex
+  source_code_uri:   https://github.com/ronin-rb/ronin-post_ex
+  bug_tracker_uri:   https://github.com/ronin-rb/ronin-post_ex/issues
+  changelog_uri:     https://github.com/ronin-rb/ronin-post_ex/blob/master/ChangeLog.md
+
+required_ruby_version: ">= 3.0.0"
+
+dependencies:
+  fake_io: ~> 0.1
+  hexdump: ~> 1.0
+  # Ronin dependencies:
+  ronin-core: ~> 0.1.0.beta1
+
+development_dependencies:
+  bundler: ~> 2.0

data/lib/ronin/post_ex/cli/shell_shell.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+#
+# ronin-post_ex - a Ruby API for Post-Exploitation.
+#
+# Copyright (c) 2007-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# 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/>.
+#
+
+require 'ronin/core/cli/shell'
+
+module Ronin
+  module PostEx
+    module CLI
+      #
+      # A shell for {System::Shell}.
+      #
+      class ShellShell < Core::CLI::Shell
+
+        prompt_sigil '$'
+
+        #
+        # Initializes the shell.
+        #
+        # @param [System::Shell] shell
+        #   The shell resource.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments for
+        #   `Ronin::Core::CLI::Shell#initialize`.
+        #
+        def initialize(shell, **kwargs)
+          super(**kwargs)
+
+          @shell = shell
+        end
+
+        #
+        # Executes a command and prints it's output.
+        #
+        # @param [String] command
+        #   The command string.
+        #
+        def exec(command)
+          if command == 'exit'
+            exit
+          else
+            puts @shell.run(command)
+          end
+        end
+
+      end
+    end
+  end
+end