Obfuscation¶

Config¶

class omvll.ObfuscationConfig(self: omvll.ObfuscationConfig)¶

Base class that must be subclassed to configure O-MVLL obfuscation passes.

Override the callback methods below to control which passes are applied to each function. The configuration file must expose a top-level omvll_get_config() function that returns an instance of this class. Using functools.lru_cache() is recommended to avoid repeated instantiation:

Note

Most callbacks accept True, False, or None as convenience shorthands in addition to the dedicated option classes. None is handled explicitly because a Python method that reaches the end without a return statement implicitly returns None — so the following pattern works as intended:

def break_control_flow(self, mod, func):
    if func.name == "secret_func":
        return True
    # no return → None → pass disabled for everything else

False and None are therefore equivalent and both disable the pass. The exceptions are basic_block_duplicate() and function_outline(), which require a probability-based option class and raise an error if a boolean is returned.

@lru_cache(maxsize=1)
def omvll_get_config() -> omvll.ObfuscationConfig:
    return MyConfig()

anti_hooking(self: omvll.ObfuscationConfig, module: omvll.Module, function: omvll.Function) → omvll.AntiHookOpt¶

Callback for the anti-hooking pass.

Return value	Interpretation
`True`	`AntiHookOpt`(`True`)
`False`	`AntiHookOpt`(`False`)
`None`	`AntiHookOpt`(`False`)

basic_block_duplicate(self: omvll.ObfuscationConfig, module: omvll.Module, function: omvll.Function) → omvll.BasicBlockDuplicateSkip | omvll.BasicBlockDuplicateWithProbability¶

Callback for the basic block duplicate pass. Randomly selects basic blocks within function to be duplicated.

Return value	Interpretation
`None`	`BasicBlockDuplicateSkip`
`int` (0–100)	`BasicBlockDuplicateWithProbability`(`int`)
`bool`	fatal error

break_control_flow(self: omvll.ObfuscationConfig, module: omvll.Module, function: omvll.Function) → omvll.BreakControlFlowOpt¶

Callback for the break-control-flow pass.

Return value	Interpretation
`True`	`BreakControlFlowOpt`(`True`)
`False`	`BreakControlFlowOpt`(`False`)
`None`	`BreakControlFlowOpt`(`False`)

default_config(self: omvll.ObfuscationConfig, module: omvll.Module, function: omvll.Function, module_excludes: List[str], function_excludes: List[str], function_includes: List[str], probability: int) → bool¶

Built-in probability-based policy helper:

Skips if module matches any pattern in module_excludes.
Skips if function matches any pattern in function_excludes.
Enables unconditionally if function matches any pattern in function_includes.
Otherwise enables with the given probability (0–100).

Typical use as a callback fallback:

def break_control_flow(self, mod, func):
    return omvll.ObfuscationConfig.default_config(
        self, mod, func, [], [], [], 10
    )

Parameters:

module_excludes (list[str]) – Module name substrings to exclude.
function_excludes (list[str]) – Function name substrings to exclude.
function_includes (list[str]) – Function name substrings that force the pass on.
probability (int) – Percentage chance (0–100) to apply the pass.

Return type:

bool

flatten_cfg(self: omvll.ObfuscationConfig, module: omvll.Module, function: omvll.Function) → omvll.ControlFlowFlatteningOpt¶

Callback for the control-flow flattening pass.

Return value	Interpretation
`True`	`ControlFlowFlatteningOpt`(`True`)
`False`	`ControlFlowFlatteningOpt`(`False`)
`None`	`ControlFlowFlatteningOpt`(`False`)

function_outline(self: omvll.ObfuscationConfig, module: omvll.Module, function: omvll.Function) → omvll.FunctionOutlineSkip | omvll.FunctionOutlineWithProbability¶

Callback for the function outline pass. Randomly selects basic blocks within function to be outlined into new standalone functions.

Return value	Interpretation
`None`	`FunctionOutlineSkip`
`int` (0–100)	`FunctionOutlineWithProbability`(`int`)
`bool`	fatal error

indirect_branch(self: omvll.ObfuscationConfig, module: omvll.Module, function: omvll.Function) → Optional[omvll::IndirectBranchConfig]¶

Callback for the indirect branch pass. Replaces ordinary branches with indirect jumps.

Return value	Interpretation
`True`	`IndirectBranchOpt`(`True`)
`False`	`IndirectBranchOpt`(`False`)
`None`	`IndirectBranchOpt`(`False`)

indirect_call(self: omvll.ObfuscationConfig, module: omvll.Module, function: omvll.Function) → Optional[omvll::IndirectCallConfig]¶

Callback for the indirect call pass. Converts direct function calls into indirect ones by splitting the target address into two additive shares.

Return value	Interpretation
`True`	`IndirectCallOpt`(`True`)
`False`	`IndirectCallOpt`(`False`)
`None`	`IndirectCallOpt`(`False`)

obfuscate_arithmetic(self: omvll.ObfuscationConfig, module: omvll.Module, function: omvll.Function) → omvll.ArithmeticOpt¶

Callback for the arithmetic obfuscation pass.

Return value	Interpretation
`True`	`ArithmeticOpt`(`True`)
`False`	`ArithmeticOpt`(`False`)
`None`	`ArithmeticOpt`(`False`)

obfuscate_constants(self: omvll.ObfuscationConfig, module: omvll.Module, function: omvll.Function) → omvll.OpaqueConstantsSkip | omvll.OpaqueConstantsBool | omvll.OpaqueConstantsLowerLimit | omvll.OpaqueConstantsSet | omvll.OpaqueConstantsExcludeSet¶

Callback for the opaque constants pass.

Return value	Interpretation
`True`	`OpaqueConstantsBool`(`True`)
`False`	`OpaqueConstantsBool`(`False`)
`None`	`OpaqueConstantsBool`(`False`)
`list[int]`	`OpaqueConstantsSet`

obfuscate_string(self: omvll.ObfuscationConfig, module: omvll.Module, function: omvll.Function, string: str) → omvll.StringEncOptSkip | omvll.StringEncOptLocal | omvll.StringEncOptGlobal | omvll.StringEncOptReplace | omvll.StringEncOptDefault¶

Callback invoked for every string literal found in function.

In addition to returning a string encoding option class directly, the following convenience shorthands are accepted:

Return value	Interpretation
`None`	`StringEncOptSkip`
`False`	`StringEncOptSkip`
`True`	`StringEncOptDefault`
`str`	`StringEncOptReplace`
`bytes`	`StringEncOptReplace`

Parameters:

module (Module) – The LLVM module containing the function.
function (Function) – The LLVM function containing the string.
string (bytes) – The raw bytes of the string literal.

obfuscate_struct_access(self: omvll.ObfuscationConfig, module: omvll.Module, function: omvll.Function, struct: omvll.Struct) → omvll.StructAccessOpt¶

Callback for obfuscating structure field accesses.

Return value	Interpretation
`True`	`StructAccessOpt`(`True`)
`False`	`StructAccessOpt`(`False`)
`None`	`StructAccessOpt`(`False`)

Parameters:: struct (Struct) – The LLVM struct type being accessed.

obfuscate_variable_access(self: omvll.ObfuscationConfig, module: omvll.Module, function: omvll.Function, variable: omvll.GlobalVariable) → omvll.VarAccessOpt¶

Callback for obfuscating global variable accesses.

Return value	Interpretation
`True`	`VarAccessOpt`(`True`)
`False`	`VarAccessOpt`(`False`)
`None`	`VarAccessOpt`(`False`)

Parameters:: variable (GlobalVariable) – The global variable being accessed.

report_diff(self: omvll.ObfuscationConfig, pass_name: str, original: str, obfuscated: str) → None¶

Optional callback to monitor IR-level changes produced by individual passes. Override to inspect before/after LLVM IR.

Parameters:

pass_name (str) – Name of the pass that made the change.
original (str) – The original LLVM IR of the function.
obfuscated (str) – The obfuscated LLVM IR of the function.

Template¶

import omvll
from functools import lru_cache

