Reference
Python API
The programmatic API — PayloadFactory and ExecutableFactory.
Python API
The public entry point is PayloadFactory (payloadfactory/factory/payload_factory.py). It orchestrates shellcode loading and delegates to ExecutableFactory (payloadfactory/factory/executable_factory.py) for embedding, evasion, syscall generation, and compilation.
PayloadFactory
from payloadfactory.factory.payload_factory import PayloadFactory
Constructor
PayloadFactory(arch: str, os_: str = "windows")
| Argument | Values | Notes |
|---|---|---|
arch | "x86", "x64" | Anything else raises NotImplementedError. |
os_ | "windows", "linux" | Must be in PayloadConstants.SUPPORTED_OS. |
Methods
| Method | Signature | Purpose |
|---|---|---|
convert_exe | (name, args=None, compress=True) → bytearray | Convert a Windows PE to shellcode via donut. |
get_shellcode | (shellfile) → bytearray | Extract shellcode from an object file with objdump. |
load_shellcode_file | (name) → bytearray | Load raw (.bin/.hex/.raw) or object-file shellcode. |
load_shellcode_str | (shellcode) → bytearray | Load shellcode from a string. |
string_to_bytearray | (buf) → bytearray | UTF-8 encode a string. |
generate | (method="current_thread", params=None) → bool | Validate technique, build stub, compile. |
logger | attribute | The shared LoggerSingleton. |
generate params
generate() accepts a params dict. Recognized keys (mirroring the CLI):
| Key | Type | Default |
|---|---|---|
outfile | str | result.exe |
recovery | str | embedded (CLI default is jumper_randomized) |
randomize | bool | True |
ppid | bool | True |
syscalls | str | stubs |
evasion_hooks | list[str] | [] |
evasion_checks | list[str | dict] | [] |
encoder | str | none (plain) |
dll | bool | False |
dll_proxy | str | None |
key_source / key_value | str | None |
clang | bool | False |
debug | bool | False |
ExecutableFactory
from payloadfactory.factory.executable_factory import ExecutableFactory
ExecutableFactory(arch: str, recovery: str, os_: str = "windows")
Key methods (all return the updated template string or True):
| Method | Signature | Purpose |
|---|---|---|
set_method | (method, params) | Load the injection stub, set process, libs, PPID spoof. |
set_evasion | (name) | Register a hook: etw, amsi, unhook, sleep_obf. |
set_sandbox_check | (name, args=None) | Register a check: cpu, memory, dll, hostname, username, domain, sleep. |
set_env_keying | (source, target_value) | Bind key to hostname/domain/username/mac. |
set_dll | (dll, proxy=None) | Enable DLL output / export proxying. |
generate_syscalls | (method, randomize) | SysPlant generation (Windows) / no-op (Linux). |
finalize_patterns | () | Clear any leftover //#### ... #### markers. |
generate | (shellcode, method, params) | Run the full embedding pipeline. |
compile | (outfile, clang, debug=False) | Write stub and cross-compile. |
ExecutableFactory extends AbstractFactory (payloadfactory/abstracts/abstract_factory.py), which provides generate_key, generate_random_syscall, generate_random_seed, and generate_random_egg.
Minimal programmatic example
from payloadfactory.factory.payload_factory import PayloadFactory
bot = PayloadFactory("x64", os_="windows")
bot.load_shellcode_file("shellcode.bin")
params = {
"outfile": "payload.exe",
"recovery": "jumper_randomized",
"syscalls": "sysplant",
"evasion_hooks": ["etw", "amsi"],
"evasion_checks": ["cpu"],
}
bot.generate("thread_hijack", params)
Note:
paramskey names are exactly as above — the CLI maps argparse dests onto these keys (e.g.--evasion→evasion_hooks,--sandbox→evasion_checks).