PageSourceSearch

https://ronin-rb.dev/docs/ronin-post_ex/

html ronin-rb.dev collected 2026-09-25 19:12:03 UTC 22,756 bytes, 306 lines download raw bytes

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    &mdash; 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> &raquo; 
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'>&#39;</span><span class='tstring_content'>/</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
128<span class='comment'># =&gt; &quot;...&quot;
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'>&#39;</span><span class='tstring_content'>/</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
137<span class='comment'># =&gt; &quot;...&quot;
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'>&lt;</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'>&quot;</span><span class='tstring_content'>fs_read</span><span class='tstring_end'>&quot;</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'>&quot;</span><span class='tstring_content'>shell_exec</span><span class='tstring_end'>&quot;</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&#39;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'>&#39;</span><span class='tstring_content'>/etc/passwd</span><span class='tstring_end'>&#39;</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'>&#39;</span><span class='tstring_content'>:</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
179
180  <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&quot;</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'>&quot;</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'># =&gt; 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'># =&gt; 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'># =&gt; {&quot;HOME&quot;=&gt;&quot;...&quot;, &quot;PATH&quot;=&gt;&quot;...&quot;, ...}
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'>&#39;</span><span class='tstring_content'>/</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
199<span class='comment'># =&gt; &quot;bin\nboot\ndev\netc\nhome\nlib\nlib64\nlost+found\nmedia\nmnt\nopt\nproc\nroot\nrun\nsbin\nsnap\nsrv\nsys\ntmp\nusr\nvar\n&quot;
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'>&quot;</span><span class='tstring_content'>find -type f -name &#39;*.xls&#39; /srv</span><span class='tstring_end'>&quot;</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'>&quot;</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'>&quot;</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&gt; 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&gt; 
241</code></pre>
242
243<h2 id="requirements">Requirements</h2>
244
245<ul>
246<li><a href="https://www.ruby-lang.org">Ruby</a> &gt;= 3.0.0</li>
247<li><a href="https://github.com/postmodern/fake_io.rb#readme">fake_io</a> ~&gt; 0.1</li>
248<li><a href="https://github.com/postmodern/hexdump.rb#readme">hexdump</a> ~&gt; 1.0</li>
249<li><a href="https://github.com/ronin-rb/ronin-core#readme">ronin-core</a> ~&gt; 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'>&#39;</span><span class='tstring_content'>ronin-post_ex</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>~&gt; 0.1</span><span class='tstring_end'>&#39;</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'>&#39;</span><span class='tstring_content'>ronin-post_ex</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>~&gt; 0.1</span><span class='tstring_end'>&#39;</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.