hexvero

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/banner-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="docs/banner-light.svg">
  <img src="docs/banner-dark.svg" alt="hexvero – the first look at a binary or app bundle. Static facts with evidence, from Node alone." width="100%">
</picture>

[![CI](https://github.com/maximilianfeix/hexvero/actions/workflows/ci.yml/badge.svg)](https://github.com/maximilianfeix/hexvero/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/hexvero?style=flat-square&color=F2B84B&labelColor=1B1D21)](https://www.npmjs.com/package/hexvero)
[![Node](https://img.shields.io/badge/node-%E2%89%A5%2022.12-F2B84B?style=flat-square&labelColor=1B1D21)](package.json)
[![License](https://img.shields.io/badge/license-MIT-F2B84B?style=flat-square&labelColor=1B1D21)](LICENSE)

**English** · [Deutsch](README.de.md) · [Español](README.es.md) · [Français](README.fr.md) · [Português (Brasil)](README.pt-BR.md) · [Русский](README.ru.md) · [中文](README.zh.md) · [日本語](README.ja.md) · [한국어](README.ko.md)

[Try it](#try-it) · [Use cases](#use-cases) · [Install](#install) · [What it reads](#what-it-reads) · [CLI](#cli) · [Web UI](#web-ui) · [For AI agents](#for-ai-agents) · [Engines](#optional-engines) · [Limits](#limits) · [Compared with REA](#compared-with-rea) · [How it works](#how-it-works) · [Contributing](#contributing) · [FAQ](#faq)

</div>

---

**A fast, local, evidence-backed first look at software, for developers and AI agents.**

hexvero reads executables, Electron apps, APKs, archives, databases and network captures **without running them**. It tells you what the software contains, what it exposes, where each fact was read, how sure it is, and what it could not establish. One CLI, one MCP server for coding agents, one local web UI. Nothing leaves your machine.

![hexvero mapping an Electron app without running it: findings with file and line, every IPC channel with its senders and handlers, the preload's contextBridge members with their channels, and what changed in the next version](docs/demo/demo.gif)

<sub>25 seconds of real output on the example app in `examples/` · [step by step](docs/demo/electron-ipc.md)</sub>

<a id="try-it"></a>

## Try it

```bash
npx hexvero analyze ./MyApp.app/Contents/Resources/app.asar
```

Node.js 22.12 or newer is all it needs. From an empty npm cache the first result took one command and about nine seconds on a laptop, download included. A real run on the small Electron app in [`examples/`](examples/):

```text
$ hexvero analyze examples/notesdesk-1.4.0.asar
Summary
  Electron ASAR: 4 JavaScript modules, 6 IPC channels

Findings
  ○ nodeIntegration: true in a BrowserWindow  @ main.js:14
      contextIsolation is on for the same window, so page scripts do not get require(). Node integration keeps the renderer out of the Chromium sandbox.
  ○ sandbox: false in a BrowserWindow  @ main.js:15
      The renderer process runs without the Chromium sandbox.
  ● 6 IPC channels  @ main.js:25
      app:quit, notes:list, notes:save, settings:get, settings:set, shell:open (collections ipcChannels, ipc)
  ● 6 members exposed to pages as window.notesdesk  @ preload.js:4
      getSetting, setSetting, listNotes, saveNote, quit, openInShell (collection contextBridge)
  ○ 2 network endpoints read from the code  @ renderer/app.bundle.js:11
      ${…}/notes/sync, https://telemetry.notesdesk.example/collect (collection endpoints)
  ● 1 storage key read from the code  @ renderer/app.bundle.js:10
      notesdesk.token (collection storage)
  … (preload script, list of collections)

Next
  Which IPC channels can a page reach, and who handles them?
    hexvero collection examples/notesdesk-1.4.0.asar ipcChannels
  What does the preload script expose to web content?
    hexvero collection examples/notesdesk-1.4.0.asar contextBridge
  … (two more)
```

A filled dot is a fact read from the file, a hollow dot an inference from a pattern; `@ main.js:14` is where it was read. Settings are reported as written, never as assumed Electron defaults. `${…}` marks the part of an address that is computed at run time. The `windows` collection puts each window's `nodeIntegration`, `contextIsolation` and `sandbox` side by side as `true`, `false`, `computed` or `not written` and says what follows from them together; a value that rests on Electron's default for the version in `package.json` is marked `default on` / `default off`. The rules and their sources are in [docs/electron-findings.md](docs/electron-findings.md). The IPC finding is a filled dot only when every IPC-shaped call could be traced; otherwise the limitations name the calls that could not, with file and line.

<a id="use-cases"></a>

## What people use it for

**1. Understand an unfamiliar application.** You downloaded a binary, an Electron app or an APK. hexvero says what it is, what it exposes and where the evidence is, and suggests what to look at next. On a native program it names the hardening and the imports worth a look:

```text
$ cc -O2 -o demo examples/native/demo-v2.c && hexvero analyze demo
Findings
  ● Imports functions that start other programs or a shell: system
      Read from the import table. Whether and with what input they are called is not established by static reading; a call graph (hexvero calls) shows who calls them. (collection imports)
  ● Hardening: PIE yes, stack canary no, ARC no, code signature yes, stripped yes

$ hexvero calls demo radare2 main --goal system      # with radare2, rizin or Ghidra installed
radare2 path main → sym.imp.system · found
main
  └ sym._run_tool
    └ sym.imp.system
```

**2. Compare two versions.** What changed between two builds, list by list, with the item as evidence. Code that only moved is not reported as changed. Without a list name, `compare` counts the differences in every list both builds have, so you know where to look:

```text
$ hexvero compare examples/notesdesk-1.4.0.asar examples/notesdesk-1.5.0.asar
12 shared collection(s), 10 with differences
  collection      added  removed  changed  unchanged
  --------------  -----  -------  -------  ---------
  findings        4      6        0        1
  modules         0      0        3        1
  …
  webPreferences  0      0        2        2
  windows         0      0        1        0
  contextBridge   1      1        0        5
  …

$ hexvero compare examples/notesdesk-1.4.0.asar examples/notesdesk-1.5.0.asar webPreferences
webPreferences: 0 added, 0 removed, 2 changed, 2 unchanged · matched by file+windowName+key
  ~ main.js::win::nodeIntegration  value: true → false
  ~ main.js::win::sandbox  value: false → true

$ hexvero compare examples/notesdesk-1.4.0.asar examples/notesdesk-1.5.0.asar windows
windows: 0 added, 0 removed, 1 changed, 0 unchanged · matched by file+windowName
  ~ main.js::win  nodeIntegration: true → false, nodeIntegrationInEffect: "on" → "off", sandbox: false → true, sandboxInEffect: "off" → "on"

$ hexvero compare examples/notesdesk-1.4.0.asar examples/notesdesk-1.5.0.asar contextBridge
contextBridge: 1 added, 1 removed, 0 changed, 5 unchanged · matched by api+member
  + notesdesk::checkUpdate
  - notesdesk::openInShell
```

Nothing is ignored by default; code that only moved in a native binary is counted as `relocated`. Windows are matched by the variable they are assigned to (`win`), so adding a window does not mis-pair the others. An item found on one side only is `added` or `removed` only if the other side read the file it sits in; otherwise it is `unknown` (`?`).

**3. Let an AI agent investigate.** `npx hexvero setup --apply` registers the MCP server with the coding agents it finds (Claude Code, Codex, Cursor, VS Code, and 14 more), and `npx hexvero setup --skill --apply` installs a skill that teaches the investigation loop. The agent then opens a target, reads a small first answer with suggested next calls, pages only the lists it needs, and cites `file:line` for each claim. Text inside the target is treated as data, never as instructions; a test plants such text in a target to check it. See [For AI agents](#for-ai-agents).

### Why hexvero

- **It never runs what it reads.** Every format is parsed by code in this repository. Engines are optional and only ever read files.
- **Evidence and honesty.** Findings are `confirmed` or `inferred` and carry the file and line where a parser records one. `limitations` say what was skipped, cut or unreadable. A partial result says it is partial, down to each page of a list.
- **Measured, not claimed.** A [corpus](corpus/README.md) with written-down correct answers measures per kind of finding what is found, missed and wrongly reported, including on a set written by someone without access to hexvero. CI fails when a result gets worse. On that unseen set hexvero found more IPC channels, settings, endpoints and storage keys than REA 6.4.0 with far fewer false reports, and still misses a lot; both are shown [below](#compared-with-rea).
- **Small answers for agents.** The MCP catalog is 14 KB (3,300 tokens). A full Electron investigation of the corpus's hold-out app costs about 3,000 tokens; every list is a page with a hard byte budget and the complete result goes to a file on request ([numbers](docs/benchmarks.md#what-an-agent-sees)).
- **Large apps, read to the end.** A JavaScript app is read 5,000 files at a time; `--continue` and `--all` read the rest and nothing is read twice.
- **A local UI** with findings, virtualized tables, a hex viewer and a module graph. Loopback only, keyboard-usable.

<a id="install"></a>

## Install

Requires Node.js 22.12 or newer. Reading SQLite databases needs Node.js 22.13 or 24 and newer; on 22.12 everything else works and SQLite files are refused with a message saying so.

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

Or run without installing: `npx hexvero <command>`