reverseai

https://github.com/user-attachments/assets/884cff5d-e37e-49c3-9bb7-8fbcf118e2ee

Why · What it analyses · How it works · The tools · Secure containers · AI analyst team · Quick start · Roadmap

ReverseAI is an open-source engine for static reverse engineering of untrusted
files. It opens programs, Android apps and JavaScript packages without running
them, puts the heavy analysis tools inside locked, offline containers, and reports as
verified only what it can prove from the file's own bytes. Every answer says where in
the file it comes from, which tool produced it and whether ReverseAI verified it
or it is a tool's interpretation.

It works from the command line and from AI agents: its MCP server lets Claude Code,
Codex, Cursor or any other Model Context Protocol client investigate a file, while
every answer it receives stays checkable and the file never leaves its locked setup.
On top of it, an optional AI analyst team (the hive) splits a native program
among parallel agents, has an independent council challenge every part, and rebuilds
the program as C or C++ that compiles and is checked against the original.

Why ReverseAI

Looking inside a suspicious file usually means trusting a large toolchain with
it, and then trusting whatever the tool, or an AI model, says about it.
ReverseAI removes both kinds of blind trust:

• The file is never executed. It is copied once into a frozen, fingerprinted
  snapshot and read as data. No sample code, install script or package manager
  ever runs.
• Heavy tools are locked away. Decompilers and parsers run in a fresh
  container per question, with no network, a read-only system, no privileges and
  hard limits. Nothing of your home folder or workspace is visible to them.
• Nothing is taken on faith. ReverseAI recomputes every byte-level fact a
  tool reports, such as headers, offsets, matches and code anchors, from the
  original bytes. A single mismatch rejects the tool's whole answer, so a
  compromised or buggy tool can hide evidence but cannot invent verified evidence.
• Facts and interpretations stay apart. Decompiled code and call graphs are
  useful but are a tool's reading; they are always labelled as such and can never
  overrule a verified fact.
• Open and reproducible. MIT-licensed, built on official open-source tools
  pinned by hash, with no Python dependencies. The same file and settings give the
  same report.

What it analyses

You can ask for a full report on a file (analyze) or ask one precise
question (query): list the functions, decompile one, show who calls it, search
the strings, read bytes at an address, inspect an Android class or method, or page
through a JavaScript application. The full list of questions is in the
usage guide.

Every report comes as JSON and Markdown and sorts findings into four groups:

Supported means the bytes say exactly this; it never means the file is safe,
malicious or behaves in a certain way.

How it works

1. Freeze the file. You approve one regular file. ReverseAI copies it into a
   private snapshot and fingerprints it with SHA-256; everything afterwards refers
   to that fingerprint. Links, hard-linked files and files that change while being
   read are refused.
2. Go through the gateway. A gateway accepts only a fixed list of operations,
   each with its own time and output budget. Nothing else can be asked of a tool.
3. Read simple formats directly. ReverseAI's own parsers, written with the
   Python standard library alone, decode executable headers, imports, strings,
   APK archives, the Android manifest, DEX bytecode, gzip and tar streams, ASAR
   archives and JSON. Their results are the verified reference.
4. Run heavy tools in a locked container. Ghidra, JADX, LIEF, YARA-X and the
   JavaScript parser run one fresh container per request, as described
   below.
5. Check the tool's answer. The host recomputes every byte-level fact the
   tool reports from the original bytes and rejects the whole reply on any
   mismatch. A decompiled function or Java method is accepted only if it is
   anchored to code that ReverseAI located and verified itself; its text and
   relationships remain the tool's interpretation.
6. Record evidence. Each item of evidence binds the file fingerprint, the tool
   and its version, the operation, and the exact byte range with its own hash. For
   a file inside an archive it also records which member it came from and how that
   member was rebuilt from the original bytes.
7. Write findings. Analysts turn evidence into findings, and every finding
   must cite its evidence.
8. Review independently. A reviewer re-reads the cited bytes, rebuilds
   compressed members from the original archive and applies a fixed rule for each
   kind of claim. What it cannot confirm is not reported as supported.
9. Report. JSON and Markdown reports name each tool version and container
   image, and are written with private permissions into a new or empty folder.

The tools

ReverseAI uses official releases of established open-source tools. Each one was
downloaded once, verified against its published hash and built into a local
image; at analysis time nothing is downloaded, pulled or installed.

Each tool keeps its own license; see third-party notices.

The secure container infrastructure

Every contained tool runs under the same locked profile, enforced on each run and
verified against the real Docker engine:

Proven, not assumed. A native verifier inspects each image and the running
configuration, then starts control containers that try to reach the network,
write to the file system, gain privileges, spawn unlimited processes, exhaust
memory, run past their time and flood their output. Each attempt must be stopped.
Known-answer files then check that the tool still gives correct results. Every
run writes a receipt naming the image, lock, verifier and outcome.

