Momoko-Ayase/Senbei
1
1
Fork 0
mirror of https://github.com/Momoko-Ayase/Senbei.git synced 2026-09-19 03:57:59 -04:00
Code Issues Activity

Compare commits

base: Momoko-Ayase/Senbei:v1.2.0
Branches Tags
Momoko-Ayase/Senbei:main
Momoko-Ayase/Senbei:v1.3.1 Momoko-Ayase/Senbei:v1.3.0 Momoko-Ayase/Senbei:v1.2.0 Momoko-Ayase/Senbei:v1.1.0 Momoko-Ayase/Senbei:v1.0.1 Momoko-Ayase/Senbei:v1.0.0
..
compare: Momoko-Ayase/Senbei:d6224e639cee25d88d80e9f961912c91ef48ba54
Branches Tags
Momoko-Ayase/Senbei:main
Momoko-Ayase/Senbei:v1.3.1 Momoko-Ayase/Senbei:v1.3.0 Momoko-Ayase/Senbei:v1.2.0 Momoko-Ayase/Senbei:v1.1.0 Momoko-Ayase/Senbei:v1.0.1 Momoko-Ayase/Senbei:v1.0.0
14 Commits
v1.2.0 .. d6224e639c
Author SHA1 Message Date
Momoko-Ayase d6224e639c chore: bump version to 1.3.1 2026-09-10 20:58:44 +08:00
Momoko-Ayase 9b8024b132 fix(windows): re-arm neutralized TLS field relocations for PE32 DLLs 
The packer demotes the four base-relocation entries covering the TLS
directory's VA fields to IMAGE_REL_BASED_ABSOLUTE padding, because its
own loader fixes TLS up by hand. Restored verbatim, a DLL mapped off its
preferred base keeps stale VAs in its TLS directory and the OS loader
faults in LdrpAllocateTlsEntry while writing the TLS slot index through
the unrelocated AddressOfIndex (observed as a 0xc0000005 startup
failure).

Walk the restored BaseReloc blocks and promote those entries back to
IMAGE_REL_BASED_HIGHLOW, gated on is_dll so EXE output stays
byte-identical.
 2026-09-10 20:42:39 +08:00
Momoko-Ayase 512a627066 web: recognize Android targets and point users at the CLI 
Dropping an .apk/.apks/.xapk package or a .so library reported
"not recognized — will be skipped", which reads as "not protected"
when the real gap is that the Android pipeline (filesystem
orchestration in senbei-io) has no wasm build. These files now get an
explicit android pseudo-kind at staging time: the row explains that
the CLI handles them, and they neither enable the Unpack button nor
error out mid-run.
 2026-09-10 09:32:58 +08:00
Momoko-Ayase a230c37281 web: stack file-row status below the name on narrow screens 
On phone-width viewports the right-aligned status column shared a flex
line with a long file name and wrapped one word per line. Below 560px
the row now wraps: name and action icons keep the first line and the
status takes a full-width line underneath.
 2026-09-10 09:29:23 +08:00
Momoko-Ayase 4f59e25652 ci: declare rustfmt/clippy components in rust-toolchain.toml 
The 1.98.1 pin installs without rustfmt and clippy, so the fmt and
clippy jobs fail at the shim before running. Listing the components in
the toolchain file makes rustup auto-install them on every host,
including the CI runners that invoke cargo with no setup action.
 2026-09-10 09:28:50 +08:00
