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.
|
Some of these options are not yet implemented. See the known issues for a list of incomplete features. |
|
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 command line arguments.