ronin-post_ex 0.1.0.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 403e9fcdbeec51db102129de41d5ab773c2f86b2befec71424ade570f0486064
+  data.tar.gz: a3eb7c6dbe7a4b5673b4b35bd425f384418084a17765d0a7602b63cb1eb35427
+SHA512:
+  metadata.gz: 7e986a6e7b619c6eb56144e8c190378c8659db22c0bc71f9d91a749a26f915bd855e6447fdbe41dbea2ff73b1c21d26d1b1f93ee7cb56c000c70117858df8a12
+  data.tar.gz: e3ac243381c04b7f79173b3bcdff9f0afb23d1393d2d9d7b0e66d2bc5f6f75afd76a34a82102ef58378fb45220d80adbb0ff38b0c850dce58f5a6fc4641318d9

data/.document

@@ -0,0 +1,6 @@
+lib/**/*.rb
+- 
+API_SPEC.md
+ChangeLog.md
+COPYING.txt
+man/*.md

data/.github/workflows/ruby.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on: [ push, pull_request ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - '3.0'
+          - '3.1'
+          - '3.2'
+          - jruby
+          - truffleruby
+    name: Ruby ${{ matrix.ruby }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install libsqlite3
+        run: |
+          sudo apt update -y && \
+          sudo apt install -y --no-install-recommends --no-install-suggests libsqlite3-dev
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+      - name: Run tests
+        run: bundle exec rake test

data/.gitignore

@@ -0,0 +1,13 @@
+/coverage
+/doc
+/pkg
+/man/*.[1-9]
+/vendor/bundle
+/Gemfile.lock
+/.bundle
+/.yardoc
+.DS_Store
+*.db
+*.log
+*.swp
+*~

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.ruby-version

@@ -0,0 +1 @@
+ruby-3.1

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title 'Ronin PostEx Documentation' --protected

data/API_SPEC.md

@@ -0,0 +1,235 @@
+# Post-Exploitation API Specification
+
+## Sys Functions
+
+### `sys_time -> Integer`
+
+Gets the current time and returns the UNIX timestamp.
+
+### `sys_hostname -> String`
+
+Gets the system's hostname.
+
+## File Functions
+
+### `file_open(path : String, mode : String) -> Integer`
+
+Opens a file and returns the file-descriptor number.
+
+### `file_read(fd : Integer, length : Integer) -> String | nil`
+
+Reads from an opened file-descriptor and returns the read data.
+`nil` will be returned if there is no more data to be read.
+
+### `file_write(fd : Integer, pos : Integer, data : String) -> Integer`
+
+Writes data to the opened file-descriptor.
+
+### `file_seek(fd : Integer, new_pos : Integer, whence : String)`
+
+Seeks to a position within the file. The `whence` argument must be one of the
+following strings:
+
+* `"SEEK_SET"` - seek from beginning of file.
+* `"SEEK_CUR"` - seek from current position.
+* `"SEEK_END"` - seek from end of file.
+* `"SEEK_DATA"` - seek to next data.
+* `"SEEK_HOLE"` - seek to next hole.
+
+### `file_tell(fd : Integer) -> Integer`
+
+Queries the current position within the file.
+
+### `file_ioctl(fd : Integer, command : String | Array[Integer], argument : Object) -> Integer`
+
+Performs a `ioctl()` operation on the file-descriptor.
+
+### `file_fcntl(fd : Integer, command : String | Array[Integer], argument : Object) -> Integer`
+
+Performs a `fcntl()` operation on the file-descriptor.
+
+### `file_stat(fd : Integer) => Hash[Symbol, Object] | nil`
+
+Queries file information from the given file-descriptor and returns a Hash of
+file metadata.
+
+### `file_close(fd : Integer)`
+
+Closes an opened file-descriptor.
+
+## File-System Functions
+
+### `fs_getcwd() -> String`
+
+Gets the current working directory and returns the directory path.
+
+### `fs_chdir(path : String)`
+
+Changes the current working directory.
+
+### `fs_readfile(path : String) -> String | nil`
+
+Reads the entire file at the given path and returns the full file's contents.
+
+### `fs_readlink(path : String) -> String`
+
+Reads the destination path of a symbolic link.
+
+### `fs_readdir(path : String) -> Array[String]`
+
+Reads the contents of the directory and returns an Array of directory entry
+names.
+
+### `fs_glob(pattern : String) -> Array[String]`
+
+Evaluates a directory glob pattern and returns all matching paths.
+
+### `fs_mktemp(basename : String) -> String`
+
+Creates a temporary file with the given file basename.
+
+### `fs_mkdir(new_path : String)`
+
+Creates a new directory at the given path.
+
+### `fs_copy(src : String, dest : String)`
+
+Copies a source file to the destination path.
+
+### `fs_unlink(path : String)`
+
+Removes a file at the given path.
+
+### `fs_rmdir(path : String)`
+
+Removes an empty directory at the given path.
+
+### `fs_move(src : String, dest : String)`
+
+Moves or renames a source file to a destination path.
+
+### `fs_link(src : String, dest : String)`
+
+Creates a symbolic link at the destination path pointing to the source path.
+
+### `fs_chgrp(group : String, path : String)`
+
+Changes the group ownership of a file or directory.
+
+### `fs_chown(user : String, path : String)`
+
+Changes the user ownership of a file or directory.
+
+### `fs_chmod(mode : Integer, path : String)`
+
+Changes the permissions on a file or directory.
+
+### `fs_stat(path : String) => Hash[Symbol, Object] | nil`
+
+Queries file information from the given path and returns a Hash of file
+metadata.
+
+## Process Functions
+
+### `process_getpid -> Integer`
+
+Gets the current process's Process ID (PID).
+
+### `process_getppid -> Integer`
+
+Gets the current process's parent Process ID (PPID).
+
+### `process_getuid -> Integer`
+
+Gets the current process's user ID (UID).
+
+### `process_setuid(uid : Integer)`
+
+Sets the current process's user ID (UID) to the given Integer.
+
+### `process_geteuid -> Integer`
+
+Gets the current process's effective UID (EUID).
+
+### `process_seteuid(euid : Integer)`
+
+Sets the current process's effective UID (EUID) to the given Integer.
+
+### `process_getgid -> Integer`
+
+Gets the current process's group ID (GID).
+
+### `process_setgid(gid : Integer)`
+
+Sets the current process's group ID (GID) to the given Integer.
+
+### `process_getegid -> Integer`
+
+Gets the current process's effective group ID (EGID).
+
+### `process_setegid(egid : Integer)`
+
+Sets the current process's effective group ID (EGID) to the given Integer.
+
+### `process_getsid -> Integer`
+
+Gets the current process's session ID (SID).
+
+### `process_setsid(sid : Integer) -> Integer`
+
+Sets the current process's session ID (SID).
+
+### `process_environ -> Hash[String, String]`
+
+Queries all environment variables of the current process. Returns a Hash of the
+env variable names and values.
+
+### `process_getenv(name : String) -> String | nil`
+
+Gets an individual environment variable. If the environment variable has not
+been set, `nil` will be returned.
+
+### `process_setenv(name : String, value : String)`
+
+Sets an environment variable to the given value.
+
+### `process_unsetenv(name : String)`
+
+Un-sets an environment variable.
+
+### `process_kill(pid : Integer, signal : Integer)`
+
+Kills another process using the given Process ID (POD) and the signal number.
+
+### `process_popen(command : String) -> Integer`
+
+Opens a new process using the given command string.
+The file descriptor of the new process will be returned.
+
+### `process_read(fd : Integer, length : Integer) -> String`
+
+Reads data from the file descriptor returned by `process_popen`.
+
+### `process_write(fd : Integer, data : String)`
+
+Writes data to the file descriptor returned by `process_popen`.
+
+### `process_close(fd : Integer)`
+
+Closes the file descriptor of a remote process opened via `process_popen`.
+
+### `process_spawn(program : String, *arguments : Array[String]) -> Integer`
+
+Spawns a new process using the given program and additional arguments.
+The process ID (PID) of the new process will be returned.
+
+### `process_exit`
+
+Exits the current process.
+
+## Shell Functions
+
+### `shell_exec(command : String) -> String`
+
+Executes the given shell command and returns it's output.
+

data/COPYING.txt

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/ChangeLog.md

@@ -0,0 +1,23 @@
+### 0.1.0 / 2023-XX-XX
+
+* Initial release:
+  * 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.
+
+[API Spec]: https://github.com/ronin-rb/ronin-post_ex/blob/main/API_SPEC.md

data/Gemfile

@@ -0,0 +1,36 @@
+source 'https://rubygems.org'
+
+gemspec
+
+platform :jruby do
+  gem 'jruby-openssl',	'~> 0.7'
+end
+
+# gem 'fake_io', '~> 0.1', github: 'postmodern/fake_io.rb',
+#                          branch: 'main'
+
+# gem 'command_kit', '~> 0.4', github: 'postmodern/command_kit.rb',
+#                              branch: 'main'
+
+# Ronin dependencies
+# gem 'ronin-core',     '~> 0.1', github: "ronin-rb/ronin-core",
+#                                 branch: 'main'
+
+group :development do
+  gem 'rake'
+  gem 'rubygems-tasks',  '~> 0.2'
+
+  gem 'rspec',           '~> 3.0'
+  gem 'simplecov',       '~> 0.20'
+
+  gem 'kramdown',        '~> 2.0'
+  gem 'kramdown-man',    '~> 0.1'
+
+  gem 'redcarpet',       platform: :mri
+  gem 'yard',            '~> 0.9'
+  gem 'yard-spellcheck', require: false
+
+  gem 'dead_end',        require: false
+  gem 'sord',            require: false, platform: :mri
+  gem 'stackprof',       require: false, platform: :mri
+end