ronin-post_ex 0.1.0.beta1

data/lib/ronin/post_ex/remote_file.rb

@@ -0,0 +1,417 @@
+# 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/remote_file/stat'
+require 'ronin/post_ex/resource'
+
+require 'fake_io'
+require 'set'
+
+module Ronin
+  module PostEx
+    #
+    # The {RemoteFile} class represents files on a remote system. {RemoteFile}
+    # requires the API object to define either `file_read` and/or `file_write`.
+    # Additionally, {RemoteFile} can optionally use the `file_open`,
+    # `file_close`, `file_tell`, `file_seek` and `file_stat` methods.
+    #
+    # ## Supported API Methods
+    #
+    # * `file_open(path : String, mode : String) -> Integer`
+    # * `file_read(fd : Integer, length : Integer) -> String | nil`
+    # * `file_write(fd : Integer, pos : Integer, data : String) -> Integer`
+    # * `file_seek(fd : Integer, new_pos : Integer, whence : String)`
+    # * `file_tell(fd : Integer) -> Integer`
+    # * `file_ioctl(fd : Integer, command : String | Array[Integer], argument : Object) -> Integer`
+    # * `file_fcntl(fd : Integer, command : String | Array[Integer], argument : Object) -> Integer`
+    # * `file_stat(fd : Integer) => Hash[Symbol, Object] | nil`
+
+    # * `file_close(fd : Integer)`
+    # * `fs_readfile(path : String) -> String | nil`
+    # * `fs_stat(path : String) => Hash[Symbol, Object] | nil`
+    #
+    class RemoteFile < Resource
+
+      include FakeIO
+
+      #
+      # Creates a new remote controlled File object.
+      #
+      # @param [Sessions::Session#file_read, Sessions::Session#file_write] session
+      #   The session object that defines the `file_read` and `file_write`
+      #   methods.
+      #
+      # @param [String] path
+      #   The path of the remote file.
+      #
+      # @param [String] mode
+      #   The mode to open the file in.
+      #
+      # @note
+      #   This method may use the `file_open` method, if it is defined by
+      #   {#session}.
+      #
+      def initialize(session,path,mode='r')
+        @session = session
+
+        @path = path.to_s
+        @mode = mode.to_s
+
+        super()
+      end
+
+      #
+      # Opens a file.
+      #
+      # @param [Sessions::Session#file_read, Sessions::Session#file_write] session
+      #   The session object controlling remote files.
+      #
+      # @param [String] path
+      #   The path of the remote file.
+      #
+      # @yield [file]
+      #   The given block will be passed the newly created file object.
+      #   When the block has returned, the File object will be closed.
+      #
+      # @yieldparam [RemoteFile]
+      #   The newly created file object.
+      #
+      # @return [RemoteFile, nil]
+      #   If no block is given, then the newly opened remote file object will be
+      #   returned. If a block was given, then `nil` will be returned.
+      #
+      def self.open(session,path)
+        io = new(session,path)
+
+        if block_given?
+          yield(io)
+          io.close
+          return
+        else
+          return io
+        end
+      end
+
+      # Seeks from beginning of file.
+      SEEK_SET  = File::SEEK_SET
+
+      # Seeks from current position.
+      SEEK_CUR  = File::SEEK_CUR
+
+      # Seeks from end of file.
+      SEEK_END  = File::SEEK_END
+
+      # Seeks to next data.
+      SEEK_DATA = (defined?(File::SEEK_DATA) && File::SEEK_DATA) || 3
+
+      # Seeks to next hole.
+      SEEK_HOLE = (defined?(File::SEEK_HOLE) && File::SEEK_HOLE) || 4
+
+      # Mapping of `SEEK_*` constants to their String values.
+      #
+      # @api private
+      WHENCE = {
+        SEEK_SET  => 'SEEK_SET',
+        SEEK_CUR  => 'SEEK_CUR',
+        SEEK_END  => 'SEEK_END',
+        SEEK_DATA => 'SEEK_DATA',
+        SEEK_HOLE => 'SEEK_HOLE'
+      }
+
+      #
+      # Sets the position in the file to read.
+      #
+      # @param [Integer] new_pos
+      #   The new position to read from.
+      #
+      # @param [Integer] whence
+      #   The origin point to seek from.
+      #
+      # @return [Integer]
+      #   The new position within the file.
+      #
+      # @raise [ArgumentError]
+      #   An invalid whence value was given.
+      #
+      # @note This method may use the `file_seek` API method, if it is defined
+      # by {#session}.
+      #
+      def seek(new_pos,whence=SEEK_SET)
+        clear_buffer!
+
+        unless WHENCE.has_key?(whence)
+          raise(ArgumentError,"invalid whence value: #{whence.inspect}")
+        end
+
+        if @session.respond_to?(:file_seek)
+          @session.file_seek(@fd,new_pos,WHENCE[whence])
+        end
+
+        @pos = new_pos
+      end
+      resource_method :seek, [:file_seek]
+
+      #
+      # The current offset in the file.
+      #
+      # @return [Integer]
+      #   The current offset in bytes.
+      #
+      # @note
+      #   This method may use the `file_tell` API method, if it is defined by
+      #   {#session}.
+      #
+      def tell
+        if @session.respond_to?(:file_tell)
+          @pos = @session.file_tell(@fd)
+        else
+          @pos
+        end
+      end
+      resource_method :tell, [:file_tell]
+
+      #
+      # Executes a low-level command to control or query the IO stream.
+      #
+      # @param [String, Array<Integer>] command
+      #   The IOCTL command.
+      #
+      # @param [Object] argument
+      #   Argument of the command.
+      #
+      # @return [Integer]
+      #   The return value from the `ioctl`.
+      #
+      # @raise [NotImplementedError]
+      #   The API object does not define `file_ioctl`.
+      #
+      # @raise [RuntimeError]
+      #   The `file_ioctl` method requires a file-descriptor.
+      #
+      # @note This method requires the `file_ioctl` API method.
+      #
+      def ioctl(command,argument)
+        unless @session.respond_to?(:file_ioctl)
+          raise(NotImplementedError,"#{@session.inspect} does not define file_ioctl")
+        end
+
+        if @fd == nil
+          raise(RuntimeError,"file_ioctl requires a file-descriptor")
+        end
+
+        return @session.file_ioctl(@fd,command,argument)
+      end
+      resource_method :ioctl, [:file_ioctl]
+
+      #
+      # Executes a low-level command to control or query the file stream.
+      #
+      # @param [String, Array<Integer>] command
+      #   The FCNTL command.
+      #
+      # @param [Object] argument
+      #   Argument of the command.
+      #
+      # @return [Integer]
+      #   The return value from the `fcntl`.
+      #
+      # @raise [NotImplementedError]
+      #   The API object does not define `file_fcntl`.
+      #
+      # @note This method requires the `file_fnctl` API method.
+      #
+      def fcntl(command,argument)
+        unless @session.respond_to?(:file_fcntl)
+          raise(NotImplementedError,"#{@session.inspect} does not define file_fcntl")
+        end
+
+        if @fd == nil
+          raise(RuntimeError,"file_ioctl requires a file-descriptor")
+        end
+
+        return @session.file_fcntl(@fd,command,argument)
+      end
+      resource_method :fcntl, [:file_fcntl]
+
+      #
+      # Re-opens the file.
+      #
+      # @param [String] path
+      #   The new path for the file.
+      #
+      # @return [RemoteFile]
+      #   The re-opened the file.
+      #
+      # @note
+      #   This method may use the `file_close` and `file_open` API methods,
+      #   if they are defined by {#session}.
+      #
+      def reopen(path)
+        close
+
+        @path = path.to_s
+        return open
+      end
+      resource_method :reopen, [:file_close, :file_open]
+
+      #
+      # The status information for the file.
+      #
+      # @return [Stat]
+      #   The status information.
+      #
+      # @note This method relies on the `fs_stat` API method.
+      #
+      def stat
+        if @fd
+          Stat.new(@session, fd: @fd)
+        else
+          Stat.new(@session, path: @path)
+        end
+      end
+      resource_method :stat, [:file_stat]
+
+      #
+      # Flushes the file.
+      #
+      # @return [self]
+      #
+      # @note This method may use the `file_flush` API method, if it is defined
+      # by {#session}.
+      #
+      def flush
+        if @session.respond_to?(:file_flush)
+          @session.file_flush
+        end
+
+        return self
+      end
+
+      #
+      # Flushes the file before closing it.
+      #
+      # @return [nil]
+      #
+      def close
+        flush if @mode.include?('w')
+        super()
+      end
+
+      #
+      # Inspects the open file.
+      #
+      # @return [String]
+      #   The inspected open file.
+      #
+      def inspect
+        "#<#{self.class}:#{@path}>"
+      end
+
+      private
+
+      #
+      # Attempts calling `file_open` from the API object to open the remote
+      # file.
+      #
+      # @return [Object]
+      #   The file descriptor returned by `file_open`.
+      #
+      # @note
+      #   This method may use the `file_open` API method, if {#session} defines
+      #   it.
+      #
+      def io_open
+        if @session.respond_to?(:file_open)
+          @session.file_open(@path,@mode)
+        end
+      end
+      resource_method :open
+
+      # Default block size to read file data with.
+      BLOCK_SIZE = 4096
+
+      #
+      # Reads a block from the remote file by calling `file_read` or
+      # `fs_readfile` from the API object.
+      #
+      # @return [String, nil]
+      #   A block of data from the file or `nil` if there is no more data to be
+      #   read.
+      #
+      # @raise [IOError]
+      #   The API object does not define `file_read` or `fs_readfile`.
+      #
+      # @note
+      #   This method requires either the `fs_readfile` or `file_read` API
+      #   methods.
+      #
+      def io_read
+        if @session.respond_to?(:file_read)
+          @session.file_read(@fd,BLOCK_SIZE)
+        elsif @api.respond_to?(:fs_readfile)
+          @eof = true
+          @api.fs_readfile(@path)
+        else
+          raise(IOError,"#{@session.inspect} does not support reading")
+        end
+      end
+      resource_method :read, [:file_read]
+
+      #
+      # Writes data to the remote file by calling `file_write` from the
+      # API object.
+      #
+      # @param [String] data
+      #   The data to write.
+      #
+      # @return [Integer]
+      #   The number of bytes writen.
+      #
+      # @raise [IOError]
+      #   The API object does not define `file_write`.
+      #
+      # @note This method requires the `file_write` API method.
+      #
+      def io_write(data)
+        if @session.respond_to?(:file_write)
+          @pos += @session.file_write(@fd,@pos,data)
+        else
+          raise(IOError,"#{@session.inspect} does not support writing to files")
+        end
+      end
+      resource_method :write, [:file_write]
+
+      #
+      # Attempts calling `file_close` from the API object to close
+      # the file.
+      #
+      # @note This method may use the `file_close` method, if {#session} defines
+      # it.
+      #
+      def io_close
+        if @session.respond_to?(:file_close)
+          @session.file_close(@fd)
+        end
+      end
+      resource_method :close
+
+    end
+  end
+end

