garble

To obfuscate a specific function, add the //garble:controlflow comment directly above the function definition. You can optionally pass parameters to fine-tune the obfuscation intensity.

Default usage:

//garble:controlflow
func main() {
	println("Hello world!")
}

Advanced usage with parameters:

//garble:controlflow block_splits=max junk_jumps=max flatten_passes=max
func main() {
    println("Hello world!")
}

// Obfuscate with maximum parameters
//garble:controlflow block_splits=max junk_jumps=max flatten_passes=max
func main() {
    println("Hello world!")
}

Control flow obfuscation is an experimental feature. To enable it, you must set the following environment variable before running garble:

GARBLE_EXPERIMENTAL_CONTROLFLOW=1

The garble CLI wraps the Go toolchain to obfuscate Go code. You can use it as a drop-in replacement for standard go commands like build, test, and run.

Basic Usage Pattern: garble [garble flags] command [go flags] [go arguments]

Examples:

Build an obfuscated program:

garble build ./cmd/foo

Combine garble flags with Go build flags:

garble -literals build -tags=purego ./cmd/foo

The garble reverse command is used to de-obfuscate text, such as panic stack traces or build errors, captured from an obfuscated program. It maps hashed names and obfuscated file paths back to their original, human-readable forms.

To use it, you must provide the same build flags (like -literals or -tags) that were used during the original obfuscated build, followed by the package path and the target file(s) containing the obfuscated text.

Usage Pattern: garble [garble flags] reverse [build flags] package [files]

When using control flow obfuscation, be aware of the following:

• Map Iteration: Obfuscation breaks lazy iteration over maps.
• Complexity Scaling: flatten_passes increases control flow complexity non-linearly. It is generally recommended not to exceed a value of 3.
• Parameter Dependency: block_splits, junk_jumps, and trash_blocks only function if flatten_passes is enabled.

You can control garble behavior and profiling using environment variables:

• GARBLE_SHARED: Sets the directory for shared cache data.
• GARBLE_CACHE: Sets the directory for the garble cache (defaults to user cache directory).
• GARBLE_EXPERIMENTAL_CONTROLFLOW: Set to 1 to enable experimental control flow obfuscation.
• GARBLE_WRITE_CPUPROFILES: Set to a directory path to write .pprof CPU profiles.
• GARBLE_WRITE_MEMPROFILES: Set to a directory path to write .pprof heap profiles.
• GARBLE_WRITE_ALLOCS: Set to a directory path to write allocation statistics text files.
• GOGARBLE: Set to a value to specify which packages to obfuscate (defaults to * for everything).

These parameters are passed via the //garble:controlflow comment.

Note: Most parameters (except flatten_passes) only affect the resulting binary when flatten_passes is greater than 0.

The transformAsm method processes Go assembly files (.s). It performs several tasks:

• Obfuscates the package name using -p.
• Modifies -trimpath to prevent leaking temporary directories.
• Replaces Go assembly constant names (e.g., go_asm.h mappings).
• Replaces function references in assembly with their obfuscated counterparts.
• Handles #include directives by creating garbled versions of header files.
• Writes the resulting obfuscated assembly to a temporary directory.

func (tf *transformer) transformAsm(args []string) ([]string, error)

The transformCompile method is the core of the Go source obfuscation process. It:

• Forces the linker to drop DWARF information via -dwarf=false.
• Seeds a deterministic random number generator for literal and control flow obfuscation.
• Performs type-checking on the files.
• Optionally builds SSA (Static Single Assignment) form for control flow obfuscation.
• Obfuscates literals and transforms Go source files (renaming packages, types, and functions).
• Rewrites toolchain directives like //go:linkname and //go:cgo_import_dynamic.
• Generates a new -importcfg to account for obfuscated import paths.
• Returns the updated compiler flags and paths to the new obfuscated files.

func (tf *transformer) transformCompile(args []string) ([]string, error)