ronin-post_ex 0.1.0.beta1

data/lib/ronin/post_ex/system.rb

@@ -0,0 +1,191 @@
+# 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/post_ex/resource'
+require 'ronin/post_ex/system/fs'
+require 'ronin/post_ex/system/process'
+require 'ronin/post_ex/system/shell'
+require 'ronin/post_ex/cli/system_shell'
+
+module Ronin
+  module PostEx
+    #
+    # Represents a successfully compromised system. The {System} class will
+    # wraps around a session object which defines syscall-like post-exploitation
+    # API for reading/writing files, run commands, etc.
+    #
+    # ## Supported API Functions
+    #
+    # * `sys_time -> Integer`
+    # * `sys_hostname -> String`
+    #
+    # ## Example
+    #
+    # Define the session class which defines the Post-Exploitation API methods:
+    #
+    #     require 'base64'
+    #     
+    #     class SimpleRATSession < Ronin::PostEx::Sessions::Session
+    #
+    #       def initialize(socket)
+    #         @socket = socket
+    #       end
+    #     
+    #       def call(name,*args)
+    #         @socket.puts("#{name} #{args.join(' ')}")
+    #
+    #         Base64.strict_decode64(@socket.gets(chomp: true)(
+    #       end
+    #
+    #       def shell_exec(command)
+    #         call('EXEC',command)
+    #       end
+    #
+    #       def fs_readfile(path)
+    #         call('READ',path)
+    #       end
+    #
+    #       def process_pid
+    #         call('PID').to_i
+    #       end
+    #
+    #       def process_getuid
+    #         call('UID').to_i
+    #       end
+    #
+    #       def process_environ
+    #         Hash[
+    #           call('ENV').each_line(chomp: true).map { |line|
+    #             line.split('=',2)
+    #           }
+    #         ]
+    #       end
+    #
+    #     end
+    #
+    # Initialize a new {System} object that wraps around the client:
+    #
+    #     session = SimpleRATSession.new(socket)
+    #     system  = Ronin::PostEx::System.new(session)
+    #
+    # 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
+    #
+    class System < Resource
+
+      # The File-System resource.
+      #
+      # @return [System::FS]
+      attr_reader :fs
+
+      # The Process resource.
+      #
+      # @return [System::Process]
+      attr_reader :process
+
+      # The Shell resource.
+      #
+      # @return [System::Shell]
+      attr_reader :shell
+
+      #
+      # Initializes the system.
+      #
+      # @param [Object] session
+      #   The object which defines the Post-Exploitation API methods.
+      #
+      def initialize(session)
+        super(session)
+
+        @fs      = FS.new(session)
+        @process = Process.new(session)
+        @shell   = Shell.new(session)
+      end
+
+      #
+      # Gets the current time.
+      #
+      # @return [Time]
+      #   The current time.
+      #
+      # @note
+      #   Requires the `sys_time` method be defined by the {#session} object.
+      #
+      def time
+        Time.at(@session.sys_time.to_i)
+      end
+      resource_method :time, [:sys_time]
+
+      #
+      # Gets the system's hostname.
+      #
+      # @return [String]
+      #   The system's local hostname.
+      #
+      # @note
+      #   Requires the `sys_hostname` method be defined by the {#session}
+      #   object.
+      #
+      def hostname
+        @session.sys_hostname
+      end
+
+      #
+      # Starts an interactive post-exploitation system shell.
+      #
+      def interact
+        CLI::SystemShell.start(self)
+      end
+
+      #
+      # Exits the process.
+      #
+      # @see Process#exit
+      #
+      def exit
+        @process.exit
+      end
+
+    end
+  end
+end

data/lib/ronin/post_ex/version.rb

@@ -0,0 +1,26 @@
+# 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/>.
+#
+
+module Ronin
+  module PostEx
+    # ronin-post_ex version
+    VERSION = '0.1.0.beta1'
+  end
+end

data/lib/ronin/post_ex.rb

@@ -0,0 +1,22 @@
+# 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/post_ex/system'
+require 'ronin/post_ex/version'

data/ronin-post_ex.gemspec

