# borer

> borer is a reverse-engineering engine built for AI agents. It gives an agent what a human reverse engineer brings to a binary: it finds the code that matters, reads it as C, follows data through it and writes down what it learned. It is one Rust binary: an MCP server when run with no arguments, a command-line tool with them. There is no GUI, and no Ghidra, IDA or Binary Ninja underneath.

Version 0.2.1-dev (v0.2.1-97-g4d2ebe1e). 41 MCP tools and 62 resource templates. Every page below is plain Markdown; [llms-full.txt](/llms-full.txt) has all of it in one file, and [mcp.json](/mcp.json) is the server's tools/list and resource templates as JSON.

## Docs

- [Why borer exists](/docs/why-borer-exists.md): Most software that matters ships as binaries nobody can read: malware, closed firmware, game clients, drivers, the third-party libraries inside every product.
- [What it is for](/docs/what-it-is-for.md): Formats: PE, ELF, Mach-O, raw code and memory dumps.
- [Where it is going](/docs/where-it-is-going.md): The aim is an agent that takes a binary and returns what a skilled reverse engineer would: what it does, what is dangerous in it, and the evidence for each claim.
- [Install](/docs/install.md): One command downloads the latest release for your machine, checks it against the release's SHA256SUMS, and registers borer with every MCP client it finds.
- [Use it from an agent](/docs/use-it-from-an-agent.md): Any address argument takes `0x` hex, decimal, or a name.
- [Use it from the command line](/docs/use-it-from-the-command-line.md): Useful flags: `--pack <file>` loads target knowledge, `--no-pdb` skips the companion PDB, and `--arch x86|x64|arm64` (with `--base`, `--entry` and `--regions`) maps raw code or a dump.
- [More](/docs/more.md): Live processes (Windows only): `live_attach` opens a running process read-only (`PROCESS_VM_READ`) and maps the loaded binary onto it.
- [Network access](/docs/network-access.md): borer sends nothing about what you analyze, and has no telemetry or crash reporting.
- [Limits](/docs/limits.md): No instruction sets beyond x86, x86-64, arm64 and 32-bit ARM.
- [Workspace](/docs/workspace.md): Workspace
- [Contributing](/docs/contributing.md): `python scripts/gate.py` runs what CI runs: fmt, clippy with `-D warnings`, tests, rustdoc, `cargo deny`, typos, ruff and a smoke test of the real server.
- [License](/docs/license.md): borer is free software under the GNU Affero General Public License v3.0 (AGPL-3.0-only).
- [Example session](/docs/session.md): Real tool calls and their answers on a fixed binary.

## Reference

- [Tools](/docs/tools.md): All 41 tools by area, each linking to its parameters and a call.
- [Resources](/docs/resources.md): All 62 borer:// URI templates and what each answers.

## Load

- [load_binary](/docs/tools/load_binary.md): Load a PE, ELF or Mach-O file (a fat Mach-O: its x86-64 slice), or any other file as raw bytes, as the current program; returns its summary.
- [binary_info](/docs/tools/binary_info.md): Summary of the current program: format, arch, entry, sections with entropy, imports/exports.
- [fetch_pdb](/docs/tools/fetch_pdb.md): Fetch the loaded PE's missing companion PDB over https from the symbol server (Microsoft's or BORER_SYMBOL_SERVER) into the cache; guid+age must match; dry-run unless dry_run=false; the next load_binary applies it.
- [reload](/docs/tools/reload.md): Restart the server on the binary at its path, keeping the session, the loaded file and its names and comments: use after rebuilding borer, instead of restarting the client.

## Find

- [functions](/docs/tools/functions.md): Discovered functions as `entry size blocks instrs callers callees src name` rows; filter on name or entry hex, sort=size for the largest first.
- [function](/docs/tools/function.md): One function's detail: name, range, counts, callers/callees and its basic-block table (`start size term successors`, 300 a page by offset).
- [symbols](/docs/tools/symbols.md): Imports/exports/forwards/locals/data as `kind addr name` rows under `# module:` lines, demangled (a forward ends `-> MODULE.name`); xrefs(import) lists its call sites.
- [strings](/docs/tools/strings.md): Printable ASCII/UTF-16LE strings as `va len enc "text"` rows; runs that are bytes of decoded instructions (prologues, nop padding) are left out.
- [search](/docs/tools/search.md): Search the whole file for bytes (AOB hex, ?? wildcards) or kind=text substring; hits as `function: va va ...` rows, `off=<n>` where unmapped; offset/limit (200, max 500).
- [find_function_by_string](/docs/tools/find_function_by_string.md): Functions referencing strings containing `filter`: a `# showing N of M` header, a numbered `# strings:` legend, then `entry name: 1 2 5` rows; offset/limit page rows and legend (50, max 300).
- [find_crypto_constants](/docs/tools/find_crypto_constants.md): Crypto tables and constants (AES, SHA-1/2, MD5, CRC-32, ChaCha, Blowfish, RC5/6, xxHash/FNV/SipHash, Base64) in the file as `va section algorithm` rows (`off=<n>` if unmapped); then API hashes, 32-bit constants hashing an export name (ROR13 as block_api, djb2, FNV-1a, CRC-32) with the candidates, `corroborated` when a neighbour resolves alike.
- [entropy](/docs/tools/entropy.md): High-entropy regions (packed/encrypted data) as `off va len entropy` rows at or above threshold bits/byte under a `# showing N of M` header; the scan stops at 200 regions.

