Configuration

Configuration

RE-Toolkit is configured three ways: command-line options, environment variables, and the rule paths the installer establishes. Command-line options take precedence over environment variables, which take precedence over defaults.

Contents

• Precedence
• Path variables
• Rule variables
• Execution variables
• Dynamic analysis variables
• Skip controls
• Persistent configuration
• Installer configuration

Precedence

Command-line option  >  Environment variable  >  Built-in default

A skip control set in the environment applies to every run in that shell, and a command-line option overrides it for a single run. There is no configuration file: the environment is the persistence mechanism, which keeps the precedence rules simple and avoids a file whose location has to be discovered.

Path variables

Variable	Default	Purpose
OUTPUT_ROOT	./re-analysis-out	Output root. Overridden by -o.
GHIDRA_INSTALL	Unset	Explicit Ghidra installation path
GHIDRA_INSTALL_DIR	Unset	Alternative Ghidra path variable
RETOOLKIT_LIB_DIR	Alongside the driver	Location of lib/ modules
RETOOLKIT_STAGES_DIR	Alongside the driver	Location of stage files
RETOOLKIT_SENTINEL_DIR	Output directory	Where run sentinel files are written
VENV_PY	Installer-provisioned	Python interpreter for analysis code

Ghidra discovery searches in order: GHIDRA_INSTALL, GHIDRA_INSTALL_DIR, /opt/ghidra, /opt/ghidra_*_PUBLIC, then /usr/share/ghidra. The -g option overrides all of them.

RETOOLKIT_LIB_DIR and RETOOLKIT_STAGES_DIR matter mainly for development. A checkout can be run directly without installing over /opt/retoolkit:

export RETOOLKIT_LIB_DIR=~/dev/retoolkit/lib
export RETOOLKIT_STAGES_DIR=~/dev/retoolkit/stages/static
~/dev/retoolkit/analyze-binaries.sh -t sample.exe -o ./out

Rule variables

Variable	Default	Purpose
CAPA_RULES	/opt/capa-rules	capa rule directory
YARA_RULES	/opt/yara-rules/_master.yar	YARA rules, directory or master file

Both are exported system-wide by the installer through /etc/profile.d/retools.sh, so a normal install needs no configuration here. Override them for a run with --capa-rules and --yara-rules.

To use your own rule set persistently:

echo 'export YARA_RULES=~/rules/custom.yar' >> ~/.bashrc

When pointing YARA_RULES at a directory rather than a master file, be aware that rule identifiers must be unique across the whole set. Duplicate identifiers across files produce compile errors, which is why the installer builds a deduplicated master index rather than compiling a directory directly.

Execution variables

Variable	Default	Purpose
TOOL_TIMEOUT	600	Per-tool timeout in seconds
GHIDRA_TIMEOUT	3600	Ghidra per-file timeout
JVM_HEAP	4G	Ghidra JVM heap
LOG_LEVEL	info	debug, info, warn, or error

Timeouts are the setting most often worth changing. The defaults suit typical targets; large or heavily obfuscated binaries need more. A tool killed by a timeout is recorded as a timeout rather than a failure, so the report shows where the limit was reached instead of silently omitting the result.

export TOOL_TIMEOUT=1800
export JVM_HEAP=8G

Dynamic analysis variables

Variable	Default	Purpose
DYNAMIC_MODE	Empty, meaning auto-tier	qiling, firejail, docker, or cuckoo
DYNAMIC_AUTO	Auto	Auto-tier selection
DYNAMIC_TIMEOUT	60	Hard timeout per binary
DYNAMIC_NETWORK	none	none, tap, or host
RETOOLKIT_REFERENCE_BINARY	Unset	Reference target for diff stages

Leaving DYNAMIC_MODE empty selects auto-tier mode, which runs every applicable and available tier. Setting it restricts the run to exactly one tier, which is the behavior automation usually wants.

DYNAMIC_NETWORK has no effect on Tier 1, which emulates rather than executes and therefore has no real network. It governs network exposure for the tiers that genuinely run the target. Leave it at none unless you specifically intend to observe network behavior and have isolated the host accordingly.

Skip controls

Every stage is governed by a skip control, settable as an environment variable or through its command-line option. Setting the variable makes the preference persistent across runs in that shell.

# Skip Ghidra for every run in this shell
export SKIP_GHIDRA=1

# Equivalent for a single run
analyze-binaries.sh -t sample.exe -o ./out --no-ghidra

Opt-in stages use ENABLE_* variables with inverted sense: the stage runs only when the variable is set.

export ENABLE_ANGR=1        # equivalent to --enable-angr
export ENABLE_YARGEN=1      # equivalent to --enable-yargen
export ENABLE_CWE_CHECKER=1 # equivalent to --enable-cwe-checker

Three skip controls have no command-line option and can only be set through the environment:

Variable	Affects
SKIP_BINARY_DIFF	Byte-level binary diff
SKIP_RETDEC	RetDec decompilation
SKIP_ROP_GADGETS	ROP gadget enumeration

The complete index of skip controls, their options, and the stages they affect is in Stage Reference.

Persistent configuration

Because configuration lives in the environment, a persistent setup is a shell profile entry. A reasonable starting point for an analysis VM:

# ~/.bashrc
export TOOL_TIMEOUT=1200          # allow slower tools to finish
export JVM_HEAP=8G                # more headroom for Ghidra
export LOG_LEVEL=info
export YARA_RULES=~/rules/custom.yar

For a triage-focused profile that favors speed:

export SKIP_GHIDRA=1              # skip the slowest stage
export TOOL_TIMEOUT=120

Keep in mind that an exported skip control silently reduces coverage for every run in that shell. When results look thinner than expected, the environment is worth checking before the target is. The report records which stages were skipped, which is the reliable way to confirm what actually ran.

Installer configuration

The installer is configured entirely through command-line options rather than environment variables, because provisioning is a deliberate, occasional act rather than something that should inherit ambient shell state.

See Installation for the option reference.

The one environment interaction worth noting: the installer writes /etc/profile.d/retools.sh, which exports CAPA_RULES and YARA_RULES for all users. That file is where those defaults come from, and editing it changes them system-wide.