@@ -0,0 +1,61 @@
+# encoding: utf-8
+
+require 'yaml'
+
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
+
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+                  require 'ronin/post_ex/version'
+                  Ronin::PostEx::VERSION
+                end
+
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+  gem.metadata    = gemspec['metadata'] if gemspec['metadata']
+
+  glob = lambda { |patterns| gem.files & Dir[*patterns] }
+
+  gem.files  = `git ls-files`.split($/)
+  gem.files  = glob[gemspec['files']] if gemspec['files']
+  gem.files += Array(gemspec['generated_files'])
+
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
+  end
+
+  gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
+  gem.test_files       = glob[gemspec['test_files'] || 'spec/{**/}*_spec.rb']
+  gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
+
+  gem.require_paths = Array(gemspec.fetch('require_paths') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
+
+  gem.requirements              = gemspec['requirements']
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
+
+  split = lambda { |string| string.split(/,\s*/) }
+
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
+    end
+  end
+
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
+    end
+  end
+end

data/spec/sessions/bind_shell_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+require 'ronin/post_ex/sessions/bind_shell'
+
+describe Ronin::PostEx::Sessions::BindShell do
+  it "must inherit from Ronin::PostEx::Sessions::RemoteShellSession" do
+    expect(described_class).to be < Ronin::PostEx::Sessions::RemoteShellSession
+  end
+
+  let(:host)     { 'example.com' }
+  let(:port)     { 1337 }
+  let(:addrinfo) { Addrinfo.tcp(host,port) }
+
+  describe ".connect" do
+    let(:host) { 'example.com' }
+    let(:port) { 1337 }
+
+    let(:socket) { double('TCPSocket') }
+
+    before  { allow(socket).to receive(:remote_address).and_return(addrinfo) }
+    subject { described_class }
+
+    it "must connect to the remote host and port and return a #{described_class} object" do
+      expect(TCPSocket).to receive(:new).with(host,port).and_return(socket)
+
+      bind_shell = subject.connect(host,port)
+
+      expect(bind_shell).to be_kind_of(described_class)
+      expect(bind_shell.io).to be(socket)
+    end
+  end
+end

data/spec/sessions/remote_shell_session_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+require 'ronin/post_ex/sessions/bind_shell'
+
+describe Ronin::PostEx::Sessions::BindShell do
+  it "must inherit from Ronin::PostEx::Sessions::ShellSession" do
+    expect(described_class).to be < Ronin::PostEx::Sessions::ShellSession
+  end
+
+  let(:host)     { 'example.com' }
+  let(:port)     { 1337 }
+  let(:addrinfo) { Addrinfo.tcp(host,port) }
+  let(:socket)   { double('TCPSocket') }
+
+  before  { allow(socket).to receive(:remote_address).and_return(addrinfo) }
+  subject { described_class.new(socket) }
+
+  describe "#initialize" do
+    it "must set #io" do
+      expect(subject.io).to be(socket)
+    end
+
+    let(:ip) { addrinfo.ip_address }
+
+    it "musst set #name to \"ip:port\"" do
+      expect(subject.name).to eq("#{ip}:#{port}")
+    end
+  end
+end

data/spec/sessions/reverse_shell_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper'
+require 'ronin/post_ex/sessions/reverse_shell'
+
+describe Ronin::PostEx::Sessions::ReverseShell do
+  it "must inherit from Ronin::PostEx::Sessions::RemoteShellSession" do
+    expect(described_class).to be < Ronin::PostEx::Sessions::RemoteShellSession
+  end
+
+  let(:host)     { 'localhost' }
+  let(:port)     { 1337 }
+  let(:addrinfo) { Addrinfo.tcp(host,port) }
+
+  describe ".listen" do
+    let(:server_socket) { double('TCPServer') }
+    let(:client_socket) { double('TCPSocket') }
+
+    before  { allow(client_socket).to receive(:remote_address).and_return(addrinfo) }
+    subject { described_class }
+
+    it "must listen on a local port, accept a connection, return a #{described_class} object, and close the server socket" do
+      expect(TCPServer).to receive(:new).with(port,nil).and_return(server_socket)
+      expect(server_socket).to receive(:listen).with(1)
+      expect(server_socket).to receive(:accept).and_return(client_socket)
+      expect(server_socket).to receive(:close)
+
+      reverse_shell = subject.listen(port)
+
+      expect(reverse_shell).to be_kind_of(described_class)
+      expect(reverse_shell.io).to be(client_socket)
+    end
+
+    context "and a host argument is given" do
+      let(:host) { '127.0.0.1' }
+
+      it "must listen on a local host and port, accept a connection, return a #{described_class} object, and close the server socket" do
+        expect(TCPServer).to receive(:new).with(port,host).and_return(server_socket)
+        expect(server_socket).to receive(:listen).with(1)
+        expect(server_socket).to receive(:accept).and_return(client_socket)
+        expect(server_socket).to receive(:close)
+        allow(client_socket).to receive(:local_address).and_return(addrinfo)
+
+        reverse_shell = subject.listen(host,port)
+
+        expect(reverse_shell).to be_kind_of(described_class)
+        expect(reverse_shell.io).to be(client_socket)
+      end
+    end
+  end
+end