Honest boundaries. Docker, its virtual machine and kernel, and the ReverseAI
host program are trusted; the built-in parsers run on the host, outside the
containers. Containment is currently proven for Linux ARM64 containers under
Docker Desktop on macOS; other platforms need their own proof. The full model is
in the security guide.

AI analyst team (the hive)

The hive turns ReverseAI's evidence into a rebuilt program, fast and with every step
checked by someone or something other than its author:

• The queen is code, not a model. She exports the program map, asks one planner
  agent to split the functions into modules and freeze a shared contract header,
  schedules the bees, compiles, links and computes the verdict. She cannot write code,
  vote or overrule a check.
• Bees work in parallel, one module each, each with its own ReverseAI MCP server
  so contained Ghidra questions run side by side. Claude bees have no shell and no web,
  and can read and write only in their own folder; every claim they make cites the
  finding IDs ReverseAI returned.
• An independent council of three non-authors per module, each with its own lens
  (control flow and arithmetic, input and output, data and memory), tries to refute the
  module against the original's assembly. Only differences backed by evidence count;
  they go back for repair, and a module still refuted is reported as disputed. Every
  seat must answer, and code changed after a council read goes back to the council.
• The final word is deterministic. A checker re-runs every question a claim cites
  and drops any claim whose finding IDs do not come back for the same file; the rebuild
  must compile cleanly, in a closed compiler file system with inline assembly disabled;
  and, only if you allow it, the original and the rebuild run the same conformance cases
  and must give the same exit code, the same stdout and files (compared by hash) and the
  same stderr once the program's own path is masked (its first 2,000 characters).
• Before spending anything, a pre-flight stops packed programs (UPX, VMProtect,
  Themida and others, high-entropy code, loader-only imports). The hive rebuilds in C,
  or in C++ when the program shows C++. Codex bees and mixed Claude/Codex councils are
  available and are refused automatically while the Codex sandbox lets a probe reach the
  network.

It runs on your own Claude Code (and optionally Codex) subscription, with no API key,
and the ReverseAI engine itself stays model-free.

* The 127-case battery was written outside the hive (compression levels, block modes, multithreading, cross-decompression,
corrupt frames) and catches a one-character change in an error message. Both runs used the queen as it was before the review of
2026-11-01, which let 13 lz4 modules be changed after their council read (link and behaviour repairs) without a new read; the
current queen sends such modules back to the council. Both behaviour batteries ran on the final binary.

python3 -m hive run --inputs /path/to/approved-inputs --file program --out new-hive-run --bees 5
python3 -m hive run --inputs /path/to/approved-inputs --file program --out new-hive-run --run-original

--run-original lets the hive run the original program on the conformance cases: use it
only for software you would run anyway, never for malware. The hive guide
covers roles, safety, the pre-flight, languages, bee models and the workspace.

Quick start

Start with the step-by-step guide, or tell your coding agent:
"Read docs/AGENT_SETUP.md and follow it." The setup prompt
asks for your approved input directory before connecting your client.

Requirements: Python 3.12 or later, with venv and pip. Host analysis needs no
Docker. On Windows, use CPython 3.12.4 or later and the paths in
INSTALL; every analysis needs a new output directory.

Recommended on macOS or Linux: clone the repository (or use a trusted checkout
already on your machine) and install it in a dedicated virtual environment:

git clone https://github.com/dagoSte/reverseai.git
cd reverseai
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --no-index --no-deps .
reverseai doctor

The install uses local source without a package download. doctor reads no
sample and never pulls, builds or starts a container; inspect its tool rows as
well as its exit status.

Other local installation paths:

The uv path creates a tool environment; use the executable location it prints.
Editable installs keep the checkout on Python's import path: use a dedicated
venv and keep the checkout in place. All paths use trusted source or an approved
local wheel; never install an analysed package or run its install scripts.

With the recommended venv active, analyse a file or ask one question:

reverseai analyze "/path/to/approved-file" --out new-report-folder
reverseai query "/path/to/approved-file" --query list_strings --out new-query-folder

