Heracles

簡介

Heracles 是一套針對 Prometheus 混淆 Lua 程式的自動解混淆與分析工具。Pipeline 結合 tool-based passes、LLM-assisted recovery、Lua 5.1 語法驗證、受限執行與證據導向報告，主要輸出為：

• 解混淆後的 Lua 程式碼
• Markdown 與 PDF 分析報告
• 語法、sandbox、metrics 與可重現性資料

Heracles 不會在缺乏證據時猜測命名或意圖；不完整復原會標記為 partial 並保留未解決問題。目前只有一套 LLM 解混淆流程，不需要選擇 method。

內建第一階段工具衍生自 Prometheus；相關授權位於 src/de_obfuscator_tool/PROMETHEUS_LICENSE。

Based on Prometheus by Elias Oelschner, https://github.com/prometheus-lua/Prometheus

Heracles 原創程式碼採用 MIT License；第三方與測資授權範圍請見 THIRD_PARTY_NOTICES.md。

環境需求

• Python 3.11 以上
• Node.js 與 npm
• Lua 5.1：lua5.1、luac5.1
• Prometheus CLI v0.2.11.1：prometheus-lua 必須可由 PATH 執行
• LLM CLI：OpenCode、Claude Code 或 Codex
• Sandbox：Linux 使用 bubblewrap；macOS 使用 sandbox-exec
• 可顯示繁體中文的 CJK 字型（PDF 報告建議）

Python dependencies 定義於 pyproject.toml；Node.js dependencies 由 package-lock.json 鎖定，AST parser 使用 luaparse@0.3.1。

檔案架構

.
├── main.py                         # Pipeline CLI 與模組串接
├── Makefile                        # 使用者操作入口
├── configs/                        # Pipeline、模型、fixtures、實驗設定
├── dataset/                        # 納入本 repository 的 Lua 測資
├── prompts/                        # LLM 與各分析角色 prompts
├── src/
│   ├── common/                     # 共用 models、config 與 interfaces
│   ├── obfuscator/                 # Prometheus CLI adapter
│   ├── de_obfuscator_tool/         # 內建 tool-based 解混淆與 SSA cleanup
│   ├── de_obfuscator_llm/          # LLM recovery、AST 與 Worker runtime
│   ├── llm_runtime/                # Providers、prompts、tokens、tracking
│   ├── verifier/                   # Lua 5.1 語法驗證
│   ├── analyzer/                   # 程式與威脅分析
│   ├── sandbox/                    # 受限執行與行為比較
│   ├── reporter/                   # Markdown／PDF 報告
│   └── evaluator/                  # Metrics 與實驗評量
├── tests/
└── logs/{run_id}/                  # 執行產物；不納入 Git

使用方式

所有操作都從專案根目錄透過 Makefile 執行；完整參數可查看：

make help

初始化

建立 .venv 並安裝 Python 與 Node.js dependencies：

make setup

在 configs/models.yaml 選擇 LLM interface、command 與 model，完成後執行：

make test

整體 pipeline 執行

輸入尚未混淆：

make run INPUT=input.lua

輸入已經過 Prometheus 混淆：

make run INPUT=obfuscated.lua OBFUSCATED=1

SSA cleanup 預設啟用；需要保留 stage-one 原始 locals 時可停用：

make run INPUT=obfuscated.lua OBFUSCATED=1 NO_SSA_CLEAN=1

常用覆寫：

make run \
  INPUT=input.lua \
  PRESET=Weak \
  RUN_ID=experiment-001 \
  ARTIFACT_PROFILE=audit

使用自訂 Prometheus config：

make run INPUT=input.lua PROMETHEUS_CONFIG=config.lua

主要 Make variables：

Variable	用途	預設值
INPUT	輸入 Lua	必填
OBFUSCATED	輸入是否已混淆	0
NO_SSA_CLEAN	跳過 SSA cleanup	0
PRESET	Prometheus preset	Minify
RUN_ID	Run 識別碼	自動產生
ARTIFACT_PROFILE	summary、audit、debug	summary
PROMETHEUS_COMMAND	PATH 中的 Prometheus command	prometheus-lua
LUA51／LUAC51	Lua runtime／syntax checker	lua5.1／luac5.1
SANDBOX_COMMAND	auto、bwrap、sandbox-exec	auto
EXTRA_ARGS	傳給內部 CLI 的其他參數	空值

成功的 summary run 主要保留：

logs/{run_id}/
├── obfuscator/
├── stage_one/
├── stage_one_runtime/fixture_suite.json
├── final_deobfuscated.lua
├── validation.json
├── deobfuscation_result.json
├── llm_usage.json
├── analysis/
├── sandbox/fixture_suite.json
├── report.md
├── report.pdf
├── metrics.json
├── pipeline.log
└── manifest.json

各階段分開執行

# 準備輸入／Prometheus 混淆
make prepare INPUT=input.lua
make prepare INPUT=obfuscated.lua OBFUSCATED=1

# Tool-based 解混淆與預設 SSA cleanup
make stage-one INPUT=input.lua
make stage-one INPUT=obfuscated.lua OBFUSCATED=1 NO_SSA_CLEAN=1

# 獨立 SSA cleanup
make ssa-clean INPUT=input.lua
make ssa-clean INPUT=input.lua SSA_OUTPUT=cleaned.lua

# LLM 解混淆
make stage-two STAGE_TWO_INPUT=logs/<run_id>/stage_one/ssa_cleaned.lua

# 建立 adaptive Worker context
make context INPUT=stage_one.lua

# Lua 5.1 語法驗證
make validate CANDIDATE=candidate.lua

# Observable behavior 比較
make sandbox CANDIDATE=candidate.lua REFERENCE=reference.lua

# 既有 candidate 與 report 評量
make evaluate \
  CANDIDATE=final_deobfuscated.lua \
  REPORT=report.md \
  REFERENCE=reference.lua

Analyzer 與 Reporter 由完整的 make run 串接，不提供獨立 target。

Pipeline 說明

1. 輸入準備：保存原始輸入；未設定 OBFUSCATED=1 時呼叫 PATH 中的 prometheus-lua。
2. Tool-based 解混淆：移除 Prometheus wrapper、anti-tamper 與無效結構，執行常數化簡、Vmify lifting 與 source reconstruction。
3. SSA cleanup：拆分 register reuse 並保守傳遞 locals；nested closure、loop-carried values 與 Lua local limit 受到保護。
4. Stage-one observation：在 fixtures 下收集 stdout、stderr、exit status 與可選 API trace。
5. LLM-assisted recovery：依實際複雜度選擇完整程式或 adaptive Workers，恢復 payload、命名與 control flow。
6. AST runtime：luaparse 只負責 scope、chunking、lexical bindings、語意比較與安全 range patches，不是另一種 LLM method。
7. 語法驗證：以 luac5.1 -p 檢查候選程式；語法錯誤進行 bounded repair，infrastructure error 直接停止。
8. 分析與 sandbox：產生具來源 hash、行號與 snippet 的 findings，並比較 reference／candidate 在指定 fixtures 下的 observable behavior。
9. 報告：驗證結構化 report data 後產生 Markdown 與 PDF；標題使用原始輸入檔名，partial 狀態必須揭露。
10. 評量與 retention：輸出 metrics；summary 保留重點產物、audit 增加壓縮 trace、debug 保留完整工作資料。失敗 run 不進行 cleanup。

Sandbox 結果只代表指定 fixtures 下的可觀察等價，不是形式化等價證明。每個 run 的 manifest.json 記錄設定、階段摘要以及保留檔案的 SHA-256 與大小。