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.1.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:v1.3.1
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
24 Commits
v1.1.0 ... v1.3.1
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
Momoko-Ayase cbfacbc31f Upgrade dependencies to latest stable 
zip 0.6.6 -> 8.6.0 (the 0.6 line is unmaintained), aes 0.8 -> 0.9
(BlockCipherDecrypt trait replaces BlockDecrypt), sha2 0.10 -> 0.11
(Array no longer formats as hex; local hex_digest helpers). Outputs are
byte-identical across the upgrade: full golden corpus and Android corpus
sidecars all pass.
 2026-09-02 03:19:06 +08:00
Momoko-Ayase d3dd1a8ff8 Merge Android (AArch64) shared-library restoration, bump to 1.2.0 
Adds the Android protection-scheme pipeline: hollowed ELF64/AArch64
libraries are restored statically (stage-1/stage-2 module extraction,
container decode, dynamic-linker table rebuild), with app-package
(.apk/.apks/.xapk) container handling, cross-source content dedup, and
il2cpp metadata support for the Android variants (seeded RID permutation;
embedded XOR-wrapped blob extraction).

The single senbei CLI now routes single .so files, packages, and folders
by content; outputs follow the existing .unpack-infix naming under
<root>/unpack or --out. PE behavior is unchanged (35/35 goldens).
 2026-09-02 03:09:21 +08:00
