reashield

REAShield

REA 可对任何应用进行逆向工程。REAShield 让它无功而返。

REA 是 GitHub 上趋势排名第 1 的仓库，它让 AI Agent 只需一条命令，就能对你发布的应用进行逆向工程，无需源代码。 **REAShield 是防御性应对方案：**将它加入构建流程，就能强化你发布的内容 （JavaScript / Electron / Python），让自动化逆向工程一无所获。

基于真实攻击者的实测，而非空口宣称

• REA（rea-agents）在强化前恢复了 6 个受保护令牌，强化后为 0。
• webcrack 完全反混淆了强化后的客户端（进行了 1103 项更改，解码了字符串数组）， 但仍然恢复了 0 个——因为机密已迁移并封存，而非仅仅经过混淆。

npm i -D reashield
npx reashield build        # hardened client + generated server skeleton
npx reashield test --rea   # run the REAL REA on before/after; score what it recovers

Python 前端：pip install reashield（参见 python/）。

坦诚的承诺与局限——请阅读

离线代码永远无法做到牢不可破。如果一台机器必须运行这些代码，它就拥有这些代码，因此只要投入足够精力，就总能将其提取出来——混淆、WASM 和 字节码只能提高提取成本。REAShield 的作用是击败自动化攻击 （REA 刚刚让所有人都能实施的那种攻击），并将人类分析人员的成本从几分钟提高到 几天。唯一真正无法恢复的代码，就是你不发布的代码——在 服务端运行（mode: "relocate"）。仅用于防御、保留原有行为、透明 （不会主动向外发送数据）。它会强化你拥有并发布的代码；无法帮助绕过他人的 DRM、许可证检查或反作弊机制。

---

通过 AI Agent 使用（MCP 服务）

REA 是一个 MCP 服务，为 Agent 提供逆向工程工具。REAShield 提供的是防御性镜像——一个 MCP 服务，为 Agent 提供强化 工具，让 Claude Code / Cursor 能通过聊天检查、强化和评估项目。

工具：reashield_doctor（检查暴露内容）、reashield_harden（进行强化）、 reashield_measure（运行真实的 REA 并报告恢复评分）。

# Claude Code
claude mcp add reashield -- npx -y reashield-mcp

# Cursor / other MCP clients — add to your MCP config:
# { "mcpServers": { "reashield": { "command": "npx", "args": ["-y", "reashield-mcp"] } } }

---

两个前端，一套架构

REAShield 是一个单体仓库。同一个经久耐用的理念——将机密移出设备，把静态信息转为运行时信息，并衡量结果——为两种生态系统提供了实现：

前端	安装	保护对象	状态
JavaScript / npm / Electron（此软件包）	npm i -D reashield	已发布的 JS 包、app.asar	已发布
Python（python/）	pip install -e python	已发布的 .py 应用	在此仓库中

两者都采用下方列出的核心能力顺序。Python 软件包也实现了迁移、 封存（AES-GCM）、字符串间接引用、名称混淆、多态变换、诱饵和 测量工具，并配备安全分析器，会拒绝处理，而不是错误编译。参见 python/README.md。

解释型语言和随应用发布源代码的语言最适合采用这种方式；编译为原生代码的语言 （Go、Rust、C/C++）不会发布源代码，逆向工程方式也有所不同。

---

为什么有效（威胁模型）

REA 的 JavaScript/Electron 路径是静态的——它绝不会运行你的应用。它会读取 你的 bundle，重建模块、导入、路由、IPC 通道和字符串的图谱，然后将精简的 摘要交给编码 Agent 进行分析。对于任何运行时计算的内容，它都会如实标记为未解析；图谱过大时，也会舍弃关系。

因此，持久有效的防御要么将机密移出设备，要么将静态事实转化为 REA 无法解析的运行时事实。纯混淆——LLM 辅助反混淆会让它最快失效——只是可替换的外层，而非基础。

防御支柱（按持久性排序）

