Initial commit: noxis JVM bytecode obfuscator

Workspace of 9 crates (noxis, noxis-core, noxis-classfile, noxis-analysis, noxis-passes, noxis-runtime, noxis-jar, noxis-verify, noxis-structure-check). AGPL-3.0-only license, Rust 2024 edition, unsafe_code denied.
2026-10-08 22:01:03 +02:00 · 2026-10-08 22:01:03 +02:00 · a641e69455
commit a641e69455
140 changed files with 17197 additions and 0 deletions
--- a/docs/learnings/lessons.md
+++ b/docs/learnings/lessons.md
@ -0,0 +1,146 @@
+# Уроки: что защита EvoVis сделала плохо
+
+Источник: `info/evo-weaknesses.md` — полный разбор за один проход, без
+рантайм-хаков. Здесь — что из этого следует для **нашей** архитектуры.
+
+Правило, которое стоит держать головой: **защита ломается не в рантайме,
+а на этапе, когда атакующий смотрит на статику.** Всё, что видно в `javap -p`
+или в содержимом jar, — это утечка.
+
+## Сводная таблица: провал → наше решение
+
+| № | провал EvoVis | наше решение | пасс | статус |
+|---|---|---|---|---|
+| 1 | ключ лежит рядом с шифротекстом | вывод мастер-секрета в декодере, ключ из `master‖salt` | Strings | частично |
+| 2 | переименованы типы, но не члены | rename полей/методов + семейства virtual | Rename | **готово** |
+| 3 | отладочная информация нетронута | strip + ложный `SourceFile`/номера строк | DebugInfo | план |
+| 4 | шаблонный flattening | 4 схемы CFG + мешанина внутри метода | Flow | план |
+| 5 | opaque-предикаты = `A+B` | ротация тождеств + предикаты от состояния | Constants | план |
+| 6 | junk-классы вне графа reachability | `weave_reachable` — обязательная вплетённость | Noise | план |
+| 7 | имена говорят «я защита» | все артефакты получают данные псевдонимы | Rename | **готово** |
+| 8 | вторичные компоненты без защиты | весь jar, а не только основной класс | Resources | план |
+| 9 | шифр без MAC и без per-string salt | salt на строку, уникальный nonce, MAC | Strings | **готово** |
+
+## 1. Ключ рядом с шифротекстом
+
+`awc.d("<cipher>", <opaque-выражение>)` — ключ был **константным выражением
+в вызове**. Свёртка выражения — ~200 строк любого парсера. Итог: 8993 вызова
+расшифрованы детерминированно, **0 обращений к JVM**.
+
+Хуже: один шифр на весь продукт (LCG с фиксированными `a/c`) — зная одну
+пару «шифротекст → текст», остальные раскрываются по обучению.
+
+**Что делаем иначе.**
+
+- Ключ строки = `F(master, salt)`, `master` **выводится** в рантайме и не
+  является константой в `LDC`.
+- `salt` лежит рядом с шифротекстом, но сам по себе бесполезен без `master`.
+- **Ротация схем** (`xor-splitmix` / `xtea-ctr`): одна расшифровка не даёт
+  ключа ко всему jar. Плюс per-string `nonce`, чтобы пары «текст→шифр»
+  не повторялись и частотный анализ не работал.
+- MAC: подмена байта не «тихо» портит текст.
+
+Остаточный риск честно признан: целевой анализ декодера раскрывает текст.
+Задача — поднять цену, а не сделать невозможным.
+
+## 2. Члены не переименованы
+
+`onDraw`, `getProjectiles`, `isAuthorized()` — открытые имена. Класс `wb`
+опознаётся за секунду по трём понятным методам.
+
+**Что делаем иначе:** переименование полей и методов входит в базовый
+уровень, а не в «продвинутый». Уже готово, включая:
+
+- **семейства virtual** — переименование на всю иерархию, чтобы не
+  разъединить переопределения и не сломать `invokevirtual`;
+- **keep-список** — private/static/final можно сразу, `rename_public_members`
+  по умолчанию выключен для библиотек, чтобы не сломать API;
+- **автодетект рефлексии по имени** — `Class.forName`, `getMethod`,
+  `getField` с литералами попадают в keep автоматически.
+
+## 3. Отладочная информация
+
+`SourceFile` оригинальные у 160 классов, `LineNumberTable` — 10 218,
+`LocalVariableTable` — имена локальных переменных, `@rn(name, description)` —
+каталог всех модулей с описаниями.
+
+**Что делаем иначе:** пасс `DebugInfo` — strip `SourceFile`,
+`LineNumberTable`, `LocalVariableTable`, `Signature`, `InnerClasses` +
+**ложная** отладочная информация (чужие имена и номера строк, чтобы
+деобфускатор выдавал правдоподобный, но чужой код).
+
+Отсюда обязательное требование: **маппинги в отчёте** — иначе мы сами не
+читаем свои stack trace'и.
+
+## 4. Шаблонный flattening
+
+Один regex нашёл 3530 автоматов: `while(true) { switch(i + i2) }`, метки —
+константы, переходы — присваивания в одном basic block, тела блоков не
+тронуты.
+
+**Что делаем иначе:** не одна схема, а **четыре** (`state-spread`,
+`computed-switch`, `butterfly`, `exception-goto`), с ротацией между методами
+и с перемешиванием внутри метода. Плюс `butterfly` и `exception-goto`
+ломают «все переходы — присваивания».
+
+Это единственная техника с **высоким риском**: любая ошибка в CFG =
+`VerifyError`. Поэтому блокером Flow объявлен не «напишем потом», а
+`StackMapTable` — см. [`../stack.md`](../stack.md) §3. Без верификатора
+Flow не включается.
+
+## 5. Opaque-предикаты
+
+`(A^B)+((A&B)<<1)` — школьное тождество, узнаётся регуляркой и даёт
+бесплатный фолдинг остальных констант. Настоящих предикатов (зависящих
+от состояния и всегда истинных) нет.
+
+**Что делаем иначе:** ротация семейств тождеств (арифметика, побитово,
+сдвиги, произведение соседних чисел, инвариант по модулю) + предикаты,
+завязанные на состояние, а не на пару констант.
+
+## 6. Reachability убивает junk
+
+42 файла, ни одного входящего ссылока, `dangling=0` → BFS от 4
+entrypoint'ов, которые открыто лежат в `fabric.mod.json`.
+
+**Что делаем иначе:** `weave_reachable` — junk попадает в граф
+достижимости, создаёт ложные рёбра и участвует в вызовах. Это свойство
+пасса, а не настройка: без вплетённости junk не включается вовсе.
+
+## 7. Самоописание защиты
+
+`StringRuntime`, `KeyAssembler`, `AttestClient`, `RuntimeGuard`,
+`SealedBoot`, `NativeGuard` — названия указывают атакующему, куда смотреть.
+
+**Что делаем иначе:** псевдонимы генерируются одним `NameGenerator` для
+всех сущностей — классы, пакеты, поля, методы, junk и даже имена атрибутов
+и схем выглядят как обычные данные. Отдельного «защитного» стиля не
+существует, поэтому отличить его от остального кода не по чему.
+
+## 8. Вторичные компоненты
+
+`evo-agent.jar` вообще без обфускации, .NET-лаунчер — статическая XOR-таблица.
+
+**Что делаем иначе:** обфускация применяется ко **всему архиву**, включая
+ресурсы (`fabric.mod.json`, mixins, refmap, access widener) — см. пасс
+`Resources`. Отдельного «ядро защищено, остальное нет» не бывает.
+
+## 9. Шифр без аутентификации
+
+Нет MAC, нет per-string сида → повреждение не ловится, частотный анализ
+работает.
+
+**Уже сделано:** `salt` на строку, уникальный `nonce`, FNV-1a MAC в
+`noxis-runtime::scheme`. `cipher:tag` лежат рядом — порча обнаруживается.
+
+## Что подтвердилось и не нужно повторять в выводах
+
+Разбор дал и **опровержения** — важно не строить защиту на мифах:
+
+- «сдвиги в байткоде бывают отрицательными» — по 1277 классам **0** случаев
+  (32 559 сдвигов, константные всегда `1`);
+- `awc.g(...)` (session-gate) в билде **не вызывался ни разу**.
+
+Вывод: проверять гипотезу на статистике **до** того, как вкладываться
+в технику против неё. Отсюда требование к `noxis-verify` — не «красиво
+обфусцировано», а измеримые метрики ([`priorities.md`](priorities.md)).
--- a/docs/learnings/priorities.md
+++ b/docs/learnings/priorities.md
@ -0,0 +1,116 @@
+# Что улучшим: стратегия и приоритеты
+
+Материал собран из `info/evo-improvements.md` (план после разбора EvoVis) и
+`info/evo-weaknesses.md` (провалы). Здесь — что мы берём, в каком порядке
+и **что осознанно не делаем**.
+
+## Стратегия в одном абзаце
+
+Максимум защиты при минимуме риска сломать рантайм. Дешёвые техники,
+дающие 80% результата, включаются по умолчанию; дорогие и опасные —
+включаются **только** после того, как для них есть верификатор. Каждая
+техника имеет измеримый критерий «сработала/не сработала», иначе это
+не защита, а мнение.
+
+## P0 — базовый уровень (дёшево, снимает главные утечки)
+
+| пункт | что это | пасс | статус |
+|---|---|---|---|
+| A1 | переименование **всех** символов: классы, поля, методы, локальные переменные, параметры, record-компоненты, enum-константы, `SourceFile` | Rename | ✅ готово |
+| A2 | вычистить `LineNumberTable`/`LocalVariableTable`/`SourceFile`/`InnerClasses`/`Signature`/`MethodParameters` | DebugInfo | план |
+| A3 | никаких сигнатурных имён у защитного кода, защитный код смешан с обычным | Rename + Noise | ✅ / план |
+| A4 | обфусцировать **весь** архив, включая ресурсы, mixin-JSON, access widener, service loader'ы | Resources | план |
+| — | маппинг в отчёт (иначе не читаем свои же stack trace) | Rename | ✅ готово |
+
+Это самый дешёвый блок и одновременно **самый большой утечка** в разобранном
+образце: оригинальные `SourceFile` у 160 классов, имена полей и методов,
+каталог модулей в атрибутах.
+
+## P1 — строки и константы
+
+| пункт | что это | пасс | статус |
+|---|---|---|---|
+| B1 | ключ на строку + ротация 3–5 схем + MAC + уникальный nonce | Strings | ✅ схемы готовы |
+| B2 | **вывод** ключа в рантайме, а не константа в вызове | Strings + генератор декодера | ⛔ блокер |
+| B3 | константы — не тождества, а вычисления, разнесённые по блокам | Constants | план |
+| B4 | **ложная** отладочная информация: чужие имена переменных и строк | DebugInfo | план |
+
+B2 — главное отличие от разобранного образца: у него ключ был константным
+выражением в вызове и расшифровывался статически, без JVM. Мастер-секрет
+должен собираться в рантайме из нескольких мест. Это требует сначала
+собрать класс-декодер (P2) — потому и блокер, а не «сделаем потом».
+
+## P2 — контрольный поток
+
+| пункт | что это | статус |
+|---|---|---|
+| C1 | **несколько схем** флаттенинга вместо одной, с мешаниной внутри метода | план |
+| C2 | верификатор обязателен: ошибка CFG = `VerifyError` | план |
+| C3 | реальный объём ≠ раздувание: бюджет на размер и время | план |
+
+Приоритет здесь строго подчинён: **C2 раньше C1**. Включать Flow без
+проверки кадров `StackMapTable` — это гарантированный битый jar.
+Подробности: [`../stack.md`](../stack.md) §3.
+
+## P3 — измеримость (метрики, без которых ничего не доказано)
+
+Обязательный блок, иначе фраза «обфускация есть» ничего не означает:
+
+1. **Утечки имён.** Список эталонных осмысленных идентификаторов;
+   если хоть один остался в `strings`/константах — тест падает.
+2. **Читаемость декомпилята.** Прогон JADX/CFR → доля распознанных структур
+   (try/catch, switch, циклы), доля классов с восстановленными именами.
+3. **Противник.** Минимальный скрипт-деобфускатор (свёртка констант,
+   regex-паттерны). Если он снимает больше порога — техника провалена.
+   **Красный список паттернов держим в репозитории.**
+4. **Семантика.** Эталонные программы до и после — 100% совпадение.
+5. **Бюджеты.** Размер ≤ N%, время исполнения ≤ M%, отдельно — бюджет
+   раскрытия строк (кэш, чтобы не платить на каждый вызов).
+6. **Стабильность между сборками.** Имена и схемы **меняются** от билда
+   к билду: у разобранного образца шифр был один на все версии — готовое
+   окно для обучения по частотам.
+
+Это блок `noxis-verify`: красные паттерны + `java -Xverify:all` +
+метрики. Единственное место, где «нам кажется защищённым» заменяется
+цифрой.
+
+## P4 — долгий горизонт (пока не делаем)
+
+| пункт | что это | почему не сразу |
+|---|---|---|
+| D1 | маленький VM/interpreter для ценных кусков | цена окупается только на ключевом коде |
+| D2 | split-function / раскрываемое по шагам тело | режет обычный профилировщик, сложная отладка |
+| D3 | мягкий анти-анализ в рантайме | требует своего нативного компонента |
+| D4 | честный anti-tamper, а не «зашейрь ключ» | целая инженерная задача, не пасс |
+| E | собственный нативный/Rust-цель вместо JVM | другой продукт, не наша цель |
+
+D1 — явно ограничен: включать только для действительно ценных функций,
+остальное оправдания не имеет. E — отдельный продукт; если он когда-нибудь
+понадобится, наш IR как раз делает его возможным (те же пассы, другой
+writer).
+
+## Что мы добавили сверх исходного плана
+
+1. **Структурный гейт при компиляции.** Лимиты «250 строк / 4 файла»
+   гоняются в `build.rs` — см. [`../README.md`](../README.md). Без этого
+   план P0–P3 превращается в один гигантский файл через месяц.
+2. **Собственный IR с метками.** Исходный план предполагал работу поверх
+   готового парсера. `Insn::Mark(Label)` убирает пересчёт смещений из
+   всех пассов — это меняет цену каждой техники, меняющей CFG.
+3. **Детерминированный PRNG с доменным разделением.** Без этого
+   пункт «стабильность между сборками» невозможно проверить тестом.
+4. **Keep как отдельный крейт (`noxis-analysis`), а не флаг CLI.**
+   Рефлексия, JNI, сериализация и entrypoint'ы — это анализ иерархии,
+   а не настройка, которую надо помнить руками.
+
+## Порядок выполнения
+
+Смотрите [`../../todo.md`](../../todo.md). Кратко:
+
+```text
+P0 DebugInfo + Resources      → снимает главные утечки, почти бесплатно
+P1 Strings (B2) + Constants   → ключ выводится, схемы ротируются
+P1 backend (ristretto) + frames
+P2 Flow (C1) после верификатора
+P3 метрики (F) и красные паттерны
+```
--- a/docs/learnings/reference.md
+++ b/docs/learnings/reference.md
@ -0,0 +1,150 @@
+# Референс: 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`](../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`](lessons.md).