data/lib/ronin/post_ex/remote_process.rb

@@ -0,0 +1,170 @@
+# 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 'fake_io'
+
+module Ronin
+  module PostEx
+    #
+    # The {RemoteProcess} class represents a command being executed on a remote
+    # system. The {RemoteProcess} class wraps around the `process_popen` and
+    # `process_read`, `process_write`, and `process_close` methods defined in
+    # the API object.
+    #
+    class RemoteProcess < Resource
+
+      include FakeIO
+      include Enumerable
+
+      # The command string.
+      #
+      # @return [String]
+      attr_reader :command
+
+      #
+      # Creates a new remote process.
+      #
+      # @param [Sessions::Session] session
+      #   The object controlling command execution.
+      #
+      # @param [String] command
+      #   The command to run.
+      #
+      # @raise [NotImplementedError]
+      #   The session object does not define `process_popen`.
+      #
+      def initialize(session,command)
+        unless session.respond_to?(:process_popen)
+          raise(NotImplementedError,"#{session.inspect} must define #process_popen for #{self.class}")
+        end
+
+        @session = session
+        @command = command
+
+        super()
+      end
+
+      #
+      # Reopens the command.
+      #
+      # @param [String] command
+      #   The new command to run.
+      #
+      # @return [RemoteProcess]
+      #   The new command.
+      #
+      def reopen(command)
+        close
+
+        @command = command
+
+        return open
+      end
+      resource_method :reopen, [:process_popen]
+
+      #
+      # Converts the command to a `String`.
+      #
+      # @return [String]
+      #   The process'es command.
+      #
+      def to_s
+        @command
+      end
+
+      #
+      # Inspects the command.
+      #
+      # @return [String]
+      #   The inspected command listing the program name and arguments.
+      #
+      def inspect
+        "#<#{self.class}: #{self}>"
+      end
+
+      private
+
+      #
+      # Executes and opens the command for reading.
+      #
+      # @return [Enumerator]
+      #   The enumerator that wraps around `process_popen`.
+      #
+      def io_open
+        @session.enum_for(:process_popen,@command)
+      end
+      resource_method :open, [:process_popen]
+
+      # Default block size to read process output with.
+      BLOCK_SIZE = 4096
+
+      #
+      # Reads a line of output from the command.
+      #
+      # @return [String]
+      #   A line of output.
+      #
+      # @raise [EOFError]
+      #   The end of the output stream has been reached.
+      #
+      def io_read
+        if @session.respond_to?(:process_read)
+          @session.process_write(@fd,BLOCK_SIZE)
+        end
+      end
+      resource_method :read
+
+      #
+      # Writes data to the shell.
+      #
+      # @param [String] data
+      #   The data to write to the shell.
+      #
+      # @return [Integer]
+      #   The number of bytes writen.
+      #
+      def io_write(data)
+        if @session.respond_to?(:process_write)
+          @session.process_write(@fd,data)
+        else
+          raise(IOError,"#{@session.inspect} does not support writing to the shell")
+        end
+      end
+      resource_method :write, [:process_write]
+
+      #
+      # Attempts calling `process_close` from the API object to close
+      # the file.
+      #
+      # @note
+      #   This method may use the `process_close` method, if {#session} defines it.
+      #
+      def io_close
+        if @session.respond_to?(:process_close)
+          @session.process_close(@fd)
+        end
+      end
+      resource_method :close
+
+    end
+  end
+end