class MyConfig(omvll.ObfuscationConfig):
    def __init__(self):
        super().__init__()

    def obfuscate_string(self, module: omvll.Module, func: omvll.Function,
                         string: bytes):
        if func.demangled_name == "Hello::say_hi()":
            return omvll.StringEncOptDefault()
        if "debug.cpp" in module.name:
            return omvll.StringEncOptReplace("<REMOVED>")
        return omvll.StringEncOptSkip()

    def obfuscate_arithmetic(self, mod: omvll.Module, func: omvll.Function):
        return omvll.ArithmeticOpt(True)

    def flatten_cfg(self, mod: omvll.Module, func: omvll.Function):
        return omvll.ControlFlowFlatteningOpt(True)

    def break_control_flow(self, mod: omvll.Module, func: omvll.Function):
        return omvll.ObfuscationConfig.default_config(
            self, mod, func, [], [], [], 10
        )

    def indirect_call(self, mod: omvll.Module, func: omvll.Function):
        return omvll.IndirectCallOpt(True)

    def function_outline(self, mod: omvll.Module, func: omvll.Function):
        return omvll.FunctionOutlineWithProbability(10)

    def basic_block_duplicate(self, mod: omvll.Module, func: omvll.Function):
        return omvll.BasicBlockDuplicateWithProbability(10)


@lru_cache(maxsize=1)
def omvll_get_config() -> omvll.ObfuscationConfig:
    return MyConfig()

Options¶

Anti-Hooking¶

class omvll.AntiHookOpt(self: omvll.AntiHookOpt, value: bool)¶

Option for the anti_hooking() callback.

Parameters:: value (bool) – True enables the protection, False disables it.

Arithmetic Obfuscation¶

class omvll.ArithmeticOpt(*args, **kwargs)¶

Option for the obfuscate_arithmetic() callback. Defines the number of rounds to apply to arithmetic expressions.

Parameters:: rounds_or_value (int or bool) – Number of rounds (int, 0–255), or a boolean (True uses O-MVLL’s default of 3 rounds, False disables the pass).

Examples:

ArithmeticOpt(3)     # 3 explicit rounds
ArithmeticOpt(True)  # O-MVLL default (3 rounds)
ArithmeticOpt(False) # disabled

Overloaded function.

__init__(self: omvll.ArithmeticOpt, rounds: int) -> None
__init__(self: omvll.ArithmeticOpt, value: bool) -> None

Basic Block Duplicate¶

class omvll.BasicBlockDuplicateSkip(self: omvll.BasicBlockDuplicateSkip)¶: Option for the basic_block_duplicate() callback. Disables the pass for the current function.

class omvll.BasicBlockDuplicateWithProbability(self: omvll.BasicBlockDuplicateWithProbability, probability: int)¶

Option for the basic_block_duplicate() callback. Selects basic blocks to duplicate with the given probability.

Parameters:: probability (int) – Percentage chance (0–100) for each basic block to be duplicated. 0 means never, 100 duplicates every block.

Control-Flow Breaking¶

class omvll.BreakControlFlowOpt(self: omvll.BreakControlFlowOpt, value: bool)¶

Option for the break_control_flow() callback.

Parameters:: value (bool) – True enables the protection, False disables it.

Control-Flow Flattening¶

class omvll.ControlFlowFlatteningOpt(self: omvll.ControlFlowFlatteningOpt, value: bool)¶

Option for the flatten_cfg() callback.

Parameters:: value (bool) – True enables the protection, False disables it.

Function Outline¶

class omvll.FunctionOutlineSkip(self: omvll.FunctionOutlineSkip)¶: Option for the function_outline() callback. Disables the pass for the current function.

class omvll.FunctionOutlineWithProbability(self: omvll.FunctionOutlineWithProbability, probability: int)¶

Option for the function_outline() callback. Selects basic blocks to outline into new functions with the given probability.

Parameters:: probability (int) – Percentage chance (0–100) for each candidate block to be outlined. 0 means never, 100 outlines every candidate.

Indirect Branch¶

class omvll.IndirectBranchOpt(self: omvll.IndirectBranchOpt, value: bool)¶

Option for the indirect_branch() callback.

Parameters:: value (bool) – True enables the protection, False disables it.