bfloat16 f862633512 chore: bump version to 1.3.0 2026-09-07 22:59:25 +08:00
bfloat16 ed2731f8e0 fix(windows): restore managed companion DLLs 2026-09-07 21:43:54 +08:00
bfloat16 53ef36c837 build: require Rust 1.98.1 2026-09-07 21:43:15 +08:00
bfloat16 6250ca4e98 refactor: align platform crate boundaries 2026-09-07 19:29:54 +08:00
bfloat16 aa1bcaa2eb fix(android): support compact ELF dynamic table layouts 2026-09-07 16:31:38 +08:00
bfloat16 2d92360d87 fix(elf): validate section names from ELF string table 2026-09-07 13:23:16 +08:00
bfloat16 4d73406ab1 fix(metadata): support Android v29 method layouts 2026-09-07 00:43:34 +08:00
bfloat16 776d246065 fix(scan): stream Android package targets 2026-09-06 22:25:41 +08:00
bfloat16 d436a200ba refactor: consolidate platform engines into senbei-engine 2026-09-06 19:31:19 +08:00
82 changed files with 3682 additions and 2526 deletions
Expand all files Collapse all files
AGENTS.md
+20 -78
View File
@@ -1,98 +1,40 @@
# AGENTS.md
Guidance for AI coding agents (and human contributors) working in this repo.
Guidance for contributors working in this repository.
## Project
Senbei is a static unpacker for Crackproof-protected PE files and protected
Android (AArch64) shared libraries: a Cargo workspace with a pure, panic-free,
no-I/O PE unpacker core (`senbei-pe/`, built on `senbei-crypto/`), il2cpp
metadata de-obfuscators (`senbei-metadata/` for the Windows structural
variant, `senbei-android-metadata/` for the Android seeded-permutation and
embedded-blob variants), the native-only Android pipeline
(`senbei-android-crypto/`, `senbei-android-engine/`, `senbei-android-elf/`),
filesystem/CLI orchestration (`senbei-io/`, including the Android
single-library/package glue in `senbei-io/src/android.rs`), the `senbei`
binary (`senbei-cli/`), WebAssembly bindings (`senbei-wasm/`, outside the
workspace; builds into `web/pkg/`), and the static browser frontend assets
(`web/`). Read `docs/design.md` first.
Senbei is a static unpacker for protected PE files and Android AArch64 shared libraries. The workspace contains `senbei-cli`, `senbei-crypto`, `senbei-elf`, `senbei-engine`, `senbei-io`, `senbei-metadata`, and `senbei-pe`; `senbei-wasm` is a separate crate for the browser frontend.
Read `docs/design.md` before changing architecture or pipeline boundaries.
## Commands
```cmd
cargo build --release :: CLI (default member: senbei-cli)
cargo test --release --workspace :: full suite (golden corpus: samples/, git-ignored)
cargo build --release
cargo test --release --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all
cd senbei-wasm && wasm-pack build --target web --release --out-dir ../web/pkg :: browser build
cd senbei-wasm && wasm-pack build --target web --release --out-dir ../web/pkg
```
The `samples/` corpus is user-managed and absent on CI; without it the
samples test is a no-op pass. `SENBEI_REQUIRE_SAMPLES=1` makes an absent
corpus fail (use this on a private CI that *does* have the corpus). The
Android corpus lives in `samples/android/` (one extracted app tree per
subdirectory) and is covered by `tests/android_samples.rs`;
`SENBEI_ANDROID_SAMPLES` overrides that location. Do not
delete `samples/` with `rm -rf` — it may be a junction; use git
worktree-aware cleanup.
The optional `samples/` corpus is user-managed and ignored by Git. The Android corpus is under `samples/android/` when present. Do not delete sample directories as part of routine cleanup.
## Hard rules
## Crate Boundaries
- **The PE unpacker core stays pure**: `senbei-pe` and `senbei-crypto` have no
file I/O, no `unsafe`, no panics across the public boundary, no
platform-specific code. Everything `senbei-wasm` compiles must keep building
for `wasm32-unknown-unknown` (`cargo check --target wasm32-unknown-unknown`
at the workspace root covers it — the Android crates do compile to wasm, but
nothing on the wasm path calls them).
- **The Android crates are native-only orchestration-style crates**:
`senbei-android-engine`/`senbei-android-elf` memory-map inputs and write a
module workspace to disk (the restore is a two-phase design consuming that
workspace). Keep them off the web app's code paths; `senbei-io`'s
`android.rs` is the only caller the CLI uses.
- **`catch_unwind` does not work on wasm** (the prebuilt std can't unwind; a
caught panic becomes a fatal `unreachable` trap). Native code may rely on
`catch_unpack`, but any routing decision must also work without a catchable
panic: spliced companion inputs route straight to the EXE pipeline, and the
web app isolates every unpack in a disposable Web Worker, retrying trapped
DLLs with `job::unpack_bytes_force_exe`. Never make correctness on wasm
depend on catching a panic.
- **Byte-identical output is the contract.** Any pipeline change must re-run
the full golden corpus; a byte mismatch on any golden is a regression.
- **Trial-and-validate, never trust a heuristic.** A silently wrong offset
produces a silently broken binary — worse than an error. Every layout
candidate must be validated (checksum / structural oracle) with fall-through
to the next candidate.
- **Determinism under parallelism.** Block fan-out must stay byte-identical
regardless of thread count (`SENBEI_THREADS=1` is the sequential reference).
- **Folder scanning: deny-list, never allow-list.** Targets are recognised by
content, not extension, and can carry arbitrary names — there is no closed
set of target extensions an allow-list could enumerate. Only known
bulk-asset formats are excluded.
- **No binaries in the repo** — not as fixtures, not in commits. The only
corpus is the local git-ignored `samples/`. (Issue attachments of
protected inputs are fine when the user is authorized to share them, but
never commit them.)
`senbei-pe` and `senbei-elf` contain format parsing, address mapping, and ELF dynamic-table helpers only. `senbei-engine/src/windows/` contains the PE unpacking pipeline; `senbei-engine/src/android/` contains Android extraction and ELF restoration. `senbei-crypto/src/windows/` and `senbei-crypto/src/android/` contain platform-specific primitives; seeded Android metadata code is under `senbei-metadata/src/android/`, while the structural metadata transform is shared at the metadata crate root. Shared source stays directly under `src/`.
## Public-repo hygiene (important)
The format crates and PE engine remain free of filesystem I/O. Native Android extraction and restoration may memory-map inputs and write temporary workspaces. The browser binding must continue to compile for `wasm32-unknown-unknown`.
This is a public research repository. In code comments, docs, tests, and
commit messages:
## Hard Rules
- **Never name specific games, publishers, or product codenames.** Refer to
build families generically ("older EXE-64 builds", "the marker-less
layout", "external-companion builds"). Keep offsets/numbers — drop names.
- **Never name specific protected filenames** from real distributions. Test
fixtures use generic names (`app.exe`, `managed.dll`, `daemon.exe`).
Exceptions (platform-standard technology names, allowed): `il2cpp`,
`Unity`, `global-metadata.dat`, the Crackproof magic `KONN`.
- **Never reference other tools, projects, implementations, or paths outside
this repo.** Describe behavior and layout directly; do not mention prior
art, porting, or where any algorithm came from.
- Outputs must be byte-identical to the available golden corpus.
- Layout heuristics must trial and validate every candidate before accepting it.
- Deterministic parallel and sequential paths must produce identical bytes.
- Folder scanning must not open bulk assets. Windows candidates are `.exe`, `.dll`, and `global-metadata.dat`; Android candidates are `.so` and `global-metadata.dat`. Matching `.exe._` and `.dll._` files are auxiliary payloads and are not counted as skipped targets.
- APK, APKS, and XAPK processing must inspect manifests first and extract only `.so` and `global-metadata.dat` entries.
- Do not commit protected or restored binaries. Use generic fixture names and do not add product-specific names or external tool references to public code, docs, tests, or commit messages.
## Conventions
## Documentation
- Comments explain *why* (layout rationale, observed variants, failure modes),
not *what*.
- Rust 2024 edition; clippy-clean at `-D warnings`; rustfmt default style.
- CLI behavior (flags, exit codes, output naming) is documented in
`docs/usage.md` — update the doc when changing behavior.
Use one line for each normal Markdown paragraph. Keep code blocks, table rows, and list items structurally separate. Update `docs/usage.md` when CLI behavior changes.
Cargo.lock
Generated
+38 -71
View File
@@ -2,12 +2,6 @@
# It is not intended for manual editing.
version = 4
[[package]]
name = "adler2"
version = "2.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
[[package]]
name = "aes"
version = "0.9.3"
@@ -158,8 +152,6 @@ version = "1.1.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
dependencies = [
"crc32fast",
"miniz_oxide",
"zlib-rs",
]
@@ -306,16 +298,6 @@ dependencies = [
"libc",
]
[[package]]
name = "miniz_oxide"
version = "0.9.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c"
dependencies = [
"adler2",
"simd-adler32",
]
[[package]]
name = "once_cell"
version = "1.21.4"
@@ -418,53 +400,11 @@ dependencies = [
"syn 3.0.4",
]
[[package]]
name = "senbei-android-crypto"
version = "1.2.0"
dependencies = [
"aes",
"thiserror",
]
[[package]]
name = "senbei-android-elf"
version = "1.2.0"
dependencies = [
"memmap2",
"senbei-android-crypto",
"serde",
"serde_json",
"sha2",
"tempfile",
"thiserror",
]
[[package]]
name = "senbei-android-engine"
version = "1.2.0"
dependencies = [
"goblin",
"memmap2",
"senbei-android-crypto",
"serde",
"serde_json",
"sha2",
"tempfile",
"thiserror",
]
[[package]]
name = "senbei-android-metadata"
version = "1.2.0"
dependencies = [
"serde",
"thiserror",
]
[[package]]
name = "senbei-cli"
version = "1.2.0"
version = "1.3.1"
dependencies = [
"senbei-engine",
"senbei-io",
"senbei-metadata",
"sha2",
@@ -473,23 +413,47 @@ dependencies = [
[[package]]
name = "senbei-crypto"
version = "1.2.0"
version = "1.3.1"
dependencies = [
"aes",
"thiserror",
]
[[package]]
name = "senbei-elf"
version = "1.3.1"
dependencies = [
"goblin",
"thiserror",
]
[[package]]
name = "senbei-engine"
version = "1.3.1"
dependencies = [
"memmap2",
"senbei-crypto",
"senbei-elf",
"senbei-pe",
"serde",
"serde_json",
"sha2",
"tempfile",
"thiserror",
]
[[package]]
name = "senbei-io"
version = "1.2.0"
version = "1.3.1"
dependencies = [
"anyhow",
"flate2",
"indicatif",
"libc",
"memmap2",
"owo-colors",
"senbei-android-elf",
"senbei-android-engine",
"senbei-android-metadata",
"senbei-crypto",
"senbei-elf",
"senbei-engine",
"senbei-metadata",
"senbei-pe",
"sha2",
@@ -501,13 +465,16 @@ dependencies = [
[[package]]
name = "senbei-metadata"
version = "1.2.0"
version = "1.3.1"
dependencies = [
"serde",
"thiserror",
]
[[package]]
name = "senbei-pe"
version = "1.2.0"
version = "1.3.1"
dependencies = [
"senbei-crypto",
"thiserror",
]
Cargo.toml
+6 -11
View File
@@ -1,11 +1,9 @@
[workspace]
members = [
"senbei-android-crypto",
"senbei-android-elf",
"senbei-android-engine",
"senbei-android-metadata",
"senbei-cli",
"senbei-crypto",
"senbei-elf",
"senbei-engine",
"senbei-io",
"senbei-metadata",
"senbei-pe",
@@ -17,15 +15,14 @@ exclude = ["senbei-wasm"]
resolver = "2"
[workspace.package]
version = "1.2.0"
version = "1.3.1"
edition = "2024"
rust-version = "1.85"
rust-version = "1.98.1"
license = "AGPL-3.0-only"
[workspace.dependencies]
aes = "0.9"
anyhow = "1"
flate2 = "1"
goblin = "0.10"
indicatif = "0.18"
libc = "0.2"
@@ -43,11 +40,9 @@ windows = { version = "0.62", features = [
"Win32_System_SystemInformation",
] }
zip = { version = "8", default-features = false, features = ["deflate"] }
senbei-android-crypto = { path = "senbei-android-crypto" }
senbei-android-elf = { path = "senbei-android-elf" }
senbei-android-engine = { path = "senbei-android-engine" }
senbei-android-metadata = { path = "senbei-android-metadata" }
senbei-crypto = { path = "senbei-crypto" }
senbei-elf = { path = "senbei-elf" }
senbei-engine = { path = "senbei-engine" }
senbei-io = { path = "senbei-io" }
senbei-metadata = { path = "senbei-metadata" }
senbei-pe = { path = "senbei-pe" }
README.md
+33 -66
View File
@@ -1,89 +1,56 @@
# Senbei
A static unpacker for Crackproof-protected 64-bit and 32-bit PE files and
protected Android (AArch64) shared libraries. Point it at a file, an app
package, or a folder and it writes decrypted copies — no launch of the
protected program, no kernel driver, no code runs out of the protected binary.
A static unpacker for Crackproof-protected 64-bit and 32-bit PE files and protected Android AArch64 shared libraries. Point it at a file, an app package, or a folder and it writes decrypted copies without launching the protected program.
> _"Crackproof"? It's senbei (煎餅 — rice cracker). Cracks itself._
Senbei reads protected input bytes and replays the unpacking algorithm statically. The command-line tool adds filesystem scanning, progress reporting, and logs; `senbei-wasm` provides the browser binding.
Senbei reads a protected `.exe` or `.dll`, replays the unpacking algorithm
entirely in memory, and writes the recovered image to a new file. The core is a
pure, panic-free library with no file I/O; the CLI wraps it with scanning, a
progress bar, and a run log. A browser version (WebAssembly, fully client-side)
lives in [`web/`](web/).
## Crates
## Legal notice and intended use
The workspace contains eight crates: `senbei-cli`, `senbei-crypto`, `senbei-io`, `senbei-metadata`, `senbei-pe`, `senbei-elf`, `senbei-engine`, and `senbei-wasm`.
**Read this before using Senbei.**
`senbei-pe` and `senbei-elf` contain validated format parsing, address mapping, and ELF dynamic-table helpers. Protection-specific code is in `senbei-engine/src/windows/` and `senbei-engine/src/android/`. Platform-specific crypto is grouped under `senbei-crypto/src/windows/` and `senbei-crypto/src/android/`; metadata code shared by both platforms stays at the `senbei-metadata` root, with seeded Android code under `src/android/`.
- Senbei is a research and interoperability tool. It exists to enable lawful
reverse engineering, security research, preservation, and interoperability
with software you already legitimately possess.
- **Only process binaries you own or are explicitly authorized to analyze.**
Depending on your jurisdiction and license agreements, circumventing
technological protection measures may be restricted (for example under
DMCA §1201 in the United States, which contains exemptions for security
research and interoperability). It is your responsibility to ensure your use
is lawful.
- Senbei does not bypass any access control for you: it performs a purely
static transformation of a file already on your disk. It derives everything
it needs from the input file itself, contains no vendor code, and
distributes no cracks or copyrighted content. (One Android packaging
variant's embedded metadata layer is unwrapped with an XOR keystream
recovered from a ciphertext/plaintext pair during analysis of a single
build; that keystream is research output shipped with the unpacker, not a
vendor-distributed key, and builds it doesn't match are left alone.)
- Senbei does not enable online play, license fraud, or cheating, and must not
be used to redistribute decrypted binaries. Do not upload outputs anywhere.
- The authors provide this software "as is", without warranty of any kind, and
accept no liability for misuse. See [LICENSE](LICENSE) (AGPL-3.0).
- "Crackproof" is a trademark of its respective owner; this project is not
affiliated with or endorsed by the protection vendor or any software
publisher. Names are used for identification only.
## Supported Inputs
## What it handles
- Protected Windows `.exe` and `.dll` files, including external `<name>.exe._` and `<name>.dll._` payloads.
- `global-metadata.dat` files with supported method-token layouts.
- Protected Android `.so` files and Android `.apk`, `.apks`, and `.xapk` packages.
| Kind | Description |
| --- | --- |
| `NativeExe` | Crackproof-protected native executable (PE32+ and PE32). |
| `ManagedExe` | Protected .NET executable (has a CLR data directory). |
| `NativeDll` | Protected native (unmanaged) DLL. |
| `ManagedDll` | Protected .NET assembly (has a CLR data directory). |
| `._` companion | Stub + external encrypted payload layout, spliced automatically. |
| `global-metadata.dat` | il2cpp metadata with obfuscated method tokens, de-obfuscated in place. |
| Android `.so` | Protected AArch64 shared library, statically restored (hollowed sections + stripped dynamic tables rebuilt). |
| `.apk` / `.apks` / `.xapk` | App packages; protected entries inside are restored, preserving the package's internal layout. |
Windows scanning probes only `.exe`, `.dll`, and `global-metadata.dat`; companion payloads are consumed through their matching stub and are not counted as skipped files. Android scanning probes only `.so` and `global-metadata.dat`. Android packages are inspected from their ZIP manifests and only matching `.so` and metadata entries are extracted.
Detection is content-based (header key-table at offset 4096, magic `KONN`),
not extension-based — app packages are the one exception, recognised by
extension plus the zip magic because they are containers. Anything
unrecognized is left untouched.
## Quick start
## Quick Start
```cmd
cargo build --release
senbei protected.exe
:: -> unpack\protected.unpack.exe
senbei game.apk
:: -> unpack\game.apk\lib\arm64-v8a\libil2cpp.unpack.so
senbei "C:\Games\MyGame"
:: -> C:\Games\MyGame\unpack\... (recursive, skips non-targets)
```
Every output is sanity-checked statically; structurally broken results are
flagged as suspect rather than silently trusted.
Outputs are written below an `unpack` directory unless `--out` is supplied. Every restored PE or ELF image passes a structural validation step before it is reported as successful.
## Documentation
## Tests
- [Usage reference](docs/usage.md) — CLI flags, exit codes, integrity check
- [Design](docs/design.md) — architecture, routing, and error model
- [Development](docs/development.md) — building, testing, environment variables
- [Web version](web/README.md) — run Senbei in a browser
```cmd
cargo test --release --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check
```
The local `test/` corpus can be passed to the CLI for real sample verification. The tracked `samples/` corpus is optional and remains user-managed.
## Web Build
```cmd
cd senbei-wasm
wasm-pack build --target web --release --out-dir ../web/pkg
```
The generated package is written to the ignored `web/pkg/` directory and can be served with any static HTTP server.
## Legal Notice
Use Senbei only for software you own or are authorized to analyze. The project is intended for lawful reverse engineering, security research, preservation, and interoperability.
## License
docs/design.md
+35 -214
View File
@@ -1,238 +1,59 @@
# Design
Senbei is a fully static unpacker: it replays the unpacking algorithm on the
file bytes in memory and writes the recovered PE image. No code from the
protected binary is ever executed, no process is launched or attached to, and
no driver or proxy DLL is involved.
Senbei is a fully static unpacker. It reads protected bytes, replays the protection algorithm, validates the result, and writes a recovered image without launching or attaching to the protected program.
## Crate layout
## Crate Layout
Senbei is a Cargo workspace split into a pure core and thin shells around it:
The workspace is organized into eight crates. `senbei-cli` is the command-line entry point, `senbei-io` owns filesystem orchestration, `senbei-wasm` provides browser bindings, `senbei-pe` and `senbei-elf` provide basic format parsing, `senbei-crypto` provides shared primitives, `senbei-metadata` restores metadata, and `senbei-engine` owns protection-specific pipelines.
- **`senbei-pe/`** — the core. Pure functions over byte slices: no file I/O,
no environment access (beyond a few debugging overrides, see
[development.md](development.md)), panic-free at the public boundary (all
internal panics are trapped and converted to `UnpackError::Corrupt`). This
is what the WebAssembly build embeds.
- **`senbei-crypto/`** — cryptographic, checksum, compression, and bytecode
primitives the core is built from. Same purity rules as `senbei-pe`.
- **`senbei-metadata/`** — il2cpp `global-metadata.dat` method-token
de-obfuscation (format version 31; other versions are left untouched).
- **`senbei-android-crypto/`** — container primitives of the Android
(AArch64) protection scheme: the word/record ciphers, the GF(2³²)
transform, the AES-augmented segment transform, and the Huffman/LZ decoder.
- **`senbei-android-engine/`** — stage-1/stage-2 extraction: finds the
appended payload section, decrypts the stage-1 header and stage-2 payload,
and walks the recursive record streams to decode every module. Native-only
(memory-maps the input, writes the module set to a workspace directory).
- **`senbei-android-elf/`** — the restore: replays the decoded target-image
and fixup containers onto a hollowed ELF and rebuilds the dynamic-linker
tables (hash tables, symbols, relocations) the protector stripped.
Native-only.
- **`senbei-android-metadata/`** — the Android metadata variants: the seeded
five-round MethodDef-RID permutation restore (v31), seed discovery, and the
embedded-metadata XOR unwrap (`keystream.rs`).
- **`senbei-io/`** — filesystem and orchestration: recursive folder scanning,
per-run log file, progress bar, Explorer-friendly exit pause, the
single-file/folder orchestration in `job.rs` (incl. the wasm-safe in-memory
byte API used by the web frontend), and `android.rs` — the Android
single-library / folder / app-package orchestration.
- **`senbei-cli/`** — the `senbei` binary: argument parsing + dispatch. The
integration test suite (incl. the golden corpus test) lives in
`senbei-cli/tests/`.
Single-platform source stays directly under `src/`. Multi-platform crates keep platform code below `src/windows/` and `src/android/`, with shared code directly below `src/`.
```
senbei-cli/
└── src/main.rs argument parsing + dispatch
senbei-io/src/
├── job.rs single-file + folder orchestration, out-naming,
│ companion splice, stub overlay/TLS restore,
│ pipeline routing (incl. the wasm-safe byte API)
├── android.rs Android single-library / folder / package
│ orchestration, cross-source dedup
├── scan.rs recursive target discovery (PE + metadata + Android)
├── logfile.rs per-run timestamped log
├── ui.rs progress bar + status lines
└── pause.rs Explorer-friendly exit pause
senbei-metadata/src/
└── metadata.rs il2cpp global-metadata.dat de-obfuscation
```text
senbei-cli/src/main.rs
senbei-crypto/src/
├── primitives.rs decrypt_data* steps, key derivation
├── bytecode.rs bytecode VM
├── tables.rs constant tables
└── crc32.rs checksum
senbei-pe/src/engine/ pure, panic-free, no-I/O core
├── mod.rs detection + unpack_auto dispatch
├── error.rs structured error taxonomy
├── integrity.rs static post-unpack sanity check
├── parallel.rs deterministic block-parallel fan-out
├── layout/ layout discovery + validation
│ ├── dd8.rs .text dd8 key-formula + shift selection
│ ├── discovery.rs layout candidate discovery (trial-and-validate)
│ └── image.rs PE image reconstruction helpers
├── exe/
│ ├── pipeline.rs EXE pipeline (PE32+ and PE32 orchestration)
│ └── pipeline/pe32.rs PE32-specific EXE restore
└── dll/
└── pipeline.rs native + managed DLL pipeline
senbei-android-crypto/src/
└── protector.rs container ciphers, GF(2^32), Huffman/LZ decoder
senbei-android-engine/src/
├── stage1.rs payload-section discovery + stage-1 header/payload
├── stream.rs record-stream parsing
├── extract.rs recursive module extraction (writes the workspace)
├── probe.rs protected-library content probe
└── report.rs machine-readable extraction report
senbei-android-elf/src/
├── restore.rs image restore + dynamic-table rebuild
├── layout.rs ELF layout parsing
├── artifact.rs module-workspace index loading
└── hash.rs SysV/GNU hash table rebuild
senbei-android-metadata/src/
├── method_tokens.rs seeded RID permutation restore + seed discovery
├── embedded.rs embedded-metadata blob locate + XOR unwrap
└── keystream.rs recovered keystream table (one observed build)
senbei-crypto/src/android/
senbei-crypto/src/windows/
senbei-elf/src/
senbei-engine/src/windows/
senbei-engine/src/android/
senbei-io/src/
senbei-io/src/android/
senbei-io/src/windows/
senbei-metadata/src/
senbei-metadata/src/windows/
senbei-metadata/src/android/
senbei-pe/src/
senbei-wasm/src/
```
## Detection and routing
`senbei-pe` and `senbei-elf` own validated format models, address mapping, and ELF dynamic hash helpers. They do not depend on the unpacking engines, filesystem code, or platform protection logic.
Detection is content-based (`unpacker::detect`), never extension-based: the
key table is derived from the file header and checked against the format
magic, then the PE characteristics classify the input as EXE or DLL and the
CLR data directory splits each into native vs managed (`NativeExe` /
`ManagedExe` / `NativeDll` / `ManagedDll`). The folder scan additionally
classifies Android targets: an ELF64/AArch64 prefix promotes the file to a
full protection probe (`senbei_android_engine::is_protected_libil2cpp`), and a
package extension plus zip magic marks an app package for container
extraction.
## Windows Engine
`unpack_auto` then dispatches:
`senbei-engine/src/windows/` contains PE detection, layout discovery, EXE and DLL restoration, deterministic block parallelism, and structural integrity checks. Candidate layouts are trial-decrypted and validated before an output is accepted.
- `NativeExe` / `ManagedExe` → the EXE pipeline (handles both PE32+ and
PE32). Managed EXEs take the same path: their import-string table is null
(imports are the CLR bootstrap stub), the entry point comes from the
protected header (the config block stores 0 for managed images), and the
COR20 header, BSJB metadata stream, and CLR resources are restored verbatim
from the protected file, mirroring the managed-DLL restore.
- `NativeDll` / `ManagedDll` → the DLL pipeline first; on failure, the EXE
pipeline as a fallback. Two DLL layouts exist in the wild: an older layout
the DLL pipeline parses, and a newer one that protects DLLs with the
EXE-style shell layout instead. The DLL-first order keeps old-layout outputs
byte-identical (the EXE pipeline also "succeeds" on old-layout DLLs but
produces different bytes); the fallback handles the new layout (including
the managed-DLL .NET metadata restore).
External companion inputs are reconstructed as `stub[..4096]` followed by the matching `._` payload. The stub's export, TLS, and declared CLR regions are overlaid after unpacking because those regions are not present in the encrypted companion. Managed restoration follows the COR20 directory and referenced metadata, resources, and vtable fixups through each file's RVA mapping, preserving the decrypted method bodies.
One routing shortcut bypasses `unpack_auto`: inputs spliced from an external
companion (`job.rs`, both the CLI and the wasm byte API) go **straight to the
EXE pipeline**. The companion layout is definitionally the EXE-style shell,
so the DLL probe can never be right for it — and the probe's rejection of
EXE-shell DLLs relies on a caught panic, which is a fatal trap on targets
without unwinding (WebAssembly). Output bytes are identical to the
probe-then-fallback route.
## Android Engine
## External-companion inputs
`senbei-engine/src/android/extract/` decrypts the stage-1 header and stage-2 record streams and writes a temporary module workspace. `senbei-engine/src/android/restore/` applies decoded image and fixup containers to the hollowed ELF and rebuilds dynamic-linker tables. Both phases validate bounds and table placement before writing output.
Some builds split a protected module into an on-disk loader stub plus an
encrypted `._` companion. When a `<name>._` sibling matches the stub's header
region, `job.rs` splices the two before unpacking and afterwards overlays the
export table and TLS directory from the stub — pieces the encrypted companion
does not carry. All overlay steps are best-effort no-ops when their inputs
can't be mapped, so a malformed stub can never corrupt an otherwise-good
unpack.
Windows protection primitives are in `senbei-crypto/src/windows/`, while Android protection primitives are in `senbei-crypto/src/android/`. Android seeded metadata restoration is in `senbei-metadata/src/android/`; the structural MethodDef transform is shared at the metadata crate root because both platform paths use it.
## Pipelines
Android ELF dynamic tables are located from the input section table and its actual file ranges. When the original gap is too small, restoration adds a validated read-only `PT_LOAD` after the existing load image and updates the dynamic tags; it never overwrites an adjacent section or emits a partial image.
Both pipelines are **heuristic with trial-and-validate**: where a layout
leaves ambiguity (e.g. which block is the real file decryptor, or a page-XOR
shift), the pipeline tries candidates and validates the result structurally
(an entry-stub oracle, checksum stamps, cluster stamps) instead of trusting
the first match. A validation failure falls through to the next candidate
rather than producing silently wrong output.
## Scanning and Packages
Several protected stages are themselves little bytecode programs. The core
includes a small VM (`bytecode.rs`) that generates and interprets those
programs rather than hardcoding each variant's constants.
Folder scanning uses platform target names to avoid opening bulk assets: Windows candidates are `.exe`, `.dll`, and `global-metadata.dat`; Android candidates are `.so` and `global-metadata.dat`. The shared walker is in `senbei-io/src/scan.rs`; platform name filters and PE companion byte adaptation are in `senbei-io/src/windows/`, and Android package adaptation is in `senbei-io/src/android/`. A Windows `.exe._` or `.dll._` companion is auxiliary input for its sibling stub and is excluded from the skipped count.
## The Android pipeline
APK, APKS, and XAPK files are containers. Senbei reads their ZIP manifests first, follows nested APK entries when necessary, and extracts only `.so` and exact `global-metadata.dat` entries. Extraction streams directly to temporary files, so compressed and decompressed copies are not held in memory together.
The Android scheme hollows an ELF64/AArch64 shared object: section bodies are
zeroed in the file and the original bytes move into an encrypted payload
appended as a `SHT_LOUSER` section (invisible to the dynamic loader). Restore
is two-phase:
## Validation
1. **Extract** (`senbei-android-engine`): decrypt the stage-1 parameter block
and stage-2 payload from the payload section, then walk the recursive
record streams — each decoded module may interpret a further nested stream
— into a temporary module workspace with a JSON index.
2. **Restore** (`senbei-android-elf`): decode the target-image container onto
a copy of the hollowed file, apply the compact fixup database (the
relocations stripped from `.rela.dyn`), and rebuild the dynamic-linker
tables the loader needs (SysV/GNU hash, symbol and string tables,
`.rela.dyn`/`.rela.plt`). Validation is structural and total: mismatched
container sizes, descriptor bounds, or a rebuilt table overhanging its
section fail the restore rather than emit a broken image.
Every heuristic layout uses trial-and-validate. A candidate that fails structural checks, checksums, or table bounds is rejected and the next candidate is tried. A failed restore is reported as an error rather than emitting a silently damaged binary.
il2cpp metadata comes in three shapes, all routed through
`job::deobfuscate_metadata_to` / `android::restore_metadata_bytes`:
The PE integrity check verifies headers, section ranges, entry-point mapping, import names, relocation requirements, and managed metadata signatures. Android restoration validates ELF ranges, decoded container sizes, fixup bounds, and rebuilt dynamic tables.
- **structural (Windows `-GMD`)**: sparse method tokens remapped to the
contiguous per-module range, keyless, idempotent (`senbei-metadata`).
- **seeded permutation (Android v31)**: MethodDef RIDs permuted by a keyed
five-round transform; the seed is recovered by intersecting per-image key
residues, and the restore validates every RID — a wrong seed errors and the
structural remap takes over (`senbei-android-metadata`).
- **embedded blob**: no metadata file in the app at all; a slim blob sits in
the library's data section under a per-word XOR layer. After a restore the
blob is located by content (two known plaintext header words against the
embedded keystream) and unwrapped to a standalone `global-metadata.dat`.
Key derivation is untraced — the shipped keystream covers the one observed
build, and other builds simply never match the probe.
## WebAssembly
Packages (`.apk`/`.apks`/`.xapk`) are containers, not targets: entries are
extracted to a temporary workspace and content-probed like loose files.
Cross-source duplicates (a library loose in the tree *and* inside its
package) are restored once, preferring the loose file, then the `.apk`, then
bundle splits.
## Integrity check
Every produced image passes through `integrity::check` — a static, execution-
free sanity check that only flags defects impossible in a correctly unpacked
image (malformed headers, unmapped/non-executable/all-zero/all-int3 entry
point, a native DLL with no base-relocation directory, any import descriptor
whose DLL name is still ciphertext, a managed image whose COR20 header or BSJB
metadata did not survive). See [usage.md](usage.md#integrity-check).
A clean report is not a proof of correctness; a non-clean report is a reliable
"broken" signal.
## Parallelism
Section decrypt/decompress blocks write disjoint output spans and read only
immutable input plus snapshotted key tables, so `parallel.rs` fans them out
across worker threads with **byte-identical** output regardless of thread
count. There is no `unsafe`: the buffer is carved with safe `split_at_mut`
chains so the borrow checker proves spans never alias. Overlapping spans (only
possible on corrupt input) degrade to the sequential whole-buffer pass,
preserving the deterministic last-writer-wins behavior of the serial
pipeline. `SENBEI_THREADS=1` forces the sequential path; on targets without
threads (WebAssembly) the sequential path is used automatically.
## Error model
The public API never panics: every pipeline runs under a `catch_unwind`
wrapper (`catch_unpack`) that converts a trapped panic to
`UnpackError::Corrupt`, with the default panic hook transiently suppressed.
Size requests are bounds-checked against a 1 GiB `MAX_IMAGE_SIZE` before
allocation so a crafted header cannot abort the process with a huge
allocation. In folder mode each file is isolated: one file's failure is logged
and counted, never fatal to the run.
**WebAssembly caveat:** the prebuilt wasm std cannot unwind, so a caught
panic becomes a fatal `unreachable` trap there. The DLL-routing probe relies
on this mechanism to reject EXE-shell-layout DLLs, so the web build routes
around it instead of through it: spliced companion inputs skip the probe
entirely (see "Detection and routing"), and the web app isolates every unpack
in a disposable Web Worker — a trapped DLL is retried once in a fresh worker
with the forced-EXE pipeline (`job::unpack_bytes_force_exe`), reproducing the
probe-then-fallback outcome without a catchable panic. A trap on any other
input is reported as a clean error rather than freezing the page.
The browser binding depends on `senbei-engine` through the I/O byte API. Native filesystem and Android package orchestration remain outside the browser workflow. Each browser unpack runs in a disposable worker because WebAssembly cannot recover from a caught panic in the same way as native code.
docs/development.md
+34 -99
View File
@@ -2,125 +2,60 @@
## Building
Requires a Rust toolchain (MSVC backend is the default on Windows;
`rustup-init.exe` from <https://rustup.rs> installs it). The pinned toolchain
and targets are in `rust-toolchain.toml`.
Rust 1.98.1 is required and pinned in `rust-toolchain.toml`. Build the CLI with `cargo build --release`; the binary is written to `target/release/senbei.exe` on Windows.
```cmd
cargo build --release
```
Output: `target\release\senbei.exe`. The binary is self-contained — no driver,
no proxy DLL, no external assets.
The library and CLI also build for Linux/macOS (`cfg`-gated platform code
only) and for `wasm32-unknown-unknown` (see the [web version](../web/README.md)).
The workspace crates are portable where their APIs are pure. The browser binding is outside the workspace and is checked with `cargo check --manifest-path senbei-wasm/Cargo.toml` or built with `wasm-pack`.
## Testing
```cmd
cargo test --release
cargo test --release --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check
```
The suite covers CLI behavior, detection, the folder driver, the run log, and
byte-exact golden tests over `samples/` — a user-managed corpus (git-ignored,
see `samples/README.md`) of real Crackproof inputs plus `<base>.golden.<ext>`
reference outputs. Every input goes through `job::unpack_bytes` — the same
routing the CLI uses, so an `<input>._` companion in the corpus is spliced and
the stub export/TLS overlays run — and is gated on **two** checks: the static
integrity check (catches runtime-broken outputs even when a stale golden would
still byte-match) and, when a golden exists, a bit-for-bit comparison. il2cpp
`*.dat` inputs are routed through `metadata::deobfuscate` instead. An empty or
absent corpus is a no-op pass; set `SENBEI_REQUIRE_SAMPLES` to make it fail
instead (useful on a private CI that has the corpus — public CI never does,
since binaries are not committed).
The tracked test suite is safe without protected samples. The optional local `samples/` corpus is user-managed and the ignored `test/` folder can be used for real Windows and Android runs.
> **Note:** goldens encode expected *bytes*, not runtime behavior. A golden
> produced before a pipeline fix may byte-match while still being wrong — the
> integrity check is the second gate for exactly this reason. Re-verify
> goldens against real runs when touching the affected pipeline stages.
>
> **The corpus only protects what it contains.** Wire the test to the routing
> the CLI actually takes (it is), and keep a sample for every layout family —
> marker-based, marker-less, external-companion, PE32, PE32+, native, managed,
> metadata. An unrepresented family has no regression gate at all, which is
> how a "re-run the golden corpus" rule can pass while silently covering
> nothing.
For an Android package, use one command at a time because a protected `.so` can be hundreds of megabytes. APK, APKS, and XAPK tests read the ZIP manifest first and extract only `.so` and `global-metadata.dat` entries.
## Debugging levers (environment variables)
## Environment Variables
- `DD8_SHIFT` — override the `decrypt_data8` page-XOR shift (`99` skips dd8
entirely).
- `SEL_DIAG` — print the dd8 selector's scores: the per-shift `0xCC` counts and
the plaintext baseline they are compared against (PE32+), and the per-formula
counts, baseline and net gain (PE32).
- `SENBEI_THREADS` — cap the block-parallel fan-out (`1` forces the fully
sequential path).
- `SENBEI_SCAN_ALL` — same as `--scan-all` (probe every file in a folder).
- `SENBEI_ANDROID_SAMPLES` — override the Android corpus location (default
`samples/android/`; see `samples/README.md`). The Android corpus test pins
restored outputs with SHA-256 sidecar files next to each protected input
and documents known restore gaps with empty `<base>.restore-fails` markers.
- `DD8_SHIFT` overrides the PE page-XOR shift; `99` skips that stage.
- `SEL_DIAG` prints PE layout-selector diagnostics.
- `SENBEI_THREADS` caps deterministic block fan-out; `1` forces the sequential reference path.
- `SENBEI_SCAN_ALL` enables probing selected target names below the size floor; it never enables arbitrary filenames.
- `SENBEI_ANDROID_SAMPLES` overrides the Android sample corpus location.
## Conventions
- The `senbei-pe/` core (and its `senbei-crypto/` base) is pure: no file I/O,
no panics across the public boundary, no `unsafe`. Keep it that way — it is
what the WebAssembly build embeds.
- Layout heuristics must **trial-and-validate**: never pick a candidate offset
on shape alone and trust it; validate by decryption/checksum and fall
through to the next candidate on failure. A silent wrong offset produces a
silently broken output, which is worse than an error.
- Output must remain byte-identical against the golden corpus for every
supported layout. When fixing one build family, re-run the full golden
corpus to prove no other family regressed.
- Folder scanning uses a size floor plus an extension **deny**-list, never an
allow-list: targets are recognised by content, not extension, and can carry
arbitrary names, so only known bulk-asset extensions are excluded. The
pre-filter exists because folder-scan cost is per-file I/O latency, not the
walk — probe fewer files, don't parallelize the probe loop.
- `cargo fmt` and `cargo clippy` must stay clean (CI enforces both).
Format crates stay free of filesystem I/O and protection-specific logic. Windows engine code lives below `senbei-engine/src/windows/`, Android engine code below `senbei-engine/src/android/`, and shared code stays directly under each crate's `src/`.
## Repository layout
Layout heuristics must trial and validate every candidate. A failed validation is an error or a fall-through, never a silently accepted offset.
```
senbei/
├── Cargo.toml workspace root (members: the senbei-* crates)
├── rust-toolchain.toml pinned toolchain + targets
├── senbei-cli/ senbei binary (default member)
│ └── tests/ CLI, detection, golden, and folder tests
├── senbei-pe/ pure unpacker core (see docs/design.md)
├── senbei-crypto/ crypto/compression primitives
├── senbei-metadata/ il2cpp metadata de-obfuscation
├── senbei-io/ filesystem, scanning, CLI orchestration
├── senbei-wasm/ WebAssembly bindings crate (own Cargo.lock,
│ outside the workspace; builds into web/pkg/)
├── samples/ local-only test corpus (git-ignored)
├── web/ static browser frontend assets (+ built pkg/)
├── docs/ usage, design, and development documentation
└── .github/ CI workflows and issue templates
Outputs must remain byte-identical against the available golden corpus. Run the full workspace tests after changing a pipeline or a metadata layout.
Folder scanning uses explicit target names to avoid opening bulk assets. External `.exe._` and `.dll._` files are auxiliary data for their sibling stubs and are not independent scan targets.
## Repository Layout
```text
senbei-cli/ command-line binary and integration tests
senbei-crypto/ Windows and Android crypto primitives
senbei-elf/ ELF parsing, mapping, and dynamic-table helpers
senbei-engine/ Windows and Android unpacking engines
senbei-io/ filesystem, package, scanning, and platform adapters
senbei-metadata/ shared, Windows, and Android metadata restoration
senbei-pe/ PE parsing, data directories, and RVA mapping
senbei-wasm/ browser bindings and its own lockfile
web/ static browser frontend
samples/ optional local corpus
```
## Web build
See [web/README.md](../web/README.md). In short:
## Web Build
```cmd
cd senbei-wasm
wasm-pack build --target web --release --out-dir ../web/pkg
```
then serve `web/` statically and open `index.html`. Everything runs
client-side; no file leaves the browser.
## Contributing
Issues and pull requests are welcome. A few ground rules:
- **Never commit binaries** (protected or decrypted) to the repository —
the only corpus is the local git-ignored `samples/`. Attaching a protected
input file to an issue is welcome if it helps diagnose the problem; only
attach files you are authorized to share.
- Run `cargo test --release`, `cargo clippy`, and `cargo fmt` before
submitting.
- Keep the unpacker core free of I/O, `unsafe`, and platform-specific code.
Serve `web/` with a static HTTP server after the build. The browser never uploads input files.
docs/usage.md
+26 -132
View File
@@ -1,163 +1,57 @@
# Usage
```
senbei <file|folder> [--out DIR] [-v|--verbose] [-q|--quiet]... [--scan-all]
[--no-log] [--no-pause] [-V|--version] [-h|--help]
```text
senbei <file|folder> [--out DIR] [-v|--verbose] [-q|--quiet]... [--scan-all] [--no-log] [--no-pause] [-V|--version] [-h|--help]
```
Real runs print `Senbei <version>` once at start. Use `-V` / `--version` to
print the version and exit.
## Single File
## Single file
The decrypted image is written under `<parent>/unpack/` with `.unpack` inserted
before the extension. A `senbei-<timestamp>.log` is written in the same
directory. With `--out DIR`, both the output and the log go into `DIR` instead:
The output is written below `<parent>/unpack/` with `.unpack` inserted before the extension. `--out DIR` changes both the output and log directory.
```cmd
senbei app.exe
:: -> unpack\app.unpack.exe
:: -> unpack\senbei-YYYYMMDD-HHMMSS.log
senbei app.exe --out C:\out
:: -> C:\out\app.unpack.exe
:: -> C:\out\senbei-YYYYMMDD-HHMMSS.log
```
Pointing senbei directly at an il2cpp `global-metadata.dat` rewrites its
obfuscated method tokens back to the contiguous per-module range il2cpp
expects; the output is `global-metadata.unpack.dat`, written only when tokens
actually changed. Only metadata format version 31 is rewritten; other versions
are reported and left untouched.
For `global-metadata.dat`, Senbei writes `global-metadata.unpack.dat` only when method tokens change. Unsupported metadata versions remain untouched and are reported as skipped.
## Android targets
## Android Targets
Senbei also restores Android (AArch64) protected shared libraries and app
packages:
Protected `.so` files are restored from their encrypted payload sections and written as `libil2cpp.unpack.so` or the corresponding input name. APK, APKS, and XAPK files are treated as containers: their manifests are read first, nested APKs are followed when necessary, and only `.so` and exact `global-metadata.dat` entries are extracted.
- **`.so`** — a protected library is hollowed out on disk: its original
sections live in an encrypted payload appended to the file, and senbei
rebuilds the static image from it. Output: `libil2cpp.unpack.so`.
- **`.apk`** — entries are extracted to a temporary workspace and
content-probed like loose files; protected libraries and metadata blobs
inside are restored to `<out>/<apk name>/<entry path>`.
- **`.apks` / `.xapk`** — split-package bundles; each nested `.apk` is opened
and searched the same way, under `<out>/<bundle name>/<split name>/...`.
If a restored library contains embedded metadata, the unwrapped blob is written beside it as `global-metadata.unpack.dat`. Identical loose and package entries are restored once, preferring the loose file.
When a restored il2cpp library carries its metadata embedded in its data
section (no standalone `global-metadata.dat` in the app at all), senbei
unwraps the blob and writes it next to the library as
`global-metadata.unpack.dat`. One observed packaging variant wraps the blob in
a per-word XOR layer whose keys are generated at runtime and stored nowhere;
senbei ships the keystream recovered from the one build known to use it and
content-probes for it — builds with a different keystream are silently
skipped (the library itself is still fully restored).
## Folder Mode
The same content may appear loose in a folder, in its `.apk`, and in a bundle
side by side: identical content is restored once, at the loose file's
destination. A restored library is validated structurally by the restore
itself (the rebuild refuses inconsistent layouts); a protected library that
fails validation counts as an error, not a suspect.
Folder mode walks recursively, skips directories named `unpack`, and mirrors recognized outputs below `<root>/unpack/` or `--out DIR`. Windows candidates are `.exe`, `.dll`, and `global-metadata.dat`; Android candidates are `.so` and `global-metadata.dat`. A matching `.exe._` or `.dll._` payload is consumed by its stub and is excluded from the skipped count.
## Folder mode
Managed DLL companions retain CLR metadata and related runtime tables in the original DLL. Both the DLL and its matching `._` file must be available; Senbei restores the declared CLR regions from the DLL while retaining method bodies decrypted from the companion. Invalid or missing referenced regions are reported as errors.
Senbei walks the directory recursively, skips any subdirectory literally named
`unpack`, and unpacks every file it recognises as protected (by content, not
extension — renamed files and `.bak` backups are still found; packages are the
one exception, recognised by extension plus the zip magic because they are
containers). Results land under `<root>/unpack/` (or `--out DIR`), mirroring
the input tree's relative paths. The run log is written **in that same out
directory**:
The summary has the form `12 unpacked · 3 skipped · 0 errors · 1 suspect · 2 metadata`; the package count is appended when packages were opened. Each file is isolated so one failed target does not stop the folder run.
```cmd
senbei "C:\Games\MyGame"
:: -> C:\Games\MyGame\unpack\...
:: -> C:\Games\MyGame\unpack\senbei-YYYYMMDD-HHMMSS.log
```
## Integrity Check
Folder mode also picks up `global-metadata.dat` files and external-companion
`._` payloads: a module whose `<name>._` sibling matches its header region is
spliced with the companion automatically (no flag needed) and unpacked as one
image, with the output named for the stub.
PE outputs are checked for valid headers, section ranges, entry-point mapping, readable import names, relocation requirements, and managed metadata signatures. Android outputs are validated during ELF restoration, including decoded container sizes, fixup bounds, and rebuilt dynamic tables.
Each file is processed in isolation: an error or panic on one file is caught,
counted, and logged, and the run continues. Folder mode finishes with a summary
line, then duration:
```
12 unpacked · 3 skipped · 0 errors · 1 suspect · 2 metadata
done in 1234 ms
```
The `packages` count appears (as `· N packages`) only when Android app
packages were processed.
## Integrity check
(PE outputs only — Android restores carry their own structural validation; see
[Android targets](#android-targets).)
A successful unpack is not always a runnable one: a layout heuristic can pick
the wrong offset and leave the entry-point stub or import strings encrypted, so
the pipeline reports success but the OS loader faults at runtime (typically
`0xC0000005`, STATUS_ACCESS_VIOLATION). To catch this, senbei runs a static
sanity check over every output it produces — inspecting the bytes alone, with
no reference image and no execution.
It flags only defects that cannot occur in a correctly unpacked image:
- malformed DOS/PE headers, bad optional-header magic, implausible section
count, zero `SizeOfImage`, or section raw-data ranges that run past EOF;
- an entry point that doesn't map into a section, isn't in an executable
section, or whose stub is all zeros or all `0xCC` int3 padding (the classic
left-encrypted symptom);
- a native (unmanaged) DLL with no base-relocation directory — it cannot
survive being mapped at a non-preferred base;
- **any** import descriptor whose DLL name doesn't resolve or isn't readable
ASCII (imports left encrypted) — the whole table is walked, not just the
first entry;
- for a managed assembly, a COR20 header whose `cb` isn't `0x48` or a
MetaData stream missing its `BSJB` signature (the CLR would reject the
image outright).
The entry-point and import checks are skipped for managed assemblies, whose
native EP and import stub are legitimately not what the native loader expects.
The check is deliberately conservative: a clean report is **not** a proof of
correctness, but a non-clean report is a reliable "this is broken" signal. A
suspect file is still written (the bytes are the best available) and flagged —
single-file mode prints a warning to stderr, folder mode prints a yellow `!`
line, adds a `SUSPECT` entry to the run log, and counts it in the summary's
`suspect` total (which is additive to `unpacked`).
A clean report is not a proof of correctness, but a non-clean report is a reliable broken-output signal. Suspect PE files are still written and counted separately.
## Flags
| Flag | Behavior |
| --- | --- |
| `--out DIR` | Write outputs (and the log, unless `--no-log`) under `DIR`. |
| `-v`, `--verbose` | Print detailed per-stage progress (and the destination path) for each file — `[N/9]` stages for PE targets, container/segment lines for Android libraries. In folder mode this replaces the progress bar. |
| `-q`, `--quiet` | Once: hide progress bar and per-file lines; keep banner, summary, and duration. Twice (`-q -q`): suppress all stdio (exit code only). |
| `--no-log` | Do not write `senbei-*.log`. Console output is unchanged by this flag alone. |
| `--scan-all` | Probe every file in a folder, including ones the scan pre-filter skips (under 4128 bytes, or a bulk-asset extension like `.ab`/`.xml`/`.acb`). Much slower on large game trees; finds the same targets in practice. |
| `--no-pause` | Skip the "Press Enter to exit" prompt (for scripted runs). |
| `-V`, `--version` | Print `Senbei <version>` and exit. |
| `--out DIR` | Write outputs and logs below `DIR`. |
| `-v`, `--verbose` | Print per-stage progress. |
| `-q`, `--quiet` | Hide progress and per-file lines; repeat to suppress all standard output. |
| `--no-log` | Do not write a run log. |
| `--scan-all` | Probe every selected target-name candidate, including files below the size floor. |
| `--no-pause` | Disable the Explorer-friendly Windows exit prompt. |
| `-V`, `--version` | Print the version and exit. |
| `-h`, `--help` | Show usage. |
On Windows, when launched from Explorer (the process owns its console) senbei
pauses for Enter before exiting so the window doesn't vanish. `--no-pause`
disables this; it has no effect when stdout is piped or run from another
process.
## Exit codes
## Exit Codes
| Code | Meaning |
| --- | --- |
| `0` | Success (single file restored, or folder run with no errors). |
| `1` | At least one file failed, a scan probe was unreadable, or a single-file unpack errored. |
| `2` | Usage error: no path given, unknown option, missing `--out` value, or multiple input paths (help printed). |
A folder run also fails with `1` when parts of the tree could not be scanned
(unreadable directory entries or files that failed the content probe) — those
are potential missed targets, not clean skips. An il2cpp metadata blob whose
format version senbei does not handle is *not* an error: it is reported, left
untouched, and counted as skipped.
| `0` | The requested restore completed without errors. |
| `1` | A target failed, a scan probe was unreadable, or a single-file restore errored. |
| `2` | The command line was invalid. |
rust-toolchain.toml
+5 -1
View File
@@ -1,3 +1,7 @@
[toolchain]
channel = "stable"
channel = "1.98.1"
# CI invokes rustfmt/clippy through the rustup shim with no setup action, so
# the pinned toolchain must declare its components here — the runner images
# only preinstall them for their default toolchain.
components = ["rustfmt", "clippy"]
targets = ["x86_64-pc-windows-msvc", "wasm32-unknown-unknown"]
samples/README.md
+15 -97
View File
@@ -1,105 +1,23 @@
# senbei/samples
# Samples
Drop-in corpus for the `samples` integration test (`tests/samples.rs`).
This ignored directory is the optional local corpus used by the samples integration test. Protected binaries and restored outputs must never be committed.
This folder is **git-ignored** (only this `README.md` is tracked), so it holds
whatever Crackproof binaries happen to be on your machine. Nothing here is
committed.
Place protected `.exe` and `.dll` files, exact `global-metadata.dat` files, and matching `.exe._` or `.dll._` companion payloads here. A golden output may sit beside an input as `<base>.golden.<ext>`.
## What to put here
Place protected inputs directly in this folder:
- `*.exe` — Crackproof-protected executables (PE32 or PE32+)
- `*.dll` — Crackproof-protected DLLs (native or managed)
- `*.dat` — il2cpp `global-metadata.dat` blobs (method-token de-obfuscation)
For an **external-companion** module, copy the `<name>._` payload in as well,
keeping the exact `._` suffix on the full file name. The test splices it the
same way the CLI does; without it the loader stub alone is meaningless and the
splice / export-overlay / TLS-restore code is never exercised.
Optionally, place a **golden** next to each input — the known-good unpacked
output, named `<base>.golden.<ext>`:
```
```text
samples/
app.exe <- input
app.golden.exe <- golden (optional)
managed.dll <- input
managed.golden.dll <- golden (optional)
stub.dll <- input (external-companion layout)
stub.dll._ <- its encrypted payload (NOT an input itself)
stub.golden.dll <- golden
global-metadata.dat <- input
global-metadata.golden.dat<- golden
mystery.exe <- input, no golden
app.exe
app.golden.exe
managed.dll
stub.dll
stub.dll._
stub.golden.dll
global-metadata.dat
global-metadata.golden.dat
```
The type (EXE vs native/managed DLL vs metadata) is auto-detected from the file
contents, not the extension, so you don't need to classify anything by hand.
Run `cargo test --release --test samples -- --nocapture`. A missing golden prints a warning; a mismatched golden or failed restore fails the test. An empty corpus is a no-op pass.
Since the corpus is the only regression gate on byte-identical output, keep it
broad: each build family, each layout (marker-based and marker-less), and at
least one external-companion pair. A family with no sample here is a family no
test protects.
## Android Corpus
## How the test treats each input
Run with:
```
cargo test --release --test samples
```
For every input file, the test runs the same routing the CLI uses
(`job::unpack_bytes`, so companions splice and the stub overlays run) — or
`metadata::deobfuscate` for an il2cpp blob — and then:
| Situation | Result |
| ------------------------------------------- | ------------------------------- |
| Golden present, bytes **identical** | **pass** |
| Golden present, bytes **differ** | **fail** (test fails) |
| **No golden** found | **warning** (needs manual check)|
| Unpack errored / file unreadable | **fail** |
Warnings are printed but do not fail the test — they flag outputs you should
eyeball or promote to a golden once verified. Failures fail the test. An empty
or absent folder is a no-op pass.
To see the per-file warning/pass/fail summary, run with output shown:
```
cargo test --release --test samples -- --nocapture
```
## Naming rules
- An **input** is any `*.exe` / `*.dll` / `*.dat` whose name does **not**
contain the `.golden.` segment.
- A **golden** is `<base>.golden.<ext>` sitting next to its input. Files with
`.golden.` in the name are never treated as inputs.
- A **companion** is `<input file name>._` (e.g. `stub.dll._` for `stub.dll`).
Its extension is `_`, so it is never picked up as an input of its own; it is
read only when its base module is processed.
## Android corpus (`samples/android/`)
The `android/` subfolder holds Android samples, one **extracted app tree** per
subdirectory (the layout an APK unpacks to: `lib/<abi>/*.so`,
`assets/.../global-metadata.dat`, ...). The test
(`tests/android_samples.rs`) finds protected AArch64 libraries by content and
restores them through the real pipeline. `SENBEI_ANDROID_SAMPLES` overrides
the corpus location.
Sidecar conventions (all next to the protected `.so` input):
| File | Meaning |
| ---- | ------- |
| `<base>.golden.so.sha256` | Expected SHA-256 of the restored library |
| `<base>.golden.metadata.sha256` | Expected SHA-256 of the unwrapped embedded metadata blob (when the library carries one) |
| `<base>.restore-fails` | Empty marker: this input's restore is a known gap and *must* fail (a future fix fails the test, prompting marker removal) |
A missing sidecar is a warning (with the computed digest printed, ready to
promote), never a failure. App packages (`.apk`/`.apks`/`.xapk`) dropped into
a tree are exercised by folder mode as containers.
`samples/android/` may contain one extracted app tree per subdirectory. Protected libraries are restored through the real pipeline and can carry SHA-256 sidecars named `<base>.golden.so.sha256` and `<base>.golden.metadata.sha256`. An empty `<base>.restore-fails` marker documents a known restore gap.
senbei-android-elf/src/layout.rs
-301
View File
@@ -1,301 +0,0 @@
use crate::error::{Error, Result, invalid};
pub(crate) const SHT_NOBITS: u32 = 8;
pub(crate) const SHT_LOUSER: u32 = 0x8000_0000;
pub(crate) const SHF_ALLOC: u64 = 2;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct LoadSegment {
pub offset: u64,
pub virtual_address: u64,
pub file_size: u64,
pub memory_size: u64,
pub flags: u32,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct SectionHeader {
pub name: u32,
pub section_type: u32,
pub flags: u64,
pub address: u64,
pub offset: u64,
pub size: u64,
pub link: u32,
pub info: u32,
pub alignment: u64,
pub entry_size: u64,
}
impl SectionHeader {
pub const SIZE: usize = 0x40;
fn parse(data: &[u8], offset: usize) -> Result<Self> {
Ok(Self {
name: read_u32(data, offset)?,
section_type: read_u32(data, offset + 4)?,
flags: read_u64(data, offset + 8)?,
address: read_u64(data, offset + 0x10)?,
offset: read_u64(data, offset + 0x18)?,
size: read_u64(data, offset + 0x20)?,
link: read_u32(data, offset + 0x28)?,
info: read_u32(data, offset + 0x2c)?,
alignment: read_u64(data, offset + 0x30)?,
entry_size: read_u64(data, offset + 0x38)?,
})
}
pub fn encode(self) -> [u8; Self::SIZE] {
let mut output = [0_u8; Self::SIZE];
output[0..4].copy_from_slice(&self.name.to_le_bytes());
output[4..8].copy_from_slice(&self.section_type.to_le_bytes());
output[8..0x10].copy_from_slice(&self.flags.to_le_bytes());
output[0x10..0x18].copy_from_slice(&self.address.to_le_bytes());
output[0x18..0x20].copy_from_slice(&self.offset.to_le_bytes());
output[0x20..0x28].copy_from_slice(&self.size.to_le_bytes());
output[0x28..0x2c].copy_from_slice(&self.link.to_le_bytes());
output[0x2c..0x30].copy_from_slice(&self.info.to_le_bytes());
output[0x30..0x38].copy_from_slice(&self.alignment.to_le_bytes());
output[0x38..0x40].copy_from_slice(&self.entry_size.to_le_bytes());
output
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct ElfLayout {
pub entrypoint: u64,
pub program_headers: Vec<LoadSegment>,
pub section_headers: Vec<SectionHeader>,
pub section_name_index: usize,
pub private_section_index: usize,
}
impl ElfLayout {
pub fn parse(data: &[u8], require_private: bool) -> Result<Self> {
let ident = slice(data, 0, 6)?;
if ident[..4] != *b"\x7fELF" || ident[4] != 2 || ident[5] != 1 {
return invalid("input is not a little-endian ELF64 file");
}
if read_u16(data, 0x12)? != 0xb7 {
return invalid("input is not an AArch64 ELF");
}
let entrypoint = read_u64(data, 0x18)?;
let program_header_offset = usize_from_u64(read_u64(data, 0x20)?, "program header offset")?;
let section_header_offset = usize_from_u64(read_u64(data, 0x28)?, "section header offset")?;
let program_header_size = usize::from(read_u16(data, 0x36)?);
let program_header_count = usize::from(read_u16(data, 0x38)?);
let section_header_size = usize::from(read_u16(data, 0x3a)?);
let section_header_count = usize::from(read_u16(data, 0x3c)?);
let section_name_index = usize::from(read_u16(data, 0x3e)?);
if program_header_size != 0x38 || section_header_size != SectionHeader::SIZE {
return invalid("unexpected ELF program/section header size");
}
let mut program_headers = Vec::new();
for index in 0..program_header_count {
let offset = checked_index(program_header_offset, index, program_header_size)?;
if read_u32(data, offset)? != 1 {
continue;
}
let segment = LoadSegment {
flags: read_u32(data, offset + 4)?,
offset: read_u64(data, offset + 8)?,
virtual_address: read_u64(data, offset + 0x10)?,
file_size: read_u64(data, offset + 0x20)?,
memory_size: read_u64(data, offset + 0x28)?,
};
let file_end = segment
.offset
.checked_add(segment.file_size)
.ok_or_else(|| Error::Invalid(format!("PT_LOAD {index} file range overflow")))?;
if file_end > data.len() as u64 {
return invalid(format!("PT_LOAD {index} exceeds input file"));
}
program_headers.push(segment);
}
if program_headers.is_empty() {
return invalid("input ELF contains no PT_LOAD segments");
}
let mut section_headers = Vec::with_capacity(section_header_count);
for index in 0..section_header_count {
let offset = checked_index(section_header_offset, index, section_header_size)?;
section_headers.push(SectionHeader::parse(data, offset)?);
}
if section_name_index >= section_headers.len() {
return invalid("ELF section-name index is out of range");
}
let private = section_headers
.iter()
.enumerate()
.filter_map(|(index, section)| (section.section_type == SHT_LOUSER).then_some(index))
.collect::<Vec<_>>();
let private_section_index = match private.as_slice() {
[index] => *index,
[] if !require_private => usize::MAX,
_ => {
return invalid(format!(
"expected {} SHT_LOUSER section, found {}",
if require_private {
"one"
} else {
"at most one"
},
private.len()
));
}
};
Ok(Self {
entrypoint,
program_headers,
section_headers,
section_name_index,
private_section_index,
})
}
pub fn private_section(&self) -> Result<SectionHeader> {
self.section_headers
.get(self.private_section_index)
.copied()
.ok_or_else(|| Error::Invalid("ELF has no private section".to_owned()))
}
pub fn load_end(&self) -> Result<u64> {
self.program_headers
.iter()
.map(|segment| {
segment
.virtual_address
.checked_add(segment.memory_size)
.ok_or_else(|| Error::Invalid("PT_LOAD memory end overflow".to_owned()))
})
.collect::<Result<Vec<_>>>()?
.into_iter()
.max()
.ok_or_else(|| Error::Invalid("ELF has no PT_LOAD memory range".to_owned()))
}
pub fn file_load_end(&self) -> Result<u64> {
self.program_headers
.iter()
.map(|segment| {
segment
.offset
.checked_add(segment.file_size)
.ok_or_else(|| Error::Invalid("PT_LOAD file end overflow".to_owned()))
})
.collect::<Result<Vec<_>>>()?
.into_iter()
.max()
.ok_or_else(|| Error::Invalid("ELF has no PT_LOAD file range".to_owned()))
}
pub fn section_names(&self, data: &[u8]) -> Result<Vec<String>> {
let table = self.section_headers[self.section_name_index];
let strings = slice_u64(data, table.offset, table.size)?;
self.section_headers
.iter()
.map(|section| {
let offset = section.name as usize;
if offset >= strings.len() {
return Ok(String::new());
}
let end = strings[offset..]
.iter()
.position(|&byte| byte == 0)
.map_or(strings.len(), |length| offset + length);
Ok(String::from_utf8_lossy(&strings[offset..end]).into_owned())
})
.collect()
}
pub fn file_offset_to_virtual_address(&self, offset: u64, size: u64) -> Result<u64> {
let end = offset
.checked_add(size)
.ok_or_else(|| Error::Invalid("file range overflow".to_owned()))?;
for segment in &self.program_headers {
let segment_end = segment
.offset
.checked_add(segment.file_size)
.ok_or_else(|| Error::Invalid("PT_LOAD file range overflow".to_owned()))?;
if segment.offset <= offset && end <= segment_end {
return segment
.virtual_address
.checked_add(offset - segment.offset)
.ok_or_else(|| Error::Invalid("virtual address overflow".to_owned()));
}
}
invalid(format!(
"file range 0x{offset:x}..0x{end:x} is not in PT_LOAD"
))
}
}
pub(crate) fn slice(data: &[u8], offset: usize, size: usize) -> Result<&[u8]> {
let end = offset
.checked_add(size)
.ok_or_else(|| Error::Invalid("byte range overflow".to_owned()))?;
data.get(offset..end).ok_or_else(|| {
Error::Invalid(format!(
"byte range 0x{offset:x}..0x{end:x} is out of bounds"
))
})
}
pub(crate) fn slice_u64(data: &[u8], offset: u64, size: u64) -> Result<&[u8]> {
slice(
data,
usize_from_u64(offset, "file offset")?,
usize_from_u64(size, "file size")?,
)
}
pub(crate) fn read_u16(data: &[u8], offset: usize) -> Result<u16> {
let bytes: [u8; 2] = slice(data, offset, 2)?
.try_into()
.map_err(|_| Error::Invalid("invalid u16 range".to_owned()))?;
Ok(u16::from_le_bytes(bytes))
}
pub(crate) fn read_u32(data: &[u8], offset: usize) -> Result<u32> {
let bytes: [u8; 4] = slice(data, offset, 4)?
.try_into()
.map_err(|_| Error::Invalid("invalid u32 range".to_owned()))?;
Ok(u32::from_le_bytes(bytes))
}
pub(crate) fn read_u64(data: &[u8], offset: usize) -> Result<u64> {
let bytes: [u8; 8] = slice(data, offset, 8)?
.try_into()
.map_err(|_| Error::Invalid("invalid u64 range".to_owned()))?;
Ok(u64::from_le_bytes(bytes))
}
pub(crate) fn read_i64(data: &[u8], offset: usize) -> Result<i64> {
let bytes: [u8; 8] = slice(data, offset, 8)?
.try_into()
.map_err(|_| Error::Invalid("invalid i64 range".to_owned()))?;
Ok(i64::from_le_bytes(bytes))
}
pub(crate) fn usize_from_u64(value: u64, field: &str) -> Result<usize> {
usize::try_from(value).map_err(|_| Error::Invalid(format!("{field} 0x{value:x} exceeds usize")))
}
pub(crate) fn checked_index(base: usize, index: usize, stride: usize) -> Result<usize> {
index
.checked_mul(stride)
.and_then(|value| base.checked_add(value))
.ok_or_else(|| Error::Invalid("table index overflow".to_owned()))
}
pub(crate) fn align_up(value: u64, alignment: u64) -> Result<u64> {
if alignment == 0 || !alignment.is_power_of_two() {
return invalid(format!("invalid alignment {alignment}"));
}
value
.checked_add(alignment - 1)
.map(|aligned| aligned & !(alignment - 1))
.ok_or_else(|| Error::Invalid("alignment overflow".to_owned()))
}
senbei-android-elf/src/lib.rs
-10
View File
@@ -1,10 +0,0 @@
//! Static restoration of the current protected AArch64 `libil2cpp.so`.
mod artifact;
mod error;
mod hash;
mod layout;
mod restore;
pub use error::Error;
pub use restore::{RestoreOptions, RestoreReport, restore_libil2cpp};
senbei-android-engine/Cargo.toml
-20
View File
@@ -1,20 +0,0 @@
[package]
name = "senbei-android-engine"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
description = "Static Stage 1 and Stage 2 extraction for Senbei Android"
[dependencies]
goblin.workspace = true
memmap2.workspace = true
serde.workspace = true
serde_json.workspace = true
sha2.workspace = true
tempfile.workspace = true
thiserror.workspace = true
senbei-android-crypto.workspace = true
[lints]
workspace = true
senbei-android-metadata/Cargo.toml
-14
View File
@@ -1,14 +0,0 @@
[package]
name = "senbei-android-metadata"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
description = "IL2CPP metadata restoration for Senbei Android"
[dependencies]
serde.workspace = true
thiserror.workspace = true
[lints]
workspace = true
senbei-cli/Cargo.toml
+1
View File
@@ -13,6 +13,7 @@ path = "src/main.rs"
[dependencies]
senbei-io.workspace = true
senbei-engine.workspace = true
[dev-dependencies]
senbei-io.workspace = true
senbei-cli/src/main.rs
+2 -3
View File
@@ -104,8 +104,7 @@ fn print_help() {
\x20 these"
);
println!(
" --scan-all probe every file in a folder, including ones the scan\n\
\x20 pre-filter skips (under 4128 bytes, extensionless,\n\
\x20 or a bulk-asset extension). Much slower on large trees."
" --scan-all probe selected .exe/.dll/.so/metadata names below the\n\
\x20 size floor; other filenames remain excluded."
);
}
senbei-crypto/Cargo.toml
+1
View File
@@ -6,4 +6,5 @@ license.workspace = true
description = "Cryptographic and compression primitives for Senbei"
[dependencies]
aes.workspace = true
thiserror.workspace = true
senbei-android-crypto/src/lib.rs → senbei-crypto/src/android/mod.rs
+1 -1
View File
@@ -1,4 +1,4 @@
//! Cryptographic and container primitives used by Senbei Android.
//! Android container cryptography and decoding primitives.
mod protector;
senbei-android-crypto/src/protector.rs → senbei-crypto/src/android/protector.rs
+6 -12
View File
@@ -359,7 +359,7 @@ pub struct HuffmanLzDecoder {
impl HuffmanLzDecoder {
/// Build the full 16-bit prefix lookup used by the static decoder.
pub fn new(tree: &[u8]) -> Result<Self> {
if tree.len() < 256 * 3 || tree.len() % 3 != 0 {
if tree.len() < 256 * 3 || !tree.len().is_multiple_of(3) {
return invalid(format!("invalid Huffman tree size 0x{:x}", tree.len()));
}
let mut result = Self {
@@ -552,7 +552,7 @@ pub fn transform_segment(
let mut state = seed;
let mut left = 0xe34e_ac63_u32;
let mut right = 0x07b4_8238_u32;
for (index, chunk) in transformed.chunks_exact_mut(4).enumerate() {
for (index, chunk) in transformed.as_chunks_mut::<4>().0.iter_mut().enumerate() {
let index32 = u32::try_from(index)
.map_err(|_| Error::Invalid("segment word index exceeds u32".to_owned()))?;
left = state
@@ -564,10 +564,7 @@ pub fn transform_segment(
.wrapping_add(right.wrapping_sub(0x1605_a81c).wrapping_mul(right))
.wrapping_shl(index32 & 7);
state = left ^ right;
let bytes: [u8; 4] = chunk
.try_into()
.map_err(|_| Error::Invalid("invalid transformed word".to_owned()))?;
let mut value = u32::from_le_bytes(bytes);
let mut value = u32::from_le_bytes(*chunk);
value = value.wrapping_add(0xb43b_9baf_u32.wrapping_mul(index32 & 0x0d));
value ^= 0xaf57_f7fb_u32.wrapping_mul(index32 & 3);
value = value.wrapping_sub(state) ^ state;
@@ -577,13 +574,10 @@ pub fn transform_segment(
if decrypt_aes {
let cipher = Aes256::new_from_slice(aes_key)
.map_err(|_| Error::Invalid("invalid AES-256 key length".to_owned()))?;
let aligned_size = transformed.len() & !0x0f;
let mut previous = [0_u8; 16];
for chunk in transformed[..aligned_size].chunks_exact_mut(16) {
let mut ciphertext = [0_u8; 16];
ciphertext.copy_from_slice(chunk);
// chunk is exactly one block (chunks_exact_mut(16)).
cipher.decrypt_block(chunk.try_into().expect("chunk is one block"));
for chunk in transformed.as_chunks_mut::<16>().0 {
let ciphertext = *chunk;
cipher.decrypt_block((&mut *chunk).into());
for (byte, prior) in chunk.iter_mut().zip(previous) {
*byte ^= prior;
}
senbei-crypto/src/lib.rs
+15 -72
View File
@@ -1,77 +1,20 @@
//! Cryptographic, checksum, compression, and bytecode primitives.
//! Cryptographic and compression primitives for the supported protection
//! formats.
pub mod bytecode;
pub mod crc32;
pub mod primitives;
mod tables;
pub mod android;
pub mod windows;
/// Maximum buffer size accepted by allocation-sensitive transforms.
pub const MAX_IMAGE_SIZE: u64 = 1 << 30;
// Keep the historical flat paths available to downstream callers while the
// implementations themselves live under their platform boundary.
pub use windows::{BufferOperation, DecompressionFailure, Error, MAX_IMAGE_SIZE};
pub use windows::{bytecode, crc32, primitives};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BufferOperation {
Read,
CopySource,
CopyDestination,
ZeroFill,
/// Lowercase hexadecimal representation for digest and diagnostic bytes.
#[must_use]
pub fn hex_digest(data: &[u8]) -> String {
let mut output = String::with_capacity(data.len() * 2);
for byte in data {
output.push_str(&format!("{byte:02x}"));
}
impl std::fmt::Display for BufferOperation {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(match self {
Self::Read => "read",
Self::CopySource => "copy source",
Self::CopyDestination => "copy destination",
Self::ZeroFill => "zero-fill",
})
}
}
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum Error {
#[error(
"{operation} range out of bounds (offset {offset}, size {size}, buffer length {buffer_len})"
)]
BufferRangeOutOfBounds {
operation: BufferOperation,
offset: usize,
size: usize,
buffer_len: usize,
},
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
#[non_exhaustive]
pub enum DecompressionFailure {
#[error("compressed source size {size} exceeds limit {max}")]
SourceTooLarge { size: u32, max: u64 },
#[error("Huffman code length {bits} is invalid")]
InvalidCodeLength { bits: u8 },
#[error("Huffman tree traversal exceeded 64 levels")]
HuffmanTraversalLimit,
#[error("pending length accumulator overflowed at {pending}")]
PendingLengthOverflow { pending: u32 },
#[error("output step {step} at byte {written} exceeds expected size {expected}")]
OutputOverflow {
written: u32,
step: u32,
expected: u32,
},
#[error("run-fill width {width} reads before output offset 0x{destination:08X}")]
RunFillBeforeOutput { width: u32, destination: u32 },
#[error("run-fill width {width} is unsupported")]
InvalidRunFillWidth { width: u32 },
#[error("back-reference distance {distance} exceeds {written} written bytes")]
InvalidBackReference { distance: u32, written: u32 },
#[error("Huffman symbol consumed no input and produced no output")]
NoProgress,
#[error(
"output size mismatch (wrote {written}/{expected} bytes after consuming {consumed}/{source_size})"
)]
OutputSizeMismatch {
written: u32,
expected: u32,
consumed: u32,
source_size: u32,
},
output
}
senbei-crypto/src/bytecode.rs → senbei-crypto/src/windows/bytecode.rs
View File
senbei-crypto/src/crc32.rs → senbei-crypto/src/windows/crc32.rs
View File
senbei-crypto/src/windows/mod.rs
+77
View File
@@ -0,0 +1,77 @@
//! Windows PE protection primitives.
pub mod bytecode;
pub mod crc32;
pub mod primitives;
mod tables;
/// Maximum buffer size accepted by allocation-sensitive PE transforms.
pub const MAX_IMAGE_SIZE: u64 = 1 << 30;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BufferOperation {
Read,
CopySource,
CopyDestination,
ZeroFill,
}
impl std::fmt::Display for BufferOperation {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(match self {
Self::Read => "read",
Self::CopySource => "copy source",
Self::CopyDestination => "copy destination",
Self::ZeroFill => "zero-fill",
})
}
}
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum Error {
#[error(
"{operation} range out of bounds (offset {offset}, size {size}, buffer length {buffer_len})"
)]
BufferRangeOutOfBounds {
operation: BufferOperation,
offset: usize,
size: usize,
buffer_len: usize,
},
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
#[non_exhaustive]
pub enum DecompressionFailure {
#[error("compressed source size {size} exceeds limit {max}")]
SourceTooLarge { size: u32, max: u64 },
#[error("Huffman code length {bits} is invalid")]
InvalidCodeLength { bits: u8 },
#[error("Huffman tree traversal exceeded 64 levels")]
HuffmanTraversalLimit,
#[error("pending length accumulator overflowed at {pending}")]
PendingLengthOverflow { pending: u32 },
#[error("output step {step} at byte {written} exceeds expected size {expected}")]
OutputOverflow {
written: u32,
step: u32,
expected: u32,
},
#[error("run-fill width {width} reads before output offset 0x{destination:08X}")]
RunFillBeforeOutput { width: u32, destination: u32 },
#[error("run-fill width {width} is unsupported")]
InvalidRunFillWidth { width: u32 },
#[error("back-reference distance {distance} exceeds {written} written bytes")]
InvalidBackReference { distance: u32, written: u32 },
#[error("Huffman symbol consumed no input and produced no output")]
NoProgress,
#[error(
"output size mismatch (wrote {written}/{expected} bytes after consuming {consumed}/{source_size})"
)]
OutputSizeMismatch {
written: u32,
expected: u32,
consumed: u32,
source_size: u32,
},
}
senbei-crypto/src/primitives.rs → senbei-crypto/src/windows/primitives.rs
+1 -1
View File
@@ -4,9 +4,9 @@
//! Each free function is self-contained: it takes the relevant byte buffer(s)
//! and parameters explicitly, with no coupling to the EXE `Unpacker` struct.
use super::tables::{COLUMMIX1, COLUMMIX2, COLUMMIX3, COLUMMIX4, SBOX};
use crate::bytecode::{Op, OpsLut};
use crate::crc32;
use crate::tables::{COLUMMIX1, COLUMMIX2, COLUMMIX3, COLUMMIX4, SBOX};
use std::cell::RefCell;
thread_local! {
senbei-crypto/src/tables.rs → senbei-crypto/src/windows/tables.rs
View File
senbei-android-crypto/Cargo.toml → senbei-elf/Cargo.toml
+3 -3
View File
@@ -1,13 +1,13 @@
[package]
name = "senbei-android-crypto"
name = "senbei-elf"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
description = "Protector container primitives for Senbei Android"
description = "ELF format parsing and structural utilities for Senbei"
[dependencies]
aes.workspace = true
goblin.workspace = true
thiserror.workspace = true
[lints]
senbei-android-elf/src/hash.rs → senbei-elf/src/hash.rs
+5 -5
View File
@@ -1,7 +1,7 @@
use crate::error::{Error, Result, invalid};
use crate::{Error, Result, invalid};
#[must_use]
pub(crate) fn elf_hash(name: &[u8]) -> u32 {
pub fn elf_hash(name: &[u8]) -> u32 {
let mut value = 0_u32;
for &byte in name {
value = value.wrapping_shl(4).wrapping_add(u32::from(byte));
@@ -15,13 +15,13 @@ pub(crate) fn elf_hash(name: &[u8]) -> u32 {
}
#[must_use]
pub(crate) fn gnu_hash(name: &[u8]) -> u32 {
pub fn gnu_hash(name: &[u8]) -> u32 {
name.iter().fold(5381_u32, |value, &byte| {
value.wrapping_mul(33).wrapping_add(u32::from(byte))
})
}
pub(crate) fn build_sysv_hash(names: &[Vec<u8>]) -> Result<Vec<u8>> {
pub fn build_sysv_hash(names: &[Vec<u8>]) -> Result<Vec<u8>> {
if names.len() < 2 {
return invalid("dynamic symbol table is unexpectedly empty");
}
@@ -60,7 +60,7 @@ pub(crate) fn build_sysv_hash(names: &[Vec<u8>]) -> Result<Vec<u8>> {
Ok(output)
}
pub(crate) fn build_gnu_hash(names: &[Vec<u8>]) -> Result<Vec<u8>> {
pub fn build_gnu_hash(names: &[Vec<u8>]) -> Result<Vec<u8>> {
let hashes = names
.iter()
.skip(1)
senbei-elf/src/layout.rs
+636
View File
@@ -0,0 +1,636 @@
use crate::{Error, Result, invalid};
pub const SHT_NOBITS: u32 = 8;
pub const SHT_STRTAB: u32 = 3;
pub const SHT_LOUSER: u32 = 0x8000_0000;
pub const SHF_ALLOC: u64 = 2;
const PT_LOAD: u32 = 1;
pub const PF_R: u32 = 4;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct LoadSegment {
pub offset: u64,
pub virtual_address: u64,
pub file_size: u64,
pub memory_size: u64,
pub flags: u32,
pub alignment: u64,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SectionHeader {
pub name: u32,
pub section_type: u32,
pub flags: u64,
pub address: u64,
pub offset: u64,
pub size: u64,
pub link: u32,
pub info: u32,
pub alignment: u64,
pub entry_size: u64,
}
impl SectionHeader {
pub const SIZE: usize = 0x40;
fn parse(data: &[u8], offset: usize) -> Result<Self> {
Ok(Self {
name: read_u32(data, offset)?,
section_type: read_u32(data, offset + 4)?,
flags: read_u64(data, offset + 8)?,
address: read_u64(data, offset + 0x10)?,
offset: read_u64(data, offset + 0x18)?,
size: read_u64(data, offset + 0x20)?,
link: read_u32(data, offset + 0x28)?,
info: read_u32(data, offset + 0x2c)?,
alignment: read_u64(data, offset + 0x30)?,
entry_size: read_u64(data, offset + 0x38)?,
})
}
pub fn encode(self) -> [u8; Self::SIZE] {
let mut output = [0_u8; Self::SIZE];
output[0..4].copy_from_slice(&self.name.to_le_bytes());
output[4..8].copy_from_slice(&self.section_type.to_le_bytes());
output[8..0x10].copy_from_slice(&self.flags.to_le_bytes());
output[0x10..0x18].copy_from_slice(&self.address.to_le_bytes());
output[0x18..0x20].copy_from_slice(&self.offset.to_le_bytes());
output[0x20..0x28].copy_from_slice(&self.size.to_le_bytes());
output[0x28..0x2c].copy_from_slice(&self.link.to_le_bytes());
output[0x2c..0x30].copy_from_slice(&self.info.to_le_bytes());
output[0x30..0x38].copy_from_slice(&self.alignment.to_le_bytes());
output[0x38..0x40].copy_from_slice(&self.entry_size.to_le_bytes());
output
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ElfLayout {
pub entrypoint: u64,
pub program_header_offset: usize,
pub program_header_size: usize,
pub program_header_count: usize,
pub program_headers: Vec<LoadSegment>,
pub section_headers: Vec<SectionHeader>,
pub section_name_index: usize,
pub private_section_index: usize,
}
impl ElfLayout {
pub fn parse(data: &[u8], require_private: bool) -> Result<Self> {
let ident = slice(data, 0, 6)?;
if ident[..4] != *b"\x7fELF" || ident[4] != 2 || ident[5] != 1 {
return invalid("input is not a little-endian ELF64 file");
}
if read_u16(data, 0x12)? != crate::AARCH64_MACHINE {
return invalid("input is not an AArch64 ELF");
}
let entrypoint = read_u64(data, 0x18)?;
let program_header_offset = usize_from_u64(read_u64(data, 0x20)?, "program header offset")?;
let section_header_offset = usize_from_u64(read_u64(data, 0x28)?, "section header offset")?;
let program_header_size = usize::from(read_u16(data, 0x36)?);
let program_header_count = usize::from(read_u16(data, 0x38)?);
let section_header_size = usize::from(read_u16(data, 0x3a)?);
let section_header_count = usize::from(read_u16(data, 0x3c)?);
let section_name_index = usize::from(read_u16(data, 0x3e)?);
if program_header_size != 0x38 || section_header_size != SectionHeader::SIZE {
return invalid("unexpected ELF program/section header size");
}
let mut program_headers = Vec::new();
for index in 0..program_header_count {
let offset = checked_index(program_header_offset, index, program_header_size)?;
if read_u32(data, offset)? != PT_LOAD {
continue;
}
let segment = LoadSegment {
flags: read_u32(data, offset + 4)?,
offset: read_u64(data, offset + 8)?,
virtual_address: read_u64(data, offset + 0x10)?,
file_size: read_u64(data, offset + 0x20)?,
memory_size: read_u64(data, offset + 0x28)?,
alignment: read_u64(data, offset + 0x30)?,
};
let file_end = segment
.offset
.checked_add(segment.file_size)
.ok_or_else(|| Error::Invalid(format!("PT_LOAD {index} file range overflow")))?;
if file_end > data.len() as u64 {
return invalid(format!("PT_LOAD {index} exceeds input file"));
}
program_headers.push(segment);
}
if program_headers.is_empty() {
return invalid("input ELF contains no PT_LOAD segments");
}
let mut section_headers = Vec::with_capacity(section_header_count);
for index in 0..section_header_count {
let offset = checked_index(section_header_offset, index, section_header_size)?;
section_headers.push(SectionHeader::parse(data, offset)?);
}
if section_name_index >= section_headers.len() {
return invalid("ELF section-name index is out of range");
}
let private = section_headers
.iter()
.enumerate()
.filter_map(|(index, section)| (section.section_type == SHT_LOUSER).then_some(index))
.collect::<Vec<_>>();
let private_section_index = match private.as_slice() {
[index] => *index,
[] if !require_private => usize::MAX,
_ => {
return invalid(format!(
"expected {} SHT_LOUSER section, found {}",
if require_private {
"one"
} else {
"at most one"
},
private.len()
));
}
};
let layout = Self {
entrypoint,
program_header_offset,
program_header_size,
program_header_count,
program_headers,
section_headers,
section_name_index,
private_section_index,
};
// Section roles are resolved from the ELF's own string table. Validate
// it at the format boundary so callers cannot silently continue with
// fabricated or lossy section names.
layout.section_names(data)?;
Ok(layout)
}
pub fn private_section(&self) -> Result<SectionHeader> {
self.section_headers
.get(self.private_section_index)
.copied()
.ok_or_else(|| Error::Invalid("ELF has no private section".to_owned()))
}
pub fn load_end(&self) -> Result<u64> {
self.program_headers
.iter()
.map(|segment| {
segment
.virtual_address
.checked_add(segment.memory_size)
.ok_or_else(|| Error::Invalid("PT_LOAD memory end overflow".to_owned()))
})
.collect::<Result<Vec<_>>>()?
.into_iter()
.max()
.ok_or_else(|| Error::Invalid("ELF has no PT_LOAD memory range".to_owned()))
}
pub fn file_load_end(&self) -> Result<u64> {
self.program_headers
.iter()
.map(|segment| {
segment
.offset
.checked_add(segment.file_size)
.ok_or_else(|| Error::Invalid("PT_LOAD file end overflow".to_owned()))
})
.collect::<Result<Vec<_>>>()?
.into_iter()
.max()
.ok_or_else(|| Error::Invalid("ELF has no PT_LOAD file range".to_owned()))
}
pub fn load_alignment(&self) -> Result<u64> {
let alignment = self
.program_headers
.iter()
.map(|segment| segment.alignment)
.max()
.ok_or_else(|| Error::Invalid("ELF has no PT_LOAD alignment".to_owned()))?;
if alignment == 0 || !alignment.is_power_of_two() {
return invalid(format!("invalid PT_LOAD alignment 0x{alignment:x}"));
}
Ok(alignment)
}
pub fn append_load_segment(&self, output: &mut [u8], segment: LoadSegment) -> Result<Self> {
if self.program_header_size != 0x38 {
return invalid("unexpected ELF program header size");
}
if segment.file_size == 0 {
return invalid("new PT_LOAD has no file contents");
}
if segment.memory_size < segment.file_size {
return invalid("new PT_LOAD memory size is smaller than file size");
}
if segment.alignment == 0 || !segment.alignment.is_power_of_two() {
return invalid(format!(
"invalid new PT_LOAD alignment 0x{:x}",
segment.alignment
));
}
if segment.offset % segment.alignment != segment.virtual_address % segment.alignment {
return invalid("new PT_LOAD offset and address are misaligned");
}
let segment_file_end = segment
.offset
.checked_add(segment.file_size)
.ok_or_else(|| Error::Invalid("new PT_LOAD file range overflow".to_owned()))?;
let segment_memory_end = segment
.virtual_address
.checked_add(segment.memory_size)
.ok_or_else(|| Error::Invalid("new PT_LOAD memory range overflow".to_owned()))?;
if segment_file_end > output.len() as u64 {
return invalid("new PT_LOAD exceeds output mapping");
}
for existing in &self.program_headers {
let existing_file_end = existing
.offset
.checked_add(existing.file_size)
.ok_or_else(|| Error::Invalid("PT_LOAD file range overflow".to_owned()))?;
if segment.offset < existing_file_end && existing.offset < segment_file_end {
return invalid("new PT_LOAD overlaps an existing file range");
}
let existing_memory_end = existing
.virtual_address
.checked_add(existing.memory_size)
.ok_or_else(|| Error::Invalid("PT_LOAD memory range overflow".to_owned()))?;
if segment.virtual_address < existing_memory_end
&& existing.virtual_address < segment_memory_end
{
return invalid("new PT_LOAD overlaps an existing memory range");
}
}
let new_count = self
.program_header_count
.checked_add(1)
.ok_or_else(|| Error::Invalid("program header count overflow".to_owned()))?;
let new_count_u16 = u16::try_from(new_count)
.map_err(|_| Error::Invalid("program header count exceeds u16".to_owned()))?;
let header_offset = checked_index(
self.program_header_offset,
self.program_header_count,
self.program_header_size,
)?;
let header_end = header_offset
.checked_add(self.program_header_size)
.ok_or_else(|| Error::Invalid("new program header range overflow".to_owned()))?;
slice(output, header_offset, self.program_header_size)?;
let first_file_section = self
.section_headers
.iter()
.filter(|section| section.section_type != SHT_NOBITS && section.size != 0)
.map(|section| section.offset)
.min();
if first_file_section.is_some_and(|offset| header_end as u64 > offset) {
return invalid("no space for an additional program header");
}
let mut header = [0_u8; 0x38];
header[0..4].copy_from_slice(&PT_LOAD.to_le_bytes());
header[4..8].copy_from_slice(&segment.flags.to_le_bytes());
header[8..0x10].copy_from_slice(&segment.offset.to_le_bytes());
header[0x10..0x18].copy_from_slice(&segment.virtual_address.to_le_bytes());
header[0x18..0x20].copy_from_slice(&segment.virtual_address.to_le_bytes());
header[0x20..0x28].copy_from_slice(&segment.file_size.to_le_bytes());
header[0x28..0x30].copy_from_slice(&segment.memory_size.to_le_bytes());
header[0x30..0x38].copy_from_slice(&segment.alignment.to_le_bytes());
output
.get_mut(header_offset..header_end)
.ok_or_else(|| Error::Invalid("new program header exceeds output".to_owned()))?
.copy_from_slice(&header);
output
.get_mut(0x38..0x3a)
.ok_or_else(|| Error::Invalid("ELF header is truncated".to_owned()))?
.copy_from_slice(&new_count_u16.to_le_bytes());
let mut updated = self.clone();
updated.program_header_count = new_count;
updated.program_headers.push(segment);
Ok(updated)
}
/// Resolve every section's name from the ELF `shstrtab` section.
///
/// The returned names are source data, not role labels supplied by the
/// caller. Any malformed string-table reference is an input error.
pub fn section_names(&self, data: &[u8]) -> Result<Vec<String>> {
let table = self
.section_headers
.get(self.section_name_index)
.copied()
.ok_or_else(|| Error::Invalid("ELF section-name index is out of range".to_owned()))?;
if table.section_type != SHT_STRTAB {
return invalid(format!(
"ELF section-name table has unexpected type 0x{:x}",
table.section_type
));
}
let strings = slice_u64(data, table.offset, table.size)?;
if strings.is_empty() || strings[0] != 0 {
return invalid("ELF section-name table does not start with NUL");
}
if strings.last().copied() != Some(0) {
return invalid("ELF section-name table is not NUL terminated");
}
self.section_headers
.iter()
.enumerate()
.map(|(index, section)| {
let offset = section.name as usize;
if offset >= strings.len() {
return invalid(format!(
"ELF section {index} name offset 0x{offset:x} exceeds section-name table"
));
}
let end = strings[offset..]
.iter()
.position(|&byte| byte == 0)
.map(|length| offset + length)
.ok_or_else(|| {
Error::Invalid(format!(
"ELF section {index} name at 0x{offset:x} is unterminated"
))
})?;
let name = std::str::from_utf8(&strings[offset..end]).map_err(|error| {
Error::Invalid(format!(
"ELF section {index} name at 0x{offset:x} is not UTF-8: {error}"
))
})?;
if index == 0 && section.name != 0 {
return invalid("ELF null section has a nonzero name offset");
}
Ok(name.to_owned())
})
.collect()
}
pub fn file_offset_to_virtual_address(&self, offset: u64, size: u64) -> Result<u64> {
let end = offset
.checked_add(size)
.ok_or_else(|| Error::Invalid("file range overflow".to_owned()))?;
for segment in &self.program_headers {
let segment_end = segment
.offset
.checked_add(segment.file_size)
.ok_or_else(|| Error::Invalid("PT_LOAD file range overflow".to_owned()))?;
if segment.offset <= offset && end <= segment_end {
return segment
.virtual_address
.checked_add(offset - segment.offset)
.ok_or_else(|| Error::Invalid("virtual address overflow".to_owned()));
}
}
invalid(format!(
"file range 0x{offset:x}..0x{end:x} is not in PT_LOAD"
))
}
}
pub fn slice(data: &[u8], offset: usize, size: usize) -> Result<&[u8]> {
let end = offset
.checked_add(size)
.ok_or_else(|| Error::Invalid("byte range overflow".to_owned()))?;
data.get(offset..end).ok_or_else(|| {
Error::Invalid(format!(
"byte range 0x{offset:x}..0x{end:x} is out of bounds"
))
})
}
pub fn slice_u64(data: &[u8], offset: u64, size: u64) -> Result<&[u8]> {
slice(
data,
usize_from_u64(offset, "file offset")?,
usize_from_u64(size, "file size")?,
)
}
pub fn read_u16(data: &[u8], offset: usize) -> Result<u16> {
let bytes: [u8; 2] = slice(data, offset, 2)?
.try_into()
.map_err(|_| Error::Invalid("invalid u16 range".to_owned()))?;
Ok(u16::from_le_bytes(bytes))
}
pub fn read_u32(data: &[u8], offset: usize) -> Result<u32> {
let bytes: [u8; 4] = slice(data, offset, 4)?
.try_into()
.map_err(|_| Error::Invalid("invalid u32 range".to_owned()))?;
Ok(u32::from_le_bytes(bytes))
}
pub fn read_u64(data: &[u8], offset: usize) -> Result<u64> {
let bytes: [u8; 8] = slice(data, offset, 8)?
.try_into()
.map_err(|_| Error::Invalid("invalid u64 range".to_owned()))?;
Ok(u64::from_le_bytes(bytes))
}
pub fn read_i64(data: &[u8], offset: usize) -> Result<i64> {
let bytes: [u8; 8] = slice(data, offset, 8)?
.try_into()
.map_err(|_| Error::Invalid("invalid i64 range".to_owned()))?;
Ok(i64::from_le_bytes(bytes))
}
pub fn usize_from_u64(value: u64, field: &str) -> Result<usize> {
usize::try_from(value).map_err(|_| Error::Invalid(format!("{field} 0x{value:x} exceeds usize")))
}
pub fn checked_index(base: usize, index: usize, stride: usize) -> Result<usize> {
index
.checked_mul(stride)
.and_then(|value| base.checked_add(value))
.ok_or_else(|| Error::Invalid("table index overflow".to_owned()))
}
pub fn align_up(value: u64, alignment: u64) -> Result<u64> {
if alignment == 0 || !alignment.is_power_of_two() {
return invalid(format!("invalid alignment {alignment}"));
}
value
.checked_add(alignment - 1)
.map(|aligned| aligned & !(alignment - 1))
.ok_or_else(|| Error::Invalid("alignment overflow".to_owned()))
}
#[cfg(test)]
mod tests {
use super::*;
fn layout(name_index: u32) -> ElfLayout {
ElfLayout {
entrypoint: 0,
program_header_offset: 0,
program_header_size: 0x38,
program_header_count: 0,
program_headers: Vec::new(),
section_headers: vec![
SectionHeader {
name: 0,
section_type: 0,
flags: 0,
address: 0,
offset: 0,
size: 0,
link: 0,
info: 0,
alignment: 0,
entry_size: 0,
},
SectionHeader {
name: name_index,
section_type: 1,
flags: 0,
address: 0,
offset: 0,
size: 0,
link: 0,
info: 0,
alignment: 0,
entry_size: 0,
},
SectionHeader {
name: 1,
section_type: SHT_STRTAB,
flags: 0,
address: 0,
offset: 0,
size: 8,
link: 0,
info: 0,
alignment: 1,
entry_size: 0,
},
],
section_name_index: 2,
private_section_index: usize::MAX,
}
}
#[test]
fn section_names_resolve_from_elf_string_table() {
let names = layout(1)
.section_names(b"\0text\0\0\0")
.expect("valid names");
assert_eq!(names, ["", "text", "text"]);
}
#[test]
fn section_names_reject_out_of_range_name_offsets() {
let error = layout(8)
.section_names(b"\0text\0\0\0")
.expect_err("invalid offset");
assert!(error.to_string().contains("exceeds section-name table"));
}
#[test]
fn section_names_reject_invalid_utf8() {
let mut elf_layout = layout(1);
elf_layout.section_headers[1].name = 1;
let error = elf_layout
.section_names(b"\0\xff\0\0\0\0\0\0")
.expect_err("invalid UTF-8");
assert!(error.to_string().contains("is not UTF-8"));
}
#[test]
fn section_names_reject_non_string_table() {
let mut elf_layout = layout(1);
elf_layout.section_headers[2].section_type = 1;
let error = elf_layout
.section_names(b"\0text\0\0\0")
.expect_err("wrong section type");
assert!(error.to_string().contains("unexpected type"));
}
#[test]
fn section_names_reject_unterminated_table() {
let elf_layout = layout(1);
let error = elf_layout
.section_names(b"\0text\0\x01\x01")
.expect_err("unterminated table");
assert!(error.to_string().contains("not NUL terminated"));
}
#[test]
fn append_load_segment_updates_program_headers() {
let elf_layout = ElfLayout {
entrypoint: 0,
program_header_offset: 0,
program_header_size: 0x38,
program_header_count: 0,
program_headers: Vec::new(),
section_headers: Vec::new(),
section_name_index: 0,
private_section_index: usize::MAX,
};
let mut output = vec![0_u8; 0x2000];
let updated = elf_layout
.append_load_segment(
&mut output,
LoadSegment {
offset: 0x1000,
virtual_address: 0x2000,
file_size: 0x20,
memory_size: 0x20,
flags: PF_R,
alignment: 0x1000,
},
)
.expect("append segment");
assert_eq!(updated.program_header_count, 1);
assert_eq!(updated.program_headers[0].virtual_address, 0x2000);
assert_eq!(&output[0..4], &PT_LOAD.to_le_bytes());
assert_eq!(&output[0x38..0x3a], &1_u16.to_le_bytes());
}
#[test]
fn append_load_segment_rejects_program_header_overlap() {
let mut elf_layout = ElfLayout {
entrypoint: 0,
program_header_offset: 0,
program_header_size: 0x38,
program_header_count: 0,
program_headers: Vec::new(),
section_headers: Vec::new(),
section_name_index: 0,
private_section_index: usize::MAX,
};
elf_layout.section_headers.push(SectionHeader {
name: 0,
section_type: 1,
flags: 0,
address: 0,
offset: 0x20,
size: 1,
link: 0,
info: 0,
alignment: 1,
entry_size: 0,
});
let mut output = vec![0_u8; 0x100];
let error = elf_layout
.append_load_segment(
&mut output,
LoadSegment {
offset: 0x80,
virtual_address: 0x1080,
file_size: 0x20,
memory_size: 0x20,
flags: PF_R,
alignment: 0x1000,
},
)
.expect_err("overlapping program header");
assert!(error.to_string().contains("additional program header"));
}
}
senbei-elf/src/lib.rs
+129
View File
@@ -0,0 +1,129 @@
//! Basic ELF format parsing shared by the unpacking engine.
use goblin::elf::{Elf, header::EM_AARCH64, program_header::PT_LOAD};
use thiserror::Error;
pub mod hash;
pub mod layout;
pub use hash::{build_gnu_hash, build_sysv_hash};
pub use layout::{
ElfLayout, LoadSegment, PF_R, SHF_ALLOC, SHT_LOUSER, SHT_NOBITS, SectionHeader, align_up,
checked_index, read_i64, read_u16, read_u32, read_u64, slice, slice_u64, usize_from_u64,
};
/// ELF machine identifier for AArch64.
pub const AARCH64_MACHINE: u16 = EM_AARCH64;
/// Dynamic sections required by the restored AArch64 loader image.
pub const DYNAMIC_SECTION_NAMES: [&str; 8] = [
".dynsym",
".gnu.version",
".gnu.version_r",
".gnu.hash",
".dynstr",
".rela.dyn",
".rela.plt",
".dynamic",
];
/// Dynamic sections needed to identify a protected image before extraction.
pub const PROBE_SECTION_NAMES: [&str; 5] = [
".dynsym",
".dynstr",
".gnu.hash",
".gnu.version",
".gnu.version_r",
];
/// ELF64 dynamic table record sizes.
pub const ELF64_SYMBOL_SIZE: usize = 0x18;
pub const ELF64_RELA_SIZE: usize = 0x18;
/// AArch64 relocation kinds used by the dynamic linker.
pub const R_AARCH64_ABS64: u32 = 0x101;
pub const R_AARCH64_GLOB_DAT: u32 = 0x401;
pub const R_AARCH64_JUMP_SLOT: u32 = 0x402;
pub const R_AARCH64_RELATIVE: u32 = 0x403;
pub const VER_NDX_GLOBAL: u16 = 1;
/// ELF dynamic-table tag identifiers used by restored images.
pub const DT_PLTRELSZ: u64 = 2;
pub const DT_HASH: u64 = 4;
pub const DT_STRTAB: u64 = 5;
pub const DT_SYMTAB: u64 = 6;
pub const DT_RELA: u64 = 7;
pub const DT_RELASZ: u64 = 8;
pub const DT_STRSZ: u64 = 10;
pub const DT_JMPREL: u64 = 23;
pub const DT_GNU_HASH: u64 = 0x6fff_fef5;
pub const DT_VERSYM: u64 = 0x6fff_fff0;
pub const DT_RELACOUNT: u64 = 0x6fff_fff9;
pub const DT_VERNEED: u64 = 0x6fff_fffe;
#[derive(Debug, Error)]
pub enum Error {
#[error("ELF parse failed: {0}")]
Parse(#[from] goblin::error::Error),
#[error("input is not an ELF64 little-endian image")]
NotElf64,
#[error("input is not an AArch64 image")]
NotAarch64,
#[error("invalid ELF layout: {0}")]
Invalid(String),
}
pub type Result<T> = std::result::Result<T, Error>;
/// Parse an ELF64 little-endian image.
pub fn parse(data: &[u8]) -> Result<Elf<'_>> {
let elf = Elf::parse(data)?;
if elf.header.e_ident[4] != 2 || elf.header.e_ident[5] != 1 {
return Err(Error::NotElf64);
}
Ok(elf)
}
/// Return true when `data` starts with a valid AArch64 ELF64 image.
pub fn is_aarch64(data: &[u8]) -> bool {
parse(data)
.map(|elf| elf.header.e_machine == EM_AARCH64)
.unwrap_or(false)
}
/// Return whether a short prefix identifies an ELF64 little-endian AArch64
/// image. This is intentionally a prefix-only check for filesystem scanners;
/// callers that need structural guarantees must use [`parse`].
#[must_use]
pub fn is_aarch64_prefix(data: &[u8]) -> bool {
data.get(0..6) == Some(b"\x7fELF\x02\x01")
&& data
.get(18..20)
.is_some_and(|bytes| u16::from_le_bytes([bytes[0], bytes[1]]) == EM_AARCH64)
}
/// Return the maximum file end among PT_LOAD segments.
pub fn load_file_end(data: &[u8]) -> Result<u64> {
let elf = parse(data)?;
Ok(elf
.program_headers
.iter()
.filter(|ph| ph.p_type == PT_LOAD)
.map(|ph| ph.p_offset.saturating_add(ph.p_filesz))
.max()
.unwrap_or(0))
}
pub(crate) fn invalid<T>(message: impl Into<String>) -> Result<T> {
Err(Error::Invalid(message.into()))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn rejects_non_elf() {
assert!(matches!(parse(b"not elf"), Err(Error::Parse(_))));
}
}
senbei-android-elf/Cargo.toml → senbei-engine/Cargo.toml
+5 -3
View File
@@ -1,10 +1,10 @@
[package]
name = "senbei-android-elf"
name = "senbei-engine"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
description = "AArch64 ELF restoration for Senbei Android"
description = "Platform unpacking engines for Senbei"
[dependencies]
memmap2.workspace = true
@@ -13,7 +13,9 @@ serde_json.workspace = true
sha2.workspace = true
tempfile.workspace = true
thiserror.workspace = true
senbei-android-crypto.workspace = true
senbei-crypto.workspace = true
senbei-elf.workspace = true
senbei-pe.workspace = true
[lints]
workspace = true
senbei-engine/src/android/common.rs
+32
View File
@@ -0,0 +1,32 @@
//! Shared Android engine filesystem and digest helpers.
use std::io::Write;
use std::path::{Path, PathBuf};
use sha2::{Digest, Sha256};
use tempfile::NamedTempFile;
pub(crate) fn absolute(path: &Path) -> std::io::Result<PathBuf> {
if path.is_absolute() {
Ok(path.to_path_buf())
} else {
std::env::current_dir().map(|current| current.join(path))
}
}
pub(crate) fn write_atomic(path: &Path, data: &[u8]) -> std::io::Result<()> {
let parent = path.parent().unwrap_or_else(|| Path::new("."));
std::fs::create_dir_all(parent)?;
let mut temporary = NamedTempFile::new_in(parent)?;
temporary.write_all(data)?;
temporary.as_file().sync_all()?;
temporary.persist(path).map_err(|error| error.error)?;
Ok(())
}
#[must_use]
pub(crate) fn sha256(data: &[u8]) -> String {
let mut digest = Sha256::new();
digest.update(data);
senbei_crypto::hex_digest(&digest.finalize())
}
senbei-android-engine/src/error.rs → senbei-engine/src/android/extract/error.rs
+4 -4
View File
@@ -14,12 +14,12 @@ pub enum Error {
Elf {
path: PathBuf,
#[source]
source: goblin::error::Error,
source: senbei_elf::Error,
},
#[error("serialize extraction index: {0}")]
Json(#[from] serde_json::Error),
#[error("embedded Stage 2 decoder configuration: {0}")]
EmbeddedConfig(#[source] senbei_android_crypto::Error),
EmbeddedConfig(#[source] senbei_crypto::android::Error),
#[error(
"depth {depth} stream 0x{stream_id:02X} interpreter 0x{interpreter_id:02X} configuration: {source}"
)]
@@ -28,7 +28,7 @@ pub enum Error {
stream_id: u32,
interpreter_id: u32,
#[source]
source: senbei_android_crypto::Error,
source: senbei_crypto::android::Error,
},
#[error(
"depth {depth} stream 0x{stream_id:02X} record {record_index} command 0x{command_id:02X} {part}: {source}"
@@ -40,7 +40,7 @@ pub enum Error {
command_id: u32,
part: &'static str,
#[source]
source: senbei_android_crypto::Error,
source: senbei_crypto::android::Error,
},
#[error("{0}")]
Invalid(String),
senbei-android-engine/src/lib.rs → senbei-engine/src/android/extract/mod.rs
+2 -4
View File
@@ -1,14 +1,12 @@
//! Pure-static Stage 1 decryption and recursive Stage 2 module extraction.
mod error;
mod extract;
mod pipeline;
mod probe;
mod report;
mod stage1;
mod stream;
pub use error::Error;
pub use extract::{ExtractOptions, extract_stage2};
pub use pipeline::{ExtractOptions, extract_stage2};
pub use probe::is_protected_libil2cpp;
pub use report::ExtractionReport;
pub use stage1::{DEFAULT_CIPHER_CONSTANT, DEFAULT_OUTER_SIZE};
senbei-android-engine/src/extract.rs → senbei-engine/src/android/extract/pipeline.rs
+12 -42
View File
@@ -1,23 +1,21 @@
use std::collections::{BTreeMap, BTreeSet, HashSet};
use std::fs::{File, create_dir_all};
use std::io::Write;
use std::fs::File;
use std::path::{Path, PathBuf};
use memmap2::MmapOptions;
use senbei_android_crypto::{Module9bConfig, decode_container};
use senbei_crypto::android::{Module9bConfig, decode_container};
use serde_json::to_vec_pretty;
use sha2::{Digest, Sha256};
use tempfile::NamedTempFile;
use crate::error::{Error, Result, invalid};
use crate::report::{
use super::super::common;
use super::error::{Error, Result, invalid};
use super::report::{
ArtifactReport, DecoderReport, ExtractionReport, ModuleRegistryEntry, RecordReport,
Stage1Report, StreamParent, StreamReport,
};
use crate::stage1::{
use super::stage1::{
DEFAULT_CIPHER_CONSTANT, DEFAULT_OUTER_SIZE, SHT_LOUSER, Stage1Result, inspect,
};
use crate::stream::{DIRECT_FLAG, Record, parse_record_stream};
use super::stream::{DIRECT_FLAG, Record, parse_record_stream};
/// Inputs and output locations for one complete static Stage 2 extraction.
#[derive(Debug, Clone)]
@@ -86,7 +84,7 @@ pub fn extract_stage2(options: &ExtractOptions) -> Result<ExtractionReport> {
return invalid("refusing to overwrite the protected ELF with Stage 2 output");
}
}
create_dir_all(&output_dir)
std::fs::create_dir_all(&output_dir)
.map_err(|source| Error::io("create Stage 2 output directory", &output_dir, source))?;
let file = File::open(&input_path)
@@ -497,42 +495,14 @@ fn write_json_atomic(path: &Path, value: &impl serde::Serialize) -> Result<()> {
}
fn write_atomic(path: &Path, data: &[u8]) -> Result<()> {
let parent = path.parent().unwrap_or_else(|| Path::new("."));
create_dir_all(parent)
.map_err(|source| Error::io("create output directory", parent, source))?;
let mut temporary = NamedTempFile::new_in(parent)
.map_err(|source| Error::io("create temporary output", parent, source))?;
temporary
.write_all(data)
.and_then(|()| temporary.as_file().sync_all())
.map_err(|source| Error::io("write temporary output", temporary.path(), source))?;
temporary
.persist(path)
.map_err(|error| Error::io("replace output", path, error.error))?;
Ok(())
common::write_atomic(path, data)
.map_err(|source| Error::io("write temporary output", path, source))
}
fn absolute(path: &Path) -> Result<PathBuf> {
if path.is_absolute() {
Ok(path.to_path_buf())
} else {
std::env::current_dir()
.map(|current| current.join(path))
.map_err(|source| Error::io("query current directory", path, source))
}
common::absolute(path).map_err(|source| Error::io("query current directory", path, source))
}
fn sha256(data: &[u8]) -> String {
let mut digest = Sha256::new();
digest.update(data);
hex_digest(&digest.finalize())
}
/// Lowercase hex of a digest output (sha2 0.11's `Array` no longer formats as
/// hex directly).
fn hex_digest(data: &[u8]) -> String {
let mut out = String::with_capacity(data.len() * 2);
for byte in data {
out.push_str(&format!("{byte:02x}"));
}
out
common::sha256(data)
}
senbei-android-engine/src/probe.rs → senbei-engine/src/android/extract/probe.rs
+2 -5
View File
@@ -1,15 +1,12 @@
use std::path::Path;
use senbei_android_crypto::Module9bConfig;
use senbei_crypto::android::Module9bConfig;
use crate::stage1::{self, DEFAULT_CIPHER_CONSTANT, DEFAULT_OUTER_SIZE};
use super::stage1::{self, DEFAULT_CIPHER_CONSTANT, DEFAULT_OUTER_SIZE};
/// Return whether `data` has a supported protected AArch64 IL2CPP layout.
#[must_use]
pub fn is_protected_libil2cpp(data: &[u8]) -> bool {
if !stage1::looks_protected(data) {
return false;
}
let Ok(stage1) = stage1::inspect(
data,
Path::new("<probe>"),
senbei-android-engine/src/report.rs → senbei-engine/src/android/extract/report.rs
View File
senbei-android-engine/src/stage1.rs → senbei-engine/src/android/extract/stage1.rs
+18 -44
View File
@@ -1,44 +1,13 @@
use std::path::Path;
use goblin::elf::{Elf, header::EM_AARCH64};
use senbei_elf::{AARCH64_MACHINE, Error as ElfError, parse};
use crate::error::{Error, Result, invalid};
use super::error::{Error, Result, invalid};
pub(crate) const SHT_LOUSER: u32 = 0x8000_0000;
pub(crate) use senbei_elf::SHT_LOUSER;
pub const DEFAULT_CIPHER_CONSTANT: u32 = 0xbf20_165d;
pub const DEFAULT_OUTER_SIZE: usize = 0x23c;
pub(crate) fn looks_protected(data: &[u8]) -> bool {
let Ok(elf) = Elf::parse(data) else {
return false;
};
if elf.header.e_machine != EM_AARCH64
|| elf
.section_headers
.iter()
.filter(|section| section.sh_type == SHT_LOUSER)
.count()
!= 1
{
return false;
}
[
".dynsym",
".dynstr",
".gnu.hash",
".gnu.version",
".gnu.version_r",
]
.into_iter()
.all(|wanted| {
elf.section_headers.iter().any(|section| {
elf.shdr_strtab
.get_at(section.sh_name)
.is_some_and(|name| name == wanted)
})
})
}
#[derive(Debug, Clone, Copy)]
pub(crate) struct Stage1Header {
pub key: u32,
@@ -70,13 +39,13 @@ pub(crate) fn inspect(
outer_size: usize,
cipher_constant: u32,
) -> Result<Stage1Result> {
let elf = Elf::parse(data).map_err(|source| Error::Elf {
let elf = parse(data).map_err(|source: ElfError| Error::Elf {
path: path.to_path_buf(),
source,
})?;
if elf.header.e_machine != EM_AARCH64 {
if elf.header.e_machine != AARCH64_MACHINE {
return invalid(format!(
"expected AArch64 ELF (machine 0x{EM_AARCH64:X}), got 0x{:X}",
"expected AArch64 ELF (machine 0x{AARCH64_MACHINE:X}), got 0x{:X}",
elf.header.e_machine
));
}
@@ -92,6 +61,15 @@ pub(crate) fn inspect(
matches.len()
));
}
for wanted in senbei_elf::PROBE_SECTION_NAMES {
if !elf.section_headers.iter().any(|section| {
elf.shdr_strtab
.get_at(section.sh_name)
.is_some_and(|name| name == wanted)
}) {
return invalid(format!("protected ELF lacks required section {wanted}"));
}
}
let (section_index, section) = matches[0];
let section_offset = usize::try_from(section.sh_offset)
.map_err(|_| Error::Invalid("SHT_LOUSER offset exceeds usize".to_owned()))?;
@@ -199,18 +177,14 @@ fn decrypt_header(raw: &[u8], constant: u32) -> Result<Stage1Header> {
}
fn decrypt_words(ciphertext: &[u8], key: u32, constant: u32) -> Result<Vec<u8>> {
if ciphertext.len() % 4 != 0 {
if !ciphertext.len().is_multiple_of(4) {
return invalid("Stage 1 word cipher input is not 4-byte aligned");
}
let mut plaintext = ciphertext.to_vec();
for (index, chunk) in plaintext.chunks_exact_mut(4).enumerate() {
for (index, chunk) in plaintext.as_chunks_mut::<4>().0.iter_mut().enumerate() {
let index = u32::try_from(index)
.map_err(|_| Error::Invalid("Stage 1 word index exceeds u32".to_owned()))?;
let mut word = u32::from_le_bytes(
chunk
.try_into()
.map_err(|_| Error::Invalid("Stage 1 word has an invalid size".to_owned()))?,
);
let mut word = u32::from_le_bytes(*chunk);
word = word.wrapping_add(index.wrapping_add(3).wrapping_mul(key));
word ^= constant.wrapping_mul(index.wrapping_add(1));
chunk.copy_from_slice(&word.to_le_bytes());
senbei-android-engine/src/stream.rs → senbei-engine/src/android/extract/stream.rs
+4 -8
View File
@@ -1,6 +1,6 @@
use senbei_android_crypto::gf32_mul_fixed;
use senbei_crypto::android::gf32_mul_fixed;
use crate::error::{Error, Result, invalid};
use super::error::{Error, Result, invalid};
pub(crate) const RECORD_SIZE: usize = 0x5c;
pub(crate) const DIRECT_FLAG: u32 = 2;
@@ -130,13 +130,9 @@ fn decrypt_record(raw: &[u8], index: usize, state: u32) -> Result<Record> {
let mut accumulator = 0x7993_4cf6_u32;
let mut feedback = 0xf02f_7685_u32;
let mut words = [0_u32; RECORD_SIZE / 4];
for (word_index, chunk) in raw.chunks_exact(4).enumerate() {
for (word_index, chunk) in raw.as_chunks::<4>().0.iter().enumerate() {
feedback = feedback.wrapping_mul(feedback);
let cipher = u32::from_le_bytes(
chunk
.try_into()
.map_err(|_| Error::Invalid("record word has an invalid size".to_owned()))?,
);
let cipher = u32::from_le_bytes(*chunk);
let mut value = gf32_mul_fixed(cipher ^ (feedback >> 3)) ^ index_mask;
value = value.wrapping_add(accumulator).wrapping_add(state);
value = value.wrapping_sub(mix >> ((word_index * 4 + 3) & 5));
senbei-engine/src/android/mod.rs
+11
View File
@@ -0,0 +1,11 @@
//! Android AArch64 extraction and ELF restoration.
mod common;
mod extract;
mod restore;
pub use extract::{
DEFAULT_CIPHER_CONSTANT, DEFAULT_OUTER_SIZE, Error as ExtractionError, ExtractOptions,
ExtractionReport, extract_stage2, is_protected_libil2cpp,
};
pub use restore::{Error as RestoreError, RestoreOptions, RestoreReport, restore_libil2cpp};
senbei-android-elf/src/artifact.rs → senbei-engine/src/android/restore/artifact.rs
+1 -1
View File
@@ -3,7 +3,7 @@ use std::path::{Path, PathBuf};
use serde_json::Value;
use crate::error::{Error, Result, invalid};
use super::error::{Error, Result, invalid};
const REQUIRED_IDS: [u32; 3] = [0x9b, 0x9d, 0x9e];
senbei-android-elf/src/error.rs → senbei-engine/src/android/restore/error.rs
+3 -1
View File
@@ -13,7 +13,9 @@ pub enum Error {
#[error("cannot parse module index: {0}")]
Json(#[from] serde_json::Error),
#[error(transparent)]
Crypto(#[from] senbei_android_crypto::Error),
Crypto(#[from] senbei_crypto::android::Error),
#[error(transparent)]
Elf(#[from] senbei_elf::Error),
#[error("{0}")]
Invalid(String),
}
senbei-engine/src/android/restore/mod.rs
+6
View File
@@ -0,0 +1,6 @@
mod artifact;
mod error;
mod pipeline;
pub use error::Error;
pub use pipeline::{RestoreOptions, RestoreReport, restore_libil2cpp};
senbei-android-elf/src/restore.rs → senbei-engine/src/android/restore/pipeline.rs
+360 -128
View File
@@ -5,42 +5,26 @@ use std::path::{Path, PathBuf};
use std::time::Instant;
use memmap2::{Mmap, MmapMut, MmapOptions};
use senbei_android_crypto::{
use senbei_crypto::android::{
ContainerHeader, HuffmanLzDecoder, Module9bConfig, ProtectedDescriptor, transform_segment,
};
use serde::Serialize;
use sha2::{Digest, Sha256};
use tempfile::NamedTempFile;
use crate::artifact::load_artifacts;
use crate::error::{Error, Result, invalid};
use crate::hash::{build_gnu_hash, build_sysv_hash};
use crate::layout::{
ElfLayout, SHF_ALLOC, SHT_LOUSER, SHT_NOBITS, SectionHeader, align_up, read_i64, read_u32,
read_u64, slice, slice_u64, usize_from_u64,
use super::super::common;
use super::artifact::load_artifacts;
use super::error::{Error, Result, invalid};
use senbei_elf::{
DT_GNU_HASH, DT_HASH, DT_JMPREL, DT_PLTRELSZ, DT_RELA, DT_RELACOUNT, DT_RELASZ, DT_STRSZ,
DT_STRTAB, DT_SYMTAB, DT_VERNEED, DT_VERSYM, ELF64_RELA_SIZE, ELF64_SYMBOL_SIZE, ElfLayout,
LoadSegment, PF_R, R_AARCH64_ABS64, R_AARCH64_GLOB_DAT, R_AARCH64_JUMP_SLOT,
R_AARCH64_RELATIVE, SHF_ALLOC, SHT_LOUSER, SHT_NOBITS, SectionHeader, VER_NDX_GLOBAL, align_up,
build_gnu_hash, build_sysv_hash, read_i64, read_u32, read_u64, slice, slice_u64,
usize_from_u64,
};
const CHUNK_SIZE: usize = 16 * 1024 * 1024;
const ELF64_SYMBOL_SIZE: usize = 0x18;
const ELF64_RELA_SIZE: usize = 0x18;
const R_AARCH64_ABS64: u32 = 0x101;
const R_AARCH64_GLOB_DAT: u32 = 0x401;
const R_AARCH64_JUMP_SLOT: u32 = 0x402;
const R_AARCH64_RELATIVE: u32 = 0x403;
const VER_NDX_GLOBAL: u16 = 1;
const DT_PLTRELSZ: u64 = 2;
const DT_HASH: u64 = 4;
const DT_STRTAB: u64 = 5;
const DT_SYMTAB: u64 = 6;
const DT_RELA: u64 = 7;
const DT_RELASZ: u64 = 8;
const DT_STRSZ: u64 = 10;
const DT_JMPREL: u64 = 23;
const DT_GNU_HASH: u64 = 0x6fff_fef5;
const DT_VERSYM: u64 = 0x6fff_fff0;
const DT_RELACOUNT: u64 = 0x6fff_fff9;
const DT_VERNEED: u64 = 0x6fff_fffe;
/// Inputs and optional diagnostics for one `libil2cpp.so` restoration.
#[derive(Debug, Clone)]
@@ -100,6 +84,12 @@ pub struct PlacementReport {
pub size: usize,
}
struct TablePayload {
name: &'static str,
alignment: u64,
data: Vec<u8>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct ElfMaterializationReport {
pub hidden_symbols: HiddenSymbolReport,
@@ -181,9 +171,7 @@ fn read_file(path: &Path) -> Result<Vec<u8>> {
}
fn sha256_bytes(data: &[u8]) -> String {
let mut digest = Sha256::new();
digest.update(data);
hex_digest(&digest.finalize())
common::sha256(data)
}
fn sha256_file(path: &Path) -> Result<String> {
@@ -199,7 +187,7 @@ fn sha256_file(path: &Path) -> Result<String> {
}
digest.update(&buffer[..read]);
}
Ok(hex_digest(&digest.finalize()))
Ok(senbei_crypto::hex_digest(&digest.finalize()))
}
fn copy_range(source: &[u8], output: &mut File, size: usize, path: &Path) -> Result<()> {
@@ -280,7 +268,7 @@ impl FileLayoutWriter<'_> {
"decoded write 0x{virtual_address:x}..0x{end:x} is not covered by PT_LOAD memory"
));
}
usize_from_u64(written, "written byte count")
Ok(usize_from_u64(written, "written byte count")?)
}
}
@@ -432,6 +420,9 @@ impl AuxiliaryElfImage {
relocation2_offset: words[10],
relocation2_count: words[11],
};
if result.dynsym_count == 0 {
return invalid("auxiliary dynamic symbol table has no null entry");
}
if result.relocation1_offset != 0x40 {
return invalid("auxiliary relocation table does not follow its header");
}
@@ -470,9 +461,6 @@ impl AuxiliaryElfImage {
));
}
}
if result.dynsym_count < 2 {
return invalid("auxiliary dynamic symbol table is empty");
}
if slice(data, result.dynsym_offset as usize, ELF64_SYMBOL_SIZE)?
.iter()
.any(|&byte| byte != 0)
@@ -489,7 +477,8 @@ fn restore_hidden_symbols(
dynstr: SectionHeader,
patch_data: &[u8],
) -> Result<(Vec<u8>, Vec<u8>, HiddenSymbolReport)> {
if dynsym.entry_size != ELF64_SYMBOL_SIZE as u64 || dynsym.size % ELF64_SYMBOL_SIZE as u64 != 0
if dynsym.entry_size != ELF64_SYMBOL_SIZE as u64
|| !dynsym.size.is_multiple_of(ELF64_SYMBOL_SIZE as u64)
{
return invalid("unexpected .dynsym entry layout");
}
@@ -596,11 +585,13 @@ fn restore_hidden_symbols(
}
fn dynamic_symbol_names(symbols: &[u8], strings: &[u8]) -> Result<Vec<Vec<u8>>> {
if symbols.len() % ELF64_SYMBOL_SIZE != 0 {
if !symbols.len().is_multiple_of(ELF64_SYMBOL_SIZE) {
return invalid("dynamic symbol table is not entry-aligned");
}
symbols
.chunks_exact(ELF64_SYMBOL_SIZE)
.as_chunks::<ELF64_SYMBOL_SIZE>()
.0
.iter()
.map(|symbol| {
let name_offset = read_u32(symbol, 0)? as usize;
Ok(read_c_string(strings, name_offset, strings.len())?.to_vec())
@@ -710,7 +701,7 @@ fn patch_dynamic_tags(
dynamic: SectionHeader,
values: &BTreeMap<u64, u64>,
) -> Result<()> {
if dynamic.size % 0x10 != 0 {
if !dynamic.size.is_multiple_of(0x10) {
return invalid(".dynamic size is not entry-aligned");
}
let start = usize_from_u64(dynamic.offset, ".dynamic offset")?;
@@ -743,20 +734,31 @@ fn patch_dynamic_tags(
Ok(())
}
fn dynamic_contains_tag(output: &[u8], dynamic: SectionHeader, wanted: u64) -> Result<bool> {
if !dynamic.size.is_multiple_of(0x10) {
return invalid(".dynamic size is not entry-aligned");
}
let start = usize_from_u64(dynamic.offset, ".dynamic offset")?;
let size = usize_from_u64(dynamic.size, ".dynamic size")?;
let end = start
.checked_add(size)
.ok_or_else(|| Error::Invalid(".dynamic end overflow".to_owned()))?;
slice(output, start, size)?;
for offset in (start..end).step_by(0x10) {
let tag = read_u64(output, offset)?;
if tag == wanted {
return Ok(true);
}
if tag == 0 {
break;
}
}
Ok(false)
}
fn required_section_indices(names: &[String]) -> Result<HashMap<&'static str, usize>> {
const REQUIRED: [&str; 9] = [
".dynsym",
".gnu.version",
".gnu.version_r",
".gnu.hash",
".dynstr",
".rela.dyn",
".rela.plt",
".dynamic",
".rodata",
];
let mut result = HashMap::with_capacity(REQUIRED.len());
for required in REQUIRED {
let mut result = HashMap::with_capacity(senbei_elf::DYNAMIC_SECTION_NAMES.len());
for required in senbei_elf::DYNAMIC_SECTION_NAMES {
let indices = names
.iter()
.enumerate()
@@ -785,13 +787,182 @@ fn required_section_indices(names: &[String]) -> Result<HashMap<&'static str, us
Ok(result)
}
fn metadata_capacity_end(
layout: &ElfLayout,
indices: &HashMap<&'static str, usize>,
metadata_start: u64,
) -> Result<u64> {
let table_indices = indices.values().copied().collect::<HashSet<_>>();
let file_end = layout.private_section()?.offset;
let next_section = layout
.section_headers
.iter()
.enumerate()
.filter(|(index, section)| {
!table_indices.contains(index)
&& section.section_type != SHT_NOBITS
&& section.size != 0
&& section.offset >= metadata_start
})
.map(|(_, section)| section.offset)
.min()
.unwrap_or(file_end);
let capacity_end = next_section.min(file_end);
// A zero-length window is a valid result: the caller can move the whole
// table set to a new PT_LOAD instead of overwriting an adjacent section.
Ok(capacity_end.max(metadata_start))
}
fn metadata_mapping_length(
source: &[u8],
layout: &ElfLayout,
auxiliary_data: &[u8],
) -> Result<usize> {
let names = layout.section_names(source)?;
let indices = required_section_indices(&names)?;
let section = |name: &'static str| -> SectionHeader { layout.section_headers[indices[name]] };
let dynsym = section(".dynsym");
let versym = section(".gnu.version");
let verneed = section(".gnu.version_r");
let dynstr = section(".dynstr");
let rela_dyn = section(".rela.dyn");
let rela_plt = section(".rela.plt");
if dynsym.entry_size != ELF64_SYMBOL_SIZE as u64
|| dynsym.size % ELF64_SYMBOL_SIZE as u64 != 0
|| versym.entry_size != 2
|| rela_dyn.entry_size != ELF64_RELA_SIZE as u64
|| rela_plt.entry_size != ELF64_RELA_SIZE as u64
|| rela_dyn.size % ELF64_RELA_SIZE as u64 != 0
|| rela_plt.size % ELF64_RELA_SIZE as u64 != 0
{
return invalid("unexpected dynamic-table entry layout");
}
let auxiliary = AuxiliaryElfImage::parse(auxiliary_data)?;
let old_symbol_count = usize_from_u64(
dynsym.size / ELF64_SYMBOL_SIZE as u64,
"dynamic symbol count",
)?;
let appended_count =
usize::try_from(auxiliary.dynsym_count.checked_sub(1).ok_or_else(|| {
Error::Invalid("auxiliary symbol table has no null entry".to_owned())
})?)
.map_err(|_| Error::Invalid("auxiliary symbol count exceeds usize".to_owned()))?;
let new_symbol_count = old_symbol_count
.checked_add(appended_count)
.ok_or_else(|| Error::Invalid("merged dynamic symbol count overflow".to_owned()))?;
let merged_dynstr_size = usize_from_u64(dynstr.size, ".dynstr size")?
.checked_add(auxiliary.dynstr_size as usize)
.ok_or_else(|| Error::Invalid("merged dynamic string size overflow".to_owned()))?;
let merged_rela_dyn_count =
usize_from_u64(rela_dyn.size / ELF64_RELA_SIZE as u64, ".rela.dyn count")?
.checked_add(auxiliary.relocation1_count as usize)
.and_then(|count| count.checked_add(auxiliary.relocation2_count as usize))
.ok_or_else(|| Error::Invalid("merged .rela.dyn count overflow".to_owned()))?;
let merged_rela_plt_count =
usize_from_u64(rela_plt.size / ELF64_RELA_SIZE as u64, ".rela.plt count")?
.checked_add(auxiliary.relocation2_count as usize)
.ok_or_else(|| Error::Invalid("merged .rela.plt count overflow".to_owned()))?;
let gnu_hash_size = 28_usize
.checked_add(
new_symbol_count
.checked_sub(1)
.ok_or_else(|| {
Error::Invalid("dynamic symbol table is unexpectedly empty".to_owned())
})?
.checked_mul(4)
.ok_or_else(|| Error::Invalid("GNU hash size overflow".to_owned()))?,
)
.ok_or_else(|| Error::Invalid("GNU hash size overflow".to_owned()))?;
let sysv_hash_size = indices.contains_key(".hash").then(|| {
new_symbol_count
.checked_mul(2)
.and_then(|count| count.checked_add(2))
.and_then(|count| count.checked_mul(4))
.ok_or_else(|| Error::Invalid("SysV hash size overflow".to_owned()))
});
let sysv_hash_size = match sysv_hash_size {
Some(size) => size?,
None => 0,
};
let mut cursor = 0_u64;
for (size, alignment) in [
(
new_symbol_count
.checked_mul(ELF64_SYMBOL_SIZE)
.ok_or_else(|| Error::Invalid("merged .dynsym size overflow".to_owned()))?,
8,
),
(
usize_from_u64(versym.size, ".gnu.version size")?
.checked_add(appended_count.checked_mul(2).ok_or_else(|| {
Error::Invalid("merged .gnu.version size overflow".to_owned())
})?)
.ok_or_else(|| Error::Invalid("merged .gnu.version size overflow".to_owned()))?,
2,
),
(usize_from_u64(verneed.size, ".gnu.version_r size")?, 4),
(gnu_hash_size, 8),
(sysv_hash_size, 4),
(merged_dynstr_size, 1),
(
merged_rela_dyn_count
.checked_mul(ELF64_RELA_SIZE)
.ok_or_else(|| Error::Invalid("merged .rela.dyn size overflow".to_owned()))?,
8,
),
(
merged_rela_plt_count
.checked_mul(ELF64_RELA_SIZE)
.ok_or_else(|| Error::Invalid("merged .rela.plt size overflow".to_owned()))?,
8,
),
] {
cursor = align_up(cursor, alignment)?;
cursor = cursor
.checked_add(size as u64)
.ok_or_else(|| Error::Invalid("dynamic-table reserve overflow".to_owned()))?;
}
let extension_alignment = layout.load_alignment()?;
let extension_start = align_up(layout.private_section()?.offset, extension_alignment)?;
let end = extension_start
.checked_add(cursor)
.ok_or_else(|| Error::Invalid("dynamic-table mapping end overflow".to_owned()))?;
Ok(usize_from_u64(end, "dynamic-table mapping length")?)
}
fn table_placements(
tables: &[TablePayload],
start: u64,
) -> Result<(BTreeMap<String, PlacementReport>, u64)> {
let mut cursor = start;
let mut placements = BTreeMap::new();
for table in tables {
cursor = align_up(cursor, table.alignment)?;
placements.insert(
table.name.to_owned(),
PlacementReport {
offset: cursor,
size: table.data.len(),
},
);
cursor = cursor
.checked_add(table.data.len() as u64)
.ok_or_else(|| Error::Invalid("rebuilt ELF metadata end overflow".to_owned()))?;
}
Ok((placements, cursor))
}
fn table_end(tables: &[TablePayload], start: u64) -> Result<u64> {
table_placements(tables, start).map(|(_, end)| end)
}
fn materialize_static_elf_tables(
output: &mut [u8],
source: &[u8],
layout: &ElfLayout,
symbol_patch_data: &[u8],
auxiliary_data: &[u8],
) -> Result<(ElfLayout, ElfMaterializationReport)> {
) -> Result<(ElfLayout, ElfMaterializationReport, u64)> {
let names = layout.section_names(source)?;
let indices = required_section_indices(&names)?;
let section = |name: &'static str| -> SectionHeader { layout.section_headers[indices[name]] };
@@ -802,7 +973,6 @@ fn materialize_static_elf_tables(
let rela_dyn = section(".rela.dyn");
let rela_plt = section(".rela.plt");
let dynamic = section(".dynamic");
let rodata = section(".rodata");
let (old_symbols, old_strings, hidden_symbols) =
restore_hidden_symbols(output, dynsym, dynstr, symbol_patch_data)?;
@@ -819,7 +989,11 @@ fn materialize_static_elf_tables(
auxiliary.dynstr_offset as usize,
auxiliary.dynstr_size as usize,
)?;
let appended_count = auxiliary.dynsym_count as usize - 1;
let appended_count =
usize::try_from(auxiliary.dynsym_count.checked_sub(1).ok_or_else(|| {
Error::Invalid("auxiliary symbol table has no null entry".to_owned())
})?)
.map_err(|_| Error::Invalid("auxiliary symbol count exceeds usize".to_owned()))?;
let mut appended_symbols = Vec::with_capacity(appended_count * ELF64_SYMBOL_SIZE);
for index in 1..auxiliary.dynsym_count as usize {
let offset = auxiliary.dynsym_offset as usize + index * ELF64_SYMBOL_SIZE;
@@ -926,11 +1100,6 @@ fn materialize_static_elf_tables(
let rela_dyn_count = merged_rela_dyn.len() / ELF64_RELA_SIZE;
let rela_plt_count = merged_rela_plt.len() / ELF64_RELA_SIZE;
struct TablePayload {
name: &'static str,
alignment: u64,
data: Vec<u8>,
}
let mut tables = vec![
TablePayload {
name: ".dynsym",
@@ -977,34 +1146,52 @@ fn materialize_static_elf_tables(
data: merged_rela_plt,
},
]);
let metadata_start = dynsym.offset;
let mut cursor = metadata_start;
let mut placements = BTreeMap::new();
for table in &tables {
cursor = align_up(cursor, table.alignment)?;
placements.insert(
table.name.to_owned(),
PlacementReport {
offset: cursor,
size: table.data.len(),
let mut placement_layout = layout.clone();
let mut metadata_start = dynsym.offset;
let (mut placements, mut cursor) = table_placements(&tables, metadata_start)?;
let mut capacity_end = metadata_capacity_end(layout, &indices, metadata_start)?;
if cursor > capacity_end {
let alignment = layout.load_alignment()?;
let extension_start = align_up(layout.private_section()?.offset, alignment)?;
let extension_end = table_end(&tables, extension_start)?;
let extension_size = extension_end
.checked_sub(extension_start)
.ok_or_else(|| Error::Invalid("dynamic-table extension underflow".to_owned()))?;
let extension_address = align_up(layout.load_end()?, alignment)?;
placement_layout = layout.append_load_segment(
output,
LoadSegment {
offset: extension_start,
virtual_address: extension_address,
file_size: extension_size,
memory_size: extension_size,
flags: PF_R,
alignment,
},
);
cursor = cursor
.checked_add(table.data.len() as u64)
.ok_or_else(|| Error::Invalid("rebuilt ELF metadata end overflow".to_owned()))?;
)?;
metadata_start = extension_start;
(placements, cursor) = table_placements(&tables, metadata_start)?;
capacity_end = cursor;
}
if cursor > rodata.offset {
return invalid(format!(
"rebuilt ELF tables end at 0x{cursor:x}, beyond .rodata 0x{:x}",
rodata.offset
));
}
let zero_start = usize_from_u64(metadata_start, "metadata start")?;
let zero_end = usize_from_u64(rodata.offset, ".rodata offset")?;
let zero_start = usize_from_u64(dynsym.offset, "metadata start")?;
let zero_end = usize_from_u64(
metadata_capacity_end(layout, &indices, dynsym.offset)?,
"metadata capacity end",
)?;
output
.get_mut(zero_start..zero_end)
.ok_or_else(|| Error::Invalid("metadata capacity exceeds output mapping".to_owned()))?
.fill(0);
if metadata_start != dynsym.offset {
let extension_start = usize_from_u64(metadata_start, "dynamic-table extension start")?;
let extension_end = usize_from_u64(cursor, "dynamic-table extension end")?;
output
.get_mut(extension_start..extension_end)
.ok_or_else(|| {
Error::Invalid("dynamic-table extension exceeds output mapping".to_owned())
})?
.fill(0);
}
let mut updated_sections = layout.section_headers.clone();
for table in &tables {
@@ -1021,8 +1208,8 @@ fn materialize_static_elf_tables(
.copy_from_slice(&table.data);
let index = indices[table.name];
let mut updated = updated_sections[index];
updated.address =
layout.file_offset_to_virtual_address(placement.offset, table.data.len() as u64)?;
updated.address = placement_layout
.file_offset_to_virtual_address(placement.offset, table.data.len() as u64)?;
updated.offset = placement.offset;
updated.size = table.data.len() as u64;
updated_sections[index] = updated;
@@ -1039,16 +1226,23 @@ fn materialize_static_elf_tables(
(DT_JMPREL, section_address(".rela.plt")),
(DT_GNU_HASH, section_address(".gnu.hash")),
(DT_VERSYM, section_address(".gnu.version")),
(DT_RELACOUNT, relative_count as u64),
(DT_VERNEED, section_address(".gnu.version_r")),
]);
if dynamic_contains_tag(output, dynamic, DT_RELACOUNT)? {
dynamic_values.insert(DT_RELACOUNT, relative_count as u64);
}
if indices.contains_key(".hash") {
dynamic_values.insert(DT_HASH, section_address(".hash"));
}
patch_dynamic_tags(output, dynamic, &dynamic_values)?;
let mut restored_layout = layout.clone();
let mut restored_layout = placement_layout;
restored_layout.section_headers = updated_sections;
let data_end = if metadata_start == dynsym.offset {
layout.private_section()?.offset
} else {
cursor
};
Ok((
restored_layout,
ElfMaterializationReport {
@@ -1065,10 +1259,11 @@ fn materialize_static_elf_tables(
relative_prefix_count: relative_count,
metadata_start,
metadata_end: cursor,
metadata_capacity_end: rodata.offset,
metadata_slack: rodata.offset - cursor,
metadata_capacity_end: capacity_end,
metadata_slack: capacity_end.saturating_sub(cursor),
placements,
},
data_end,
))
}
@@ -1090,9 +1285,13 @@ fn finalize_clean_elf(
temporary_path: &Path,
source: &[u8],
layout: &ElfLayout,
data_start: u64,
preserve_entrypoint: bool,
) -> Result<CleaningReport> {
let private = layout.private_section()?;
if data_start < private.offset {
return invalid("ELF data start precedes the private section");
}
let names = layout.section_names(source)?;
if layout.private_section_index + 1 != layout.section_headers.len() {
return invalid("SHT_LOUSER section is not the final section");
@@ -1100,7 +1299,7 @@ fn finalize_clean_elf(
let retained = &layout.section_headers[..layout.private_section_index];
let mut updated = Vec::with_capacity(retained.len());
stream
.seek(SeekFrom::Start(private.offset))
.seek(SeekFrom::Start(data_start))
.map_err(|error| Error::io("seek temporary output", temporary_path, error))?;
for &section in retained {
if section.section_type == SHT_NOBITS || section.flags & SHF_ALLOC != 0 || section.size == 0
@@ -1222,14 +1421,13 @@ fn validate_restored_binary(
rela_plt.size / ELF64_RELA_SIZE as u64,
"restored PLT relocation count",
)?;
if let Some(expected) = materialization {
if dynamic_symbols != expected.new_symbol_count
if let Some(expected) = materialization
&& (dynamic_symbols != expected.new_symbol_count
|| dynamic_relocations != expected.rela_dyn_count
|| pltgot_relocations != expected.rela_plt_count
|| pltgot_relocations != expected.rela_plt_count)
{
return invalid("restored ELF table counts do not match materialization report");
}
}
Ok(ValidationReport {
format: "ELF64".to_owned(),
machine: "AARCH64".to_owned(),
@@ -1243,29 +1441,11 @@ fn validate_restored_binary(
}
fn absolute(path: &Path) -> Result<PathBuf> {
if path.is_absolute() {
Ok(path.to_path_buf())
} else {
std::env::current_dir()
.map(|current| current.join(path))
.map_err(|error| Error::io("query current directory", path, error))
}
common::absolute(path).map_err(|error| Error::io("query current directory", path, error))
}
fn write_atomic(path: &Path, data: &[u8]) -> Result<()> {
let parent = path.parent().unwrap_or_else(|| Path::new("."));
std::fs::create_dir_all(parent)
.map_err(|error| Error::io("create output directory", parent, error))?;
let mut temporary = NamedTempFile::new_in(parent)
.map_err(|error| Error::io("create temporary file", parent, error))?;
temporary
.write_all(data)
.and_then(|_| temporary.as_file().sync_all())
.map_err(|error| Error::io("write temporary file", temporary.path(), error))?;
temporary
.persist(path)
.map_err(|error| Error::io("replace output", path, error.error))?;
Ok(())
common::write_atomic(path, data).map_err(|error| Error::io("write temporary file", path, error))
}
/// Restore the current protected `libil2cpp.so` without executing protector code.
@@ -1363,9 +1543,9 @@ pub fn restore_libil2cpp(options: &RestoreOptions) -> Result<RestoreReport> {
.map_err(|error| Error::io("size temporary output", &temporary_path, error))?;
let mut restored_layout = layout.clone();
let mut auxiliary_data = None;
let mut auxiliary_stats = None;
let mut materialization = None;
let mut temporary_end = private.offset;
let primary_stats;
{
let mut output = map_mut(temporary.as_file(), private_size, &temporary_path)?;
@@ -1384,6 +1564,11 @@ pub fn restore_libil2cpp(options: &RestoreOptions) -> Result<RestoreReport> {
options.verbose,
|address, data| writer.write(address, data),
)?;
output
.flush()
.map_err(|error| Error::io("flush restored image", &temporary_path, error))?;
}
if !options.outer_only {
if options.verbose {
eprintln!("Decoding auxiliary 0x9D ELF materialization container...");
@@ -1396,9 +1581,9 @@ pub fn restore_libil2cpp(options: &RestoreOptions) -> Result<RestoreReport> {
options.verbose,
|offset, data| {
let start = usize_from_u64(offset, "auxiliary write offset")?;
let end = start.checked_add(data.len()).ok_or_else(|| {
Error::Invalid("auxiliary decoded write overflow".to_owned())
})?;
let end = start
.checked_add(data.len())
.ok_or_else(|| Error::Invalid("auxiliary decoded write overflow".to_owned()))?;
let destination = decoded.get_mut(start..end).ok_or_else(|| {
Error::Invalid("auxiliary decoded write is out of range".to_owned())
})?;
@@ -1409,10 +1594,20 @@ pub fn restore_libil2cpp(options: &RestoreOptions) -> Result<RestoreReport> {
if let Some(path) = &options.dump_auxiliary {
write_atomic(&absolute(path)?, &decoded)?;
}
let mapping_length = metadata_mapping_length(&source, &layout, &decoded)?;
if mapping_length < private_size {
return invalid("dynamic-table mapping is shorter than the ELF image");
}
temporary
.as_file()
.set_len(mapping_length as u64)
.map_err(|error| Error::io("extend temporary output", &temporary_path, error))?;
if options.verbose {
eprintln!("Rebuilding static ELF dynamic-linker tables...");
}
let (new_layout, report) = materialize_static_elf_tables(
{
let mut output = map_mut(temporary.as_file(), mapping_length, &temporary_path)?;
let (new_layout, report, data_end) = materialize_static_elf_tables(
&mut output,
&source,
&layout,
@@ -1422,19 +1617,23 @@ pub fn restore_libil2cpp(options: &RestoreOptions) -> Result<RestoreReport> {
restored_layout = new_layout;
materialization = Some(report);
auxiliary_stats = Some(stats);
auxiliary_data = Some(decoded);
}
temporary_end = data_end;
output
.flush()
.map_err(|error| Error::io("flush restored image", &temporary_path, error))?;
}
drop(auxiliary_data);
temporary
.as_file()
.set_len(temporary_end)
.map_err(|error| Error::io("trim temporary output", &temporary_path, error))?;
}
let cleaning = finalize_clean_elf(
temporary.as_file_mut(),
&temporary_path,
&source,
&restored_layout,
temporary_end,
options.preserve_entrypoint,
)?;
let validation = {
@@ -1480,12 +1679,45 @@ pub fn restore_libil2cpp(options: &RestoreOptions) -> Result<RestoreReport> {
elapsed_seconds: started.elapsed().as_secs_f64(),
})
}
/// Lowercase hex of a digest output (sha2 0.11's `Array` no longer formats as
/// hex directly).
fn hex_digest(data: &[u8]) -> String {
let mut out = String::with_capacity(data.len() * 2);
for byte in data {
out.push_str(&format!("{byte:02x}"));
#[cfg(test)]
mod tests {
use super::*;
fn auxiliary_image(symbol_count: u32) -> Vec<u8> {
let mut data = vec![0_u8; 0x279];
let words = [
0x40_u32,
0,
0x40,
0,
0x278,
1,
0x260,
symbol_count,
0x40,
3,
0x90,
19,
0,
0,
0xb7,
0,
];
for (index, word) in words.into_iter().enumerate() {
data[index * 4..index * 4 + 4].copy_from_slice(&word.to_le_bytes());
}
data
}
#[test]
fn auxiliary_accepts_null_only_dynamic_symbol_table() {
let parsed = AuxiliaryElfImage::parse(&auxiliary_image(1)).expect("null-only dynsym");
assert_eq!(parsed.dynsym_count, 1);
}
#[test]
fn auxiliary_rejects_missing_null_dynamic_symbol() {
let error = AuxiliaryElfImage::parse(&auxiliary_image(0)).expect_err("missing null symbol");
assert!(error.to_string().contains("no null entry"));
}
out
}
senbei-engine/src/lib.rs
+22
View File
@@ -0,0 +1,22 @@
//! Platform-specific unpacking engines.
pub mod android;
pub mod windows;
pub use windows::{
Detected, IntegrityReport, Kind, UnpackError, check_integrity, detect, unpack_auto,
unpack_auto_v, unpack_dll, unpack_dll_v, unpack_exe, unpack_exe_v,
};
/// Deterministic worker-thread cap shared by filesystem scanning and engines.
pub fn thread_cap() -> usize {
if let Ok(value) = std::env::var("SENBEI_THREADS")
&& let Ok(count) = value.trim().parse::<usize>()
&& count >= 1
{
return count;
}
std::thread::available_parallelism()
.map(|count| count.get())
.unwrap_or(1)
}
senbei-pe/src/engine/dll/mod.rs → senbei-engine/src/windows/dll/mod.rs
View File
senbei-pe/src/engine/dll/pipeline.rs → senbei-engine/src/windows/dll/pipeline.rs
View File
senbei-pe/src/engine/error.rs → senbei-engine/src/windows/error.rs
+7
View File
@@ -149,6 +149,13 @@ pub enum UnpackError {
buffer_len: usize,
},
#[error("managed stub {region} restoration failed: {source}")]
ManagedStubRestoreFailed {
region: &'static str,
#[source]
source: senbei_pe::Error,
},
#[error(
"EXE checksum descriptor at 0x{descriptor:08X} points outside input (offset {offset}, size {size}, input length {image_len})"
)]
senbei-pe/src/engine/exe/mod.rs → senbei-engine/src/windows/exe/mod.rs
View File
senbei-pe/src/engine/exe/pipeline.rs → senbei-engine/src/windows/exe/pipeline.rs
+4 -15
View File
@@ -15,23 +15,12 @@ pub fn unpack(input: &[u8]) -> Result<Vec<u8>, UnpackError> {
/// Used by the new-layout managed (CLR) metadata restore to locate the COR20
/// header and BSJB MetaData stream in the original protected file.
fn prot_rva_to_off(file_data: &[u8], pe_header: u32, rva: u32) -> Option<u32> {
let nsec = get_u16(file_data, pe_header + 6) as u32;
let opt = get_u16(file_data, pe_header + 20) as u32;
let tab = pe_header + 24 + opt;
for i in 0..nsec {
let s = tab + i * 40;
if (s as usize + 24) > file_data.len() {
let headers = senbei_pe::parse(file_data).ok()?;
if headers.pe_offset != pe_header as usize {
return None;
}
let va = get_u32(file_data, s + 12);
let vs = get_u32(file_data, s + 8);
let rsz = get_u32(file_data, s + 16);
let rp = get_u32(file_data, s + 20);
if va <= rva && rva < va + vs.max(rsz) {
return Some(rp + (rva - va));
}
}
None
let offset = senbei_pe::rva_to_offset(file_data, headers, rva).ok()?;
u32::try_from(offset).ok()
}
pub fn unpack_v(input: &[u8], verbose: bool) -> Result<Vec<u8>, UnpackError> {
senbei-pe/src/engine/exe/pipeline/pe32.rs → senbei-engine/src/windows/exe/pipeline/pe32.rs
+122 -6
View File
@@ -1,6 +1,27 @@
use super::super::super::layout;
use super::*;
fn stage_key_rounds(data: &[u8], table: u32, slots: usize) -> Result<u32, UnpackError> {
let offset = table as usize;
let size = slots.saturating_mul(16);
let descriptors = offset
.checked_add(size)
.and_then(|end| data.get(offset..end))
.ok_or(UnpackError::BufferRangeOutOfBounds {
operation: BufferOperation::Read,
offset,
size,
buffer_len: data.len(),
})?;
// The loader stops at the first empty helper, even if later slots are nonempty.
Ok(descriptors
.as_chunks::<16>()
.0
.iter()
.take_while(|descriptor| get_u32(descriptor.as_slice(), 4) > 4)
.count() as u32)
}
impl<'a> Unpacker<'a> {
/// PE32 (32-bit) unpack pipeline. The shared Stage 1/2 setup (info decrypt,
/// payload decrypt, raw copy, header restore) has already run in `run()`
@@ -224,11 +245,15 @@ impl<'a> Unpacker<'a> {
// ---- ForthStage ----
let second_stage_cs = self.calculate_checksum(second_stage_cs_addr);
let dp_base = ss.wrapping_add(dp_base_off);
let forth_key_rounds = stage_key_rounds(&self.decompressed, dp_base, 4)?;
let forth_stage_key = advance_key(
get_u32(&self.decompressed, ss.wrapping_add(forth_key_off)),
4,
forth_key_rounds,
);
let dp_base = ss.wrapping_add(dp_base_off);
if verbose {
println!(" fourth-stage key rounds = {forth_key_rounds}");
}
let forth_addr = dp_base.wrapping_add(0x40);
let fk = header_checksum ^ second_stage_cs ^ forth_stage_key;
if let Err(reason) = self.decrypt_and_decompress_data(forth_addr, fk, None) {
@@ -313,6 +338,11 @@ impl<'a> Unpacker<'a> {
)?;
let seven_cs = self.calculate_checksum(seven_stage_cs_addr);
let eighth_key_rounds =
stage_key_rounds(&self.decompressed, dp_base.wrapping_add(0x80), 4)?;
if verbose {
println!(" eighth-stage key rounds = {eighth_key_rounds}");
}
let eighth_addr = dp_base.wrapping_add(0xC0);
let eighth_dsz = get_u32(&self.decompressed, eighth_addr.wrapping_add(12));
let eighth_src = get_u32(&self.decompressed, eighth_addr);
@@ -381,7 +411,7 @@ impl<'a> Unpacker<'a> {
self.decompressed[eighth_addr as usize..(eighth_addr + 16) as usize]
.copy_from_slice(&eighth_pair_bak);
let raw = get_u32(&self.decompressed, seven_start_actual.wrapping_add(ek_off));
let test_key = advance_key(raw, 3);
let test_key = advance_key(raw, eighth_key_rounds);
let fk8 = header_checksum ^ fifth_cs ^ seven_cs ^ test_key;
let result = primitives::decrypt_and_decompress_data(
&mut self.decompressed,
@@ -445,7 +475,7 @@ impl<'a> Unpacker<'a> {
let mut best: Option<(u32 /*dist*/, u32 /*off*/)> = None;
let mut o = 0u32;
let dlen = self.decompressed.len() as u32;
while o + 8 <= eighth_dsz.saturating_sub(0x4B4u32.saturating_sub(0x30)) {
while o + 8 <= eighth_dsz {
let fc = get_u32(&self.decompressed, eighth_start.wrapping_add(o));
let sz = get_u32(&self.decompressed, eighth_start.wrapping_add(o + 4));
if fc > info3
@@ -454,8 +484,9 @@ impl<'a> Unpacker<'a> {
&& (0x10..=0x200).contains(&sz)
&& (sz & 0xF) == 0
{
// Cluster base must leave room for the +0x4B4 LFSR slot
// (even if the exact LFSR is later adjusted by scan).
// Compact stages place the decryptor closer to this
// cluster. Only the config fields must fit here; the
// actual LFSR location is trial-validated below.
if o >= 0x30 {
let base = o - 0x30;
if base.wrapping_add(0x4C) <= eighth_dsz {
@@ -945,6 +976,58 @@ impl<'a> Unpacker<'a> {
}
}
// ---- Re-arm TLS field base relocations (PE32 DLL) ----
// The packer neutralizes the four relocations covering the TLS
// directory's VA fields (Start/EndAddressOfRawData, AddressOfIndex,
// AddressOfCallBacks) by demoting them to IMAGE_REL_BASED_ABSOLUTE
// padding, because its own loader fixes TLS up by hand. Restored
// verbatim, a DLL mapped off its preferred base keeps stale VAs in its
// TLS directory, and the OS loader faults in LdrpAllocateTlsEntry when
// it writes the TLS slot index through the unrelocated AddressOfIndex.
// Promote those entries back to IMAGE_REL_BASED_HIGHLOW. EXE output
// is untouched: its BaseReloc directory is zeroed above, and its
// goldens must stay byte-identical.
if is_dll && tls_dir_rva > 0 {
let reloc_rva = get_u32(&self.decompressed, exe_pe.wrapping_add(0xA0));
let reloc_size = get_u32(&self.decompressed, exe_pe.wrapping_add(0xA4));
let reloc_end = reloc_rva.wrapping_add(reloc_size);
let dlen = self.decompressed.len() as u32;
if reloc_rva > 0 && reloc_size >= 8 && reloc_end <= dlen {
let mut rearmed = 0u32;
let mut block = reloc_rva;
while block.wrapping_add(8) <= reloc_end {
let page = get_u32(&self.decompressed, block);
let block_size = get_u32(&self.decompressed, block.wrapping_add(4));
if block_size < 8
|| !block_size.is_multiple_of(2)
|| block.wrapping_add(block_size) > reloc_end
{
break;
}
let entries = (block_size - 8) / 2;
for i in 0..entries {
let entry_off = block.wrapping_add(8).wrapping_add(i.wrapping_mul(2));
let entry = get_u16(&self.decompressed, entry_off);
let entry_rva = page.wrapping_add((entry & 0x0FFF) as u32);
// IMAGE_REL_BASED_ABSOLUTE with a real offset is
// neutralized, not padding (padding keeps offset 0).
if entry >> 12 == 0
&& entry & 0x0FFF != 0
&& entry_rva >= tls_dir_rva
&& entry_rva < tls_dir_rva.wrapping_add(16)
{
write_u16(&mut self.decompressed, entry_off, (entry | 0x3000) as u32);
rearmed = rearmed.wrapping_add(1);
}
}
block = block.wrapping_add(block_size);
}
if verbose && rearmed > 0 {
println!(" re-armed {} TLS field relocations", rearmed);
}
}
}
// ---- Import table (PE32, 4-byte thunks) ----
if verbose {
println!("[8/9] Decrypting import strings (PE32)...");
@@ -1061,3 +1144,36 @@ impl<'a> Unpacker<'a> {
Ok(compact)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn stage_key_rounds_follow_active_descriptor_prefix() {
for (sizes, expected) in [
([0, 0x45, 0x45, 0x45], 0),
([0x45, 4, 0x45, 0x45], 1),
([0x45, 0x45, 0x45, 3], 3),
([0x45, 0x45, 0x45, 0x45], 4),
] {
let mut data = [0u8; 80];
for (index, size) in sizes.into_iter().enumerate() {
write_u32(&mut data, 16 + index as u32 * 16 + 4, size);
}
assert_eq!(stage_key_rounds(&data, 16, 4).unwrap(), expected);
}
}
#[test]
fn stage_key_rounds_reject_truncated_tables() {
assert!(matches!(
stage_key_rounds(&[0u8; 63], 0, 4),
Err(UnpackError::BufferRangeOutOfBounds { .. })
));
assert!(matches!(
stage_key_rounds(&[0u8; 64], u32::MAX, 4),
Err(UnpackError::BufferRangeOutOfBounds { .. })
));
}
}
senbei-pe/src/engine/integrity.rs → senbei-engine/src/windows/integrity.rs
+45 -69
View File
@@ -42,47 +42,26 @@ fn rd_u32(d: &[u8], off: u32) -> Option<u32> {
.map(|s| u32::from_le_bytes([s[0], s[1], s[2], s[3]]))
}
/// A parsed section-table entry (only the fields we translate against).
struct Section {
va: u32,
vsize: u32,
raw_ptr: u32,
raw_size: u32,
chars: u32,
}
/// PE format section data used by the integrity policy.
type Section = senbei_pe::Section;
/// Walk the output's own section table and translate an RVA to a file offset.
/// Works for both memory-image output (raw_ptr == va) and compacted disk
/// output (real raw pointers), because it consults whatever the output declares.
/// Returns the offset only if the translated range `[off, off+need)` lies inside
/// the file.
fn rva_to_off(secs: &[Section], file_len: usize, rva: u32, need: u32) -> Option<u32> {
for s in secs {
// The mapped span is the larger of virtual and raw size, so an RVA that
// falls in the virtual tail of a section still resolves.
let span = s.vsize.max(s.raw_size);
if span == 0 {
continue;
}
if rva >= s.va && rva < s.va.wrapping_add(span) {
let delta = rva - s.va;
let off = s.raw_ptr.checked_add(delta)?;
let end = off.checked_add(need)?;
if (end as usize) <= file_len {
return Some(off);
}
return None;
}
}
None
fn rva_to_off(data: &[u8], headers: senbei_pe::Headers, rva: u32, need: u32) -> Option<u32> {
let offset = u32::try_from(senbei_pe::rva_to_offset(data, headers, rva).ok()?).ok()?;
let end = offset.checked_add(need)?;
(usize::try_from(end).ok()? <= data.len()).then_some(offset)
}
fn is_executable_rva(secs: &[Section], rva: u32) -> bool {
secs.iter().any(|section| {
let span = section.vsize.max(section.raw_size);
rva >= section.va
&& rva < section.va.wrapping_add(span)
&& (section.chars & 0x2000_0000) != 0
let span = section.virtual_size.max(section.raw_size);
rva >= section.virtual_address
&& rva < section.virtual_address.wrapping_add(span)
&& (section.characteristics & 0x2000_0000) != 0
})
}
@@ -151,7 +130,6 @@ pub fn check(out: &[u8]) -> IntegrityReport {
return r;
}
};
let opt_hdr_size = rd_u16(out, pe_off.wrapping_add(20)).unwrap_or(0) as u32;
let opt = pe_off.wrapping_add(24);
let magic = match rd_u16(out, opt) {
Some(v) => v,
@@ -181,42 +159,38 @@ pub fn check(out: &[u8]) -> IntegrityReport {
}
// --- Section table ------------------------------------------------------
let sec_table = opt.wrapping_add(opt_hdr_size);
let mut secs: Vec<Section> = Vec::new();
for i in 0..num_sections {
let base = sec_table.wrapping_add(i * 40);
// If the table runs past EOF the image is structurally broken.
let (vsize, va, raw_size, raw_ptr, chars) = match (
rd_u32(out, base.wrapping_add(8)),
rd_u32(out, base.wrapping_add(12)),
rd_u32(out, base.wrapping_add(16)),
rd_u32(out, base.wrapping_add(20)),
rd_u32(out, base.wrapping_add(36)),
) {
(Some(a), Some(b), Some(c), Some(d), Some(e)) => (a, b, c, d, e),
_ => {
let headers = match senbei_pe::parse(out) {
Ok(headers) => headers,
Err(_) => {
r.issues
.push("section table extends past end of file".into());
return r;
}
};
// Raw data must lie within the file for compacted (disk-layout) output.
if raw_size != 0 {
let end = raw_ptr.wrapping_add(raw_size) as usize;
let parsed_sections = match senbei_pe::sections(out, headers) {
Ok(sections) => sections,
Err(_) => {
r.issues
.push("section table extends past end of file".into());
return r;
}
};
let secs: Vec<Section> = parsed_sections
.into_iter()
.enumerate()
.map(|(i, section)| {
if section.raw_size != 0 {
let end = section.raw_offset.wrapping_add(section.raw_size) as usize;
if end > file_len {
r.issues.push(format!(
"section #{i} raw data [0x{raw_ptr:X}..0x{end:X}] exceeds file size 0x{file_len:X}"
"section #{i} raw data [0x{:X}..0x{end:X}] exceeds file size 0x{file_len:X}",
section.raw_offset
));
}
}
secs.push(Section {
va,
vsize,
raw_ptr,
raw_size,
chars,
});
}
section
})
.collect();
// --- Managed (CLR) detection ------------------------------------------
// The COR20 (CLR) data directory, when present and non-zero, marks a managed
@@ -266,7 +240,7 @@ pub fn check(out: &[u8]) -> IntegrityReport {
r.issues.push("entry point RVA is zero".into());
}
} else if !is_managed {
match rva_to_off(&secs, file_len, ep, 16) {
match rva_to_off(out, headers, ep, 16) {
None => {
r.issues.push(format!(
"entry point RVA 0x{ep:X} does not map into any section"
@@ -288,8 +262,10 @@ pub fn check(out: &[u8]) -> IntegrityReport {
}
// The entry must live in an executable section.
let exec = secs.iter().any(|s| {
let span = s.vsize.max(s.raw_size);
ep >= s.va && ep < s.va.wrapping_add(span) && (s.chars & 0x2000_0000) != 0
let span = s.virtual_size.max(s.raw_size);
ep >= s.virtual_address
&& ep < s.virtual_address.wrapping_add(span)
&& (s.characteristics & 0x2000_0000) != 0
});
if !exec {
r.issues.push(format!(
@@ -316,7 +292,7 @@ pub fn check(out: &[u8]) -> IntegrityReport {
if !is_managed {
let imp_rva = rd_u32(out, dd_base.wrapping_add(8)).unwrap_or(0);
if imp_rva != 0 {
match rva_to_off(&secs, file_len, imp_rva, 20) {
match rva_to_off(out, headers, imp_rva, 20) {
None => r.issues.push(format!(
"import directory RVA 0x{imp_rva:X} does not map into any section"
)),
@@ -331,7 +307,7 @@ pub fn check(out: &[u8]) -> IntegrityReport {
if name_rva == 0 {
break;
}
match rva_to_off(&secs, file_len, name_rva, 1) {
match rva_to_off(out, headers, name_rva, 1) {
None => r.issues.push(format!(
"import descriptor {i} DLL name RVA 0x{name_rva:X} does not map into any section"
)),
@@ -359,7 +335,7 @@ pub fn check(out: &[u8]) -> IntegrityReport {
// still refuses to load. Validate: COR20 cb == 0x48, and the MetaData stream
// begins with the "BSJB" signature.
if is_managed {
match rva_to_off(&secs, file_len, clr_rva, 0x48) {
match rva_to_off(out, headers, clr_rva, 0x48) {
None => r.issues.push(format!(
"CLR (COR20) directory RVA 0x{clr_rva:X} does not map into any section"
)),
@@ -373,7 +349,7 @@ pub fn check(out: &[u8]) -> IntegrityReport {
// MetaData RVA/size live at COR20 + 0x08 / + 0x0C.
let md_rva = rd_u32(out, coff.wrapping_add(8)).unwrap_or(0);
if md_rva != 0 {
match rva_to_off(&secs, file_len, md_rva, 4) {
match rva_to_off(out, headers, md_rva, 4) {
None => r.issues.push(format!(
"CLR MetaData RVA 0x{md_rva:X} does not map into any section"
)),
@@ -416,11 +392,11 @@ mod tests {
fn executable_text() -> Vec<Section> {
vec![Section {
va: 0x1000,
vsize: 0x4000,
raw_ptr: 0x1000,
virtual_address: 0x1000,
virtual_size: 0x4000,
raw_offset: 0x1000,
raw_size: 0x4000,
chars: 0x6000_0020,
characteristics: 0x6000_0020,
}]
}
senbei-pe/src/engine/layout.rs → senbei-engine/src/windows/layout.rs
View File
senbei-pe/src/engine/layout/dd8.rs → senbei-engine/src/windows/layout/dd8.rs
View File
senbei-pe/src/engine/layout/discovery.rs → senbei-engine/src/windows/layout/discovery.rs
View File
senbei-pe/src/engine/layout/image.rs → senbei-engine/src/windows/layout/image.rs
View File
senbei-pe/src/engine/mod.rs → senbei-engine/src/windows/mod.rs
+5 -5
View File
@@ -11,11 +11,11 @@ use senbei_crypto::primitives;
use std::cell::RefCell;
use std::sync::{Arc, Mutex};
pub use crate::thread_cap;
pub use dll::{unpack_dll, unpack_dll_v};
pub use error::*;
pub use exe::{unpack as unpack_exe, unpack_v as unpack_exe_v};
pub use integrity::{IntegrityReport, check as check_integrity};
pub use parallel::thread_cap;
/// Maximum plausible PE `SizeOfImage` we are willing to allocate a zero buffer
/// for. Guards against a corrupt/crafted header requesting a multi-gigabyte
@@ -350,8 +350,8 @@ mod tests {
};
assert_eq!(message, "test panic");
assert!(
file.ends_with("senbei-pe/src/engine/mod.rs")
|| file.ends_with("senbei-pe\\src\\engine\\mod.rs")
file.ends_with("senbei-engine/src/windows/mod.rs")
|| file.ends_with("senbei-engine\\src\\windows\\mod.rs")
);
assert!(line > 0);
assert!(column > 0);
@@ -382,8 +382,8 @@ mod tests {
};
assert_eq!(message, "worker panic");
assert!(
file.ends_with("senbei-pe/src/engine/mod.rs")
|| file.ends_with("senbei-pe\\src\\engine\\mod.rs")
file.ends_with("senbei-engine/src/windows/mod.rs")
|| file.ends_with("senbei-engine\\src\\windows\\mod.rs")
);
assert!(line > 0);
assert!(column > 0);
senbei-pe/src/engine/parallel.rs → senbei-engine/src/windows/parallel.rs
+1 -15
View File
@@ -19,20 +19,6 @@
use std::sync::Mutex;
use std::sync::atomic::{AtomicBool, Ordering};
/// Worker-thread cap. `SENBEI_THREADS` overrides it (`1` forces the sequential
/// path); otherwise the host's available parallelism; otherwise 1.
pub fn thread_cap() -> usize {
if let Ok(v) = std::env::var("SENBEI_THREADS")
&& let Ok(n) = v.trim().parse::<usize>()
&& n >= 1
{
return n;
}
std::thread::available_parallelism()
.map(|n| n.get())
.unwrap_or(1)
}
/// Run `f(i, span_base, span)` for every block `i`, fanning out across worker
/// threads when the spans are disjoint and worthwhile, else sequentially.
///
@@ -102,7 +88,7 @@ where
}
}
let cap = thread_cap();
let cap = crate::thread_cap();
let per = min_per_thread.max(1);
let workers = if cap > 1 && n >= per.saturating_mul(2) {
cap.min(n / per)
senbei-io/Cargo.toml
+5 -5
View File
@@ -7,14 +7,14 @@ description = "Filesystem, scanning, logging, and CLI orchestration for Senbei"
[dependencies]
anyhow.workspace = true
flate2.workspace = true
senbei-crypto.workspace = true
indicatif.workspace = true
memmap2.workspace = true
owo-colors.workspace = true
senbei-android-elf.workspace = true
senbei-android-engine.workspace = true
senbei-android-metadata.workspace = true
senbei-metadata.workspace = true
senbei-engine.workspace = true
senbei-elf.workspace = true
senbei-pe.workspace = true
senbei-metadata.workspace = true
sha2.workspace = true
tempfile.workspace = true
walkdir.workspace = true
senbei-io/src/android.rs → senbei-io/src/android/mod.rs
+103 -82
View File
@@ -5,59 +5,71 @@
//! The protection scheme hollows out an ELF64/AArch64 shared object and moves
//! the original bytes into an encrypted payload appended as a `SHT_LOUSER`
//! section; restoration extracts the stage-2 module set
//! ([`senbei_android_engine`]) and rebuilds the static image
//! ([`senbei_android_elf`]). Some il2cpp builds additionally embed their
//! ([`senbei_engine::android`]) and rebuilds the static image
//! ([`senbei_engine::android`]). Some il2cpp builds additionally embed their
//! metadata blob — XOR-wrapped, with no standalone `global-metadata.dat` in
//! the assets — inside the library's data section; after a successful restore
//! the blob is located by content and unwrapped
//! ([`senbei_android_metadata::extract_embedded_metadata`]).
//! ([`senbei_metadata::android::extract_embedded_metadata`]).
//!
//! All functions in this module are native filesystem orchestration; the web
//! app (wasm) never touches them.
use std::collections::HashSet;
use std::io::Read;
use std::fs::File;
use std::io::{BufWriter, Read, Seek, Write};
use std::path::{Path, PathBuf};
use anyhow::{Context, Result, bail};
use flate2::read::DeflateDecoder;
use senbei_android_elf::{RestoreOptions, restore_libil2cpp};
use senbei_android_engine::{ExtractOptions, extract_stage2, is_protected_libil2cpp};
use memmap2::{Mmap, MmapOptions};
use senbei_crypto::hex_digest;
use senbei_engine::android::{ExtractOptions, extract_stage2, is_protected_libil2cpp};
use senbei_engine::android::{RestoreOptions, restore_libil2cpp};
use sha2::{Digest, Sha256};
use zip::ZipArchive;
/// File name of an il2cpp metadata blob (a platform-standard technology name).
pub const METADATA_FILE_NAME: &str = "global-metadata.dat";
pub use crate::METADATA_FILE_NAME;
/// Package extensions recognised as Android app packages. Packages are
/// *containers*: membership is decided by extension plus the zip magic, while
/// every file pulled out of one is still content-probed like a loose file.
/// *containers*: membership is decided by extension plus the ZIP magic, while
/// only `.so` and `global-metadata.dat` entries are read.
const PACKAGE_EXTENSIONS: [&str; 3] = ["apk", "apks", "xapk"];
pub(crate) fn is_package_name(path: &Path) -> bool {
path.extension()
.and_then(|value| value.to_str())
.is_some_and(|value| {
PACKAGE_EXTENSIONS
.iter()
.any(|ext| value.eq_ignore_ascii_case(ext))
})
}
pub(crate) fn is_so_name(path: &Path) -> bool {
path.extension()
.and_then(|value| value.to_str())
.is_some_and(|value| value.eq_ignore_ascii_case("so"))
}
pub(crate) fn is_android_entry_name(path: &Path) -> bool {
path.file_name()
.and_then(|name| name.to_str())
.is_some_and(|name| name.eq_ignore_ascii_case(METADATA_FILE_NAME))
|| is_so_name(path)
}
/// Whether `prefix` (the first bytes of a file) is an ELF64/AArch64 image.
/// Only those can be protected Android libraries, so the folder scan uses this
/// cheap check to decide when the full-file protection probe is worth its
/// read.
pub fn is_elf64_aarch64(prefix: &[u8]) -> bool {
prefix.len() >= 20
&& prefix[0..4] == [0x7f, b'E', b'L', b'F']
&& prefix[4] == 2 // ELFCLASS64
&& prefix[5] == 1 // ELFDATA2LSB
&& u16::from_le_bytes([prefix[18], prefix[19]]) == 0xB7 // EM_AARCH64
senbei_elf::is_aarch64_prefix(prefix)
}
/// Whether `path` is an Android app package: a recognised package extension
/// and the local-file-header zip magic in `prefix`.
pub fn is_app_package(path: &Path, prefix: &[u8]) -> bool {
let is_package_ext = path
.extension()
.and_then(|value| value.to_str())
.is_some_and(|value| {
PACKAGE_EXTENSIONS
.iter()
.any(|ext| value.eq_ignore_ascii_case(ext))
});
is_package_ext && prefix.starts_with(b"PK\x03\x04")
is_package_name(path) && prefix.starts_with(b"PK\x03\x04")
}
/// Probe a file on disk: true when it is a protected AArch64 library.
@@ -65,12 +77,23 @@ pub fn is_app_package(path: &Path, prefix: &[u8]) -> bool {
/// section-header table at the end); call only after [`is_elf64_aarch64`]
/// has matched a prefix.
pub fn is_protected_so_file(path: &Path) -> bool {
let Ok(bytes) = std::fs::read(path) else {
let Ok(file) = File::open(path) else {
return false;
};
let Ok(bytes) = map_read_only(&file, path) else {
return false;
};
is_elf64_aarch64(&bytes) && is_protected_libil2cpp(&bytes)
}
pub fn file_content_identity(path: &Path) -> std::io::Result<String> {
let file = File::open(path)?;
// SAFETY: the file remains open for the mapping lifetime and the mapping
// is read-only.
let bytes = unsafe { MmapOptions::new().map(&file)? };
Ok(content_identity(&bytes))
}
/// Restore one protected `.so` to `dest`.
///
/// The stage-2 module set is extracted into a temporary workspace (it is an
@@ -97,7 +120,7 @@ pub fn restore_so_file(input: &Path, dest: &Path, verbose: bool) -> Result<Optio
.context("restore protected library")?;
let restored =
std::fs::read(dest).with_context(|| format!("read restored `{}`", dest.display()))?;
Ok(senbei_android_metadata::extract_embedded_metadata(
Ok(senbei_metadata::android::extract_embedded_metadata(
&restored,
))
}
@@ -122,20 +145,19 @@ pub fn content_identity(data: &[u8]) -> String {
/// canonical form. Both paths are no-ops (`remapped == 0`) on an
/// already-clean blob.
pub fn restore_metadata_bytes(data: &[u8]) -> anyhow::Result<(Vec<u8>, senbei_metadata::Report)> {
if let Ok(discovery) = senbei_android_metadata::discover_method_token_seeds(data)
&& discovery.version == 31
&& discovery.images.iter().any(|image| !image.clean)
if let Ok(discovery) = senbei_metadata::android::discover_method_token_seeds(data)
&& matches!(discovery.version, 29 | 31 | 39)
{
let mut seeds = discovery.seed_candidates.clone();
if seeds.is_empty() {
seeds.push(senbei_android_metadata::DEFAULT_METHOD_TOKEN_SEED);
seeds.push(senbei_metadata::android::DEFAULT_METHOD_TOKEN_SEED);
}
// Trial-and-validate: a wrong seed fails the restore's full-coverage
// RID check, so ambiguous candidates cost one extra pass each and a
// build with an unseeded permutation falls through to the structural
// remap rather than producing a silently wrong file.
for seed in seeds {
if let Ok((out, report)) = senbei_android_metadata::restore_method_tokens(data, seed) {
if let Ok((out, report)) = senbei_metadata::android::restore_method_tokens(data, seed) {
return Ok((
out,
senbei_metadata::Report {
@@ -234,22 +256,29 @@ pub fn restore_package(
nested.push((index, name));
}
} else {
if is_android_entry_name(&name) {
direct.push((index, name));
}
}
drop(archive);
}
for (index, name) in direct {
let label = format!("{}::{}", rel.display(), name.display());
let dest = out_root.join(rel).join(crate::job::out_name(&name));
let mut entry_outcomes =
restore_package_entry(package, index, &label, &dest, &temporary, seen, verbose)
let mut entry_outcomes = restore_package_entry(
&mut archive,
index,
&label,
&dest,
&temporary,
seen,
verbose,
)
.with_context(|| format!("extract `{label}`"))?;
outcomes.append(&mut entry_outcomes);
}
for (index, name) in nested {
let nested_label = rel.join(&name);
let nested_path = extract_entry(package, index, &temporary, &nested_label)
let nested_path = extract_entry(&mut archive, index, &temporary, &nested_label)
.with_context(|| format!("extract `{}`", nested_label.display()))?;
let mut nested_archive = open_package(&nested_path)?;
let mut entries = Vec::new();
@@ -262,10 +291,11 @@ pub fn restore_package(
let Some(entry_name) = entry_name else {
bail!("unsafe entry path in `{}`", nested_label.display());
};
if is_android_entry_name(&entry_name) {
entries.push((nested_index, entry_name));
}
}
drop(nested_archive);
}
// Keep the nested package's stem in the output layout so two splits
// carrying same-named entries cannot collide.
let base = rel.join(name.with_extension(""));
@@ -273,7 +303,7 @@ pub fn restore_package(
let label = format!("{}::{}", nested_label.display(), entry_name.display());
let dest = out_root.join(&base).join(crate::job::out_name(&entry_name));
let mut entry_outcomes = restore_package_entry(
&nested_path,
&mut nested_archive,
nested_index,
&label,
&dest,
@@ -291,8 +321,8 @@ pub fn restore_package(
/// Probe one extracted package entry and restore it when it is a target.
/// Returns one outcome per produced/consumed artifact: the entry itself, plus
/// an `EmbeddedMetadata` outcome when the restored library carried a blob.
fn restore_package_entry(
package: &Path,
fn restore_package_entry<R: Read + Seek>(
archive: &mut ZipArchive<R>,
index: usize,
label: &str,
dest: &Path,
@@ -300,11 +330,13 @@ fn restore_package_entry(
seen: &mut HashSet<String>,
verbose: bool,
) -> Result<Vec<EntryOutcome>> {
let entry_path = extract_entry(package, index, temporary, Path::new(label))?;
let data = std::fs::read(&entry_path).with_context(|| format!("read extracted `{label}`"))?;
let entry_path = extract_entry(archive, index, temporary, Path::new(label))?;
let entry_file =
File::open(&entry_path).with_context(|| format!("open extracted `{label}`"))?;
let entry_data = map_read_only(&entry_file, &entry_path)?;
let is_so = is_elf64_aarch64(&data) && is_protected_libil2cpp(&data);
let is_meta = !is_so && senbei_metadata::is_metadata(&data);
let is_so = is_elf64_aarch64(&entry_data) && is_protected_libil2cpp(&entry_data);
let is_meta = !is_so && senbei_metadata::is_metadata(&entry_data);
let outcome = |kind, status| EntryOutcome {
label: label.to_owned(),
dest: dest.to_path_buf(),
@@ -314,7 +346,7 @@ fn restore_package_entry(
if !is_so && !is_meta {
return Ok(vec![outcome(EntryKind::So, EntryStatus::NotTarget)]);
}
if !seen.insert(content_identity(&data)) {
if !seen.insert(content_identity(&entry_data)) {
let kind = if is_so {
EntryKind::So
} else {
@@ -324,6 +356,8 @@ fn restore_package_entry(
}
if is_so {
drop(entry_data);
drop(entry_file);
return Ok(match restore_so_file(&entry_path, dest, verbose) {
Ok(embedded) => {
let mut outcomes = vec![outcome(EntryKind::So, EntryStatus::Restored)];
@@ -348,7 +382,7 @@ fn restore_package_entry(
// Metadata entry: write only when the restore actually changed tokens —
// a clean blob needs no copy (same contract as loose metadata files).
let kind_and_status = match restore_metadata_bytes(&data) {
let kind_and_status = match restore_metadata_bytes(&entry_data) {
Ok((out, report)) if report.remapped > 0 => {
let kind = EntryKind::Metadata {
remapped: report.remapped,
@@ -375,14 +409,14 @@ pub fn embedded_metadata_dest(restored_so: &Path) -> PathBuf {
}
/// Write a metadata blob, creating the parent directory. The restore writes
/// its own output atomically; metadata blobs go through the job layer's
/// atomic write to share the mid-write failure semantics.
/// its own output atomically; metadata blobs use the shared orchestration
/// atomic writer to keep the same mid-write failure semantics.
fn write_metadata_blob(dest: &Path, data: &[u8]) -> Result<()> {
if let Some(parent) = dest.parent() {
std::fs::create_dir_all(parent)
.with_context(|| format!("create `{}`", parent.display()))?;
}
crate::job::write_atomic(dest, data)
crate::atomic::write_atomic(dest, data)
.map_err(anyhow::Error::from)
.context("write metadata output")
}
@@ -392,50 +426,37 @@ fn open_package(path: &Path) -> Result<ZipArchive<std::fs::File>> {
ZipArchive::new(file).with_context(|| format!("read package `{}`", path.display()))
}
/// Extract one package entry to the temporary workspace, streaming stored
/// entries and inflating deflated ones by hand so compression-method
/// surprises fail loudly instead of producing a truncated file.
fn extract_entry(
package: &Path,
/// Stream one package entry to a temporary, seekable file. The Android engine
/// needs random access to ELF section tables, while the ZIP reader itself is
/// consumed directly without creating an in-memory compressed or decompressed
/// copy.
fn extract_entry<R: Read + Seek>(
archive: &mut ZipArchive<R>,
index: usize,
temporary: &tempfile::TempDir,
label: &Path,
) -> Result<PathBuf> {
let mut archive = open_package(package)?;
let mut entry = archive.by_index_raw(index)?;
let mut entry = archive.by_index(index)?;
let key = format!("{}-{index:08x}", label.display());
// `:` appears in `package::entry` labels and is invalid in Windows file
// names; sanitize every path-ish separator.
let destination = temporary.path().join(key.replace(['\\', '/', ':'], "_"));
let compressed_size = usize::try_from(entry.compressed_size())
.map_err(|_| anyhow::anyhow!("entry compressed size exceeds usize"))?;
let output_size =
usize::try_from(entry.size()).map_err(|_| anyhow::anyhow!("entry size exceeds usize"))?;
let mut compressed = vec![0_u8; compressed_size];
entry.read_exact(&mut compressed)?;
let mut output = Vec::with_capacity(output_size);
match entry.compression() {
zip::CompressionMethod::Stored => output.extend_from_slice(&compressed),
zip::CompressionMethod::Deflated => {
DeflateDecoder::new(compressed.as_slice()).read_to_end(&mut output)?;
}
method => bail!("unsupported compression method {method:?} in entry `{key}`"),
}
if output.len() != output_size {
let output_size = entry.size();
let mut output = BufWriter::new(std::fs::File::create(&destination)?);
let written = std::io::copy(&mut entry, &mut output)?;
output.flush()?;
if written != output_size {
bail!(
"entry `{key}` decompressed to 0x{:x}, expected 0x{output_size:x}",
output.len()
written
);
}
std::fs::write(&destination, &output)?;
Ok(destination)
}
/// Lowercase hex of a digest output (sha2 0.11's `Array` no longer formats as
/// hex directly).
fn hex_digest(data: &[u8]) -> String {
let mut out = String::with_capacity(data.len() * 2);
for byte in data {
out.push_str(&format!("{byte:02x}"));
}
out
fn map_read_only(file: &File, path: &Path) -> Result<Mmap> {
// SAFETY: the file descriptor remains open for the returned mapping's
// lifetime, and this mapping is read-only.
unsafe { MmapOptions::new().map(file) }
.with_context(|| format!("map extracted `{}`", path.display()))
}
senbei-io/src/atomic.rs
+16
View File
@@ -0,0 +1,16 @@
//! Shared atomic filesystem writes for native orchestration.
use std::path::{Path, PathBuf};
/// Write `bytes` through a sibling temporary file and replace `dest` only after
/// the complete write succeeds.
pub(crate) fn write_atomic(dest: &Path, bytes: &[u8]) -> std::io::Result<()> {
let mut temporary_name = dest.as_os_str().to_os_string();
temporary_name.push(".senbei-tmp");
let temporary = PathBuf::from(temporary_name);
let result = std::fs::write(&temporary, bytes).and_then(|()| std::fs::rename(&temporary, dest));
if result.is_err() {
let _ = std::fs::remove_file(&temporary);
}
result
}
senbei-io/src/job.rs
+9 -504
View File
@@ -1,326 +1,9 @@
use senbei_pe as unpacker;
use std::path::{Path, PathBuf};
/// Crackproof header key table lives at this fixed file offset. For the
/// external-companion layout, the companion payload aligns to the stub here.
const HEADER_OFF: usize = 4096;
/// Build the unpacker input for `input`, transparently handling the
/// **external-companion** layout used by some il2cpp games.
///
/// In that layout a protected module is split into a thin on-disk loader stub
/// (`Foo.dll`, whose code sections are stripped to one page) plus an encrypted
/// `Foo.dll._` companion holding the real payload. The companion is byte-for-byte
/// the stub's payload region starting at the Crackproof header (offset 4096), so
/// `stub[..4096] ++ companion` reconstructs the ordinary embedded-payload file
/// the existing pipelines already unpack. The runtime loader does exactly this:
/// it maps `Foo.dll._` and feeds it through the standard Crackproof unpack.
///
/// The splice fires only when a sibling `<input>._` exists *and* its first 32
/// bytes equal the stub's header at offset 4096 — a precise signal that the
/// companion is this stub's payload. Otherwise the file is returned untouched,
/// so normal (embedded-payload) inputs are unaffected.
fn read_unpacker_input(input: &Path) -> std::io::Result<UnpackerInput> {
let stub = std::fs::read(input)?;
// Companion path: append "._" to the full file name (Foo.dll -> Foo.dll._).
let companion = match input.file_name() {
Some(name) => {
let mut n = name.to_os_string();
n.push("._");
input.with_file_name(n)
}
None => {
return Ok(UnpackerInput {
bytes: stub,
stub: None,
});
}
use crate::atomic::write_atomic;
pub use crate::windows::{
UnpackedImage, unpack_bytes, unpack_bytes_force_exe, unpack_one, unpack_one_v,
};
if !companion.is_file() {
return Ok(UnpackerInput {
bytes: stub,
stub: None,
});
}
let comp = std::fs::read(&companion)?;
match splice_companion(&stub, &comp) {
// A splice fired: keep the stub so its plaintext export table can be
// overlaid onto the unpacked image (the companion does not carry it).
Some(spliced) => Ok(UnpackerInput {
bytes: spliced,
stub: Some(stub),
}),
None => Ok(UnpackerInput {
bytes: stub,
stub: None,
}),
}
}
/// The bytes fed to the unpacker, plus the original loader stub when the input
/// was reconstructed from an external companion. The stub is retained because
/// the crackproof loader rebuilds the PE export table at runtime from data kept
/// in the stub — that table is *not* present in the encrypted companion, so the
/// unpacked image needs it overlaid from the stub afterwards
/// (see [`overlay_exports_from_stub`]).
struct UnpackerInput {
bytes: Vec<u8>,
stub: Option<Vec<u8>>,
}
/// Overlay the PE export table from the loader `stub` onto the unpacked image
/// `out`, for the external-companion layout.
///
/// In that layout the encrypted companion carries the real `.text`/`il2cpp`
/// payload but **not** a usable export directory: the crackproof loader rebuilds
/// exports at runtime from the plaintext copy retained in the stub's `.rdata`.
/// Statically, the spliced input therefore decrypts to a garbage export
/// directory (`NumberOfFunctions` etc. are ciphertext), which makes downstream
/// tools (IL2CppDumper, IDA) choke when they parse it. The fix does what the
/// loader does: copy the export-directory region byte-for-byte from the stub to
/// the same RVA in the unpacked image.
///
/// No-op (leaves `out` untouched) if there is no export directory, or if the
/// region cannot be mapped in either image — so a malformed stub can never
/// corrupt an otherwise-good unpack.
fn overlay_exports_from_stub(out: &mut [u8], stub: &[u8]) {
let (export_rva, export_size) = match pe_export_dir(out) {
Some(v) if v.1 != 0 => v,
_ => return,
};
let dst = match rva_to_file_off(out, export_rva) {
Some(o) => o,
None => return,
};
let src = match rva_to_file_off(stub, export_rva) {
Some(o) => o,
None => return,
};
let n = export_size as usize;
if dst + n <= out.len() && src + n <= stub.len() {
out[dst..dst + n].copy_from_slice(&stub[src..src + n]);
}
}
/// Restore the TLS directory from the loader `stub` onto the unpacked image
/// `out`, for the external-companion layout.
///
/// Crackproof strips the whole `IMAGE_TLS_DIRECTORY` from the encrypted payload
/// — the data-directory entry, the directory struct, the raw-data template, and
/// the base relocations for the struct's four 64-bit pointer fields — and
/// re-installs TLS itself from data kept in the stub when it loads the module.
/// A statically-unpacked DLL is loaded by the ordinary Windows loader instead,
/// which needs a valid TLS directory or it never allocates a TLS slot for the
/// module nor writes `_tls_index`. The module's C++ `thread_local` accesses then
/// read a garbage TLS slot — observed as a `0xC0000005` deep in IL2CPP type
/// resolution (a TypeDef token used as a raw `s_TypeInfoTable` index).
///
/// The stub retains the full plaintext `.rdata` (only `.text`/`il2cpp` are
/// stripped to one page), so the directory struct and its raw-data template are
/// copied back byte-for-byte at their RVAs, the data-directory entry is taken
/// from the stub header (the unpacked image's was overwritten with the zeroed
/// saved-header blob), and four DIR64 relocations are appended to `.reloc`.
///
/// No-op if the stub declares no TLS directory or if any required region cannot
/// be mapped/relocated — so it can never corrupt an otherwise-good unpack.
fn restore_tls_from_stub(out: &mut [u8], stub: &[u8]) {
let pe = match read_u32(out, 0x3C) {
Some(v) => v as usize,
None => return,
};
if out.get(pe..pe + 4) != Some(&b"PE\0\0"[..]) {
return;
}
// This restore is PE32+-only: it copies a 40-byte IMAGE_TLS_DIRECTORY64,
// converts fields with a 64-bit image base, and appends DIR64 relocs. A
// PE32 module needs the 24-byte struct / DIR32 handling (the unpacker core
// does that itself — see `restore_pe32_tls_from_stub`), so bail rather than
// read the data directories at the wrong (PE32+) offset and write garbage.
if read_u16(out, pe + 24) != Some(0x20B) {
return;
}
// TLS is data-directory index 9 (PE32+ directories at optional header +112).
let tls_dd = match pe.checked_add(24 + 112 + 9 * 8) {
Some(v) => v,
None => return,
};
// The genuine entry survives in the stub header; the unpacked image's copy
// was clobbered by the (zeroed-TLS) saved-header blob.
let (tls_rva, tls_size) = match (read_u32(stub, tls_dd), read_u32(stub, tls_dd + 4)) {
(Some(r), Some(s)) if r != 0 && s != 0 => (r, s),
_ => return, // module has no TLS — nothing to restore
};
// Image base (PE32+, optional header +24) converts the struct's absolute VAs
// back to RVAs for the raw-data template overlay.
let image_base = match read_u64(out, pe + 24 + 24) {
Some(v) => v,
None => return,
};
// 1) Overlay the IMAGE_TLS_DIRECTORY struct from the stub at its RVA.
let dst = match rva_to_file_off(out, tls_rva) {
Some(o) => o,
None => return,
};
let src = match rva_to_file_off(stub, tls_rva) {
Some(o) => o,
None => return,
};
let n = tls_size as usize;
if dst.checked_add(n).is_none_or(|e| e > out.len())
|| src.checked_add(n).is_none_or(|e| e > stub.len())
{
return;
}
out[dst..dst + n].copy_from_slice(&stub[src..src + n]);
// 2) Restore the data-directory entry so the loader processes TLS at all.
write_u32_at(out, tls_dd, tls_rva);
write_u32_at(out, tls_dd + 4, tls_size);
// 3) Overlay the raw-data template [StartAddressOfRawData, EndAddressOfRawData).
if let (Some(start_va), Some(end_va)) = (read_u64(out, dst), read_u64(out, dst + 8))
&& end_va > start_va
&& start_va >= image_base
{
let tpl_rva = (start_va - image_base) as u32;
let tpl_len = (end_va - start_va) as usize;
if let (Some(td), Some(ts)) = (
rva_to_file_off(out, tpl_rva),
rva_to_file_off(stub, tpl_rva),
) && td.checked_add(tpl_len).is_some_and(|e| e <= out.len())
&& ts.checked_add(tpl_len).is_some_and(|e| e <= stub.len())
{
out[td..td + tpl_len].copy_from_slice(&stub[ts..ts + tpl_len]);
}
}
// 4) Append DIR64 relocations for the struct's four 64-bit pointer fields
// (Start/End/Index/CallBacks at +0/+8/+0x10/+0x18). Without them the
// loader would leave preferred-base VAs in a rebased image.
add_tls_relocs(out, pe, tls_rva);
}
/// Append a single base-relocation block covering the four 64-bit pointer fields
/// of the TLS directory struct at `tls_rva`. The block is written immediately
/// after the existing relocation table (which must be free space and in bounds)
/// and the BaseReloc directory size is grown to include it. No-op if the table
/// is absent, the fields straddle a relocation page, or the slot is not free.
fn add_tls_relocs(out: &mut [u8], pe: usize, tls_rva: u32) {
let reloc_dd = pe + 24 + 112 + 5 * 8; // BaseReloc = directory index 5
let (reloc_rva, reloc_size) = match (read_u32(out, reloc_dd), read_u32(out, reloc_dd + 4)) {
(Some(r), Some(s)) if r != 0 => (r, s),
_ => return,
};
// All four fields (last at +0x18) must share one 0x1000 relocation page.
let page = tls_rva & !0xFFF;
if (tls_rva.wrapping_add(0x18)) & !0xFFF != page {
return;
}
const BLOCK: usize = 8 + 4 * 2; // header + four DIR64 entries
let at = match rva_to_file_off(out, reloc_rva.wrapping_add(reloc_size)) {
Some(o) => o,
None => return,
};
if at.checked_add(BLOCK).is_none_or(|e| e > out.len()) {
return;
}
if out[at..at + BLOCK].iter().any(|&b| b != 0) {
return; // refuse to clobber existing data
}
write_u32_at(out, at, page);
write_u32_at(out, at + 4, BLOCK as u32);
for (i, off) in [0u32, 8, 0x10, 0x18].iter().enumerate() {
let entry = (10u16 << 12) | (((tls_rva.wrapping_add(*off)) & 0xFFF) as u16);
let p = at + 8 + i * 2;
out[p..p + 2].copy_from_slice(&entry.to_le_bytes());
}
write_u32_at(out, reloc_dd + 4, reloc_size.wrapping_add(BLOCK as u32));
}
/// Read the Export data-directory (RVA, size) from a PE image, or `None` if the
/// headers are too short/invalid to parse.
fn pe_export_dir(buf: &[u8]) -> Option<(u32, u32)> {
let pe = read_u32(buf, 0x3C)? as usize;
if buf.get(pe..pe + 4)? != b"PE\0\0" {
return None;
}
// Optional header at pe+24; data directories start at +96 on PE32 (0x10B)
// and +112 on PE32+ (0x20B); Export is index 0.
let dd_base = match read_u16(buf, pe + 24)? {
0x20B => 112,
0x10B => 96,
_ => return None,
};
let dd = pe.checked_add(24 + dd_base)?;
Some((read_u32(buf, dd)?, read_u32(buf, dd + 4)?))
}
/// Map an RVA to a file offset using the PE section table. Returns `None` if no
/// section contains the RVA or the headers cannot be parsed.
fn rva_to_file_off(buf: &[u8], rva: u32) -> Option<usize> {
let pe = read_u32(buf, 0x3C)? as usize;
if buf.get(pe..pe + 4)? != b"PE\0\0" {
return None;
}
let nsec = read_u16(buf, pe + 6)? as usize;
let opt_size = read_u16(buf, pe + 20)? as usize;
let sh = pe.checked_add(24)?.checked_add(opt_size)?;
for i in 0..nsec {
let o = sh.checked_add(i.checked_mul(40)?)?;
let vsz = read_u32(buf, o + 8)?;
let va = read_u32(buf, o + 12)?;
let raw = read_u32(buf, o + 20)?;
if rva >= va && rva < va.wrapping_add(vsz.max(1)) {
return Some((rva - va).wrapping_add(raw) as usize);
}
}
None
}
fn read_u32(buf: &[u8], off: usize) -> Option<u32> {
let b = buf.get(off..off + 4)?;
Some(u32::from_le_bytes([b[0], b[1], b[2], b[3]]))
}
fn read_u16(buf: &[u8], off: usize) -> Option<u16> {
let b = buf.get(off..off + 2)?;
Some(u16::from_le_bytes([b[0], b[1]]))
}
fn read_u64(buf: &[u8], off: usize) -> Option<u64> {
let b = buf.get(off..off + 8)?;
Some(u64::from_le_bytes([
b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7],
]))
}
/// Write a little-endian `u32` at `off`, silently doing nothing if out of bounds.
fn write_u32_at(buf: &mut [u8], off: usize, val: u32) {
if let Some(slot) = buf.get_mut(off..off + 4) {
slot.copy_from_slice(&val.to_le_bytes());
}
}
/// Splice a stub and its external-companion payload into the embedded-payload
/// form the pipelines expect, or `None` if `comp` is not this stub's payload.
///
/// The companion is byte-for-byte the stub's payload region from the Crackproof
/// header (offset 4096) onward, so the result is `stub[..4096] ++ comp`. The
/// splice fires only when the first 32 bytes of `comp` equal the stub's header
/// at offset 4096 — a 32-byte match on the key-table/magic region that confirms
/// the pairing and leaves ordinary (non-companion) inputs untouched.
fn splice_companion(stub: &[u8], comp: &[u8]) -> Option<Vec<u8>> {
let hdr_end = HEADER_OFF + 32;
if stub.len() >= hdr_end && comp.len() >= 32 && stub[HEADER_OFF..hdr_end] == comp[..32] {
let mut spliced = Vec::with_capacity(HEADER_OFF + comp.len());
spliced.extend_from_slice(&stub[..HEADER_OFF]);
spliced.extend_from_slice(comp);
return Some(spliced);
}
None
}
/// Summary of a folder-mode run.
#[derive(Default)]
@@ -403,11 +86,8 @@ pub fn run_folder_v(
/// Like [`run_folder_v`], but with the scan pre-filter explicitly controlled.
///
/// When `scan_all` is true every regular file under `root` is opened and
/// content-probed, instead of skipping ones the free directory metadata already
/// rules out (extensionless, too small to hold a Crackproof key table, or a
/// bulk-asset extension). See [`crate::scan::find_targets_opts`] — exhaustive
/// scanning is dramatically slower on asset-heavy trees.
/// When `scan_all` is true selected target names below the minimum size are
/// also opened and content-probed. Other filenames are never opened.
pub fn run_folder_opts(
root: &Path,
out_dir: Option<&Path>,
@@ -549,8 +229,8 @@ pub fn run_folder_opts(
let dest = out_root.join(out_name(&rel));
// Unreadable here is fine: the restore reports the same error.
if android_dedup
&& let Ok(bytes) = std::fs::read(input)
&& !android_seen.insert(crate::android::content_identity(&bytes))
&& let Ok(identity) = crate::android::file_content_identity(input)
&& !android_seen.insert(identity)
{
s.skipped += 1;
if let Some(log) = &log {
@@ -816,10 +496,8 @@ pub fn run_file_v(
// library probe needs the whole file (its payload section is found through
// the section-header table at the end), while a package is a container
// handled entry-by-entry. Anything else falls through to the PE pipeline.
let is_android_so = crate::android::is_elf64_aarch64(&prefix)
&& std::fs::read(input)
.map(|bytes| senbei_android_engine::is_protected_libil2cpp(&bytes))
.unwrap_or(false);
let is_android_so =
crate::android::is_elf64_aarch64(&prefix) && crate::android::is_protected_so_file(input);
let is_android_package = !is_android_so && crate::android::is_app_package(input, &prefix);
if is_meta {
@@ -1041,139 +719,6 @@ fn unsupported_version(e: &anyhow::Error) -> Option<u32> {
None
}
/// Write `bytes` to `dest` atomically: a sibling temp file, then a rename.
/// A direct `std::fs::write` truncates the destination first, so a mid-write
/// failure (disk full, AV lock, quota) destroys a previously good unpack at
/// the same path; the temp+rename keeps the old file until the new one is
/// complete. Best-effort temp cleanup on failure.
pub(crate) fn write_atomic(dest: &Path, bytes: &[u8]) -> std::io::Result<()> {
let mut tmp_name = dest.as_os_str().to_os_string();
tmp_name.push(".senbei-tmp");
let tmp = PathBuf::from(tmp_name);
let r = std::fs::write(&tmp, bytes).and_then(|()| std::fs::rename(&tmp, dest));
if r.is_err() {
let _ = std::fs::remove_file(&tmp);
}
r
}
/// Detect `bytes` and run the right pipeline. Spliced external companions use
/// the EXE pipeline directly because that layout is definitionally EXE-style.
///
/// Routing spliced inputs straight to the EXE pipeline is safe: the
/// companion layout is definitionally the EXE-style shell (the runtime
/// loader maps the companion and runs the standard shell unpack), so the DLL
/// pipeline probe can never be right for it. Output bytes are identical to the
/// DLL-first + EXE-fallback route for every input that route handles.
fn unpack_spliced_or_auto(
bytes: &[u8],
spliced: bool,
force_exe: bool,
verbose: bool,
) -> Result<(unpacker::Kind, Vec<u8>), unpacker::UnpackError> {
if spliced || force_exe {
let detected = unpacker::detect(bytes).ok_or(unpacker::UnpackError::NotCrackproof)?;
let out = unpacker::unpack_exe_v(bytes, verbose)?;
return Ok((detected.kind, out));
}
unpacker::unpack_auto_v(bytes, verbose)
}
/// Unpack a single file to `dest`. Returns the Kind and integrity report on success.
pub fn unpack_one(
input: &Path,
dest: &Path,
) -> anyhow::Result<(unpacker::Kind, unpacker::IntegrityReport)> {
unpack_one_v(input, dest, false)
}
/// Outcome of a byte-level unpack ([`unpack_bytes`]): the image, its detected
/// kind, and its integrity report. No file I/O is involved.
pub struct UnpackedImage {
pub kind: unpacker::Kind,
pub bytes: Vec<u8>,
pub integrity: unpacker::IntegrityReport,
/// True when the input was reconstructed from an external companion (the
/// `._` layout), i.e. the export/TLS overlays ran.
pub companion: bool,
}
/// Unpack in-memory `input` bytes, optionally paired with an external
/// companion payload `companion` (the `<input>._` file's contents).
///
/// This is the in-memory counterpart of [`unpack_one_v`]: splice a matching
/// companion, unpack, overlay the export table and TLS directory from the stub,
/// then run the static integrity check.
pub fn unpack_bytes(
input: &[u8],
companion: Option<&[u8]>,
) -> Result<UnpackedImage, unpacker::UnpackError> {
unpack_bytes_impl(input, companion, false)
}
/// Like [`unpack_bytes`], but forces the EXE pipeline (no DLL-pipeline
/// probe). This is the web app's recovery path: the DLL-first probe relies
/// on `catch_unwind` to reject EXE-shell-layout DLLs, and panics cannot be
/// caught on wasm — the probe traps the whole call. The web app runs each
/// unpack in a disposable Web Worker and retries trapped DLLs with this
/// entry point, reproducing the CLI's dll-first/exe-fallback routing.
pub fn unpack_bytes_force_exe(
input: &[u8],
companion: Option<&[u8]>,
) -> Result<UnpackedImage, unpacker::UnpackError> {
unpack_bytes_impl(input, companion, true)
}
fn unpack_bytes_impl(
input: &[u8],
companion: Option<&[u8]>,
force_exe: bool,
) -> Result<UnpackedImage, unpacker::UnpackError> {
let spliced = companion.and_then(|c| splice_companion(input, c));
let bytes: &[u8] = spliced.as_deref().unwrap_or(input);
let (kind, mut out) = unpack_spliced_or_auto(bytes, spliced.is_some(), force_exe, false)?;
if spliced.is_some() {
overlay_exports_from_stub(&mut out, input);
restore_tls_from_stub(&mut out, input);
}
let integrity = unpacker::check_integrity(&out);
Ok(UnpackedImage {
kind,
bytes: out,
integrity,
companion: spliced.is_some(),
})
}
/// Like [`unpack_one`], but prints detailed `[N/9]` step progress (and a final
/// `Write to <dest>` line) to stdout when `verbose` is true.
pub fn unpack_one_v(
input: &Path,
dest: &Path,
verbose: bool,
) -> anyhow::Result<(unpacker::Kind, unpacker::IntegrityReport)> {
let UnpackerInput { bytes, stub } = read_unpacker_input(input)?;
let (kind, mut out) = unpack_spliced_or_auto(&bytes, stub.is_some(), false, verbose)?;
// External-companion layout: restore the export table from the stub, which
// the encrypted companion does not carry (the loader rebuilds it at runtime).
if let Some(stub) = stub {
overlay_exports_from_stub(&mut out, &stub);
// ...and the TLS directory, which Crackproof strips from the payload and
// re-installs at runtime; the ordinary loader needs it or thread_local
// access crashes (see [`restore_tls_from_stub`]).
restore_tls_from_stub(&mut out, &stub);
}
let report = unpacker::check_integrity(&out);
if let Some(parent) = dest.parent() {
std::fs::create_dir_all(parent)?;
}
write_atomic(dest, &out)?;
if verbose {
println!("Write to {}", dest.display());
}
Ok((kind, report))
}
/// De-obfuscate an il2cpp `global-metadata.dat` to `dest`.
///
/// Crackproof's `-GMD` option scrambles each `Il2CppMethodDefinition`'s token
@@ -1302,44 +847,4 @@ mod tests {
let rel = rel_in_tree(root, under);
assert_eq!(rel.as_ref(), Path::new(r"bin\app.exe"));
}
fn stub_with_header(header: &[u8; 32], extra: usize) -> Vec<u8> {
let mut s = vec![0u8; HEADER_OFF];
s.extend_from_slice(header);
s.extend_from_slice(&vec![0xAAu8; extra]);
s
}
#[test]
fn splices_when_header_matches() {
let header = [7u8; 32];
let stub = stub_with_header(&header, 16);
// Companion: same 32-byte header, then the real (longer) payload.
let mut comp = header.to_vec();
comp.extend_from_slice(&[0x42u8; 1000]);
let out = splice_companion(&stub, &comp).expect("should splice");
assert_eq!(out.len(), HEADER_OFF + comp.len());
assert_eq!(&out[..HEADER_OFF], &stub[..HEADER_OFF]);
assert_eq!(&out[HEADER_OFF..], &comp[..]);
}
#[test]
fn no_splice_when_header_differs() {
let stub = stub_with_header(&[7u8; 32], 16);
let mut comp = vec![9u8; 32]; // different header
comp.extend_from_slice(&[0x42u8; 1000]);
assert!(splice_companion(&stub, &comp).is_none());
}
#[test]
fn no_splice_when_too_short() {
let short_stub = vec![0u8; HEADER_OFF + 8]; // < HEADER_OFF + 32
let comp = vec![0u8; 64];
assert!(splice_companion(&short_stub, &comp).is_none());
let stub = stub_with_header(&[1u8; 32], 0);
let short_comp = vec![1u8; 16]; // < 32
assert!(splice_companion(&stub, &short_comp).is_none());
}
}
senbei-io/src/lib.rs
+5
View File
@@ -1,8 +1,13 @@
//! Filesystem and command-line orchestration.
/// File name of an IL2CPP metadata blob shared by both platform scanners.
pub const METADATA_FILE_NAME: &str = "global-metadata.dat";
pub mod android;
mod atomic;
pub mod job;
pub mod logfile;
pub mod pause;
pub mod scan;
pub mod ui;
pub mod windows;
senbei-io/src/scan.rs
+96 -165
View File
@@ -1,4 +1,4 @@
use senbei_pe::detect;
use senbei_engine::detect;
use std::io::Read;
use std::path::{Path, PathBuf};
use walkdir::WalkDir;
@@ -16,7 +16,7 @@ const DETECT_PREFIX: u64 = 8 * 1024;
/// Smallest file that can possibly be a target, so anything shorter is skipped
/// without ever being opened.
///
/// A Crackproof module needs ≥ 4128 bytes for [`senbei_pe::detect`]'s key
/// A Crackproof module needs ≥ 4128 bytes for [`senbei_engine::detect`]'s key
/// table (it reads the dword at 4124), so the bound is exact for the unpack
/// path. An il2cpp `global-metadata.dat` only needs 4 bytes to match its magic,
/// but its header alone runs to offset 0xB0 and the images/types/methods tables
@@ -25,85 +25,10 @@ const DETECT_PREFIX: u64 = 8 * 1024;
/// processable is lost.
const MIN_SIZE: u64 = 4128;
/// File extensions that are bulk data by construction and can never be a PE
/// image or an il2cpp metadata blob.
///
/// This is deliberately a **deny**-list, not an executable allow-list: unknown
/// extensions are still probed. Extensionless files are handled separately by
/// [`denied_name`] because asset stores commonly contain tens of thousands of
/// extensionless chunks; exhaustive probing remains available through
/// `--scan-all`.
///
/// Set `SENBEI_SCAN_ALL=1` (or pass `--scan-all`) to probe every file regardless.
const DENY_EXT: &[&str] = &[
// Unity and other engine asset containers
"ab",
"bundle",
"unity3d",
"manifest",
"resource",
"ress",
"assets",
"sharedassets",
// audio / video / image / font
"acb",
"awb",
"usm",
"wav",
"ogg",
"mp3",
"mp4",
"avi",
"png",
"jpg",
"jpeg",
"bmp",
"gif",
"tga",
"dds",
"svg",
"ttf",
"otf",
// text, markup, config, logs
"xml",
"json",
"txt",
"csv",
"md",
"toml",
"ini",
"yml",
"yaml",
"log",
"html",
"htm",
"css",
"aspx",
"browser",
"config",
"sig",
"map",
"pdb",
// rhythm-game chart/score data
"ma2",
"sr",
];
/// Whether `path` can be skipped from its name alone. Extensionless files and
/// files whose extension is on [`DENY_EXT`] are not opened during a default
/// scan. `--scan-all` remains available when exhaustive probing is required.
fn denied_name(path: &Path) -> bool {
let Some(ext) = path.extension() else {
return true;
};
let Some(ext) = ext.to_str() else {
return false;
};
// Extensions are ASCII in practice; compare case-insensitively without
// allocating for the overwhelmingly common non-match.
DENY_EXT
.iter()
.any(|d| d.len() == ext.len() && d.eq_ignore_ascii_case(ext))
fn is_metadata_name(path: &Path) -> bool {
path.file_name()
.and_then(|name| name.to_str())
.is_some_and(|name| name.eq_ignore_ascii_case(crate::METADATA_FILE_NAME))
}
/// Content classification of a single file.
@@ -151,16 +76,14 @@ pub struct ScanResult {
/// per-file I/O latency, not bandwidth (that tree lives on a user-mode virtual
/// disk that tops out near 1,300 IOPS). Thread count barely moves it either.
///
/// So the only lever is **probing fewer files**, which is what [`MIN_SIZE`] and
/// [`DENY_EXT`] do — both decided from the free directory metadata, before any
/// file is opened. On that tree they cut 46,446 probes to 1,814 and the scan
/// from ~40 s to ~2 s while still finding every target.
/// So the only lever is **probing fewer files**, which is what the target-name
/// filter and [`MIN_SIZE`] do — both decided before any file is opened.
///
/// The surviving probes (open + short read + magic test) are fanned out across
/// worker threads. Directory traversal itself stays serial (one cheap `readdir`
/// pass, no file opens) because it feeds the parallel probe.
/// The selected probes (open + short read + magic test) are fanned out across
/// worker threads. Directory traversal itself stays serial because it only
/// collects names and sizes before the parallel probe.
///
/// Thread count follows [`crate::unpacker::parallel::thread_cap`] (honoring
/// Thread count follows [`senbei_engine::thread_cap`] (honoring
/// `SENBEI_THREADS`, `1` = fully sequential). Output order is independent of
/// thread count: each worker owns a disjoint contiguous slice of the path list
/// and writes the matching disjoint slice of the class list, so results are
@@ -186,8 +109,7 @@ pub struct ScanStats {
}
/// [`find_targets`], but with the pre-filter explicitly controlled. When
/// `scan_all` is true every regular file is probed, restoring the exhaustive
/// (and on asset-heavy trees, far slower) behavior.
/// `scan_all` is true selected target names below [`MIN_SIZE`] are also probed.
pub fn find_targets_opts(root: &Path, scan_all: bool) -> ScanResult {
// Phase 1: serial traversal collecting regular-file paths only. No file is
// opened here; `readdir` is fast relative to the content probe that follows,
@@ -212,7 +134,7 @@ pub fn find_targets_opts(root: &Path, scan_all: bool) -> ScanResult {
// Skip reparse-point directories (junctions, symlink-dirs): they point
// outside the scanned tree — walking one would silently unpack an
// entire foreign tree (e.g. a `samples` junction into the golden corpus).
!is_reparse_point(e)
!crate::windows::is_reparse_point(e)
}) {
let entry = match entry {
Ok(e) => e,
@@ -224,12 +146,17 @@ pub fn find_targets_opts(root: &Path, scan_all: bool) -> ScanResult {
if !entry.file_type().is_file() {
continue;
}
if !scan_all {
// Name checks come first so extensionless asset chunks never
// trigger even an explicit metadata query.
if denied_name(entry.path()) {
if crate::windows::is_companion(entry.path()) {
continue;
}
if !is_metadata_name(entry.path())
&& !crate::windows::is_pe_extension(entry.path())
&& !crate::android::is_so_name(entry.path())
&& !crate::android::is_package_name(entry.path())
{
continue;
}
if !scan_all {
// Skip on directory metadata alone — never open these.
let too_small = entry
.metadata()
@@ -247,7 +174,7 @@ pub fn find_targets_opts(root: &Path, scan_all: bool) -> ScanResult {
// `Some(Class::None)` means "probed, matched neither detector".
let n = paths.len();
let mut class: Vec<Option<Class>> = vec![Some(Class::None); n];
let workers = senbei_pe::thread_cap().clamp(1, n.max(1));
let workers = senbei_engine::thread_cap().clamp(1, n.max(1));
if workers <= 1 {
for (p, c) in paths.iter().zip(class.iter_mut()) {
*c = classify(p);
@@ -284,29 +211,9 @@ pub fn find_targets_opts(root: &Path, scan_all: bool) -> ScanResult {
result
}
/// True if a walked directory entry is a reparse point (junction or symlink).
///
/// `DirEntry::file_type` only flags true symlinks; NTFS junctions report as
/// ordinary directories, so without this check the walker descends into them.
/// Off-Windows there are no junctions — symlink dirs are already excluded
/// because `follow_links` is off (their `file_type().is_dir()` is false).
#[cfg(windows)]
fn is_reparse_point(e: &walkdir::DirEntry) -> bool {
use std::os::windows::fs::MetadataExt;
const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x400;
e.metadata()
.map(|m| m.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0)
.unwrap_or(false)
}
#[cfg(not(windows))]
fn is_reparse_point(_e: &walkdir::DirEntry) -> bool {
false
}
/// Whether the scan pre-filter is disabled via `SENBEI_SCAN_ALL`. Any value
/// other than `0`/empty turns exhaustive scanning on. The `--scan-all` flag is
/// ORed with this.
/// Whether the size pre-filter is disabled via `SENBEI_SCAN_ALL`. Any value
/// other than `0`/empty enables probing small selected target names. It never
/// expands the platform filename boundary.
pub fn scan_all_env() -> bool {
match std::env::var("SENBEI_SCAN_ALL") {
Ok(v) => !matches!(v.trim(), "" | "0"),
@@ -314,9 +221,8 @@ pub fn scan_all_env() -> bool {
}
}
/// Classify one file by content. Reads a short prefix once and tests the
/// Crackproof detector first, then the il2cpp metadata magic, then the
/// Android probes. Returns `None` when the file could not be classified at
/// Classify one named candidate by content. Reads a short prefix once and tests
/// the detector for that platform. Returns `None` when the file could not be classified at
/// all — an I/O error opening it (locked, permissions) or a panic inside a
/// detector — so the caller counts it as a probe error rather than a clean
/// "not a target" skip.
@@ -332,27 +238,25 @@ pub fn scan_all_env() -> bool {
/// The Android library probe needs more than the prefix: the protection
/// payload lives in a section found via the section-header table at the *end*
/// of the file, so an ELF64/AArch64 prefix triggers a full-file read. Only
/// aarch64 images pay for it — a handful of `.so` files per app tree, against
/// tens of thousands of assets the free name/size checks already rejected.
/// selected `.so` images pay for it.
fn classify(path: &Path) -> Option<Class> {
let head = read_prefix(path, DETECT_PREFIX)?;
let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
if detect(&head).is_some() {
return Class::Crackproof;
if crate::android::is_package_name(path) && crate::android::is_app_package(path, &head) {
return Class::AndroidPackage;
}
if senbei_metadata::is_metadata(&head) {
if is_metadata_name(path) && senbei_metadata::is_metadata(&head) {
return Class::Metadata;
}
if crate::android::is_elf64_aarch64(&head)
&& std::fs::read(path)
.map(|bytes| senbei_android_engine::is_protected_libil2cpp(&bytes))
.unwrap_or(false)
if crate::windows::is_pe_extension(path) && detect(&head).is_some() {
return Class::Crackproof;
}
if crate::android::is_so_name(path)
&& crate::android::is_elf64_aarch64(&head)
&& crate::android::is_protected_so_file(path)
{
return Class::AndroidSo;
}
if crate::android::is_app_package(path, &head) {
return Class::AndroidPackage;
}
Class::None
}));
r.ok()
@@ -372,38 +276,39 @@ mod tests {
use super::*;
#[test]
fn denies_bulk_asset_extensions_case_insensitively() {
for p in ["a.ab", "a.XML", "a.Acb", "a.ma2", "a.manifest", "a.PNG"] {
assert!(denied_name(Path::new(p)), "{p} should be denied");
fn candidate_names_are_platform_specific() {
for p in [
"daemon.exe",
"GameLib.DLL",
"libil2cpp.so",
"global-metadata.dat",
] {
assert!(
is_metadata_name(Path::new(p))
|| crate::windows::is_pe_extension(Path::new(p))
|| crate::android::is_so_name(Path::new(p)),
"{p} should be a candidate"
);
}
}
#[test]
fn denies_extensionless_files() {
for p in ["asset", "level0", "0123456789abcdef"] {
assert!(denied_name(Path::new(p)), "{p} should be denied");
}
}
#[test]
fn never_denies_what_a_target_can_be_named() {
// Unknown extensions must still be probed. This keeps the filter a
// narrow deny-list rather than an executable-extension allow-list.
for p in [
"app.exe.bak",
"managed.dll.bak",
"daemon.exe",
"GameLib.dll",
"global-metadata.dat",
"a.so",
"a.bin",
"libil2cpp.so.bak",
"global-metadata.bin",
"asset",
"a.ab",
] {
assert!(!denied_name(Path::new(p)), "{p} must still be probed");
assert!(
!is_metadata_name(Path::new(p))
&& !crate::windows::is_pe_extension(Path::new(p))
&& !crate::android::is_so_name(Path::new(p)),
"{p} must not be a candidate"
);
}
}
#[test]
fn extensionless_targets_require_exhaustive_scan() {
fn extensionless_targets_are_not_candidates() {
let td = tempfile::tempdir().unwrap();
let root = td.path();
let mut blob = vec![0u8; MIN_SIZE as usize + 1];
@@ -414,13 +319,13 @@ mod tests {
assert!(filtered.metadata.is_empty());
let exhaustive = find_targets_opts(root, true);
assert_eq!(exhaustive.metadata.len(), 1);
assert!(exhaustive.metadata.is_empty());
}
/// A file below the Crackproof key-table bound is skipped without being
/// opened, but a large non-asset file is still probed.
/// A selected file below the Crackproof key-table bound is skipped without
/// being opened, while `scan_all` probes it.
#[test]
fn prefilter_skips_small_and_denied_files_only() {
fn prefilter_skips_small_selected_files_only() {
let td = tempfile::tempdir().unwrap();
let root = td.path();
std::fs::write(root.join("tiny.dll"), vec![0u8; 100]).unwrap();
@@ -428,15 +333,15 @@ mod tests {
std::fs::write(root.join("plain.dll"), vec![0u8; 100_000]).unwrap();
// None of them are Crackproof, so both modes find nothing; the point is
// that the filtered walk does not panic and honors `scan_all`.
// that only the selected names are considered and `scan_all` controls
// the size floor.
let scan = find_targets_opts(root, false);
assert!(scan.crackproof.is_empty() && scan.metadata.is_empty());
let scan = find_targets_opts(root, true);
assert!(scan.crackproof.is_empty() && scan.metadata.is_empty());
}
/// An il2cpp metadata blob is found by the filtered scan: `.dat` is not on
/// the deny-list and a real one is far above `MIN_SIZE`.
/// An exact `global-metadata.dat` name is found by the filtered scan.
#[test]
fn finds_metadata_through_the_prefilter() {
let td = tempfile::tempdir().unwrap();
@@ -479,4 +384,30 @@ mod tests {
);
assert_eq!(scan.stats.walk_errors, 0);
}
#[test]
fn companion_payload_is_not_counted_as_skipped() {
let td = tempfile::tempdir().unwrap();
let root = td.path();
std::fs::write(root.join("app.exe"), vec![0u8; MIN_SIZE as usize]).unwrap();
std::fs::write(root.join("app.exe._"), vec![0u8; MIN_SIZE as usize]).unwrap();
let scan = find_targets_opts(root, false);
assert_eq!(scan.stats.skipped, 1, "only the stub was probed");
assert!(crate::windows::is_companion(&root.join("app.exe._")));
}
#[test]
fn scan_all_keeps_the_platform_name_boundary() {
let td = tempfile::tempdir().unwrap();
let root = td.path();
let mut metadata = vec![0_u8; MIN_SIZE as usize];
metadata[..4].copy_from_slice(&0xFAB1_1BAFu32.to_le_bytes());
std::fs::write(root.join("renamed.bin"), &metadata).unwrap();
std::fs::write(root.join("global-metadata.dat"), &metadata).unwrap();
let scan = find_targets_opts(root, true);
assert_eq!(scan.metadata.len(), 1);
assert!(scan.metadata[0].ends_with("global-metadata.dat"));
}
}
senbei-io/src/ui.rs
+1 -1
View File
@@ -1,6 +1,6 @@
use indicatif::{ProgressBar, ProgressStyle};
use owo_colors::OwoColorize;
use senbei_pe::{IntegrityReport, Kind};
use senbei_engine::{IntegrityReport, Kind};
use std::path::Path;
/// Create a progress bar for `n` items. Hidden when `quiet` is true.
senbei-io/src/windows/mod.rs
+677
View File
@@ -0,0 +1,677 @@
//! Windows filesystem adapter for PE companion payloads and byte APIs.
use senbei_engine as unpacker;
use std::path::Path;
use crate::atomic::write_atomic;
pub(crate) fn is_pe_extension(path: &Path) -> bool {
path.extension()
.and_then(|ext| ext.to_str())
.is_some_and(|ext| ext.eq_ignore_ascii_case("exe") || ext.eq_ignore_ascii_case("dll"))
}
pub(crate) fn is_companion(path: &Path) -> bool {
let Some(name) = path.file_name().and_then(|name| name.to_str()) else {
return false;
};
let Some(stub_name) = name.strip_suffix("._") else {
return false;
};
is_pe_extension(Path::new(stub_name))
}
/// Return whether a directory entry is an NTFS reparse point. The scanner keeps
/// this host-specific check in the Windows adapter while the traversal itself
/// remains platform-neutral.
#[cfg(windows)]
pub(crate) fn is_reparse_point(entry: &walkdir::DirEntry) -> bool {
use std::os::windows::fs::MetadataExt;
const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x400;
entry
.metadata()
.map(|metadata| metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0)
.unwrap_or(false)
}
#[cfg(not(windows))]
pub(crate) fn is_reparse_point(_entry: &walkdir::DirEntry) -> bool {
false
}
/// Crackproof header key table lives at this fixed file offset. For the
/// external-companion layout, the companion payload aligns to the stub here.
const HEADER_OFF: usize = 4096;
/// Build the unpacker input for `input`, transparently handling the
/// **external-companion** layout used by some il2cpp games.
///
/// In that layout a protected module is split into a thin on-disk loader stub
/// (`Foo.dll`, whose code sections are stripped to one page) plus an encrypted
/// `Foo.dll._` companion holding the real payload. The companion is byte-for-byte
/// the stub's payload region starting at the Crackproof header (offset 4096), so
/// `stub[..4096] ++ companion` reconstructs the ordinary embedded-payload file
/// the existing pipelines already unpack. The runtime loader does exactly this:
/// it maps `Foo.dll._` and feeds it through the standard Crackproof unpack.
///
/// The splice fires only when a sibling `<input>._` exists *and* its first 32
/// bytes equal the stub's header at offset 4096 — a precise signal that the
/// companion is this stub's payload. Otherwise the file is returned untouched,
/// so normal (embedded-payload) inputs are unaffected.
pub(crate) fn read_unpacker_input(input: &Path) -> std::io::Result<UnpackerInput> {
let stub = std::fs::read(input)?;
// Companion path: append "._" to the full file name (Foo.dll -> Foo.dll._).
let companion = match input.file_name() {
Some(name) => {
let mut n = name.to_os_string();
n.push("._");
input.with_file_name(n)
}
None => {
return Ok(UnpackerInput {
bytes: stub,
stub: None,
});
}
};
if !companion.is_file() {
return Ok(UnpackerInput {
bytes: stub,
stub: None,
});
}
let comp = std::fs::read(&companion)?;
match splice_companion(&stub, &comp) {
// A splice fired: keep the stub so its plaintext export table can be
// overlaid onto the unpacked image (the companion does not carry it).
Some(spliced) => Ok(UnpackerInput {
bytes: spliced,
stub: Some(stub),
}),
None => Ok(UnpackerInput {
bytes: stub,
stub: None,
}),
}
}
/// The bytes fed to the unpacker, plus the original loader stub when the input
/// was reconstructed from an external companion. The stub is retained because
/// the crackproof loader rebuilds the PE export table at runtime from data kept
/// in the stub — that table is *not* present in the encrypted companion, so the
/// unpacked image needs it overlaid from the stub afterwards
/// (see [`overlay_exports_from_stub`]).
pub(crate) struct UnpackerInput {
pub(crate) bytes: Vec<u8>,
pub(crate) stub: Option<Vec<u8>>,
}
/// Overlay the PE export table from the loader `stub` onto the unpacked image
/// `out`, for the external-companion layout.
///
/// In that layout the encrypted companion carries the real `.text`/`il2cpp`
/// payload but **not** a usable export directory: the crackproof loader rebuilds
/// exports at runtime from the plaintext copy retained in the stub's `.rdata`.
/// Statically, the spliced input therefore decrypts to a garbage export
/// directory (`NumberOfFunctions` etc. are ciphertext), which makes downstream
/// tools (IL2CppDumper, IDA) choke when they parse it. The fix does what the
/// loader does: copy the export-directory region byte-for-byte from the stub to
/// the same RVA in the unpacked image.
///
/// No-op (leaves `out` untouched) if there is no export directory, or if the
/// region cannot be mapped in either image — so a malformed stub can never
/// corrupt an otherwise-good unpack.
pub(crate) fn overlay_exports_from_stub(out: &mut [u8], stub: &[u8]) {
let (export_rva, export_size) = match pe_export_dir(out) {
Some(v) if v.1 != 0 => v,
_ => return,
};
let dst = match rva_to_file_off(out, export_rva) {
Some(o) => o,
None => return,
};
let src = match rva_to_file_off(stub, export_rva) {
Some(o) => o,
None => return,
};
let n = export_size as usize;
if dst + n <= out.len() && src + n <= stub.len() {
out[dst..dst + n].copy_from_slice(&stub[src..src + n]);
}
}
/// Restore the CLR regions retained by an external-companion loader stub.
/// Method bodies come from the unpacked payload and must not be overlaid.
fn restore_managed_from_stub(out: &mut [u8], stub: &[u8]) -> Result<(), unpacker::UnpackError> {
let failure =
|region, source| unpacker::UnpackError::ManagedStubRestoreFailed { region, source };
let source_headers = senbei_pe::parse(stub).map_err(|e| failure("PE headers", e))?;
let (clr_rva, clr_size) = senbei_pe::data_directory(stub, source_headers, 14)
.map_err(|e| failure("CLR directory", e))?;
if clr_rva == 0 && clr_size == 0 {
return Ok(());
}
if clr_rva == 0 || clr_size < 0x48 {
return Err(failure("CLR directory", senbei_pe::Error::Invalid));
}
let destination_headers = senbei_pe::parse(out).map_err(|e| failure("output PE headers", e))?;
senbei_pe::data_directory(out, destination_headers, 14)
.map_err(|e| failure("output CLR directory", e))?;
let cor = senbei_pe::rva_range(stub, source_headers, clr_rva, 0x48)
.map_err(|e| failure("COR20 header", e))?;
if read_u32(stub, cor.start) != Some(0x48) {
return Err(failure("COR20 header", senbei_pe::Error::Invalid));
}
let range_pair = |rva, size, region| {
let source = senbei_pe::rva_range(stub, source_headers, rva, size)
.map_err(|e| failure(region, e))?;
let destination = senbei_pe::rva_range(out, destination_headers, rva, size)
.map_err(|e| failure(region, e))?;
Ok::<_, unpacker::UnpackError>((source, destination))
};
let mut copies = vec![range_pair(clr_rva, 0x48, "COR20 header")?];
for (field, region) in [
(0x08, "metadata"),
(0x18, "resources"),
(0x20, "strong-name signature"),
(0x28, "code-manager table"),
(0x30, "vtable fixups"),
(0x38, "export address jumps"),
(0x40, "managed native header"),
] {
let rva = read_u32(stub, cor.start + field)
.ok_or_else(|| failure(region, senbei_pe::Error::OutOfBounds))?;
let size = read_u32(stub, cor.start + field + 4)
.ok_or_else(|| failure(region, senbei_pe::Error::OutOfBounds))?;
if field != 0x08 && rva == 0 && size == 0 {
continue;
}
if rva == 0 || size == 0 {
return Err(failure(region, senbei_pe::Error::Invalid));
}
let (source, destination) = range_pair(rva, size, region)?;
if field == 0x08 && !stub[source.clone()].starts_with(b"BSJB") {
return Err(failure(region, senbei_pe::Error::Invalid));
}
if field == 0x30 {
if !size.is_multiple_of(8) {
return Err(failure(region, senbei_pe::Error::Invalid));
}
for fixup in stub[source.clone()].as_chunks::<8>().0 {
let slots_rva =
u32::from_le_bytes(fixup[..4].try_into().expect("eight-byte fixup"));
let count = u16::from_le_bytes([fixup[4], fixup[5]]) as u32;
let flags = u16::from_le_bytes([fixup[6], fixup[7]]);
let width = match flags & 3 {
1 => 4,
2 => 8,
_ => return Err(failure(region, senbei_pe::Error::Invalid)),
};
if count != 0 {
copies.push(range_pair(slots_rva, count * width, "vtable slots")?);
}
}
}
copies.push((source, destination));
}
// Validate all referenced ranges before changing the output.
for (source, destination) in copies {
out[destination].copy_from_slice(&stub[source]);
}
let directory = destination_headers.pe_offset
+ 24
+ if destination_headers.is_pe32_plus {
112
} else {
96
}
+ 14 * 8;
out[directory..directory + 4].copy_from_slice(&clr_rva.to_le_bytes());
out[directory + 4..directory + 8].copy_from_slice(&clr_size.to_le_bytes());
Ok(())
}
/// Restore the TLS directory from the loader `stub` onto the unpacked image
/// `out`, for the external-companion layout.
///
/// Crackproof strips the whole `IMAGE_TLS_DIRECTORY` from the encrypted payload
/// — the data-directory entry, the directory struct, the raw-data template, and
/// the base relocations for the struct's four 64-bit pointer fields — and
/// re-installs TLS itself from data kept in the stub when it loads the module.
/// A statically-unpacked DLL is loaded by the ordinary Windows loader instead,
/// which needs a valid TLS directory or it never allocates a TLS slot for the
/// module nor writes `_tls_index`. The module's C++ `thread_local` accesses then
/// read a garbage TLS slot — observed as a `0xC0000005` deep in IL2CPP type
/// resolution (a TypeDef token used as a raw `s_TypeInfoTable` index).
///
/// The stub retains the full plaintext `.rdata` (only `.text`/`il2cpp` are
/// stripped to one page), so the directory struct and its raw-data template are
/// copied back byte-for-byte at their RVAs, the data-directory entry is taken
/// from the stub header (the unpacked image's was overwritten with the zeroed
/// saved-header blob), and four DIR64 relocations are appended to `.reloc`.
///
/// No-op if the stub declares no TLS directory or if any required region cannot
/// be mapped/relocated — so it can never corrupt an otherwise-good unpack.
pub(crate) fn restore_tls_from_stub(out: &mut [u8], stub: &[u8]) {
let pe = match read_u32(out, 0x3C) {
Some(v) => v as usize,
None => return,
};
if out.get(pe..pe + 4) != Some(&b"PE\0\0"[..]) {
return;
}
// This restore is PE32+-only: it copies a 40-byte IMAGE_TLS_DIRECTORY64,
// converts fields with a 64-bit image base, and appends DIR64 relocs. A
// PE32 module needs the 24-byte struct / DIR32 handling (the unpacker core
// does that itself — see `restore_pe32_tls_from_stub`), so bail rather than
// read the data directories at the wrong (PE32+) offset and write garbage.
if read_u16(out, pe + 24) != Some(0x20B) {
return;
}
// TLS is data-directory index 9 (PE32+ directories at optional header +112).
let tls_dd = match pe.checked_add(24 + 112 + 9 * 8) {
Some(v) => v,
None => return,
};
// The genuine entry survives in the stub header; the unpacked image's copy
// was clobbered by the (zeroed-TLS) saved-header blob.
let (tls_rva, tls_size) = match (read_u32(stub, tls_dd), read_u32(stub, tls_dd + 4)) {
(Some(r), Some(s)) if r != 0 && s != 0 => (r, s),
_ => return, // module has no TLS — nothing to restore
};
// Image base (PE32+, optional header +24) converts the struct's absolute VAs
// back to RVAs for the raw-data template overlay.
let image_base = match read_u64(out, pe + 24 + 24) {
Some(v) => v,
None => return,
};
// 1) Overlay the IMAGE_TLS_DIRECTORY struct from the stub at its RVA.
let dst = match rva_to_file_off(out, tls_rva) {
Some(o) => o,
None => return,
};
let src = match rva_to_file_off(stub, tls_rva) {
Some(o) => o,
None => return,
};
let n = tls_size as usize;
if dst.checked_add(n).is_none_or(|e| e > out.len())
|| src.checked_add(n).is_none_or(|e| e > stub.len())
{
return;
}
out[dst..dst + n].copy_from_slice(&stub[src..src + n]);
// 2) Restore the data-directory entry so the loader processes TLS at all.
write_u32_at(out, tls_dd, tls_rva);
write_u32_at(out, tls_dd + 4, tls_size);
// 3) Overlay the raw-data template [StartAddressOfRawData, EndAddressOfRawData).
if let (Some(start_va), Some(end_va)) = (read_u64(out, dst), read_u64(out, dst + 8))
&& end_va > start_va
&& start_va >= image_base
{
let tpl_rva = (start_va - image_base) as u32;
let tpl_len = (end_va - start_va) as usize;
if let (Some(td), Some(ts)) = (
rva_to_file_off(out, tpl_rva),
rva_to_file_off(stub, tpl_rva),
) && td.checked_add(tpl_len).is_some_and(|e| e <= out.len())
&& ts.checked_add(tpl_len).is_some_and(|e| e <= stub.len())
{
out[td..td + tpl_len].copy_from_slice(&stub[ts..ts + tpl_len]);
}
}
// 4) Append DIR64 relocations for the struct's four 64-bit pointer fields
// (Start/End/Index/CallBacks at +0/+8/+0x10/+0x18). Without them the
// loader would leave preferred-base VAs in a rebased image.
add_tls_relocs(out, pe, tls_rva);
}
/// Append a single base-relocation block covering the four 64-bit pointer fields
/// of the TLS directory struct at `tls_rva`. The block is written immediately
/// after the existing relocation table (which must be free space and in bounds)
/// and the BaseReloc directory size is grown to include it. No-op if the table
/// is absent, the fields straddle a relocation page, or the slot is not free.
fn add_tls_relocs(out: &mut [u8], pe: usize, tls_rva: u32) {
let reloc_dd = pe + 24 + 112 + 5 * 8; // BaseReloc = directory index 5
let (reloc_rva, reloc_size) = match (read_u32(out, reloc_dd), read_u32(out, reloc_dd + 4)) {
(Some(r), Some(s)) if r != 0 => (r, s),
_ => return,
};
// All four fields (last at +0x18) must share one 0x1000 relocation page.
let page = tls_rva & !0xFFF;
if (tls_rva.wrapping_add(0x18)) & !0xFFF != page {
return;
}
const BLOCK: usize = 8 + 4 * 2; // header + four DIR64 entries
let at = match rva_to_file_off(out, reloc_rva.wrapping_add(reloc_size)) {
Some(o) => o,
None => return,
};
if at.checked_add(BLOCK).is_none_or(|e| e > out.len()) {
return;
}
if out[at..at + BLOCK].iter().any(|&b| b != 0) {
return; // refuse to clobber existing data
}
write_u32_at(out, at, page);
write_u32_at(out, at + 4, BLOCK as u32);
for (i, off) in [0u32, 8, 0x10, 0x18].iter().enumerate() {
let entry = (10u16 << 12) | (((tls_rva.wrapping_add(*off)) & 0xFFF) as u16);
let p = at + 8 + i * 2;
out[p..p + 2].copy_from_slice(&entry.to_le_bytes());
}
write_u32_at(out, reloc_dd + 4, reloc_size.wrapping_add(BLOCK as u32));
}
/// Read the Export data-directory (RVA, size) from a PE image, or `None` if the
/// headers are too short/invalid to parse.
fn pe_export_dir(buf: &[u8]) -> Option<(u32, u32)> {
let headers = senbei_pe::parse(buf).ok()?;
senbei_pe::data_directory(buf, headers, 0).ok()
}
/// Map an RVA to a file offset using the PE section table. Returns `None` if no
/// section contains the RVA or the headers cannot be parsed.
fn rva_to_file_off(buf: &[u8], rva: u32) -> Option<usize> {
let headers = senbei_pe::parse(buf).ok()?;
senbei_pe::rva_to_offset(buf, headers, rva).ok()
}
fn read_u32(buf: &[u8], off: usize) -> Option<u32> {
let b = buf.get(off..off + 4)?;
Some(u32::from_le_bytes([b[0], b[1], b[2], b[3]]))
}
fn read_u16(buf: &[u8], off: usize) -> Option<u16> {
let b = buf.get(off..off + 2)?;
Some(u16::from_le_bytes([b[0], b[1]]))
}
fn read_u64(buf: &[u8], off: usize) -> Option<u64> {
let b = buf.get(off..off + 8)?;
Some(u64::from_le_bytes([
b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7],
]))
}
/// Write a little-endian `u32` at `off`, silently doing nothing if out of bounds.
fn write_u32_at(buf: &mut [u8], off: usize, val: u32) {
if let Some(slot) = buf.get_mut(off..off + 4) {
slot.copy_from_slice(&val.to_le_bytes());
}
}
/// Splice a stub and its external-companion payload into the embedded-payload
/// form the pipelines expect, or `None` if `comp` is not this stub's payload.
///
/// The companion is byte-for-byte the stub's payload region from the Crackproof
/// header (offset 4096) onward, so the result is `stub[..4096] ++ comp`. The
/// splice fires only when the first 32 bytes of `comp` equal the stub's header
/// at offset 4096 — a 32-byte match on the key-table/magic region that confirms
/// the pairing and leaves ordinary (non-companion) inputs untouched.
pub(crate) fn splice_companion(stub: &[u8], comp: &[u8]) -> Option<Vec<u8>> {
let hdr_end = HEADER_OFF + 32;
if stub.len() >= hdr_end && comp.len() >= 32 && stub[HEADER_OFF..hdr_end] == comp[..32] {
let mut spliced = Vec::with_capacity(HEADER_OFF + comp.len());
spliced.extend_from_slice(&stub[..HEADER_OFF]);
spliced.extend_from_slice(comp);
return Some(spliced);
}
None
}
/// Detect `bytes` and run the right pipeline. Spliced external companions use
/// the EXE pipeline directly because that layout is definitionally EXE-style.
///
/// Routing spliced inputs straight to the EXE pipeline is safe: the
/// companion layout is definitionally the EXE-style shell (the runtime
/// loader maps the companion and runs the standard shell unpack), so the DLL
/// pipeline probe can never be right for it. Output bytes are identical to the
/// DLL-first + EXE-fallback route for every input that route handles.
pub(crate) fn unpack_spliced_or_auto(
bytes: &[u8],
spliced: bool,
force_exe: bool,
verbose: bool,
) -> Result<(unpacker::Kind, Vec<u8>), unpacker::UnpackError> {
if spliced || force_exe {
let detected = unpacker::detect(bytes).ok_or(unpacker::UnpackError::NotCrackproof)?;
let out = unpacker::unpack_exe_v(bytes, verbose)?;
return Ok((detected.kind, out));
}
unpacker::unpack_auto_v(bytes, verbose)
}
/// Unpack a single file to `dest`. Returns the Kind and integrity report on success.
pub fn unpack_one(
input: &Path,
dest: &Path,
) -> anyhow::Result<(unpacker::Kind, unpacker::IntegrityReport)> {
unpack_one_v(input, dest, false)
}
/// Outcome of a byte-level unpack ([`unpack_bytes`]): the image, its detected
/// kind, and its integrity report. No file I/O is involved.
pub struct UnpackedImage {
pub kind: unpacker::Kind,
pub bytes: Vec<u8>,
pub integrity: unpacker::IntegrityReport,
/// True when the input was reconstructed from an external companion (the
/// `._` layout), i.e. the export/TLS overlays ran.
pub companion: bool,
}
/// Unpack in-memory `input` bytes, optionally paired with an external
/// companion payload `companion` (the `<input>._` file's contents).
///
/// This is the in-memory counterpart of [`unpack_one_v`]: splice a matching
/// companion, unpack, overlay the export table and TLS directory from the stub,
/// then run the static integrity check.
pub fn unpack_bytes(
input: &[u8],
companion: Option<&[u8]>,
) -> Result<UnpackedImage, unpacker::UnpackError> {
unpack_bytes_impl(input, companion, false)
}
/// Like [`unpack_bytes`], but forces the EXE pipeline (no DLL-pipeline
/// probe). This is the web app's recovery path: the DLL-first probe relies
/// on `catch_unwind` to reject EXE-shell-layout DLLs, and panics cannot be
/// caught on wasm — the probe traps the whole call. The web app runs each
/// unpack in a disposable Web Worker and retries trapped DLLs with this
/// entry point, reproducing the CLI's dll-first/exe-fallback routing.
pub fn unpack_bytes_force_exe(
input: &[u8],
companion: Option<&[u8]>,
) -> Result<UnpackedImage, unpacker::UnpackError> {
unpack_bytes_impl(input, companion, true)
}
fn unpack_bytes_impl(
input: &[u8],
companion: Option<&[u8]>,
force_exe: bool,
) -> Result<UnpackedImage, unpacker::UnpackError> {
let spliced = companion.and_then(|c| splice_companion(input, c));
let bytes: &[u8] = spliced.as_deref().unwrap_or(input);
let (kind, mut out) = unpack_spliced_or_auto(bytes, spliced.is_some(), force_exe, false)?;
if spliced.is_some() {
overlay_exports_from_stub(&mut out, input);
restore_tls_from_stub(&mut out, input);
restore_managed_from_stub(&mut out, input)?;
}
let integrity = unpacker::check_integrity(&out);
Ok(UnpackedImage {
kind,
bytes: out,
integrity,
companion: spliced.is_some(),
})
}
/// Like [`unpack_one`], but prints detailed `[N/9]` step progress (and a final
/// `Write to <dest>` line) to stdout when `verbose` is true.
pub fn unpack_one_v(
input: &Path,
dest: &Path,
verbose: bool,
) -> anyhow::Result<(unpacker::Kind, unpacker::IntegrityReport)> {
let UnpackerInput { bytes, stub } = read_unpacker_input(input)?;
let (kind, mut out) = unpack_spliced_or_auto(&bytes, stub.is_some(), false, verbose)?;
// External-companion layout: restore the export table from the stub, which
// the encrypted companion does not carry (the loader rebuilds it at runtime).
if let Some(stub) = stub {
overlay_exports_from_stub(&mut out, &stub);
// ...and the TLS directory, which Crackproof strips from the payload and
// re-installs at runtime; the ordinary loader needs it or thread_local
// access crashes (see [`restore_tls_from_stub`]).
restore_tls_from_stub(&mut out, &stub);
restore_managed_from_stub(&mut out, &stub)?;
}
let report = unpacker::check_integrity(&out);
if let Some(parent) = dest.parent() {
std::fs::create_dir_all(parent)?;
}
write_atomic(dest, &out)?;
if verbose {
println!("Write to {}", dest.display());
}
Ok((kind, report))
}
#[cfg(test)]
mod tests {
use super::*;
const HEADER_OFF: usize = 4096;
fn stub_with_header(header: &[u8; 32], extra: usize) -> Vec<u8> {
let mut stub = vec![0_u8; HEADER_OFF];
stub.extend_from_slice(header);
stub.extend_from_slice(&vec![0xAA_u8; extra]);
stub
}
#[test]
fn splices_when_header_matches() {
let header = [7_u8; 32];
let stub = stub_with_header(&header, 16);
let mut companion = header.to_vec();
companion.extend_from_slice(&[0x42_u8; 1000]);
let output = splice_companion(&stub, &companion).expect("should splice");
assert_eq!(output.len(), HEADER_OFF + companion.len());
assert_eq!(&output[..HEADER_OFF], &stub[..HEADER_OFF]);
assert_eq!(&output[HEADER_OFF..], &companion[..]);
}
#[test]
fn no_splice_when_header_differs() {
let stub = stub_with_header(&[7_u8; 32], 16);
let mut companion = vec![9_u8; 32];
companion.extend_from_slice(&[0x42_u8; 1000]);
assert!(splice_companion(&stub, &companion).is_none());
}
#[test]
fn no_splice_when_too_short() {
let short_stub = vec![0_u8; HEADER_OFF + 8];
let companion = vec![0_u8; 64];
assert!(splice_companion(&short_stub, &companion).is_none());
let stub = stub_with_header(&[1_u8; 32], 0);
let short_companion = vec![1_u8; 16];
assert!(splice_companion(&stub, &short_companion).is_none());
}
fn managed_fixture(is_pe32_plus: bool, raw: usize) -> Vec<u8> {
let mut data = vec![0; raw + 0x600];
data[..2].copy_from_slice(b"MZ");
data[0x80..0x84].copy_from_slice(b"PE\0\0");
let optional_size = if is_pe32_plus { 0xf0u16 } else { 0xe0 };
let section = 0x98 + optional_size as usize;
let dirs = 0x98 + if is_pe32_plus { 112 } else { 96 };
for (offset, value) in [
(0x86, 1u16),
(0x94, optional_size),
(0x98, if is_pe32_plus { 0x20b } else { 0x10b }),
(raw + 0x204, 2),
(raw + 0x206, if is_pe32_plus { 2 } else { 1 }),
] {
data[offset..offset + 2].copy_from_slice(&value.to_le_bytes());
}
for (offset, value) in [
(0x3c, 0x80u32),
(0xd0, 0x3000),
(0xd4, 0x400),
(dirs + 14 * 8, 0x2010),
(dirs + 14 * 8 + 4, 0x48),
(section + 8, 0x600),
(section + 12, 0x2000),
(section + 16, 0x600),
(section + 20, raw as u32),
(raw + 0x10, 0x48),
(raw + 0x18, 0x2100),
(raw + 0x1c, 0x20),
(raw + 0x28, 0x2180),
(raw + 0x2c, 8),
(raw + 0x40, 0x2200),
(raw + 0x44, 8),
(raw + 0x200, 0x2280),
(raw + 0x280, 0x0600_0001),
] {
data[offset..offset + 4].copy_from_slice(&value.to_le_bytes());
}
data[raw + 0x100..raw + 0x104].copy_from_slice(b"BSJB");
data[raw + 0x180..raw + 0x188].copy_from_slice(b"resource");
data
}
#[test]
fn managed_companion_restores_rva_mapped_regions_without_overwriting_il() {
for is_pe32_plus in [false, true] {
let stub = managed_fixture(is_pe32_plus, 0x600);
let mut out = managed_fixture(is_pe32_plus, 0x400);
out[0x400..].fill(0xcc);
restore_managed_from_stub(&mut out, &stub).unwrap();
for (offset, size) in [
(0x10, 0x48),
(0x100, 0x20),
(0x180, 8),
(0x200, 8),
(0x280, if is_pe32_plus { 16 } else { 8 }),
] {
assert_eq!(
&out[0x400 + offset..0x400 + offset + size],
&stub[0x600 + offset..0x600 + offset + size]
);
}
assert!(out[0x700..0x740].iter().all(|&b| b == 0xcc));
}
}
#[test]
fn managed_companion_rejects_invalid_metadata_and_unbacked_vtable_slots() {
for broken_metadata in [true, false] {
let mut stub = managed_fixture(false, 0x600);
if broken_metadata {
stub[0x700..0x704].fill(0);
} else {
stub[0x800..0x804].copy_from_slice(&0x2600u32.to_le_bytes());
}
let mut out = managed_fixture(false, 0x400);
let before = out.clone();
assert!(matches!(
restore_managed_from_stub(&mut out, &stub),
Err(unpacker::UnpackError::ManagedStubRestoreFailed { .. })
));
assert_eq!(out, before);
}
}
}
senbei-metadata/Cargo.toml
+4
View File
@@ -4,3 +4,7 @@ version.workspace = true
edition.workspace = true
license.workspace = true
description = "Unity il2cpp metadata de-obfuscation for Senbei"
[dependencies]
serde.workspace = true
thiserror.workspace = true
senbei-android-metadata/src/embedded.rs → senbei-metadata/src/android/embedded.rs
+1 -1
View File
@@ -20,7 +20,7 @@
//! they are rewritten to the standard il2cpp metadata magic and version so the
//! output is a well-formed `global-metadata.dat`.
use crate::keystream::{HEADER_KEYS, SEGMENTS};
use super::keystream::{HEADER_KEYS, SEGMENTS};
/// Standard il2cpp metadata sanity magic written over the patched header.
const STANDARD_MAGIC: u32 = 0xfab1_1baf;
senbei-android-metadata/src/keystream.rs → senbei-metadata/src/android/keystream.rs
View File
senbei-android-metadata/src/method_tokens.rs → senbei-metadata/src/android/method_tokens.rs
+611 -19
View File
@@ -1,17 +1,17 @@
//! Static restoration of protected IL2CPP v31 method tokens.
//! Static restoration of protected IL2CPP method tokens for verified layouts.
use serde::Serialize;
use crate::common::MAGIC;
/// Seed embedded in the current `libil2cpp` module `0x0C`.
pub const DEFAULT_METHOD_TOKEN_SEED: u32 = 0xa6fa_e968;
const MAGIC: u32 = 0xfab1_1baf;
const SUPPORTED_VERSION: u32 = 31;
const SUPPORTED_V29: u32 = 29;
const SUPPORTED_V31: u32 = 31;
const HDR_METHODS: usize = 0x30;
const HDR_TYPES: usize = 0xa0;
const HDR_IMAGES: usize = 0xa8;
const METHOD_STRIDE: usize = 0x24;
const METHOD_TOKEN_OFFSET: usize = 0x18;
const TYPE_STRIDE: usize = 0x58;
const TYPE_METHOD_START_OFFSET: usize = 0x24;
const TYPE_METHOD_COUNT_OFFSET: usize = 0x40;
@@ -20,6 +20,33 @@ const IMAGE_TYPE_START_OFFSET: usize = 0x08;
const IMAGE_TYPE_COUNT_OFFSET: usize = 0x0c;
const METHOD_TOKEN_TABLE: u32 = 0x0600_0000;
// The aliases keep the v31 synthetic fixtures readable; production paths use
// the version-specific layout returned by `layout_for_version`.
#[cfg(test)]
const METHOD_STRIDE: usize = 0x24;
#[cfg(test)]
const METHOD_TOKEN_OFFSET: usize = 0x18;
#[derive(Clone, Copy)]
struct Layout {
method_stride: usize,
method_token_offset: usize,
}
fn layout_for_version(version: u32) -> Option<Layout> {
match version {
SUPPORTED_V29 => Some(Layout {
method_stride: 0x20,
method_token_offset: 0x14,
}),
SUPPORTED_V31 => Some(Layout {
method_stride: 0x24,
method_token_offset: 0x18,
}),
_ => None,
}
}
/// Summary of one metadata restoration pass.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct Report {
@@ -171,20 +198,23 @@ pub fn restore_method_tokens(data: &[u8], seed: u32) -> Result<(Vec<u8>, Report)
return Err(Error::NotMetadata);
}
let version = read_u32(data, 4)?;
if version != SUPPORTED_VERSION {
return Err(Error::UnsupportedVersion(version));
if version == 39 {
return restore_v39(data, seed);
}
let Some(layout) = layout_for_version(version) else {
return Err(Error::UnsupportedVersion(version));
};
let (method_offset, method_size) = table(data, HDR_METHODS)?;
let (type_offset, type_size) = table(data, HDR_TYPES)?;
let (image_offset, image_size) = table(data, HDR_IMAGES)?;
if method_size % METHOD_STRIDE != 0
if method_size % layout.method_stride != 0
|| type_size % TYPE_STRIDE != 0
|| image_size % IMAGE_STRIDE != 0
{
return malformed("v31 table size is not divisible by its entry stride");
return malformed("method/type/image table size is not divisible by its entry stride");
}
let method_count = method_size / METHOD_STRIDE;
let method_count = method_size / layout.method_stride;
let type_count = type_size / TYPE_STRIDE;
let image_count = image_size / IMAGE_STRIDE;
let mut owners = vec![u32::MAX; method_count];
@@ -264,7 +294,8 @@ pub fn restore_method_tokens(data: &[u8], seed: u32) -> Result<(Vec<u8>, Report)
let mut tokens = Vec::with_capacity(methods.len());
let mut image_already_clean = true;
for &method_index in &methods {
let token_offset = method_offset + method_index * METHOD_STRIDE + METHOD_TOKEN_OFFSET;
let token_offset =
method_offset + method_index * layout.method_stride + layout.method_token_offset;
let token = read_u32(data, token_offset)?;
if token & 0xff00_0000 != METHOD_TOKEN_TABLE {
return malformed(format!(
@@ -357,7 +388,7 @@ pub fn restore_method_tokens(data: &[u8], seed: u32) -> Result<(Vec<u8>, Report)
))
}
/// Discover seeds compatible with the known v31 five-round RID permutation.
/// Discover seeds compatible with the known five-round RID permutation.
///
/// This is diagnostic and does not modify metadata. It enumerates the only
/// possible per-image key residues and intersects them over the 32-bit seed
@@ -368,23 +399,26 @@ pub fn discover_method_token_seeds(data: &[u8]) -> Result<SeedDiscoveryReport> {
return Err(Error::NotMetadata);
}
let version = read_u32(data, 4)?;
if version != SUPPORTED_VERSION {
if version == 39 {
return discover_v39(data);
}
let Some(layout) = layout_for_version(version) else {
return Ok(SeedDiscoveryReport {
version,
images: Vec::new(),
seed_candidates: Vec::new(),
});
}
};
let (method_offset, method_size) = table(data, HDR_METHODS)?;
let (type_offset, type_size) = table(data, HDR_TYPES)?;
let (image_offset, image_size) = table(data, HDR_IMAGES)?;
if method_size % METHOD_STRIDE != 0
if method_size % layout.method_stride != 0
|| type_size % TYPE_STRIDE != 0
|| image_size % IMAGE_STRIDE != 0
{
return malformed("v31 table size is not divisible by its entry stride");
return malformed("method/type/image table size is not divisible by its entry stride");
}
let method_count = method_size / METHOD_STRIDE;
let method_count = method_size / layout.method_stride;
let type_count = type_size / TYPE_STRIDE;
let image_count = image_size / IMAGE_STRIDE;
let mut reports = Vec::with_capacity(image_count);
@@ -446,7 +480,7 @@ pub fn discover_method_token_seeds(data: &[u8]) -> Result<SeedDiscoveryReport> {
for method_index in methods {
let token = read_u32(
data,
method_offset + method_index * METHOD_STRIDE + METHOD_TOKEN_OFFSET,
method_offset + method_index * layout.method_stride + layout.method_token_offset,
)?;
if token & 0xff00_0000 != METHOD_TOKEN_TABLE {
return validation(format!(
@@ -550,6 +584,458 @@ fn decrypt_rid_with_key(rid: u32, low: u32, high: u32, key: u32) -> u32 {
value + low
}
const V39_METHODS: usize = 5;
const V39_PARAMETERS: usize = 10;
const V39_GENERIC_CONTAINERS: usize = 14;
const V39_INTERFACE_OFFSETS: usize = 18;
const V39_TYPES: usize = 19;
const V39_IMAGES: usize = 20;
#[derive(Debug, Clone, Copy)]
struct V39Layout {
method_offset: usize,
method_count: usize,
method_stride: usize,
method_token_offset: usize,
type_definition_index_width: usize,
type_offset: usize,
type_count: usize,
type_stride: usize,
type_method_start_offset: usize,
type_method_count_offset: usize,
image_offset: usize,
image_count: usize,
image_stride: usize,
}
fn v39_section(data: &[u8], index: usize) -> Result<(usize, usize, usize)> {
let header = 8_usize
.checked_add(
index
.checked_mul(12)
.ok_or_else(|| Error::Malformed("v39 section header offset overflow".to_owned()))?,
)
.ok_or_else(|| Error::Malformed("v39 section header offset overflow".to_owned()))?;
let offset = read_u32(data, header)? as usize;
let size = read_u32(data, header + 4)? as usize;
let count = read_u32(data, header + 8)? as usize;
bytes(data, offset, size)?;
Ok((offset, size, count))
}
fn v39_index_width(count: usize) -> usize {
if count <= u8::MAX as usize {
1
} else if count <= u16::MAX as usize {
2
} else {
4
}
}
fn read_v39_index(data: &[u8], offset: usize, width: usize) -> Result<usize> {
match width {
1 => Ok(bytes(data, offset, 1)?[0] as usize),
2 => Ok(read_u16(data, offset)? as usize),
4 => Ok(read_u32(data, offset)? as usize),
_ => malformed("v39 index has an unsupported width"),
}
}
fn parse_v39(data: &[u8]) -> Result<V39Layout> {
let (method_offset, method_size, method_count) = v39_section(data, V39_METHODS)?;
let (_, parameter_size, parameter_count) = v39_section(data, V39_PARAMETERS)?;
let (_, _, generic_count) = v39_section(data, V39_GENERIC_CONTAINERS)?;
let (_interface_offset, interface_size, interface_count) =
v39_section(data, V39_INTERFACE_OFFSETS)?;
let (type_offset, type_size, type_count) = v39_section(data, V39_TYPES)?;
let (image_offset, image_size, image_count) = v39_section(data, V39_IMAGES)?;
let parameter_index_width = v39_index_width(parameter_count);
let generic_container_index_width = v39_index_width(generic_count);
let type_definition_index_width = v39_index_width(type_count);
let type_index_width = if interface_count == 0 {
4
} else {
let element_size = interface_size
.checked_div(interface_count)
.ok_or_else(|| Error::Malformed("v39 interface-offset size is invalid".to_owned()))?;
element_size
.checked_sub(4)
.filter(|width| matches!(width, 1 | 2 | 4))
.ok_or_else(|| Error::Malformed("v39 type-index width is invalid".to_owned()))?
};
let method_stride = 20_usize
.checked_add(type_definition_index_width)
.and_then(|size| size.checked_add(type_index_width))
.and_then(|size| size.checked_add(parameter_index_width))
.and_then(|size| size.checked_add(generic_container_index_width))
.ok_or_else(|| Error::Malformed("v39 method stride overflow".to_owned()))?;
let type_stride = 68_usize
.checked_add(
type_index_width
.checked_mul(3)
.ok_or_else(|| Error::Malformed("v39 type stride overflow".to_owned()))?,
)
.and_then(|size| size.checked_add(generic_container_index_width))
.ok_or_else(|| Error::Malformed("v39 type stride overflow".to_owned()))?;
let image_stride = 32_usize
.checked_add(
type_definition_index_width
.checked_mul(2)
.ok_or_else(|| Error::Malformed("v39 image stride overflow".to_owned()))?,
)
.ok_or_else(|| Error::Malformed("v39 image stride overflow".to_owned()))?;
if method_count.checked_mul(method_stride) != Some(method_size)
|| type_count.checked_mul(type_stride) != Some(type_size)
|| image_count.checked_mul(image_stride) != Some(image_size)
|| parameter_count == 0 && parameter_size != 0
{
return malformed("v39 table size does not match its compact entry layout");
}
let type_method_start_offset = 16_usize
.checked_add(
type_index_width
.checked_mul(3)
.ok_or_else(|| Error::Malformed("v39 type method offset overflow".to_owned()))?,
)
.and_then(|offset| offset.checked_add(generic_container_index_width))
.ok_or_else(|| Error::Malformed("v39 type method offset overflow".to_owned()))?;
let type_method_count_offset = type_method_start_offset
.checked_add(7 * 4)
.ok_or_else(|| Error::Malformed("v39 type method count offset overflow".to_owned()))?;
let method_token_offset = 4_usize
.checked_add(type_definition_index_width)
.and_then(|offset| offset.checked_add(type_index_width))
.and_then(|offset| offset.checked_add(4))
.and_then(|offset| offset.checked_add(parameter_index_width))
.and_then(|offset| offset.checked_add(generic_container_index_width))
.ok_or_else(|| Error::Malformed("v39 method token offset overflow".to_owned()))?;
if method_token_offset
.checked_add(4)
.is_none_or(|end| end > method_stride)
|| type_method_count_offset
.checked_add(2)
.is_none_or(|end| end > type_stride)
{
return malformed("v39 compact layout fields exceed their records");
}
// Touch the section base so malformed headers fail before any output copy.
Ok(V39Layout {
method_offset,
method_count,
method_stride,
method_token_offset,
type_definition_index_width,
type_offset,
type_count,
type_stride,
type_method_start_offset,
type_method_count_offset,
image_offset,
image_count,
image_stride,
})
}
fn v39_image_methods(data: &[u8], layout: V39Layout, image: usize) -> Result<Vec<usize>> {
let image_base = layout
.image_offset
.checked_add(
image
.checked_mul(layout.image_stride)
.ok_or_else(|| Error::Malformed("v39 image offset overflow".to_owned()))?,
)
.ok_or_else(|| Error::Malformed("v39 image offset overflow".to_owned()))?;
let type_start = read_v39_index(data, image_base + 8, layout.type_definition_index_width)?;
let type_count = read_u32(data, image_base + 8 + layout.type_definition_index_width)? as usize;
let type_end = type_start
.checked_add(type_count)
.ok_or_else(|| Error::Malformed("v39 image type range overflow".to_owned()))?;
if type_end > layout.type_count {
return malformed("v39 image type range exceeds the type table");
}
let mut methods = Vec::new();
for type_index in type_start..type_end {
let type_base = layout
.type_offset
.checked_add(
type_index
.checked_mul(layout.type_stride)
.ok_or_else(|| Error::Malformed("v39 type offset overflow".to_owned()))?,
)
.ok_or_else(|| Error::Malformed("v39 type offset overflow".to_owned()))?;
let method_start = read_u32(data, type_base + layout.type_method_start_offset)?;
let method_count = read_u16(data, type_base + layout.type_method_count_offset)? as usize;
if method_start == u32::MAX || method_count == 0 {
continue;
}
let method_start = method_start as usize;
let method_end = method_start
.checked_add(method_count)
.ok_or_else(|| Error::Malformed("v39 type method range overflow".to_owned()))?;
if method_end > layout.method_count {
return malformed("v39 type method range exceeds the method table");
}
methods.extend(method_start..method_end);
}
Ok(methods)
}
#[allow(clippy::too_many_arguments)]
fn v39_report(
layout: V39Layout,
changed_tokens: usize,
images_with_methods: usize,
visited_methods: usize,
already_correct_before: usize,
correct_after: usize,
transformed_images: usize,
seed: u32,
) -> Report {
Report {
version: 39,
seed: format!("0x{seed:08X}"),
encryption_status: if changed_tokens == 0 {
"clean".to_owned()
} else {
"encrypted".to_owned()
},
images: layout.image_count,
images_with_methods,
types: layout.type_count,
methods: layout.method_count,
visited_methods,
already_correct_before,
correct_after,
changed_tokens,
transformed_images,
}
}
fn restore_v39(data: &[u8], seed: u32) -> Result<(Vec<u8>, Report)> {
let layout = parse_v39(data)?;
let mut owners = vec![u32::MAX; layout.method_count];
let mut output = data.to_vec();
let mut images_with_methods = 0;
let mut visited_methods = 0;
let mut already_correct_before = 0;
let mut correct_after = 0;
let mut changed_tokens = 0;
let mut transformed_images = 0;
for image in 0..layout.image_count {
let methods = v39_image_methods(data, layout, image)?;
if methods.is_empty() {
continue;
}
images_with_methods += 1;
visited_methods += methods.len();
let method_base = *methods.iter().min().ok_or_else(|| {
Error::Malformed("v39 nonempty image lost its method minimum".to_owned())
})?;
let method_last = *methods.iter().max().ok_or_else(|| {
Error::Malformed("v39 nonempty image lost its method maximum".to_owned())
})?;
if method_last - method_base + 1 != methods.len() {
return validation(format!("v39 image {image} method block is not contiguous"));
}
for &method in &methods {
if owners[method] != u32::MAX {
return malformed(format!("v39 method {method} belongs to multiple images"));
}
owners[method] = image as u32;
}
let mut tokens = Vec::with_capacity(methods.len());
let mut clean = true;
for method in methods {
let offset =
layout.method_offset + method * layout.method_stride + layout.method_token_offset;
let token = read_u32(data, offset)?;
if token & 0xff00_0000 != METHOD_TOKEN_TABLE {
return malformed(format!("v39 method {method} has a non-MethodDef token"));
}
let expected = (method - method_base + 1) as u32;
let rid = token & 0x00ff_ffff;
if rid == expected {
already_correct_before += 1;
} else {
clean = false;
}
tokens.push((offset, token, expected));
}
if clean {
correct_after += tokens.len();
continue;
}
transformed_images += 1;
let low = tokens
.iter()
.map(|(_, token, _)| token & 0x00ff_ffff)
.min()
.unwrap();
let high = tokens
.iter()
.map(|(_, token, _)| token & 0x00ff_ffff)
.max()
.unwrap();
if high - low + 1 != tokens.len() as u32 {
return validation(format!(
"v39 image {image} RID interval is not a permutation"
));
}
for (offset, token, expected) in tokens {
let restored = decrypt_rid(token & 0x00ff_ffff, low, high, seed)?;
if restored != expected {
return validation(format!(
"v39 restored RID {restored} != expected {expected}"
));
}
let restored_token = METHOD_TOKEN_TABLE | restored;
if restored_token != token {
output[offset..offset + 4].copy_from_slice(&restored_token.to_le_bytes());
changed_tokens += 1;
}
correct_after += 1;
}
}
if owners.contains(&u32::MAX) {
return malformed("v39 method definitions are not all owned by an image");
}
if visited_methods != layout.method_count || correct_after != layout.method_count {
return validation(format!(
"v39 method coverage mismatch: visited={visited_methods}, correct={correct_after}, total={}",
layout.method_count
));
}
Ok((
output,
v39_report(
layout,
changed_tokens,
images_with_methods,
visited_methods,
already_correct_before,
correct_after,
transformed_images,
seed,
),
))
}
fn discover_v39(data: &[u8]) -> Result<SeedDiscoveryReport> {
let layout = parse_v39(data)?;
let mut reports = Vec::with_capacity(layout.image_count);
for image in 0..layout.image_count {
let methods = v39_image_methods(data, layout, image)?;
if methods.is_empty() {
reports.push(ImageKeyDiscovery {
image,
method_count: 0,
modulus: 0,
clean: true,
seed_residues: Vec::new(),
});
continue;
}
let base = *methods.iter().min().unwrap();
let last = *methods.iter().max().unwrap();
if last - base + 1 != methods.len() {
return validation(format!("v39 image {image} method block is not contiguous"));
}
let values = methods
.iter()
.map(|&method| {
let offset = layout.method_offset
+ method * layout.method_stride
+ layout.method_token_offset;
let token = read_u32(data, offset)?;
if token & 0xff00_0000 != METHOD_TOKEN_TABLE {
return malformed(format!("v39 method {method} has a non-MethodDef token"));
}
Ok((token & 0x00ff_ffff, (method - base + 1) as u32))
})
.collect::<Result<Vec<_>>>()?;
let count = u32::try_from(values.len())
.map_err(|_| Error::Validation("v39 image method count exceeds u32".to_owned()))?;
let clean = values.iter().all(|(rid, expected)| rid == expected);
if clean {
reports.push(ImageKeyDiscovery {
image,
method_count: count,
modulus: count / 2,
clean: true,
seed_residues: Vec::new(),
});
continue;
}
let low = values.iter().map(|(rid, _)| *rid).min().unwrap();
let high = values.iter().map(|(rid, _)| *rid).max().unwrap();
if high - low + 1 != count || count < 2 {
return validation(format!(
"v39 image {image} RID interval is not a permutation"
));
}
let half = count / 2;
let quarter = count / 4;
let mut residues = Vec::new();
for residue in 0..half {
let key = quarter + residue;
if values
.iter()
.all(|(rid, expected)| decrypt_rid_with_key(*rid, low, high, key) == *expected)
{
residues.push(residue);
}
}
reports.push(ImageKeyDiscovery {
image,
method_count: count,
modulus: half,
clean: false,
seed_residues: residues,
});
}
let constraints = reports
.iter()
.filter(|image| !image.clean)
.collect::<Vec<_>>();
let mut candidates = Vec::new();
if let Some(anchor) = constraints.iter().max_by_key(|image| image.modulus) {
// Returning every 32-bit seed is not representable for tiny synthetic
// images (for example, a two-entry image has billions of candidates).
// The caller still tries the known default seed and validates it fully.
if anchor.modulus < 1024 {
return Ok(SeedDiscoveryReport {
version: 39,
images: reports,
seed_candidates: candidates,
});
}
for &residue in &anchor.seed_residues {
let modulus = u64::from(anchor.modulus);
let mut candidate = u64::from(residue);
while candidate <= u64::from(u32::MAX) {
if constraints.iter().all(|image| {
image.modulus != 0
&& image
.seed_residues
.iter()
.any(|value| candidate % u64::from(image.modulus) == u64::from(*value))
}) {
candidates.push(candidate as u32);
}
candidate = candidate.saturating_add(modulus);
}
}
}
candidates.sort_unstable();
candidates.dedup();
Ok(SeedDiscoveryReport {
version: 39,
images: reports,
seed_candidates: candidates,
})
}
#[cfg(test)]
mod tests {
use super::*;
@@ -575,7 +1061,7 @@ mod tests {
let methods = types + 2 * TYPE_STRIDE;
let mut data = vec![0_u8; methods + tokens.len() * METHOD_STRIDE];
put_u32(&mut data, 0, MAGIC);
put_u32(&mut data, 4, SUPPORTED_VERSION);
put_u32(&mut data, 4, SUPPORTED_V31);
put_u32(&mut data, HDR_METHODS, methods as u32);
put_u32(
&mut data,
@@ -628,6 +1114,50 @@ mod tests {
}
}
#[test]
fn restores_v29_method_tokens_with_legacy_method_layout() {
let method_stride = 0x20;
let method_token_offset = 0x14;
let hdr = 0x100usize;
let images = hdr;
let types = images + IMAGE_STRIDE;
let methods = types + 2 * TYPE_STRIDE;
let mut data = vec![0_u8; methods + 7 * method_stride];
put_u32(&mut data, 0, MAGIC);
put_u32(&mut data, 4, SUPPORTED_V29);
put_u32(&mut data, HDR_METHODS, methods as u32);
put_u32(&mut data, HDR_METHODS + 4, (7 * method_stride) as u32);
put_u32(&mut data, HDR_TYPES, types as u32);
put_u32(&mut data, HDR_TYPES + 4, (2 * TYPE_STRIDE) as u32);
put_u32(&mut data, HDR_IMAGES, images as u32);
put_u32(&mut data, HDR_IMAGES + 4, IMAGE_STRIDE as u32);
put_u32(&mut data, images + IMAGE_TYPE_START_OFFSET, 0);
put_u32(&mut data, images + IMAGE_TYPE_COUNT_OFFSET, 2);
put_u32(&mut data, types + TYPE_METHOD_START_OFFSET, 0);
put_u16(&mut data, types + TYPE_METHOD_COUNT_OFFSET, 3);
put_u32(&mut data, types + TYPE_STRIDE + TYPE_METHOD_START_OFFSET, 3);
put_u16(&mut data, types + TYPE_STRIDE + TYPE_METHOD_COUNT_OFFSET, 4);
for expected in 1..=7 {
let encrypted = encrypted_rid(expected, 7, DEFAULT_METHOD_TOKEN_SEED);
put_u32(
&mut data,
methods + (expected as usize - 1) * method_stride + method_token_offset,
METHOD_TOKEN_TABLE | encrypted,
);
}
let (restored, report) =
restore_method_tokens(&data, DEFAULT_METHOD_TOKEN_SEED).expect("v29 restore");
assert_eq!(report.version, SUPPORTED_V29);
assert_eq!(report.changed_tokens, 7);
for expected in 1..=7 {
let offset = methods + (expected as usize - 1) * method_stride + method_token_offset;
assert_eq!(
read_u32(&restored, offset).unwrap(),
METHOD_TOKEN_TABLE | expected
);
}
}
#[test]
fn clean_metadata_is_idempotent() {
let tokens = (1..=7)
@@ -656,4 +1186,66 @@ mod tests {
Err(Error::Validation(_))
));
}
#[test]
fn restores_compact_v39_method_tokens_without_touching_other_fields() {
let method_stride = 25;
let type_stride = 75;
let image_stride = 34;
let method_offset = 0x400;
let type_offset = 0x600;
let image_offset = 0x700;
let method_count = 7_u32;
let mut data = vec![0_u8; image_offset + image_stride];
put_u32(&mut data, 0, MAGIC);
put_u32(&mut data, 4, 39);
let section = |data: &mut [u8], index: usize, offset: usize, size: usize, count: usize| {
let header = 8 + index * 12;
put_u32(data, header, offset as u32);
put_u32(data, header + 4, size as u32);
put_u32(data, header + 8, count as u32);
};
section(
&mut data,
V39_METHODS,
method_offset,
method_stride * method_count as usize,
method_count as usize,
);
section(&mut data, V39_PARAMETERS, 0x300, 1, 1);
section(&mut data, V39_GENERIC_CONTAINERS, 0x320, 1, 1);
section(&mut data, V39_INTERFACE_OFFSETS, 0x340, 6, 1);
section(&mut data, V39_TYPES, type_offset, type_stride, 1);
section(&mut data, V39_IMAGES, image_offset, image_stride, 1);
data.resize(image_offset + image_stride, 0);
// Compact v39 type definition: firstMethod at offset 23, methodCount at 51.
put_u32(&mut data, type_offset + 23, 0);
put_u16(&mut data, type_offset + 51, method_count as u16);
// Compact v39 image definition: firstTypeIndex (one byte) and typeCount.
data[image_offset + 8] = 0;
put_u32(&mut data, image_offset + 9, 1);
for expected in 1..=method_count {
let token = METHOD_TOKEN_TABLE
| encrypted_rid(expected, method_count, DEFAULT_METHOD_TOKEN_SEED);
put_u32(
&mut data,
method_offset + (expected as usize - 1) * method_stride + 13,
token,
);
}
let (out, report) =
restore_method_tokens(&data, DEFAULT_METHOD_TOKEN_SEED).expect("v39 restore");
assert_eq!(report.version, 39);
assert_eq!(report.changed_tokens, method_count as usize);
for expected in 1..=method_count {
let offset = method_offset + (expected as usize - 1) * method_stride + 13;
assert_eq!(
read_u32(&out, offset).unwrap(),
METHOD_TOKEN_TABLE | expected
);
}
let discovery = discover_method_token_seeds(&data).expect("v39 discovery");
assert_eq!(discovery.version, 39);
assert!(discovery.seed_candidates.is_empty());
}
}
senbei-android-metadata/src/lib.rs → senbei-metadata/src/android/mod.rs
View File
senbei-metadata/src/common.rs
+12
View File
@@ -0,0 +1,12 @@
//! Shared IL2CPP metadata header primitives.
/// IL2CPP global-metadata sanity magic.
pub(crate) const MAGIC: u32 = 0xFAB1_1BAF;
/// Cheap check used by both platform scanners before opening a full metadata
/// file.
#[must_use]
pub fn is_metadata(data: &[u8]) -> bool {
data.get(0..4)
.is_some_and(|bytes| u32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]) == MAGIC)
}
senbei-metadata/src/lib.rs
+7 -3
View File
@@ -1,5 +1,9 @@
//! Unity il2cpp metadata de-obfuscation.
//! Unity il2cpp metadata restoration.
mod metadata;
pub mod android;
mod common;
mod structural;
pub mod windows;
pub use metadata::*;
pub use common::is_metadata;
pub use structural::*;
senbei-metadata/src/metadata.rs → senbei-metadata/src/structural.rs
+1 -2
View File
@@ -27,8 +27,7 @@
//! metadata (its tokens already equal `local_index + 1`), so it is safe to run on
//! any il2cpp game — `remapped == 0` then reports that nothing changed.
/// il2cpp `global-metadata.dat` sanity magic (`Il2CppGlobalMetadataHeader.sanity`).
const MAGIC: u32 = 0xFAB1_1BAF;
use crate::common::MAGIC;
/// Metadata format version this de-obfuscator understands. The struct strides
/// and header field offsets below are specific to it; other versions are left
senbei-metadata/src/windows/mod.rs
+3
View File
@@ -0,0 +1,3 @@
//! Compatibility namespace for the shared structural metadata transform.
pub use crate::structural::*;
senbei-pe/Cargo.toml
+1 -2
View File
@@ -3,8 +3,7 @@ name = "senbei-pe"
version.workspace = true
edition.workspace = true
license.workspace = true
description = "PE detection, unpacking, and validation for Senbei"
description = "PE format parsing and address mapping for Senbei"
[dependencies]
senbei-crypto.workspace = true
thiserror.workspace = true
senbei-pe/src/lib.rs
+231 -3
View File
@@ -1,5 +1,233 @@
//! PE detection, unpacking, and structural validation.
//! Basic PE format parsing and address mapping.
mod engine;
use thiserror::Error;
pub use engine::*;
#[derive(Debug, Error, Clone, PartialEq, Eq)]
pub enum Error {
#[error("input is not a PE image")]
Invalid,
#[error("PE range is outside the input")]
OutOfBounds,
}
pub type Result<T> = std::result::Result<T, Error>;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Section {
pub virtual_address: u32,
pub virtual_size: u32,
pub raw_offset: u32,
pub raw_size: u32,
pub characteristics: u32,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Headers {
pub pe_offset: usize,
pub is_pe32_plus: bool,
pub image_base: u64,
pub size_of_image: u32,
pub entry_rva: u32,
pub sections_offset: usize,
pub sections: u16,
}
pub fn parse(data: &[u8]) -> Result<Headers> {
if data.get(0..2) != Some(b"MZ") {
return Err(Error::Invalid);
}
let pe_offset = read_u32(data, 0x3c)? as usize;
if data.get(pe_offset..pe_offset + 4) != Some(b"PE\0\0") {
return Err(Error::Invalid);
}
let sections = read_u16(data, pe_offset + 6)?;
let optional_size = read_u16(data, pe_offset + 20)? as usize;
let optional = pe_offset.checked_add(24).ok_or(Error::OutOfBounds)?;
let magic = read_u16(data, optional)?;
let is_pe32_plus = magic == 0x20b;
if !is_pe32_plus && magic != 0x10b {
return Err(Error::Invalid);
}
let entry_rva = read_u32(data, optional + 16)?;
let image_base = if is_pe32_plus {
read_u64(data, optional + 24)?
} else {
read_u32(data, optional + 28)? as u64
};
let size_of_image = read_u32(data, optional + 56)?;
let sections_offset = optional
.checked_add(optional_size)
.ok_or(Error::OutOfBounds)?;
let table_size = usize::from(sections)
.checked_mul(40)
.ok_or(Error::OutOfBounds)?;
data.get(sections_offset..sections_offset + table_size)
.ok_or(Error::OutOfBounds)?;
Ok(Headers {
pe_offset,
is_pe32_plus,
image_base,
size_of_image,
entry_rva,
sections_offset,
sections,
})
}
pub fn sections(data: &[u8], headers: Headers) -> Result<Vec<Section>> {
(0..headers.sections)
.map(|index| {
let offset = headers
.sections_offset
.checked_add(usize::from(index) * 40)
.ok_or(Error::OutOfBounds)?;
Ok(Section {
virtual_size: read_u32(data, offset + 8)?,
virtual_address: read_u32(data, offset + 12)?,
raw_size: read_u32(data, offset + 16)?,
raw_offset: read_u32(data, offset + 20)?,
characteristics: read_u32(data, offset + 36)?,
})
})
.collect()
}
/// Read one PE data-directory entry as `(RVA, size)`.
pub fn data_directory(data: &[u8], headers: Headers, index: u16) -> Result<(u32, u32)> {
let directory_base = headers
.pe_offset
.checked_add(24)
.and_then(|offset| offset.checked_add(if headers.is_pe32_plus { 112 } else { 96 }))
.ok_or(Error::OutOfBounds)?;
let offset = directory_base
.checked_add(
usize::from(index)
.checked_mul(8)
.ok_or(Error::OutOfBounds)?,
)
.ok_or(Error::OutOfBounds)?;
Ok((read_u32(data, offset)?, read_u32(data, offset + 4)?))
}
/// Return the COFF characteristics bit field.
pub fn characteristics(data: &[u8], headers: Headers) -> Result<u16> {
read_u16(
data,
headers
.pe_offset
.checked_add(22)
.ok_or(Error::OutOfBounds)?,
)
}
pub fn rva_to_offset(data: &[u8], headers: Headers, rva: u32) -> Result<usize> {
if rva < headers.sections_offset as u32 {
return Ok(rva as usize);
}
for section in sections(data, headers)? {
let span = section.virtual_size.max(section.raw_size);
if rva >= section.virtual_address && rva < section.virtual_address.saturating_add(span) {
let offset = section
.raw_offset
.checked_add(rva - section.virtual_address)
.ok_or(Error::OutOfBounds)? as usize;
if offset < data.len() {
return Ok(offset);
}
}
}
Err(Error::OutOfBounds)
}
/// Map a complete RVA range backed by file bytes in the headers or one section.
/// Unlike a virtual mapping, this rejects a section's zero-filled tail.
pub fn rva_range(
data: &[u8],
headers: Headers,
rva: u32,
size: u32,
) -> Result<std::ops::Range<usize>> {
let header_size = read_u32(data, headers.pe_offset + 24 + 60)?;
let offset = if rva < header_size && size <= header_size - rva {
rva
} else {
sections(data, headers)?
.into_iter()
.find_map(|section| {
let delta = rva.checked_sub(section.virtual_address)?;
if delta >= section.raw_size || size > section.raw_size - delta {
return None;
}
section.raw_offset.checked_add(delta)
})
.ok_or(Error::OutOfBounds)?
} as usize;
let end = offset
.checked_add(size as usize)
.ok_or(Error::OutOfBounds)?;
data.get(offset..end).ok_or(Error::OutOfBounds)?;
Ok(offset..end)
}
fn read_u16(data: &[u8], offset: usize) -> Result<u16> {
let bytes: [u8; 2] = data
.get(offset..offset + 2)
.ok_or(Error::OutOfBounds)?
.try_into()
.map_err(|_| Error::OutOfBounds)?;
Ok(u16::from_le_bytes(bytes))
}
fn read_u32(data: &[u8], offset: usize) -> Result<u32> {
let bytes: [u8; 4] = data
.get(offset..offset + 4)
.ok_or(Error::OutOfBounds)?
.try_into()
.map_err(|_| Error::OutOfBounds)?;
Ok(u32::from_le_bytes(bytes))
}
fn read_u64(data: &[u8], offset: usize) -> Result<u64> {
let bytes: [u8; 8] = data
.get(offset..offset + 8)
.ok_or(Error::OutOfBounds)?
.try_into()
.map_err(|_| Error::OutOfBounds)?;
Ok(u64::from_le_bytes(bytes))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn rva_ranges_require_file_backing_for_every_byte() {
let mut data = [0u8; 0x400];
let headers = Headers {
pe_offset: 0x40,
is_pe32_plus: false,
image_base: 0,
size_of_image: 0x2000,
entry_rva: 0x1000,
sections_offset: 0x100,
sections: 1,
};
for (offset, value) in [
(0x94, 0x200u32),
(0x108, 0x100),
(0x10c, 0x1000),
(0x110, 0x80),
(0x114, 0x200),
] {
data[offset..offset + 4].copy_from_slice(&value.to_le_bytes());
}
assert_eq!(rva_range(&data, headers, 0x1000, 0x80), Ok(0x200..0x280));
assert_eq!(rva_range(&data, headers, 0x100, 0x100), Ok(0x100..0x200));
for (rva, size) in [(0x1070, 0x20), (0x1080, 1), (0x1f0, 0x20), (u32::MAX, 4)] {
assert_eq!(
rva_range(&data, headers, rva, size),
Err(Error::OutOfBounds)
);
}
}
}
senbei-wasm/Cargo.lock
Generated
+27 -61
View File
@@ -2,12 +2,6 @@
# It is not intended for manual editing.
version = 4
[[package]]
name = "adler2"
version = "2.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
[[package]]
name = "aes"
version = "0.9.3"
@@ -168,8 +162,6 @@ version = "1.1.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
dependencies = [
"crc32fast",
"miniz_oxide",
"zlib-rs",
]
@@ -316,16 +308,6 @@ dependencies = [
"libc",
]
[[package]]
name = "miniz_oxide"
version = "0.9.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c"
dependencies = [
"adler2",
"simd-adler32",
]
[[package]]
name = "once_cell"
version = "1.21.4"
@@ -429,33 +411,29 @@ dependencies = [
]
[[package]]
name = "senbei-android-crypto"
version = "1.2.0"
name = "senbei-crypto"
version = "1.3.1"
dependencies = [
"aes",
"thiserror",
]
[[package]]
name = "senbei-android-elf"
version = "1.2.0"
dependencies = [
"memmap2",
"senbei-android-crypto",
"serde",
"serde_json",
"sha2",
"tempfile",
"thiserror",
]
[[package]]
name = "senbei-android-engine"
version = "1.2.0"
name = "senbei-elf"
version = "1.3.1"
dependencies = [
"goblin",
"thiserror",
]
[[package]]
name = "senbei-engine"
version = "1.3.1"
dependencies = [
"memmap2",
"senbei-android-crypto",
"senbei-crypto",
"senbei-elf",
"senbei-pe",
"serde",
"serde_json",
"sha2",
@@ -463,33 +441,18 @@ dependencies = [
"thiserror",
]
[[package]]
name = "senbei-android-metadata"
version = "1.2.0"
dependencies = [
"serde",
"thiserror",
]
[[package]]
name = "senbei-crypto"
version = "1.2.0"
dependencies = [
"thiserror",
]
[[package]]
name = "senbei-io"
version = "1.2.0"
version = "1.3.1"
dependencies = [
"anyhow",
"flate2",
"indicatif",
"libc",
"memmap2",
"owo-colors",
"senbei-android-elf",
"senbei-android-engine",
"senbei-android-metadata",
"senbei-crypto",
"senbei-elf",
"senbei-engine",
"senbei-metadata",
"senbei-pe",
"sha2",
@@ -501,24 +464,27 @@ dependencies = [
[[package]]
name = "senbei-metadata"
version = "1.2.0"
version = "1.3.1"
dependencies = [
"serde",
"thiserror",
]
[[package]]
name = "senbei-pe"
version = "1.2.0"
version = "1.3.1"
dependencies = [
"senbei-crypto",
"thiserror",
]
[[package]]
name = "senbei-wasm"
version = "1.2.0"
version = "1.3.1"
dependencies = [
"console_error_panic_hook",
"senbei-engine",
"senbei-io",
"senbei-metadata",
"senbei-pe",
"wasm-bindgen",
]
senbei-wasm/Cargo.toml
+3 -2
View File
@@ -1,7 +1,8 @@
[package]
name = "senbei-wasm"
version = "1.2.0"
version = "1.3.1"
edition = "2024"
rust-version = "1.98.1"
description = "WebAssembly bindings for senbei (browser frontend assets live in web/)"
license = "AGPL-3.0-only"
@@ -11,7 +12,7 @@ crate-type = ["cdylib"]
[dependencies]
senbei-io = { path = "../senbei-io" }
senbei-metadata = { path = "../senbei-metadata" }
senbei-pe = { path = "../senbei-pe" }
senbei-engine = { path = "../senbei-engine" }
wasm-bindgen = "0.2"
console_error_panic_hook = "0.1"
senbei-wasm/src/lib.rs
+6 -6
View File
@@ -101,12 +101,12 @@ impl MetadataResult {
}
}
fn kind_str(kind: senbei_pe::Kind) -> &'static str {
fn kind_str(kind: senbei_engine::Kind) -> &'static str {
match kind {
senbei_pe::Kind::NativeExe => "native-exe",
senbei_pe::Kind::ManagedExe => "managed-exe",
senbei_pe::Kind::NativeDll => "native-dll",
senbei_pe::Kind::ManagedDll => "managed-dll",
senbei_engine::Kind::NativeExe => "native-exe",
senbei_engine::Kind::ManagedExe => "managed-exe",
senbei_engine::Kind::NativeDll => "native-dll",
senbei_engine::Kind::ManagedDll => "managed-dll",
}
}
@@ -120,7 +120,7 @@ pub fn detect(input: &[u8]) -> Option<String> {
if senbei_metadata::is_metadata(input) {
return Some("metadata".to_string());
}
senbei_pe::detect(input).map(|d| kind_str(d.kind).to_string())
senbei_engine::detect(input).map(|d| kind_str(d.kind).to_string())
}
/// Unpack a protected module.
web/README.md
+10 -61
View File
@@ -1,76 +1,25 @@
# Senbei web
# Senbei Web
Senbei running in the browser: the unpacker core compiled to WebAssembly,
wrapped in a small static page. Everything is client-side — files are read
into the page, unpacked locally, and offered back as downloads. Nothing is
uploaded; there is no server component.
Senbei runs in the browser through the `senbei-wasm` crate. Files are read locally, unpacked in a worker, and offered back as downloads; no server receives input bytes.
## Features
- A legal notice is shown as a blocking dialog on page open; the tool is
unusable until it is acknowledged.
- Dropped files land in a file list, not unpacked immediately: review the
batch, remove mistakes, then press **Unpack**. A module and its `._`
companion can be dropped in any order (or in separate drops) — companions
auto-pair by name (`Foo.dll._` → `Foo.dll`) and show as a badge on the
module's row; removing a module removes its companion too.
- Rows show state at a glance: black while staged, an animated blue bar
while unpacking, green on success (with a download button) and red on
failure.
- Drop one or more protected `.exe` / `.dll` modules → get `<name>.unpack.*`
downloads.
- Drop an il2cpp `global-metadata.dat` → de-obfuscated
`global-metadata.unpack.dat` (only when tokens actually change).
- Each output passes the same static integrity check as the CLI; suspect
outputs are flagged with the specific defects found.
- Protected `.exe` and `.dll` files produce `<name>.unpack.*` downloads.
- External `.exe._` and `.dll._` companions are paired by filename.
- `global-metadata.dat` produces `global-metadata.unpack.dat` when tokens change.
- Each output receives the same static integrity check as the CLI.
## Architecture notes
Every unpack uses a disposable Web Worker so a WebAssembly trap cannot freeze the page. A trapped DLL can be retried through the forced-EXE path, matching native routing.
- Every unpack runs in a **disposable Web Worker** (fresh wasm instance per
file): the UI stays responsive on 100 MB+ modules, and a wasm trap is
isolated to that worker.
- **Why workers matter for correctness:** the DLL-first routing probe relies
on `catch_unwind` to reject EXE-shell-layout DLLs, and panics cannot be
caught in WebAssembly — the probe traps the whole call. When a DLL unpack
traps, the app retries once in a new worker with the forced-EXE pipeline
(`unpack_file_force_exe`), reproducing the CLI's dll-first/exe-fallback
outcome. Spliced companion inputs skip the probe entirely (they are always
EXE-shell layout), exactly like the CLI.
- Rust panic messages are forwarded to the browser console
(`console_error_panic_hook`) — check devtools when reporting an issue.
## Building
Requires a Rust toolchain (`rust-toolchain.toml` in the repo root pins one,
including the `wasm32-unknown-unknown` target) and
[wasm-pack](https://rustwasm.github.io/wasm-pack/installer/).
## Build
```cmd
cd senbei-wasm
wasm-pack build --target web --release --out-dir ../web/pkg
```
This produces `web/pkg/` (git-ignored). Then serve the `web/` directory with
any static file server and open `index.html`:
```cmd
python -m http.server -d web 8000
:: -> http://localhost:8000
```
(Opening `index.html` via `file://` won't work — ES modules require HTTP.)
Serve `web/` with a static HTTP server, for example `python -m http.server -d web 8000`. Opening `index.html` with `file://` does not work because browser modules require HTTP.
## Layout
```
senbei-wasm/ the senbei-wasm cdylib crate (own Cargo.lock, outside the
workspace; depends on the senbei-pe/-io/-metadata crates)
└── src/lib.rs #[wasm_bindgen] bindings: detect / unpack_file /
unpack_file_force_exe / deobfuscate_metadata
web/
├── index.html the page
├── app.js dropzone, file list, worker orchestration, downloads
├── worker.js one-shot unpack worker (fresh wasm instance per file)
├── style.css
└── pkg/ wasm-pack output (git-ignored; build from senbei-wasm/)
```
`senbei-wasm/src/lib.rs` contains the bindings. `web/app.js` manages the dropzone and downloads, `web/worker.js` runs one unpack job per worker, and `web/pkg/` contains ignored wasm-pack output.
web/app.js
+31 -3
View File
@@ -50,6 +50,22 @@ const KIND_LABEL = {
'native-dll': 'protected native DLL',
'managed-dll': 'protected managed DLL',
metadata: 'il2cpp metadata',
'android-package':
'Android app package — the web build cannot unpack these yet; use the senbei CLI',
'android-so':
'Android AArch64 library — the web build cannot unpack these yet; use the senbei CLI',
};
// Android targets are recognized by extension so the row can explain the
// situation instead of reporting a protected file as unrecognized: the
// Android pipeline is filesystem orchestration (senbei-io) with no wasm
// build, so these files need the CLI. The pseudo-kinds are labels only —
// they never reach the worker.
const ANDROID_KIND = {
apk: 'android-package',
apks: 'android-package',
xapk: 'android-package',
so: 'android-so',
};
const COMPANION_SVG =
@@ -91,8 +107,13 @@ async function stageFiles(list) {
// the PE header fields); read a small slice, not the whole file.
const head = new Uint8Array(await file.slice(0, 65536).arrayBuffer());
// Companions are ciphertext fragments; detect() only makes sense on the
// base module, so skip it for `._` files.
const kind = file.name.endsWith('._') ? undefined : detect(head);
// base module, so skip it for `._` files. Android targets short-circuit
// detect() as well: an ELF/zip never classifies as a protected PE, and
// the row must carry the android pseudo-kind for its status line.
const ext = file.name.slice(file.name.lastIndexOf('.') + 1).toLowerCase();
const kind = file.name.endsWith('._')
? undefined
: (ANDROID_KIND[ext] ?? detect(head));
const old = files.get(file.name);
files.set(file.name, {
file,
@@ -284,7 +305,10 @@ function render() {
const unpackable = [...files].some(
([name, e]) =>
!name.endsWith('._') && e.kind !== undefined && e.state === 'staged',
!name.endsWith('._') &&
e.kind !== undefined &&
!e.kind.startsWith('android-') &&
e.state === 'staged',
);
unpackBtn.disabled = !unpackable;
actions.hidden = files.size === 0;
@@ -364,6 +388,10 @@ unpackBtn.addEventListener('click', async () => {
continue;
}
// Android rows are informational only (no wasm pipeline); their staged
// status line already says to use the CLI.
if (entry.kind.startsWith('android-')) continue;
entry.state = 'working';
render();
try {
web/index.html
+3 -1
View File
@@ -56,7 +56,9 @@
<p class="hint">
Protected <code>.exe</code> / <code>.dll</code> modules, optional
<code>._</code> companions, or an il2cpp
<code>global-metadata.dat</code>.
<code>global-metadata.dat</code>. Android packages
(<code>.apk</code> / <code>.apks</code> / <code>.xapk</code>) and
<code>.so</code> libraries are recognized but need the CLI.
</p>
<input type="file" id="picker" multiple hidden>
</div>
web/style.css
+20
View File
@@ -333,6 +333,26 @@ footer {
}
footer a { color: var(--dim); }
/* --- narrow screens --- */
/* On a narrow viewport the status column (flex: 1, right-aligned) is
squeezed by a long file name into a one-word-per-line vertical strip.
Stack the row instead: name + icons on the first line, the status on its
own full-width line below, left-aligned. */
@media (max-width: 560px) {
main { padding: 1.5rem 0.9rem 2.5rem; }
#dropzone { padding: 1.75rem 1rem; }
.file .row { flex-wrap: wrap; }
.file .name { flex: 1; min-width: 0; }
.file .status {
order: 6; /* after the download/remove icons */
flex-basis: 100%;
text-align: left;
}
}
/* --- animations --- */
@keyframes fadeIn {