hexvero

hexvero は、Electron アプリの2つのビルド（app.asar、.app、インストールディレクトリ、リリース ZIP）を比較し、リリースのセキュリティレビューや監査に役立つよう、ファイル名と両方のビルドにおける行番号とともに、内部で何が変わったかを示します。ファイルを読み取るだけで、実行はしません。

検出できる内容

npx hexvero demo がコピーする2つのビルド例（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 が読み取られます。
• 判定できなかった内容：1.5.0では main.js:33 で環境変数からチャンネル名を組み立てているため、shell:open は削除済みではなく、不明を表す ? として報告されます。

リリースポリシー（hexvero check）を使えば、これらをCIのゲートにできます。インターフェースメンバーの追加、外部ホストの追加、より許可的なウィンドウ設定、または ipcRenderer や fs などの特権オブジェクトを、そのままページに渡す変更を検出します。.app、インストールディレクトリ、リリース ZIP では、バイナリのバイト列から同梱された Electron ランタイムも読み取ります（Electron、Chromium、Node のバージョン、fuse、ASAR 整合性レコード、および日付付きの Electron リリースデータのスナップショットに基づき、該当する Electron 系統がまだサポートされているかどうか）。fuse の安全性が低下した場合、ポリシーはそれを検出します（docs/cli.md）。

_{examples/ にある2つのビルド例を比較するローカルWeb UI。実際の出力です。}

_{25秒、実際の出力：2つのリリース、ページから呼び出せる新しいメンバーとその読み取り元2か所、削除ではなく不明として示されるチャンネル、そして終了コード3で失敗するポリシー · mp4 · docs/demo/release-gate.tape を使って録画}

試してみる

npx hexvero demo

必要なのは Node.js 22.12 以降だけです。demo は 2 つのサンプルビルドとサンプルポリシーを ./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 に同じ比較が表示され、両方のビルドのソース行が並べて表示されます。すべての手順と完全な出力については、walkthrough をご覧ください。

自分のアプリで使う

hexvero にアプリの 2 つのビルドを指定します。リリース済みのものと、これからリリースするものです。

プラットフォーム	アプリの場所
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 はレビューをオフラインで閲覧できる 1 つの HTML ページとして書き出します（Markdown の場合は report.md）。init は、すべてのルールを fail に設定し、旧ビルドがすでに接続しているホストを許可した .hexvero/policy.json を作成します。check は、合格なら 0、違反があれば 3、判定できない場合（必要な値が実行時に計算される、または読み取れなかった場合）は 4 で終了します。現在の状態を受け入れるには、1 回だけ --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 ファイルには 22.13 以降、または 24 以降が必要です）。

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

または、インストールせずに実行できます：npx hexvero <command>。

AI エージェント向け

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 では、サーバーとスキルを 1 つのプラグインとして利用できます。/plugin marketplace add maximilianfeix/hexvero を実行し、続けて /plugin install hexvero@hexvero を実行してください。それ以外のクライアントでは、stdio 経由で npx -y hexvero mcp を実行できます。再現可能な結果を得るには、バージョンを固定してください（npx -y [email protected] mcp）。hexvero_compare や hexvero_check を含む 16 個のツールを利用でき、回答は次に呼び出すとよいツールを提案する短いページとして返されます。対象内のテキストはデータとして扱われ、指示として扱われることはありません。対応する 18 個のクライアント、ツール、およびエージェントが受け取る内容については、docs/mcp.md をご覧ください。

制限事項

• ファイルを読み取りますが、プログラムは実行しません。そのため、検出結果はコードに含まれる内容を示すものであり、実行時の動作や、悪用可能かどうかを示すものではありません。チェックに合格した場合、読み取った内容にポリシーに反する新たな点がなかったことを意味します。
• 見落としがあったり、誤った結果を出したりすることがあります（精度）。リストにないことは、あることよりも弱い証拠です。
• hexvero check は 7 つのルールを判定します。脆弱性スキャナーではなく、合格してもセキュリティ上の保証にはなりません。Content Security Policy、権限ハンドラー、shell.openExternal の呼び出しはチェックされず、fuse のチェック対象はパッケージ化されたビルドに限られます（読み取らない内容）。
• 対象を実行しなくても安全が保証されるわけではありません。悪意のあるファイルを解析する場合も、サイズ、深さ、時間の制限内で、攻撃者が制御するバイト列を処理します。

制限事項の全一覧は、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 ラベルの付いた issue は、半日程度で取り組める規模です。コードの構成については、仕組みをご覧ください。誤った事実や不足している事実を見つけた場合は、hexvero doctor の出力と、共有できる場合はそのファイルを添えて、バグを報告してください。hexvero がリリースについて正しい情報を示した場合は、スターを付けていただけると、ほかの人にも見つけてもらいやすくなります。

FAQ

hexvero はファイルを実行したり、アップロードしたりしますか？

いいえ。対象はバイト列として解析され、実行されることはありません。UI サーバーはセッションごとのトークンを使って 127.0.0.1 にバインドし、ほかのホストからの接続を拒否します。コードベースにはテレメトリーもネットワーク呼び出しもありません。クラウドホスト型エージェントを通じて hexvero を使う場合、エージェントが要求した結果は、ほかのツール出力と同様に、そのモデルプロバイダーへ送信されます。共有したくないファイルについては、この点にご留意ください。

これは逆コンパイラーですか？

それ自体は違います。組み込みの解析機能では、構造、シンボル、文字列、インポート、メタデータ、強化に関する情報を確認できます。逆アセンブルや擬似コードを利用するには、radare2、rizin、または Ghidra をインストールし、hexvero provider または hexvero calls を使用してください（オプションのエンジン）。

「静的」なら「安全」ということですか？

悪意のあるファイルを解析する場合も、攻撃者が制御するバイト列を処理することになります。hexvero はすべてのパーサーに対し、サイズ、件数、深さ、ワーカーのタイムアウト、ヒープの上限を設定しています。また、テストには切り詰められた入力やサイズ超過の入力が含まれています。しかし、どのような細工が施されたファイルに対しても安全であると証明されたパーサーはありません。結果は判定ではなく、証拠として扱ってください。

Windows には対応していますか？

パーサー、CLI、MCP サーバー、UI は Windows で動作します（CI では Windows と macOS でテストスイートを実行しています）。エンジンのプロセス処理は POSIX のみでテストされています。

法的事項

hexvero は、自分が所有するソフトウェア、オープンソースソフトウェア、または調査を許可されているソフトウェアにのみ使用してください。DISCLAIMER.md をご覧ください。

ライセンス

MIT