AIDebug

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

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:

# Remote/local LLM providers and validated YARA generation
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"

For development:

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.

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-based formats are inspected by bounded member names and small metadata reads; files are never executed or extracted.

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

python -m pip install python-magic

When no deterministic signature, structure, or text rule matches, a configured AI provider may infer a candidate from bounded metadata: the extension, size, SHA-256, up to 96 header bytes, 32 tail bytes, sample entropy, and NUL ratio. The file body, extracted strings, and filesystem path are not sent. AI-only results are labeled ai-inference, capped at 60% confidence, and require analyst validation. Use --offline to disable the fallback completely; an unresolved type is reported as Unknown with exit status 2.

String Intelligence Workspace (3.1.0)

Press S in the main terminal interface, or start directly in the workspace:

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

The workspace preserves file offsets, mapped addresses when available, encoding, byte and character lengths, duplicate-occurrence information, section context, confidence, triage score, and the deterministic reasons for each classification. Filters cover minimum length, encoding, category, and free-text search; column sorting and pagination keep large inventories usable. Every selected encoding scans the complete size-bounded artifact. The retained inventory is capped at 25,000 records and 4,096 displayed characters per value; exact candidate/omission counts and full-byte coverage make either cap visible. Each record retains at most 32 DLL/API annotations and 4,096 description characters; adversarial overflows are reported in the record reasons.

Detection is multi-label. A single value can simultaneously be a DLL, Windows path, URL, IP address, registry key, command, PowerShell fragment, named pipe, hash, credential candidate, user agent, or another supported evidence type. Domain candidates are IDNA-normalized and checked against a packaged offline IANA root-zone snapshot; IP addresses must occupy a complete valid token, and configuration assignments must match a conservative full-line grammar. This prevents short binary fragments from being promoted merely because they contain a dot, colon, or equals sign. Related labels share one confidence family, so ip_address plus ipv6 is not treated as two independent observations. Known DLLs and APIs receive short neutral capability descriptions; unknown names receive an explicit unverified fallback instead of a guessed purpose. An extracted name is evidence of presence, not proof that code invoked it or that the sample is malicious.

Print the deterministic inventory locally, filter the displayed CLI view, or write the canonical full inventory as owner-only JSON:

aidebug --binary /path/to/sample.exe --strings --no-tui
aidebug --binary /path/to/sample.exe --strings --no-tui \
  --string-encoding ascii --min-string-length 6 --string-category url
aidebug --binary /path/to/sample.exe --strings --no-tui \
  --strings-output reports/sample-strings.json

AI string review is a separate opt-in action. Press A inside the workspace and confirm the privacy/cost warning, or request it explicitly in CLI mode:

aidebug --binary /path/to/sample.exe --strings --no-tui \
  --analyze-strings --accept-ai-cost \
  --strings-output reports/sample-strings-ai.json

Every retained string is assigned a stable evidence ID. After explicit confirmation, the AI path plans every retained record across deterministic, bounded chunks; provider or validation failures stop safely and remain visible. Responses must account for every supplied ID and pass strict local schema, enum, reference, and IOC-grounding validation before they are accepted. A final reducer sees validated findings rather than the raw inventory. Extraction limits, failed batches, and reviewed/sent counts are always reported; incomplete coverage forces an unknown overall assessment. Strings can contain passwords, API tokens, customer data, and attacker-authored prompt injection, so review the remote-AI boundary before enabling this feature.

Inspect prior analysis by file or SHA-256:

aidebug --history /path/to/sample.exe
aidebug --history 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

PE Structure Workspace

Load a PE file and press X (or P) in the main GUI. AIDebug presents the exact bytes it hashed and organizes structural evidence into bounded, navigable views.

Area	Evidence
Headers	DOS, NT, COFF, Optional Header, characteristics, data directories, and mitigation flags
Sections	Complete IMAGE_SECTION_HEADER fields, mapped ranges, entropy, and permissions
Imports and exports	Import descriptors, INT/IAT entries, delay imports, ordinals, names, RVAs, and forwarders
Resources	Type/name/language hierarchy, metadata, hashes, previews, and safe no-overwrite export
Relocations and ASLR	Relocation blocks/entries and structural ASLR compatibility assessment
TLS	TLS directory, template data, index, callback table, mappings, and termination evidence
Exceptions and unwind	x64 runtime functions, UNWIND_INFO, operations, handlers, and chained records
Load configuration	Versioned fields, Guard flags, stack-cookie and exploit-mitigation evidence
CFG	Check/dispatch pointers, Guard Function ID targets, ordering, suppression, and consistency checks
Authenticode	Certificate records, PKCS#7/X.509 evidence, PE image digest comparison, and signer verification
Debug and provenance	Rich header, Debug Directory, CodeView RSDS/NB10, PDB GUID, age, and path
Overlays	Exact offset, size, hash, entropy, preview, and safe export
.NET / CLR	COR20 header, metadata root and streams, ECMA-335 tables, assemblies, references, and resources

AIDebug does not execute a PE while building these views. Static certificate verification is not Windows root trust or revocation validation, Rich metadata is not attribution, strong-name metadata is not publisher trust, and static mitigation flags are not proof of effective runtime policy.

Published Guides

These articles provide the long-form workflows and screenshots that complement the repository documentation:

• AIDebug 3.1 Full Release Review: From Binary Intake to String Intelligence — the complete evidence-first workflow across file identification, PE and ELF triage, functions, control flow, strings, Ghidra, optional AI review, controlled debugging, history, and reports.
• Strings Analysis for Malware Analysis: Turning Binary Text into Defensible Hypotheses — occurrence-aware extraction, conservative categorization, IOC validation, cross-references, and AIDebug String Intelligence.
• PE File Structure for Malware Analysis: A Practical Guide — PE layout, loader behavior, headers, sections, imports, exports, resources, relocations, TLS, mitigations, signatures, overlays, and .NET metadata with AIDebug.
• Assembly for Malware Analysis: A Practical x86/x64 Guide — registers, flags, calling conventions, control flow, Windows APIs, and hands-on AIDebug learning cases.
• AI-Powered Malware Debugger That Explains Every Function It Sees — the locally preserved original AIDebug project walkthrough.

Learning Mode

Open the complete catalog or start with a specific case:

aidebug --learn
aidebug --learn mov-load
aidebug --learn lea-arithmetic
aidebug --learn switch-dispatch

Each bundled case is a standalone file under learning/cases/. AIDebug compiles the selected case into a temporary x86-64 ELF, shows the exact C source and compiler-generated instructions, asks Ghidra for an independent reconstruction, records build provenance, and removes the temporary artifact. The generated lesson binary is never executed.

Use --no-tui for text output, or load a reviewed external collection:

aidebug --learn movsxd --no-tui
aidebug --learn --learning-collection /path/to/reviewed-cases

AI Providers

AI analysis is optional. Deterministic offline mode remains available without credentials.

python -m pip install "1200km-aidebug[ai]==3.0.0"
cp .env.example .env
chmod 600 .env

Configure exactly one provider, or set AIDEBUG_LLM_PROVIDER explicitly when several credentials exist:

AIDEBUG_LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=replace_with_your_key

# Alternatives:
# OPENAI_API_KEY=replace_with_your_key
# GEMINI_API_KEY=replace_with_your_key
# OLLAMA_BASE_URL=http://127.0.0.1:11434/v1

Use AIDEBUG_ENV_FILE=/absolute/path/to/private.env to keep configuration away from untrusted analysis directories. Remote bulk analysis requires the explicit --accept-ai-cost acknowledgement. Review the remote-AI data boundary before sending sample evidence to any provider.

Active ELF Debugging

GDB-backed active mode executes the selected local ELF. Use it only inside an isolated, authorized lab:

aidebug --binary ./sample.elf --mode debug --breakpoint main

Available commands include break, continue, step, next, finish, registers, changes, io, disassemble, and quit. Frida dynamic mode is available separately for supported local or remote instrumentation workflows.

Outputs

Output	Intended use
HTML report	Human review and case notes
Versioned JSON	Custom integration input; not a vendor-native or STIX schema
String Intelligence JSON	Canonical retained string inventory plus optional validated AI annotations and coverage
YARA candidates	Locally compiled detection-engineering seeds requiring review and testing
ATT&CK candidates	Technique-level hypotheses requiring analyst validation
CFG visualization	Function-level control-flow review
SQLite history	Local session evidence and SHA-256-based finding restoration

How It Works

flowchart LR
  Input[PE, ELF, or C source] --> Parse[Bounded parsing and hashing]
  Parse --> Structure[Hex and PE structure evidence]
  Parse --> Strings[Deterministic string intelligence]
  Parse --> Disasm[Capstone disassembly]
  Disasm --> Patterns[Deterministic patterns]
  Disasm --> Ghidra[Ghidra reconstruction]
  Patterns --> Offline[Offline findings]
  Patterns --> AI[Optional LLM cross-check]
  Strings --> StringAI[Opt-in chunked string AI review]
  Ghidra --> AI
  Offline --> Reports[HTML, JSON, YARA, CFG]
  AI --> Reports
  StringAI --> StringJSON[Structured string JSON]
  Reports --> History[SHA-256-indexed history]

Safety and Scope

Use AIDebug only on software and systems you are authorized to examine, inside an isolated malware-analysis VM or lab.

• Static analysis does not execute the inspected PE or ELF.
• C inputs and learning cases are compiled to temporary artifacts that are not executed by their analysis workflows.
• GDB active mode launches a local ELF; Frida mode instruments a running target.
• Outputs are bounded evidence and hypotheses, not automatic attribution or final detection truth.
• Session databases and exports can contain sensitive evidence and are not encrypted by AIDebug.
• Ghidra output is reconstructed C-like code, not recovered original source.

Read the complete safety model, security policy, and limitations and validation plan before analyzing untrusted samples.

Documentation

Document	Purpose
Analyst workflow	Repeatable analysis process
Safety model	Trust boundaries and safe operation
Validation plan	Testable capability claims
Sample evidence	Illustrative screenshots and mock artifacts
Comparison	Scope and positioning
Release readiness	Reproducible release gates
AIDebug 3.1 release notes	Current source release changes
AIDebug 3.0 release notes	Previous published release changes
Changelog	Version history

Development

Run the fast local checks:

python -m ruff check .
python -m pytest -q

Run the complete isolated release gate:

./scripts/release-readiness.sh

See CONTRIBUTING.md for contribution guidance. Do not attach live malware, credentials, private case data, or unredacted evidence to issues or pull requests.

Project

• Releases
• PyPI
• Issues
• Discussions
• Security policy
• Citation metadata
• 1200km security research ecosystem

License

AIDebug is released under the MIT License.