AIDebug

Reviewer starting point

Evidence-focused reverse-engineering CLI. Andrey Pautov develops the Python analyst interface, offline triage, string intelligence, PE inspection and reporting workflows. Capstone, Ghidra, GDB and optional AI providers are integrations, not original tools authored by this project.

Role relevance: Malware triage, reverse engineering tooling, safe AI-assisted analysis, Python delivery.

Run the safe local demo and review validation scope · Recorded local validation

AIDebug is an evidence-focused malware reverse-engineering CLI and terminal UI. It combines deterministic offline triage, whole-file hex inspection, deep PE structure analysis, Capstone disassembly, Ghidra reconstruction, optional LLM cross-checks, local ELF debugging, compiled learning exercises, and analyst-review reporting.

Current source version: AIDebug 3.1.0. See the 3.1.0 release notes.

The latest immutable published release remains AIDebug v3.0.0, available as 1200km-aidebug, until the version-matched 3.1.0 tag and GitHub release complete the verified publishing workflow.

Highlights

• Deterministic PE and ELF static triage without requiring an AI service.
• Whole-file, occurrence-aware ASCII, UTF-8, UTF-16LE, and UTF-16BE string intelligence with smart categories, ranking, and DLL/API explanations.
• Read-only, paged hex viewer for the complete analyzed file.
• Deep PE32/PE32+ structure explorer with mapped RVA, VA, and file offsets.
• Ghidra-backed C-like reconstruction for one function or the complete bounded function set.
• Optional evidence-grounded review through Anthropic, OpenAI, Google Gemini, or a local Ollama-compatible endpoint.
• GDB-backed local ELF debugging with breakpoints, stepping, registers, deltas, disassembly context, and function input/output candidates.
• One hundred standalone C learning cases with real compiler output, disassembly, and Ghidra pseudo-code in the main GUI.
• SHA-256-indexed local analysis history and compatible finding restoration.
• HTML, versioned JSON, YARA-candidate, ATT&CK-candidate, and CFG outputs for analyst review.

Installation

Published 3.0.0 package

Install the stable package from PyPI:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install 1200km-aidebug==3.0.0
aidebug --version

Install optional capabilities as needed:

# LLM provider clients and local validation of AI-generated YARA candidates
python -m pip install "1200km-aidebug[ai]==3.0.0"

# Frida dynamic instrumentation
python -m pip install "1200km-aidebug[dynamic]==3.0.0"

# All optional Python integrations
python -m pip install "1200km-aidebug[all]==3.0.0"

Reviewed 3.1.0 source

String Intelligence requires source 3.1 until its package is published. The 3.1 review pins the revision below. Its runtime code also matches the audited October 1 main revision 80b0b7172b592814504c405a16bf4cc0ce4161eb.

git clone https://github.com/anpa1200/AIDebug.git
cd AIDebug
git checkout cd81ef242db0bcea3296970d45c241a4228d2d27
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
aidebug --version

From that checkout, add extras with python -m pip install -e ".[ai]", ".[dynamic]", or ".[all]". Keep extras on the same installation track: installing "1200km-aidebug[ai]==3.0.0" over source 3.1 can replace it with the published 3.0 package.

Development

For a moving development checkout:

git clone https://github.com/anpa1200/AIDebug.git
cd AIDebug
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev,dynamic]"

Ghidra, GDB, Bubblewrap, a C compiler, and Frida target components are external tools used only by the workflows that require them.

REMnux integration

AIDebug was accepted into REMnux on 7 October 2026 through PR #355, first included in salt-states v2026.41.4. The accepted state installs unpinned 1200km-aidebug[ai] from PyPI into /opt/aidebug, enables upgrades, and exposes /usr/local/bin/aidebug. As verified on 8 October 2026, PyPI still provides 3.0.0; this does not install unpublished 3.1 source or the dynamic extra. Use --offline to keep analysis local. See REMnux setup and version boundaries.

Quick Start

Open a PE or ELF sample in the main terminal interface:

aidebug --binary /path/to/sample.exe --offline

Run deterministic analysis without the full-screen UI and export evidence:

aidebug --binary /path/to/sample.exe \
  --offline --no-tui --report --json-export --yara \
  --out-dir reports/

Use Ghidra reconstruction:

aidebug --binary /path/to/sample.exe --offline --no-tui --decompile
aidebug --binary /path/to/sample.exe --offline --no-tui \
  --decompile-all reports/sample-reconstruction.c

Analyze one C translation unit through a temporary, non-executed ELF artifact:

aidebug --source /path/to/example.c --offline --no-tui

Identify an arbitrary file independently of its filename extension:

aidebug --identify /path/to/renamed-or-unknown-file --offline

--identify reports structured JSON with the declared type, MIME type, common extensions, confidence, method, evidence, SHA-256, and size. Deterministic coverage includes common executable and bytecode formats, archives and disk images, Office/OpenDocument/EPUB containers, documents, images, audio/video, packet captures, databases, registry/event-log artifacts, scripts, and text. ZIP classification considers the first 4,096 names and reads at most 128 bytes of a mimetype entry. Python parses the central directory before the name limit applies; this does not bound initial directory-parsing memory. The whole input is capped at 128 MiB, and files are never executed or extracted. Built-in capture signatures cover nanosecond PCAP in both byte orders and PCAP-NG. Conventional microsecond PCAP signatures are currently missing; optional libmagic may recognize them.

Install python-magic plus the operating system's libmagic database for additional signatures known to the local platform:

python -m pip install python-magic