Indirect Call¶

class omvll.IndirectCallOpt(self: omvll.IndirectCallOpt, value: bool)¶

Option for the indirect_call() callback.

Parameters:: value (bool) – True enables the protection, False disables it.

Opaque Constants¶

class omvll.OpaqueConstantsSkip(self: omvll.OpaqueConstantsSkip)¶: Option for the obfuscate_constants() callback. Disables the pass for the current function. Alias for OpaqueConstantsBool(False).

class omvll.OpaqueConstantsBool(self: omvll.OpaqueConstantsBool, value: bool, arith_rounds: int = 0)¶

Option for the obfuscate_constants() callback. Obfuscates all constants (True) or none (False).

Parameters:

value (bool) – True protects all constants, False disables the pass.
arith_rounds (int) – Additional arithmetic obfuscation rounds applied to the generated opaque expressions. Default 0.

class omvll.OpaqueConstantsLowerLimit(self: omvll.OpaqueConstantsLowerLimit, limit: int, arith_rounds: int = 0)¶

Option for the obfuscate_constants() callback. Obfuscates only constants whose value is at or above limit.

Parameters:

limit (int) – Lower bound; constants below this value are left unprotected.
arith_rounds (int) – Additional arithmetic obfuscation rounds. Default 0.

Examples:

OpaqueConstantsLowerLimit(100)
OpaqueConstantsLowerLimit(100, arith_rounds=2)

class omvll.OpaqueConstantsSet(self: omvll.OpaqueConstantsSet, constants: List[int], arith_rounds: int = 0)¶

Option for the obfuscate_constants() callback. Obfuscates only the constants in the given list.

Parameters:

constants (list[int]) – Specific constant values to protect.
arith_rounds (int) – Additional arithmetic obfuscation rounds. Default 0.

Examples:

OpaqueConstantsSet([0x1234, 1, 2])
OpaqueConstantsSet([1, 2], arith_rounds=2)

class omvll.OpaqueConstantsExcludeSet(self: omvll.OpaqueConstantsExcludeSet, constants: List[int], arith_rounds: int = 0)¶

Option for the obfuscate_constants() callback. Obfuscates all constants except those in the given list.

Parameters:

constants (list[int]) – Constant values to leave unprotected.
arith_rounds (int) – Additional arithmetic obfuscation rounds. Default 0.

Examples:

OpaqueConstantsExcludeSet([0, 1])
OpaqueConstantsExcludeSet([0, 1], arith_rounds=2)

Opaque Fields Access¶

class omvll.StructAccessOpt(self: omvll.StructAccessOpt, value: bool)¶

Option for the obfuscate_struct_access() callback.

Parameters:: value (bool) – True enables the protection, False disables it.

class omvll.VarAccessOpt(self: omvll.VarAccessOpt, value: bool)¶

Option for the obfuscate_variable_access() callback.

Parameters:: value (bool) – True enables the protection, False disables it.

Strings Encoding¶

class omvll.StringEncOptSkip(self: omvll.StringEncOptSkip)¶: Option for the obfuscate_string() callback. Leaves the string unprotected.

class omvll.StringEncOptDefault(self: omvll.StringEncOptDefault)¶: Option for the obfuscate_string() callback. Defers the choice of encoding strategy to O-MVLL.

class omvll.StringEncOptGlobal(self: omvll.StringEncOptGlobal)¶: Option for the obfuscate_string() callback. Decodes the string in a global constructor (before main).

Warning

The string is briefly visible in clear memory as soon as the binary is loaded.

class omvll.StringEncOptLocal(self: omvll.StringEncOptLocal)¶: Option for the obfuscate_string() callback. Decodes the string lazily at the point of use within the function.

Danger

For large strings this can introduce significant overhead if called in a loop.

class omvll.StringEncOptReplace(*args, **kwargs)¶

Option for the obfuscate_string() callback. Replaces the original string with new_string.

Parameters:: new_string (str) – The replacement string. Defaults to an empty string.

Overloaded function.

__init__(self: omvll.StringEncOptReplace) -> None
__init__(self: omvll.StringEncOptReplace, new_string: str) -> None