126 lines
9.8 KiB
HTML
126 lines
9.8 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
|
|
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
|
<meta name="generator" content="AsciiDoc 8.6.9" />
|
|
<title>Shellcode Compiler Runtime</title>
|
|
<link rel="stylesheet" href="lib/v35.css" type="text/css" />
|
|
<link rel="stylesheet" href="lib/layout2v35.css" type="text/css" />
|
|
<script type="text/javascript" src="lib/asciidoc.js"></script>
|
|
<script type="text/javascript">
|
|
/*<![CDATA[*/
|
|
asciidoc.install();
|
|
/*]]>*/
|
|
</script>
|
|
</head>
|
|
<body>
|
|
<div id="layout-menu-box">
|
|
<div id="layout-menu">
|
|
<div>»<a href="index.html">Home</a></div>
|
|
<div>»<a href="examples.html">Examples</a></div>
|
|
<div>»<a href="scc.html">Invocation</a></div>
|
|
<div>»<a href="runtime.html">Runtime Library</a></div>
|
|
<div>»<a href="python.html">Python Bindings</a></div>
|
|
<div>»<a href="issues.html">Known Issues</a></div>
|
|
</div>
|
|
</div>
|
|
<div id="layout-content-box">
|
|
<div id="layout-banner">
|
|
<div id="layout-title">Shellcode Compiler</div>
|
|
<div id="layout-description">A custom shellcode compiler for Binary Ninja</div>
|
|
</div>
|
|
<div id="layout-content">
|
|
<div id="header">
|
|
<h1>Python bindings</h1>
|
|
</div>
|
|
<div id="content">
|
|
<div id="preamble">
|
|
<div class="sectionbody">
|
|
<div class="paragraph"><p>The Shellcode Compiler has a simple interface for compiling code from Python. Once installed, the <span class="monospaced">scc</span> module
|
|
contains the function <span class="monospaced">compile_source</span>, which will invoke the compiler and return the results. The following
|
|
is the definition of this function:</p></div>
|
|
<div class="listingblock">
|
|
<div class="content monospaced">
|
|
<pre>def compile_source(source, platform="linux", arch="x86", blacklist=None, allow_return=False, unsafe_stack=False,
|
|
base=None, concat=False, encode_pointers=False, frame_reg=None, max_length=None,
|
|
optimization=NormalOptimization, pad=False, polymorph=False, preserve_regs=None, return_reg=None,
|
|
return_high_reg=None, seed=None, stack_grows_up=False, stack_reg=None, include_dirs=None, align=None,
|
|
anti_disasm=False, anti_disasm_freq=None, markov_chain=None, defines=None, additional_options=None)</pre>
|
|
</div></div>
|
|
<div class="paragraph"><p>This function will return a tuple of two elements. The first element is the compiled code, or <span class="monospaced">None</span> on compilation
|
|
failure. The second element contains the output from the compiler, and will include the error messages when the
|
|
compilation fails.</p></div>
|
|
<div class="admonitionblock">
|
|
<table><tr>
|
|
<td class="icon">
|
|
<img src="./images/icons/important.png" alt="Important">
|
|
</td>
|
|
<td class="content">Some of these options are not yet implemented. See the <a href="issues.html">known issues</a> for a list
|
|
of incomplete features.</td>
|
|
</tr></table>
|
|
</div>
|
|
<div class="admonitionblock">
|
|
<table><tr>
|
|
<td class="icon">
|
|
<img src="./images/icons/warning.png" alt="Warning">
|
|
</td>
|
|
<td class="content">This API is not protected against command injection from the various options. Do not pass untrusted input as
|
|
options to this function.</td>
|
|
</tr></table>
|
|
</div>
|
|
<div class="paragraph"><p>The <span class="monospaced">source</span> parameter contains the source code to compile. This code does not need to be present in a file on
|
|
the file system, and can be dynamically constructed.</p></div>
|
|
<div class="paragraph"><p>The <span class="monospaced">platform</span> parameter contains the OS to compile for. This can be one of <span class="monospaced">linux</span>, <span class="monospaced">freebsd</span>, <span class="monospaced">mac</span>, <span class="monospaced">windows</span>, or <span class="monospaced">none</span>.</p></div>
|
|
<div class="paragraph"><p>The <span class="monospaced">arch</span> parameter contains the architecture to compile for. This can be one of <span class="monospaced">x86</span> or <span class="monospaced">x64</span>.</p></div>
|
|
<div class="paragraph"><p>The <span class="monospaced">blacklist</span> parameter specifies the byte values that must not occur in the output. This should be a list of integers.</p></div>
|
|
<div class="paragraph"><p>If the <span class="monospaced">allow_return</span> parameter is <span class="monospaced">True</span>, the outputted code will issue a return instruction on completion instead of
|
|
exiting the process.</p></div>
|
|
<div class="paragraph"><p>If the <span class="monospaced">unsafe_stack</span> parameter is <span class="monospaced">True</span>, the compiler will not assume that the stack is safe for use (for example, use
|
|
of the stack may corrupt the code that is executing). When this is enabled, the compiler will adjust the stack pointer
|
|
to ensure that it is in a safe location.</p></div>
|
|
<div class="paragraph"><p>The <span class="monospaced">base</span> parameter specifies the base address of the start of the output. This can be a computed expression in terms
|
|
of register contents at the start of the program.</p></div>
|
|
<div class="paragraph"><p>If the <span class="monospaced">concat</span> parameter is <span class="monospaced">True</span>, the compiler will jump to the end of the output on completion instead of exiting the
|
|
process. This allows multiple pieces of code to be appended together to form a larger program.</p></div>
|
|
<div class="paragraph"><p>If the <span class="monospaced">encode_pointers</span> parameter is <span class="monospaced">True</span>, the compiler will encode all pointers to code using a key that is unique
|
|
to each execution of the program. Using this option will significantly increase code size.</p></div>
|
|
<div class="paragraph"><p>If the <span class="monospaced">frame_reg</span> parameter is specified, the register that is used to hold the base of the stack frame is forced to the
|
|
specified register.</p></div>
|
|
<div class="paragraph"><p>If the <span class="monospaced">max_length</span> parameter is specified, the compiler will ensure that the output does not exceed the given number of
|
|
bytes. If the compiler cannot satisfy the constraints, an error is generated.</p></div>
|
|
<div class="paragraph"><p>The <span class="monospaced">optimization</span> parameter can be one of <span class="monospaced">scc.NormalOptimization</span>, <span class="monospaced">scc.Unoptimized</span>, or <span class="monospaced">scc.SizeOptimization</span>.</p></div>
|
|
<div class="paragraph"><p>If the <span class="monospaced">pad</span> parameter is <span class="monospaced">True</span>, the output will be padded to exactly the length specified by the <span class="monospaced">max_length</span> parameter.
|
|
The padding is randomly chosen and will never include bytes in the <span class="monospaced">blacklist</span> list.</p></div>
|
|
<div class="paragraph"><p>If the <span class="monospaced">polymorph</span> parameter is <span class="monospaced">True</span>, the output will be randomly shuffled to produce different code on each run. The
|
|
<span class="monospaced">seed</span> parameter can be specified to force a specific result from the randomization.</p></div>
|
|
<div class="paragraph"><p>The <span class="monospaced">preserve_regs</span> parameter contains registers that should be preserved across execution of the code. This should be
|
|
a list of register names.</p></div>
|
|
<div class="paragraph"><p>If the <span class="monospaced">return_reg</span> parameter is specified, the register that is used to hold the return value is forced to the specified
|
|
register.</p></div>
|
|
<div class="paragraph"><p>If the <span class="monospaced">return_high_reg</span> parameter is specified, the register that is used to hold the high half of a large return value
|
|
is forced to the specified register.</p></div>
|
|
<div class="paragraph"><p>If the <span class="monospaced">seed</span> parameter is specified, the compiler will use the provided random seed for generating padding and
|
|
polymorphic code.</p></div>
|
|
<div class="paragraph"><p>If the <span class="monospaced">stack_grows_up</span> parameter is <span class="monospaced">True</span>, the compiler will cause the stack to grow toward larger addresses.</p></div>
|
|
<div class="paragraph"><p>If the <span class="monospaced">stack_reg</span> parameter is specified, the register that is used to hold the stack pointer is forced to the specified
|
|
register. Using this option will significantly increase code size.</p></div>
|
|
<div class="paragraph"><p>The <span class="monospaced">include_dirs</span> specifies additional include directories, and should be a list of strings.</p></div>
|
|
<div class="paragraph"><p>The <span class="monospaced">align</span> parameter, if specified, provides the minimum alignment of the output in bytes.</p></div>
|
|
<div class="paragraph"><p>If the <span class="monospaced">anti_disasm</span> parameter is <span class="monospaced">True</span>, the compiler will emit anti-disassembly sequences in the output. The frequency
|
|
of the anti-disassembly sequences can be specified with the <span class="monospaced">anti_disasm_freq</span> parameter, which specifies the average
|
|
number of operations between sequences.</p></div>
|
|
<div class="paragraph"><p>The <span class="monospaced">markov_chain</span> parameter, if specified, gives the filename of a binary that will be used as a source of instructions
|
|
for random instruction generation.</p></div>
|
|
<div class="paragraph"><p>The <span class="monospaced">defines</span> parameter, if specified, gives a map of preprocessor macro names to values. Use the empty string or <span class="monospaced">None</span>
|
|
if the macro should not have a value.</p></div>
|
|
<div class="paragraph"><p>The <span class="monospaced">additional_options</span> parameter can hold a list of additional <a href="scc.html">command line arguments</a>.</p></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="footnotes"><hr /></div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|