AIDebug

AIDebug — это CLI-инструмент и терминальный интерфейс для обратной инженерии вредоносного ПО с фокусом на доказательства (evidence-focused). Он объединяет детерминированную офлайн-триажу, постраничный просмотр всего файла в шестнадцатеричном виде, глубокий анализ структуры PE, дизассемблирование Capstone, реконструкцию Ghidra, опциональную перепроверку с помощью LLM, локальную отладку ELF, скомпилированные учебные упражнения и отчёты для аналитика.

Текущая версия исходного кода: AIDebug 3.1.0. См. заметки к релизу 3.1.0.

Последний неизменный опубликованный релиз остаётся AIDebug v3.0.0, доступный как 1200km-aidebug, до завершения проверенного процесса публикации для тега 3.1.0 и соответствующего GitHub-релиза.

Особенности

• Детерминированная статическая триажа PE и ELF без необходимости в AI-сервисе.
• Интеллектуальный анализ строк по всему файлу с учётом вхождений для кодировок ASCII, UTF-8, UTF-16LE и UTF-16BE с умными категориями, ранжированием и объяснениями DLL/API.
• Постраничный шестнадцатеричный просмотрщик всего анализируемого файла в режиме только чтения.
• Глубокий обозреватель структуры PE32/PE32+ с отображением RVA, VA и файловых смещений.
• Реконструкция в C-подобном виде на базе Ghidra для одной функции или полного ограниченного набора функций.
• Опциональная доказательная перепроверка через Anthropic, OpenAI, Google Gemini или локальную Ollama-совместимую точку входа.
• Локальная отладка ELF на базе GDB с точки останова, пошаговым выполнением, регистрами, дельтами, контекстом дизассемблирования и кандидатами входов/выходов функций.
• Сто автономных учебных случаев на C с реальным выводом компилятора, дизассемблированием и псевдокодом Ghidra в основном GUI.
• Локальная история анализов, индексированная SHA-256, и совместимое восстановление результатов.
• Вывод в HTML, версионированный JSON, кандидаты YARA, кандидаты ATT&CK и CFG для проверки аналитиком.

Установка

Установите стабильный пакет из 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

Установите опциональные возможности по необходимости:

# 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"

Для разработки:

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, C-компилятор и целевые компоненты Frida — это внешние инструменты, используемые только теми рабочими процессами, которые в них нуждаются.

Быстрый старт

Откройте образец PE или ELF в главном терминальном интерфейсе:

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

Запустите детерминированный анализ без полноэкранного UI и экспортируйте доказательства:

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

Используйте реконструкцию Ghidra:

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

Проанализируйте одну единицу трансляции C через временный неисполняемый ELF-артефакт:

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

Идентифицируйте произвольный файл независимо от расширения имени файла:

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

--identify выдаёт структурированный JSON с объявленным типом, MIME-типом, распространёнными расширениями, уверенностью, методом, доказательствами, SHA-256 и размером. Детерминированное покрытие включает распространённые форматы исполняемых файлов и байт-кода, архивы и образы дисков, контейнеры Office/OpenDocument/EPUB, документы, изображения, аудио/видео, захваты пакетов, базы данных, артефакты реестра и журналов событий, скрипты и текст. ZIP-базированные форматы проверяются по ограниченным именам элементов и небольшим чтениям метаданных; файлы никогда не выполняются и не извлекаются.

Установите python-magic и системную базу данных libmagic операционной системы для дополнительных сигнатур, известных локальной платформе:

python -m pip install python-magic

Когда ни одна детерминированная сигнатура, структура или текстовое правило не совпадает, настроенный AI-провайдер может вывести кандидата из ограниченных метаданных: расширение, размер, SHA-256, до 96 байт заголовка, 32 байта хвоста, примерную энтропию и отношение NUL. Тело файла, извлечённые строки и путь в файловой системе не отправляются. Результаты только от AI помечаются как ai-inference, ограничиваются 60% уверенности и требуют проверки аналитиком. Используйте --offline для полного отключения запасного варианта; неразрешённый тип сообщается как Unknown с кодом выхода 2.

Рабочая область строкового интеллекта (3.1.0)

Нажмите S в главном терминальном интерфейсе или запустите рабочую область напрямую:

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

Рабочая область сохраняет файловые смещения, отображённые адреса (при наличии), кодировку, длины в байтах и символах, информацию о дублирующихся вхождениях,

Рабочее пространство структуры PE

Загрузите PE-файл и нажмите X (или P) в главном GUI. Aidebug показывает точные байты, которые были захешированы, и организует структурные доказательства в ограниченные, навигируемые представления.

