From 92a1ac27746641b7904d75b3a723ab7451354cbe Mon Sep 17 00:00:00 2001 From: haonan Date: Fri, 13 Nov 2026 19:28:30 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=20SO=20=E5=8A=A0?= =?UTF-8?q?=E5=9B=BA=E4=B8=8E=20MCP=20=E4=BD=BF=E7=94=A8=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.en.md | 37 ++++++++++++++++++++++++++++++++++--- README.md | 38 +++++++++++++++++++++++++++++++++----- 2 files changed, 67 insertions(+), 8 deletions(-) diff --git a/README.en.md b/README.en.md index 822097a..c50af63 100644 --- a/README.en.md +++ b/README.en.md @@ -15,21 +15,23 @@ Shellsmith is a desktop hardening tool for Android and iOS apps, with two key-de On Android, Shellsmith provides DEX encryption and certificate binding for APK/AAB, PVM2 method virtualization, baseline anti-debugging, and optional strict protection, then repackages, aligns, and signs the output. On iOS, it works on an isolated copy, integrates Swift Confidential and freeRASP, then archives, exports, and verifies signing. Apart from registration and key fetch against your own service in online mode, APKs, certificates, signing materials, and passwords are never uploaded or sent to Shellsmith maintainers. -A desktop GUI is available for Windows, macOS, and Linux, with Chinese and English interfaces. The CLI is built from source for automation. +A desktop GUI is available for Windows, macOS, and Linux, with Chinese and English interfaces. Starting with 1.11.0, the CLI and local MCP server are also available as a separate download. > Use only with applications you own or are authorized to protect. Do not bypass third-party protections or use this tool for unauthorized purposes. -**Quick navigation** · [Capabilities](#core-capabilities) · [Quick Start](#quick-start) · [Compatibility](#compatibility-and-limitations) · [Online Keys (BYOS)](#byos-out-of-package-keys) · [Security Scope](#how-it-works-and-security-scope) · [Documentation](#documentation-and-development) +**Quick navigation** · [Capabilities](#core-capabilities) · [Quick Start](#quick-start) · [SO Protection](#android-so-protection) · [CLI and MCP](#cli-and-mcp) · [Compatibility](#compatibility-and-limitations) · [Online Keys (BYOS)](#byos-out-of-package-keys) · [Security Scope](#how-it-works-and-security-scope) · [Documentation](#documentation-and-development) ## Core Capabilities - **Two key-delivery modes:** **Offline keys** are derived locally and wrapped into the artifact, requiring no network or key service. **Online keys (BYOS)** keep the IKM on your self-hosted HTTPS service; the artifact carries only the service URL and token and fetches the key at launch after device approval or Play Integrity authorization. See [BYOS Out-of-Package Keys](#byos-out-of-package-keys). - **Android code protection:** encrypt application DEX files, bind them to the original certificate, and support PVM2 method virtualization, baseline anti-debugging, and optional strict protection; then repackage, align, and sign. +- **Android SO protection** encrypts eligible function regions in application `.so` files packaged in an APK or AAB in strict mode. See [Android SO Protection](#android-so-protection). - **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. - **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. +- **CLI and MCP** support local automation. MCP provides 16 tools over stdio for preflight checks, hardening, signing, APKS installation, report reading, and job control. See [CLI and MCP](#cli-and-mcp). 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. @@ -64,6 +66,16 @@ Signing status depends on how the package was produced: 4. Review the output directory, filename, automatic signing certificate, and per-app sharing choice, then start protection. 5. Test the signed output on target devices: installation, launch, core functionality, and upgrade installation. +### Android SO Protection + +In **Protect**, select a signed APK and set the protection profile to **Strict code protection (PVM2 required)**. Use the bundled PVM2 Packer and specify your application's class prefixes or a list of critical methods. This requires Java 17 or later. Shellsmith encrypts eligible function regions in the packaged `.so` files and decrypts them at runtime. If any ABI variant of a library lacks suitable function symbols or has incompatible relocations, Shellsmith skips the library across all ABIs. Review the protection log for encrypted and skipped libraries, then test JNI calls and app behavior on target devices. + +For an AAB, select **Strict (PVM2 + PAS2 + PSO2)** under **AAB · Google Play**. For a multi-module AAB, native libraries must pass module protection checks before Shellsmith writes the output. [Usage guide](docs/usage.md#基础用法) + +APK repackaging preserves the original `android:extractNativeLibs` setting. When explicitly set to `false`, packaged `.so` files are stored uncompressed and aligned to 16 KB in the ZIP. Each library's ELF segments still need to meet the target device's alignment requirements. [Native library packaging](docs/design/native-library-packaging.md) + +**Protection for standalone SO files and Android project `jniLibs` directories is in development** and is unavailable in the 1.11.0 release. + ### 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. @@ -87,6 +99,25 @@ This removes quarantine; it does not mean the application is notarized by Apple. +### CLI and MCP + +Download the matching `Shellsmith-cli--` archive for macOS Universal, Linux x86_64, or Windows x86_64. After extraction, run `shield` from `bin/` for CLI use. The `shellsmith-mcp` executable locates `shield` in the same directory. On Windows, both executable names end in `.exe`. [Download CLI and MCP](https://github.com/kairowan/Shellsmith/releases/latest) + +In a client that supports stdio MCP, replace the paths below with absolute paths on your machine. The allowed directory should cover the inputs and outputs of your jobs. + +```json +{ + "mcpServers": { + "shellsmith": { + "command": "/absolute/path/to/bin/shellsmith-mcp", + "args": ["--allow-root", "/absolute/path/to/projects"] + } + } +} +``` + +Call `shellsmith_version` to verify the connection and `shellsmith_check_apk` to inspect an APK. Pass `confirm: true` when performing hardening, signing, or installation. Long-running jobs return a `job_id` for checking progress, retrieving results, or cancelling. Supply signing passwords and BYOS build API keys through the MCP process environment. [Tool list and iOS setup](docs/mcp.md) + ## Preview

@@ -249,7 +280,7 @@ The iOS balanced and strict profiles integrate freeRASP directly into the target `apps/shield-gui` is the Tauri desktop frontend for hardening, signing, certificate management, and settings. `tools/stats-worker` provides JSON endpoints for maintenance statistics, error reports, and feedback. See the [desktop architecture](docs/design/gui.md) and [maintenance statistics guide](docs/ops/project-statistics.md). -Use the local CLI or stdio MCP server to automate hardening, signing, preflight checks, and report reading. See the [MCP guide](docs/mcp.md) for installation and client setup. Local `make release` / `scripts/release-cli.sh` CLI packages include both `shield` and `shellsmith-mcp`. Run `make build-stub` first, then `make build-cli` or `make build-gui`. +Local `make release` / `scripts/release-cli.sh` CLI packages include both `shield` and `shellsmith-mcp`. Run `make build-stub` first, then `make build-cli` or `make build-gui`.

CI/CD and Cross-Platform Releases diff --git a/README.md b/README.md index 003934c..8451c2d 100644 --- a/README.md +++ b/README.md @@ -15,22 +15,23 @@ Shellsmith 是一款面向 Android 与 iOS 的桌面应用加固工具，支持* Android 侧提供 APK/AAB 的 DEX 加密、证书绑定、PVM2 方法虚拟化、基础反调试与可选的严格保护，并完成重打包、ZIP 对齐和自动签名；iOS 侧在独立工作副本中接入 Swift Confidential 与 freeRASP，完成 Archive、导出和签名验证。除在线密钥模式向你的服务端注册和取钥外，APK、证书、签名材料与密码不会上传，也不会发送给 Shellsmith 维护者。 -提供 Windows、macOS、Linux 桌面 GUI（中英文界面），CLI 可从源码构建用于自动化和本地开发。 +提供 Windows、macOS、Linux 桌面 GUI（中英文界面）。从 1.11.0 起，发布页也提供 CLI 与本地 MCP 服务的独立下载包。 > 仅用于保护你拥有合法权利的 Android 与 iOS 应用，请勿用于绕过第三方保护或其他未授权场景。 -**快速导航** · [核心能力](#核心能力) · [快速开始](#快速开始) · [兼容性](#兼容性与限制) · [在线密钥（BYOS）](#byos-包外密钥) · [安全边界](#工作原理与安全边界) · [文档](#文档与开发) +**快速导航** · [核心能力](#核心能力) · [快速开始](#快速开始) · [SO 加固](#android-so-加固) · [CLI 与 MCP](#cli-与-mcp) · [兼容性](#兼容性与限制) · [在线密钥（BYOS）](#byos-包外密钥) · [安全边界](#工作原理与安全边界) · [文档](#文档与开发) ## 核心能力 - **双密钥交付**：**离线密钥**由本机派生并封装进产物，无需网络和密钥服务；**在线密钥（BYOS）**把 IKM 托管到自建 HTTPS 服务，产物只携带服务地址和 token，启动时经设备批准或 Play Integrity 授权取回。详见 [BYOS 包外密钥](#byos-包外密钥)。 - **Android 代码保护**：加密业务 DEX 并绑定原签名证书；支持 PVM2 方法虚拟化、基础反调试和可选的严格保护；重新打包、对齐并按需签名。 +- **Android SO 加固**在严格保护模式下加密 APK/AAB 内符合条件的业务 `.so` 函数区域。见 [Android SO 加固](#android-so-加固)。 - **iOS 源码保护**：在独立工作副本中接入 Swift Confidential 与 freeRASP，再用 `xcodebuild` 完成 Archive、导出和签名验证，原工程不被修改。 - **加固签名一体化**：导入、新建和管理证书；加固后自动签名，也可独立签名。 - **加固前检查与失败诊断**：检查签名、已有加固、系统要求、ABI 等兼容信号；失败时给出脱敏诊断摘要，可预览后确认发送。 - **少重复配置**：记住常用加固选项和证书选择，支持自定义输出目录与文件名，任务开始后固定本次配置。 - **安装兼容**：处理 APK ZIP 对齐及常见 Native 库问题；标准模式与 Android 4.4 工控模式分开选择。 -- **CLI 与 MCP**：在本机脚本或支持 stdio MCP 的客户端中执行加固、签名、预检和报告读取，可查询和取消长任务。接入方式见 [MCP 指南](docs/mcp.md)。 +- **CLI 与 MCP**支持本地自动化。MCP 通过 stdio 提供 16 个工具，覆盖预检、加固、签名、APKS 安装、报告读取和任务管理。见 [CLI 与 MCP](#cli-与-mcp)。 两条链路都用于提高静态分析、篡改和非法重签的成本，不承诺无法脱壳或逆向。 @@ -46,8 +47,6 @@ Android 侧提供 APK/AAB 的 DEX 加密、证书绑定、PVM2 方法虚拟化 | macOS | `Shellsmith_x.y.z_macos_universal.dmg` | | Linux | `Shellsmith_x.y.z_linux_amd64.AppImage` 或 `.deb` | -需要命令行或 MCP 时，可下载发布页中可用的 `Shellsmith-cli--` 包，或按 [MCP 指南](docs/mcp.md) 从源码构建。 - ### 环境要求 - 完整 JDK 8 或更高版本，确保 `java`、`keytool` 可用；使用 PVM2 需要 Java 17+。 @@ -67,6 +66,16 @@ Android 侧提供 APK/AAB 的 DEX 加密、证书绑定、PVM2 方法虚拟化 4. 确认输出目录、文件名和自动签名证书，按需调整当前应用的分享选择，再开始加固。 5. 在目标设备验证安装、启动、主要业务功能和覆盖升级。 +### Android SO 加固 + +在 **加固** 页面选择已签名 APK，将保护级别设为 **严格代码保护（需 PVM2）**，使用内置 PVM2 Packer 并填写自有业务类前缀或关键方法清单。需要 Java 17+。加固时会加密符合条件的业务 `.so` 函数区域，由壳在运行时解密加载。若同名库的任一 ABI 缺少可安全处理的函数符号或含有不兼容的重定位，该库会整体跳过。加固后查看日志中的加密和跳过统计，并在目标设备验证 JNI 与业务功能。 + +处理 AAB 时，在 **AAB · Google Play** 中选择 **严格保护（PVM2 + PAS2 + PSO2）**。多模块 AAB 的 Native 库必须满足模块保护校验才能生成产物。[使用指南](docs/usage.md#基础用法) + +APK 重打包会保留原有 `android:extractNativeLibs` 设置。显式设为 `false` 时，包内 `.so` 保持不压缩并按 16 KB 对齐。目标设备所需的 ELF 段对齐仍取决于各库的构建产物。[Native 库打包说明](docs/design/native-library-packaging.md) + +**独立 SO 和 Android 工程 `jniLibs` 目录的加固入口仍在开发中**，1.11.0 发布包尚未提供。 + ### iOS 加固流程 在 macOS 安装完整 Xcode，在 **加固 → iOS** 选择 `.xcodeproj` 或 `.xcworkspace`，填写 scheme、Team ID、Bundle ID，先运行检查，再选择独立空目录执行保护。`confidential.yml`、freeRASP 邮箱和 App Attest 服务端地址均为可选项；没有后台地址时仍可执行严格客户端加固，但不包含服务端设备证明闭环。 @@ -90,6 +99,25 @@ xattr -rd com.apple.quarantine /Applications/Shellsmith.app
+### CLI 与 MCP + +下载对应平台的 `Shellsmith-cli--` 包，支持 macOS Universal、Linux x86_64 和 Windows x86_64。解压后，`bin/` 内的 `shield` 可直接用于命令行，`shellsmith-mcp` 会自动查找同目录的 `shield`。Windows 下两个程序均带 `.exe` 后缀。[下载 CLI 与 MCP](https://github.com/kairowan/Shellsmith/releases/latest) + +在支持 stdio MCP 的客户端中，将下面的路径替换为本机的绝对路径。允许目录应覆盖任务的输入和输出。 + +```json +{ + "mcpServers": { + "shellsmith": { + "command": "/absolute/path/to/bin/shellsmith-mcp", + "args": ["--allow-root", "/absolute/path/to/projects"] + } + } +} +``` + +接入后，可先调用 `shellsmith_version` 验证连接，再用 `shellsmith_check_apk` 检查 APK。执行加固、签名和安装时传入 `confirm: true`。长任务返回 `job_id`，可查询进度、读取结果或取消。签名密码和 BYOS 构建 API key 通过 MCP 进程的环境变量提供。[工具清单与 iOS 接入](docs/mcp.md) + ## 界面预览