README.md

                                _            
  /\  /\ ___  _ __  ___  _   _ | |  ___  ___ 
 / /_/ // _ \| '__|/ __|| | | || | / _ \/ __|
/ __  /|  __/| |  | (__ | |_| || ||  __/\__ \
\/ /_/  \___||_|   \___| \__,_||_| \___||___/

---

Hercules is a powerful Lua obfuscator designed to make your Lua code nearly impossible to reverse-engineer. With multiple layers of advanced obfuscation techniques, Hercules ensures your scripts are secure from prying eyes.

If you decide to use/fork Hercules, please do star it to show support. It helps out a ton!

Contact either zeusssz_ on Discord for queries, or join the Discord, to use the Herucles Bot.

You may also use the Website to obfuscate your code

---

Features

• String Encoding: Transform strings into seemingly indecipherable formats using an advanced Caesar Cipher, making reverse engineering a daunting task.

• Variable Renaming: Elevates your code's security by replacing original variable names with a unique set of randomly generated identifiers, effectively masking their true intent.

• Control Flow Obfuscation: Introduces intricate, deceptive control flow structures to mislead static analysis tools, ensuring your logic remains obscured from prying eyes.

• Garbage Code Insertion: Strategically inject meaningless code snippets that bloat your scripts, complicating the analysis and deterring attackers.

• Bytecode Encoding: Seamlessly convert critical sections of your script into bytecode, adding an additional layer of complexity that hinders comprehension.

• Function Inlining: Enhances obfuscation by embedding function bodies directly into their calls, effectively disguising the original flow and logic of the code.

• Opaque Predicates: Utilizes constructed conditions that always evaluate to true or false, creating confusion about the actual functionality of your code.

• Dynamic Code Generator: Generates code blocks dynamically from the script itself, complicating static analysis and enhancing security.

• String to Expressions: Transform string literals into complex mathematical expressions, making it nearly impossible to deduce their original meaning.

• Virtual Machinery: Employs a virtual machine environment to execute obfuscated code, adding a layer of execution complexity that challenges traditional analysis techniques.

• Wrap In Function: Encapsulates entire scripts within a function, further obscuring the code's entry points and enhancing overall security.

• Anti Tamper: Implements runtime integrity checks to detect and block unauthorized overrides or manipulations of core functions and bytecode.

---

Installation

1. Clone this repository (alternatively, install the ZIP file):

   git clone https://github.com/zeusssz/hercules-obfuscator.git
   cd hercules-obfuscator/src
   

2. Run the obfuscator:

   lua hercules.lua path/to/your/script.lua
   

---

Usage

To obfuscate a Lua script using Hercules, simply run:

lua hercules.lua path/to/your/script.lua

This will generate an obfuscated version of the script in the same directory, with the filename *_obfuscated.lua.

Example

lua hercules.lua my_script.lua

Output: my_script_obfuscated.lua – the obfuscated version of your script.

---

If you specify the overwrite option with the --overwrite flag, it will write over to the specified script, instead of creating a new file.
You may also specify a preset using --light, --balanced, --heavy, or --maximum. eg.

lua hercules.lua my_script.lua --maximum

You may also choose modules through the command line by using the flags, such as --compressor/-c. eg.

lua hercules.lua my_script.lua -c --antitamper

above enables compressor and antitamper

Adding a New Module

To add a module so it runs in the pipeline and gets picked up by the test suite, follow these steps:

1. Create the module file

Create a new Lua file in src/modules/ (e.g. my_module.lua). It must export a .process(code, ...) function that returns the transformed code:

-- modules/my_module.lua
local M = {}

function M.process(code, some_option)
    -- transform code here
    return code
end

return M

2. Register it in config.lua

Add a default config entry under settings so the module can be toggled:

settings = {
    -- ...existing entries...
    my_module = { enabled = false },  -- or enabled = true
},

If your module has configurable parameters (e.g. intensity, name lengths), add them here as well.

3. Wire it into pipeline.lua

a) Add a require at the top:

local MyModule = require("modules/my_module")

b) Call it inside Pipeline.process(code) at the correct position (order matters!):

if config.get("settings.my_module.enabled") then
    local param = config.get("settings.my_module.some_parameter")
    code = MyModule.process(code, param)
end

4. Register it in test.lua

a) Add the module name to ALL_MODULES:

local ALL_MODULES = {
    "VirtualMachine",
    -- ...existing modules...
    "my_module",    -- add here
}

b) Map it to its config path in MODULE_PATHS:

local MODULE_PATHS = {
    -- ...existing mappings...
    my_module       = "settings.my_module.enabled",   -- add here
}

5. Verify

cd src
lua test.lua --quick --verbose   # should show your new module in single-module tests

---

Customization

You can modify or add new modules to the modules/ directory to create additional layers of obfuscation. The pipeline.lua file controls the order of obfuscation steps.

---

Testing

A comprehensive end-to-end test suite verifies all $2^{14}$ − 1 = 16,383 module combinations against a realistic Lua fixture (FNV-1a hashing, JSON builder, escape sequences, closures, method chains, and multi-line table constructors). Each test runs actual obfuscation via Pipeline.process() and verifies the output matches expected results.

Supported Targets

Target	Modules	Notes
Lua 5.4	14/14	Full support including VirtualMachine and bytecode_encoding
Luau	12/14	VirtualMachine and bytecode_encoding disabled (incompatible bytecode)

Python Parallel Runner (recommended for full sweep)

Fast parallel execution using multiple Lua worker processes:

# Full combination sweep with auto-detected workers (Lua target)
python3 test_py.py

# Explicit worker count
python3 test_py.py --jobs 8

# Luau target (12 modules, validated with luau binary)
python3 test_py.py --target luau

# Run both Lua and Luau tests
python3 test_py.py --target both

Luau Support

The obfuscator supports generating code for Luau (Roblox's Lua dialect):

# Obfuscate for Luau target
lua hercules.lua script.lua --target luau -cf -se -vr -gci -opi -st -wif -fi -dc -at

# Output: script_obfuscated.luau

Luau-specific adaptations:

• VirtualMachine and bytecode_encoding modules are automatically disabled
• load() calls in source code are converted to loadstring()
• Polyfills for math.ldexp/math.frexp are prepended to output
• Antitamper checks only functions available in Luau (no loadfile, dofile, debug.*, os.exit)

Lua Test Runner (recommended for quick checks)

Interactive test suite with selective test groups:

# Quick mode: baseline + 14 single modules + 64 core combos (~5s)
lua test.lua --quick

# Full combination sweep (single process)
lua test.lua --test full_combinations --verbose

# Run all tests
lua test.lua --verbose

# Test a specific fixture against all combinations
lua test.lua --test fixture_sweep_main_script --verbose

# Run only single module tests
lua test.lua --group single --verbose

# Baseline only (no modules)
lua test.lua --test baseline_no_modules --verbose

# List all available tests
lua test.lua --list

# Show help
lua test.lua --help

All commands must be run from the src/ directory.

Test Coverage

Suite	What it tests	Combinations
quick	Baseline + 14 singles + 64 core combos	79 tests
full_combinations	All non-empty module subsets	16,383 combos
single_<module>	Each module individually	14 tests
fixture_sweep_*	All combos against one fixture	16,383 each
config_get_set	Config API validation	16 tests

Working modules (14/14): VirtualMachine, antitamper, bytecode_encoding, opaque_predicates, function_inlining, dynamic_code, string_encoding, garbage_code, control_flow, compressor, WrapInFunction, watermark, variable_renaming, StringToExpressions

---