diff --git a/AGENTS.md b/AGENTS.md index 5b675e1..10ef1b8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ Guidance for contributors working in this repository. 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. +Read the [Senbei design notes](https://xn--ri8h.gitbook.io/crackproof-research/senbei) before changing architecture or pipeline boundaries. ## Commands @@ -37,4 +37,4 @@ The format crates and PE engine remain free of filesystem I/O. Native Android ex ## Documentation -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. +Use one line for each normal Markdown paragraph. Keep code blocks, table rows, and list items structurally separate. Product documentation lives at ; update that site (not this repository) when CLI behavior changes. diff --git a/README.md b/README.md index 11d1ee7..457b4df 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,10 @@ # Senbei -A static unpacker for Crackproof-protected 64-bit and 32-bit PE files and protected Android AArch64 shared libraries. Point it at a file, an app package, or a folder and it writes decrypted copies without launching the protected program. +A static unpacker for CrackProof-protected Windows PE files and Android AArch64 shared libraries. -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. +> _"Crackproof"? It's senbei (煎餅 — rice cracker). Cracks itself._ -## Crates - -The workspace contains eight crates: `senbei-cli`, `senbei-crypto`, `senbei-io`, `senbei-metadata`, `senbei-pe`, `senbei-elf`, `senbei-engine`, and `senbei-wasm`. - -`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/`. - -## Supported Inputs - -- Protected Windows `.exe` and `.dll` files, including external `.exe._` and `.dll._` payloads. -- `global-metadata.dat` files with supported method-token layouts. -- Protected Android `.so` files and Android `.apk`, `.apks`, and `.xapk` packages. - -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. - -## Quick Start +## Usage ```cmd cargo build --release @@ -27,30 +13,20 @@ senbei game.apk senbei "C:\Games\MyGame" ``` -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. +Outputs are written below an `unpack` directory unless `--out` is supplied. -## Tests +Full documentation: -```cmd -cargo test --release --workspace -cargo clippy --workspace --all-targets -- -D warnings -cargo fmt --all -- --check -``` +## Legal notice and intended use -The local `test/` corpus can be passed to the CLI for real sample verification. The tracked `samples/` corpus is optional and remains user-managed. +**Read this before using Senbei.** -## 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. +- Senbei is a research and interoperability tool. It exists to enable lawful reverse engineering, security research, preservation, and interoperability with software you already legitimately possess. +- **Only process binaries you own or are explicitly authorized to analyze.** Depending on your jurisdiction and license agreements, circumventing technological protection measures may be restricted (for example under DMCA §1201 in the United States, which contains exemptions for security research and interoperability). It is your responsibility to ensure your use is lawful. +- Senbei does not bypass any access control for you: it performs a purely static transformation of a file already on your disk. It derives everything it needs from the input file itself, contains no vendor code, and distributes no cracks or copyrighted content. (One Android packaging variant's embedded metadata layer is unwrapped with an XOR keystream recovered from a ciphertext/plaintext pair during analysis of a single build; that keystream is research output shipped with the unpacker, not a vendor-distributed key, and builds it doesn't match are left alone.) +- Senbei does not enable online play, license fraud, or cheating, and must not be used to redistribute decrypted binaries. Do not upload outputs anywhere. +- The authors provide this software "as is", without warranty of any kind, and accept no liability for misuse. See [LICENSE](LICENSE) (AGPL-3.0). +- "Crackproof" is a trademark of its respective owner; this project is not affiliated with or endorsed by the protection vendor or any software publisher. Names are used for identification only. ## License diff --git a/docs/design.md b/docs/design.md deleted file mode 100644 index 60235ce..0000000 --- a/docs/design.md +++ /dev/null @@ -1,59 +0,0 @@ -# Design - -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 - -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. - -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/`. - -```text -senbei-cli/src/main.rs -senbei-crypto/src/ -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/ -``` - -`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. - -## Windows Engine - -`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. - -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. - -## Android Engine - -`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. - -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. - -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. - -## Scanning and Packages - -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. - -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. - -## Validation - -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. - -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. - -## WebAssembly - -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. diff --git a/docs/development.md b/docs/development.md deleted file mode 100644 index 8b7d277..0000000 --- a/docs/development.md +++ /dev/null @@ -1,61 +0,0 @@ -# Development - -## Building - -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. - -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 --workspace -cargo clippy --workspace --all-targets -- -D warnings -cargo fmt --all -- --check -``` - -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. - -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. - -## Environment Variables - -- `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 - -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/`. - -Layout heuristics must trial and validate every candidate. A failed validation is an error or a fall-through, never a silently accepted offset. - -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 - -```cmd -cd senbei-wasm -wasm-pack build --target web --release --out-dir ../web/pkg -``` - -Serve `web/` with a static HTTP server after the build. The browser never uploads input files. diff --git a/docs/usage.md b/docs/usage.md deleted file mode 100644 index f862af3..0000000 --- a/docs/usage.md +++ /dev/null @@ -1,57 +0,0 @@ -# Usage - -```text -senbei [--out DIR] [-v|--verbose] [-q|--quiet]... [--scan-all] [--no-log] [--no-pause] [-V|--version] [-h|--help] -``` - -## Single File - -The output is written below `/unpack/` with `.unpack` inserted before the extension. `--out DIR` changes both the output and log directory. - -```cmd -senbei app.exe -senbei app.exe --out C:\out -``` - -For `global-metadata.dat`, Senbei writes `global-metadata.unpack.dat` only when method tokens change. Unsupported metadata versions remain untouched and are reported as skipped. - -## Android Targets - -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. - -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 - -Folder mode walks recursively, skips directories named `unpack`, and mirrors recognized outputs below `/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. - -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. - -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. - -## Integrity Check - -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. - -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 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. | - -## Exit Codes - -| Code | Meaning | -| --- | --- | -| `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. |