<div align="center">

<img src="docs/assets/banner.svg" alt="Antardrishti — Look inside the binary. Understand the logic." width="100%" />

# Antardrishti · अन्तर्दृष्टि

**Local reverse engineering for humans and AI agents.**

PE · ELF · Mach-O · x86 · x64 · ARM64 · .NET IL

[![CI](https://github.com/divyanshu-iitian/antardrishti/actions/workflows/ci.yml/badge.svg)](https://github.com/divyanshu-iitian/antardrishti/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%2B-3776AB?style=flat-square)](pyproject.toml)
[![License: MIT](https://img.shields.io/badge/license-MIT-D4A64A?style=flat-square)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-12_tools-167D7F?style=flat-square)](#connect-your-ai-agent)

[Quick start](#quick-start) · [REA comparison](#antardrishti-vs-rea) · [Commands](#command-reference) · [हिन्दी](docs/README.hi.md) · [Contribute](CONTRIBUTING.md)

</div>

Open a binary. Find its functions. Follow a string to the code that uses it. Read C-like pseudocode, save what you learn, and compare the next build—from a terminal or an MCP-connected agent.

Antardrishti brings its own analysis and decompilation pipeline. **No IDA, Ghidra, Hopper, Java runtime, API key, or hosted model is required for the engine.** Its two direct runtime dependencies are [Capstone](https://www.capstone-engine.org/) and [LIEF](https://lief.re/).

> **Early alpha · v0.1.0.** Pseudocode and inferred types are analysis aids. Check disassembly and warnings before relying on a conclusion. See [limitations](#limitations).

## Why the name?

**Antardrishti (अन्तर्दृष्टि)** is a Sanskrit-derived word used in Hindi for *inner insight*: looking beneath the surface to understand what is happening within. That is the job of a reverse engineering tool. Pronounced roughly **an-tar-drish-ti**.

## Quick start

Requires **Python 3.10+**. Install from this repository; a PyPI release is not currently provided.

```bash
git clone https://github.com/divyanshu-iitian/antardrishti.git
cd antardrishti
python -m venv .venv
```

Activate the environment:

```bash
# Linux / macOS
source .venv/bin/activate
```

```powershell
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
```

Then install and try the included fixtures. You do not need a compiler to run them.

```bash
python -m pip install -e .
antardrishti --version
antardrishti info tests/fixtures/sample32.exe
antardrishti decompile tests/fixtures/sample32.exe _crc32_compute
antardrishti report tests/fixtures/sample32.exe -o analysis.html
```

If activation is unavailable, use `.venv/Scripts/python.exe` on Windows or `.venv/bin/python` on Unix with `-m pip` and `-m antardrishti`.

### A small investigation

```bash
# Hashes, entropy, imports, hardening checks and algorithm indicators.
antardrishti triage tests/fixtures/sample32.exe

# Follow a string to the functions that use it.
antardrishti trace tests/fixtures/sample32.exe crc=

# Inspect pseudocode and save your understanding across sessions.
antardrishti decompile tests/fixtures/sample32.exe _crc32_compute
antardrishti annotate tests/fixtures/sample32.exe _crc32_compute --comment "CRC-32 checksum routine"

# Export facts as JSON or a standalone report.
antardrishti funcs tests/fixtures/sample32.exe --json
antardrishti report tests/fixtures/sample32.exe -o analysis.html
```

See [a captured demo](docs/DEMO.md) for actual output from the included fixture.

## Why Antardrishti?

| You want to… | Antardrishti provides |
| --- | --- |
| Inspect native code without a separate decompiler | Built-in loading, function discovery, disassembly and pseudocode |
| Give an agent a small, predictable interface | 12 MCP tools with simple schemas, pagination and bounded responses |
| Understand where a feature lives | Strings/API references, caller/callee graphs and paths from `main` when discovered |
| Keep findings between sessions | SQLite cache and annotations keyed by the binary's SHA-256 |
| Inspect stripped library code | Bundled musl signatures; build or learn additional packs |
| Inspect native and managed functions | x86/x64/ARM64 pseudocode and a .NET IL analysis path |
| Review a patch | Function-level matching and changes to calls, strings and constants |
| Share an investigation | Standalone HTML reports and JSON output |

The engine reads local files and does not execute the target. Connecting it to an AI client gives that client access to analysis results; the client's own data handling still applies.

## Antardrishti vs REA

[REA](https://github.com/morluto/rea) is a broader reverse engineering orchestration project. **Antardrishti is a better fit when your priority is self-contained static binary analysis with a compact agent interface.**

| Decision | Antardrishti | REA |
| --- | --- | --- |
| Native decompilation setup | Built-in x86/x64/ARM64 pipeline; Python + Capstone + LIEF | Deep native analysis through configured engines such as Hopper, Ghidra or IDA |
| Agent interface | Focused 12-tool MCP catalog | Broader interface covering many targets and workflows |
| Core triage | Entropy, packing indicators, hardening and algorithm constants in the engine | Capabilities depend on workflow/provider; consult REA documentation |
| Findings between sessions | Own SHA-256-keyed annotation store | Persistence depends on workflow and native provider |
| Application/runtime breadth | Native binaries and .NET IL; static analysis | JavaScript/Electron, websites, Android, captures, firmware and runtime workflows in addition to native analysis |
| Established decompiler depth | Early alpha, heuristic recovery | Can use mature external decompilers |

The REA column is based on its [README at `fe7bcc3`](https://github.com/morluto/rea/blob/fe7bcc3/README.md), reviewed on **16 October 2026**. REA also documents offline objdump/Rizin paths and built-in metadata readers. The external-engine requirement here refers to deep native decompilation, not every REA feature.

This compares architecture and setup, **not decompilation accuracy or speed**. See [evidence and reproduction](docs/REA_ANALYSIS.md). Antardrishti is independent of REA and is not affiliated with its maintainers.

## Connect your AI agent

```bash
antardrishti mcp-config
```

This prints configuration using your current Python executable. Paste it into your client's MCP settings. For clients using the `mcpServers` format:

```json
{
  "mcpServers": {
    "antardrishti": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "antardrishti", "mcp"]
    }
  }
}
```

On Windows, use an absolute executable path such as `C:/tools/antardrishti/.venv/Scripts/python.exe`. Clients with another settings format can register the same command and arguments. MCP uses stdio; no HTTP server is started.

**Tools:** `triage`, `list_functions`, `get_function`, `xrefs`, `list_strings`, `list_imports`, `trace_feature`, `call_graph`, `search`, `read_memory`, `annotate`, `diff_binaries`.

Each tool accepts the target path directly. Results are paginated and capped at 24,000 characters by default (`ANTARDRISHTI_MCP_MAX_CHARS`). Input schemas avoid `$ref`, `const`, `oneOf` and `anyOf`; tests enforce catalog constraints. Verify client interoperability in your environment.

Try asking your agent:

> Analyze `/absolute/path/to/sample32.exe`. Start with triage, trace the string `crc=`, inspect matching functions, and explain the logic with addresses and uncertainty. Save useful names and comments.

## Command reference

| Command | Purpose |
| --- | --- |
| `info FILE` / `triage FILE` | Overview or detailed static triage |
| `funcs FILE [-q NAME] [--sort complexity]` | Find and rank functions |
| `fn FILE REF [--asm\|--pseudo\|--cfg\|--all]` | Inspect a function |
| `decompile FILE REF` / `disasm FILE REF` | Pseudocode or annotated assembly |
| `xrefs FILE REF [--from]` | References to/from a symbol or address |
| `strings FILE [-q TEXT] [--refs]` | Strings and their users |
| `imports FILE [--area network]` / `exports FILE` | Imported/exported symbols |
| `trace FILE QUERY` | Trace a string/API and paths from `main` |
| `callgraph FILE REF [--depth N]` | Function relationships |
| `search FILE PATTERN --kind hex\|text\|regex\|value\|insn` | Bytes, values, text and instructions |
| `read FILE ADDR [-n 256] [--fmt hex\|asm\|string]` | Read mapped bytes |
| `annotate FILE REF --name NAME --comment TEXT` | Save names and comments |
| `diff OLD NEW` | Compare binary versions |
| `report FILE -o report.html` | Export a standalone report |
| `sigs list` / `sigs build --auto` | Inspect/build library signature packs |
| `sigs learn FILE --name PACK` | Learn signatures from a named binary |
| `mcp` / `mcp-config` | Start/configure the MCP server |
| `recent` | Recently analyzed binaries |

Prefix commands with `antardrishti`. `REF` accepts a function name or address; managed methods also accept qualified names and method tokens. Most analysis commands accept `--json`; use `COMMAND --help` for exact options. Raw code supports `--arch x64 --base 0x1000`; universal Mach-O supports `--slice arm64`.

Cache and annotations live in `~/.antardrishti/antardrishti.db`. Override with `ANTARDRISHTI_HOME`. Use `--no-cache` to reanalyze a target.

## Supported analysis

- **Formats:** PE, ELF, Mach-O (including universal slices), raw code, and managed PE/.NET IL.
- **Native pseudocode:** x86, x64 and ARM64; branches, loops, switches, arguments, expression simplification and basic type/structure inference.
- **Other architectures:** disassembly and analysis paths for ARM, MIPS, PowerPC, RISC-V and SPARC; coverage depends on instructions and format.
- **Discovery:** symbols, exports, entry points, unwind/function metadata, recursive calls, thunks, jump tables and prologue scanning.
- **Triage:** hashes, import features, entropy, compiler/runtime indicators, packing indicators, hardening and known algorithm constants.
- **Signatures:** bundled musl x64/ARM64 packs, library/archive pack building, and learning from named functions. See [notices](antardrishti/sigdata/NOTICE.md).

## Architecture

```mermaid
flowchart LR
    A[PE / ELF / Mach-O / raw / .NET] --> B[Load and discover]
    B --> C[Functions, CFGs, references]
    C --> D[Lift, simplify, structure, infer types]
    C --> E[Triage, search, trace, diff]
    D --> F[Session API + SQLite]
    E --> F
    F --> G[CLI]
    F --> H[12-tool MCP server]
    F --> I[HTML report]
```

Start with [`project.py`](antardrishti/project.py) for the shared API, [`analysis.py`](antardrishti/analysis.py) for discovery, and [`decompiler/`](antardrishti/decompiler/) for pseudocode generation.

## Development and validation

```bash
python -m pip install -e ".[dev]"
python -m pytest -q
python scripts/measure_mcp.py python -m antardrishti mcp
```

Tests use included PE/ELF/Mach-O/.NET binaries and generated tiny ELF fixtures. Coverage includes native analysis, pseudocode, signatures, search, annotations, diffing, CLI, reports and MCP contracts. Fixture sources and rebuild instructions are in [`tests/fixtures/`](tests/fixtures/). The CI matrix exercises Windows, Linux and macOS; check its actual status above. See [captured validation](docs/VALIDATION.md).

## Limitations

- Early static analyzer: pseudocode is reconstructed, not original source, and may be incomplete or incorrect.
- Type/structure recovery is heuristic. Indirect branches, obfuscation, unusual calling conventions and optimized code can lose information or leave `goto`s.
- ARM64 and .NET paths have narrower validation than mature dedicated decompilers. Other advertised disassembly architectures have no native pseudocode lifter.
- Packing/algorithm indicators are clues, not proof of malicious behavior or cryptographic use. Packed code is not automatically unpacked.
- No debugger, live instrumentation, JavaScript/Electron, JVM/DEX, website or packet-capture analysis.
- Large targets may take substantial time and memory. No comparative speed or accuracy benchmark is published here.
- Dependency wheel availability varies by Python/OS/CPU combination.

## Roadmap

- Broaden compiler and optimization fixture coverage.
- Improve native/managed control-flow recovery and inferred types.
- Expand redistributable library signatures with provenance and regression cases.
- Add reproducible accuracy/performance benchmarks against ground truth.
- Explore optional external decompiler providers for deeper investigations.

## Contributing

Small, reproducible cases make the engine better. Source, compiler flags, expected behavior and observed output are especially useful. Read [CONTRIBUTING.md](CONTRIBUTING.md), [security reporting](SECURITY.md), and [third-party notices](THIRD_PARTY_NOTICES.md).

If this helps your work, star the repository and share a reproducible investigation. [Launch copy](docs/LAUNCH.md) is included for sharing the project.

## License

[MIT](LICENSE). Built with Capstone and LIEF. Bundled musl-derived signatures retain upstream attribution. Use the tool for software you own or are authorized to examine.