ronin-post_ex 0.1.0.beta1

data/lib/ronin/post_ex/system/fs.rb

@@ -0,0 +1,650 @@
+# 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/remote_file'
+require 'ronin/post_ex/remote_file/stat'
+require 'ronin/post_ex/remote_dir'
+
+require 'hexdump'
+
+module Ronin
+  module PostEx
+    class System < Resource
+      #
+      # Provides access to a system's a File System (FS).
+      #
+      # # Supported API Methods
+      #
+      # The File System resource uses the following post-exploitation methods,
+      # defined by the {#session} object:
+      #
+      # * `fs_getcwd() -> String`
+      # * `fs_chdir(path : String)`
+      # * `fs_readlink(path : String) -> String`
+      # * `fs_readdir(path : String) -> Array[String]`
+      # * `fs_glob(pattern : String) -> Array[String]`
+      # * `fs_mktemp(basename : String) -> String`
+      # * `fs_mkdir(new_path : String)`
+      # * `fs_copy(src : String, dest : String)`
+      # * `fs_unlink(path : String)`
+      # * `fs_rmdir(path : String)`
+      # * `fs_move(src : String, dest : String)`
+      # * `fs_link(src : String, dest : String)`
+      # * `fs_chgrp(group : String, path : String)`
+      # * `fs_chown(user : String, path : String)`
+      # * `fs_chmod(mode : Integer, path : String)`
+      # * `fs_stat(path : String) => Hash[Symbol, Object] | nil`
+      #
+      class FS < Resource
+
+        #
+        # Gets the current working directory.
+        #
+        # @return [String]
+        #   The path of the current working directory.
+        #
+        # @note
+        #   May call the `fs_getcwd` method, if defined by the {#session}
+        #   object.
+        #
+        def getcwd
+          if @session.respond_to?(:fs_getcwd)
+            @cwd = @session.fs_getcwd
+          end
+
+          return @cwd
+        end
+        resource_method :getcwd, [:fs_getcwd]
+
+        alias getwd getcwd
+        alias pwd getcwd
+
+        #
+        # Changes the current working directory.
+        #
+        # @param [String] path
+        #   The path to use as the new current working directory.
+        #
+        # @return [String]
+        #   The new current working directory.
+        #
+        # @note
+        #   May call the `fs_chdir` method, if defined by the {#session}
+        #   object.
+        #
+        def chdir(path)
+          path = expand_path(path)
+          old_cwd = @cwd
+
+          @cwd = if @session.respond_to?(:fs_chdir)
+                   @session.fs_chdir(path)
+                 else
+                   path
+                 end
+
+          if block_given?
+            yield @cwd
+            chdir(old_cwd)
+          end
+
+          return @cwd
+        end
+        resource_method :chdir
+
+        #
+        # Joins the path with the current working directory.
+        #
+        # @param [String] path
+        #   The path to join.
+        #
+        # @return [String]
+        #   The absolute path.
+        #
+        def expand_path(path)
+          if (@cwd && path[0,1] != '/')
+            ::File.expand_path(::File.join(@cwd,path))
+          else
+            path
+          end
+        end
+
+        #
+        # Reads the full contents of a file.
+        #
+        # @param [String] path
+        #   The path to the file.
+        #
+        # @return [String]
+        #   The contents of the file.
+        #
+        # @note
+        #   Requires the `fs_readfile` method be defined by the {#session}
+        #   object.
+        #
+        def readfile(path)
+          @session.fs_readfile(path)
+        end
+        resource_method :readfile, [:fs_readfile]
+
+        #
+        # Reads the destination of a link.
+        #
+        # @param [String] path
+        #   The path to the link.
+        #
+        # @return [String]
+        #   The destination of the link.
+        #
+        # @note
+        #   Requires the `fs_readlink` method be defined by the {#session}
+        #   object.
+        #
+        def readlink(path)
+          @session.fs_readlink(path)
+        end
+        resource_method :readlink, [:fs_readlink]
+
+        #
+        # Opens a directory for reading.
+        #
+        # @param [String] path
+        #   The path to the directory.
+        #
+        # @return [RemoteDir]
+        #   The opened directory.
+        #
+        # @note
+        #   Requires the `fs_readdir` method be defined by the {#session}
+        #   object.
+        #
+        def readdir(path)
+          path    = expand_path(path)
+          entries = @session.fs_readdir(path)
+
+          return RemoteDir.new(path,entries)
+        end
+        resource_method :readdir, [:fs_readdir]
+
+        #
+        # Searches the file-system for matching paths.
+        #
+        # @param [String] pattern
+        #   A path-glob pattern.
+        #
+        # @yield [path]
+        #   The given block, will be passed each matching path.
+        #
+        # @return [String] path
+        #   A path in the file-system that matches the pattern.
+        #
+        # @return [Array<String>]
+        #   If no block is given, the matching paths will be returned.
+        #
+        # @example
+        #   exploit.fs.glob('*.txt')
+        #   # => [...]
+        #
+        # @example
+        #   exploit.fs.glob('**/*.xml') do |path|
+        #     # ...
+        #   end
+        #
+        # @note
+        #   Requires the `fs_glob` method be defined by the {#session} object.
+        #
+        def glob(pattern,&block)
+          path  = expand_path(pattern)
+          paths = @session.fs_glob(pattern)
+
+          paths.each(&block) if block
+          return paths
+        end
+        resource_method :glob, [:fs_glob]
+
+        #
+        # Opens a file for reading.
+        #
+        # @param [String] path
+        #   The path to file.
+        #
+        # @param [String] mode
+        #   The mode to open the file in.
+        #
+        # @yield [file]
+        #   If a block is given, it will be passed the newly opened file.
+        #   After the block has returned, the file will be closed and
+        #   `nil` will be returned.
+        #
+        # @yieldparam [RemoteFile] file
+        #   The temporarily opened remote file.
+        #
+        # @return [RemoteFile, nil]
+        #   If no block was given, then the newly opened remote file will be
+        #   returned.
+        #
+        # @see RemoteFile.open
+        #
+        def open(path,mode='r',&block)
+          RemoteFile.open(@session,expand_path(path),mode,&block)
+        end
+        resource_method :open
+
+        #
+        # Hexdumps the contents of a file.
+        #
+        # @param [String] path
+        #   The path of the file.
+        #
+        # @param [IO] output
+        #   The output stream to write the hexdump to.
+        #
+        # @return [nil]
+        #
+        def hexdump(path,output=STDOUT)
+          open(path) { |file| Hexdump.dump(file,output: output) }
+        end
+        resource_method :hexdump, [:fs_read]
+
+        #
+        # Writes data to a file.
+        #
+        # @param [String] path
+        #   The path to the file.
+        #
+        # @param [String] data
+        #   The data to write.
+        #
+        # @return [nil]
+        # 
+        def write(path,data)
+          open(path) { |file| file.write(data) }
+        end
+        resource_method :write, [:fs_write]
+
+        #
+        # Touches a file.
+        #
+        # @param [String] path
+        #   The path of the file.
+        #
+        # @return [nil]
+        #
+        def touch(path)
+          open(path) { |file| file << '' }
+        end
+        resource_method :touch, [:fs_write]
+
+        #
+        # Opens a tempfile.
+        #
+        # @param [String] basename
+        #   The base-name to use in the tempfile.
+        #
+        # @yield [tempfile]
+        #   The given block will be passed the newly opened tempfile.
+        #   After the block has returned, the tempfile will be closed
+        #   and `nil` will be returned.
+        #
+        # @yieldparam [RemoteFile] tempfile
+        #   The temporarily opened tempfile.
+        #
+        # @return [RemoteFile, nil]
+        #   The newly opened tempfile.
+        #
+        # @note
+        #   Requires the `fs_mktemp` method be defined by the {#session} object.
+        #
+        def tmpfile(basename,&block)
+          open(@session.fs_mktemp(basename),&block)
+        end
+        resource_method :tmpfile, [:fs_mktemp]
+
+        #
+        # Creates a directory.
+        #
+        # @param [String] path
+        #   The path of the directory.
+        #
+        # @return [true]
+        #   Specifies that the directory was successfully created.
+        #
+        # @note
+        #   Requires the `fs_mkdir` method be defined by the {#session} object.
+        #
+        def mkdir(path)
+          @session.fs_mkdir(path)
+          return true
+        end
+        resource_method :mkdir, [:fs_mkdir]
+
+        #
+        # Copies a file.
+        #
+        # @param [String] path
+        #   The path of the file to copy.
+        #
+        # @param [String] new_path
+        #   The destination path to copy to.
+        #
+        # @return [true]
+        #   Specifies that the file was successfully copied.
+        #
+        # @note
+        #   Requires the `fs_copy` method be defined by the {#session} object.
+        #
+        def copy(path,new_path)
+          @session.fs_copy(expand_path(path),expand_path(new_path))
+          return true
+        end
+        resource_method :copy, [:fs_copy]
+
+        #
+        # Unlinks a file.
+        #
+        # @param [String] path
+        #   The path of the file.
+        #
+        # @return [true]
+        #   Specifies that the file was successfully removed.
+        #
+        # @note
+        #   Requires the `fs_unlink` method be defined by the {#session} object.
+        #
+        def unlink(path)
+          @session.fs_unlink(expand_path(path))
+          return true
+        end
+        resource_method :unlink, [:fs_unlink]
+
+        alias rm unlink
+
+        #
+        # Removes a directory.
+        #
+        # @param [String] path
+        #   The path of the directory.
+        #
+        # @return [true]
+        #   Specifies that the directory was successfully removed.
+        #
+        # @note
+        #   Requires the `fs_rmdir` method be defined by the {#session} object.
+        #
+        def rmdir(path)
+          @session.fs_rmdir(expand_path(path))
+          return true
+        end
+        resource_method :rmdir, [:fs_rmdir]
+
+        #
+        # Moves a file or directory.
+        #
+        # @param [String] path
+        #   The path of the file or directory to be moved.
+        #
+        # @param [String] new_path
+        #   The destination path for the file or directory to be moved to.
+        #
+        # @return [true]
+        #   Specifies that the file or directory was successfully moved.
+        #
+        # @note
+        #   Requires the `fs_move` method be defined by the {#session} object.
+        #
+        def move(path,new_path)
+          @session.fs_move(expand_path(path),expand_path(new_path))
+          return true
+        end
+        resource_method :move, [:fs_move]
+
+        alias rename move
+
+        #
+        # Creates a symbolic link.
+        #
+        # @param [String] path
+        #   The path that the link will point to.
+        #
+        # @param [String] new_path
+        #   The path of the link.
+        #
+        # @return [true]
+        #   Specifies that the symbolic link was successfully created.
+        #
+        # @note
+        #   Requires the `fs_link` method be defined by the {#session} object.
+        #
+        def link(path,new_path)
+          @session.fs_link(path,new_path)
+          return true
+        end
+        resource_method :link, [:fs_link]
+
+        #
+        # Changes ownership of a file or directory.
+        #
+        # @param [String, (String,String)] owner
+        #   the user and/or group that will own the file or directory.
+        #
+        # @param [String] path
+        #   The path of the file or directory.
+        #
+        # @return [true]
+        #   Specifies that the ownership was successfully changed.
+        #
+        # @example
+        #   exploit.fs.chown('www', 'one.html')
+        #
+        # @example
+        #   exploit.fs.chown(['alice', 'users'], 'one.html')
+        #
+        # @note
+        #   Requires the `fs_chown` method be defined by the {#session} object.
+        #
+        def chown(owner,path)
+          user, group = owner
+
+          chgrp(group,path) if group
+
+          @session.fs_chown(user,expand_path(path))
+          return true
+        end
+        resource_method :chown, [:fs_chown]
+
+        #
+        # Changes group ownership on one or more files or directories.
+        #
+        # @param [String] group
+        #   The group that will own the file or directory.
+        #
+        # @param [String] path
+        #   The path of the file or directory.
+        #
+        # @return [true]
+        #   Specifies that the group ownership was successfully changed.
+        #
+        # @example
+        #   exploit.fs.chgrp('www', 'one.html')
+        #
+        # @note
+        #   Requires the `fs_chgrp` method be defined by the {#session} object.
+        #
+        def chgrp(group,path)
+          @session.fs_chgrp(group,expand_path(path))
+          return true
+        end
+        resource_method :chgrp, [:fs_chgrp]
+
+        #
+        # Changes permissions on one or more file or directorie.
+        #
+        # @param [Integer] mode
+        #   The new mode for the file or directory.
+        #
+        # @param [String] path
+        #   The path of the file or directory.
+        #
+        # @return [true]
+        #   Specifies that the permissions were successfully changed.
+        #
+        # @example
+        #   exploit.fs.chmod(0665, 'one.html')
+        #
+        # @note
+        #   Requires the `fs_chmod` method be defined by the {#session} object.
+        #
+        def chmod(mode,path)
+          @session.fs_chmod(mode,expand_path(path))
+          return true
+        end
+        resource_method :chmod, [:fs_chmod]
+
+        #
+        # Gathers statistics on a file or directory.
+        #
+        # @param [String] path
+        #   The path of the file or directory.
+        #
+        # @return [RemoteFile::Stat]
+        #   The statistics on the file or directory.
+        #
+        # @see RemoteFile::Stat#initialize
+        #
+        def stat(path)
+          RemoteFile::Stat.new(@session,expand_path(path))
+        end
+        resource_method :stat, [:fs_stat]
+
+        #
+        # Tests whether a file or directory exists.
+        #
+        # @param [String] path
+        #   The path of the file or directory in question.
+        #
+        # @return [Boolean]
+        #   Specifies whether the file or directory exists.
+        #
+        def exists?(path)
+          begin
+            stat(path)
+            return true
+          rescue Errno::ENOENT
+            return false
+          end
+        end
+        resource_method :exists?, [:fs_stat]
+
+        #
+        # Tests whether a file exists.
+        #
+        # @param [String] path
+        #   The path of the file in question.
+        #
+        # @return [Boolean]
+        #   Specifies whether the file exists.
+        #
+        def file?(path)
+          begin
+            stat(path).file?
+          rescue Errno::ENOENT
+            return false
+          end
+        end
+        resource_method :file?, [:fs_stat]
+
+        #
+        # Tests whether a directory exists.
+        #
+        # @param [String] path
+        #   The path of the directory in question.
+        #
+        # @return [Boolean]
+        #   Specifies whether the directory exists.
+        #
+        def directory?(path)
+          begin
+            stat(path).directory?
+          rescue Errno::ENOENT
+            return false
+          end
+        end
+        resource_method :directory?, [:fs_stat]
+
+        #
+        # Tests whether a FIFO pipe exists.
+        #
+        # @param [String] path
+        #   The path of the FIFO pipe in question.
+        #
+        # @return [Boolean]
+        #   Specifies whether the FIFO pipe exists.
+        #
+        def pipe?(path)
+          begin
+            stat(path).pipe?
+          rescue Errno::ENOENT
+            return false
+          end
+        end
+        resource_method :pipe?, [:fs_stat]
+
+        #
+        # Tests whether a UNIX socket exists.
+        #
+        # @param [String] path
+        #   The path of the UNIX socket in question.
+        #
+        # @return [Boolean]
+        #   Specifies whether the UNIX socket exists.
+        #
+        def socket?(path)
+          begin
+            stat(path).socket?
+          rescue Errno::ENOENT
+            return false
+          end
+        end
+        resource_method :socket?, [:fs_stat]
+
+        #
+        # Tests whether a file is empty.
+        #
+        # @param [String] path
+        #   The path of the file in question.
+        #
+        # @return [Boolean]
+        #   Specifies whether the file is empty.
+        #
+        def zero?(path)
+          begin
+            stat(path).zero?
+          rescue Errno::ENOENT
+            return false
+          end
+        end
+        resource_method :zero?, [:fs_stat]
+
+        alias empty? zero?
+
+      end
+    end
+  end
+end