Aidebug не выполняет PE-файл при построении этих представлений. Статическая верификация сертификата — это не проверка доверенных корневых центров Windows или проверка отзыва, Rich-метаданные — не атрибуция, метаданные строгого имени — не доверие к издателю, и статическая флаги смягчения не являются доказательством эффективной политики выполнения.

Опубликованные руководства

Эти статьи предоставляют подробные рабочие процессы и скриншоты, дополняющие документацию репозитория:

• AIDebug 3.1 Полный обзор выпуска: от приёма бинарника до строковой разведки — полный рабочий процесс evidence-first через идентификацию файла, триаж PE и ELF, функции, граф потока управления, строки, Ghidra, опциональный AI-обзор, контролируемую отладку, историю и отчёты.
• Анализ строк для анализа вредоносного ПО: превращение бинарного текста в обоснованные гипотезы — извлечение с учётом вхождений, консервативная категоризация, валидация IOC, перекрёстные ссылки и AIDebug String Intelligence.
• Структура PE-файла для анализа вредоносного ПО: практическое руководство — структура PE, поведение загрузчика, заголовки, секции, импорт, экспорт, ресурсы, релокации, TLS, митигации, подписи, оверлеи и метаданные .NET с AIDebug.
• Ассемблер для анализа вредоносного ПО: практическое руководство по x86/x64 — регистры, флаги, соглашения о вызовах, поток управления, Windows API и практические обучающие кейсы AIDebug.
• AI-отладчик вредоносного ПО, объясняющий каждую видимую функцию — оригинальный обзор проекта AIDebug, сохранённый локально.

Режим обучения

Откройте полный каталог или начните с конкретного кейса:

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

Каждый встроенный кейс — это отдельный файл в learning/cases/. AIDebug компилирует выбранный кейс во временный x86-64 ELF, показывает точный исходный код на C и сгенерированные компилятором инструкции, запрашивает у Ghidra независимую реконструкцию, фиксирует provenance сборки и удаляет временный артефакт. Сгенерированный обучающий бинарник никогда не выполняется.

Используйте --no-tui для текстового вывода или загрузите проверенную внешнюю коллекцию:

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

AI-провайдеры

AI-анализ опционален. Детерминированный офлайн-режим доступен без учётных данных.

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

Настройте ровно одного провайдера или явно задайте AIDEBUG_LLM_PROVIDER, когда существует несколько наборов учётных данных:

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

Используйте AIDEBUG_ENV_FILE=/absolute/path/to/private.env, чтобы держать конфигурацию в стороне от непроверенных директорий анализа. Удалённый массовый анализ требует явного подтверждения --accept-ai-cost. Просмотрите границу данных remote-AI перед отправкой доказательств сэмпла любому провайдеру.

Активная отладка ELF

GDB-режим активного выполнения запускает выбранный локальный ELF. Используйте его только внутри изолированной, авторизованной лаборатории:

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

Доступные команды включают break, continue, step, next, finish, registers, changes, io, disassemble и quit. Frida-режим динамической инструментации доступен отдельно для поддерживаемых локальных или удалённых рабочих процессов.

Выходные данные

Как это работает

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]

Безопасность и область применения

Используйте AIDebug только на программном обеспечении и системах, которые вы авторизованы исследовать, внутри изолированной VM для анализа вредоносного ПО или лаборатории.

• Статический анализ не выполняет исследуемый PE или ELF.
• C-входные данные и обучающие кейсы компилируются во временные артефакты, которые не выполняются их рабочими процессами анализа.
• GDB-активный режим запускает локальный ELF; Frida-режим инструментирует работающую цель.
• Выходные данные — ограниченные доказательства и гипотезы, не автоматическая атрибуция или окончательная истина детекции.

• Базы данных сессий и экспорты могут содержать конфиденциальные доказательства и не шифруются AIDebug.
• Результат работы Ghidra — это реконструированный C-подобный код, а не восстановленный оригинальный исходный код.

Ознакомьтесь с полной моделью безопасности, политикой безопасности и планом валидации и ограничениями перед анализом недоверенных образцов.

Документация

Разработка

Запустите быстрые локальные проверки:

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

Запустите полный изолированный гейт релиза:

./scripts/release-readiness.sh

См. CONTRIBUTING.md для руководства по внесению вклада. Не прикрепляйте живое вредоносное ПО, учётные данные, частные данные дел или неочищенные доказательства к issue или pull request.

Проект

• Релизы
• PyPI
• Issues
• Обсуждения
• Политика безопасности
• Метаданные для цитирования
• Экосистема безопасности 1200km

Лицензия

AIDebug распространяется под лицензией MIT.