Skip to content

Commit 09335fd

Browse files
msm-codemsm-code
committed
Deployed 0e09a08 with MkDocs version: 1.6.1
1 parent 3579167 commit 09335fd

File tree

9 files changed

+5503
-3861
lines changed

9 files changed

+5503
-3861
lines changed

‎404.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,15 +34,15 @@
3434

3535
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
3636
<ul>
37-
<li class="toctree-l1"><a class="reference internal" href="/.">Index</a>
37+
<li class="toctree-l1"><a class="reference internal" href="/.">Ghidralib</a>
3838
</li>
3939
</ul>
4040
<ul>
41-
<li class="toctree-l1"><a class="reference internal" href="/everything/">Ghidralib</a>
41+
<li class="toctree-l1"><a class="reference internal" href="/getting_started/">Getting Started</a>
4242
</li>
4343
</ul>
4444
<ul>
45-
<li class="toctree-l1"><a class="reference internal" href="/program_model/">Program Model</a>
45+
<li class="toctree-l1"><a class="reference internal" href="/reference/">API reference</a>
4646
</li>
4747
</ul>
4848
</div>

‎dragon1.png‎

29.6 KB
Loading

‎getting_started/index.html‎

Lines changed: 326 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,326 @@
1+
<!DOCTYPE html>
2+
<html class="writer-html5" lang="en" >
3+
<head>
4+
<meta charset="utf-8" />
5+
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
7+
<link rel="shortcut icon" href="../img/favicon.ico" />
8+
<title>Getting Started - My Project Documentation</title>
9+
<link rel="stylesheet" href="../css/theme.css" />
10+
<link rel="stylesheet" href="../css/theme_extra.css" />
11+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css" />
12+
<link href="../assets/_mkdocstrings.css" rel="stylesheet" />
13+
14+
<script>
15+
// Current page data
16+
var mkdocs_page_name = "Getting Started";
17+
var mkdocs_page_input_path = "getting_started.md";
18+
var mkdocs_page_url = null;
19+
</script>
20+
21+
<!--[if lt IE 9]>
22+
<script src="../js/html5shiv.min.js"></script>
23+
<![endif]-->
24+
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js"></script>
25+
<script>hljs.highlightAll();</script>
26+
</head>
27+
28+
<body class="wy-body-for-nav" role="document">
29+
30+
<div class="wy-grid-for-nav">
31+
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
32+
<div class="wy-side-scroll">
33+
<div class="wy-side-nav-search">
34+
<a href=".." class="icon icon-home"> My Project Documentation
35+
</a><div role="search">
36+
<form id ="rtd-search-form" class="wy-form" action="../search.html" method="get">
37+
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" title="Type search term here" />
38+
</form>
39+
</div>
40+
</div>
41+
42+
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
43+
<ul>
44+
<li class="toctree-l1"><a class="reference internal" href="..">Ghidralib</a>
45+
</li>
46+
</ul>
47+
<ul class="current">
48+
<li class="toctree-l1 current"><a class="reference internal current" href="#">Getting Started</a>
49+
<ul class="current">
50+
<li class="toctree-l2"><a class="reference internal" href="#installation">Installation</a>
51+
</li>
52+
<li class="toctree-l2"><a class="reference internal" href="#main-actors">Main actors</a>
53+
<ul>
54+
<li class="toctree-l3"><a class="reference internal" href="#function">Function</a>
55+
</li>
56+
<li class="toctree-l3"><a class="reference internal" href="#instruction">Instruction</a>
57+
</li>
58+
<li class="toctree-l3"><a class="reference internal" href="#basicblock">BasicBlock</a>
59+
</li>
60+
<li class="toctree-l3"><a class="reference internal" href="#datatype">DataType</a>
61+
</li>
62+
<li class="toctree-l3"><a class="reference internal" href="#symbol">Symbol</a>
63+
</li>
64+
</ul>
65+
</li>
66+
<li class="toctree-l2"><a class="reference internal" href="#working-at-various-abstraction-levels">Working at various abstraction levels</a>
67+
</li>
68+
<li class="toctree-l2"><a class="reference internal" href="#conventions">Conventions</a>
69+
</li>
70+
</ul>
71+
</li>
72+
</ul>
73+
<ul>
74+
<li class="toctree-l1"><a class="reference internal" href="../reference/">API reference</a>
75+
</li>
76+
</ul>
77+
</div>
78+
</div>
79+
</nav>
80+
81+
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
82+
<nav class="wy-nav-top" role="navigation" aria-label="Mobile navigation menu">
83+
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
84+
<a href="..">My Project Documentation</a>
85+
86+
</nav>
87+
<div class="wy-nav-content">
88+
<div class="rst-content"><div role="navigation" aria-label="breadcrumbs navigation">
89+
<ul class="wy-breadcrumbs">
90+
<li><a href=".." class="icon icon-home" aria-label="Docs"></a></li>
91+
<li class="breadcrumb-item active">Getting Started</li>
92+
<li class="wy-breadcrumbs-aside">
93+
</li>
94+
</ul>
95+
<hr/>
96+
</div>
97+
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
98+
<div class="section" itemprop="articleBody">
99+
100+
<h1 id="getting-started">Getting Started</h1>
101+
<p>This document contains an introduction to the most important objects
102+
wrapped by this library, and a few more motivational segments.</p>
103+
<ul>
104+
<li><a href="#main-actors">Main Actors</a> - description of the most important
105+
ghidralib objects</li>
106+
<li><a href="#working-at-various-abstraction-levels">Working at various abstraction levels</a>
107+
description of the various abstraction levels wrapped (and made easy!)
108+
by ghidralib.</li>
109+
<li><a href="#conventions">Conventions</a> this library follows some design rules.
110+
They are hopefully intuitive, but understanding them may make your
111+
first steps easier.</li>
112+
</ul>
113+
<h2 id="installation">Installation</h2>
114+
<p>To use ghidralib, <strong>just drop <a href="https://github.com/msm-code/ghidralib/blob/master/ghidralib.py">this file</a> into your ghidra_scripts directory</strong>.
115+
Click <a href="https://raw.githubusercontent.com/msm-code/ghidralib/refs/heads/master/ghidralib.py">here</a>
116+
for a direct download link.</p>
117+
<h2 id="main-actors">Main actors</h2>
118+
<h3 id="function">Function</h3>
119+
<p>Check these usage examples:</p>
120+
<pre><code class="language-python">from ghidralib import *
121+
# Get a function at address 0x8ca3f0
122+
Function(0x8ca3f0)
123+
124+
# Get a function named &quot;main&quot;
125+
Function(&quot;main&quot;)
126+
127+
# Print all assembly instructions in main function
128+
for instr in Function(&quot;main&quot;).instructions:
129+
print(instr)
130+
131+
# Print all pcode instructions in main function
132+
for instr in Function(&quot;main&quot;).pcode:
133+
print(instr)
134+
135+
# Print all high-level pcode instructions in main function
136+
# Or you can do it in 100 lines of Java:
137+
# https://github.com/evm-sec/high-pcode/blob/main/HighPCode.java
138+
for instr in Function(&quot;main&quot;).high_pcode:
139+
print(instr)
140+
141+
# Print all basic blocks in main function
142+
for block in Function(&quot;main&quot;).basicblocks:
143+
print(block)
144+
145+
# Decompile the main function and print the C code.
146+
print(Function(&quot;main&quot;).decompile())
147+
148+
# Define a function at address 0x400300
149+
Function.create(0x400300, &quot;main&quot;)
150+
151+
# Print a value of eax and edx at each call of this function
152+
for call in Function(&quot;MyCustomCrypto&quot;).calls:
153+
ctx = call.emulate()
154+
key, data = ctx.read_register(&quot;eax&quot;), ctx.read_register(&quot;edx&quot;)
155+
print(key, data)
156+
157+
# Print parameters of each call to this function, as seen by
158+
# the decompiler
159+
for call in Function(&quot;MyCustomCrypto&quot;).calls:
160+
key, data = call.get_args()
161+
print(key, data)
162+
</code></pre>
163+
<p>Read more in the <a href="../reference/#ghidralib.Function"><code>Function</code> object documentation</a>.</p>
164+
<h3 id="instruction">Instruction</h3>
165+
<p>Check these usage examples:</p>
166+
<pre><code class="language-python"># Get an instruction at address 0x8ca3f0
167+
Instruction(0x8ca3f0)
168+
169+
# Get the first instruction in main function
170+
Instruction(&quot;main&quot;)
171+
172+
# Print the instruction mnemonic and operands
173+
instr = Instruction(0x8ca3f0)
174+
print(instr.mnemonic, instr.operands)
175+
176+
# Print the instruction pcode:
177+
for op in instr.pcode:
178+
print(op)
179+
180+
# Print the instruction high-level pcode:
181+
for op in instr.high_pcode:
182+
print(op)
183+
</code></pre>
184+
<p>Read more in the <a href="../reference/#ghidralib.Instruction"><code>Instruction</code> object documentation</a>.</p>
185+
<h3 id="basicblock">BasicBlock</h3>
186+
<p>Check these usage examples:</p>
187+
<pre><code class="language-python"># TODO: DFS example
188+
</code></pre>
189+
<p>Read more in the <a href="../reference/#ghidralib.BasicBlock"><code>BasicBlock</code> object documentation</a>.</p>
190+
<h3 id="datatype">DataType</h3>
191+
<p>Check these usage examples:</p>
192+
<pre><code class="language-python"># Get a datatype called &quot;int&quot;
193+
DataType(&quot;int&quot;)
194+
195+
# Parse a datatype from C string
196+
HINTERNET = DataType.from_c('typedef void* HINTERNET;')
197+
198+
# Change a datatype at location
199+
create_data(0x1234, HINTERNET)
200+
</code></pre>
201+
<p>Read more in the <a href="../reference/#ghidralib.DataType"><code>DataType</code> object documentation</a>.</p>
202+
<h3 id="symbol">Symbol</h3>
203+
<p>Sometimes called a label. Check these usage examples:</p>
204+
<pre><code class="language-python"># Get a symbol (label) at address 0x8ca3f0
205+
Symbol(0x8ca3f0)
206+
207+
# Get a symbol (label) named &quot;main&quot;
208+
Symbol(&quot;main&quot;)
209+
210+
# Create a label &quot;foo&quot; at address 0x1234
211+
Symbol.create(0x1234, &quot;foo&quot;)
212+
213+
# Change the symbol's data type
214+
Symbol(&quot;DAT_1234&quot;).set_type(HINTERNET)
215+
216+
# Print all symbols in the program
217+
for symbol in Symbol.all():
218+
print(symbol)
219+
220+
# Rename all unknown data to something funniner
221+
for symbol in Symbol.all():
222+
if symbol.name.startswith(&quot;DAT_&quot;):
223+
symbol.rename(f&quot;funniner_{symbol.name}&quot;)
224+
</code></pre>
225+
<p>Read more in the <a href="../reference/#ghidralib.Symbol"><code>Symbol</code> object documentation</a>.</p>
226+
<h2 id="working-at-various-abstraction-levels">Working at various abstraction levels</h2>
227+
<p>TODO</p>
228+
<ul>
229+
<li><strong>Assembly instructions</strong></li>
230+
<li><strong>Pcode instructions</strong></li>
231+
<li><strong>High Pcode instructions</strong></li>
232+
<li><strong>Pcode AST graph</strong></li>
233+
<li><strong>Clang tokens</strong></li>
234+
</ul>
235+
<h2 id="conventions">Conventions</h2>
236+
<p>There are a few conventions that this library follows, and which may be useful
237+
when learning:</p>
238+
<ul>
239+
<li>Every object that wraps a Ghidra object has a <code>.raw</code> property that can be used
240+
to get the unwrapped object. So you can always "escape" ghidralib:</li>
241+
</ul>
242+
<pre><code class="language-python">Function(&quot;main&quot;).raw.UNKNOWN_STACK_DEPTH_CHANGE
243+
2147483647
244+
</code></pre>
245+
<ul>
246+
<li>Objects that have an address can be addressed in many different ways - by name,
247+
by address, or by Ghidra address object. All of these are equivalent:</li>
248+
</ul>
249+
<pre><code class="language-python">Function(&quot;main&quot;)
250+
Function(0x669d1e)
251+
Function(toAddr(0x669d1e))
252+
</code></pre>
253+
<ul>
254+
<li>Additionaly, wrappers are "tolerant" and try to drop unnecessary layers.
255+
All of these are resolved to the same object:</li>
256+
</ul>
257+
<pre><code class="language-python">Instruction(getInstructionAt(toAddr(0x0669d2a))) # from raw object
258+
Instruction(0x669d2a) # from integer
259+
Instruction(Instruction(0x669d2a)) # wrapped two times
260+
</code></pre>
261+
<ul>
262+
<li>Same goes in the other direction btw - Java API will accept wrappers</li>
263+
</ul>
264+
<pre><code class="language-python">getInstructionBefore(getInstructionAt(toAddr(0x0669d2a))) # pure java
265+
getInstructionBefore(Instruction(0x0669d2a)) # mixup library object
266+
</code></pre>
267+
<ul>
268+
<li>
269+
<p>Many objects expose a static constructor methods, where it makes sense.
270+
Possible methods are "get", "create", "all", "create". So for example
271+
instead of <code>getAllSymbols()</code> use <code>Symbols.all()</code>.</p>
272+
</li>
273+
<li>
274+
<p>The difference between <code>Function.get(addr)</code> and <code>Function(addr)</code> is that
275+
<code>Function.get</code> returns <code>None</code> instead of raising an exception when
276+
the desired object was not found.</p>
277+
</li>
278+
</ul>
279+
280+
</div>
281+
</div><footer>
282+
<div class="rst-footer-buttons" role="navigation" aria-label="Footer Navigation">
283+
<a href=".." class="btn btn-neutral float-left" title="Ghidralib"><span class="icon icon-circle-arrow-left"></span> Previous</a>
284+
<a href="../reference/" class="btn btn-neutral float-right" title="API reference">Next <span class="icon icon-circle-arrow-right"></span></a>
285+
</div>
286+
287+
<hr/>
288+
289+
<div role="contentinfo">
290+
<!-- Copyright etc -->
291+
</div>
292+
293+
Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
294+
</footer>
295+
296+
</div>
297+
</div>
298+
299+
</section>
300+
301+
</div>
302+
303+
<div class="rst-versions" role="note" aria-label="Versions">
304+
<span class="rst-current-version" data-toggle="rst-current-version">
305+
306+
307+
<span><a href=".." style="color: #fcfcfc">&laquo; Previous</a></span>
308+
309+
310+
<span><a href="../reference/" style="color: #fcfcfc">Next &raquo;</a></span>
311+
312+
</span>
313+
</div>
314+
<script src="../js/jquery-3.6.0.min.js"></script>
315+
<script>var base_url = "..";</script>
316+
<script src="../js/theme_extra.js"></script>
317+
<script src="../js/theme.js"></script>
318+
<script src="../search/main.js"></script>
319+
<script>
320+
jQuery(function () {
321+
SphinxRtdTheme.Navigation.enable(true);
322+
});
323+
</script>
324+
325+
</body>
326+
</html>

0 commit comments

Comments
 (0)