Terminal 1.0: a-Shell 2.3.2 full + worse_query + native plugin environment

2026-11-09 22:51:39 +08:00
commit 598ef7b1bf
@@ -0,0 +1,152 @@
+# terminal_worse
+
+A fork of **a-Shell 2.3.2 (full)** with the **worse_query** sandbox escape,
+a native terminal plugin environment, and a small set of UX additions.
+
+Built and tested on **iPhone 18 Pro Max, iOS 27.0.1 (24A446)**, signed with a
+development provisioning profile.  Bundle ID: `com.apple.Terminal`.
+
+> This is a personal security-research project.  The repository does NOT
+> contain the decrypted a-Shell IPA (it must be supplied locally) and does NOT
+> contain the signing certificate or provisioning profile.
+
+## Features
+
+- Full a-Shell 2.3.2 app: Python, Perl, TeX, clang/LLVM, SSH, vim, etc.
+- `worse_query` app-group sandbox escape covering every path documented by
+  the upstream project:
+  - `/var/containers/Data/System`
+  - `/var/containers/Shared/SystemGroup/*`
+  - `/var/mobile/Containers/Data/Application/*`
+  - `/var/mobile/Containers/Data/InternalDaemon/*`
+  - `/var/mobile/Containers/Data/PluginKitPlugin/*`
+  - `/var/mobile/Containers/Shared/AppGroup/*`
+  - `/var/mobile/Containers/Shared/AppGroup`
+- Launch-time blocking progress UI, then auto-mount under
+  `~/Documents/_sandbox/` and run `cd _sandbox; ls`.
+- App containers are exposed by bundle ID, with `Documents/ Library/ tmp/
+  SystemData/ StoreKit/` and a `_data` link to the full container root.
+- `keep_content` is forced off: every launch starts a fresh terminal and does
+  not restore the previous command history.
+- BadShell command set preserved.  `badshell` is renamed to **`sbxhelp`**.
+- Built-in **`neofetch`** with live device data (OS/build, model, kernel,
+  uptime, resolution, CPU/GPU, memory, disk, battery, thermal, locale,
+  timezone, IP).  It uses neofetch's compact Apple ASCII art, not a bash
+  script.
+- Terminal-style app icon (generated by `icon/make_icon.py`).
+
+## Shell commands
+
+```
+sbxhelp                     help / mount overview
+sbx_status [-v]             app group, mount state, active handles
+sbx_remount                 re-run the full auto-mount
+sbx_grant [-c] <path>       consume a sandbox extension
+sbx_release <handle|path|all>
+sbx_ls <path>
+sbx_cat <file>
+sbx_cp <src> <dst>
+sbx_write [-a] <file> <text...>
+sbx_rm [-r] <path>
+sbx_hexdump [-n N] <file>
+sbx_containers [root]
+sbx_id <container>
+sbx_sysgroups [filter]
+sbx_probe
+sbx_paths
+bswelcome
+neofetch
+```
+
+## Native plugin environment
+
+`termenv` creates an independent prefix at `~/Documents/.terminal` and
+provides a native `apt`/`dpkg` compatible package front-end for
+Terminal-compatible `.deb` files (scripts or iOS/Darwin arm64 payloads).
+
+```sh
+termenv init
+source ~/Documents/.terminal/etc/profile     # or: termenv on
+apt update
+apt install <package>
+dpkg -i <file.deb>
+dpkg -l
+mkdeb <name> <version> <payload-dir> [arch]
+plugin-run <command> [args...]
+```
+
+Default sources:
+
+```
+deb [trusted=yes] file://$PREFIX/repo ./
+deb [trusted=yes] https://repo.procurs.us/ ./
+deb [trusted=yes] https://repo.havoc.app/ ./
+```
+
+`apt update` downloads `Packages.xz`/`.gz`/plain indexes.  Procursus/Havoc
+indexes may be unreachable from some networks; the local source still works.
+
+### Important limitations
+
+- **Native Mach-O CLI binaries from Procursus/Havoc cannot run in a-Shell.**
+  `ios_system`'s `isRealCommand` deliberately rejects Mach-O files, and a
+  non-jailbroken app cannot execute unsigned external executables.  Script
+  plugins (`#!/bin/sh`, python, perl, lua) and WebAssembly plugins can run;
+  use `plugin-run` for a clear diagnostic.  Native binaries require a
+  jailbreak or a Linux/emulator environment.
+- `bash` is a **sh-compatibility launcher**, not GNU bash.  `bash -c` and
+  simple scripts work; bash-specific arrays/`[[` do not.
+- The Python package backend (`pkgtool`) is used when available.  The
+  package-install path is still being polished; `apt update`, package
+  download, extraction, `dpkg -l` and the local `hello` sample are the
+  current test targets.
+- `apt` does not verify GPG signatures; sources are `[trusted=yes]`.
+
+## Repository layout
+
+```
+src/TerminalSBX.m        injected dylib: worse_query, UI, commands, neofetch
+env/                     native plugin environment commands
+icon/                    icon generator + compiled Assets.car
+scripts/                 entitlements, signing/build helpers
+```
+
+## Building
+
+Requirements: macOS + Xcode 27, the decrypted `a-Shell_2.3.2.ipa`, a signing
+identity and provisioning profile with an app group.
+
+1. Extract `Payload/a-Shell.app` to `work/Terminal.app`.
+2. Rename the executable `a-Shell` to `Terminal`; set `CFBundleIdentifier`
+   `com.apple.Terminal`, `CFBundleName`/`CFBundleDisplayName` `Terminal`,
+   `CFBundleExecutable` `Terminal`, and `AppGroupIdentifier` to a group in
+   the profile.
+3. Build `src/TerminalSBX.m` as `Frameworks/TerminalSBX.dylib`
+   (`scripts/build_dylib.sh`).
+4. Copy `env/*` into `Terminal.app/bin`; copy `icon/out/Assets.car` and the
+   three `DisplayIcon*.png` files.
+5. Add the `sbx_*`, `sbxhelp`, `neofetch` entries to
+   `commandDictionary.plist` pointing at
+   `@executable_path/Frameworks/TerminalSBX.dylib`.
+6. Inject a weak `LC_LOAD_DYLIB` for
+   `@executable_path/Frameworks/TerminalSBX.dylib` with LIEF
+   (`scripts/inject_dylib.py`).
+7. Re-sign every framework with the same team, then the app with
+   `scripts/ent.plist` and the provisioning profile
+   (`scripts/sign_all.sh`).
+8. Install with `devicectl`/Feather/TrollStore as appropriate for the
+   signing profile.
+
+The app in this repository is source-only; the signed IPA is a release asset
+and is not committed to Git.
+
+## Credits
+
+- **a-Shell** — Nicolas Holzschuch, BSD-2-Clause.
+- **worse_query** — Taj C / forcequitOS, GPL-3.0.
+- **badshell** — wormprojects.
+- **pathleak** — forcequitOS.
+- **neofetch** — Dylan Araps (ASCII art/field inspiration), MIT.
+- The a-Shell full IPA was supplied by the operator for local research.
+
+All project-specific additions are released under GPL-3.0 (see `LICENSE`).