obfuskator/docs/learnings/reference.md

Референс: Fabric Mod Obfuscator (Java + ASM)

Разобранный образец лежит в /tmp/opencode/obf_extract/OBF (JAR из OBF.rar). Нужен не как «правильный ответ», а как карта решений, которые уже были приняты и проверены на живых кейсах.

1. Что это

язык	Java 21, Maven, сборка mvnw package
движок	ASM (читает .class, строит маппинги, переписывает байткод)
объём	18 классов в org.example, 3224 строки
цель	Fabric/Minecraft-моды
интерфейс	CLI + Swing GUI (drag-and-drop)

2. Карта модулей → наш план

модуль	LOC	что делает	у нас
JarRemapper	409	обход архива, remap всех ссылок	noxis-jar + rename::rewrite
InheritanceAnalyzer	373	иерархия, безопасность переименования	noxis-analysis::hierarchy ✅
ObfuscatorGui	276	GUI	не нужно (CLI)
MappingGenerator	262	маппинг → файл	noxis-core::mapping ✅
JunkClassGenerator	251	junk-классы	пасс noise
StringDecoderGenerator	205	генерит класс-декодер	noxis-runtime + P2 генератор
ObfuscatorRunner	202	конвейер, оркестрация	noxis-passes::standard_pipeline ✅
NumberObfuscator	185	константы / opaque	пасс constants
ControlFlowObfuscator	183	flattening	пасс flow (ждёт StackMapTable)
FabricKeepRuleScanner	147	keep из конфига Fabric	noxis-analysis::keep ✅
Main	134	CLI-точки	noxis (clap)
StringEncryptor	132	AES-128 строк + chunk'и	noxis-runtime::scheme ✅
NameGenerator	131	имена	noxis-passes::namegen ✅
JunkAnnotationInjector	79	junk-аннотации	пасс noise
PackageGenerator	78	пакеты	namegen::generate_packages ✅
AccessWidener	73	патч access widener	noxis-jar + пасс resources
DebugInfoStripper	69	strip отладки	пасс debug
StringFilter	35	что считать строкой	функция внутри strings

Вывод: структура совпадает с нашей почти один в один — это подтверждает раскладку крейтов. Ключевое отличие: у них всё живёт в одном jar'е и одном проекте; у нас конвейер отделён от I/O и от CLI.

3. Что берём

3.1 Порядок пассов

У них: remap → strings → numbers → flow → junk → debug. Тот же инвариант, что и у нас: переименование раньше всех техник, порождающих новые ссылки, а debug — последним.

3.2 Наследование как условие безопасности

InheritanceAnalyzer — самый большой после remap'ера модуль. Совпадает с нашим выводом: переименование virtual-методов без иерархии ломает invokevirtual. У нас это hierarchy + семейства в rename.

3.3 Keep-сканер

FabricKeepRuleScanner читает правило из конфигурации Fabric и не даёт сломать то, что JVM находит по имени. Мы делаем то же самое + расширяем рефлексией по строкам.

3.4 Подпись срезается

*.SF/*.RSA/*.DSA/*.EC удаляются при перепаковке — после записи подпись всё равно невалидна, а её наличие заставляет JVM падать. Это входит в noxis-jar.

3.5 Маппинг в файл + ложные ограничения

--mappings пишет соответствие «новое → старое» — без него автор сам не читает stack trace. Плюс честные off-ключи: --no-strings, --no-flow, --no-junk, --keep-lines, --keep-source, --keep-vars, --no-widen.

Мы берём то же: каждый пасс выключаем по отдельности, иначе диагностика проблемы «что сломало» превращается в угадывание.

3.6 Seed

--seed — детерминированный прогон. У нас это базовое свойство noxis-core, без отдельного флага.

4. Что не берём

4.1 Java + ASM

Главное отличие стека. Пара Java+ASM даёт родную JVM, готовые visitor'ы и CheckClassAdapter — но и:

• нужно раскатывать JDK для сборки и запуска тестов;
• наш проект — Rust (deny(unsafe_code), свои лимиты, свои гейты);
• отсутствует возможность отдавать один бинарь.

Цена, которую мы платим: StackMapTable придётся считать самим (через inference-верификатор — ../stack.md §3). Это осознанно.

4.2 Swing GUI

Лишняя точка входа: GUI дублирует CLI и удваивает площадь тестирования. У нас — только clap.

4.3 StringDecoderGenerator как «генератор текста»

Они генерируют Java-исходник декодера и компилируют. Для нас это означало бы зависимость от javac на этапе обфускации. Наш путь — генерировать байткод напрямую через наш IR (noxis-runtime держит схемы, генератор собирает ClassFile).

4.4 AES-128 + Base64 как единственная схема

Одна схема на весь архив = тот же провал, что у EvoVis §1/§9. У нас ротация схем, per-string salt, nonce и MAC.

4.5 --flatten-flow только «для простых методов»

Ограничение из их README: агрессивный switch-gate включается только на простых методах. Это признаёт, что верификация у них эмпирическая. Мы вместо этого делаем верификатор обязательным условием включения flow.

5. Что проверяем на их smoke-тестах

В target/ референса лежат готовые проверочные кейсы — их стоит переиспользовать как наш regression-набор:

кейс	что ломает
smoke-safe	базовый round-trip, Sample/MyMixin
smoke-inheritance	Base/Child/InheritedChild/ExternalChild — семейства virtual и мосты
smoke-flow	LoadAll — загрузка всех классов, ловит VerifyError
smoke-fields	переименование полей и статических полей
smoke-aes	шифрование строк, RunStrings сверяет расшифровку
Probe.java	точечная проверка одной гипотезы

Это ровно тот класс тестов, который нужен noxis-verify: загрузить и выполнить, а не «выглядит обфусцированным».

6. Итог

берём	не берём
порядок пассов	стек Java + ASM
иерархия как условие rename	Swing GUI
keep-сканер	генератор Java-исходника
срез подписей, патч ресурсов	единственная схема шифра
маппинг в отчёт, честные off-ключи	эмпирическая верификация flow
их smoke-кейсы как regression	—

Полный перечень провалов защиты, которую они не закрывают, — в lessons.md.