From 9ea14adfda5ebe9db3545d62a97571dabe64d728 Mon Sep 17 00:00:00 2001 From: haonan Date: Wed, 4 Nov 2026 15:10:54 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BC=98=E5=8C=96=E4=B8=AD=E8=8B=B1?= =?UTF-8?q?=E6=96=87=20README=20=E7=BB=93=E6=9E=84=E4=B8=8E=E8=BF=87?= =?UTF-8?q?=E6=9C=9F=E4=BF=A1=E6=81=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.en.md | 152 +++++++++++++++++++++++----------------------- README.md | 166 +++++++++++++++++++++++++-------------------------- 2 files changed, 155 insertions(+), 163 deletions(-) diff --git a/README.en.md b/README.en.md index 15677b4..4db340c 100644 --- a/README.en.md +++ b/README.en.md @@ -6,79 +6,29 @@ [![CI](https://img.shields.io/github/actions/workflow/status/kairowan/Shellsmith/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/kairowan/Shellsmith/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-green?style=flat-square)](#license) -By default, protect Android APK/AAB outputs and iOS source projects, and verify the resulting artifacts, entirely on your own machine; APKs and signing materials do not leave it. When BYOS out-of-package keys are explicitly enabled, the artifact IKM is sent only to the self-hosted HTTPS service you configure, never to Shellsmith maintainers. +Shellsmith is a local-first desktop hardening tool. It protects Android APK/AAB outputs and iOS source projects, signs them, and verifies the results entirely on your machine; APKs, certificates, and signing materials are never uploaded. When BYOS out-of-package keys are explicitly enabled, the artifact IKM is sent only to the self-hosted HTTPS service you configure, never to Shellsmith maintainers. -- **Android:** DEX encryption and runtime protection, then repackaging, alignment, and optional signing. -- **iOS:** selected Swift literal protection and freeRASP runtime checks, combined with Apple's native archive, export, and signature verification. - -Both pipelines raise the cost of static analysis, tampering, and unauthorized re-signing. They do not guarantee that an app cannot be unpacked or reverse engineered. - -The recommended desktop GUI supports Windows, macOS, Linux, and Chinese/English interfaces. A source-built CLI is available for automation and development. +A desktop GUI is available for Windows, macOS, and Linux, with Chinese and English interfaces. The CLI is built from source for automation. > Use only with applications you own or are authorized to protect. Do not bypass third-party protections or use this tool for unauthorized purposes. ## Core Capabilities -- **DEX and runtime protection:** encrypt application DEX files, bind them to the original certificate, and apply baseline anti-debugging or optional strict environment checks. -- **BYOS out-of-package keys:** DEXB v7 artifacts carry only the service URL and token; the IKM is fetched from your self-hosted HTTPS service at launch. Device approval and Google Play Integrity are supported, with a local master key, AWS KMS, GCP KMS, or PKCS#11 HSM backend. -- **iOS source protection:** modify an isolated working copy with Swift Confidential and freeRASP, then archive, export, and verify it with `xcodebuild`. -- **Integrated signing:** import, create, and manage certificates; automatically sign protected output or sign an APK independently. -- **Preflight checks and failure diagnostics:** inspect signatures, existing protection, system requirements, and ABIs; on failure, show a sanitized diagnostic summary that can be previewed and submitted as an error report. -- **Reusable settings:** remember protection options and the protection page's certificate choice, customize output directory and filename, and freeze each running task's configuration. +- **Android DEX hardening:** encrypt application DEX files and bind them to the original certificate, then repackage, align, and optionally sign. Baseline anti-debugging and optional strict checks are included. +- **iOS source protection:** modify an isolated working copy with Swift Confidential and freeRASP, then archive, export, and verify it with `xcodebuild`. The original project is left unchanged. +- **BYOS out-of-package keys:** artifacts carry only the service URL and token; the IKM is fetched from your self-hosted HTTPS service at launch. Device approval and Google Play Integrity are supported. See [BYOS Out-of-Package Keys](#byos-out-of-package-keys). +- **Integrated signing:** import, create, and manage certificates; sign protected output automatically or sign an APK independently. +- **Preflight checks and diagnostics:** inspect signatures, existing protection, system requirements, and ABIs; on failure, show a sanitized summary that can be previewed before submission. +- **Reusable settings:** remember protection options and the certificate choice, customize output directory and filename, and freeze each task's configuration. - **Installation compatibility:** handle APK ZIP alignment and common native-library cases, with separate standard and Android 4.4 industrial modes. -## BYOS Out-of-Package Keys - -BYOS (Bring Your Own Server) moves the artifact IKM out of the APK. It is intended for teams that manage their own keys, device authorization, and revocation policy. - -During protection, Shellsmith generates an independent 32-byte IKM for each artifact and registers it with your self-hosted service in exchange for a `token_id`. The APK carries only the service URL and token, not the IKM. At launch, the client generates an ephemeral RSA key pair and requests the IKM with the token plus a device proof or Play Integrity proof. After validating authorization, replay protection, and the device or Play result, the server encrypts `digest[32] || IKM[32]` to the request's RSA public key and returns it. The client decrypts and verifies the digest before loading business code. - -### Authorization Modes - -| Mode | Use case | Requirements | -|---|---|---| -| `device_approval` | Domestic distribution, sideloading, private channels | Device EC P-256 public-key registration and administrator approval; Android 8.0+ (`minSdk 26`) | -| `play_integrity` | Google Play distribution | Play Console and a Google Cloud service account; Android 10+ (`minSdk 29`) | - -Neither mode falls back to offline loading on failure. An unknown device is recorded as pending and denied; a failed Play check never switches to device approval. - -### Workflow - -1. Deploy the self-hosted HTTPS service, create an application policy, and create a build API key. Source builds must generate the device-approval and Play resources separately with `make build-byos` and `make build-byos-play`; release packages include the matching resources. -2. In Shellsmith, open **Key Delivery → Add Service** and fill in the HTTPS base URL, build API key, authorization mode, and final certificate SHA-256. -3. Test the connection, then protect and sign the APK. Each artifact receives a new `token_id`. -4. In device mode, the first launch is denied until an administrator approves the device; in Play mode, validate with a Play test-track APK. -5. Revoking a device or artifact blocks future fetches. IKM and plaintext code already loaded into a running process cannot be recalled remotely. - -### Server Reference - -Shellsmith does not host the BYOS service. The repository documents a separately deployable Go/PostgreSQL reference implementation with device approval, Play Integrity, replay protection, auditing, master-key rotation, and `migrate-backend` migration. It supports: - -- Local `local_aead` master keys -- AWS KMS -- GCP KMS (including Cloud HSM) -- PKCS#11 HSM - -See the [server reference implementation](docs/design/byos-key-server-reference.md) for deployment and operations. - -### Security Boundaries - -- BYOS keeps the IKM out of the APK and reduces offline key recovery from the package. It is not DRM and cannot prevent memory extraction, hooking, or further analysis of an authorized process. -- The server is the trust root. If the server, KMS, or HSM is compromised, an attacker can unseal the IKM. Protect the database, master keys, KMS/HSM permissions, and backups as described in the server documentation. -- The key is still fetched on every launch, including cache-based launches; there is no offline fallback when the network or service is unavailable. -- The build API key is only for protection-time registration. It is not included in the APK and does not grant runtime authorization. -- AAB, iOS, and Android 4.4 compatibility mode do not support BYOS. - -### Documentation +Both pipelines raise the cost of static analysis, tampering, and unauthorized re-signing. They do not guarantee that an app cannot be unpacked or reverse engineered. -- [BYOS HTTPS Key Service Protocol](docs/design/byos-key-server.md) -- [BYOS Key Server Reference](docs/design/byos-key-server-reference.md) -- [BYOS Local Validation and Troubleshooting](docs/process/byos-local-validation.md) -- [DEXB boundaries in the technical internals](docs/design/internals.md) +## Quick Start -## Download and Quick Start +### Download -Download a stable desktop installer from [GitHub Releases](https://github.com/kairowan/Shellsmith/releases/latest). +Download a stable desktop installer from [GitHub Releases](https://github.com/kairowan/Shellsmith/releases/latest): | Platform | Package | |---|---| @@ -89,7 +39,7 @@ Download a stable desktop installer from [GitHub Releases](https://github.com/ka ### Requirements - A **full JDK 8 or later**, with `java` and `keytool` available; PVM2 requires Java 17+. -- Desktop release users do not need to install the Android SDK. apktool, apksigner, bundletool, and aapt2 for APK/AAB work are bundled. +- Desktop release users do not need to install the Android SDK. apktool, apksigner, bundletool, and aapt2 are bundled. - iOS hardening requires macOS with full Xcode; Windows and Linux cannot archive or export an IPA. Signing status depends on how the package was produced: @@ -107,7 +57,7 @@ Signing status depends on how the package was produced: ### iOS Quick Start -Install full Xcode on macOS, open **Protect → iOS**, select an `.xcodeproj` or `.xcworkspace`, enter the scheme, Team ID, and Bundle ID, run the check, and choose a separate empty output directory. `confidential.yml`, the freeRASP watcher email, and the App Attest server endpoint are all optional. Strict client hardening works without an endpoint, but it does not include a server-side device-attestation loop. The source project is left unchanged. +Install full Xcode on macOS, open **Protect → iOS**, select an `.xcodeproj` or `.xcworkspace`, enter the scheme, Team ID, and Bundle ID, run the check, and choose a separate empty output directory. `confidential.yml`, the freeRASP watcher email, and the App Attest server endpoint are all optional. Strict client hardening works without an endpoint, but it does not include a server-side device-attestation loop. ### Output and Signing @@ -143,7 +93,7 @@ The screenshot illustrates the layout; available options depend on the current v | Android 5.0 and later | API 21+; `armeabi-v7a`, `arm64-v8a`, `x86`, and `x86_64`. An APK does not need all four ABIs | | Android 4.4 industrial | API 19+; inputs must have no native libraries or only `armeabi-v7a` libraries. Physical-device coverage is an Android 4.4.2 `armeabi-v7a`/NEON industrial device | | iOS source project | iOS 13+ SwiftUI/UIKit application targets; archive, export, and signing require macOS with full Xcode | -| BYOS out-of-package keys | Android APK only; `device_approval` requires `minSdk 26+`, `play_integrity` requires `minSdk 29+`; requires a reachable self-hosted HTTPS service and network; AAB, iOS, and Android 4.4 compatibility mode are not supported | +| BYOS out-of-package keys | Android APK only; `device_approval` requires `minSdk 24+`, `play_integrity` requires `minSdk 29+`; requires a reachable self-hosted HTTPS service and network; AAB, iOS, and Android 4.4 compatibility mode are not supported | ### Not Supported @@ -158,7 +108,7 @@ The screenshot illustrates the layout; available options depend on the current v ### Requires Your Own Validation - Vendor systems and hardware still need testing; a successful build does not establish compatibility with every environment. -- The Android GUI and CLI support APK/AAB, but Google Play App Signing, dynamic features, Asset Packs, and dynamic delivery still require validation in the target app's internal test track. +- Google Play App Signing, dynamic features, Asset Packs, and dynamic delivery still require validation in the target app's internal test track. - Unneeded legacy ABIs can be excluded with per-task confirmation, but prefer filtering them in the original project. - 16 KB ZIP alignment does not establish ELF page-size compatibility for every third-party library or guarantee Google Play acceptance. @@ -168,19 +118,57 @@ The screenshot illustrates the layout; available options depend on the current v See the [usage guide](docs/usage.md) for detailed boundaries. +## BYOS Out-of-Package Keys + +BYOS (Bring Your Own Server) moves the artifact IKM out of the APK. It is intended for teams that manage their own keys, device authorization, and revocation policy. + +During protection, Shellsmith generates an independent 32-byte IKM for each artifact and registers it with your self-hosted service in exchange for a `token_id`. The APK carries only the service URL and token. At launch, the client generates an ephemeral RSA key pair and requests the IKM with the token plus a device proof or Play Integrity proof. After validating authorization, replay protection, and the device or Play result, the server encrypts `digest[32] || IKM[32]` to the request's RSA public key and returns it. The client decrypts and verifies the digest before loading business code. + +### Authorization Modes + +| Mode | Use case | Requirements | +|---|---|---| +| `device_approval` | Domestic distribution, sideloading, private channels | Device EC P-256 public-key registration and administrator approval; Android 7.0+ (`minSdk 24`) | +| `play_integrity` | Google Play distribution | Play Console and a Google Cloud service account; Android 10+ (`minSdk 29`) | + +Neither mode falls back to offline loading on failure. An unknown device is recorded as pending and denied; a failed Play check never switches to device approval. + +### Workflow + +1. Deploy the self-hosted HTTPS service, create an application policy, and create a build API key. Source builds must generate the device-approval and Play resources separately with `make build-byos` and `make build-byos-play`; release packages include the matching resources. +2. In Shellsmith, open **Key Delivery → Add Service** and fill in the HTTPS base URL, build API key, authorization mode, and final certificate SHA-256. +3. Test the connection, then protect and sign the APK. Each artifact receives a new `token_id`. +4. In device mode, the first launch is denied until an administrator approves the device; in Play mode, validate with a Play test-track APK. +5. Revoking a device or artifact blocks future fetches. IKM and plaintext code already loaded into a running process cannot be recalled remotely. + +### Security Boundaries + +- BYOS keeps the IKM out of the APK and reduces offline key recovery from the package. It is not DRM and cannot prevent memory extraction, hooking, or further analysis of an authorized process. +- The server is the trust root. If the server, KMS, or HSM is compromised, an attacker can unseal the IKM. Protect the database, master keys, KMS/HSM permissions, and backups as described in the server documentation. +- The key is still fetched on every launch, including cache-based launches; there is no offline fallback when the network or service is unavailable. Revocation affects only future fetches. +- The build API key is only for protection-time registration. It is not included in the APK and does not grant runtime authorization. +- AAB, iOS, and Android 4.4 compatibility mode do not support BYOS. + +Shellsmith does not host the BYOS service. The repository documents a separately deployable Go/PostgreSQL reference implementation with device approval, Play Integrity, replay protection, auditing, master-key rotation, and `migrate-backend`, supporting local `local_aead`, AWS KMS, GCP KMS (including Cloud HSM), and PKCS#11 HSM: + +- [BYOS HTTPS Key Service Protocol](docs/design/byos-key-server.md) +- [Server Reference and Deployment](docs/design/byos-key-server-reference.md) +- [BYOS Local Validation and Troubleshooting](docs/process/byos-local-validation.md) +- [DEXB boundaries in the technical internals](docs/design/internals.md) + ## How It Works and Security Scope -### Android pipeline +### Android Protection reads the original certificate, compresses and encrypts DEX files, injects the stub, then rebuilds, aligns, and optionally signs the APK. At runtime, the stub checks the environment, validates or decrypts the DEX cache, loads code, and starts the original application. The default offline DEXB v6 payload encryption **does not provide confidentiality against static analysis**: both inputs of the envelope key (the signing certificate fingerprint and the build ID) are stored in cleartext in the package header, so the key can be recovered from the APK file alone, and with it the derived keys for every business DEX, the PVM2 images, encrypted assets and business `.text`. What it does provide is refusal to run after re-signing, plus a higher cost for automated scanning and reverse engineering. -BYOS artifacts use DEXB v7: the APK header stores only `server_url` and `token_id`; the IKM remains on the server and is released after authorization, so the APK alone cannot recover it. An authorized process still holds the IKM and plaintext code in memory, and revocation affects only future fetches. See the [BYOS protocol](docs/design/byos-key-server.md) and [technical internals](docs/design/internals.md). +BYOS artifacts use DEXB v7: the APK header stores only `server_url` and `token_id`; the IKM remains on the server and is released after authorization, so the APK alone cannot recover it. An authorized process still holds the IKM and plaintext code in memory. Production uses a decrypted DEX cache in the application's private directory. It is **not a fully in-memory DEX loader or method-code extraction scheme**. Root access, process control, or other elevated privileges may allow runtime code extraction. Standard protection does not block startup solely because of root signals; strict protection blocks some risky environments but cannot guarantee detection of hidden root or prevent bypasses. -### iOS pipeline +### iOS The iOS pipeline edits only a working copy, resolves exact upstream Swift Package versions, generates a stable threat-event wrapper, uses Apple's native Archive/Export flow, and verifies signatures, Team ID, Bundle ID, entitlements, arm64, privacy manifests, dSYMs, and selected sensitive literals. Closed-source freeRASP behavior and the known RootHide gap remain upstream residual risks. @@ -205,7 +193,7 @@ The iOS balanced and strict profiles integrate freeRASP directly into the target ## Feedback and Community - Read the [support guide](docs/process/support.md), then open a [GitHub issue](https://github.com/kairowan/Shellsmith/issues); you can also submit directly from the **Problem feedback** section on the Settings page. -- For feature requests, choose **Feature request** in the **Problem feedback** section on the Settings page, or use the [feature request form](https://github.com/kairowan/Shellsmith/issues/new?template=feature_request.yml); upvote an existing matching request instead of filing a duplicate. +- For feature requests, choose **Feature request** in the **Problem feedback** section, or use the [feature request form](https://github.com/kairowan/Shellsmith/issues/new?template=feature_request.yml); upvote an existing matching request instead of filing a duplicate. - Report vulnerabilities privately following [SECURITY.md](SECURITY.md). Do not publish exploits, business APKs, certificates, or passwords. ## Documentation and Development @@ -224,16 +212,17 @@ The iOS balanced and strict profiles integrate freeRASP directly into the target The CLI is source-built; Releases contain desktop GUI packages only. Build `make build-stub` first, then `make build-cli` or `make build-gui`. Refer to the build guide for dependencies and platform-specific steps. -### CI/CD and Cross-Platform Releases +
+CI/CD and Cross-Platform Releases GitHub Actions live under `.github/workflows/`: - Every push to `main` and every pull request runs Rust, Python, iOS-core, and frontend checks. -- After every successful CI run on `main`, the Release workflow automatically computes a `-build.` version, builds native Linux, macOS, and Windows installers, and creates a GitHub Release. You can still run `Release` manually for a specified version. -- The release job uploads Linux `.AppImage`/`.deb`, macOS `.dmg`, Windows `.exe`, Android runtime resources, and SHA-256 checksum files, and includes an automatic summary of the triggering commit. +- The `Release` workflow is **manual only**: run `workflow_dispatch` on a `main` commit and enter a version matching `package.json`. The workflow validates the source and version, builds native Linux, macOS, and Windows installers, and creates a GitHub Release. Merging a normal pull request does not trigger a release. +- The release job uploads Linux `.AppImage`/`.deb`, macOS `.dmg`, Windows `.exe`, Android runtime resources, and SHA-256 checksum files, and generates the update manifest. - macOS builds use ad-hoc signing by default. Set `MACOS_RELEASE_MODE=developer-id`, a Developer ID identity, and a notarytool profile to produce a distributable notarized package. -The same scripts can be used locally, reading the version from `package.json` so it cannot drift from the released version: +The same scripts can be used locally, reading the version from `package.json`: ```bash VERSION=$(node -p "require('./apps/shield-gui/package.json').version") @@ -245,14 +234,19 @@ On Windows, run this from an elevated PowerShell: ```powershell $version = (Get-Content apps/shield-gui/package.json | ConvertFrom-Json).version -.\scripts\release-windows.ps1 -Version $version +.\scripts/release-windows.ps1 -Version $version ``` All three builds include the stub, PVM2 packer, Android resources, and signing tools; install and verify each package on its target OS before publishing. +
+ ## Acknowledgements -Shellsmith's hardening capabilities build on the upstream projects and tools below. They define the capability boundary, or take part directly in hardening at build time or runtime. Licenses and third-party notices for redistributed components ship in `tools/licenses/`. +Shellsmith's hardening capabilities build on the upstream projects and tools below. Licenses and third-party notices for redistributed components ship in `tools/licenses/`. + +
+Upstream projects and tools ### Origin project @@ -264,7 +258,7 @@ Shellsmith's hardening capabilities build on the upstream projects and tools bel | Project | License | Use | |---|---|---| -| [XopProtector](https://github.com/xopJack/XopProtector) | Apache-2.0 | PVM2 and True-VMP code protection; the runtime and packer sources are redistributed in `third_party/xopprotector/`, and `xop-pvm2-packer.jar` ships with releases, with its license and third-party notices in `tools/licenses/` | +| [XopProtector](https://github.com/xopJack/XopProtector) | Apache-2.0 | PVM2 and True-VMP code protection; the runtime and packer sources are redistributed in `third_party/xopprotector/`, and `xop-pvm2-packer.jar` ships with releases | | [LLVM](https://llvm.org/) | Apache-2.0 WITH LLVM-exception | Native VMP is implemented as an LLVM 21 pass plugin for the app's native build (`native-vmp/`; standalone component, not yet wired into the hardening flow) | ### iOS runtime protection @@ -278,13 +272,15 @@ Shellsmith's hardening capabilities build on the upstream projects and tools bel | Project | License | Use | |---|---|---| -| [Apktool](https://apktool.org/) 3.0.1 | Apache-2.0 | APK decoding and rebuilding; redistributed with releases | +| [Apktool](https://apktool.org/) 3.0.3 | Apache-2.0 | APK decoding and rebuilding; redistributed with releases | | [apksigner](https://developer.android.com/tools/apksigner) (Android SDK Build-Tools) | Apache-2.0 | APK signing and signature verification; redistributed with releases | | [bundletool](https://github.com/google/bundletool) · [aapt2](https://developer.android.com/tools) | Apache-2.0 | AAB module handling and resource compilation | | [Android NDK](https://developer.android.com/ndk) | Apache-2.0 | Compiling the stub native libraries and Android 4.4 compatibility libraries | Desktop frameworks, frontend packages, and general-purpose Rust libraries are not enumerated here; exact versions and licenses can be reproduced from `Cargo.lock`, `apps/shield-gui/package-lock.json`, and `shield-stub/gradle/libs.versions.toml`. +
+ If a credit is wrong, a license is mislabeled, or a project is missing, please open an issue or pull request and we will correct it. ## License diff --git a/README.md b/README.md index 455e1c6..6ce3398 100644 --- a/README.md +++ b/README.md @@ -6,77 +6,27 @@ [![CI](https://img.shields.io/github/actions/workflow/status/kairowan/Shellsmith/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/kairowan/Shellsmith/actions/workflows/ci.yml) [![许可证](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-green?style=flat-square)](#许可证) -默认离线模式下在本机完成 Android APK/AAB 与 iOS 源码工程的加固、签名和产物验证，加固与签名材料不出本机。显式启用 BYOS 包外密钥时，产物 IKM 只会发送到你配置的自建 HTTPS 服务，不经过 Shellsmith 维护者。 +Shellsmith 是一款本地优先的桌面加固工具：Android APK/AAB 与 iOS 源码工程的加固、签名和产物验证都在本机完成，APK、证书和签名材料不会上传。显式启用 BYOS 包外密钥时，产物 IKM 只会发送到你配置的自建 HTTPS 服务，不经过 Shellsmith 维护者。 -- **Android**：DEX 加密与运行时保护，重新打包、对齐并按需签名。 -- **iOS**：选择性 Swift 字符串保护、freeRASP 运行时检测，配合 Apple 原生 Archive、导出与签名验证。 - -两条链路都用于提高静态分析、篡改和非法重签的成本，不承诺无法脱壳或逆向。 - -推荐使用 Windows、macOS、Linux 桌面 GUI，支持中英文界面；CLI 可从源码构建，用于自动化和本地开发。 +提供 Windows、macOS、Linux 桌面 GUI（中英文界面），CLI 可从源码构建用于自动化和本地开发。 > 仅用于保护你拥有合法权利的 Android 与 iOS 应用，请勿用于绕过第三方保护或其他未授权场景。 ## 核心能力 -- **DEX 加固与运行时保护**：加密业务 DEX，绑定原签名证书；提供基础反调试和可选的严格保护。 -- **BYOS 包外密钥**：DEXB v7 产物只携带服务地址和 token，启动时从自建 HTTPS 服务取回 IKM；支持设备批准和 Google Play Integrity，服务端可用本机主密钥、AWS KMS、GCP KMS 或 PKCS#11 HSM。 -- **iOS 源码保护**：在独立工作副本中接入 Swift Confidential 与 freeRASP，再用 `xcodebuild` 完成 Archive、导出和签名验证。 -- **加固签名一体化**：证书导入、新建与管理，加固后自动签名，也支持独立签名。 -- **加固前风险检查与失败诊断**：检查签名、已有加固、系统要求、ABI 等兼容信号；失败时给出脱敏诊断摘要，可预览并确认发送错误报告。 -- **省去重复配置**：记住常用加固选项和加固页证书选择，可调整输出目录与文件名，任务开始后固定本次配置。 -- **安装与系统兼容**：处理 APK ZIP 对齐及常见 Native 库兼容问题；标准模式与 Android 4.4 工控模式分开选择。 - -## BYOS 包外密钥 - -BYOS（Bring Your Own Server）把产物 IKM 从 APK 中移出，适合需要自行保管密钥、控制设备授权和撤销发布权限的应用。 - -加固时 Shellsmith 为每个产物生成独立 32 字节 IKM，调用自建服务端的注册接口换取 `token_id`。APK 只携带服务地址和 token，不携带 IKM。应用启动时，客户端生成一次性 RSA 密钥对，带上 token、设备证明或 Play Integrity 证明请求 IKM；服务端验证授权、防重放和设备/Play 状态后，用本次请求的 RSA 公钥加密 `digest[32] || IKM[32]` 返回。客户端解密并校验摘要后才加载业务代码。 - -### 授权方式 - -| 方式 | 适用场景 | 要求 | -|---|---|---| -| `device_approval` | 国内、侧载、自有分发 | 设备 EC P-256 公钥登记，管理员批准；Android 7.0+（`minSdk 24`） | -| `play_integrity` | Google Play 分发 | Play Console 与 Google Cloud 服务账号；Android 10+（`minSdk 29`） | - -两种方式都不会在失败时回退到离线加载。未知设备只登记为待批准并拒绝；Play 证明失败也不会切换到设备授权。 +- **Android DEX 加固**：加密业务 DEX 并绑定原签名证书，重新打包、对齐并按需签名；提供基础反调试和可选的严格保护。 +- **iOS 源码保护**：在独立工作副本中接入 Swift Confidential 与 freeRASP，再用 `xcodebuild` 完成 Archive、导出和签名验证，原工程不被修改。 +- **BYOS 包外密钥**：产物只携带服务地址和 token，启动时从自建 HTTPS 服务取回 IKM；支持设备批准与 Google Play Integrity。详见 [BYOS 包外密钥](#byos-包外密钥)。 +- **加固签名一体化**：导入、新建和管理证书；加固后自动签名，也可独立签名。 +- **加固前检查与失败诊断**：检查签名、已有加固、系统要求、ABI 等兼容信号；失败时给出脱敏诊断摘要，可预览后确认发送。 +- **少重复配置**：记住常用加固选项和证书选择，支持自定义输出目录与文件名，任务开始后固定本次配置。 +- **安装兼容**：处理 APK ZIP 对齐及常见 Native 库问题；标准模式与 Android 4.4 工控模式分开选择。 -### 使用流程 - -1. 按协议部署自建 HTTPS 服务端，创建应用策略和构建 API key。源码构建需分别生成设备授权和 Play 资源：`make build-byos`、`make build-byos-play`；正式发布包已包含对应资源。 -2. 在 Shellsmith 的“密钥交付 → 新增服务”中填写 HTTPS 基础地址、构建 API key、授权方式和最终证书 SHA-256。 -3. 测试连接，加固并签名 APK。每个产物注册后获得新的 `token_id`。 -4. 设备模式首次启动会被拒绝，管理员在服务端批准设备后重新启动；Play 模式使用 Play 测试轨道 APK 验证。 -5. 撤销设备或产物后，后续取钥失败；已经进入进程的 IKM 和明文代码无法远程收回。 - -### 服务端参考实现 - -Shellsmith 不托管 BYOS 服务端。仓库提供一份可独立部署的 Go/PostgreSQL 参考实现，包含设备批准、Play Integrity、防重放、审计、主密钥轮换和 `migrate-backend` 迁移，并支持： - -- 本机 `local_aead` 主密钥 -- AWS KMS -- GCP KMS（含 Cloud HSM） -- PKCS#11 HSM - -参考实现和完整部署步骤见[服务端参考实现](docs/design/byos-key-server-reference.md)。 - -### 安全边界 - -- BYOS 让 APK 本身不含 IKM，降低仅凭 APK 离线恢复业务密钥的风险；它不等于 DRM，也不能阻止已授权进程的内存提取、Hook 或二次打包分析。 -- 服务端是信任根。服务端、KMS 或 HSM 被攻破后，攻击者可以解封 IKM；必须按服务端文档保护数据库、主密钥、KMS/HSM 权限和备份。 -- 每次启动仍需取钥，DEX 缓存启动也不例外；没有网络或服务端不可用时不会回退到离线加载。 -- 构建 API key 只用于加固注册，不进入 APK，也不具备运行时授权能力。 -- AAB、iOS 和 Android 4.4 兼容模式不支持 BYOS。 +两条链路都用于提高静态分析、篡改和非法重签的成本，不承诺无法脱壳或逆向。 -### 文档入口 +## 快速开始 -- [BYOS HTTPS 密钥服务接入协议](docs/design/byos-key-server.md) -- [BYOS 密钥服务端参考实现](docs/design/byos-key-server-reference.md) -- [BYOS 本地验证与排障记录](docs/process/byos-local-validation.md) -- [技术内参中的 DEXB 边界](docs/design/internals.md) - -## 下载与快速开始 +### 下载 从 [GitHub Releases](https://github.com/kairowan/Shellsmith/releases/latest) 下载正式桌面安装包： @@ -89,25 +39,25 @@ Shellsmith 不托管 BYOS 服务端。仓库提供一份可独立部署的 Go/Po ### 环境要求 - 完整 JDK 8 或更高版本，确保 `java`、`keytool` 可用；使用 PVM2 需要 Java 17+。 -- 使用桌面发布包无需自行安装 Android SDK；AAB 与 APK 所需的 apktool、apksigner、bundletool、aapt2 已随包提供。 -- 仅 iOS 加固需要 macOS 并安装完整 Xcode，Windows 与 Linux 无法 Archive 或导出 IPA。 +- 桌面发布包无需自行安装 Android SDK；apktool、apksigner、bundletool、aapt2 已随包提供。 +- iOS 加固需要 macOS 和完整 Xcode；Windows 与 Linux 无法 Archive 或导出 IPA。 -签名状态随构建方式不同，下载后请按需确认： +签名状态随构建方式不同： -- 本地源码构建产出的是 adhoc 签名包。 +- 本地源码构建产出 adhoc 签名包。 - 对外 macOS 产物只有在配置 Developer ID 与 notary profile 后才会签名、公证，并带上 `_notarized` 后缀；未带该后缀的包仅应从可信位置使用。 -### Android 快速流程 +### Android 加固流程 1. 在 **证书** 页面导入原 APK 使用的签名证书。新项目可创建证书，但输入 APK 也必须先用该证书签名。 2. 在 **加固** 页面选择已签名 APK，或切换到 **AAB · Google Play** 选择已签名 AAB，查看预检结果。 3. 选择目标系统和保护策略。一般使用“Android 5.0 及以上”与“标准保护（推荐）”；目标确有 Android 4.4 时再选择工控模式。 4. 确认输出目录、文件名和自动签名证书，按需调整当前应用的分享选择，再开始加固。 -5. 使用签名后的产物，在目标设备验证安装、启动、主要业务功能和覆盖升级。 +5. 在目标设备验证安装、启动、主要业务功能和覆盖升级。 -### iOS 快速流程 +### iOS 加固流程 -在 macOS 安装完整 Xcode，在 **加固 → iOS** 选择 `.xcodeproj` 或 `.xcworkspace`，填写 scheme、Team ID、Bundle ID，先运行检查，再选择独立空目录执行保护。`confidential.yml`、freeRASP 邮箱和 App Attest 服务端地址均为可选项；没有后台地址时仍可执行严格客户端加固，但不包含服务端设备证明闭环。原工程不会被修改。 +在 macOS 安装完整 Xcode，在 **加固 → iOS** 选择 `.xcodeproj` 或 `.xcworkspace`，填写 scheme、Team ID、Bundle ID，先运行检查，再选择独立空目录执行保护。`confidential.yml`、freeRASP 邮箱和 App Attest 服务端地址均为可选项；没有后台地址时仍可执行严格客户端加固，但不包含服务端设备证明闭环。 ### 输出与签名 @@ -143,7 +93,7 @@ xattr -rd com.apple.quarantine /Applications/Shellsmith.app | Android 5.0 及以上 | API 21+，支持 `armeabi-v7a`、`arm64-v8a`、`x86`、`x86_64`；不要求每个 APK 都包含四种架构 | | Android 4.4 工控兼容 | API 19+；只接受无 Native 库或 Native 库仅含 `armeabi-v7a` 的 APK；真机验证范围为 Android 4.4.2、`armeabi-v7a`/NEON 工控设备 | | iOS 源码工程 | iOS 13+；SwiftUI/UIKit 应用 target；Archive、导出与签名仅支持安装完整 Xcode 的 macOS | -| BYOS 包外密钥 | 仅 Android APK；`device_approval` 要求 `minSdk 26+`，`play_integrity` 要求 `minSdk 29+`；需要可用的自建 HTTPS 服务和网络；AAB、iOS、Android 4.4 兼容模式不支持 | +| BYOS 包外密钥 | 仅 Android APK；`device_approval` 要求 `minSdk 24+`，`play_integrity` 要求 `minSdk 29+`；需要可用的自建 HTTPS 服务和网络；AAB、iOS、Android 4.4 兼容模式不支持 | ### 不支持与不会做的事 @@ -158,7 +108,7 @@ xattr -rd com.apple.quarantine /Applications/Shellsmith.app ### 需要自行验证 - 不同厂商系统和硬件仍需实测，构建通过不代表所有环境可用。 -- Android GUI 和 CLI 都支持 APK/AAB，但 AAB 的 Google Play App Signing、dynamic-feature、Asset Pack 和动态交付仍需在目标应用内测轨道验证。 +- AAB 的 Google Play App Signing、dynamic-feature、Asset Pack 和动态交付仍需在目标应用内测轨道验证。 - 混合旧 ABI 可逐次确认排除，但优先建议从原工程过滤业务不需要的架构。 - 16 KB ZIP 对齐不等于所有第三方 `.so` 都满足 ELF 页大小要求，也不等于通过 Google Play 审核。 @@ -168,19 +118,57 @@ xattr -rd com.apple.quarantine /Applications/Shellsmith.app 详细边界见[使用指南](docs/usage.md)。 +## BYOS 包外密钥 + +BYOS（Bring Your Own Server）把产物 IKM 从 APK 中移出，适合需要自行保管密钥、控制设备授权和撤销发布权限的应用。 + +加固时 Shellsmith 为每个产物生成独立 32 字节 IKM，调用自建服务端的注册接口换取 `token_id`。APK 只携带服务地址和 token。应用启动时，客户端生成一次性 RSA 密钥对，带上 token、设备证明或 Play Integrity 证明请求 IKM；服务端验证授权、防重放和设备/Play 状态后，用本次请求的 RSA 公钥加密 `digest[32] || IKM[32]` 返回。客户端解密并校验摘要后才加载业务代码。 + +### 授权方式 + +| 方式 | 适用场景 | 要求 | +|---|---|---| +| `device_approval` | 国内、侧载、自有分发 | 设备 EC P-256 公钥登记，管理员批准；Android 7.0+（`minSdk 24`） | +| `play_integrity` | Google Play 分发 | Play Console 与 Google Cloud 服务账号；Android 10+（`minSdk 29`） | + +两种方式都不会在失败时回退到离线加载。未知设备只登记为待批准并拒绝；Play 证明失败也不会切换到设备授权。 + +### 使用流程 + +1. 按协议部署自建 HTTPS 服务端，创建应用策略和构建 API key。源码构建需分别生成设备授权和 Play 资源：`make build-byos`、`make build-byos-play`；正式发布包已包含对应资源。 +2. 在 Shellsmith 的“密钥交付 → 新增服务”中填写 HTTPS 基础地址、构建 API key、授权方式和最终证书 SHA-256。 +3. 测试连接，加固并签名 APK。每个产物注册后获得新的 `token_id`。 +4. 设备模式首次启动会被拒绝，管理员批准设备后重新启动；Play 模式使用 Play 测试轨道 APK 验证。 +5. 撤销设备或产物后，后续取钥失败；已经进入进程的 IKM 和明文代码无法远程收回。 + +### 安全边界 + +- BYOS 让 APK 本身不含 IKM，降低仅凭 APK 离线恢复业务密钥的风险；它不等于 DRM，不能阻止已授权进程的内存提取、Hook 或二次打包分析。 +- 服务端是信任根。服务端、KMS 或 HSM 被攻破后，攻击者可以解封 IKM；必须按服务端文档保护数据库、主密钥、KMS/HSM 权限和备份。 +- 每次启动仍需取钥，DEX 缓存启动也不例外；没有网络或服务端不可用时不会回退到离线加载。撤销只影响后续取钥。 +- 构建 API key 只用于加固注册，不进入 APK，也不具备运行时授权能力。 +- AAB、iOS 和 Android 4.4 兼容模式不支持 BYOS。 + +Shellsmith 不托管 BYOS 服务端。仓库提供一份可独立部署的 Go/PostgreSQL 参考实现，包含设备批准、Play Integrity、防重放、审计、主密钥轮换和 `migrate-backend`，支持本机 `local_aead`、AWS KMS、GCP KMS（含 Cloud HSM）和 PKCS#11 HSM。 + +- [BYOS HTTPS 密钥服务接入协议](docs/design/byos-key-server.md) +- [服务端参考实现与部署](docs/design/byos-key-server-reference.md) +- [BYOS 本地验证与排障记录](docs/process/byos-local-validation.md) +- [技术内参中的 DEXB 边界](docs/design/internals.md) + ## 工作原理与安全边界 -### Android 链路 +### Android 加固时读取原签名证书，压缩并加密 DEX，注入壳资源，再重新打包、对齐并按需签名。运行时由壳执行安全检查、校验或解密 DEX 缓存，加载业务代码并启动原应用。 默认离线链路的 DEXB v6 载荷加密**不提供针对静态分析的机密性**：包裹密钥的两个输入（签名证书指纹与 build_id）都写在包内头部，仅凭 APK 文件本身即可还原密钥，并进一步解出全部业务 DEX 与 PVM2、加密 assets、业务 `.text` 的派生密钥。该层提供的是「改包重签后无法运行」以及提高自动化扫描与逆向的成本。 -BYOS 产物使用 DEXB v7：APK 头部只保存 `server_url` 和 `token_id`，IKM 由服务端保管并在启动时按授权下发，因此仅凭 APK 不能还原 IKM。已授权进程仍会在内存中持有 IKM 和明文代码，撤销只影响后续取钥；详见[BYOS 接入协议](docs/design/byos-key-server.md)和[技术内参](docs/design/internals.md)。 +BYOS 产物使用 DEXB v7：APK 头部只保存 `server_url` 和 `token_id`，IKM 由服务端保管并在启动时按授权下发，因此仅凭 APK 不能还原 IKM。已授权进程仍会在内存中持有 IKM 和明文代码。 当前正式方案会在应用私有目录使用解密后的 DEX 缓存，**不是完整内存 DEX 或方法代码抽取方案**。Root、进程控制或其他高权限环境下，攻击者仍可能提取运行时代码。标准保护不因 Root 信号拒绝启动；严格保护可阻断部分风险环境，但无法保证识别隐藏 Root 或抵御绕过。 -### iOS 链路 +### iOS iOS 流水线只改工作副本：接入精确版本的上游 Swift Package，生成统一威胁事件封装，调用 Apple 原生 Archive/Export，再核验签名、Team ID、Bundle ID、Entitlements、arm64、隐私清单、dSYM 和选定敏感字符串。freeRASP 的闭源检测能力和已知 RootHide 漏检仍属于上游残余风险。 @@ -208,7 +196,7 @@ iOS balanced/strict 会让目标应用直接集成 freeRASP；其 `watcherMail` - 功能建议可在设置页的“问题反馈”中选择“需求建议”提交，也可使用[需求表单](https://github.com/kairowan/Shellsmith/issues/new?template=feature_request.yml)；已有相同需求可在原 issue 点赞。 - 安全漏洞请按 [SECURITY.md](SECURITY.md) 私下报告，不公开可利用细节、业务 APK、证书或密码。 -## 文档与开发者入口 +## 文档与开发 | 需要了解 | 文档 | |---|---| @@ -224,16 +212,17 @@ iOS balanced/strict 会让目标应用直接集成 freeRASP；其 `watcherMail` CLI 仅供源码构建和自动化使用，Release 不单独提供 CLI 包。构建顺序为先 `make build-stub`，再 `make build-cli` 或 `make build-gui`；完整依赖与平台步骤以构建指南为准。 -### CI/CD 与跨平台发布 +
+CI/CD 与跨平台发布 GitHub Actions 位于 `.github/workflows/`： -- 每次推送到 `main` 或创建 Pull Request 时运行 Rust、Python、iOS 核心和前端检查。 -- `main` 每次通过 CI 后，Release 工作流会自动计算 `<当前版本>-build.` 版本，在 Linux、macOS 和 Windows 原生 runner 上构建安装包，并创建 GitHub Release；也可以手动运行 `Release` 发布指定版本。 -- 发布流程会上传 Linux `.AppImage`/`.deb`、macOS `.dmg`、Windows `.exe`、Android runtime 资源包及 SHA-256 校验文件，并自动生成本次提交的变更摘要。 +- 每次推送到 `main` 或创建 Pull Request 时，运行 Rust、Python、iOS 核心和前端检查。 +- `Release` 工作流**仅手动触发**：在 `main` 的提交上运行 `workflow_dispatch`，填写与 `package.json` 一致的版本号。工作流会校验来源和版本，在 Linux、macOS、Windows 原生 runner 上构建安装包并创建 GitHub Release，不会因普通 PR 合并自动发版。 +- 发布产物包括 Linux `.AppImage`/`.deb`、macOS `.dmg`、Windows `.exe`、Android runtime 资源包及 SHA-256 校验文件，并生成更新清单。 - macOS 默认生成 adhoc 签名包；配置 `MACOS_RELEASE_MODE=developer-id`、Developer ID 身份和 notarytool profile 后，才生成可分发的公证包。 -本地也可以复用同一套脚本，版本号直接从 `package.json` 读取，避免与当前发布版本脱节： +本地也可以复用同一套脚本，版本号直接从 `package.json` 读取： ```bash VERSION=$(node -p "require('./apps/shield-gui/package.json').version") @@ -245,14 +234,19 @@ Windows 使用管理员 PowerShell： ```powershell $version = (Get-Content apps/shield-gui/package.json | ConvertFrom-Json).version -.\scripts\release-windows.ps1 -Version $version +.\scripts/release-windows.ps1 -Version $version ``` 三平台构建都包含 Stub、PVM2 Packer、Android 资源和签名工具，发布前仍应在目标系统安装并验证。 +
+ ## 致谢 -Shellsmith 的加固能力建立在这些上游项目与工具之上：它们定义了本工具的能力边界，或在构建期、运行期直接参与加固。随发布包分发的组件，其许可证与第三方声明见 `tools/licenses/`。 +Shellsmith 的加固能力建立在这些上游项目与工具之上。随发布包分发的组件，其许可证与第三方声明见 `tools/licenses/`。 + +
+上游项目与工具 ### 上游来源工程 @@ -264,7 +258,7 @@ Shellsmith 的加固能力建立在这些上游项目与工具之上：它们定 | 项目 | 许可证 | 用途 | |---|---|---| -| [XopProtector](https://github.com/xopJack/XopProtector) | Apache-2.0 | PVM2 与 True-VMP 代码保护；壳运行时源码与打包器源码随本仓库分发（`third_party/xopprotector/`），`xop-pvm2-packer.jar` 随发布包分发，许可证与第三方声明见 `tools/licenses/` | +| [XopProtector](https://github.com/xopJack/XopProtector) | Apache-2.0 | PVM2 与 True-VMP 代码保护；壳运行时源码与打包器源码随本仓库分发（`third_party/xopprotector/`），`xop-pvm2-packer.jar` 随发布包分发 | | [LLVM](https://llvm.org/) | Apache-2.0 WITH LLVM-exception | Native VMP 以 LLVM 21 Pass 插件形式接入业务 Native 构建（`native-vmp/`，独立组件，尚未接入加固流程） | ### iOS 运行时保护 @@ -278,13 +272,15 @@ Shellsmith 的加固能力建立在这些上游项目与工具之上：它们定 | 项目 | 许可证 | 用途 | |---|---|---| -| [Apktool](https://apktool.org/) 3.0.1 | Apache-2.0 | APK 反编译与重打包，随发布包分发 | +| [Apktool](https://apktool.org/) 3.0.3 | Apache-2.0 | APK 反编译与重打包，随发布包分发 | | [apksigner](https://developer.android.com/tools/apksigner)（Android SDK Build-Tools） | Apache-2.0 | APK 签名与签名校验，随发布包分发 | | [bundletool](https://github.com/google/bundletool) · [aapt2](https://developer.android.com/tools) | Apache-2.0 | AAB 模块处理与资源编译 | | [Android NDK](https://developer.android.com/ndk) | Apache-2.0 | 壳 Native 库与 Android 4.4 兼容库的编译 | 桌面框架、前端与 Rust 通用库依赖不在本节逐一列出；完整版本与许可证可从 `Cargo.lock`、`apps/shield-gui/package-lock.json` 与 `shield-stub/gradle/libs.versions.toml` 复现。 +
+ 如果这里署名有误、许可证标注不准或遗漏了应当致谢的项目，欢迎提交 issue 或 PR，我们会尽快更正。 ## 许可证