1<!DOCTYPE html> 2<html> 3 <head> 4 <meta charset="UTF-8"> 5<meta name="viewport" content="width=device-width, initial-scale=1.0"> 6<title> 7 File: README 8 9 — Ronin::PostEx Documentation 10 11</title> 12 13 <link rel="stylesheet" href="css/style.css" type="text/css" /> 14 15 <link rel="stylesheet" href="css/common.css" type="text/css" /> 16
17<script type="text/javascript"> 18 pathId = "README"; 19 relpath = ''; 20</script>
20 21 22 23
23<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
23 24 25
25<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
25 26 27 28 </head> 29 <body> 30 <div class="nav_wrap"> 31 <iframe id="nav" src="class_list.html?1"></iframe> 32 <div id="resizer"></div> 33 </div> 34 35 <div id="main" tabindex="-1"> 36 <div id="header"> 37 <div id="menu"> 38 39 <a href="_index.html">Index</a> » 40 <span class="title">File: README</span> 41 42</div> 43 44 <div id="search"> 45 46 <a class="full_list_link" id="class_list_link" 47 href="class_list.html"> 48 49 <svg width="24" height="24"> 50 <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect> 51 <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect> 52 <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect> 53 </svg> 54 </a> 55 56</div> 57 <div class="clear"></div> 58 </div> 59 60 <div id="content"><div id='filecontents'><h1 id="ronin-post_ex">ronin-post_ex</h1> 61 62<p><a href="https://github.com/ronin-rb/ronin-post_ex/actions/workflows/ruby.yml"><img src="https://github.com/ronin-rb/ronin-post_ex/actions/workflows/ruby.yml/badge.svg" alt="CI"></a> 63<a href="https://codeclimate.com/github/ronin-rb/ronin-post_ex"><img src="https://codeclimate.com/github/ronin-rb/ronin-post_ex.svg" alt="Code Climate"></a> 64<a href="https://badge.fury.io/rb/ronin-post_ex"><img src="https://badge.fury.io/rb/ronin-post_ex.svg" alt="Gem Version"></a></p> 65 66<ul> 67<li><a href="https://ronin-rb.dev/">Website</a></li> 68<li><a href="https://github.com/ronin-rb/ronin-post_ex">Source</a></li> 69<li><a href="https://github.com/ronin-rb/ronin-post_ex/issues">Issues</a></li> 70<li><a href="https://ronin-rb.dev/docs/ronin-post_ex/frames">Documentation</a></li> 71<li><a href="https://discord.gg/6WAb3PsVX9">Discord</a> | 72<a href="https://twitter.com/ronin_rb">Twitter</a> | 73<a href="https://infosec.exchange/@ronin_rb">Mastodon</a></li> 74</ul> 75 76<h2 id="description">Description</h2> 77 78<p>ronin-post_ex is a Ruby API for Post-Exploitation.</p> 79 80<p>This library is used by <a href="https://github.com/ronin-rb/ronin-payloads#readme">ronin-payloads</a>, <a href="https://github.com/ronin-rb/ronin-c2#readme">ronin-c2</a>, and <a href="https://github.com/ronin-rb/ronin-exploits#readme">ronin-exploits</a> 81to provide a Post-Exploitation API around payloads, C2 sessions, or even 82exploits.</p> 83 84<p>ronin-post_ex is part of the <a href="https://ronin-rb.dev">ronin-rb</a> project, a <a href="https://www.ruby-lang.org">Ruby</a> toolkit for security 85research and development.</p> 86 87<h2 id="features">Features</h2> 88 89<ul> 90<li>Defines a syscall-like <a href="https://github.com/ronin-rb/ronin-post_ex/blob/main/API_SPEC.md">API for Post-Exploitation</a>.</li> 91<li>Provides classes for interacting with the Post-Exploitation API. 92 93<ul> 94<li><span class='object_link'><a href="Ronin/PostEx/System.html" title="Ronin::PostEx::System (class)">Ronin::PostEx::System</a></span> - allows interacting with a remote system.</li> 95<li><span class='object_link'><a href="Ronin/PostEx/System/FS.html" title="Ronin::PostEx::System::FS (class)">Ronin::PostEx::System::FS</a></span> - allows interacting with the file-system.</li> 96<li><span class='object_link'><a href="Ronin/PostEx/System/Process.html" title="Ronin::PostEx::System::Process (class)">Ronin::PostEx::System::Process</a></span> - allows manipulating the current process 97or child processes.</li> 98<li><span class='object_link'><a href="Ronin/PostEx/System/Shell.html" title="Ronin::PostEx::System::Shell (class)">Ronin::PostEx::System::Shell</a></span> - allows interacting with an interactive 99shell..</li> 100<li><span class='object_link'><a href="Ronin/PostEx/RemoteFile.html" title="Ronin::PostEx::RemoteFile (class)">Ronin::PostEx::RemoteFile</a></span> - allows reading/writing files.</li> 101<li><span class='object_link'><a href="Ronin/PostEx/RemoteDir.html" title="Ronin::PostEx::RemoteDir (class)">Ronin::PostEx::RemoteDir</a></span> - allows reading the contents of directories.</li> 102<li><span class='object_link'><a href="Ronin/PostEx/RemoteProcess.html" title="Ronin::PostEx::RemoteProcess (class)">Ronin::PostEx::RemoteProcess</a></span> - allows reading/writing to an running 103command.</li> 104</ul></li> 105<li>Supports interacting with interactive shell commands.</li> 106<li>Provides interactive command shells for interacting with systems.</li> 107<li>Supports Linux/BSD/UNIX systems.</li> 108<li>Provides common post-exploitation session classes for interacting with shells, 109bind shells, and reverse shells.</li> 110<li>Supports defining custom post-exploitation session classes.</li> 111</ul> 112 113<h2 id="limitations">Limitations</h2> 114 115<ul> 116<li>Does not currently support Windows systems.</li> 117<li>Does not fully support bidirectional fully interactive shell commands.</li> 118</ul> 119 120<h2 id="examples">Examples</h2> 121 122<h3 id="bind-shell">Bind Shell</h3> 123 124<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_session'>session</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Ronin.html" title="Ronin (module)">Ronin</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Ronin/PostEx.html" title="Ronin::PostEx (module)">PostEx</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Ronin/PostEx/Sessions.html" title="Ronin::PostEx::Sessions (module)">Sessions</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Ronin/PostEx/Sessions/BindShell.html" title="Ronin::PostEx::Sessions::BindShell (class)">BindShell</a></span></span><span class='period'>.</span><span class='id identifier rubyid_connect'><span class='object_link'><a href="Ronin/PostEx/Sessions/BindShell.html#connect-class_method" title="Ronin::PostEx::Sessions::BindShell.connect (method)">connect</a></span></span><span class='lparen'>(</span><span class='id identifier rubyid_host'>host</span><span class='comma'>,</span><span class='id identifier rubyid_port'>port</span><span class='rparen'>)</span> 125<span class='id identifier rubyid_system'>system</span> <span class='op'>=</span> <span class='id identifier rubyid_session'>session</span><span class='period'>.</span><span class='id identifier rubyid_system'>system</span> 126 127<span class='id identifier rubyid_system'>system</span><span class='period'>.</span><span class='id identifier rubyid_shell'>shell</span><span class='period'>.</span><span class='id identifier rubyid_ls'>ls</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>/</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> 128<span class='comment'># => "..." 129</span></code></pre> 130 131<h3 id="reverse-shell">Reverse Shell</h3> 132 133<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_session'>session</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Ronin.html" title="Ronin (module)">Ronin</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Ronin/PostEx.html" title="Ronin::PostEx (module)">PostEx</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Ronin/PostEx/Sessions.html" title="Ronin::PostEx::Sessions (module)">Sessions</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Ronin/PostEx/Sessions/ReverseShell.html" title="Ronin::PostEx::Sessions::ReverseShell (class)">ReverseShell</a></span></span><span class='period'>.</span><span class='id identifier rubyid_listen'><span class='object_link'><a href="Ronin/PostEx/Sessions/ReverseShell.html#listen-class_method" title="Ronin::PostEx::Sessions::ReverseShell.listen (method)">listen</a></span></span><span class='lparen'>(</span><span class='id identifier rubyid_host'>host</span><span class='comma'>,</span><span class='id identifier rubyid_port'>port</span><span class='rparen'>)</span> 134<span class='id identifier rubyid_system'>system</span> <span class='op'>=</span> <span class='id identifier rubyid_session'>session</span><span class='period'>.</span><span class='id identifier rubyid_system'>system</span> 135 136<span class='id identifier rubyid_system'>system</span><span class='period'>.</span><span class='id identifier rubyid_shell'>shell</span><span class='period'>.</span><span class='id identifier rubyid_ls'>ls</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>/</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> 137<span class='comment'># => "..." 138</span></code></pre> 139 140<h3 id="custom-session-class">Custom Session Class</h3> 141 142<p>Define a custom session class which defines the 143<a href="https://github.com/ronin-rb/ronin-post_ex/blob/main/API_SPEC.md">Post-Exploitation API methods</a>:</p> 144 145<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>RATSession</span> <span class='op'><</span> <span class='const'><span class='object_link'><a href="Ronin.html" title="Ronin (module)">Ronin</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Ronin/PostEx.html" title="Ronin::PostEx (module)">PostEx</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Ronin/PostEx/Sessions.html" title="Ronin::PostEx::Sessions (module)">Sessions</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Ronin/PostEx/Sessions/Session.html" title="Ronin::PostEx::Sessions::Session (class)">Session</a></span></span> 146 147 <span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='id identifier rubyid_host'>host</span><span class='comma'>,</span><span class='id identifier rubyid_port'>port</span><span class='rparen'>)</span> 148 <span class='comment'># ... 149</span> <span class='kw'>end</span> 150 151 <span class='kw'>def</span> <span class='id identifier rubyid_rpc_call'>rpc_call</span><span class='lparen'>(</span><span class='id identifier rubyid_method'>method</span><span class='comma'>,</span><span class='op'>*</span><span class='id identifier rubyid_arguments'>arguments</span><span class='rparen'>)</span> 152 <span class='comment'># ... 153</span> <span class='kw'>end</span> 154 155 <span class='kw'>def</span> <span class='id identifier rubyid_fs_read'>fs_read</span><span class='lparen'>(</span><span class='id identifier rubyid_path'>path</span><span class='rparen'>)</span> 156 <span class='id identifier rubyid_rpc_call'>rpc_call</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>fs_read</span><span class='tstring_end'>"</span></span><span class='comma'>,</span><span class='id identifier rubyid_path'>path</span><span class='rparen'>)</span> 157 <span class='kw'>end</span> 158 159 <span class='kw'>def</span> <span class='id identifier rubyid_shell_exec'>shell_exec</span><span class='lparen'>(</span><span class='id identifier rubyid_command'>command</span><span class='rparen'>)</span> 160 <span class='id identifier rubyid_rpc_call'>rpc_call</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>shell_exec</span><span class='tstring_end'>"</span></span><span class='comma'>,</span><span class='id identifier rubyid_command'>command</span><span class='rparen'>)</span> 161 <span class='kw'>end</span> 162 163 <span class='comment'># ... 164</span> 165<span class='kw'>end</span> 166 167<span class='id identifier rubyid_session'>session</span> <span class='op'>=</span> <span class='const'>RATSession</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span> 168<span class='id identifier rubyid_system'>system</span> <span class='op'>=</span> <span class='id identifier rubyid_session'>session</span><span class='period'>.</span><span class='id identifier rubyid_system'>system</span> 169</code></pre> 170 171<h3 id="system">System</h3> 172 173<p>Interact with the system's remote files as if they were local files:</p> 174 175<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_file'>file</span> <span class='op'>=</span> <span class='id identifier rubyid_system'>system</span><span class='period'>.</span><span class='id identifier rubyid_fs'>fs</span><span class='period'>.</span><span class='id identifier rubyid_open'>open</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>/etc/passwd</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> 176 177<span class='id identifier rubyid_file'>file</span><span class='period'>.</span><span class='id identifier rubyid_each_line'>each_line</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_line'>line</span><span class='op'>|</span> 178 <span class='id identifier rubyid_user'>user</span><span class='comma'>,</span> <span class='id identifier rubyid_x'>x</span><span class='comma'>,</span> <span class='id identifier rubyid_uid'>uid</span><span class='comma'>,</span> <span class='id identifier rubyid_gid'>gid</span><span class='comma'>,</span> <span class='id identifier rubyid_name'>name</span><span class='comma'>,</span> <span class='id identifier rubyid_home_dir'>
178home_dir</span><span class='comma'>,</span> <span class='id identifier rubyid_shell'>shell</span> <span class='op'>=</span> <span class='id identifier rubyid_line'>line</span><span class='period'>.</span><span class='id identifier rubyid_split'>split</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>:</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> 179 180 <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>User Detected: </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_user'>user</span><span class='embexpr_end'>}</span><span class='tstring_content'> (id=</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_uid'>uid</span><span class='embexpr_end'>}</span><span class='tstring_content'>)</span><span class='tstring_end'>"</span></span> 181<span class='kw'>end</span> 182</code></pre> 183 184<p>Get information about the current process:</p> 185 186<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_system'>system</span><span class='period'>.</span><span class='id identifier rubyid_process'>process</span><span class='period'>.</span><span class='id identifier rubyid_pid'>pid</span> 187<span class='comment'># => 1234 188</span> 189<span class='id identifier rubyid_system'>system</span><span class='period'>.</span><span class='id identifier rubyid_process'>process</span><span class='period'>.</span><span class='id identifier rubyid_getuid'>getuid</span> 190<span class='comment'># => 1001 191</span> 192<span class='id identifier rubyid_system'>system</span><span class='period'>.</span><span class='id identifier rubyid_process'>process</span><span class='period'>.</span><span class='id identifier rubyid_environ'>environ</span> 193<span class='comment'># => {"HOME"=>"...", "PATH"=>"...", ...} 194</span></code></pre> 195 196<p>Execute commands on the remote system:</p> 197 198<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_system'>system</span><span class='period'>.</span><span class='id identifier rubyid_shell'>shell</span><span class='period'>.</span><span class='id identifier rubyid_ls'>ls</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>/</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> 199<span class='comment'># => "bin\nboot\ndev\netc\nhome\nlib\nlib64\nlost+found\nmedia\nmnt\nopt\nproc\nroot\nrun\nsbin\nsnap\nsrv\nsys\ntmp\nusr\nvar\n" 200</span> 201<span class='id identifier rubyid_system'>system</span><span class='period'>.</span><span class='id identifier rubyid_shell'>shell</span><span class='period'>.</span><span class='id identifier rubyid_exec'>exec</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>find -type f -name '*.xls' /srv</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_path'>path</span><span class='op'>|</span> 202 <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Found XLS file: </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_path'>path</span><span class='embexpr_end'>}</span><span class='tstring_end'>"</span></span> 203<span class='kw'>end</span> 204</code></pre> 205 206<p>Spawn an interactive command shell:</p> 207 208<pre class="code ruby"><code class="ruby">system.shell.interact 209$ 210</code></pre> 211 212<p>Spawn an interactive post-exploitation system shell:</p> 213 214<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_system'>system</span><span class='period'>.</span><span class='id identifier rubyid_interact'>interact</span> 215</code></pre> 216 217<pre class="code ruby"><code class="ruby">ronin-post_ex> help 218 help [COMMAND] Prints the list of commands or additional help 219 fs.chdir DIR Changes the current working directory 220 fs.pwd Prints the current working directory 221 fs.readfile FILE Reads the contents of a given FILE 222 fs.readlink SYMLINK Reads the destination path of a symlink 223 fs.readdir DIR Reads the contents of a given directory 224 fs.hexdump FILE Hexdumps a given file 225 fs.copy SRC DEST Copies the SRC file to the DEST path 226 fs.unlink FILE Deletes a given file 227 fs.rmdir DIR Removes a given directory 228 fs.mv SRC DEST Moves or renames a given file or directory 229 fs.link SRC DEST Creates a link from the source to the destination 230 fs.chown USER PATH Changes the owner of a given file or directory 231 fs.chgrp GROUP PATH Changes the group of a given file or directory 232 fs.chmod MODE PATH Changes the permission mode of a given file or directory 233 fs.stat PATH Prints file system information about a given file or directory 234 fs.open PATH [MODE] Opens a file for reading or writing 235 files Lists opened files
236 file.seek FILE_ID POS [WHENCE] Seeks to a position within the file 237 file.read FILE_ID LENGTH Reads LENGTH of data from an opened file 238 file.write FILE_ID DATA Writes data to an opened file 239 file.close FILE_ID Closes an open file 240ronin-post_ex> 241</code></pre> 242 243<h2 id="requirements">Requirements</h2> 244 245<ul> 246<li><a href="https://www.ruby-lang.org">Ruby</a> >= 3.0.0</li> 247<li><a href="https://github.com/postmodern/fake_io.rb#readme">fake_io</a> ~> 0.1</li> 248<li><a href="https://github.com/postmodern/hexdump.rb#readme">hexdump</a> ~> 1.0</li> 249<li><a href="https://github.com/ronin-rb/ronin-core#readme">ronin-core</a> ~> 0.1</li> 250</ul> 251 252<h2 id="install">Install</h2> 253 254<pre class="code shell"><code class="shell">$ gem install ronin-post_ex 255</code></pre> 256 257<h3 id="gemfile">Gemfile</h3> 258 259<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>ronin-post_ex</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>~> 0.1</span><span class='tstring_end'>'</span></span> 260</code></pre> 261 262<h3 id="gemspec">gemspec</h3> 263 264<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span><span class='period'>.</span><span class='id identifier rubyid_add_dependency'>add_dependency</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>ronin-post_ex</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>~> 0.1</span><span class='tstring_end'>'</span></span> 265</code></pre> 266 267<h2 id="development">Development</h2> 268 269<ol> 270<li><a href="https://github.com/ronin-rb/ronin-post_ex/fork">Fork It!</a></li> 271<li>Clone It!</li> 272<li><code>cd ronin-post_ex/</code></li> 273<li><code>bundle install</code></li> 274<li><code>git checkout -b my_feature</code></li> 275<li>Code It!</li> 276<li><code>bundle exec rake spec</code></li> 277<li><code>git push origin my_feature</code></li> 278</ol> 279 280<h2 id="license">License</h2> 281 282<p>Copyright (c) 2007-2023 Hal Brodigan (postmodern.mod3 at gmail.com)</p> 283 284<p>ronin-post_ex is free software: you can redistribute it and/or modify 285it under the terms of the GNU Lesser General Public License as published 286by the Free Software Foundation, either version 3 of the License, or 287(at your option) any later version.</p> 288 289<p>ronin-post_ex is distributed in the hope that it will be useful, 290but WITHOUT ANY WARRANTY; without even the implied warranty of 291MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 292GNU Lesser General Public License for more details.</p> 293 294<p>You should have received a copy of the GNU Lesser General Public License 295along with ronin-post_ex. If not, see <a href="https://www.gnu.org/licenses/">https://www.gnu.org/licenses/</a>.</p> 296</div></div> 297 298 <div id="footer"> 299 Generated on Wed Feb 1 13:45:20 2023 by 300 <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a> 301 0.9.28 (ruby-3.1.3). 302</div> 303 304 </div> 305 </body> 306</html>
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.