Skip to main content
Glama
lbi-mcp

lbi-mcp

local-binary-index

Offline PE inspection engine that speaks MCP — packer ID, OEP hunting, IAT rebuild, anti-debug patches, .NET fingerprints, dump repair.

npm CI license dependencies tests MCP PRs

English · 简体中文 · Tools reference · Disclaimer

Read the DISCLAIMER before use. This project is for authorized security research, incident response, and education on binaries you own or are permitted to analyze. It does not ship or fetch malware, and it never executes its targets.


What it is

A single-purpose, dependency-free PE analysis core, packaged three ways:

Surface

What you get

MCP server (lbi-mcp)

8 tools an agent can call over stdio — works with Codex, Claude Desktop, Cursor, or any MCP client

CLI (lbi)

The same engine from a terminal, JSON or Markdown out

Library (ESM)

import { analyzeFile } from "local-binary-index"

Everything is static: files are read, parsed, and reasoned about. Nothing is unpacked into memory, nothing is executed, nothing leaves the machine.

$ lbi zxwn analyze samples/packed.exe --out ./out
判定: packed (1)          主家族: UPX
OEP : 0x0000000000401000  (push 0x401000 ; ret, score 100)
IAT : 1 module / 3 functions · residual descriptor @0x00005500 (USER32.dll, GDI32.dll)
反分析: int 2d @0x00000A10 → patch 90 90 · icebp ×4 · TLS callback ×1
written: out/report.md, out/analysis.json, out/scripts/{x64dbg,gdb,windbg,frida,scylla,patches}

Related MCP server: BinSight

Why another PE tool

Most "what packer is this" answers are a filename, a section name, and a guess. The useful answer is a plan: which family, how confident, where the entry transfer is, where the import table went, which anti-debug checks will bite you, and what to patch or breakpoint first.

local-binary-index returns that plan as structured, evidence-linked data — every signal carries its file offset, and every report carries a SHA-256 per section, so a human (or another agent) can re-derive the conclusion instead of trusting it.

Design rules

  1. Evidence over verdict — each match reports the exact section name, marker string, byte pattern, or overlay offset behind it.

  2. No execution, ever — no emulator, no loader, no CreateProcess, no network.

  3. Honest unknowns — unsupported formats and unresolved indirect jumps are stated, not guessed.

  4. Bounded work — every loop has a cap; malformed or truncated input returns partial facts plus explicit limitations instead of throwing.


Features

Area

What it does

Protection profiling

25 signature families (UPX, ASPack, PECompact, MPRESS, Themida/WinLicense, VMProtect, Enigma, Armadillo, .NET Reactor, ConfuserEx, KoiVM, PyInstaller, Electron, NSIS, Inno, Go, Rust, …) + structural heuristics (virtual-only sections, RWX, entry in last section, checksum mismatch, IAT moved out of .idata, high-entropy sections)

OEP hunting

Walks the entry stub with a length-accurate x86/x86-64 decoder, finds push imm32; ret, cross-section relative jumps, and popad-then-jump; scores candidates; emits ESP-law and BND-style breakpoint plans for x64dbg / gdb / WinDbg

Import rebuild planning

Current module/function map, ordinal-only census, IAT location vs .idata, residual IMAGE_IMPORT_DESCRIPTOR array scan, rebuild steps and Scylla/x64dbg commands

Anti-analysis scan

PEB (fs:[0x30], gs:[0x60]), NtGlobalFlag, rdtsc, int 2d, icebp, ud2, CPUID hypervisor probe, VMware backdoor port; TLS callbacks; IAT-level hook targets with suggested return values; NOP patches with file offsets

Managed code