支柱	mode / 层	作用	局限性（如实说明）
服务端迁移	relocate	将实际代码体移至生成的服务端骨架；仅通过一个端点发送不透明的远程调用存根。机密绝不会被发送。	需要安全的后端；请求／响应边界可被观察到。
加密封装（max）	seal	将模块以密文形式发送，运行时从你的服务端获取密钥并解密。	需要连接；无法阻止他人转储已解密的内存。
WASM	wasm	将数值子集逻辑编译为真正的 WebAssembly 模块，使其脱离 REA 的 JS 图谱路径。	仅支持数值子集；超出范围时回退到 obfuscate（并报告）；WASM 仍可被反编译。
动态图谱（max）	dynamicGraph	计算导入 + 运行时分发表——删除 REA 能还原的调用／导入边。	有 CPU 开销；仅限受保护区域。
图谱稀释	flattenBundle、stripSourceMaps、stringIndirection、dynamicChannels	合并为一个模块，不含映射文件、无语义的明文字符串、计算得出的通道名称。	混淆效果会随时间减弱。
多态化	polymorphic	每次构建都重新随机化名称、字符串和结构——防止版本差异比对。	单独使用只是表面防护；需与上述措施配合。
诱饵	decoys	无效的伪造“功能”集群（枢纽 + 环形链接成员 + 伪造入口），包含看似合理的路由／IPC／密钥字符串，设计成在 REA 摘要中显得居于核心。	试验性功能；经过测量，但可能增加体积。
完整性	integrity（关闭）	故障安全的防篡改机制。	无法防御 REA 的静态路径（REA 从不运行你的应用）。

安装

npm install --save-dev reashield

快速开始

npx reashield init          # scaffold shield.config.cjs
npx reashield build         # emit hardened client + server skeleton
npx reashield doctor        # show config, layers, costs, deps
npx reashield test          # measure before vs after (static; add --rea for real REA)

配置（shield.config.cjs）

module.exports = {
  input: "src/index.js",
  output: "dist-shielded",
  preset: "balanced",            // low | balanced | max
  protect: [
    { name: "licenseCheck", mode: "relocate" },  // strongest: off-device
    { name: "sealedCalc",   mode: "seal" },        // ciphertext + remote key (max)
    { name: "pricingLogic", mode: "wasm" },        // off the JS graph (fast-follow)
    { name: "featureGate",  mode: "obfuscate" },   // harden in place
  ],
  server: {
    enabled: true, out: "server-shielded", adapter: "express",
    endpoint: "/__s", keyEndpoint: "/__s/k", decoyCalls: false,
  },
  polymorphic: { enabled: true, seed: "auto" },     // "auto" rotates every build
  layers: {
    stripSourceMaps: true, flattenBundle: true, obfuscate: true,
    stringIndirection: true, dynamicChannels: true, dynamicGraph: false,
    decoys: { enabled: true, count: 5 }, integrity: false,
  },
};

也接受 protect: ["a", "b"]（普通字符串数组）；每项默认使用 mode: "obfuscate"。你也可以将配置放在 package.json 的 reashield 键下。

预设

• low — 移除映射文件、扁平化、混淆命名。速度快，体积最小。
• balanced（默认）— + 字符串间接寻址、名称同质化、计算通道、不透明迁移边界、结构多态化、5 个诱饵。开销较低。
• max — + 动态分派、加密封装、诱饵调用、控制流扁平化、死代码注入、自我防御、约 15 个诱饵。会增加延迟／CPU 开销／体积——doctor 会标记这些影响。

打包器插件（在现有构建中运行强化）

不使用 CLI，而是在 esbuild / Rollup / Vite 构建过程中进行强化。插件会按模块运行源码级支柱，然后处理每个输出分块（诱饵 + 混淆 + 移除源映射 + 注入客户端运行时），并写入服务端骨架。这里的 flattenBundle 不执行任何操作——打包器已经完成打包；插件会强化其输出。通过插件安装的全局对象配置一次迁移／封装传输： globalThis.__configureShield({ transport, keyTransport })（也可以让默认的 fetch 传输调用你的端点）。

// rollup.config.mjs
import { reashieldRollup } from "reashield/plugins";
export default {
  input: "src/index.js",
  output: { dir: "dist", format: "esm" },
  plugins: [reashieldRollup({ configPath: "shield.config.cjs" })],
};

// vite.config.mjs  (Vite consumes the Rollup plugin interface)
import { reashieldVite } from "reashield/plugins";
export default { plugins: [reashieldVite({ configPath: "shield.config.cjs" })] };

// esbuild build script
import { build } from "esbuild";
import { reashieldEsbuild } from "reashield/plugins";
await build({
  entryPoints: ["src/index.js"],
  bundle: true,
  outdir: "dist",
  plugins: [reashieldEsbuild({ configPath: "shield.config.cjs" })],
});

每个插件都接受 { config | configPath, cwd, seed }。注意：插件会强化每个发出的 JS 分块，因此混淆开销会作用于整个输出——请据此限定构建范围。

生成的服务骨架

relocate 和 seal 会生成一个 server-shielded/ 目录，其中包含真实逻辑和密钥。**切勿将其交付给用户。**你应在自有的身份验证和 TLS 保护下运行它。REAShield 会搭建 Express/Fastify 接线代码和用于测试的进程内处理程序；保护端点是你的责任（它不会为你添加身份验证）。

身份验证接口（由你提供）。在调用 setAuthVerifier 之前，端点处于开放状态——交付前务必做好安全保护。客户端会附加来自你配置的数据源的令牌；服务端负责验证令牌：

// server
import { setAuthVerifier } from "./server-shielded/handlers.js";
setAuthVerifier(async (token, ctx) => (await myAuth.verify(token)) === true);

// client (wire once at startup)
__configureShield({ authToken: () => myAuth.currentToken() }); // (or globalThis.__configureShield in plugin builds)

适配器。adapter: "express" | "fastify" | "web" | "generic"。骨架始终会导出一个跨运行时的 webHandler(request: Request): Promise<Response>，可直接用于 Hono、Cloudflare Workers、Deno、Bun 或 Next.js 路由处理程序：

import { webHandler } from "./server-shielded/handlers.js";
export const POST = (req) => webHandler(req); // Next.js app route, Workers fetch, ...

迁移或封装的函数会变成 async（它们需要进行往返调用）。确保调用位置使用 await。这些函数必须是自包含的（不能闭包引用仅存在于客户端的模块状态）。

保持行为不变

加固绝不能改变程序的行为。打包示例（examples/sample-package）证明加固前后的输出完全一致——包括通过进程内服务调用的迁移和封装代码，并断言诱饵代码绝不会执行。运行 npm run example:test 即可测试。

Electron 加固

对于 Electron 应用，REAShield 提供了 Electron 专用路径（与上述 JS 保护支柱配合使用）：

• 动态 IPC 通道重写 — 将字面量 ipcMain/ipcRenderer/webContents 通道字符串转换为运行时计算的字符串。REA 按设计会将动态计算的 IPC 名称保留为未解析状态，因此这会直接切断其图谱。保留值不变：两端会计算出完全相同的字符串。通过 layers.ipcChannels: true 启用，或单独运行：

  npx reashield electron ipc src/main.js --out dist/main.js
  

• V8 字节码（bytenode）——交付 .jsc，使 asar 中不包含可读的 JS：

  npx reashield electron bytecode dist/main.js --out dist/main.jsc
  

  **注意事项：**V8 字节码与特定的 V8 版本绑定——请使用目标 Electron 的 Node/V8 编译，否则无法加载 .jsc。这会提高自动化静态 JS 分析的成本，但并非坚不可破。
• 防御性熔断开关（@electron/fuses）——将打包后的二进制切换为强化的默认配置（禁用 RunAsNode、Node CLI 检查参数和 NODE_OPTIONS；启用内嵌 ASAR 完整性验证和 OnlyLoadAppFromAsar）。在打包后、afterPack 中运行：

  npx reashield electron fuses path/to/YourApp   # --dry to preview
  

bytenode 和 @electron/fuses 是可选依赖项，仅在使用这些命令时才会加载。编程接口：import { rewriteIpcChannels, compileToBytecode, recommendedFuses, applyFuses } from "reashield/electron"。

WASM 后端（核心数值逻辑）

将函数标记为 mode: "wasm"，REAShield 就会将其编译为真正的 WebAssembly 模块（直接生成二进制，无需外部工具链），并以同步方式实例化，因此行为保持不变。随后，算术逻辑会驻留在 wasm 字节中，脱离 REA 的 JS 模块图分析路径。目前支持：数值参数、const 局部变量、return、+ - * /、一元 -、带比较运算或 &&/||/! 条件的三元表达式，以及 Math.(max|min|abs|floor|ceil|round|sqrt|trunc)。超出此子集的内容会回退为原地混淆，并会报告出来（绝不会静默处理）。坦诚地说：wasm 属于更难、截然不同的分析领域——但并非坚不可破。

持久防护：测量，而非轻信

REA 经常发布新版本。reashield test 会比较你自己的加固前后产物并写入基线；已提交的 GitHub Action（.github/workflows/reashield-regression.yml）会针对多个 rea-agents 版本重新测量，并且当新版 REA 恢复出的内容超出基线允许范围时，测试会失败。随着时间推移，真正让防护保持强度的是这道回归门禁，而非任何单一的混淆技巧。

rea-agents 是可选的开发依赖项。若未安装，reashield test 会回退到静态代理指标（源映射、导入边、字符串泄露、受保护名称泄露、机密字符串移除）。

路线图

✅ 打包器插件（esbuild/Rollup/Vite）· ✅ Electron 路径（bytenode、防御性 fuse、动态 IPC 重写）· ✅ WASM 后端（数值子集 → 真实 wasm）。

下一步：扩展 WASM 子集（控制流、字符串）· 扩展服务适配器和身份验证辅助工具 · 针对摘要视图优化的诱饵 · ASAR 打包集成辅助工具。

许可证

MIT。使用它来保护你拥有并发布的代码。这里的任何内容都不是用来对付他人软件的武器。