99 lines
5.5 KiB
Plaintext
99 lines
5.5 KiB
Plaintext
Python bindings
|
|
===============
|
|
:title: Shellcode Compiler Runtime
|
|
|
|
The Shellcode Compiler has a simple interface for compiling code from Python. Once installed, the `scc` module
|
|
contains the function `compile_source`, which will invoke the compiler and return the results. The following
|
|
is the definition of this function:
|
|
|
|
---------------------------------------
|
|
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)
|
|
---------------------------------------
|
|
|
|
This function will return a tuple of two elements. The first element is the compiled code, or `None` on compilation
|
|
failure. The second element contains the output from the compiler, and will include the error messages when the
|
|
compilation fails.
|
|
|
|
IMPORTANT: Some of these options are not yet implemented. See the link:issues.html[known issues] for a list
|
|
of incomplete features.
|
|
|
|
WARNING: This API is not protected against command injection from the various options. Do not pass untrusted input as
|
|
options to this function.
|
|
|
|
The `source` 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.
|
|
|
|
The `platform` parameter contains the OS to compile for. This can be one of `linux`, `freebsd`, `mac`, `windows`, or `none`.
|
|
|
|
The `arch` parameter contains the architecture to compile for. This can be one of `x86` or `x64`.
|
|
|
|
The `blacklist` parameter specifies the byte values that must not occur in the output. This should be a list of integers.
|
|
|
|
If the `allow_return` parameter is `True`, the outputted code will issue a return instruction on completion instead of
|
|
exiting the process.
|
|
|
|
If the `unsafe_stack` parameter is `True`, 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.
|
|
|
|
The `base` 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.
|
|
|
|
If the `concat` parameter is `True`, 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.
|
|
|
|
If the `encode_pointers` parameter is `True`, 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.
|
|
|
|
If the `frame_reg` parameter is specified, the register that is used to hold the base of the stack frame is forced to the
|
|
specified register.
|
|
|
|
If the `max_length` 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.
|
|
|
|
The `optimization` parameter can be one of `scc.NormalOptimization`, `scc.Unoptimized`, or `scc.SizeOptimization`.
|
|
|
|
If the `pad` parameter is `True`, the output will be padded to exactly the length specified by the `max_length` parameter.
|
|
The padding is randomly chosen and will never include bytes in the `blacklist` list.
|
|
|
|
If the `polymorph` parameter is `True`, the output will be randomly shuffled to produce different code on each run. The
|
|
`seed` parameter can be specified to force a specific result from the randomization.
|
|
|
|
The `preserve_regs` parameter contains registers that should be preserved across execution of the code. This should be
|
|
a list of register names.
|
|
|
|
If the `return_reg` parameter is specified, the register that is used to hold the return value is forced to the specified
|
|
register.
|
|
|
|
If the `return_high_reg` parameter is specified, the register that is used to hold the high half of a large return value
|
|
is forced to the specified register.
|
|
|
|
If the `seed` parameter is specified, the compiler will use the provided random seed for generating padding and
|
|
polymorphic code.
|
|
|
|
If the `stack_grows_up` parameter is `True`, the compiler will cause the stack to grow toward larger addresses.
|
|
|
|
If the `stack_reg` 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.
|
|
|
|
The `include_dirs` specifies additional include directories, and should be a list of strings.
|
|
|
|
The `align` parameter, if specified, provides the minimum alignment of the output in bytes.
|
|
|
|
If the `anti_disasm` parameter is `True`, the compiler will emit anti-disassembly sequences in the output. The frequency
|
|
of the anti-disassembly sequences can be specified with the `anti_disasm_freq` parameter, which specifies the average
|
|
number of operations between sequences.
|
|
|
|
The `markov_chain` parameter, if specified, gives the filename of a binary that will be used as a source of instructions
|
|
for random instruction generation.
|
|
|
|
The `defines` parameter, if specified, gives a map of preprocessor macro names to values. Use the empty string or `None`
|
|
if the macro should not have a value.
|
|
|
|
The `additional_options` parameter can hold a list of additional link:scc.html[command line arguments].
|
|
|