Each output folder contains report.json and report.md. Choose a fresh folder
for each call. The usage guide lists format-specific questions
and paging. Contained tools need Docker and their exact local images; the
installation guide covers building them from approved inputs
(offline except Ghidra's build, which still needs network) and the native proof.

Use it from an AI agent

Start ReverseAI as a local MCP server over a folder of files you approved; the agent
sees one tool per question plus list_files and analyze_file:

claude mcp add --transport stdio reverseai -- /path/to/.venv/bin/reverseai mcp --inputs /path/to/approved-files

The server talks only over standard input and output, reads only files inside that
folder, runs a contained tool only when you add its flag (for example --with-ghidra),
and marks every quoted text from the files as untrusted. Answers are compact by default
(findings and verdicts without evidence bodies); an agent asks for view=full when it
needs everything. With --with-ghidra, prepare_file analyses a program once and the
export tools then page through all of its functions, calls, references, strings and
complete pseudocode. Results go to your agent and,
through it, to the agent's model provider, including text quoted from the files: use a
provider and plan you trust with that content. Setup for Claude Code, Codex and Cursor,
and the full security model, are in the MCP guide.

Use cases

The commands below assume the virtual environment from the quick start is active and
that each file has been copied into a folder of approved inputs. Every analyze and
query command writes its JSON and Markdown report into a new folder (prepare prints a
short receipt instead); nothing is executed. Prompts for an
agent work once the MCP server is connected as shown above.

Check an Electron app before installing it

The app's code is in app.asar (on macOS inside Contents/Resources/). List what it
contains, look for process spawning, then let the parser show the real calls:

reverseai query app.asar --query analyze_javascript_application --arg detail=summary --out check-app
reverseai query app.asar --query analyze_javascript_application --arg detail=hints --arg category=shell --out check-app-shell
reverseai query app.asar --query analyze_javascript_application --arg detail=calls --with-jsparser --out check-app-calls

Agent prompt: "Does the Electron app in the folder start other processes, read credentials or
contact hard-coded endpoints? Cite the file and byte range for every claim."

Review an Android app before it reaches your devices

reverseai query app.apk --query inspect_android_package --out review-apk
reverseai query app.apk --query search_android_classes --arg query=Activity --out review-classes
reverseai query app.apk --query inspect_android_method --arg class='Lcom/example/MainActivity;' --arg method=onCreate --with-jadx --out review-oncreate

The first report lists the package's files and its manifest (package name, version,
permissions); copy a class name exactly as the second report shows it.

Agent prompt: "Which permissions does this app declare, and which of its methods call the
network or read contacts? Separate verified facts from decompiled code."

Vet an npm package before adding the dependency

Download the package tarball without running anything, then read it:

npm pack [email protected] --ignore-scripts
reverseai query some-package-1.2.3.tgz --query analyze_javascript_application --arg detail=package --out vet-package
reverseai query some-package-1.2.3.tgz --query analyze_javascript_application --arg detail=hints --out vet-hints
reverseai query some-package-1.2.3.tgz --query analyze_javascript_application --arg detail=modules --with-jsparser --out vet-modules

The package report shows its package.json declarations, install scripts included; they
are read, never run.

Agent prompt: "Compare version 1.2.3 and 1.2.4 of this package: which install scripts,
imports or sensitive calls are new?"

Triage a suspicious program

reverseai query sample.exe --query binary_overview --out triage-overview
reverseai query sample.exe --query search_strings --arg query=http --out triage-urls
reverseai query sample.exe --query list_procedures --with-ghidra --out triage-functions
reverseai analyze sample.exe --with-lief --with-yarax --with-ghidra --out triage-full

The same works for Linux (ELF) and macOS (Mach-O) programs. A universal macOS binary is
recognised but not yet split into its architectures, and a packed program shows little
of its real code; recognising packers is on the roadmap.

Agent prompt: "Profile sample.exe: format, imports, notable strings, and what its entry
function calls. Mark which findings are verified and which are Ghidra's reading."

Rebuild a program you are allowed to rebuild

For software whose licence permits reconstruction, or a program whose copyright you hold
and whose source was lost, prepare the analysis once and export it page by page; an agent
can then rebuild the program function by function from the cited evidence. For a
malicious sample, use the same exports only to reconstruct its logic as readable,
annotated code for analysis: never compile or run it outside an isolated lab you are
authorised to use.

reverseai prepare tool.bin --with-ghidra --json
reverseai query tool.bin --with-ghidra --query export_program --arg part=functions --arg limit=32 --out rebuild-functions
reverseai query tool.bin --with-ghidra --query export_function --arg entry=0x401000 --arg part=info --out rebuild-info
reverseai query tool.bin --with-ghidra --query procedure_pseudo_code --arg mode=paged --arg entry=0x401000 --arg text_start=0 --out rebuild-code

Copy a real entry from the function page in place of 0x401000, and follow each
page's next cursor. Everything Ghidra reconstructs stays labelled derived, and ReverseAI
never compiles or runs anything: building the rebuilt program, or comparing it with the
original, is a separate step that you run only where you are entitled to (see the
legal notice). The prepared analysis is kept in a
private cache on your machine (see Your data).
Details are in the usage guide.

Agent prompt: "Prepare tool.bin, list its functions page by page, and rebuild it in C
starting from the functions that call nothing else. Cite the export page for each
function you write."

Or let the AI analyst team do it end to end: it plans,
rebuilds in parallel, has every module challenged by an independent council, compiles
and links the result, and re-checks every citation. The hive is a separate layer: it
compiles the rebuild, and it runs the original only when you pass --run-original.

Keep an evidence record for an audit or an incident

mkdir -p evidence
reverseai analyze vendor-agent.exe --with-lief --with-yarax --out evidence/vendor-agent

report.json records the file's SHA-256, every tool and image used, and for each
finding the exact byte range it rests on, so a colleague or auditor can check the same
facts against the same file later.

Platforms

Roadmap

Available today

• Native programs on Linux, Windows and macOS: structure, imports, strings, and
  with Ghidra functions, decompiled code, assembly, calls and cross-references.
• Android apps: manifest, classes, methods and references, and decompiled Java
  with JADX.
• JavaScript applications in ZIP, Electron ASAR, npm package or bundle form:
  inventory, declarations, hints, and syntax with the Babel parser.
• Offline installation, a setup check, reproducible packages and the MIT license.
• An MCP server (protocol revision 2026-07-28, with older clients supported) that
  gives AI agents the same verified questions, confined to a folder you choose.
• Reconstruction export: a Ghidra analysis prepared once per file and kept in a
  private cache, then each function's complete pseudocode, assembly, calls, references
  and strings, and the whole program's functions, calls, references and strings,
  exported in pages over the command line and MCP; compact answers for agents by
  default. The prepared analysis is limited to 64 MiB, which in practice bounds the
  size of program it can hold; a 10,000-function test program is proven.
• AI analyst team (the hive): a queen in code, parallel builder bees, an independent
  council and a deterministic evidence checker that rebuild native programs as C or
  C++; a pre-flight for packed programs; optional Codex bees and mixed councils.

Next

• x86-64: container images for Intel and AMD machines (Linux servers, Windows
  PCs, Intel Macs), with the same offline, unprivileged containment proven natively
  on each. Today the containers run on ARM64 (Apple silicon and Linux ARM64);
  x86-64 programs can already be analysed there.
• Reconstruction, next steps: recognising known libraries, per-function comparison
  against the original in an emulator, and more languages (Java for Android apps).
• Benchmark: measured accuracy on a public corpus of files with known
  answers, with the method and raw results published.

Later

• Enterprise mode: the same engine hosted on our infrastructure and reachable
  over MCP, for teams that need central policy and audit trails.
• Clean-room kit: evidence-cited functional specifications that support
  clean-room reimplementation.

Responsible use and legal notice

ReverseAI is a tool for examining files you are entitled to examine. How you use it is
your responsibility.

• Intended purpose. ReverseAI is built for defensive security work: examining
  suspicious or potentially dangerous software, such as malware, untrusted packages and
  third-party components, to understand its risks without running it, for incident
  response, threat analysis and pre-adoption review. It also supports reconstructing
  software whose licence permits it or whose copyright you hold, such as a program
  whose source was lost.
• Analyse only what you may analyse. Use ReverseAI on files you own or are authorised
  to examine. Licence agreements of third-party software may restrict reverse
  engineering, decompilation or disassembly, and the law of your country may allow such
  activities only for specific purposes (for example interoperability or security
  research) and under specific conditions. Complying with those licences and laws,
  including copyright, trade-secret, computer-misuse, data-protection and export-control
  rules, is up to you.
• No misuse. Do not use ReverseAI to infringe intellectual property, circumvent
  protection measures, build or improve malware, or access systems or data without
  authorisation.
• No advice. Findings, decompiled code and any AI-generated summary can be incomplete
  or wrong. Check them before relying on them. Nothing ReverseAI produces is legal,
  security or compliance advice.
• Dangerous files stay dangerous. ReverseAI never executes the files it reads, but the
  files themselves may be malicious. Store and handle them according to your
  organisation's policy.
• Your data. Reports can contain text taken from the analysed files. When an AI agent
  uses ReverseAI, results go to that agent and its model provider. Preparing a file for
  Ghidra keeps its analysis, which includes the file's bytes, in a private cache on your
  machine (~/Library/Caches/ReverseAI/ghidra/v1 on macOS, ~/.cache/reverseai/ghidra/v1
  or under $XDG_CACHE_HOME on Linux) until newer entries replace it; delete that folder
  to remove every prepared analysis at once.
• No warranty, no liability. ReverseAI is provided "as is", without warranty of any
  kind, under the MIT License. To the maximum extent permitted by applicable
  law, the authors and contributors are not liable for any claim, damages or other
  liability arising from the use or misuse of the software or of its results, including
  any analysis of third-party software or files.
• Trademarks. Names of third-party tools and products belong to their owners; their
  mention does not imply endorsement.

Open source

ReverseAI is free and open source under the MIT License. The engine,
the containment profile and the verification rules stay open; the planned
enterprise mode adds hosting and integration on top of the same open core.
Third-party tools keep their own licenses, listed in the
third-party notices. Release history is in the
changelog.

Created by Stefano D'Agostino.