## Read code

- [function_summary](/docs/tools/function_summary.md): One-call triage of a function: shape, loops, jump tables, callers/callees by name, strings and data it references; `# next:` lines name what to read next.
- [function_strings](/docs/tools/function_strings.md): String literals a function references as `site string_va text` rows (max 100).
- [decompile](/docs/tools/decompile.md): Pseudo-C with locals local_N/arg_N (N hex bytes below the entry sp: higher N, lower address), named calls, structured flow; /* asm */ marks unmodeled code, goto unproven flow.
- [decompile_batch](/docs/tools/decompile_batch.md): Pseudo-C for many functions: filter on name or entry hex, max_functions (10, max 50); 6000 chars per function, 40000 total; out=<file.c> writes all of them uncapped, leaves first, under the output root (BORER_OUTPUT_DIR or the binary's project dir); overwrite=true replaces a file.
- [disassemble](/docs/tools/disassemble.md): Disassemble `count` instructions (default 32, max 256) at an address or name as `va text` rows (bytes=true adds bytes); whole functions: disassemble_function.
- [disassemble_function](/docs/tools/disassemble_function.md): Disassemble a whole function block by block with `L_<addr>:` labels and named call/jmp targets (max_instrs default 400, max 2000).
- [cfg](/docs/tools/cfg.md): Control-flow graph of a function as mermaid: basic blocks (start, terminator) and successor edges, 300 blocks a page by offset; a trailing %% line says when blocks were cut.
- [callgraph](/docs/tools/callgraph.md): Callgraph from a function as mermaid: callees (callers=true: what reaches it), six per function before the rest is shared out, imports as leaves; a trailing %% line counts what was hidden.
- [reaches](/docs/tools/reaches.md): Shortest call chain from one function to another (or to an import, called through its slot or a thunk), or that there is none and how far it looked.
- [xrefs](/docs/tools/xrefs.md): References to an address or name, one `function: site kind, ...` row per referencing function, same-code functions folded; an import lists calls through its slot; `Class+0x24` lists who touches that field.
- [class_layout](/docs/tools/class_layout.md): Class layout from its methods: field offset, width, reads/writes, methods, vftable; takes a class name or a method address; apply=Name defines it as a struct typing each method's object (dry-run unless dry_run=false).

## Read data

- [read](/docs/tools/read.md): Read `count` values of `kind` (default one u64) as `va value` rows; pointers are named.
- [hexdump](/docs/tools/hexdump.md): Hexdump `length` bytes (default 64, max 4096) at `address`.

## Annotate

- [set_name](/docs/tools/set_name.md): Name a function (any address inside it) or a data global in the overlay, not the binary; names=["addr=name",...] renames many.
- [set_comment](/docs/tools/set_comment.md): Comment an address in the overlay; dry-run unless dry_run=false.
- [set_type](/docs/tools/set_type.md): Define or apply a user type: at a data global `type` types it (a `Player *` names the fields read through it); at a function it is the C prototype, or with `var` (a1, local_58) that variable's; `type` alone declares C types.
- [types](/docs/tools/types.md): List user-defined types and where they are applied; filter pages like every list.
- [annotations](/docs/tools/annotations.md): List the annotation overlay: names, findings and open questions (comments opening with ?); filter pages like every list.
- [save_project](/docs/tools/save_project.md): Save the annotation overlay (names, comments, types) to a .json project file keyed by the binary's SHA-256, under the output root (BORER_OUTPUT_DIR or the binary's project dir); overwrite=true replaces a file.
- [load_project](/docs/tools/load_project.md): Load a JSON project file into the annotation overlay, replacing it.

## Live process (Windows only)

- [live_attach](/docs/tools/live_attach.md): Attach read-only to a running process (name or pid) running the loaded binary (any process with BORER_LIVE_ANY=1); maps the binary onto it so live tools take static addresses and names.
- [live_detach](/docs/tools/live_detach.md): Detach from the attached process and drop its watches.
- [live_modules](/docs/tools/live_modules.md): List the attached process's modules.
- [live_read](/docs/tools/live_read.md): Read typed values from the attached process; pointers say what they point at.
- [live_object](/docs/tools/live_object.md): Read an object in the attached process as its class: each field's name, type, live value, and what pointers point at.
- [live_instances](/docs/tools/live_instances.md): Find a class's live objects by vtable in the attached process's data; live_object reads one.
- [live_watch](/docs/tools/live_watch.md): Watch attached-process memory: with an address, keep its bytes under the name; without, list what changed, naming fields when the class is known.

## Anything else

- [query](/docs/tools/query.md): Read a borer:// resource as resources/read does, for hosts that cannot read resources (borer://triage, borer://scenarios/0x401000/a1=0..8); a template read bare says its grammar, !offset=N!limit=N page a listing, borer://help lists all.
- [script](/docs/tools/script.md): Run a sandboxed Rhai script over the loaded program: what it printed, then the names and comments it proposed (dry-run unless dry_run=false).

## Optional

- [llms-full.txt](/llms-full.txt): Every page above in one file.
- [mcp.json](/mcp.json): tools/list and resources/templates/list, as the server sends them.
- [Source](https://github.com/imjustprism/borer): The repository.