CLR header, metadata streams (#~, #Strings, #US, #Blob, #GUID), table row counts (TypeDef/MethodDef/Field/MemberRef/AssemblyRef), obfuscator fingerprints, obfuscation-strength indicators

Dump repair

Memory image → parseable file: section re-layout, SizeOfRawData/PointerToRawData/SizeOfImage/SizeOfHeaders rewrite, PE checksum recompute, then self-verification by re-parsing

Script emission

Ready-to-run x64dbg, gdb, WinDbg, Scylla, and Frida assets (PEB patching, API interception, RWX watch, auto-dump on OEP hit)

Reporting

Markdown + JSON + per-section evidence chain (E-001 …)


Quick start

git clone https://github.com/lingbol088-spec/local-binary-index.git
cd local-binary-index
npm ci
npm test          # builds, generates synthetic fixtures, runs 10 unit tests

Use as an MCP server

Codex desktop / CLI (~/.codex/config.toml):

[mcp_servers.local-binary-index]
command = "node"
args = ["/absolute/path/to/local-binary-index/bin/lbi-mcp.mjs"]
startup_timeout_sec = 60

[mcp_servers.local-binary-index.env]
LBI_TOKEN = "zxwn"      # activation token; omit for the inert catalog

Claude Desktop / Cursor / any mcpServers JSON:

{
  "mcpServers": {
    "local-binary-index": {
      "command": "node",
      "args": ["/absolute/path/to/local-binary-index/bin/lbi-mcp.mjs"],
      "env": { "LBI_TOKEN": "zxwn" }
    }
  }
}

Then, in a new conversation:

you: zxwn
agent: (capability table) … which file do you want analyzed?
you: D:\samples\target.exe — what packer is this and how do I unpack it

Use as a CLI

npx lbi status
npx lbi zxwn profile  samples/packed.exe
npx lbi zxwn transfer samples/packed.exe
npx lbi zxwn imports  samples/packed.exe
npx lbi zxwn anti     samples/packed.exe
npx lbi zxwn managed  samples/assembly.dll
npx lbi zxwn analyze  samples/packed.exe --out ./out
npx lbi zxwn repair-dump dump.bin --out fixed.exe

Every command accepts --json (except analyze, which writes files) so it drops into pipelines.


The 8 MCP tools

Tool

Question it answers

Notable output

inspect_protection_profile

What is this, and what does breaking it take?

verdict, family, confidence, per-signal evidence, structural anomalies, strategy list

inspect_entry_transfer

Where does the original code start?

scored OEP candidates with source instruction, ESP-law plan, breakpoints for 3 debuggers

inspect_import_rebuild_plan

Where did the import table go?

IAT census, ordinal-only list, residual descriptor arrays, rebuild steps

inspect_anti_analysis

What will fight the debugger?

findings with file offsets, patch bytes where safe, IAT hook targets + suggested returns, TLS callbacks

inspect_managed_protection

Is it .NET, and how obfuscated?

CLR runtime, streams, table row counts, obfuscator markers, indicators

repair_image_dump

Can this memory dump be parsed?

re-laid sections, rewritten headers, recomputed checksum, post-repair self-check

emit_recovery_scripts

What do I paste into my debugger?

x64dbg / gdb / WinDbg / Scylla / Frida files

inspect_binary_report

Give me the whole thing.

Markdown + JSON + evidence chain

Full input/output schemas: docs/TOOLS.md.


Trigger word and activation

The server has two catalogs:

State

Condition

tools/list

inert

no LBI_TOKEN, or the local state file is missing/expired/mismatched

1 (index_status)

armed

LBI_TOKEN=zxwn, or state file holds zxwn and has not expired

8

lbi zxwn arm --minutes 1440   # arm for 24h (0 = never expires)
lbi zxwn disarm               # drop back to the inert catalog immediately
lbi status                    # show activation + expiry

Why: an agent workstation often runs several MCP servers. Keeping a binary-analysis surface inert until it is explicitly armed makes accidental tool use visible and auditable.


How it works

                 ┌──────────────────────────────────────────────────────┐
   file bytes ──▶│ peFile      headers · sections · imports · exports   │
                 │             TLS · resources · debug · Rich · overlay │
                 └───────────────┬──────────────────────────────────────┘
                                 │  PeImage (RVA⇄offset resolver, anomalies)
        ┌────────────────────────┼───────────────────────────┬─────────────────────┐
        ▼                        ▼                           ▼                     ▼
  packer/detect            oep/x86len + hunt            iat/plan            antidebug/scan
  signatures + heuristics  stub walk → candidates       IAT census +        patterns + IAT hooks
  → families, confidence   ESP law + breakpoints        residual descriptors → patches, hook targets
        │                        │                           │                     │
        └────────────┬───────────┴─────────────┬─────────────┴──────────┬──────────┘
                     ▼                         ▼                        ▼
              runtime/scripts           runtime/fixDump            report/markdown
              x64dbg/gdb/windbg         dump → file layout         Markdown + JSON + evidence
              scylla/frida              + checksum recompute

Everything is pure computation over Uint8Array. The only I/O is reading the target file and (optionally) writing reports/scripts.


What real runs look like

Target

Result

Synthetic UPX-shaped PE32 (5,136 B)

packed (1.0) · UPX · OEP 0x401000 score 100 · patches int 2d @0x00000A10 → 90 90 · residual descriptor @0x00005500 = USER32.dll, GDI32.dll

notepad.exe (x64, real Windows binary)

clean · 50 modules / 315 imports · 12 anti-analysis findings · 0 structural anomalies

mscorlib.dll (.NET 4)

CLR v1.1 · metadata v4.0.30319 · 31 tables · TypeDef 3,356 / MethodDef 29,257

24,576 B memory dump

memory→file re-layout · pointers rewritten · checksum recomputed · re-parsed successfully

Reproduce locally: npm run fixtures && npm run demo.


Compatibility

Item

Support

Input formats

PE32 / PE32+ (EXE, DLL, SYS); .NET assemblies

Not supported

ELF, Mach-O, 16-bit NE/LE (rejected with an explicit error)

Host OS

Windows / macOS / Linux (pure Node)

Node

≥ 20.11

Runtime deps

none

MCP transport

stdio


Safety model

  • Read-only. The engine opens files, never maps them executable, never spawns them.

  • No network. No telemetry, no remote lookups, no signature downloads.

  • No samples shipped. Fixtures are generated locally by scripts/make-fixtures.mjs and contain no malicious code.

  • Deterministic. Same bytes in, same JSON out; every report carries hashes so results can be audited.


Limitations

  • Static analysis cannot recover an encrypted packer payload; for those you need a runtime dump (the Frida script gets you there, the analysis does not).

  • Single-byte signatures (F1 icebp) can match by coincidence in random data; hit counts are capped and flagged.

  • x86-64 VEX/EVEX decoding is length-approximate; decoding stops at the first invalid byte and reports where.

  • IAT rebuild is a plan plus residual-descriptor discovery, not an automated Scylla replacement.

  • .NET metadata is read structurally; IL is not decompiled here (use a dedicated decompiler on the output).


FAQ

Does it unpack anything? No. It tells you how to unpack, and generates the debugger/Frida assets that do the runtime part.

Why is the catalog inert by default? So that a shared workstation does not silently grow a binary-analysis attack surface. Arm it with zxwn, optionally with an expiry.

Can I use it commercially? MIT license permits it. Read DISCLAIMER.md — permitted use is still your responsibility.

Where do I start with an unknown binary? analyze → read protection.verdict and entryTransfer.candidates[0] → follow the emitted x64dbg script.


Roadmap

  • ELF support (packer ID + .init_array analysis)

  • Mach-O support

  • Direct Scylla-compatible .scv IAT export

  • Optional YARA rule export from detection signals

  • WASM build of the parser core for browser-side triage


Contributing

Issues and PRs are welcome — see CONTRIBUTING.md. Please run npm test before opening a PR, and keep new detection signatures backed by a reproducible fixture.

Security

Report vulnerabilities privately per SECURITY.md. Please do not open a public issue for an exploitable parser bug.

License

MIT © 2026 li lingbo

Disclaimer

This software is provided as is, without warranty of any kind. It is intended only for lawful analysis of binaries you own or are explicitly authorized to examine (security research, incident response, CTF, malware triage in an isolated lab). Do not use it to circumvent protection on software you do not have rights to, to develop or distribute malware, or in violation of any applicable law. The authors accept no liability for misuse or damage. Full text: DISCLAIMER.md.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents and CLI users to statically inspect any binary offline — identifying file type, architecture, imports, packing, embedded content and signatures — and to diff two files to see exactly what changed. It works on ELF, PE and Mach-O executables, firmware dumps and calibration files without ever running them, reporting observations and inferences with file offsets as evidence.
      104 npm
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables agents to drive an end-to-end reverse-engineering loop on protected binaries: launch and dump live processes, rebuild memory images into file-aligned PEs with repaired imports, map Delphi RTTI methods, scan strings/entropy/xrefs, emulate code, and decompile through Ghidra or .NET. It also supports scripted live x64 and WOW64 debugging with breakpoints, registers, and module dumps exposed as callable tools.
      35
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables local, evidence-first triage of native binaries by extracting bounded symbols, strings, sections, call sites, gadget candidates, and mitigation signals as MCP tools for agent-guided manual review. It also provides metadata-only inspection for carriers such as archives, WebAssembly, firmware, and scripts without claiming verified vulnerabilities.
      12
      5
      MIT