docs: sync status with code, add AI-resistance research, restyle README
Documentation had drifted from the actual implementation: the noxis
(CLI) and noxis-verify crates were fully built and tested but every
doc called them "not started". Verified against the code (build +
test run) and corrected status across README.md, todo.md,
architecture.md, techniques.md and learnings/{lessons,priorities}.md.
Also:
- restyled README.md (badges, no em dashes, usage examples, dropped
the redundant "Принципы" section already covered elsewhere)
- added docs/learnings/ai-resistance.md: a sourced writeup of what
actually works against LLM-driven reverse engineering (Elastic
Security Labs' Opus 4.6 vs Tigress study, the Acoda paper) and what
of it applies to noxis, plus concrete todo.md §7 items
- noxis-structure-check: the 250-line/4-file gate was scanning
docs/**, which fought against writing documentation freely; it now
only scans crates/*/{src,tests,benches} and only counts .rs files
This commit is contained in:
parent
2674d7fc89
commit
c3b8d4dd62
9 changed files with 349 additions and 162 deletions
134
README.md
134
README.md
|
|
@ -1,34 +1,61 @@
|
|||
<div align="center">
|
||||
|
||||
# noxis
|
||||
|
||||
Обфускатор JVM/Java-байткода на Rust.
|
||||
|
||||
Читает JAR, переписывает классовые файлы и ресурсы, собирает обратно —
|
||||
детерминированно, с маппингами для stack trace и с проверкой, что выход
|
||||
действительно загружается настоящей JVM.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
Читает JAR, переписывает классовые файлы и ресурсы, собирает обратно: детерминированно,
|
||||
с маппингами для stack trace и с проверкой, что выход действительно загружается настоящей JVM.
|
||||
|
||||
## Статус
|
||||
|
||||
В работе. Ядро построено, часть техник реализована, часть — по плану.
|
||||
Ядро построено, большая часть техник реализована.
|
||||
|
||||
| блок | состояние |
|
||||
|---|---|
|
||||
| IR классовых файлов, метки вместо смещений | ✅ |
|
||||
| конфиг, детерминированный PRNG, маппинги, отчёт | ✅ |
|
||||
| анализ: иерархия, entrypoint'ы, keep-правила | ✅ |
|
||||
| переименование всех символов | ✅ |
|
||||
| схемы шифрования строк (salt, nonce, MAC) | ✅ |
|
||||
| JAR: чтение/запись, ресурсы, срез подписей | ✅ |
|
||||
| гейт структурных правил при компиляции | ✅ |
|
||||
| пассы: rename, resources, debug | ✅ |
|
||||
| spike backend'а `ristretto_classfile` | ✅ |
|
||||
| `format::parse`/`write` + кадры `StackMapTable` | ✅ |
|
||||
| пассы: strings, constants, noise (+ декодер v49) | ✅ |
|
||||
| пасс flow | 🚧 |
|
||||
| верификация и метрики | 🚧 |
|
||||
| CLI | 🚧 |
|
||||
| `format::parse`/`write` + кадры `StackMapTable` (backend `ristretto_classfile`) | ✅ |
|
||||
| пассы: rename, resources, strings, constants, noise, debug | ✅ |
|
||||
| верификация: red-паттерны, `java -Xverify:all`, метрики | ✅ |
|
||||
| CLI (`obfuscate` / `analyze` / `patterns`) | ✅ |
|
||||
| пасс flow (кадры готовы, схем флаттенинга пока нет) | 🚧 |
|
||||
|
||||
Подробности — [`docs/architecture.md`](docs/architecture.md),
|
||||
план — [`todo.md`](todo.md).
|
||||
Подробности в [`docs/architecture.md`](docs/architecture.md), план в [`todo.md`](todo.md).
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
```sh
|
||||
./scripts/check.sh # fmt + clippy -D warnings + тесты
|
||||
|
||||
# обфускация jar: конвейер, маппинги, JSON-отчёт
|
||||
cargo run -p noxis -- obfuscate input.jar -o output.jar --seed 42
|
||||
|
||||
# что внутри jar: классы, entrypoint'ы, keep-правила (без изменений)
|
||||
cargo run -p noxis -- analyze input.jar
|
||||
|
||||
# красный список паттернов: показать или прогнать по jar'у
|
||||
cargo run -p noxis -- patterns --list
|
||||
cargo run -p noxis -- patterns --input output.jar
|
||||
```
|
||||
|
||||
`obfuscate` по умолчанию включает все готовые пассы. Флаги `--no-rename`,
|
||||
`--no-strings`, `--no-constants`, `--no-noise`, `--no-resources`, `--no-debug-info`
|
||||
выключают их по отдельности. `--no-flow` честно падает с ошибкой: пасса пока нет.
|
||||
|
||||
Одно `cargo build` уже гоняет проверку структуры кода: `.rs`-файл длиннее
|
||||
250 строк или директория с больше чем 4 `.rs`-файлами ломают сборку.
|
||||
Документация (`docs/**`) под это правило не попадает. Правила в [`docs/README.md`](docs/README.md).
|
||||
|
||||
## Структура
|
||||
|
||||
|
|
@ -36,75 +63,56 @@
|
|||
noxis/
|
||||
├── Cargo.toml workspace, lints, release-профиль
|
||||
├── scripts/check.sh structure → fmt → clippy → test
|
||||
├── docs/ ← архитектура, техники, стек, уроки
|
||||
├── docs/ архитектура, техники, стек, уроки
|
||||
├── info/ исходный материал разбора (вне правил)
|
||||
└── crates/
|
||||
├── noxis-classfile/ IR + парсер/запись + StackMapTable
|
||||
├── noxis-core/ конфиг, seed, маппинги, контракт Pass
|
||||
├── noxis-analysis/ иерархия, entrypoint'ы, keep
|
||||
├── noxis-passes/ сами трансформации + конвейер
|
||||
├── noxis-runtime/ схемы шифрования, ABI декодера
|
||||
├── noxis-jar/ ZIP, ресурсы, срез подписей
|
||||
├── noxis-verify/ red-паттерны, java -Xverify (план)
|
||||
├── noxis/ CLI (план)
|
||||
├── noxis-classfile/ IR + парсер/запись + StackMapTable
|
||||
├── noxis-core/ конфиг, seed, маппинги, контракт Pass
|
||||
├── noxis-analysis/ иерархия, entrypoint'ы, keep
|
||||
├── noxis-passes/ сами трансформации + конвейер
|
||||
├── noxis-runtime/ схемы шифрования, ABI декодера
|
||||
├── noxis-jar/ ZIP, ресурсы, срез подписей
|
||||
├── noxis-verify/ red-паттерны, java -Xverify, метрики
|
||||
├── noxis/ CLI: obfuscate, analyze, patterns
|
||||
└── noxis-structure-check/ автогейт структуры
|
||||
```
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
```sh
|
||||
./scripts/check.sh # fmt + clippy -D warnings + тесты
|
||||
```
|
||||
|
||||
Одно `cargo build` уже гоняет проверку структуры проекта: если файл
|
||||
длиннее 250 строк или в директории больше 4 файлов, сборка падает.
|
||||
Правила — в [`docs/README.md`](docs/README.md).
|
||||
|
||||
## Документация
|
||||
|
||||
| документ | что внутри |
|
||||
|---|---|
|
||||
| [`docs/README.md`](docs/README.md) | индекс и структурные правила проекта |
|
||||
| [`docs/architecture.md`](docs/architecture.md) | слои, крейты, IR, конвейер |
|
||||
| [`docs/techniques.md`](docs/techniques.md) | как работает каждая техника: плюсы и минусы |
|
||||
| [`docs/techniques.md`](docs/techniques.md) | как работает каждая техника, плюсы и минусы |
|
||||
| [`docs/stack.md`](docs/stack.md) | почему свой IR, backend, `StackMapTable`, PRNG |
|
||||
| [`docs/learnings/lessons.md`](docs/learnings/lessons.md) | уроки разбора: чего делать нельзя |
|
||||
| [`docs/learnings/reference.md`](docs/learnings/reference.md) | разбор референсного обфускатора |
|
||||
| [`docs/learnings/priorities.md`](docs/learnings/priorities.md) | что улучшаем и в каком порядке |
|
||||
| [`docs/learnings/ai-resistance.md`](docs/learnings/ai-resistance.md) | новые техники (MBA, виртуализация) и устойчивость к LLM-анализу |
|
||||
|
||||
Исходный материал разбора — [`info/README.md`](info/README.md).
|
||||
|
||||
## Принципы
|
||||
|
||||
- **KISS / DRY / SOLID.** Файл — одна ответственность. Не больше 250 строк,
|
||||
не больше 4 файлов в директории.
|
||||
- **Детерминированность.** Один seed → байт-в-байт одинаковый артефакт.
|
||||
- **Ничего не ломаем.** Техника, которая может дать `VerifyError`,
|
||||
включается только после верификатора.
|
||||
- **Измеримо.** Защита без метрик — это мнение, а не свойство.
|
||||
Исходный материал разбора в [`info/README.md`](info/README.md).
|
||||
|
||||
## Лицензия
|
||||
|
||||
AGPL-3.0-only — см. [`LICENSE`](LICENSE).
|
||||
AGPL-3.0-only, см. [`LICENSE`](LICENSE).
|
||||
|
||||
Проект остаётся полностью открытым: его можно изучать, использовать
|
||||
(в том числе коммерчески) и изменять. Условие AGPL — любые производные
|
||||
работы, которые распространяются или доступны пользователям по сети,
|
||||
обязаны публиковаться под той же лицензией. Это защищает `noxis` от
|
||||
закрытых форков, которые перепродают его как готовый продукт.
|
||||
Проект остаётся полностью открытым: его можно изучать, использовать (в том числе
|
||||
коммерчески) и изменять. Условие AGPL: любые производные работы, которые
|
||||
распространяются или доступны пользователям по сети, обязаны публиковаться под
|
||||
той же лицензией. Это защищает `noxis` от закрытых форков, которые перепродают
|
||||
его как готовый продукт.
|
||||
|
||||
Сторонние зависимости и их лицензии — в [`NOTICE.md`](NOTICE.md).
|
||||
Сторонние зависимости и их лицензии в [`NOTICE.md`](NOTICE.md).
|
||||
|
||||
## Ответственное использование
|
||||
|
||||
`noxis` — инструмент двойного назначения. Он одинаково полезен для
|
||||
защиты собственного байткода и способен усложнять анализ вредоносного
|
||||
ПО. Лицензия это не регламентирует, но это норма сообщества проекта:
|
||||
`noxis` это инструмент двойного назначения, одинаково полезный для защиты
|
||||
собственного байткода и способен усложнять анализ вредоносного ПО. Лицензия
|
||||
это не регламентирует, но это норма сообщества проекта:
|
||||
|
||||
- используйте обфускацию, чтобы защищать **свой** код и код тех, кто
|
||||
вас об этом попросил;
|
||||
- не применяйте инструмент для упаковки вредоносов, обхода средств
|
||||
защиты и антивирусов или иной деятельности, запрещённой законом.
|
||||
- используйте обфускацию, чтобы защищать **свой** код и код тех, кто вас об этом попросил;
|
||||
- не применяйте инструмент для упаковки вредоносов, обхода средств защиты
|
||||
и антивирусов или иной деятельности, запрещённой законом.
|
||||
|
||||
Нарушение этих норм не влечёт юридических последствий по лицензии, но
|
||||
приведёт к отказу в поддержке и закрытию issue/PR в репозитории.
|
||||
Нарушение этих норм не влечёт юридических последствий по лицензии, но приведёт
|
||||
к отказу в поддержке и закрытию issue/PR в репозитории.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue