hexvero

hexvero 会比较 Electron 应用的两个构建版本（app.asar、.app、安装目录或发行 ZIP），并指出其中的变化，以及两边对应的文件和行号，供版本发布的安全审查或审计使用。它只读取文件，不会执行任何内容。

它能发现什么

以下示例构建由 npx hexvero demo 复制（NotesDesk 1.4.0 和 1.5.0）：

• 新增 IPC 和桥接接口：window.notesdesk.checkUpdate 是 1.5.0 新增的接口，在 preload.js:9 中读取，并关联到 main.js:30 中针对 update:check 的 ipcMain.handle。
• 会改变页面可执行操作的窗口设置：在 main.js::win 中，nodeIntegration: true → false 和 sandbox: false → true，报告为权限更宽松。
• 新增网络主机和存储键：main.js:30 中对 updates.notesdesk.example 的请求；在 renderer/app.bundle.js:15 中读取的 localStorage 键 notesdesk.telemetry。
• 无法确认的内容：shell:open 被报告为未知（?），而非已移除，因为 1.5.0 会在 main.js:33 中根据环境变量构建通道名称。

发布策略（hexvero check）可将这些检查作为 CI 门禁：新增接口成员、新增外部主机、权限更宽松的窗口，或直接交给页面的特权对象（例如 ipcRenderer 或 fs）。对于 .app、安装目录或发行 ZIP，它还会从二进制文件字节中读取随包分发的 Electron 运行时信息（Electron、Chromium 和 Node 版本、fuse、ASAR 完整性记录，以及根据 Electron 发布数据的带日期快照判断 Electron 版本线是否仍受支持），并在 fuse 变得不再安全时由策略发出标记（文档）。

_{本地 Web UI 正在比较 examples/ 中的两个示例构建。真实输出。}

_{25 秒，真实输出：两个版本、一个页面可以调用的新成员及其读取位置、一个标记为未知而非已移除的通道，以及返回退出码 3 的策略检查失败 · mp4 · 使用 docs/demo/release-gate.tape 录制}

试用

npx hexvero demo

只需 Node.js 22.12 或更高版本。demo 会将两个示例构建和一份示例策略复制到 ./hexvero-demo，并显示变更内容（标记为 … 的部分会缩短）：

$ npx hexvero demo
What changed between notesdesk-1.4.0.asar and notesdesk-1.5.0.asar
  Two builds of a small example Electron app, read statically. Nothing was executed.

  interfaces (2)
    + preload.js::notesdesk::checkUpdate  @ b: preload.js:9, handler main.js:30 · link direct
    - preload.js::notesdesk::openInShell  @ a: preload.js:9, handler main.js:30 · link direct
  …
  ipcChannels (2)
    + update:check  @ b: receiver main.js:30, sender preload.js:9
    ? shell:open  @ a: receiver main.js:30, sender preload.js:9
        the other side has values there that could not be resolved
  windows (1)
    ~ main.js::win  @ b: main.js:8
        nodeIntegration: true → false, nodeIntegrationInEffect: "on" → "off", sandbox: false → true
  …
  endpoints (1)
    + main.js::fetch::https://updates.notesdesk.example/latest.json  @ b: main.js:30 · literal
  …
  Next
    npx hexvero compare hexvero-demo/notesdesk-1.4.0.asar hexvero-demo/notesdesk-1.5.0.asar interfaces
    npx hexvero compare hexvero-demo/notesdesk-1.4.0.asar hexvero-demo/notesdesk-1.5.0.asar --report report.md
    npx hexvero check hexvero-demo/notesdesk-1.4.0.asar hexvero-demo/notesdesk-1.5.0.asar --policy hexvero-demo/policy.json
    npx hexvero ui --demo --open

npx hexvero ui --demo --open 会在本地 Web UI 中显示相同的对比，并排展示两个构建的源代码行。查看包含完整输出的每个步骤：操作指南。

在自己的应用上使用

让 hexvero 对比应用的两个构建版本：已发布的版本和即将发布的版本：

平台	应用所在位置
macOS	应用程序包本身、/Applications/YourApp.app，或 YourApp.app/Contents/Resources/app.asar
Windows	安装目录（其中包含 YourApp.exe 和 resources\），或其 resources\app.asar
Linux	安装目录（其中包含 resources/ 和 Electron 运行时文件），或其 resources/app.asar
发布构建	原样发布的 .zip 文件

安装程序（.dmg、安装用 .exe、AppImage）不会被作为 Electron 应用读取：请先安装或解压它们。

npx hexvero compare old/YourApp.app new/YourApp.app --report report.html
npx hexvero init old/YourApp.app
npx hexvero check old/YourApp.app new/YourApp.app --policy .hexvero/policy.json

compare --report 会将审查结果写入一个可离线查看的 HTML 页面（Markdown 格式则写入 report.md）。init 会生成 .hexvero/policy.json，将每条规则设为 fail，并允许旧构建已连接的主机。check 的退出码为：通过时 0、违反规则时 3、无法判定时 4（所需值在运行时计算，或未被读取）。若要接受当前已有的内容，添加 --baseline .hexvero/baseline.json --update-baseline 执行一次；之后只有出现新发现时才会失败。

在 CI 中使用

GitHub Actions 任务，固定到某个版本，以免发布更新在不通知的情况下改变结果：

jobs:
  hexvero:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
        with:
          node-version: 24
      # Build your app and fetch the previous release here, e.g. into previous/ and dist/.
      - run: npx --yes [email protected] check previous/app.asar dist/app.asar --policy .hexvero/policy.json

完整工作流包括基线、Markdown 任务摘要，以及用于代码扫描的最小权限 SARIF 上传：docs/ci.md。

结果有多可靠？

每条事实都会说明读取方式（literal、inferred、link direct）及其来源；无法读取的内容会列出对应的文件和行号。在最新的盲测集中（由无法访问 hexvero 的人员编写），它找出了 64 个 IPC 通道中的 52 个，且没有误报；其他列表中仍有漏报和误报。所有数字、每一处漏报及完整的限制列表，请参阅：准确性与限制。

文档

• 操作指南：演示、对比、检查、单个构建、Web UI，并附有实际输出
• CLI 参考 · CI · MCP 服务 · 策略架构
• 准确性与限制 · Electron 规则及其来源 · 基准测试 · 准确性语料库
• 读取内容：Electron 和 JavaScript，以及原生二进制文件、APK、.NET、WebAssembly、EVM 等，还有可选引擎
• 与 Electronegativity 和 REA 对比
• 变更日志

安装

需要 Node.js 22.12 或更高版本（SQLite 文件需要 Node.js 22.13 或 24 及更高版本）。

npm install -g hexvero        # the hexvero command
hexvero doctor                # checks Node, node:sqlite and optional engines

也可以不安装，直接运行：npx hexvero <command>。

面向 AI Agent

npx hexvero setup --apply          # registers the MCP server with the coding agents it finds (dry run without --apply)
npx hexvero setup --skill --apply  # installs a skill that teaches the investigation loop

在 Claude Code 中，服务和技能也作为一个插件提供：/plugin marketplace add maximilianfeix/hexvero，然后运行 /plugin install hexvero@hexvero。其他客户端可以通过标准输入输出运行 npx -y hexvero mcp；若要获得可复现的结果，请固定版本（npx -y [email protected] mcp）。共有 16 个工具，包括 hexvero_compare 和 hexvero_check；回答是包含建议后续调用的小型页面，目标中的文本会被视为数据，而非指令。支持的 18 个客户端、工具以及 Agent 会收到的内容：docs/mcp.md。

限制

• 它会读取文件，但不会运行程序，因此发现反映的是代码包含的内容，而非代码在运行时的行为，也不代表内容是否可被利用。检查通过只表示在已读取的内容中没有发现违反策略的新问题。
• 它可能会漏掉问题，也可能判断错误（数字）。某项内容未出现在列表中，所能提供的证据弱于它出现在列表中的情况。
• hexvero check 会评估七项规则；它不是漏洞扫描器，检查通过也不代表安全结论。它不会检查内容安全策略、权限处理程序和 shell.openExternal 调用，且只会检查已打包构建的熔断器（未读取的内容）。
• 不执行目标文件并不意味着安全保证：解析恶意文件仍会处理攻击者控制的字节，但会受到大小、深度和时间限制。

完整列表：docs/accuracy.md。

参与贡献

npm install && npm run check      # typecheck, lint, format, unit tests, shape rules
npm run e2e                       # the four user flows on real inputs (compiler and engines if installed)

CONTRIBUTING.md 列出了审查工作流强制执行的规则；标记为 good first issue 的问题适合在一个下午内完成；代码布局说明见：工作原理。发现错误或遗漏的信息？请附上 hexvero doctor 的输出，并在可以分享时附上文件，提交错误报告。如果 hexvero 曾告诉你某个版本的真实信息，请点个星，帮助其他人找到它。

常见问题

hexvero 会运行或上传我的文件吗？

不会。目标文件会按字节解析，不会执行任何内容。UI 服务会绑定到 127.0.0.1，并使用每个会话独有的令牌，同时拒绝其他主机。代码库中没有遥测，也不会发起网络请求。通过托管在云端的 Agent 使用 hexvero 时，该 Agent 请求的结果会像其他工具输出一样发送给其模型提供商；对于你不愿分享的文件，请留意这一点。

这是反编译器吗？

本身不是。内置分析会提供结构、符号、字符串、导入项、元数据和加固信息。若要进行反汇编并生成伪代码，请安装 radare2、rizin 或 Ghidra，并使用 hexvero provider 或 hexvero calls（可选引擎）。

“静态”就等于“安全”吗？

解析恶意文件仍然是在处理攻击者控制的字节。hexvero 会限制每个解析器的资源使用（大小、数量、深度、工作进程超时和堆上限），其测试也包含截断和超大输入，但没有解析器能被证明可以安全处理所有精心构造的文件。应将结果视为证据，而非结论。

Windows 呢？

解析器、CLI、MCP 服务和 UI 均可在 Windows 上运行（CI 会在 Windows 和 macOS 上运行测试套件）。引擎进程处理仅在 POSIX 上测试。

法律声明

仅可对你拥有、已开源或获准检查的软件使用 hexvero。请参阅 DISCLAIMER.md。

许可证

MIT