bfloat16 35076848b6 chore: ignore local test corpus 2026-08-16 03:49:11 +08:00
bfloat16 18886272e5 docs: note embedded metadata compatibility 2026-08-16 03:43:12 +08:00
bfloat16 b534de872d refactor: move library implementations into modules 2026-08-16 03:38:42 +08:00
bfloat16 a9aaf95e01 docs: add Android compatibility matrix 2026-08-16 03:31:25 +08:00
bfloat16 7f827d6400 feat: add folder-based Android unpack workflow 2026-08-16 02:38:07 +08:00
bfloat16 131ced6db5 feat: add static stage extraction and metadata detection 2026-08-16 01:47:25 +08:00
bfloat16 b1d3699df3 feat: add static Android il2cpp restoration 2026-08-16 00:34:08 +08:00
bfloat16 9433b4dcca Initial commit 2026-08-15 22:20:03 +08:00
79 changed files with 9851 additions and 1553 deletions
Expand all files Collapse all files
AGENTS.md
+20 -62
View File
@@ -1,82 +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: a Cargo
workspace with a pure, panic-free, no-I/O unpacker core (`senbei-pe/`, built
on `senbei-crypto/`), an il2cpp metadata de-obfuscator (`senbei-metadata/`),
filesystem/CLI orchestration (`senbei-io/`), 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). 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 unpacker core stays pure**: no file I/O, no `unsafe`, no panics across
the public boundary, no platform-specific code. It must keep compiling to
`wasm32-unknown-unknown` (`cargo check --target wasm32-unknown-unknown`).
- **`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
+345 -7
View File
@@ -2,6 +2,17 @@
# It is not intended for manual editing.
version = 4
[[package]]
name = "aes"
version = "0.9.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "35f0f96ce78e38c3dc6d8948aa8163d06385be74000f3c7a95bf1eef35d3ea32"
dependencies = [
"cipher",
"cpubits",
"cpufeatures",
]
[[package]]
name = "anyhow"
version = "1.0.104"
@@ -14,6 +25,15 @@ version = "2.13.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
[[package]]
name = "block-buffer"
version = "0.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d2f6c7dbe95a6ed67ad9f18e57daf93a2f034c524b99fd2b76d18fdfeb6660aa"
dependencies = [
"hybrid-array",
]
[[package]]
name = "bumpalo"
version = "3.20.3"
@@ -26,6 +46,16 @@ version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
[[package]]
name = "cipher"
version = "0.5.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e8cf2a2c93cd704877c0858356ed03480ff301ee950b43f1cbe4573b088bfa6c"
dependencies = [
"crypto-common",
"inout",
]
[[package]]
name = "console"
version = "0.16.4"
@@ -38,12 +68,68 @@ dependencies = [
"windows-sys",
]
[[package]]
name = "const-oid"
version = "0.10.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a6ef517f0926dd24a1582492c791b6a4818a4d94e789a334894aa15b0d12f55c"
[[package]]
name = "cpubits"
version = "0.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "15b85f9c39137c3a891689859392b1bd49812121d0d61c9caf00d46ed5ce06ae"
[[package]]
name = "cpufeatures"
version = "0.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566"
dependencies = [
"libc",
]
[[package]]
name = "crc32fast"
version = "1.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8498c871161e1742aaa9d52551b2d6ebdd4c3d45a3be423e3728f33b955be550"
dependencies = [
"cfg-if",
]
[[package]]
name = "crypto-common"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453"
dependencies = [
"hybrid-array",
]
[[package]]
name = "digest"
version = "0.11.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2"
dependencies = [
"block-buffer",
"const-oid",
"crypto-common",
]
[[package]]
name = "encode_unicode"
version = "1.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "34aa73646ffb006b8f5147f3dc182bd4bcb190227ce861fc4a4844bf8e3cb2c0"
[[package]]
name = "equivalent"
version = "1.0.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
[[package]]
name = "errno"
version = "0.3.14"
@@ -60,6 +146,15 @@ version = "2.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
[[package]]
name = "flate2"
version = "1.1.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
dependencies = [
"zlib-rs",
]
[[package]]
name = "futures-core"
version = "0.3.34"
@@ -95,6 +190,42 @@ dependencies = [
"r-efi",
]
[[package]]
name = "goblin"
version = "0.10.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "17582616a7718cca54cec18e534a76c7c4aec11a8b9a85695712f262fd15a4c8"
dependencies = [
"log",
"plain",
"scroll",
]
[[package]]
name = "hashbrown"
version = "0.17.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
[[package]]
name = "hybrid-array"
version = "0.4.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "707114b52a152fa7bdb290cd7cd5912d9467273b6d74e21b8d81aca1f8533f6b"
dependencies = [
"typenum",
]
[[package]]
name = "indexmap"
version = "2.14.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "07aa2048142242915a31d35844fb311e0e53fcca590c3a0a40dcf1b841fa09eb"
dependencies = [
"equivalent",
"hashbrown",
]
[[package]]
name = "indicatif"
version = "0.18.6"
@@ -108,6 +239,21 @@ dependencies = [
"web-time",
]
[[package]]
name = "inout"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4250ce6452e92010fdf7268ccc5d14faa80bb12fc741938534c58f16804e03c7"
dependencies = [
"hybrid-array",
]
[[package]]
name = "itoa"
version = "1.0.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
[[package]]
name = "js-sys"
version = "0.3.104"
@@ -131,6 +277,27 @@ version = "0.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
[[package]]
name = "log"
version = "0.4.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
[[package]]
name = "memchr"
version = "2.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
[[package]]
name = "memmap2"
version = "0.9.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d1219ed1b7f229ee7104d281dd01d6802fe28bb6e95d292942c4daacdeb798c0"
dependencies = [
"libc",
]
[[package]]
name = "once_cell"
version = "1.21.4"
@@ -149,6 +316,12 @@ version = "0.2.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
[[package]]
name = "plain"
version = "0.2.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b4596b6d070b27117e987119b4dac604f3c58cfb0b191112e24771b2faeac1a6"
[[package]]
name = "portable-atomic"
version = "1.15.0"
@@ -208,48 +381,163 @@ dependencies = [
]
[[package]]
name = "senbei-cli"
version = "1.1.0"
name = "scroll"
version = "0.13.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c1257cd4248b4132760d6524d6dda4e053bc648c9070b960929bf50cfb1e7add"
dependencies = [
"scroll_derive",
]
[[package]]
name = "scroll_derive"
version = "0.13.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e1a36a382ed65dbcc0ab47fd5e9a94112417ccd34560a392ef3b7b0f0ec39148"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.4",
]
[[package]]
name = "senbei-cli"
version = "1.3.1"
dependencies = [
"senbei-engine",
"senbei-io",
"senbei-metadata",
"sha2",
"tempfile",
]
[[package]]
name = "senbei-crypto"
version = "1.1.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.1.0"
version = "1.3.1"
dependencies = [
"anyhow",
"indicatif",
"libc",
"memmap2",
"owo-colors",
"senbei-crypto",
"senbei-elf",
"senbei-engine",
"senbei-metadata",
"senbei-pe",
"sha2",
"tempfile",
"walkdir",
"windows",
"zip",
]
[[package]]
name = "senbei-metadata"
version = "1.1.0"
version = "1.3.1"
dependencies = [
"serde",
"thiserror",
]
[[package]]
name = "senbei-pe"
version = "1.1.0"
version = "1.3.1"
dependencies = [
"senbei-crypto",
"thiserror",
]
[[package]]
name = "serde"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
dependencies = [
"serde_core",
"serde_derive",
]
[[package]]
name = "serde_core"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
dependencies = [
"serde_derive",
]
[[package]]
name = "serde_derive"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.4",
]
[[package]]
name = "serde_json"
version = "1.0.151"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
dependencies = [
"itoa",
"memchr",
"serde",
"serde_core",
"zmij",
]
[[package]]
name = "sha2"
version = "0.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "446ba717509524cb3f22f17ecc096f10f4822d76ab5c0b9822c5f9c284e825f4"
dependencies = [
"cfg-if",
"cpufeatures",
"digest",
]
[[package]]
name = "simd-adler32"
version = "0.3.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
[[package]]
name = "slab"
version = "0.4.12"
@@ -311,6 +599,18 @@ dependencies = [
"syn 3.0.4",
]
[[package]]
name = "typed-path"
version = "0.12.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8e28f89b80c87b8fb0cf04ab448d5dd0dd0ade2f8891bae878de66a75a28600e"
[[package]]
name = "typenum"
version = "1.20.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
[[package]]
name = "unicode-ident"
version = "1.0.24"
@@ -521,3 +821,41 @@ checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37"
dependencies = [
"windows-link",
]
[[package]]
name = "zip"
version = "8.6.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2d04a6b5381502aa6087c94c669499eb1602eb9c5e8198e534de571f7154809b"
dependencies = [
"crc32fast",
"flate2",
"indexmap",
"memchr",
"typed-path",
"zopfli",
]
[[package]]
name = "zlib-rs"
version = "0.6.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "34b31d188d9d685a4f9c7b46d6e36631b07058d2cfe190267adce54dc230bf12"
[[package]]
name = "zmij"
version = "1.0.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
[[package]]
name = "zopfli"
version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f05cd8797d63865425ff89b5c4a48804f35ba0ce8d125800027ad6017d2b5249"
dependencies = [
"bumpalo",
"crc32fast",
"log",
"simd-adler32",
]
Cargo.toml
+22 -1
View File
@@ -2,6 +2,8 @@
members = [
"senbei-cli",
"senbei-crypto",
"senbei-elf",
"senbei-engine",
"senbei-io",
"senbei-metadata",
"senbei-pe",
@@ -13,15 +15,22 @@ exclude = ["senbei-wasm"]
resolver = "2"
[workspace.package]
version = "1.1.0"
version = "1.3.1"
edition = "2024"
rust-version = "1.98.1"
license = "AGPL-3.0-only"
[workspace.dependencies]
aes = "0.9"
anyhow = "1"
goblin = "0.10"
indicatif = "0.18"
libc = "0.2"
memmap2 = "0.9"
owo-colors = "4"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
sha2 = "0.11"
tempfile = "3"
thiserror = "2"
walkdir = "2"
@@ -30,11 +39,23 @@ windows = { version = "0.62", features = [
"Win32_System_Console",
"Win32_System_SystemInformation",
] }
zip = { version = "8", default-features = false, features = ["deflate"] }
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" }
[workspace.lints.rust]
unsafe_op_in_unsafe_fn = "deny"
[workspace.lints.clippy]
correctness = { level = "deny", priority = -1 }
suspicious = { level = "warn", priority = -1 }
complexity = { level = "warn", priority = -1 }
perf = { level = "warn", priority = -1 }
[profile.release]
opt-level = 3
lto = true
README.md
+34 -55
View File
@@ -1,77 +1,56 @@
# Senbei
A static unpacker for Crackproof-protected 64-bit and 32-bit PE files. Point it
at a file 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 or secrets, and
distributes no keys, cracks, or copyrighted content.
- 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. |
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. Anything unrecognized is left untouched.
## Quick start
## Quick Start
```cmd
cargo build --release
senbei protected.exe
:: -> unpack\protected.unpack.exe
senbei game.apk
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 -135
View File
@@ -1,159 +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-io/`** — filesystem and orchestration: recursive folder scanning,
per-run log file, progress bar, Explorer-friendly exit pause, and the
single-file/folder orchestration in `job.rs` (incl. the wasm-safe in-memory
byte API used by the web frontend).
- **`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)
├── scan.rs recursive Crackproof + metadata discovery
├── 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-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`).
## 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.
## Integrity check
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.
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.
## Validation
## Parallelism
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.
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.
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.
## Error model
## WebAssembly
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 -95
View File
@@ -2,121 +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).
- `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 -95
View File
@@ -1,126 +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.
## Folder mode
## Android Targets
Senbei walks the directory recursively, skips any subdirectory literally named
`unpack`, and unpacks every file it recognises as Crackproof-protected (by
content, not extension — renamed files and `.bak` backups are still found).
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**:
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.
```cmd
senbei "C:\Games\MyGame"
:: -> C:\Games\MyGame\unpack\...
:: -> C:\Games\MyGame\unpack\senbei-YYYYMMDD-HHMMSS.log
```
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.
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.
## Folder Mode
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:
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.
```
12 unpacked · 3 skipped · 0 errors · 1 suspect · 2 metadata
done in 1234 ms
```
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.
## Integrity check
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.
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.
## Integrity Check
It flags only defects that cannot occur in a correctly unpacked image:
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.
- 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 `[N/9]` per-stage unpack progress (and the destination path) for each file. 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 unpacked, 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 -76
View File
@@ -1,84 +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.
`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-cli/Cargo.toml
+2
View File
@@ -13,8 +13,10 @@ path = "src/main.rs"
[dependencies]
senbei-io.workspace = true
senbei-engine.workspace = true
[dev-dependencies]
senbei-io.workspace = true
senbei-metadata.workspace = true
sha2.workspace = true
tempfile.workspace = true
senbei-cli/src/main.rs
+9 -11
View File
@@ -74,14 +74,7 @@ fn main() -> std::process::ExitCode {
match result {
Ok(summary) => {
if quiet < 2 {
println!(
"{} unpacked · {} skipped · {} errors · {} suspect · {} metadata",
summary.unpacked,
summary.skipped,
summary.errors,
summary.suspect,
summary.metadata
);
println!("{}", summary.line());
println!("done in {} ms", summary.duration_ms);
}
if summary.errors > 0 { 1 } else { 0 }
@@ -105,8 +98,13 @@ fn print_help() {
"senbei <file|folder> [--out DIR] [-v|--verbose] [-q|--quiet]... [--scan-all] [--no-log] [--no-pause] [-V|--version] [-h|--help]"
);
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."
" input a Crackproof PE (.exe/.dll), an il2cpp global-metadata.dat,\n\
\x20 a protected Android AArch64 library (.so), an Android app\n\
\x20 package (.apk/.apks/.xapk), or a folder containing any of\n\
\x20 these"
);
println!(
" --scan-all probe selected .exe/.dll/.so/metadata names below the\n\
\x20 size floor; other filenames remain excluded."
);
}
senbei-cli/tests/android_samples.rs
+231
View File
@@ -0,0 +1,231 @@
//! Corpus test over the user-managed Android samples.
//!
//! Each immediate subdirectory of `samples/android/` that contains a `lib/`
//! tree is one app-package sample (an extracted APK layout). For every
//! protected AArch64 `.so` found by content probe, the test runs the real
//! restore pipeline and checks the result:
//!
//! - `<name>.golden.so.sha256` next to the input pins the restored bytes
//! (byte-identity through the digest; absent sidecar -> WARNING).
//! - `<name>.restore-fails` (empty marker) documents an input whose restore
//! is known to fail; the test then *requires* failure, so a future fix
//! surfaces as a test failure too. Without the marker a failed restore is
//! a test failure.
//! - A restored library carrying an unwrappable embedded metadata blob must
//! produce one, pinned by `<name>.golden.metadata.sha256`.
//!
//! The folder-mode driver is then run over each app dir to exercise the
//! scan/restore/write path end to end; its error count must equal the number
//! of marked known-failures.
//!
//! The corpus is git-ignored and absent on CI (no binaries in the repo);
//! `SENBEI_REQUIRE_SAMPLES=1` turns an absent corpus into a failure, and
//! `SENBEI_ANDROID_SAMPLES` overrides the corpus location.
mod common;
use std::path::{Path, PathBuf};
use senbei_io::{android, job};
fn corpus_dir() -> PathBuf {
if let Some(dir) = std::env::var_os("SENBEI_ANDROID_SAMPLES") {
return PathBuf::from(dir);
}
common::samples_dir().join("android")
}
/// Immediate subdirectories of `root` that hold an app tree (a `lib/`
/// folder) — research notes, dumps, and other non-app material in the corpus
/// never match.
fn app_dirs(root: &Path) -> Vec<PathBuf> {
let mut dirs: Vec<PathBuf> = std::fs::read_dir(root)
.unwrap_or_else(|e| panic!("read {}: {e}", root.display()))
.filter_map(|entry| entry.ok().map(|entry| entry.path()))
.filter(|path| path.is_dir() && path.join("lib").is_dir())
.collect();
dirs.sort();
dirs
}
/// Every regular `.so` below `dir`, skipping previous output trees.
fn collect_so_files(dir: &Path, out: &mut Vec<PathBuf>) {
let mut entries: Vec<_> = std::fs::read_dir(dir)
.unwrap_or_else(|e| panic!("read {}: {e}", dir.display()))
.filter_map(|entry| entry.ok().map(|entry| entry.path()))
.collect();
entries.sort();
for path in entries {
if path.is_dir() {
if path
.file_name()
.is_some_and(|name| !name.eq_ignore_ascii_case("unpack"))
{
collect_so_files(&path, out);
}
} else if path
.extension()
.and_then(|ext| ext.to_str())
.is_some_and(|ext| ext.eq_ignore_ascii_case("so"))
{
out.push(path);
}
}
}
fn sha256_hex(data: &[u8]) -> String {
use sha2::Digest;
let mut digest = sha2::Sha256::new();
digest.update(data);
let mut out = String::with_capacity(64);
for byte in digest.finalize() {
out.push_str(&format!("{byte:02x}"));
}
out
}
/// `<stem>.golden.so.sha256` next to `input`.
fn golden_sidecar(input: &Path, artifact: &str) -> PathBuf {
let file = input.file_name().unwrap().to_string_lossy();
let stem = file.strip_suffix(".so").unwrap_or(&file);
input.with_file_name(format!("{stem}.golden.{artifact}.sha256"))
}
fn read_sidecar(path: &Path) -> Option<String> {
std::fs::read_to_string(path)
.ok()
.map(|text| text.trim().to_ascii_lowercase())
}
#[test]
fn android_samples_restore_against_goldens() {
let root = corpus_dir();
// Same opt-in gate as the PE corpus test: an absent corpus is a no-op
// pass unless CI explicitly requires it.
let require = std::env::var_os("SENBEI_REQUIRE_SAMPLES").is_some();
if !root.is_dir() {
assert!(
!require,
"android samples: {} does not exist — corpus required (CI)",
root.display()
);
eprintln!(
"android samples: {} does not exist, nothing to test",
root.display()
);
return;
}
let apps = app_dirs(&root);
if apps.is_empty() {
assert!(
!require,
"android samples: no app trees under {} — corpus required (CI)",
root.display()
);
eprintln!("android samples: no app trees under {}", root.display());
return;
}
let mut passed = 0usize;
let mut warnings: Vec<String> = Vec::new();
let mut failures: Vec<String> = Vec::new();
for app in &apps {
let mut so_files = Vec::new();
collect_so_files(app, &mut so_files);
let protected: Vec<PathBuf> = so_files
.into_iter()
.filter(|path| android::is_protected_so_file(path))
.collect();
let mut known_failures = 0usize;
for input in &protected {
let name = input.file_name().unwrap().to_string_lossy().to_string();
let known_fails = input.with_file_name(format!(
"{}.restore-fails",
name.strip_suffix(".so").unwrap_or(&name)
));
let temp = tempfile::tempdir().expect("tempdir");
let dest = temp.path().join("restored.so");
match android::restore_so_file(input, &dest, false) {
Ok(embedded) => {
if known_fails.is_file() {
failures.push(format!(
"{name}: restore succeeded but a restore-fails marker exists \
(delete the marker — the gap is fixed)"
));
continue;
}
let bytes = std::fs::read(&dest).expect("read restored output");
match read_sidecar(&golden_sidecar(input, "so")) {
Some(expected) if expected == sha256_hex(&bytes) => passed += 1,
Some(expected) => failures.push(format!(
"{name}: restored bytes differ from golden\n expected sha256 {expected}\n actual sha256 {}",
sha256_hex(&bytes)
)),
None => warnings.push(format!(
"{name}: no golden sidecar — restored sha256 {}",
sha256_hex(&bytes)
)),
}
if let Some(blob) = embedded {
match read_sidecar(&golden_sidecar(input, "metadata")) {
Some(expected) if expected == sha256_hex(&blob) => {}
Some(expected) => failures.push(format!(
"{name}: embedded metadata differs from golden\n expected sha256 {expected}\n actual sha256 {}",
sha256_hex(&blob)
)),
None => warnings.push(format!(
"{name}: no embedded-metadata sidecar — sha256 {}",
sha256_hex(&blob)
)),
}
}
}
Err(error) => {
if known_fails.is_file() {
known_failures += 1;
} else {
failures.push(format!("{name}: restore failed: {error:#}"));
}
}
}
}
// Folder-mode smoke run: the scan must route every protected library,
// and only the marked known-failures may error.
let out_temp = tempfile::tempdir().expect("tempdir");
match job::run_folder_opts(app, Some(out_temp.path()), 2, false, true, false) {
Ok(summary) => {
if summary.errors != known_failures {
failures.push(format!(
"{}: folder run errors {} != known-failure markers {known_failures}",
app.display(),
summary.errors
));
}
if summary.unpacked < protected.len().saturating_sub(known_failures) {
failures.push(format!(
"{}: folder run restored {} libraries, per-file pass found {} ({} known-failing)",
app.display(),
summary.unpacked,
protected.len(),
known_failures
));
}
}
Err(error) => failures.push(format!("{}: folder run failed: {error:#}", app.display())),
}
}
for warning in &warnings {
eprintln!("WARNING: {warning}");
}
eprintln!(
"android samples: {} app tree(s) — {passed} pass, {} warning(s), {} failure(s)",
apps.len(),
warnings.len(),
failures.len()
);
assert!(failures.is_empty(), "{}", failures.join("\n"));
}
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-crypto/src/android/mod.rs
+8
View File
@@ -0,0 +1,8 @@
//! Android container cryptography and decoding primitives.
mod protector;
pub use protector::{
ContainerHeader, EncodedSegment, Error, HuffmanLzDecoder, Module9bConfig, ProtectedDescriptor,
decode_container, gf32_mul_fixed, transform_segment,
};
senbei-crypto/src/android/protector.rs
+712
View File
@@ -0,0 +1,712 @@
//! Cryptographic and compression primitives used by the Android protector.
use aes::Aes256;
use aes::cipher::{BlockCipherDecrypt, KeyInit};
const RECORD_SIZE: usize = 0x5c;
/// Errors raised while parsing or decoding protector containers.
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error("{0}")]
Invalid(String),
}
type Result<T> = std::result::Result<T, Error>;
fn invalid<T>(message: impl Into<String>) -> Result<T> {
Err(Error::Invalid(message.into()))
}
fn range(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"
))
})
}
fn read_u16(data: &[u8], offset: usize) -> Result<u16> {
let bytes: [u8; 2] = range(data, offset, 2)?
.try_into()
.map_err(|_| Error::Invalid("invalid u16 range".to_owned()))?;
Ok(u16::from_le_bytes(bytes))
}
fn read_u32(data: &[u8], offset: usize) -> Result<u32> {
let bytes: [u8; 4] = range(data, offset, 4)?
.try_into()
.map_err(|_| Error::Invalid("invalid u32 range".to_owned()))?;
Ok(u32::from_le_bytes(bytes))
}
fn align_up(value: usize, alignment: usize) -> Result<usize> {
let mask = alignment
.checked_sub(1)
.ok_or_else(|| Error::Invalid("zero alignment".to_owned()))?;
value
.checked_add(mask)
.map(|v| v & !mask)
.ok_or_else(|| Error::Invalid("alignment overflow".to_owned()))
}
/// Multiply by the fixed element used by the native GF(2^32) transform.
#[must_use]
pub fn gf32_mul_fixed(mut value: u32) -> u32 {
let mut multiplier = 0x9451_1dd2_u32;
let mut result = 0_u32;
while multiplier != 0 {
if multiplier & 1 != 0 {
result ^= value;
}
let carry = value >> 31;
value = value.wrapping_shl(1);
if carry != 0 {
value ^= 0x5793_57eb;
}
multiplier >>= 1;
}
result
}
fn mix_columns(block: [u8; 16]) -> [u8; 16] {
const fn xtime(value: u8) -> u8 {
(value << 1) ^ if value & 0x80 != 0 { 0x1b } else { 0 }
}
let mut output = [0_u8; 16];
for offset in (0..16).step_by(4) {
let [a, b, c, d] = block[offset..offset + 4] else {
unreachable!("fixed four-byte AES column")
};
output[offset] = xtime(a) ^ (xtime(b) ^ b) ^ c ^ d;
output[offset + 1] = a ^ xtime(b) ^ (xtime(c) ^ c) ^ d;
output[offset + 2] = a ^ b ^ xtime(c) ^ (xtime(d) ^ d);
output[offset + 3] = (xtime(a) ^ a) ^ b ^ c ^ xtime(d);
}
output
}
/// Static configuration recovered from module `0x9B`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Module9bConfig {
pub header_seed: u32,
pub container_seed: u32,
pub aes_key: [u8; 32],
pub skip_aes: bool,
pub schedule_offset: usize,
}
impl Module9bConfig {
/// Parse the unique AES-256 decryption schedule and adjacent configuration.
pub fn parse(image: &[u8]) -> Result<Self> {
Self::parse_inner(image, true)
}
/// Parse the decoder configuration embedded in the raw Stage 2 image.
///
/// The embedded decoder ends before the interpreter-only `skip_aes`
/// field, so that flag is definitionally false for this layout.
pub fn parse_embedded(image: &[u8]) -> Result<Self> {
Self::parse_inner(image, false)
}
fn parse_inner(image: &[u8], has_skip_aes: bool) -> Result<Self> {
const MARKER: [u8; 4] = [0x00, 0x01, 0x0e, 0x00];
let mut matches = image
.windows(MARKER.len())
.enumerate()
.filter_map(|(offset, bytes)| (bytes == MARKER).then_some(offset));
let schedule_offset = matches
.next()
.ok_or_else(|| Error::Invalid("cannot locate the 0x9B AES-256 schedule".to_owned()))?;
if schedule_offset < 8 || matches.next().is_some() {
return invalid("cannot uniquely locate the 0x9B AES-256 schedule");
}
let header_seed = read_u32(image, schedule_offset - 8)?;
let schedule_size = read_u32(image, schedule_offset - 4)?;
if !matches!(schedule_size, 0 | 0xf4) {
return invalid(format!(
"unexpected 0x9B AES schedule size 0x{schedule_size:x}"
));
}
let bits = read_u16(image, schedule_offset)?;
let rounds = read_u16(image, schedule_offset + 2)?;
if (bits, rounds) != (0x100, 14) {
return invalid(format!(
"unexpected AES schedule header 0x{bits:x}/{rounds}"
));
}
let schedule = range(image, schedule_offset + 4, 15 * 16)?;
let mut round_keys = [[0_u8; 16]; 15];
for (round, output) in round_keys.iter_mut().enumerate() {
let source = &schedule[round * 16..round * 16 + 16];
for word in 0..4 {
let start = word * 4;
for byte in 0..4 {
output[start + byte] = source[start + 3 - byte];
}
}
}
let mut aes_key = [0_u8; 32];
aes_key[..16].copy_from_slice(&round_keys[14]);
aes_key[16..].copy_from_slice(&mix_columns(round_keys[13]));
let container_seed_offset = schedule_offset
.checked_add(0x100)
.ok_or_else(|| Error::Invalid("container seed offset overflow".to_owned()))?;
let skip_aes = if has_skip_aes {
let skip_aes_offset = schedule_offset
.checked_add(0x240)
.ok_or_else(|| Error::Invalid("skip-AES offset overflow".to_owned()))?;
*image.get(skip_aes_offset).ok_or_else(|| {
Error::Invalid("module static configuration exceeds its image".to_owned())
})? != 0
} else {
false
};
Ok(Self {
header_seed,
container_seed: if has_skip_aes {
read_u32(image, container_seed_offset)?
} else {
header_seed
},
aes_key,
skip_aes,
schedule_offset,
})
}
}
/// Decrypted header at the start of direct-data object `0x9D`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ProtectedDescriptor {
pub command_id: u32,
pub flags: u32,
pub outer_offset: u32,
pub outer_expected_size: u32,
pub auxiliary_offset: u32,
pub auxiliary_expected_size: u32,
}
impl ProtectedDescriptor {
/// Decrypt the `0x5c`-byte descriptor with the module header seed.
pub fn decrypt(data: &[u8], seed: u32) -> Result<Self> {
if data.len() < RECORD_SIZE {
return invalid("0x9D descriptor is truncated");
}
let base0 = seed.wrapping_add(0xd3e8_7144).wrapping_mul(seed);
let base1 = base0.wrapping_add(seed.wrapping_mul(0x0bd9_418d));
let mut words = [0_u32; RECORD_SIZE / 4];
for (index, word) in words.iter_mut().enumerate() {
let cipher = read_u32(data, index * 4)?;
let subtractor = base0.wrapping_shl(if index & 1 != 0 { 4 } else { 0 });
*word = cipher.wrapping_sub(subtractor)
^ base1.wrapping_shr((seed.wrapping_add((index as u32).wrapping_mul(4))) & 7);
}
if words[6..].iter().any(|&word| word != 0) {
return invalid("unexpected nonzero reserved words in the 0x9D descriptor");
}
let descriptor = Self {
command_id: words[0],
flags: words[1],
outer_offset: words[2],
outer_expected_size: words[3],
auxiliary_offset: words[4],
auxiliary_expected_size: words[5],
};
if descriptor.command_id != 0x9d || descriptor.outer_offset as usize != RECORD_SIZE {
return invalid("unexpected decrypted 0x9D descriptor");
}
Ok(descriptor)
}
}
/// One encrypted segment in a decoded `0x9D` container header.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct EncodedSegment {
pub offset: u32,
pub size: u32,
}
/// Parsed primary or auxiliary `0x9D` container.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ContainerHeader {
pub start: usize,
pub output_size: u32,
pub skip_aes: bool,
pub tree: Vec<u8>,
pub segments: Vec<EncodedSegment>,
}
impl ContainerHeader {
/// Parse and decrypt a container header, Huffman tree, and segment table.
pub fn parse(data: &[u8], start: usize, seed: u32) -> Result<Self> {
range(data, start, 12)?;
let seed_square = seed.wrapping_mul(seed);
let state = seed_square.wrapping_shr(17) ^ seed_square.wrapping_shl(11);
let raw0 = read_u32(data, start)?;
let raw1 = read_u32(data, start + 4)?;
let raw2 = read_u32(data, start + 8)?;
let output_size = 0xa21d_fb3a_u32
.wrapping_shl(state & 7)
.wrapping_add(state.wrapping_mul(0xf87b_337c))
.wrapping_add(gf32_mul_fixed(raw0));
let flag_word = gf32_mul_fixed(raw1)
^ state
.wrapping_add(0xbd19_c63c)
.wrapping_add(0x416e_2af2_u32.wrapping_shr(state & 0x0d));
let segment_count = (flag_word & 0xff) as usize;
let skip_aes = (flag_word >> 8) & 0xff == 1;
let tree_size = 0x643a_3a3b_u32
.wrapping_shl(state & 0x0b)
.wrapping_sub(state ^ 0x3b2b_f538)
.wrapping_add(gf32_mul_fixed(raw2)) as usize;
if segment_count == 0 || tree_size > 0x1b00 {
return invalid(format!(
"invalid container fields: segments={segment_count}, tree=0x{tree_size:x}"
));
}
let tree_start = start
.checked_add(12)
.ok_or_else(|| Error::Invalid("tree offset overflow".to_owned()))?;
let mut tree = range(data, tree_start, tree_size)?.to_vec();
for offset in (0..tree_size & !3).step_by(4) {
let value = read_u32(&tree, offset)?;
tree[offset..offset + 4].copy_from_slice(&gf32_mul_fixed(value).to_le_bytes());
}
let tree_state = state.wrapping_add(0xf1cb_5b81).wrapping_mul(state);
let tree_delta = tree_state.wrapping_sub(0x23b3_2203_u32.wrapping_mul(state));
for (index, byte) in tree.iter_mut().enumerate() {
let shift = u32::try_from(index & 0x1b)
.map_err(|_| Error::Invalid("tree shift conversion failed".to_owned()))?;
let left = gf32_mul_fixed(tree_state.wrapping_shl(shift));
let right = tree_delta.wrapping_shr((index & 0x17) as u32);
let adjustment = left.wrapping_sub(right).wrapping_shr((index & 0x1f) as u32);
*byte = byte.wrapping_add(adjustment as u8);
}
let table_start = start
.checked_add(align_up(12 + tree_size, 4)?)
.ok_or_else(|| Error::Invalid("segment table offset overflow".to_owned()))?;
let table_size = segment_count
.checked_mul(8)
.ok_or_else(|| Error::Invalid("segment table size overflow".to_owned()))?;
let mut table = range(data, table_start, table_size)?.to_vec();
let table_state = state.wrapping_add(0xb31f_451c).wrapping_mul(state);
let table_xor = table_state.wrapping_shl(3);
let table_add = table_state.wrapping_sub(0x822f_e82d_u32.wrapping_mul(state));
for offset in (0..table_size).step_by(4) {
let value = read_u32(&table, offset)?;
let decoded = gf32_mul_fixed(value ^ table_xor)
.wrapping_add(table_add.wrapping_shr(((offset & 7) + 5) as u32));
table[offset..offset + 4].copy_from_slice(&decoded.to_le_bytes());
}
let mut segments = Vec::with_capacity(segment_count);
for index in 0..segment_count {
let offset = read_u32(&table, index * 8)?;
let size = read_u32(&table, index * 8 + 4)?;
let absolute = start
.checked_add(offset as usize)
.and_then(|value| value.checked_add(size as usize));
if size == 0 || absolute.is_none_or(|end| end > data.len()) {
return invalid(format!("container segment {index} lies outside 0x9D"));
}
segments.push(EncodedSegment { offset, size });
}
Ok(Self {
start,
output_size,
skip_aes,
tree,
segments,
})
}
/// End offset of the furthest encrypted segment.
pub fn encoded_end(&self) -> Result<usize> {
self.segments
.iter()
.map(|segment| {
self.start
.checked_add(segment.offset as usize)
.and_then(|value| value.checked_add(segment.size as usize))
.ok_or_else(|| Error::Invalid("encoded segment end overflow".to_owned()))
})
.collect::<Result<Vec<_>>>()?
.into_iter()
.max()
.ok_or_else(|| Error::Invalid("container has no encoded segments".to_owned()))
}
}
/// Decoder for the protector's Huffman/LZ writer streams.
#[derive(Debug, Clone)]
pub struct HuffmanLzDecoder {
tree: Vec<u8>,
lookup_symbols: Vec<u16>,
lookup_bits: Vec<u8>,
}
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().is_multiple_of(3) {
return invalid(format!("invalid Huffman tree size 0x{:x}", tree.len()));
}
let mut result = Self {
tree: tree.to_vec(),
lookup_symbols: vec![0; 0x1_0000],
lookup_bits: vec![0; 0x1_0000],
};
for word in 0..0x1_0000_u32 {
let (symbol, bits) = result.decode_symbol(word)?;
if bits <= 16 {
result.lookup_symbols[word as usize] = symbol;
result.lookup_bits[word as usize] = bits;
}
}
Ok(result)
}
fn entry(&self, index: usize) -> Result<(u16, bool, u8)> {
let offset = index
.checked_mul(3)
.ok_or_else(|| Error::Invalid("Huffman node offset overflow".to_owned()))?;
let bytes = range(&self.tree, offset, 3)?;
let raw = u16::from(bytes[0]) | (u16::from(bytes[1]) << 8);
Ok((raw & 0x7fff, raw & 0x8000 != 0, bytes[2]))
}
fn decode_symbol(&self, word: u32) -> Result<(u16, u8)> {
let (mut value, leaf, extra) = self.entry((word & 0xff) as usize)?;
if leaf {
if extra == 0 {
return invalid("zero-width Huffman leaf");
}
return Ok((value, extra));
}
let mut bits = extra
.checked_add(1)
.ok_or_else(|| Error::Invalid("Huffman bit count overflow".to_owned()))?;
let mut mask = 1_u32.wrapping_shl(u32::from(extra));
loop {
let branch = usize::from(word & mask != 0);
let (next, is_leaf, _) = self.entry(usize::from(value) + branch)?;
value = next;
if is_leaf {
return Ok((value, bits));
}
mask = mask.wrapping_shl(1);
bits = bits
.checked_add(1)
.ok_or_else(|| Error::Invalid("Huffman bit count overflow".to_owned()))?;
if bits > 31 {
return invalid("Huffman code exceeds the native 32-bit window");
}
}
}
/// Decode one compressed writer payload to its exact expected size.
pub fn decode(&self, source: &[u8], output_size: usize) -> Result<Vec<u8>> {
let mut output = vec![0_u8; output_size];
let mut source_pos = 0_usize;
let mut bit_buffer = 0_u64;
let mut available = 0_u8;
let mut consumed_bits = 0_usize;
let mut output_pos = 0_usize;
let mut prefix = 0_usize;
while output_pos < output_size {
while available < 24 && source_pos < source.len() {
bit_buffer |= u64::from(source[source_pos]) << available;
source_pos += 1;
available += 8;
}
let key = (bit_buffer & 0xffff) as usize;
let mut bits = self.lookup_bits[key];
let symbol = if bits != 0 {
self.lookup_symbols[key]
} else {
let mut value_offset = ((bit_buffer & 0xff) as usize) * 3;
let mut node = range(&self.tree, value_offset, 3)?;
let mut raw = u16::from(node[0]) | (u16::from(node[1]) << 8);
if raw & 0x8000 != 0 {
bits = node[2];
raw & 0x7fff
} else {
let extra = node[2];
bits = extra + 1;
let mut mask = 1_u64 << extra;
loop {
let branch = usize::from(bit_buffer & mask != 0);
let index = usize::from(raw & 0x7fff) + branch;
value_offset = index
.checked_mul(3)
.ok_or_else(|| Error::Invalid("Huffman node overflow".to_owned()))?;
node = range(&self.tree, value_offset, 3)?;
raw = u16::from(node[0]) | (u16::from(node[1]) << 8);
if raw & 0x8000 != 0 {
break raw & 0x7fff;
}
mask <<= 1;
bits += 1;
}
}
};
if bits == 0 || bits > available {
return invalid("compressed stream ends inside a Huffman code");
}
bit_buffer >>= bits;
available -= bits;
consumed_bits = consumed_bits
.checked_add(usize::from(bits))
.ok_or_else(|| Error::Invalid("consumed bit count overflow".to_owned()))?;
let kind = symbol & 0x300;
let value = usize::from(symbol & 0xff);
match kind {
0 => {
output[output_pos] = value as u8;
output_pos += 1;
}
0x100 => {
if prefix > 0xff {
return invalid("compressed prefix exceeds 16 bits");
}
prefix = if prefix == 0 {
value
} else {
value | (prefix << 8)
};
}
0x200 => {
if prefix == 0 {
prefix = 1;
}
let count = value
.checked_mul(prefix)
.ok_or_else(|| Error::Invalid("repeat count overflow".to_owned()))?;
if !matches!(value, 1 | 2 | 4)
|| value > output_pos
|| output_pos
.checked_add(count)
.is_none_or(|end| end > output_size)
{
return invalid("invalid compressed repeated-pattern command");
}
let pattern = output[output_pos - value..output_pos].to_vec();
for chunk in output[output_pos..output_pos + count].chunks_exact_mut(value) {
chunk.copy_from_slice(&pattern);
}
output_pos += count;
prefix = 0;
}
0x300 => {
let length = value;
let distance = prefix.checked_add(length).ok_or_else(|| {
Error::Invalid("back-reference distance overflow".to_owned())
})?;
if distance > output_pos
|| output_pos
.checked_add(length)
.is_none_or(|end| end > output_size)
{
return invalid("invalid compressed back-reference");
}
let source_start = output_pos - distance;
output.copy_within(source_start..source_start + length, output_pos);
output_pos += length;
prefix = 0;
}
_ => unreachable!("masked Huffman symbol kind"),
}
}
if consumed_bits.div_ceil(8) != source.len() {
return invalid(format!(
"compressed input consumption mismatch: used=0x{:x}, size=0x{:x}",
consumed_bits.div_ceil(8),
source.len()
));
}
Ok(output)
}
}
/// Apply the native word transform and optional AES-256-CBC decryption.
pub fn transform_segment(
data: &[u8],
seed: u32,
aes_key: &[u8; 32],
decrypt_aes: bool,
) -> Result<Vec<u8>> {
let mut transformed = data.to_vec();
let mut state = seed;
let mut left = 0xe34e_ac63_u32;
let mut right = 0x07b4_8238_u32;
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
.wrapping_add(0x72f6_fcbe)
.wrapping_add(left.wrapping_add(0x4f8b_1bca).wrapping_mul(left))
.wrapping_shr(index32.wrapping_mul(index32) & 0x0f);
right = state
.wrapping_sub(0x71b6_a98d)
.wrapping_add(right.wrapping_sub(0x1605_a81c).wrapping_mul(right))
.wrapping_shl(index32 & 7);
state = left ^ right;
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;
chunk.copy_from_slice(&value.to_le_bytes());
}
if decrypt_aes {
let cipher = Aes256::new_from_slice(aes_key)
.map_err(|_| Error::Invalid("invalid AES-256 key length".to_owned()))?;
let mut previous = [0_u8; 16];
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;
}
previous = ciphertext;
}
}
Ok(transformed)
}
/// Decode one complete protector container into its flat output buffer.
///
/// This is the static equivalent of the decoder entrypoint embedded in Stage
/// 2 and in each nested interpreter module.
pub fn decode_container(
data: &[u8],
config: &Module9bConfig,
expected_size: usize,
) -> Result<Vec<u8>> {
let header = ContainerHeader::parse(data, 0, config.container_seed)?;
let header_size = usize::try_from(header.output_size)
.map_err(|_| Error::Invalid("container output size exceeds usize".to_owned()))?;
if header_size != expected_size {
return invalid(format!(
"container output size 0x{header_size:x} != expected 0x{expected_size:x}"
));
}
let decoder = HuffmanLzDecoder::new(&header.tree)?;
let decrypt_aes = !(config.skip_aes || header.skip_aes);
let mut output = vec![0_u8; expected_size];
for (segment_index, encoded) in header.segments.iter().enumerate() {
let start = header
.start
.checked_add(encoded.offset as usize)
.ok_or_else(|| Error::Invalid("encoded segment start overflow".to_owned()))?;
let encoded_data = range(data, start, encoded.size as usize)?;
let transformed = transform_segment(
encoded_data,
config.container_seed,
&config.aes_key,
decrypt_aes,
)?;
if transformed.len() < 16 {
return invalid(format!(
"decoded segment {segment_index} is shorter than its header"
));
}
let base_offset = read_u32(&transformed, 0)? as usize;
let writer_count = read_u32(&transformed, 4)? as usize;
let table_offset = read_u32(&transformed, 8)? as usize;
let data_offset = read_u32(&transformed, 12)? as usize;
let table_size = writer_count
.checked_mul(16)
.ok_or_else(|| Error::Invalid("writer table size overflow".to_owned()))?;
let table_end = table_offset
.checked_add(table_size)
.ok_or_else(|| Error::Invalid("writer table end overflow".to_owned()))?;
if table_end > transformed.len() || data_offset > transformed.len() {
return invalid(format!(
"decoded segment {segment_index} has invalid writer offsets"
));
}
let mut data_cursor = data_offset;
for writer_index in 0..writer_count {
let record =
table_offset
.checked_add(writer_index.checked_mul(16).ok_or_else(|| {
Error::Invalid("writer record offset overflow".to_owned())
})?)
.ok_or_else(|| Error::Invalid("writer record offset overflow".to_owned()))?;
let output_offset = read_u32(&transformed, record)? as usize;
let output_size = read_u32(&transformed, record + 4)? as usize;
let encoded_size = read_u32(&transformed, record + 8)? as usize;
let reserved = read_u32(&transformed, record + 12)?;
let encoded_end = data_cursor
.checked_add(encoded_size)
.ok_or_else(|| Error::Invalid("writer data end overflow".to_owned()))?;
if reserved != 0 || encoded_end > transformed.len() {
return invalid(format!(
"segment {segment_index} writer {writer_index} has invalid bounds"
));
}
let source = &transformed[data_cursor..encoded_end];
let decoded = if encoded_size == output_size {
None
} else {
Some(decoder.decode(source, output_size)?)
};
let decoded = decoded.as_deref().unwrap_or(source);
let target = base_offset
.checked_add(output_offset)
.ok_or_else(|| Error::Invalid("writer target offset overflow".to_owned()))?;
let target_end = target
.checked_add(decoded.len())
.ok_or_else(|| Error::Invalid("writer target end overflow".to_owned()))?;
let destination = output.get_mut(target..target_end).ok_or_else(|| {
Error::Invalid(format!(
"segment {segment_index} writer {writer_index} target is out of range"
))
})?;
destination.copy_from_slice(decoded);
data_cursor = encoded_end;
}
}
Ok(output)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn aes_mix_columns_matches_fips_example() {
let input = [
0xdb, 0x13, 0x53, 0x45, 0xf2, 0x0a, 0x22, 0x5c, 0x01, 0x01, 0x01, 0x01, 0xc6, 0xc6,
0xc6, 0xc6,
];
assert_eq!(
mix_columns(input),
[
0x8e, 0x4d, 0xa1, 0xbc, 0x9f, 0xdc, 0x58, 0x9d, 0x01, 0x01, 0x01, 0x01, 0xc6, 0xc6,
0xc6, 0xc6,
]
);
}
#[test]
fn descriptor_rejects_truncated_input() {
assert!(ProtectedDescriptor::decrypt(&[0_u8; 16], 1).is_err());
}
}
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-elf/Cargo.toml
+14
View File
@@ -0,0 +1,14 @@
[package]
name = "senbei-elf"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
description = "ELF format parsing and structural utilities for Senbei"
[dependencies]
goblin.workspace = true
thiserror.workspace = true
[lints]
workspace = true
senbei-elf/src/hash.rs
+107
View File
@@ -0,0 +1,107 @@
use crate::{Error, Result, invalid};
#[must_use]
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));
let high = value & 0xf000_0000;
if high != 0 {
value ^= high >> 24;
value &= !high;
}
}
value
}
#[must_use]
pub fn gnu_hash(name: &[u8]) -> u32 {
name.iter().fold(5381_u32, |value, &byte| {
value.wrapping_mul(33).wrapping_add(u32::from(byte))
})
}
pub fn build_sysv_hash(names: &[Vec<u8>]) -> Result<Vec<u8>> {
if names.len() < 2 {
return invalid("dynamic symbol table is unexpectedly empty");
}
let bucket_count = names.len();
let symbol_count = names.len();
let mut buckets = vec![0_u32; bucket_count];
let mut chains = vec![0_u32; symbol_count];
for (symbol_index, name) in names.iter().enumerate().skip(1) {
let bucket_index = elf_hash(name) as usize % bucket_count;
let symbol_index32 = u32::try_from(symbol_index)
.map_err(|_| Error::Invalid("dynamic symbol index exceeds u32".to_owned()))?;
if buckets[bucket_index] == 0 {
buckets[bucket_index] = symbol_index32;
continue;
}
let mut chain_index = buckets[bucket_index] as usize;
while chains[chain_index] != 0 {
chain_index = chains[chain_index] as usize;
}
chains[chain_index] = symbol_index32;
}
let mut output = Vec::with_capacity((2 + bucket_count + symbol_count) * 4);
output.extend_from_slice(
&u32::try_from(bucket_count)
.map_err(|_| Error::Invalid("SysV bucket count exceeds u32".to_owned()))?
.to_le_bytes(),
);
output.extend_from_slice(
&u32::try_from(symbol_count)
.map_err(|_| Error::Invalid("SysV symbol count exceeds u32".to_owned()))?
.to_le_bytes(),
);
for value in buckets.into_iter().chain(chains) {
output.extend_from_slice(&value.to_le_bytes());
}
Ok(output)
}
pub fn build_gnu_hash(names: &[Vec<u8>]) -> Result<Vec<u8>> {
let hashes = names
.iter()
.skip(1)
.map(|name| gnu_hash(name))
.collect::<Vec<_>>();
if hashes.is_empty() {
return invalid("GNU hash requires at least one dynamic symbol");
}
let bloom_shift = 5_u32;
let mut bloom_word = 0_u64;
for &value in &hashes {
bloom_word |= 1_u64 << (value & 63);
bloom_word |= 1_u64 << ((value >> bloom_shift) & 63);
}
let mut chains = hashes
.into_iter()
.map(|value| value & !1)
.collect::<Vec<_>>();
let last = chains
.last_mut()
.ok_or_else(|| Error::Invalid("GNU hash chain is empty".to_owned()))?;
*last |= 1;
let mut output = Vec::with_capacity(28 + chains.len() * 4);
for value in [1_u32, 1, 1, bloom_shift] {
output.extend_from_slice(&value.to_le_bytes());
}
output.extend_from_slice(&bloom_word.to_le_bytes());
output.extend_from_slice(&1_u32.to_le_bytes());
for value in chains {
output.extend_from_slice(&value.to_le_bytes());
}
Ok(output)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn standard_elf_hash_is_stable() {
assert_eq!(elf_hash(b"printf"), 0x0779_05a6);
assert_eq!(gnu_hash(b"printf"), 0x156b_2bb8);
}
}
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-engine/Cargo.toml
+21
View File
@@ -0,0 +1,21 @@
[package]
name = "senbei-engine"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
description = "Platform unpacking engines for Senbei"
[dependencies]
memmap2.workspace = true
serde.workspace = true
serde_json.workspace = true
sha2.workspace = true
tempfile.workspace = true
thiserror.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-engine/src/android/extract/error.rs
+63
View File
@@ -0,0 +1,63 @@
use std::path::{Path, PathBuf};
/// Stage 1 or Stage 2 extraction failure.
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error("{action} `{path}`: {source}")]
Io {
action: &'static str,
path: PathBuf,
#[source]
source: std::io::Error,
},
#[error("parse ELF `{path}`: {source}")]
Elf {
path: PathBuf,
#[source]
source: senbei_elf::Error,
},
#[error("serialize extraction index: {0}")]
Json(#[from] serde_json::Error),
#[error("embedded Stage 2 decoder configuration: {0}")]
EmbeddedConfig(#[source] senbei_crypto::android::Error),
#[error(
"depth {depth} stream 0x{stream_id:02X} interpreter 0x{interpreter_id:02X} configuration: {source}"
)]
InterpreterConfig {
depth: usize,
stream_id: u32,
interpreter_id: u32,
#[source]
source: senbei_crypto::android::Error,
},
#[error(
"depth {depth} stream 0x{stream_id:02X} record {record_index} command 0x{command_id:02X} {part}: {source}"
)]
RecordDecode {
depth: usize,
stream_id: u32,
record_index: usize,
command_id: u32,
part: &'static str,
#[source]
source: senbei_crypto::android::Error,
},
#[error("{0}")]
Invalid(String),
}
impl Error {
pub(crate) fn io(action: &'static str, path: &Path, source: std::io::Error) -> Self {
Self::Io {
action,
path: path.to_path_buf(),
source,
}
}
}
pub(crate) type Result<T> = std::result::Result<T, Error>;
pub(crate) fn invalid<T>(message: impl Into<String>) -> Result<T> {
Err(Error::Invalid(message.into()))
}
senbei-engine/src/android/extract/mod.rs
+12
View File
@@ -0,0 +1,12 @@
mod error;
mod pipeline;
mod probe;
mod report;
mod stage1;
mod stream;
pub use error::Error;
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-engine/src/android/extract/pipeline.rs
+508
View File
@@ -0,0 +1,508 @@
use std::collections::{BTreeMap, BTreeSet, HashSet};
use std::fs::File;
use std::path::{Path, PathBuf};
use memmap2::MmapOptions;
use senbei_crypto::android::{Module9bConfig, decode_container};
use serde_json::to_vec_pretty;
use super::super::common;
use super::error::{Error, Result, invalid};
use super::report::{
ArtifactReport, DecoderReport, ExtractionReport, ModuleRegistryEntry, RecordReport,
Stage1Report, StreamParent, StreamReport,
};
use super::stage1::{
DEFAULT_CIPHER_CONSTANT, DEFAULT_OUTER_SIZE, SHT_LOUSER, Stage1Result, inspect,
};
use super::stream::{DIRECT_FLAG, Record, parse_record_stream};
/// Inputs and output locations for one complete static Stage 2 extraction.
#[derive(Debug, Clone)]
pub struct ExtractOptions {
pub input: PathBuf,
pub output_dir: PathBuf,
pub stage2_output: Option<PathBuf>,
pub outer_size: usize,
pub cipher_constant: u32,
}
impl ExtractOptions {
#[must_use]
pub fn with_defaults(input: PathBuf, output_dir: PathBuf) -> Self {
Self {
input,
output_dir,
stage2_output: None,
outer_size: DEFAULT_OUTER_SIZE,
cipher_constant: DEFAULT_CIPHER_CONSTANT,
}
}
}
#[derive(Debug)]
struct LoadedModule {
image: Vec<u8>,
metadata: Option<Vec<u8>>,
image_path: String,
metadata_path: Option<String>,
sha256: String,
depth: usize,
record_index: usize,
command_id: u32,
init_offset: u32,
entry_offset: u32,
}
#[derive(Debug, Clone, Copy)]
struct ArtifactSpec<'a> {
suffix: &'a str,
kind: &'a str,
classification: &'a str,
}
struct Extractor {
output_dir: PathBuf,
streams: Vec<StreamReport>,
artifacts: Vec<ArtifactReport>,
registry: BTreeMap<u32, LoadedModule>,
seen_streams: HashSet<(u32, String)>,
}
pub fn extract_stage2(options: &ExtractOptions) -> Result<ExtractionReport> {
let input_path = absolute(&options.input)?;
let output_dir = absolute(&options.output_dir)?;
if !input_path.is_file() {
return invalid(format!(
"protected ELF does not exist: {}",
input_path.display()
));
}
if let Some(stage2_output) = &options.stage2_output {
let stage2_output = absolute(stage2_output)?;
if stage2_output == input_path {
return invalid("refusing to overwrite the protected ELF with Stage 2 output");
}
}
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)
.map_err(|source| Error::io("open protected ELF", &input_path, source))?;
// SAFETY: the mapping is read-only, the file remains open for the mapping
// lifetime, and extraction never mutates or truncates the source.
let source = unsafe { MmapOptions::new().map(&file) }
.map_err(|source| Error::io("map protected ELF", &input_path, source))?;
let stage1 = inspect(
&source,
&input_path,
options.outer_size,
options.cipher_constant,
)?;
if let Some(stage2_output) = &options.stage2_output {
write_atomic(&absolute(stage2_output)?, &stage1.plaintext)?;
}
let core_config =
Module9bConfig::parse_embedded(&stage1.plaintext).map_err(Error::EmbeddedConfig)?;
let bootstrap_end = stage1
.remaining_file_offset
.checked_add(stage1.remaining_size)
.ok_or_else(|| Error::Invalid("Stage 2 bootstrap range overflow".to_owned()))?;
let bootstrap = source
.get(stage1.remaining_file_offset..bootstrap_end)
.ok_or_else(|| Error::Invalid("Stage 2 bootstrap range is outside the ELF".to_owned()))?;
let mut extractor = Extractor {
output_dir: output_dir.clone(),
streams: Vec::new(),
artifacts: Vec::new(),
registry: BTreeMap::new(),
seen_streams: HashSet::new(),
};
extractor.extract_stream(
bootstrap,
0xe2,
0,
None,
Some(stage1.remaining_file_offset),
core_config,
)?;
let module_registry = extractor
.registry
.values()
.map(|module| ModuleRegistryEntry {
command_id: module.command_id,
size: module.image.len(),
sha256: module.sha256.clone(),
depth: module.depth,
record_index: module.record_index,
image_path: module.image_path.clone(),
metadata_path: module.metadata_path.clone(),
init_offset: module.init_offset,
entry_offset: module.entry_offset,
classification: if module.metadata.is_some() {
"module_image".to_owned()
} else {
"decoded_data".to_owned()
},
})
.collect::<Vec<_>>();
let report = ExtractionReport {
format_version: 4,
protected_elf: input_path.display().to_string(),
output_dir: output_dir.display().to_string(),
stage1: stage1_report(&stage1, options.outer_size),
streams: extractor.streams,
artifacts: extractor.artifacts,
errors: Vec::new(),
module_registry,
};
write_json_atomic(&output_dir.join("index.json"), &report)?;
Ok(report)
}
impl Extractor {
fn extract_stream(
&mut self,
stream: &[u8],
stream_id: u32,
depth: usize,
parent: Option<StreamParent>,
source_file_offset: Option<usize>,
config: Module9bConfig,
) -> Result<()> {
let digest = sha256(stream);
if !self.seen_streams.insert((stream_id, digest.clone())) {
return Ok(());
}
let (header, records, table_size) =
parse_record_stream(stream, stream_id).map_err(|source| {
Error::Invalid(format!(
"depth {depth} stream 0x{stream_id:02X} record table: {source}"
))
})?;
let mut stream_report = StreamReport {
depth,
stream_id,
parent,
source_file_offset,
available_size: stream.len(),
descriptor_table_size: table_size,
encrypted_header_words: header.encrypted_words,
decrypted_header_words: header.decrypted_words,
record_state: header.record_state,
sha256: digest,
decoder: decoder_report(
if depth == 0 {
"embedded_stage2"
} else {
"decoded_interpreter"
},
(depth != 0).then_some(stream_id),
&config,
),
records: Vec::with_capacity(records.len()),
};
let mut direct_records = Vec::new();
let mut modules_at_level = BTreeSet::new();
for record in records {
let mut result = record_report(record);
let mut image_data = None;
let mut metadata_data = None;
if !record.direct() && record.image_size != 0 {
let image_source = record_tail(stream, record.image_offset)?;
let image = decode_container(image_source, &config, record.image_size as usize)
.map_err(|source| Error::RecordDecode {
depth,
stream_id,
record_index: record.index,
command_id: record.command_id,
part: "image decode",
source,
})?;
let classification = if record.metadata_size != 0 {
"module_image"
} else {
"decoded_data"
};
let artifact = self.write_artifact(
&record,
depth,
stream_id,
ArtifactSpec {
suffix: "module.bin",
kind: "decoded_container",
classification,
},
&image,
)?;
result.image = Some(artifact.clone());
image_data = Some((image, artifact));
}
if record.metadata_size != 0 {
let metadata_source = record_tail(stream, record.metadata_offset)?;
let metadata =
decode_container(metadata_source, &config, record.metadata_size as usize)
.map_err(|source| Error::RecordDecode {
depth,
stream_id,
record_index: record.index,
command_id: record.command_id,
part: "metadata decode",
source,
})?;
let artifact = self.write_artifact(
&record,
depth,
stream_id,
ArtifactSpec {
suffix: "metadata.bin",
kind: "decoded_metadata",
classification: "decoded_metadata",
},
&metadata,
)?;
result.metadata = Some(artifact.clone());
metadata_data = Some((metadata, artifact));
}
if let Some((image, image_artifact)) = image_data {
let (metadata, metadata_path) = if let Some((data, artifact)) = metadata_data {
(Some(data), Some(artifact.path))
} else {
(None, None)
};
self.register_module(LoadedModule {
sha256: image_artifact.sha256.clone(),
image_path: image_artifact.path.clone(),
metadata_path,
image,
metadata,
depth,
record_index: record.index,
command_id: record.command_id,
init_offset: record.init_offset,
entry_offset: record.entry_offset,
})?;
modules_at_level.insert(record.command_id);
}
if record.direct() && record.image_size != 0 {
direct_records.push((record, stream_report.records.len()));
}
stream_report.records.push(result);
}
let mut children = Vec::new();
for (record, report_index) in direct_records {
let next_stream_id = record.command_id.wrapping_sub(0x10);
if modules_at_level.contains(&next_stream_id) {
stream_report.records[report_index].nested_stream_id = Some(next_stream_id);
children.push((record, next_stream_id));
continue;
}
let direct_data = record_slice(stream, record.image_offset, record.image_size)?;
let artifact = self.write_artifact(
&record,
depth,
stream_id,
ArtifactSpec {
suffix: "direct.bin",
kind: "direct",
classification: "direct_data",
},
direct_data,
)?;
stream_report.records[report_index].image = Some(artifact);
}
self.streams.push(stream_report);
for (record, next_stream_id) in children {
let child_data = record_slice(stream, record.image_offset, record.image_size)?;
let parent = StreamParent {
stream_id,
record_index: record.index,
command_id: record.command_id,
};
let interpreter = self.registry.get(&next_stream_id).ok_or_else(|| {
Error::Invalid(format!(
"depth {depth} stream 0x{stream_id:02X} child 0x{next_stream_id:02X} has no interpreter module"
))
})?;
let interpreter_config =
Module9bConfig::parse(&interpreter.image).map_err(|source| {
Error::InterpreterConfig {
depth: depth + 1,
stream_id: next_stream_id,
interpreter_id: next_stream_id,
source,
}
})?;
self.extract_stream(
child_data,
next_stream_id,
depth + 1,
Some(parent),
None,
interpreter_config,
)?;
}
Ok(())
}
fn register_module(&mut self, module: LoadedModule) -> Result<()> {
if let Some(previous) = self.registry.get(&module.command_id) {
if previous.sha256 != module.sha256 {
return invalid(format!(
"module 0x{:02X} produced conflicting images: {} and {}",
module.command_id, previous.sha256, module.sha256
));
}
return Ok(());
}
self.registry.insert(module.command_id, module);
Ok(())
}
fn write_artifact(
&mut self,
record: &Record,
depth: usize,
stream_id: u32,
spec: ArtifactSpec<'_>,
data: &[u8],
) -> Result<ArtifactReport> {
let digest = sha256(data);
let filename = format!(
"d{depth:02}_s{stream_id:02X}_r{:03}_id{:08X}_{}.{}",
record.index,
record.command_id,
&digest[..12],
spec.suffix
);
let path = self.output_dir.join(filename);
write_atomic(&path, data)?;
let artifact = ArtifactReport {
kind: spec.kind.to_owned(),
path: path
.file_name()
.ok_or_else(|| Error::Invalid("artifact path has no file name".to_owned()))?
.to_string_lossy()
.into_owned(),
size: data.len(),
sha256: digest,
depth,
stream_id,
record_index: Some(record.index),
command_id: Some(record.command_id),
classification: spec.classification.to_owned(),
};
self.artifacts.push(artifact.clone());
Ok(artifact)
}
}
fn record_report(record: Record) -> RecordReport {
RecordReport {
index: record.index,
command_id: record.command_id,
flags: record.flags,
image_offset: record.image_offset,
image_size: record.image_size,
metadata_offset: record.metadata_offset,
metadata_size: record.metadata_size,
id_copy: record.id_copy,
entry_offset: record.entry_offset,
init_offset: record.init_offset,
direct: record.flags & DIRECT_FLAG != 0,
extraction_status: "complete".to_owned(),
image: None,
metadata: None,
nested_stream_id: None,
}
}
fn decoder_report(
kind: &str,
interpreter_id: Option<u32>,
config: &Module9bConfig,
) -> DecoderReport {
DecoderReport {
kind: kind.to_owned(),
interpreter_id,
header_seed: config.header_seed,
container_seed: config.container_seed,
schedule_offset: config.schedule_offset,
aes_key_sha256: sha256(&config.aes_key),
skip_aes: config.skip_aes,
}
}
fn record_slice(stream: &[u8], offset: u32, size: u32) -> Result<&[u8]> {
let offset = usize::try_from(offset)
.map_err(|_| Error::Invalid("record payload offset exceeds usize".to_owned()))?;
let size = usize::try_from(size)
.map_err(|_| Error::Invalid("record payload size exceeds usize".to_owned()))?;
let end = offset
.checked_add(size)
.ok_or_else(|| Error::Invalid("record payload range overflows usize".to_owned()))?;
stream.get(offset..end).ok_or_else(|| {
Error::Invalid(format!(
"record payload range 0x{offset:x}..0x{end:x} exceeds stream 0x{:x}",
stream.len()
))
})
}
fn record_tail(stream: &[u8], offset: u32) -> Result<&[u8]> {
let offset = usize::try_from(offset)
.map_err(|_| Error::Invalid("record container offset exceeds usize".to_owned()))?;
stream.get(offset..).ok_or_else(|| {
Error::Invalid(format!(
"record container offset 0x{offset:x} exceeds stream 0x{:x}",
stream.len()
))
})
}
fn stage1_report(stage1: &Stage1Result, outer_size: usize) -> Stage1Report {
Stage1Report {
section_index: stage1.section_index,
section_type: SHT_LOUSER,
section_offset: stage1.section_offset,
section_size: stage1.section_size,
outer_size,
header_offset: stage1.header_offset,
header_key: stage1.header.key,
payload_offset: stage1.header.payload_offset,
payload_size: stage1.header.payload_size,
payload_key: stage1.header.payload_key,
entry_offset: stage1.header.entry_offset,
protect_size: stage1.header.protect_size,
stage2_file_offset: stage1.payload_file_offset,
stage2_size: stage1.plaintext.len(),
stage2_sha256: sha256(&stage1.plaintext),
remaining_file_offset: stage1.remaining_file_offset,
remaining_size: stage1.remaining_size,
}
}
fn write_json_atomic(path: &Path, value: &impl serde::Serialize) -> Result<()> {
let mut bytes = to_vec_pretty(value)?;
bytes.push(b'\n');
write_atomic(path, &bytes)
}
fn write_atomic(path: &Path, data: &[u8]) -> Result<()> {
common::write_atomic(path, data)
.map_err(|source| Error::io("write temporary output", path, source))
}
fn absolute(path: &Path) -> Result<PathBuf> {
common::absolute(path).map_err(|source| Error::io("query current directory", path, source))
}
fn sha256(data: &[u8]) -> String {
common::sha256(data)
}
senbei-engine/src/android/extract/probe.rs
+19
View File
@@ -0,0 +1,19 @@
use std::path::Path;
use senbei_crypto::android::Module9bConfig;
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 {
let Ok(stage1) = stage1::inspect(
data,
Path::new("<probe>"),
DEFAULT_OUTER_SIZE,
DEFAULT_CIPHER_CONSTANT,
) else {
return false;
};
Module9bConfig::parse_embedded(&stage1.plaintext).is_ok()
}
senbei-engine/src/android/extract/report.rs
+115
View File
@@ -0,0 +1,115 @@
use serde::Serialize;
#[derive(Debug, Clone, Serialize)]
pub struct Stage1Report {
pub section_index: usize,
pub section_type: u32,
pub section_offset: usize,
pub section_size: usize,
pub outer_size: usize,
pub header_offset: usize,
pub header_key: u32,
pub payload_offset: u32,
pub payload_size: u32,
pub payload_key: u32,
pub entry_offset: u32,
pub protect_size: u32,
pub stage2_file_offset: usize,
pub stage2_size: usize,
pub stage2_sha256: String,
pub remaining_file_offset: usize,
pub remaining_size: usize,
}
#[derive(Debug, Clone, Serialize)]
pub struct DecoderReport {
pub kind: String,
pub interpreter_id: Option<u32>,
pub header_seed: u32,
pub container_seed: u32,
pub schedule_offset: usize,
pub aes_key_sha256: String,
pub skip_aes: bool,
}
#[derive(Debug, Clone, Serialize)]
pub struct ArtifactReport {
pub kind: String,
pub path: String,
pub size: usize,
pub sha256: String,
pub depth: usize,
pub stream_id: u32,
pub record_index: Option<usize>,
pub command_id: Option<u32>,
pub classification: String,
}
#[derive(Debug, Clone, Serialize)]
pub struct RecordReport {
pub index: usize,
pub command_id: u32,
pub flags: u32,
pub image_offset: u32,
pub image_size: u32,
pub metadata_offset: u32,
pub metadata_size: u32,
pub id_copy: u32,
pub entry_offset: u32,
pub init_offset: u32,
pub direct: bool,
pub extraction_status: String,
pub image: Option<ArtifactReport>,
pub metadata: Option<ArtifactReport>,
pub nested_stream_id: Option<u32>,
}
#[derive(Debug, Clone, Serialize)]
pub struct StreamParent {
pub stream_id: u32,
pub record_index: usize,
pub command_id: u32,
}
#[derive(Debug, Clone, Serialize)]
pub struct StreamReport {
pub depth: usize,
pub stream_id: u32,
pub parent: Option<StreamParent>,
pub source_file_offset: Option<usize>,
pub available_size: usize,
pub descriptor_table_size: usize,
pub encrypted_header_words: [u32; 2],
pub decrypted_header_words: [u32; 2],
pub record_state: u32,
pub sha256: String,
pub decoder: DecoderReport,
pub records: Vec<RecordReport>,
}
#[derive(Debug, Clone, Serialize)]
pub struct ModuleRegistryEntry {
pub command_id: u32,
pub size: usize,
pub sha256: String,
pub depth: usize,
pub record_index: usize,
pub image_path: String,
pub metadata_path: Option<String>,
pub init_offset: u32,
pub entry_offset: u32,
pub classification: String,
}
/// Machine-readable output of one complete static Stage 2 extraction.
#[derive(Debug, Clone, Serialize)]
pub struct ExtractionReport {
pub format_version: u32,
pub protected_elf: String,
pub output_dir: String,
pub stage1: Stage1Report,
pub streams: Vec<StreamReport>,
pub artifacts: Vec<ArtifactReport>,
pub errors: Vec<String>,
pub module_registry: Vec<ModuleRegistryEntry>,
}
senbei-engine/src/android/extract/stage1.rs
+236
View File
@@ -0,0 +1,236 @@
use std::path::Path;
use senbei_elf::{AARCH64_MACHINE, Error as ElfError, parse};
use super::error::{Error, Result, invalid};
pub(crate) use senbei_elf::SHT_LOUSER;
pub const DEFAULT_CIPHER_CONSTANT: u32 = 0xbf20_165d;
pub const DEFAULT_OUTER_SIZE: usize = 0x23c;
#[derive(Debug, Clone, Copy)]
pub(crate) struct Stage1Header {
pub key: u32,
pub reserved: u32,
pub payload_offset: u32,
pub payload_size: u32,
pub payload_key: u32,
pub entry_offset: u32,
pub protect_size: u32,
pub size_copy: u32,
}
#[derive(Debug)]
pub(crate) struct Stage1Result {
pub section_index: usize,
pub section_offset: usize,
pub section_size: usize,
pub header_offset: usize,
pub payload_file_offset: usize,
pub remaining_file_offset: usize,
pub remaining_size: usize,
pub header: Stage1Header,
pub plaintext: Vec<u8>,
}
pub(crate) fn inspect(
data: &[u8],
path: &Path,
outer_size: usize,
cipher_constant: u32,
) -> Result<Stage1Result> {
let elf = parse(data).map_err(|source: ElfError| Error::Elf {
path: path.to_path_buf(),
source,
})?;
if elf.header.e_machine != AARCH64_MACHINE {
return invalid(format!(
"expected AArch64 ELF (machine 0x{AARCH64_MACHINE:X}), got 0x{:X}",
elf.header.e_machine
));
}
let matches = elf
.section_headers
.iter()
.enumerate()
.filter(|(_, section)| section.sh_type == SHT_LOUSER)
.collect::<Vec<_>>();
if matches.len() != 1 {
return invalid(format!(
"expected exactly one SHT_LOUSER section, found {}",
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()))?;
let section_size = usize::try_from(section.sh_size)
.map_err(|_| Error::Invalid("SHT_LOUSER size exceeds usize".to_owned()))?;
let section_end = section_offset
.checked_add(section_size)
.ok_or_else(|| Error::Invalid("SHT_LOUSER range overflows usize".to_owned()))?;
if section_end > data.len() {
return invalid("SHT_LOUSER range extends beyond the input file");
}
let header_relative = outer_size;
if outer_size
.checked_add(0x1000)
.is_none_or(|end| end > section_size)
{
return invalid("Stage 1 outer header leaves no complete parameter area");
}
let header_offset = section_offset
.checked_add(header_relative)
.ok_or_else(|| Error::Invalid("Stage 1 header offset overflow".to_owned()))?;
let header_raw = bytes(data, header_offset, 0x1000)?;
let header = decrypt_header(header_raw, cipher_constant)?;
if header.reserved != 0 {
return invalid(format!(
"Stage 1 header reserved word is nonzero: 0x{:x}",
header.reserved
));
}
if header.size_copy != header.payload_size {
return invalid(format!(
"Stage 1 payload size copy 0x{:x} != size 0x{:x}",
header.size_copy, header.payload_size
));
}
let private_size = section_size - outer_size;
let payload_offset = usize::try_from(header.payload_offset)
.map_err(|_| Error::Invalid("Stage 1 payload offset exceeds usize".to_owned()))?;
let payload_size = usize::try_from(header.payload_size)
.map_err(|_| Error::Invalid("Stage 1 payload size exceeds usize".to_owned()))?;
let payload_end = payload_offset
.checked_add(payload_size)
.ok_or_else(|| Error::Invalid("Stage 1 payload range overflow".to_owned()))?;
if payload_offset < 0x20 || payload_end > private_size {
return invalid(format!(
"Stage 1 payload range 0x{payload_offset:x}..0x{payload_end:x} exceeds private size 0x{private_size:x}"
));
}
if payload_size == 0 || payload_size % 4 != 0 {
return invalid(format!(
"Stage 1 payload size must be nonzero and word aligned: 0x{payload_size:x}"
));
}
let entry_offset = usize::try_from(header.entry_offset)
.map_err(|_| Error::Invalid("Stage 1 entry offset exceeds usize".to_owned()))?;
if entry_offset >= payload_size {
return invalid("Stage 1 entry offset is outside the payload");
}
let protect_size = usize::try_from(header.protect_size)
.map_err(|_| Error::Invalid("Stage 1 protect size exceeds usize".to_owned()))?;
if protect_size > payload_size {
return invalid("Stage 1 mprotect length exceeds the payload");
}
let payload_file_offset = header_offset
.checked_add(payload_offset)
.ok_or_else(|| Error::Invalid("Stage 1 payload file offset overflow".to_owned()))?;
let encrypted = bytes(data, payload_file_offset, payload_size)?;
let plaintext = decrypt_words(encrypted, header.payload_key, cipher_constant)?;
let aligned_payload_end = (payload_end + 3) & !3;
let remaining_relative = aligned_payload_end;
if remaining_relative > private_size {
return invalid("aligned Stage 2 cursor exceeds SHT_LOUSER");
}
let remaining_file_offset = section_offset
.checked_add(outer_size)
.and_then(|value| value.checked_add(remaining_relative))
.ok_or_else(|| Error::Invalid("Stage 2 stream offset overflow".to_owned()))?;
Ok(Stage1Result {
section_index,
section_offset,
section_size,
header_offset,
payload_file_offset,
remaining_file_offset,
remaining_size: private_size - remaining_relative,
header,
plaintext,
})
}
fn decrypt_header(raw: &[u8], constant: u32) -> Result<Stage1Header> {
let key = read_u32(raw, 0)?;
let mut decoded = decrypt_words(&raw[..0x20], key, constant)?;
decoded[..4].copy_from_slice(&key.to_le_bytes());
Ok(Stage1Header {
key,
reserved: read_u32(&decoded, 4)?,
payload_offset: read_u32(&decoded, 8)?,
payload_size: read_u32(&decoded, 12)?,
payload_key: read_u32(&decoded, 16)?,
entry_offset: read_u32(&decoded, 20)?,
protect_size: read_u32(&decoded, 24)?,
size_copy: read_u32(&decoded, 28)?,
})
}
fn decrypt_words(ciphertext: &[u8], key: u32, constant: u32) -> Result<Vec<u8>> {
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.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);
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());
}
Ok(plaintext)
}
fn bytes(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 outside the input"
))
})
}
fn read_u32(data: &[u8], offset: usize) -> Result<u32> {
let bytes = bytes(data, offset, 4)?;
Ok(u32::from_le_bytes(bytes.try_into().map_err(|_| {
Error::Invalid("invalid u32 byte range".to_owned())
})?))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn stage1_word_transform_round_trips() {
let key = 0x1234_5678;
let constant = DEFAULT_CIPHER_CONSTANT;
let plain = [0x1122_3344_u32, 0xaabb_ccdd, 0x0102_0304];
let mut cipher = Vec::new();
for (index, value) in plain.into_iter().enumerate() {
let index = index as u32;
let word = (value ^ constant.wrapping_mul(index + 1))
.wrapping_sub((index + 3).wrapping_mul(key));
cipher.extend_from_slice(&word.to_le_bytes());
}
let decoded = decrypt_words(&cipher, key, constant).unwrap();
let expected = plain
.into_iter()
.flat_map(u32::to_le_bytes)
.collect::<Vec<_>>();
assert_eq!(decoded, expected);
}
}
senbei-engine/src/android/extract/stream.rs
+164
View File
@@ -0,0 +1,164 @@
use senbei_crypto::android::gf32_mul_fixed;
use super::error::{Error, Result, invalid};
pub(crate) const RECORD_SIZE: usize = 0x5c;
pub(crate) const DIRECT_FLAG: u32 = 2;
#[derive(Debug, Clone, Copy)]
pub(crate) struct Record {
pub index: usize,
pub command_id: u32,
pub flags: u32,
pub image_offset: u32,
pub image_size: u32,
pub metadata_offset: u32,
pub metadata_size: u32,
pub id_copy: u32,
pub entry_offset: u32,
pub init_offset: u32,
}
impl Record {
pub(crate) fn direct(self) -> bool {
self.flags & DIRECT_FLAG != 0
}
}
#[derive(Debug, Clone, Copy)]
pub(crate) struct StreamHeader {
pub encrypted_words: [u32; 2],
pub decrypted_words: [u32; 2],
pub record_state: u32,
}
pub(crate) fn parse_record_stream(
stream: &[u8],
stream_id: u32,
) -> Result<(StreamHeader, Vec<Record>, usize)> {
if stream.len() < 8 {
return invalid(format!(
"stream 0x{stream_id:02X} is shorter than its 8-byte header"
));
}
let cipher0 = read_u32(stream, 0)?;
let cipher1 = read_u32(stream, 4)?;
let key = stream_id.wrapping_mul(0x9d32_3cd7);
let shift = stream_id & 7;
let base = (key >> shift)
.wrapping_add(0x5e72_7d74)
.wrapping_add(key.wrapping_shl(stream_id & 0xb))
.wrapping_add(0xf71e_3005);
let plain0 =
gf32_mul_fixed(cipher0.wrapping_add(0xcbf0_c1d8)) ^ 0xeb_e81dba_u32.wrapping_add(base);
let plain1 = gf32_mul_fixed(cipher1.wrapping_add(cipher0))
^ 0xeb_e81dba_u32.wrapping_mul(5).wrapping_add(base);
let header = StreamHeader {
encrypted_words: [cipher0, cipher1],
decrypted_words: [plain0, plain1],
record_state: plain1.wrapping_add(base),
};
let mut records = Vec::new();
let mut first_payload = stream.len();
for index in 0..256_usize {
let start =
8_usize
.checked_add(index.checked_mul(RECORD_SIZE).ok_or_else(|| {
Error::Invalid("record descriptor offset overflow".to_owned())
})?)
.ok_or_else(|| Error::Invalid("record descriptor offset overflow".to_owned()))?;
let end = start
.checked_add(RECORD_SIZE)
.ok_or_else(|| Error::Invalid("record descriptor end overflow".to_owned()))?;
if end > stream.len() {
return invalid(format!(
"stream 0x{stream_id:02X} descriptor table is truncated at record {index}"
));
}
let record = decrypt_record(&stream[start..end], index, header.record_state)?;
if record.id_copy != 0 && record.command_id != record.id_copy {
return invalid(format!(
"stream 0x{stream_id:02X} record {index} command/id mismatch: 0x{:X} != 0x{:X}",
record.command_id, record.id_copy
));
}
for (offset, size) in [
(record.image_offset, record.image_size),
(record.metadata_offset, record.metadata_size),
] {
if offset != 0 && size != 0 {
let offset = usize::try_from(offset).map_err(|_| {
Error::Invalid(format!(
"stream 0x{stream_id:02X} record {index} payload offset exceeds usize"
))
})?;
if offset >= stream.len() {
return invalid(format!(
"stream 0x{stream_id:02X} record {index} payload offset 0x{offset:x} exceeds stream 0x{:x}",
stream.len()
));
}
first_payload = first_payload.min(offset);
}
}
records.push(record);
if end == first_payload {
return Ok((header, records, first_payload));
}
if end > first_payload {
return invalid(format!(
"stream 0x{stream_id:02X} descriptor table crosses first payload at 0x{first_payload:x}"
));
}
}
invalid(format!(
"stream 0x{stream_id:02X} has no descriptor boundary in 256 records"
))
}
fn decrypt_record(raw: &[u8], index: usize, state: u32) -> Result<Record> {
if raw.len() != RECORD_SIZE {
return invalid(format!(
"record {index} has size 0x{:x}, expected 0x{RECORD_SIZE:x}",
raw.len()
));
}
let product = state.wrapping_add(0x96f6_0b71).wrapping_mul(state);
let index_mask = product.wrapping_shl(((index + 1) & 3) as u32);
let mix = state.wrapping_mul(0x06a5_5bcc).wrapping_add(product);
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.as_chunks::<4>().0.iter().enumerate() {
feedback = feedback.wrapping_mul(feedback);
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));
words[word_index] = value;
accumulator = accumulator.wrapping_add(0xe64d_33d8);
feedback = cipher;
}
Ok(Record {
index,
command_id: words[0],
flags: words[1],
image_offset: words[2],
image_size: words[3],
metadata_offset: words[4],
metadata_size: words[5],
id_copy: words[6],
entry_offset: words[7],
init_offset: words[8],
})
}
fn read_u32(data: &[u8], offset: usize) -> Result<u32> {
let bytes = data.get(offset..offset + 4).ok_or_else(|| {
Error::Invalid(format!("record header range 0x{offset:x} is out of bounds"))
})?;
Ok(u32::from_le_bytes(bytes.try_into().map_err(|_| {
Error::Invalid("invalid record u32 range".to_owned())
})?))
}
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-engine/src/android/restore/artifact.rs
+105
View File
@@ -0,0 +1,105 @@
use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
use serde_json::Value;
use super::error::{Error, Result, invalid};
const REQUIRED_IDS: [u32; 3] = [0x9b, 0x9d, 0x9e];
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct Artifact {
pub path: PathBuf,
pub size: u64,
}
pub(crate) fn load_artifacts(index_path: &Path) -> Result<BTreeMap<u32, Artifact>> {
let text = std::fs::read_to_string(index_path)
.map_err(|error| Error::io("read module index", index_path, error))?;
let document: Value = serde_json::from_str(&text)?;
let root = index_path.parent().unwrap_or_else(|| Path::new("."));
let mut result = BTreeMap::new();
if let Some(items) = document.get("module_registry").and_then(Value::as_array) {
for item in items {
let Some(command_id) = item.get("command_id").and_then(Value::as_u64) else {
continue;
};
let command_id = u32::try_from(command_id)
.map_err(|_| Error::Invalid("module command ID exceeds u32".to_owned()))?;
if !REQUIRED_IDS.contains(&command_id) {
continue;
}
let Some(path) = item.get("image_path").and_then(Value::as_str) else {
continue;
};
let size = item
.get("size")
.and_then(Value::as_u64)
.ok_or_else(|| Error::Invalid(format!("module 0x{command_id:02X} lacks size")))?;
result.insert(
command_id,
Artifact {
path: root.join(path),
size,
},
);
}
}
if let Some(streams) = document.get("streams").and_then(Value::as_array) {
for stream in streams {
let Some(records) = stream.get("records").and_then(Value::as_array) else {
continue;
};
for record in records {
let Some(command_id) = record.get("command_id").and_then(Value::as_u64) else {
continue;
};
let command_id = u32::try_from(command_id)
.map_err(|_| Error::Invalid("record command ID exceeds u32".to_owned()))?;
if !REQUIRED_IDS.contains(&command_id) {
continue;
}
let Some(image) = record.get("image") else {
continue;
};
let Some(path) = image.get("path").and_then(Value::as_str) else {
continue;
};
let size = image.get("size").and_then(Value::as_u64).ok_or_else(|| {
Error::Invalid(format!("record 0x{command_id:02X} lacks image size"))
})?;
result.insert(
command_id,
Artifact {
path: root.join(path),
size,
},
);
}
}
}
let missing = REQUIRED_IDS
.iter()
.filter(|id| !result.contains_key(id))
.map(|id| format!("0x{id:02X}"))
.collect::<Vec<_>>();
if !missing.is_empty() {
return invalid(format!(
"module index lacks required IDs: {}",
missing.join(", ")
));
}
for (&command_id, artifact) in &result {
let metadata = std::fs::metadata(&artifact.path)
.map_err(|error| Error::io("inspect artifact", &artifact.path, error))?;
if !metadata.is_file() || metadata.len() != artifact.size {
return invalid(format!(
"invalid artifact for module 0x{command_id:02X}: {}",
artifact.path.display()
));
}
}
Ok(result)
}
senbei-engine/src/android/restore/error.rs
+37
View File
@@ -0,0 +1,37 @@
use std::path::{Path, PathBuf};
/// ELF restoration failure.
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error("{action} `{path}`: {source}")]
Io {
action: &'static str,
path: PathBuf,
#[source]
source: std::io::Error,
},
#[error("cannot parse module index: {0}")]
Json(#[from] serde_json::Error),
#[error(transparent)]
Crypto(#[from] senbei_crypto::android::Error),
#[error(transparent)]
Elf(#[from] senbei_elf::Error),
#[error("{0}")]
Invalid(String),
}
impl Error {
pub(crate) fn io(action: &'static str, path: &Path, source: std::io::Error) -> Self {
Self::Io {
action,
path: path.to_path_buf(),
source,
}
}
}
pub(crate) type Result<T> = std::result::Result<T, Error>;
pub(crate) fn invalid<T>(message: impl Into<String>) -> Result<T> {
Err(Error::Invalid(message.into()))
}
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-engine/src/android/restore/pipeline.rs
+1723
View File
File diff suppressed because it is too large Load Diff
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
+8 -1
View File
@@ -7,11 +7,18 @@ description = "Filesystem, scanning, logging, and CLI orchestration for Senbei"
[dependencies]
anyhow.workspace = true
senbei-crypto.workspace = true
indicatif.workspace = true
memmap2.workspace = true
owo-colors.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
zip.workspace = true
[target.'cfg(windows)'.dependencies]
windows.workspace = true
senbei-io/src/android/mod.rs
+462
View File
@@ -0,0 +1,462 @@
//! Android target orchestration: protected AArch64 shared libraries (`.so`),
//! app packages (`.apk` / `.apks` / `.xapk`), and the Android variant of the
//! il2cpp method-token obfuscation.
//!
//! 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_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_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::fs::File;
use std::io::{BufWriter, Read, Seek, Write};
use std::path::{Path, PathBuf};
use anyhow::{Context, Result, bail};
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;
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
/// 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 {
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 {
is_package_name(path) && prefix.starts_with(b"PK\x03\x04")
}
/// Probe a file on disk: true when it is a protected AArch64 library.
/// Reads the whole file (the payload section is found through the
/// 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(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
/// implementation detail of the two-phase restore, not user-facing output).
/// Returns the unwrapped embedded metadata blob when the restored image
/// carries one (see the module docs); the caller decides where to write it.
pub fn restore_so_file(input: &Path, dest: &Path, verbose: bool) -> Result<Option<Vec<u8>>> {
let temporary = tempfile::tempdir().context("create stage-2 workspace")?;
let stage2_dir = temporary.path().join("stage2");
extract_stage2(&ExtractOptions::with_defaults(
input.to_path_buf(),
stage2_dir.clone(),
))
.context("extract stage-1/stage-2 payload")?;
restore_libil2cpp(&RestoreOptions {
input: input.to_path_buf(),
output: dest.to_path_buf(),
index: stage2_dir.join("index.json"),
dump_auxiliary: None,
outer_only: false,
preserve_entrypoint: false,
verbose,
})
.context("restore protected library")?;
let restored =
std::fs::read(dest).with_context(|| format!("read restored `{}`", dest.display()))?;
Ok(senbei_metadata::android::extract_embedded_metadata(
&restored,
))
}
/// Content identity for cross-source deduplication: the same library may
/// appear loose in a tree, in its `.apk`, and again in an `.apks`/`.xapk`
/// bundle — restore it once, at the highest-priority source's destination.
pub fn content_identity(data: &[u8]) -> String {
let mut digest = Sha256::new();
digest.update(data);
hex_digest(&digest.finalize())
}
/// Restore an il2cpp metadata blob (Android seeded permutation first, then the
/// structural remap used by the Windows builds).
///
/// The Android variant obfuscates MethodDef RIDs with a keyed five-round
/// permutation; the correct seed is recovered by intersecting per-image key
/// residues, and the restore *validates* every restored RID against its
/// canonical per-module index — so an unusable seed fails loudly and the
/// caller falls through to the structural remap, which targets the same
/// 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_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_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_metadata::android::restore_method_tokens(data, seed) {
return Ok((
out,
senbei_metadata::Report {
version: report.version,
methods: report.methods,
remapped: report.changed_tokens,
modules: report.images_with_methods,
},
));
}
}
}
let (out, report) = senbei_metadata::deobfuscate(data).map_err(anyhow::Error::new)?;
Ok((out, report))
}
/// What happened to one archive entry (or one loose Android target).
#[derive(Debug)]
pub struct EntryOutcome {
/// Human-readable source label, e.g. `base.apk::lib/arm64-v8a/libil2cpp.so`.
pub label: String,
/// Where the restored bytes were written (meaningless unless `status` is
/// `Restored`).
pub dest: PathBuf,
pub kind: EntryKind,
pub status: EntryStatus,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EntryKind {
/// A protected shared library, restored.
So,
/// An il2cpp metadata blob, de-obfuscated (`remapped` tokens changed).
Metadata { remapped: usize },
/// A metadata blob unwrapped from a restored library's data section.
EmbeddedMetadata,
}
#[derive(Debug)]
pub enum EntryStatus {
Restored,
/// Byte-identical content was already restored from a higher-priority
/// source; no output written.
Duplicate,
/// Content-probed but not a target (unprotected library).
NotTarget,
/// A metadata blob whose tokens were already canonical; no copy written.
Unchanged,
/// Recognised as a target but the restore failed.
Failed(anyhow::Error),
}
/// Restore every protected library and metadata blob inside one app package.
///
/// `rel` is the package's path relative to the scanned root (or its bare file
/// name in single-file mode); outputs mirror the package's internal layout
/// under `out_root/rel/`, with [`crate::job::out_name`] renaming. `seen`
/// carries content identities already restored from higher-priority sources
/// (loose files first, then `.apk`, then bundles) across the whole run.
pub fn restore_package(
package: &Path,
rel: &Path,
out_root: &Path,
seen: &mut HashSet<String>,
verbose: bool,
) -> Result<Vec<EntryOutcome>> {
let bundle = package
.extension()
.and_then(|value| value.to_str())
.is_some_and(|value| {
value.eq_ignore_ascii_case("apks") || value.eq_ignore_ascii_case("xapk")
});
let mut archive = open_package(package)?;
let temporary = tempfile::tempdir().context("create package workspace")?;
let mut outcomes = Vec::new();
let mut direct = Vec::new();
let mut nested = Vec::new();
for index in 0..archive.len() {
let (name, is_dir) = {
let entry = archive.by_index(index)?;
(entry.enclosed_name(), entry.is_dir())
};
if is_dir {
continue;
}
let Some(name) = name else {
bail!("unsafe entry path in package `{}`", package.display());
};
if bundle {
if name
.extension()
.and_then(|value| value.to_str())
.is_some_and(|value| value.eq_ignore_ascii_case("apk"))
{
nested.push((index, name));
}
} else {
if is_android_entry_name(&name) {
direct.push((index, name));
}
}
}
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(
&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(&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();
for nested_index in 0..nested_archive.len() {
let (entry_name, is_dir) = {
let entry = nested_archive.by_index(nested_index)?;
(entry.enclosed_name(), entry.is_dir())
};
if !is_dir {
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));
}
}
}
// 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(""));
for (nested_index, entry_name) in entries {
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(
&mut nested_archive,
nested_index,
&label,
&dest,
&temporary,
seen,
verbose,
)
.with_context(|| format!("extract `{label}`"))?;
outcomes.append(&mut entry_outcomes);
}
}
Ok(outcomes)
}
/// 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<R: Read + Seek>(
archive: &mut ZipArchive<R>,
index: usize,
label: &str,
dest: &Path,
temporary: &tempfile::TempDir,
seen: &mut HashSet<String>,
verbose: bool,
) -> Result<Vec<EntryOutcome>> {
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(&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(),
kind,
status,
};
if !is_so && !is_meta {
return Ok(vec![outcome(EntryKind::So, EntryStatus::NotTarget)]);
}
if !seen.insert(content_identity(&entry_data)) {
let kind = if is_so {
EntryKind::So
} else {
EntryKind::Metadata { remapped: 0 }
};
return Ok(vec![outcome(kind, EntryStatus::Duplicate)]);
}
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)];
if let Some(blob) = embedded {
let meta_dest = embedded_metadata_dest(dest);
let status = match write_metadata_blob(&meta_dest, &blob) {
Ok(()) => EntryStatus::Restored,
Err(error) => EntryStatus::Failed(error),
};
outcomes.push(EntryOutcome {
label: format!("{label} (embedded metadata)"),
dest: meta_dest,
kind: EntryKind::EmbeddedMetadata,
status,
});
}
outcomes
}
Err(error) => vec![outcome(EntryKind::So, EntryStatus::Failed(error))],
});
}
// 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(&entry_data) {
Ok((out, report)) if report.remapped > 0 => {
let kind = EntryKind::Metadata {
remapped: report.remapped,
};
match write_metadata_blob(dest, &out) {
Ok(()) => (kind, EntryStatus::Restored),
Err(error) => (kind, EntryStatus::Failed(error)),
}
}
Ok(_) => (EntryKind::Metadata { remapped: 0 }, EntryStatus::Unchanged),
Err(error) => (
EntryKind::Metadata { remapped: 0 },
EntryStatus::Failed(error),
),
};
Ok(vec![outcome(kind_and_status.0, kind_and_status.1)])
}
/// Output path for a metadata blob unwrapped from a restored library: next to
/// the library, under the standard file name (with the usual `.unpack` infix).
pub fn embedded_metadata_dest(restored_so: &Path) -> PathBuf {
let dir = restored_so.parent().unwrap_or_else(|| Path::new("."));
dir.join(crate::job::out_name(Path::new(METADATA_FILE_NAME)))
}
/// Write a metadata blob, creating the parent directory. The restore writes
/// 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::atomic::write_atomic(dest, data)
.map_err(anyhow::Error::from)
.context("write metadata output")
}
fn open_package(path: &Path) -> Result<ZipArchive<std::fs::File>> {
let file = std::fs::File::open(path).with_context(|| format!("open `{}`", path.display()))?;
ZipArchive::new(file).with_context(|| format!("read package `{}`", path.display()))
}
/// 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 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 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}",
written
);
}
Ok(destination)
}
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
+341 -536
View File
@@ -1,328 +1,12 @@
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)]
pub struct Summary {
pub unpacked: usize,
pub skipped: usize,
@@ -331,12 +15,29 @@ pub struct Summary {
/// — likely to crash at runtime (e.g. 0xC0000005). Counted in addition to
/// `unpacked` (a suspect file is still written).
pub suspect: usize,
/// il2cpp `global-metadata.dat` files de-obfuscated (method tokens remapped).
/// il2cpp `global-metadata.dat` files de-obfuscated (method tokens remapped),
/// including blobs unwrapped from restored Android libraries.
pub metadata: usize,
/// Android app packages (`.apk`/`.apks`/`.xapk`) opened and searched.
pub packages: usize,
/// Wall-clock duration of the folder run in milliseconds.
pub duration_ms: u128,
}
impl Summary {
/// The summary line shared by CLI output and the log file.
pub fn line(&self) -> String {
let mut line = format!(
"{} unpacked · {} skipped · {} errors · {} suspect · {} metadata",
self.unpacked, self.skipped, self.errors, self.suspect, self.metadata
);
if self.packages > 0 {
line.push_str(&format!(" · {} packages", self.packages));
}
line
}
}
/// Default output root for a folder unpack: `<root>/unpack`.
pub fn default_out_root_for_folder(root: &Path) -> PathBuf {
root.join("unpack")
@@ -385,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>,
@@ -416,12 +114,15 @@ pub fn run_folder_opts(
log.step(&format!("out {}", out_root.display()));
Some(log)
};
// Single merged directory walk: returns Crackproof unpack candidates and
// il2cpp metadata blobs from one traversal (see
// Single merged directory walk: returns Crackproof unpack candidates, il2cpp
// metadata blobs, and Android targets from one traversal (see
// [`crate::scan::find_targets_opts`]). Files the free directory metadata
// already rules out are never opened — on asset-heavy trees the per-file
// open+read latency, not the traversal, is the whole cost.
let (candidates, metas, scan_stats) = crate::scan::find_targets_opts(root, scan_all);
let scan = crate::scan::find_targets_opts(root, scan_all);
let candidates = scan.crackproof.as_slice();
let metas = scan.metadata.as_slice();
let scan_stats = &scan.stats;
// Files the scan could not classify are potential missed targets, not
// clean skips: an unreadable directory or a locked il2cpp game assembly must
// fail the run (exit 1) rather than report "0 errors" over a partial scan.
@@ -453,21 +154,22 @@ pub fn run_folder_opts(
// Verbose mode prints multi-line `[N/9]` step output per file straight to
// stdout; an active progress bar would be clobbered by it, so hide the bar
// (its per-file ok/err lines still print) when verbose is on.
let bar = crate::ui::progress(candidates.len() as u64, quiet >= 1 || verbose);
let android_targets = scan.android_so.len() + scan.android_packages.len();
let bar = crate::ui::progress(
(candidates.len() + android_targets) as u64,
quiet >= 1 || verbose,
);
let mut s = Summary {
unpacked: 0,
skipped: scan_stats.skipped,
errors: scan_failed,
suspect: 0,
metadata: 0,
duration_ms: 0,
..Summary::default()
};
// Silence the default panic hook's stderr spew during per-file processing.
let default_hook = std::panic::take_hook();
std::panic::set_hook(Box::new(|_| {})); // suppress "thread panicked" messages
for input in &candidates {
for input in candidates {
let rel = rel_in_tree(root, input);
let dest = out_root.join(out_name(&rel));
@@ -515,14 +217,146 @@ pub fn run_folder_opts(
bar.inc(1);
}
// Android pass: protected AArch64 libraries and app packages. Loose `.so`
// files restore first so the cross-source dedup keeps them over a copy
// inside a package (loose beats `.apk` beats `.apks`/`.xapk` bundle).
let mut android_seen = std::collections::HashSet::new();
// Hashing a protected library costs a full read, so only pay it when a
// duplicate source can actually exist in this run.
let android_dedup = scan.android_so.len() > 1 || !scan.android_packages.is_empty();
for input in &scan.android_so {
let rel = rel_in_tree(root, input);
let dest = out_root.join(out_name(&rel));
// Unreadable here is fine: the restore reports the same error.
if android_dedup
&& let Ok(identity) = crate::android::file_content_identity(input)
&& !android_seen.insert(identity)
{
s.skipped += 1;
if let Some(log) = &log {
log.step(&format!("SKIP {rel:?}: duplicate of an earlier target"));
}
bar.inc(1);
continue;
}
let input_owned = input.clone();
let dest_owned = dest.clone();
let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
crate::android::restore_so_file(&input_owned, &dest_owned, verbose_steps)
}));
match result {
Ok(Ok(embedded)) => {
s.unpacked += 1;
crate::ui::ok_label(
&bar,
suppress_file_lines,
&rel.display().to_string(),
"So",
&dest,
);
if let Some(log) = &log {
log.step(&format!("OK {rel:?} -> {dest:?} (Android SO)"));
}
match write_embedded_metadata(embedded, &dest) {
Ok(Some(meta_dest)) => {
s.metadata += 1;
crate::ui::ok_label(
&bar,
suppress_file_lines,
&format!("{} (embedded metadata)", rel.display()),
"metadata",
&meta_dest,
);
if let Some(log) = &log {
log.step(&format!("META {rel:?} (embedded) -> {meta_dest:?}"));
}
}
Ok(None) => {}
Err(e) => {
s.errors += 1;
crate::ui::err(&bar, suppress_file_lines, &rel, &e);
if let Some(log) = &log {
log.step(&format!("ERR {rel:?}: embedded metadata: {e:#}"));
}
}
}
}
Ok(Err(e)) => {
s.errors += 1;
crate::ui::err(&bar, suppress_file_lines, &rel, &e);
if let Some(log) = &log {
log.step(&format!("ERR {rel:?}: {e:#}"));
}
}
Err(panic) => {
s.errors += 1;
let e = anyhow::anyhow!("unexpected panic: {}", panic_payload(&panic));
crate::ui::err(&bar, suppress_file_lines, &rel, &e);
if let Some(log) = &log {
log.step(&format!(
"ERR {rel:?}: panic during restore: {}",
panic_payload(&panic)
));
}
}
}
bar.inc(1);
}
for package in &scan.android_packages {
let rel = rel_in_tree(root, package);
s.packages += 1;
let package_owned = package.clone();
let rel_owned = rel.clone().into_owned();
let out_root_owned = out_root.clone();
let mut seen_taken = std::mem::take(&mut android_seen);
let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
let outcomes = crate::android::restore_package(
&package_owned,
&rel_owned,
&out_root_owned,
&mut seen_taken,
verbose_steps,
);
(outcomes, seen_taken)
}));
match result {
Ok((Ok(outcomes), seen_back)) => {
android_seen = seen_back;
apply_package_outcomes(outcomes, &mut s, &bar, suppress_file_lines, &log);
}
Ok((Err(e), seen_back)) => {
android_seen = seen_back;
s.errors += 1;
crate::ui::err(&bar, suppress_file_lines, &rel, &e);
if let Some(log) = &log {
log.step(&format!("ERR {rel:?}: {e:#}"));
}
}
Err(panic) => {
// The dedup set may be in an unknown state after a panic; a
// re-scan costs a duplicate restore at worst, never corruption.
let e = anyhow::anyhow!("unexpected panic: {}", panic_payload(&panic));
s.errors += 1;
crate::ui::err(&bar, suppress_file_lines, &rel, &e);
if let Some(log) = &log {
log.step(&format!(
"ERR {rel:?}: panic during package restore: {}",
panic_payload(&panic)
));
}
}
}
bar.inc(1);
}
// il2cpp metadata pass. Crackproof's `-GMD` option obfuscates the method
// tokens in `global-metadata.dat`; de-obfuscate any we find so the unpacked
// il2cpp game assembly resolves methods instead of indexing its per-module
// tables out of bounds (see [`senbei_metadata`]). This is additive to the
// Crackproof module unpack above — the metadata blob is not itself a
// Crackproof file.
for meta in metas {
let rel = rel_in_tree(root, &meta);
for meta in metas.iter() {
let rel = rel_in_tree(root, meta);
let dest = out_root.join(out_name(&rel));
let meta_owned = meta.clone();
let dest_owned = dest.clone();
@@ -604,10 +438,7 @@ pub fn run_folder_opts(
s.duration_ms = t0.elapsed().as_millis();
if let Some(log) = &log {
log.step(&format!("done in {} ms", s.duration_ms));
log.step(&format!(
"summary: {} unpacked · {} skipped · {} errors · {} suspect · {} metadata",
s.unpacked, s.skipped, s.errors, s.suspect, s.metadata
));
log.step(&format!("summary: {}", s.line()));
}
Ok(s)
}
@@ -646,23 +477,28 @@ pub fn run_file_v(
let name = out_name(Path::new(input.file_name().unwrap_or_default()));
let dest = out_root.join(name);
let mut s = Summary {
unpacked: 0,
skipped: 0,
errors: 0,
suspect: 0,
metadata: 0,
duration_ms: 0,
};
let mut s = Summary::default();
let is_meta = {
let prefix = {
use std::io::Read;
let mut buf = [0u8; 4];
std::fs::File::open(input)
.and_then(|mut f| f.read_exact(&mut buf))
.map(|_| senbei_metadata::is_metadata(&buf))
.unwrap_or(false)
let mut buf = vec![0u8; 8 * 1024];
match std::fs::File::open(input).and_then(|mut f| f.read(&mut buf).map(|n| (buf, n))) {
Ok((buf, n)) => {
let mut b = buf;
b.truncate(n);
b
}
Err(_) => Vec::new(),
}
};
let is_meta = senbei_metadata::is_metadata(&prefix);
// Android single-file targets are routed by content: a protected AArch64
// 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) && crate::android::is_protected_so_file(input);
let is_android_package = !is_android_so && crate::android::is_app_package(input, &prefix);
if is_meta {
match deobfuscate_metadata_to(input, &dest, verbose && quiet == 0) {
@@ -706,6 +542,77 @@ pub fn run_file_v(
}
}
}
} else if is_android_so {
match crate::android::restore_so_file(input, &dest, verbose && quiet == 0) {
Ok(embedded) => {
s.unpacked = 1;
if let Some(log) = &log {
log.step(&format!("OK {:?} -> {:?} (Android SO)", input, dest));
}
if quiet == 0 {
println!("✓ So {} -> {}", input.display(), dest.display());
}
match write_embedded_metadata(embedded, &dest) {
Ok(Some(meta_dest)) => {
s.metadata += 1;
if let Some(log) = &log {
log.step(&format!("META {:?} (embedded) -> {:?}", input, meta_dest));
}
if quiet == 0 {
println!(
"✓ metadata {} (embedded) -> {}",
input.display(),
meta_dest.display()
);
}
}
Ok(None) => {}
Err(e) => {
s.errors += 1;
if let Some(log) = &log {
log.step(&format!("ERR {:?}: embedded metadata: {e:#}", input));
}
if quiet == 0 {
eprintln!("error: embedded metadata: {e:#}");
}
}
}
}
Err(e) => {
s.errors = 1;
if let Some(log) = &log {
log.step(&format!("ERR {:?}: {e:#}", input));
}
if quiet == 0 {
eprintln!("error: {e:#}");
}
}
}
} else if is_android_package {
s.packages = 1;
let rel = PathBuf::from(input.file_name().unwrap_or_default());
let mut seen = std::collections::HashSet::new();
match crate::android::restore_package(
input,
&rel,
&out_root,
&mut seen,
verbose && quiet == 0,
) {
Ok(outcomes) => {
let bar = crate::ui::progress(0, true);
apply_package_outcomes(outcomes, &mut s, &bar, quiet >= 1, &log);
}
Err(e) => {
s.errors = 1;
if let Some(log) = &log {
log.step(&format!("ERR {:?}: {e:#}", input));
}
if quiet == 0 {
eprintln!("error: {e:#}");
}
}
}
} else {
match unpack_one_v(input, &dest, verbose && quiet == 0) {
Ok((kind, report)) => {
@@ -748,10 +655,7 @@ pub fn run_file_v(
s.duration_ms = t0.elapsed().as_millis();
if let Some(log) = &log {
log.step(&format!("done in {} ms", s.duration_ms));
log.step(&format!(
"summary: {} unpacked · {} skipped · {} errors · {} suspect · {} metadata",
s.unpacked, s.skipped, s.errors, s.suspect, s.metadata
));
log.step(&format!("summary: {}", s.line()));
}
Ok(s)
}
@@ -815,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.
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
@@ -966,10 +737,13 @@ pub fn deobfuscate_metadata_to(
verbose: bool,
) -> anyhow::Result<senbei_metadata::Report> {
let data = std::fs::read(input)?;
// Preserve the metadata::Error in the chain (rather than stringifying it)
// so the folder driver can apply its unsupported-version policy.
let (out, report) = senbei_metadata::deobfuscate(&data)
.map_err(|e| anyhow::Error::new(e).context(format!("{input:?}")))?;
// The Android seeded-permutation variant is tried first (it validates
// every restored RID); the structural remap is the fallback and the
// Windows path. The [`senbei_metadata::Error`] is preserved in the chain
// (rather than stringified) so the folder driver can apply its
// unsupported-version policy.
let (out, report) = crate::android::restore_metadata_bytes(&data)
.map_err(|e| e.context(format!("{input:?}")))?;
if report.remapped > 0 {
if let Some(parent) = dest.parent() {
std::fs::create_dir_all(parent)?;
@@ -982,6 +756,77 @@ pub fn deobfuscate_metadata_to(
Ok(report)
}
/// Write an embedded metadata blob (unwrapped from a restored Android
/// library) next to the restored library. Returns the destination when a
/// blob was written.
fn write_embedded_metadata(
embedded: Option<Vec<u8>>,
so_dest: &Path,
) -> anyhow::Result<Option<PathBuf>> {
let Some(blob) = embedded else {
return Ok(None);
};
let dest = crate::android::embedded_metadata_dest(so_dest);
if let Some(parent) = dest.parent() {
std::fs::create_dir_all(parent)?;
}
write_atomic(&dest, &blob)?;
Ok(Some(dest))
}
/// Fold one package's per-entry outcomes into the run summary, UI, and log.
fn apply_package_outcomes(
outcomes: Vec<crate::android::EntryOutcome>,
s: &mut Summary,
bar: &indicatif::ProgressBar,
quiet: bool,
log: &Option<crate::logfile::Log>,
) {
use crate::android::{EntryKind, EntryStatus};
for outcome in outcomes {
match outcome.status {
EntryStatus::Restored => {
match outcome.kind {
EntryKind::So => {
s.unpacked += 1;
crate::ui::ok_label(bar, quiet, &outcome.label, "So", &outcome.dest);
}
EntryKind::Metadata { remapped } => {
s.metadata += 1;
crate::ui::metadata(
bar,
quiet,
Path::new(&outcome.label),
remapped,
&outcome.dest,
);
}
EntryKind::EmbeddedMetadata => {
s.metadata += 1;
crate::ui::ok_label(bar, quiet, &outcome.label, "metadata", &outcome.dest);
}
}
if let Some(log) = log {
log.step(&format!("OK {} -> {:?}", outcome.label, outcome.dest));
}
}
EntryStatus::Duplicate | EntryStatus::NotTarget | EntryStatus::Unchanged => {
s.skipped += 1;
if let Some(log) = log {
log.step(&format!("SKIP {} ({:?})", outcome.label, outcome.kind));
}
}
EntryStatus::Failed(e) => {
s.errors += 1;
crate::ui::err(bar, quiet, Path::new(&outcome.label), &e);
if let Some(log) = log {
log.step(&format!("ERR {}: {e:#}", outcome.label));
}
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
@@ -1002,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
+6
View File
@@ -1,7 +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
+158 -184
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.
@@ -115,6 +40,25 @@ enum Class {
Crackproof,
/// An il2cpp `global-metadata.dat` (de-obfuscation target).
Metadata,
/// A protected AArch64 shared library (Android restore target).
AndroidSo,
/// An Android app package (`.apk`/`.apks`/`.xapk`) — a container whose
/// entries are content-probed individually during the Android pass.
AndroidPackage,
}
/// Everything one [`find_targets_opts`] walk found, plus non-target tallies.
#[derive(Default)]
pub struct ScanResult {
/// Crackproof-protected PE files.
pub crackproof: Vec<PathBuf>,
/// il2cpp `global-metadata.dat` blobs.
pub metadata: Vec<PathBuf>,
/// Protected AArch64 shared libraries.
pub android_so: Vec<PathBuf>,
/// Android app packages (containers restored entry-by-entry).
pub android_packages: Vec<PathBuf>,
pub stats: ScanStats,
}
/// Walk `root` recursively (skipping any directory literally named `"unpack"`)
@@ -132,21 +76,19 @@ enum Class {
/// 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
/// deterministic.
pub fn find_targets(root: &Path) -> (Vec<PathBuf>, Vec<PathBuf>, ScanStats) {
pub fn find_targets(root: &Path) -> ScanResult {
find_targets_opts(root, scan_all_env())
}
@@ -167,9 +109,8 @@ 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.
pub fn find_targets_opts(root: &Path, scan_all: bool) -> (Vec<PathBuf>, Vec<PathBuf>, ScanStats) {
/// `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,
// and `entry.metadata()` is served from the directory entry on Windows, so
@@ -193,7 +134,7 @@ pub fn find_targets_opts(root: &Path, scan_all: bool) -> (Vec<PathBuf>, Vec<Path
// 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,
@@ -205,12 +146,17 @@ pub fn find_targets_opts(root: &Path, scan_all: bool) -> (Vec<PathBuf>, Vec<Path
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()
@@ -228,7 +174,7 @@ pub fn find_targets_opts(root: &Path, scan_all: bool) -> (Vec<PathBuf>, Vec<Path
// `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);
@@ -246,44 +192,28 @@ pub fn find_targets_opts(root: &Path, scan_all: bool) -> (Vec<PathBuf>, Vec<Path
});
}
let mut candidates = Vec::new();
let mut metadata = Vec::new();
let mut result = ScanResult {
stats,
..ScanResult::default()
};
for (p, c) in paths.into_iter().zip(class) {
match c {
Some(Class::Crackproof) => candidates.push(p),
Some(Class::Metadata) => metadata.push(p),
Some(Class::None) => stats.skipped += 1,
Some(Class::Crackproof) => result.crackproof.push(p),
Some(Class::Metadata) => result.metadata.push(p),
Some(Class::AndroidSo) => result.android_so.push(p),
Some(Class::AndroidPackage) => result.android_packages.push(p),
Some(Class::None) => result.stats.skipped += 1,
// Unreadable / panicking probe: NOT skipped — the scan could not
// classify it, so it may be a target we failed to unpack.
None => stats.probe_errors += 1,
None => result.stats.probe_errors += 1,
}
}
(candidates, metadata, stats)
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"),
@@ -291,11 +221,11 @@ 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. 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.
/// 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.
///
/// The detector is wrapped in `catch_unwind` because a panic in a scan worker
/// thread would otherwise abort the whole folder run (a scoped-thread panic
@@ -304,16 +234,30 @@ pub fn scan_all_env() -> bool {
///
/// A Crackproof PE never matches the metadata magic (it is a PE, not a
/// metadata blob) and vice versa, so the order is immaterial.
///
/// 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
/// 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() {
Class::Crackproof
} else if senbei_metadata::is_metadata(&head) {
Class::Metadata
} else {
Class::None
if crate::android::is_package_name(path) && crate::android::is_app_package(path, &head) {
return Class::AndroidPackage;
}
if is_metadata_name(path) && senbei_metadata::is_metadata(&head) {
return Class::Metadata;
}
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;
}
Class::None
}));
r.ok()
}
@@ -332,55 +276,56 @@ 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];
blob[..4].copy_from_slice(&0xFAB1_1BAFu32.to_le_bytes());
std::fs::write(root.join("metadata"), &blob).unwrap();
let (_, filtered, _) = find_targets_opts(root, false);
assert!(filtered.is_empty());
let filtered = find_targets_opts(root, false);
assert!(filtered.metadata.is_empty());
let (_, exhaustive, _) = find_targets_opts(root, true);
assert_eq!(exhaustive.len(), 1);
let exhaustive = find_targets_opts(root, true);
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();
@@ -388,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`.
let (c, m, _) = find_targets_opts(root, false);
assert!(c.is_empty() && m.is_empty());
let (c, m, _) = find_targets_opts(root, true);
assert!(c.is_empty() && m.is_empty());
// 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();
@@ -407,9 +352,9 @@ mod tests {
// Same magic but too small to be processable — skipped by the size floor.
std::fs::write(root.join("stub.dat"), &blob[..64]).unwrap();
let (_, m, _) = find_targets_opts(root, false);
assert_eq!(m.len(), 1);
assert!(m[0].ends_with("global-metadata.dat"));
let scan = find_targets_opts(root, false);
assert_eq!(scan.metadata.len(), 1);
assert!(scan.metadata[0].ends_with("global-metadata.dat"));
}
/// Review regression: a previous output tree is pruned case-insensitively
@@ -428,12 +373,41 @@ mod tests {
// A big non-target file at the root: probed, then skipped.
std::fs::write(root.join("plain.dll"), vec![0u8; 100_000]).unwrap();
let (c, m, stats) = find_targets_opts(root, false);
let scan = find_targets_opts(root, false);
assert!(
c.is_empty() && m.is_empty(),
scan.crackproof.is_empty() && scan.metadata.is_empty(),
"old output tree must be pruned"
);
assert_eq!(stats.skipped, 1, "the probed non-target counts as skipped");
assert_eq!(stats.walk_errors, 0);
assert_eq!(
scan.stats.skipped, 1,
"the probed non-target counts as skipped"
);
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
+14 -8
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.
@@ -19,16 +19,22 @@ pub fn progress(n: u64, quiet: bool) -> ProgressBar {
/// Print a green success line, suspending the progress bar.
pub fn ok(bar: &ProgressBar, quiet: bool, rel: &Path, kind: Kind, dest: &Path) {
ok_label(
bar,
quiet,
&rel.display().to_string(),
&format!("{kind:?}"),
dest,
);
}
/// Print a green success line with a free-form kind label (Android targets),
/// suspending the progress bar.
pub fn ok_label(bar: &ProgressBar, quiet: bool, rel: &str, label: &str, dest: &Path) {
if quiet {
return;
}
let msg = format!(
"{} {:?} {} -> {}",
"✓".green(),
kind,
rel.display(),
dest.display()
);
let msg = format!("{} {} {} -> {}", "✓".green(), label, rel, dest.display());
bar.suspend(|| println!("{msg}"));
}
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-metadata/src/android/embedded.rs
+137
View File
@@ -0,0 +1,137 @@
//! Extraction of the embedded-metadata packaging variant.
//!
//! Some protected il2cpp builds ship no `global-metadata.dat` in the app's
//! assets at all. Instead a slim metadata blob (an older header format with
//! custom record layouts) is embedded in the protected library's data section
//! and wrapped in a per-word XOR layer: a 0x100-byte header whose 64 words each
//! carry their own key, followed by exactly 256 segments with one u32 key each
//! at irregular boundaries. At runtime the protector's il2cpp-side modules
//! regenerate the keys and unwrap the blob in place; the keys are stored
//! nowhere in the image.
//!
//! For the one observed build using this variant the full keystream was
//! recovered from a ciphertext/plaintext pair and is embedded in
//! [`crate::keystream`]. Extraction is therefore content-gated: the wrapped
//! header's first plaintext words are known constants, so a restored image that
//! does not contain them (every other build) is skipped cheaply and nothing is
//! written.
//!
//! The unwrapped blob stores its patched sanity/version fields byte-swapped;
//! they are rewritten to the standard il2cpp metadata magic and version so the
//! output is a well-formed `global-metadata.dat`.
use super::keystream::{HEADER_KEYS, SEGMENTS};
/// Standard il2cpp metadata sanity magic written over the patched header.
const STANDARD_MAGIC: u32 = 0xfab1_1baf;
/// Standard header version matching the blob's record layout.
const STANDARD_VERSION: u32 = 24;
/// Plaintext of the first two wrapped header words (the byte-swapped patched
/// sanity/version pair). Also the probe pattern: a restored image contains the
/// embedded blob iff `word[0] ^ HEADER_KEYS[0]` and `word[1] ^ HEADER_KEYS[1]`
/// equal these constants at some 4-aligned offset.
const PROBE_WORDS: [u32; 2] = [0x9732_ca38, 0xbac4_374f];
/// Size of the wrapped blob: the last segment's end offset.
pub fn embedded_metadata_size() -> usize {
SEGMENTS[SEGMENTS.len() - 1].0 as usize
}
/// Locate and unwrap the embedded metadata blob in a restored library image.
///
/// Returns a standalone, well-formed `global-metadata.dat`, or `None` when the
/// image carries no blob wrapped with the known keystream.
pub fn extract_embedded_metadata(image: &[u8]) -> Option<Vec<u8>> {
let total = embedded_metadata_size();
let offset = find_wrapped_header(image)?;
let blob = image.get(offset..offset.checked_add(total)?)?;
let mut out = blob.to_vec();
for (i, &key) in HEADER_KEYS.iter().enumerate() {
xor_word(&mut out, 4 * i, key);
}
let mut pos = 0x100_usize;
for &(end, key) in &SEGMENTS {
let end = end as usize;
let mut o = pos;
while o + 4 <= end {
xor_word(&mut out, o, key);
o += 4;
}
pos = end;
}
out[0..4].copy_from_slice(&STANDARD_MAGIC.to_le_bytes());
out[4..8].copy_from_slice(&STANDARD_VERSION.to_le_bytes());
Some(out)
}
/// Scan `image` for the wrapped header probe pattern (4-aligned).
fn find_wrapped_header(image: &[u8]) -> Option<usize> {
let mut off = 0;
while off + 8 <= image.len() {
let word = u32::from_le_bytes(image[off..off + 4].try_into().ok()?);
if word ^ HEADER_KEYS[0] == PROBE_WORDS[0] {
let next = u32::from_le_bytes(image[off + 4..off + 8].try_into().ok()?);
if next ^ HEADER_KEYS[1] == PROBE_WORDS[1] {
return Some(off);
}
}
off += 4;
}
None
}
fn xor_word(data: &mut [u8], offset: usize, key: u32) {
let word = u32::from_le_bytes(data[offset..offset + 4].try_into().expect("word in bounds"));
data[offset..offset + 4].copy_from_slice(&(word ^ key).to_le_bytes());
}
#[cfg(test)]
mod tests {
use super::*;
/// Wrap a synthetic blob with the keystream, then unwrap it back.
#[test]
fn roundtrip_wrapped_blob() {
let total = embedded_metadata_size();
let mut image = vec![0_u8; total + 0x40];
// Plaintext blob: standard probe words, then a ramp.
image[0..4].copy_from_slice(&PROBE_WORDS[0].to_le_bytes());
image[4..8].copy_from_slice(&PROBE_WORDS[1].to_le_bytes());
for o in (8..total).step_by(4) {
let v = (o as u32).wrapping_mul(0x9e37_79b1);
image[o..o + 4].copy_from_slice(&v.to_le_bytes());
}
// Wrap with the keystream.
for (i, &key) in HEADER_KEYS.iter().enumerate() {
xor_word(&mut image, 4 * i, key);
}
let mut pos = 0x100_usize;
for &(end, key) in &SEGMENTS {
let mut o = pos;
while o + 4 <= end as usize {
xor_word(&mut image, o, key);
o += 4;
}
pos = end as usize;
}
let out = extract_embedded_metadata(&image).expect("blob found");
assert_eq!(out.len(), total);
// Header rewritten to the standard magic/version…
assert_eq!(&out[0..4], &STANDARD_MAGIC.to_le_bytes());
assert_eq!(&out[4..8], &STANDARD_VERSION.to_le_bytes());
// …and the body round-trips.
for o in (8..total).step_by(4) {
let v = (o as u32).wrapping_mul(0x9e37_79b1);
assert_eq!(&out[o..o + 4], &v.to_le_bytes(), "word at {o:#x}");
}
}
#[test]
fn no_blob_in_plain_data() {
let image = vec![0xAB_u8; 0x1000];
assert!(extract_embedded_metadata(&image).is_none());
}
}
senbei-metadata/src/android/keystream.rs
+274
View File
@@ -0,0 +1,274 @@
/// Per-word XOR keystream for the embedded-metadata packaging variant,
/// recovered from a ciphertext/plaintext pair of one observed build.
/// Key derivation for future builds is untraced; other builds simply do
/// not match the header probe and are left untouched.
pub(crate) const HEADER_KEYS: [u32; 64] = [
0x39184c70, 0xd901afd4, 0x19b98815, 0x132906ed, 0x663e8ace, 0x299b1952, 0xe5404ab8, 0xd93b331c,
0xb67d3761, 0x42da9259, 0xc29c7a59, 0x17cb841c, 0xd0bcb9c6, 0x21db779b, 0x43874deb, 0x89bf697b,
0x0b7f97b4, 0xbe1c59f7, 0xc653ad92, 0x8cdf4336, 0x5e0b6b68, 0x1bd4d668, 0x7250ed61, 0x31a36491,
0xaf144dcd, 0xc1e387d0, 0x9d6df5b7, 0x78514f32, 0xc2648cbf, 0x3b8272a5, 0xd2053679, 0x4b18af77,
0x71b9ebdd, 0x0094daaa, 0xf3adfed8, 0xc0d082bc, 0xae5e523c, 0xa8dec0be, 0x090a7784, 0x2c0483d6,
0x95f0e8f7, 0x234de6d4, 0xa7464527, 0x3b1c531d, 0xc2b31d82, 0xe1c60be0, 0x3d65a0c2, 0x2ea7d77a,
0x4ababadb, 0xce484b16, 0x59ab3f99, 0x10a9a463, 0x70e2f78a, 0x0ed71c9c, 0xf8996b2e, 0xff637928,
0xf413313d, 0x77c57bf9, 0xdab41dba, 0x0cd2ccbc, 0x3b2fbde3, 0x0b19b14d, 0xd2645dbc, 0x318113d4,
];
/// (segment end offset, segment key) pairs; offsets relative to blob start.
pub(crate) const SEGMENTS: [(u32, u32); 256] = [
(0x3915c, 0xbb5dda1a),
(0x736b4, 0x906dbe0f),
(0xaedc4, 0x1e4ca8bd),
(0xc506c, 0xe603cb21),
(0xdfe34, 0x93bec702),
(0xe8f10, 0x9a9f429f),
(0x139088, 0x125a8b3f),
(0x20bd30, 0x69a6395f),
(0x20c548, 0xca807b9a),
(0x20c774, 0x8b8880c4),
(0x300518, 0x48087852),
(0x36c07c, 0x32aa7b5b),
(0x448b7c, 0x2e668589),
(0x4592b0, 0x292e07d9),
(0x45d374, 0x83b0a0ef),
(0x474520, 0x8983245d),
(0x47a1d4, 0xefb941b7),
(0x4bdc74, 0x7c3b3458),
(0x4c34c8, 0xee0a87b3),
(0x4f1068, 0xf6a2069f),
(0x51601c, 0x2e83612b),
(0x549d40, 0xb413a58f),
(0x56a714, 0x95596da3),
(0x573c98, 0x68513e8d),
(0x59d058, 0xc4ff5f9a),
(0x5c4b34, 0x249ed022),
(0x5f19bc, 0xc27272d3),
(0x5f47c8, 0xd73aa37b),
(0x627df4, 0x002334ba),
(0x648f54, 0x868bb6c9),
(0x6718a4, 0x17ff0ef4),
(0x6a88b8, 0x22cfbc5f),
(0x742dbc, 0x152072dd),
(0x75603c, 0xbd31be45),
(0x783238, 0x45911d6a),
(0x7b94d8, 0x6f281add),
(0x800060, 0xcf58c8d0),
(0x819b50, 0xb40f0276),
(0x82dea4, 0x1a1a8402),
(0x880210, 0xf2c0824a),
(0x8e4f08, 0x86c9ba90),
(0x8ea544, 0x0e928544),
(0x931454, 0xc3fa017b),
(0x94eb70, 0x1dbe612a),
(0x95993c, 0x902498fe),
(0x98d2b0, 0xb7760451),
(0x992034, 0x711cddfc),
(0x9e14a0, 0x8bd95e64),
(0xa1d2d0, 0xbfdce920),
(0xa21ed8, 0x90cf0372),
(0xa4d2b8, 0x91e88c9c),
(0xa76f8c, 0x9c721e61),
(0xac5ba4, 0xbda16e3e),
(0xaf070c, 0xe02b6799),
(0xaf3a78, 0x32953b4e),
(0xb32510, 0x47ea48db),
(0xb46550, 0x1443e512),
(0xb54998, 0x9e123a75),
(0xb5e24c, 0xe11a8efd),
(0xb625cc, 0x3facfbf4),
(0xb66ec8, 0x76c0c452),
(0xb67ad0, 0x4de4ed6c),
(0xb7ba5c, 0xe622d97a),
(0xb85a90, 0x6f564f8b),
(0xbff8b8, 0x3e25d671),
(0xc03e50, 0x3563fc2b),
(0xc6e958, 0xda8bc3b0),
(0xc87f7c, 0x5a9d2269),
(0xcb36a4, 0x0ab420cc),
(0xcbe4d0, 0x9bbb091e),
(0xccd7dc, 0x9e4fd577),
(0xd078c0, 0x4b655ae1),
(0xd275dc, 0x5ca2a2f4),
(0xd2c840, 0xdb437f0d),
(0xd3296c, 0x66487f75),
(0xd7cbe8, 0xf5427945),
(0xd8e0a0, 0x9a65bdb6),
(0xda2ed4, 0x46dea4b3),
(0xda6f1c, 0xb9916a02),
(0xdee9ac, 0x18800a5c),
(0xe3673c, 0x4afab3cd),
(0xe65420, 0x52e80204),
(0xe861f8, 0x639a02d7),
(0xeb61c0, 0x21077eba),
(0xed51dc, 0x17be91d8),
(0xf048a4, 0xd30cc8cb),
(0xf3b274, 0xdfb43f3f),
(0xf76ac8, 0x63a8b363),
(0xf84b64, 0x16508a16),
(0xf8bb2c, 0x22ce110d),
(0xfb3390, 0xf09a4eb2),
(0xff07bc, 0xd2bb0e2c),
(0x102d32c, 0xb424012c),
(0x10795b0, 0x07338bb9),
(0x108d65c, 0x5d68f86e),
(0x10ce528, 0x1826c952),
(0x10d3528, 0xa7473860),
(0x10dca58, 0x92435967),
(0x1115c78, 0x061200f4),
(0x1171098, 0x94f538a1),
(0x117ebf0, 0xd8731d88),
(0x1186638, 0x4381b3f9),
(0x118afdc, 0xf25ff376),
(0x11ee3b4, 0x29605488),
(0x11f182c, 0x04367932),
(0x11f41dc, 0xaeaccadd),
(0x11ff0f4, 0x7c4d358e),
(0x120caac, 0xacbc8412),
(0x12437cc, 0x3e0ac7e9),
(0x124edf8, 0x06f523fd),
(0x1263ba0, 0x0a1b9763),
(0x12943f0, 0x24a86ba4),
(0x12d9230, 0x0cd82e2e),
(0x12fd9b4, 0xf3903fb9),
(0x135a198, 0x2887f4a3),
(0x1366180, 0x9f0d7ca5),
(0x13680a4, 0x61e9a459),
(0x13a1b44, 0xe61623a4),
(0x13a860c, 0xdc44c798),
(0x13c024c, 0xc90f7be6),
(0x1475c00, 0xc2f338b3),
(0x1480aa8, 0xb7b0609e),
(0x14fb82c, 0x748e3939),
(0x1511184, 0x98426fcf),
(0x153c144, 0x1a452d5d),
(0x1547838, 0x7dd360e9),
(0x15565d4, 0x1d8f093b),
(0x156e298, 0x102a1524),
(0x159df70, 0xe42613f7),
(0x15a13d0, 0xafc5fdc6),
(0x15e7f24, 0x84fcd342),
(0x15f0878, 0x55038958),
(0x1614210, 0xe0602ae4),
(0x1631b3c, 0xce2765f6),
(0x164eb70, 0xf772dac5),
(0x1688b68, 0x5f1a72c9),
(0x16d5f8c, 0x7c77747d),
(0x16e76dc, 0xac0e16fb),
(0x1726374, 0x4a1e7fd7),
(0x173455c, 0x870856b4),
(0x17697d8, 0xbb2f0a5c),
(0x176ed60, 0xc937b386),
(0x1784fa8, 0x5e676ab2),
(0x17ae3a0, 0xdbf662a1),
(0x1866c7c, 0x4e3f1a7d),
(0x186b844, 0xe30fce60),
(0x18b507c, 0xdfc73c88),
(0x18c2f64, 0xb7ee08e0),
(0x18c8010, 0xd1471a25),
(0x18de290, 0x292e6310),
(0x19140d0, 0x9f346f05),
(0x192c590, 0xf1eb61bf),
(0x194fca0, 0x8888b1df),
(0x1959d34, 0x92b89d15),
(0x196c0c4, 0x5e152de5),
(0x19a5710, 0x866e7bfa),
(0x19abfd4, 0x3084ae26),
(0x19b1550, 0x0581836f),
(0x19b7214, 0xeefc34eb),
(0x19c523c, 0xc980335d),
(0x19dc4c0, 0x019084e6),
(0x19dfb8c, 0xdb1a21a7),
(0x19fbf3c, 0xec84cc17),
(0x1a29b18, 0xcb31da7d),
(0x1a4c670, 0xc5fe570e),
(0x1a97024, 0xbbd80964),
(0x1ac33bc, 0xe186586d),
(0x1acd124, 0x1e413252),
(0x1ad9bac, 0x48fc4c75),
(0x1b1b728, 0x8071d7a5),
(0x1b31d78, 0x9d958013),
(0x1badb24, 0x2f236951),
(0x1bccc00, 0x7023c620),
(0x1bdab2c, 0x88b1e4b8),
(0x1c000dc, 0x9e43291a),
(0x1c9f0cc, 0x27a7d592),
(0x1cd1328, 0x9c0bcc88),
(0x1cd79a0, 0x63e0ed75),
(0x1d0e484, 0xf51a0d3d),
(0x1d17b10, 0xbfd2a7ac),
(0x1d930c4, 0xf6b9e877),
(0x1db115c, 0xf3eb7e37),
(0x1df16b4, 0x682326ff),
(0x1e389c0, 0xea11f566),
(0x1eb7e48, 0x3dc5fa76),
(0x1ec38fc, 0x296ffc1d),
(0x1ee87a0, 0x1b9f7fd4),
(0x1f19f88, 0x78972e8f),
(0x1f33a0c, 0x390c2deb),
(0x1f4e0fc, 0xe05e8c6b),
(0x1f5a718, 0x367432ae),
(0x1f61dcc, 0x7063e58a),
(0x1f85878, 0x21c00cea),
(0x1fc043c, 0x2676aaaa),
(0x1ffdb94, 0xc270eb02),
(0x202a618, 0x3a98aed2),
(0x2037b34, 0x115d5afc),
(0x203d92c, 0x11bced76),
(0x203da14, 0xf2628105),
(0x2066014, 0x97f32700),
(0x208a908, 0xa68e2f71),
(0x20ab8ac, 0x1daa2a78),
(0x20ba504, 0x73919ef6),
(0x20e71e0, 0x0b3fd1d3),
(0x2102278, 0x6c123def),
(0x21166dc, 0xee354161),
(0x2126478, 0x299493f4),
(0x2137090, 0x05ae2007),
(0x2148270, 0x34b52663),
(0x21482ac, 0xe381b5b6),
(0x21813b8, 0x94244de1),
(0x21a41e8, 0x02c38df5),
(0x21a8c4c, 0xf72700dd),
(0x21abbac, 0x34c2e7b5),
(0x21bcb24, 0x442739ad),
(0x21cbe84, 0x6e40d22c),
(0x21e2798, 0xdbf774d0),
(0x21f892c, 0xe90f1e0c),
(0x222beec, 0xa27f27f3),
(0x22394f4, 0x7f999a4f),
(0x22437ec, 0xf12d28f8),
(0x22480b0, 0xf58f3a7d),
(0x2261a0c, 0x89b28301),
(0x22a76c8, 0x1fe501e2),
(0x22b2018, 0xf079db5f),
(0x22cc610, 0xaf7d17b7),
(0x22cd4f8, 0x71c010cb),
(0x22d016c, 0x4a8daed0),
(0x22e1c04, 0xe1201aca),
(0x22f9994, 0xf3f0e4ee),
(0x2384f5c, 0x6b8a5eb1),
(0x23d5ecc, 0x5298a9c4),
(0x23e15b0, 0xc7bf0afb),
(0x23e248c, 0x2d67fecf),
(0x2407898, 0x4eef422a),
(0x241695c, 0x33ba9ce8),
(0x243e8b0, 0x833c1d2c),
(0x2460b64, 0x819c96ee),
(0x247caec, 0x0ebccbd6),
(0x24832b4, 0xf789d4b6),
(0x24938b8, 0x9f63baeb),
(0x24a7c64, 0x3384e552),
(0x24bce94, 0x7bfec208),
(0x24bd8f4, 0x9b5260cc),
(0x24ce8ec, 0xaf854888),
(0x24e741c, 0xda82f062),
(0x254401c, 0xbb1a5d5a),
(0x25a6a64, 0x24d202d3),
(0x2617878, 0x6ac71e5f),
(0x2617df0, 0x0e76bd90),
(0x268e9b8, 0x874d931c),
(0x26a8848, 0xefefd680),
(0x26e4f10, 0xfc2799f7),
(0x26e93d8, 0x1930ad55),
(0x26eea84, 0xfa2f742f),
(0x2701f30, 0xed9b92c4),
];
senbei-metadata/src/android/method_tokens.rs
+1251
View File
File diff suppressed because it is too large Load Diff
senbei-metadata/src/android/mod.rs
+11
View File
@@ -0,0 +1,11 @@
//! Static IL2CPP metadata restoration interfaces.
mod embedded;
mod keystream;
mod method_tokens;
pub use embedded::{embedded_metadata_size, extract_embedded_metadata};
pub use method_tokens::{
DEFAULT_METHOD_TOKEN_SEED, Error, ImageKeyDiscovery, Report, SeedDiscoveryReport,
discover_method_token_seeds, restore_method_tokens,
};
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
+416 -8
View File
@@ -2,12 +2,38 @@
# It is not intended for manual editing.
version = 4
[[package]]
name = "aes"
version = "0.9.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "35f0f96ce78e38c3dc6d8948aa8163d06385be74000f3c7a95bf1eef35d3ea32"
dependencies = [
"cipher",
"cpubits",
"cpufeatures",
]
[[package]]
name = "anyhow"
version = "1.0.104"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
[[package]]
name = "bitflags"
version = "2.13.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
[[package]]
name = "block-buffer"
version = "0.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d2f6c7dbe95a6ed67ad9f18e57daf93a2f034c524b99fd2b76d18fdfeb6660aa"
dependencies = [
"hybrid-array",
]
[[package]]
name = "bumpalo"
version = "3.20.3"
@@ -20,6 +46,16 @@ version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
[[package]]
name = "cipher"
version = "0.5.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e8cf2a2c93cd704877c0858356ed03480ff301ee950b43f1cbe4573b088bfa6c"
dependencies = [
"crypto-common",
"inout",
]
[[package]]
name = "console"
version = "0.16.4"
@@ -42,12 +78,93 @@ dependencies = [
"wasm-bindgen",
]
[[package]]
name = "const-oid"
version = "0.10.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a6ef517f0926dd24a1582492c791b6a4818a4d94e789a334894aa15b0d12f55c"
[[package]]
name = "cpubits"
version = "0.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "15b85f9c39137c3a891689859392b1bd49812121d0d61c9caf00d46ed5ce06ae"
[[package]]
name = "cpufeatures"
version = "0.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566"
dependencies = [
"libc",
]
[[package]]
name = "crc32fast"
version = "1.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8498c871161e1742aaa9d52551b2d6ebdd4c3d45a3be423e3728f33b955be550"
dependencies = [
"cfg-if",
]
[[package]]
name = "crypto-common"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453"
dependencies = [
"hybrid-array",
]
[[package]]
name = "digest"
version = "0.11.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2"
dependencies = [
"block-buffer",
"const-oid",
"crypto-common",
]
[[package]]
name = "encode_unicode"
version = "1.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "34aa73646ffb006b8f5147f3dc182bd4bcb190227ce861fc4a4844bf8e3cb2c0"
[[package]]
name = "equivalent"
version = "1.0.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
[[package]]
name = "errno"
version = "0.3.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
dependencies = [
"libc",
"windows-sys",
]
[[package]]
name = "fastrand"
version = "2.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
[[package]]
name = "flate2"
version = "1.1.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
dependencies = [
"zlib-rs",
]
[[package]]
name = "futures-core"
version = "0.3.34"
@@ -72,6 +189,53 @@ dependencies = [
"slab",
]
[[package]]
name = "getrandom"
version = "0.4.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
dependencies = [
"cfg-if",
"libc",
"r-efi",
]
[[package]]
name = "goblin"
version = "0.10.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "17582616a7718cca54cec18e534a76c7c4aec11a8b9a85695712f262fd15a4c8"
dependencies = [
"log",
"plain",
"scroll",
]
[[package]]
name = "hashbrown"
version = "0.17.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
[[package]]
name = "hybrid-array"
version = "0.4.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "707114b52a152fa7bdb290cd7cd5912d9467273b6d74e21b8d81aca1f8533f6b"
dependencies = [
"typenum",
]
[[package]]
name = "indexmap"
version = "2.14.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "07aa2048142242915a31d35844fb311e0e53fcca590c3a0a40dcf1b841fa09eb"
dependencies = [
"equivalent",
"hashbrown",
]
[[package]]
name = "indicatif"
version = "0.18.6"
@@ -85,6 +249,21 @@ dependencies = [
"web-time",
]
[[package]]
name = "inout"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4250ce6452e92010fdf7268ccc5d14faa80bb12fc741938534c58f16804e03c7"
dependencies = [
"hybrid-array",
]
[[package]]
name = "itoa"
version = "1.0.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
[[package]]
name = "js-sys"
version = "0.3.104"
@@ -102,6 +281,33 @@ version = "0.2.189"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
[[package]]
name = "linux-raw-sys"
version = "0.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
[[package]]
name = "log"
version = "0.4.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
[[package]]
name = "memchr"
version = "2.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
[[package]]
name = "memmap2"
version = "0.9.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d1219ed1b7f229ee7104d281dd01d6802fe28bb6e95d292942c4daacdeb798c0"
dependencies = [
"libc",
]
[[package]]
name = "once_cell"
version = "1.21.4"
@@ -120,6 +326,12 @@ version = "0.2.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
[[package]]
name = "plain"
version = "0.2.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b4596b6d070b27117e987119b4dac604f3c58cfb0b191112e24771b2faeac1a6"
[[package]]
name = "portable-atomic"
version = "1.15.0"
@@ -144,6 +356,25 @@ dependencies = [
"proc-macro2",
]
[[package]]
name = "r-efi"
version = "6.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
[[package]]
name = "rustix"
version = "1.1.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
dependencies = [
"bitflags",
"errno",
"libc",
"linux-raw-sys",
"windows-sys",
]
[[package]]
name = "rustversion"
version = "1.0.23"
@@ -160,49 +391,163 @@ dependencies = [
]
[[package]]
name = "senbei-crypto"
version = "1.1.0"
name = "scroll"
version = "0.13.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c1257cd4248b4132760d6524d6dda4e053bc648c9070b960929bf50cfb1e7add"
dependencies = [
"scroll_derive",
]
[[package]]
name = "scroll_derive"
version = "0.13.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e1a36a382ed65dbcc0ab47fd5e9a94112417ccd34560a392ef3b7b0f0ec39148"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.4",
]
[[package]]
name = "senbei-crypto"
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.1.0"
version = "1.3.1"
dependencies = [
"anyhow",
"indicatif",
"libc",
"memmap2",
"owo-colors",
"senbei-crypto",
"senbei-elf",
"senbei-engine",
"senbei-metadata",
"senbei-pe",
"sha2",
"tempfile",
"walkdir",
"windows",
"zip",
]
[[package]]
name = "senbei-metadata"
version = "1.1.0"
version = "1.3.1"
dependencies = [
"serde",
"thiserror",
]
[[package]]
name = "senbei-pe"
version = "1.1.0"
version = "1.3.1"
dependencies = [
"senbei-crypto",
"thiserror",
]
[[package]]
name = "senbei-wasm"
version = "1.1.0"
version = "1.3.1"
dependencies = [
"console_error_panic_hook",
"senbei-engine",
"senbei-io",
"senbei-metadata",
"senbei-pe",
"wasm-bindgen",
]
[[package]]
name = "serde"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
dependencies = [
"serde_core",
"serde_derive",
]
[[package]]
name = "serde_core"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
dependencies = [
"serde_derive",
]
[[package]]
name = "serde_derive"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.4",
]
[[package]]
name = "serde_json"
version = "1.0.151"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
dependencies = [
"itoa",
"memchr",
"serde",
"serde_core",
"zmij",
]
[[package]]
name = "sha2"
version = "0.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "446ba717509524cb3f22f17ecc096f10f4822d76ab5c0b9822c5f9c284e825f4"
dependencies = [
"cfg-if",
"cpufeatures",
"digest",
]
[[package]]
name = "simd-adler32"
version = "0.3.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
[[package]]
name = "slab"
version = "0.4.12"
@@ -231,6 +576,19 @@ dependencies = [
"unicode-ident",
]
[[package]]
name = "tempfile"
version = "3.27.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
dependencies = [
"fastrand",
"getrandom",
"once_cell",
"rustix",
"windows-sys",
]
[[package]]
name = "thiserror"
version = "2.0.20"
@@ -251,6 +609,18 @@ dependencies = [
"syn 3.0.4",
]
[[package]]
name = "typed-path"
version = "0.12.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8e28f89b80c87b8fb0cf04ab448d5dd0dd0ade2f8891bae878de66a75a28600e"
[[package]]
name = "typenum"
version = "1.20.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
[[package]]
name = "unicode-ident"
version = "1.0.24"
@@ -461,3 +831,41 @@ checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37"
dependencies = [
"windows-link",
]
[[package]]
name = "zip"
version = "8.6.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2d04a6b5381502aa6087c94c669499eb1602eb9c5e8198e534de571f7154809b"
dependencies = [
"crc32fast",
"flate2",
"indexmap",
"memchr",
"typed-path",
"zopfli",
]
[[package]]
name = "zlib-rs"
version = "0.6.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "34b31d188d9d685a4f9c7b46d6e36631b07058d2cfe190267adce54dc230bf12"
[[package]]
name = "zmij"
version = "1.0.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
[[package]]
name = "zopfli"
version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f05cd8797d63865425ff89b5c4a48804f35ba0ce8d125800027ad6017d2b5249"
dependencies = [
"bumpalo",
"crc32fast",
"log",
"simd-adler32",
]
senbei-wasm/Cargo.toml
+3 -2
View File
@@ -1,7 +1,8 @@
[package]
name = "senbei-wasm"
version = "1.1.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 {