Evidence-focused анализ вредоносного ПО с глубоким исследованием PE/.NET, реконструкцией в Ghidra, перекрёстными проверками с ИИ, YARA и отладкой ELF
AIDebug — это CLI и терминальный интерфейс для реверс-инжиниринга вредоносного ПО, ориентированный на работу с доказательствами. Он объединяет детерминированную офлайн-триаж, просмотр всего файла в шестнадцатеричном виде, глубокий анализ структуры PE, дизассемблирование Capstone, реконструкцию Ghidra, опциональные перекрёстные проверки LLM, локальную отладку ELF, скомпилированные учебные упражнения и формирование отчётов для проверки аналитиком.
Текущая версия исходного кода: AIDebug 3.1.0. См. примечания к выпуску 3.1.0.
Последняя неизменяемая опубликованная версия остаётся AIDebug v3.0.0, доступная как
1200km-aidebug, до тех пор, пока тег 3.1.0, соответствующий версии, и релиз GitHub не завершат проверенный процесс публикации.
Установите стабильный пакет из 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
Установите дополнительные возможности по мере необходимости:
# Удалённые/локальные LLM-провайдеры и проверенная генерация YARA
python -m pip install "1200km-aidebug[ai]==3.0.0"
# Динамическая инструментация Frida
python -m pip install "1200km-aidebug[dynamic]==3.0.0"
# Все дополнительные интеграции Python
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
Запустите детерминированный анализ без полноэкранного интерфейса и экспортируйте доказательства:
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.
Нажмите S в основном терминальном интерфейсе или запустите непосредственно в рабочем пространстве:
aidebug --binary /path/to/sample.exe --offline --strings
Рабочее пространство сохраняет смещения в файле, отображаемые адреса при наличии, кодировку, длины в байтах и символах, информацию о дублирующихся вхождениях, контекст секции, уверенность, оценку триажа и детерминированные причины для каждой классификации. Фильтры охватывают минимальную длину, кодировку, категорию и полнотекстовый поиск; сортировка столбцов и разбиение на страницы делают большие списки удобными. Каждая выбранная кодировка сканирует полный артефакт с ограничением по размеру. Сохранённый список ограничен 25 000 записей и 4 096 отображаемыми символами на значение; точные счётчики кандидатов/пропусков и полное покрытие байтов делают любой предел видимым. Каждая запись сохраняет не более 32 аннотаций DLL/API и 4 096 символов описания; враждебные переполнения сообщаются в причинах записи.
Обнаружение является мульти-меточным. Одно значение может одновременно быть DLL, путём Windows,
URL, IP-адресом, ключом реестра, командой, фрагментом PowerShell, именованным каналом,
хэшем, кандидатом учётных данных, пользовательским агентом или другим поддерживаемым типом доказательств.
Кандидаты доменов нормализуются по IDNA и проверяются по встроенному офлайн
снимку корневой зоны IANA; IP-адреса должны занимать полный допустимый токен, а
назначения конфигурации должны соответствовать консервативной грамматике полной строки. Это
предотвращает продвижение коротких бинарных фрагментов только потому, что они содержат точку,
двоеточие или знак равенства. Связанные метки используют одну семью уверенности, поэтому
ip_address плюс ipv6 не рассматриваются как два независимых наблюдения.
Известные DLL и API получают краткие нейтральные описания возможностей; неизвестные
имена получают явный непроверенный запасной вариант вместо угаданного назначения.
Извлечённое имя — это доказательство присутствия, а не доказательство того, что код его вызвал или
что образец вредоносен.
Выведите детерминированный список локально, отфильтруйте отображаемое CLI-представление или запишите канонический полный список как 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-проверка строк — это отдельное действие по согласию. Нажмите A внутри рабочего
пространства и подтвердите предупреждение о конфиденциальности/стоимости или запросите его явно в режиме CLI:
aidebug --binary /path/to/sample.exe --strings --no-tui \
--analyze-strings --accept-ai-cost \
--strings-output reports/sample-strings-ai.json
Каждой сохранённой строке присваивается стабильный идентификатор доказательства. После явного
подтверждения AI-путь планирует каждую сохранённую запись по детерминированным,
ограниченным фрагментам; сбои провайдера или валидации безопасно останавливаются и остаются видимыми.
Ответы должны учитывать каждый предоставленный идентификатор и
пройти строгую локальную проверку схемы, перечислений, ссылок и привязки IOC, прежде чем
будут приняты. Финальный редуктор видит проверенные находки, а не
сырой список. Лимиты извлечения, неудачные пакеты
и подсчитанные/отправленные количества всегда сообщаются; неполное покрытие приводит к
общей оценке unknown. Строки могут содержать пароли, токены API,
данные клиентов и инъекции промптов, созданные злоумышленником, поэтому проверьте границу удалённого AI,
прежде чем включать эту функцию.
Просмотрите предыдущий анализ по файлу или SHA-256:
aidebug --history /path/to/sample.exe
aidebug --history 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
Загрузите PE-файл и нажмите X (или P) в основном GUI. AIDebug представляет
точные байты, которые он хэшировал, и организует структурные доказательства в ограниченные,
навигационные представления.
| Область | Доказательства |
|---|---|
| Заголовки | DOS, NT, COFF, Optional Header, характеристики, каталоги данных и флаги смягчения |
| Секции | Полные поля IMAGE_SECTION_HEADER, отображаемые диапазоны, энтропия и разрешения |
| Импорты и экспорты | Дескрипторы импорта, записи INT/IAT, отложенные импорты, порядковые номера, имена, RVA и форвардеры |
| Ресурсы | Иерархия тип/имя/язык, метаданные, хэши, предпросмотры и безопасный экспорт без перезаписи |
| Релокации и ASLR | Блоки/записи релокаций и структурная оценка совместимости ASLR |
| TLS | Каталог TLS, данные шаблона, индекс, таблица обратных вызовов, отображения и доказательства завершения |
| Исключения и размотка | Функции времени выполнения x64, UNWIND_INFO, операции, обработчики и связанные записи |
| Конфигурация загрузки | Версионированные поля, флаги Guard, доказательства cookie стека и смягчения эксплойтов |
| CFG | Указатели проверки/диспетчеризации, цели Guard Function ID, упорядочивание, подавление и проверки согласованности |
| Authenticode | Записи сертификатов, доказательства PKCS#7/X.509, сравнение дайджеста образа PE и проверка подписанта |
| Отладка и происхождение | Rich header, Debug Directory, CodeView RSDS/NB10, GUID PDB, возраст и путь |
| Оверлеи | Точное смещение, размер, хэш, энтропия, предпросмотр и безопасный экспорт |
| .NET / CLR | Заголовок COR20, корень метаданных и потоки, таблицы ECMA-335, сборки, ссылки и ресурсы |
AIDebug не выполняет PE при построении этих представлений. Статическая проверка сертификатов — это не доверие корневых сертификатов Windows или проверка отзыва, метаданные Rich — это не атрибуция, метаданные строгого имени — это не доверие издателю, а статические флаги смягчения — это не доказательство эффективной политики времени выполнения.
Эти статьи содержат подробные рабочие процессы и скриншоты, дополняющие документацию репозитория:
Откройте полный каталог или начните с конкретного примера:
aidebug --learn
aidebug --learn mov-load
aidebug --learn lea-arithmetic
aidebug --learn switch-dispatch
Каждый встроенный пример — это отдельный файл в learning/cases/.
AIDebug компилирует выбранный пример во временный x86-64 ELF, показывает точный
исходный код C и сгенерированные компилятором инструкции, запрашивает у Ghidra независимую
реконструкцию, записывает происхождение сборки и удаляет временный артефакт.
Сгенерированный учебный бинарный файл никогда не выполняется.
Используйте --no-tui для текстового вывода или загрузите проверенную внешнюю коллекцию:
aidebug --learn movsxd --no-tui
aidebug --learn --learning-collection /path/to/reviewed-cases
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
# Альтернативы:
# 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. Ознакомьтесь с границей данных удалённого AI
перед отправкой доказательств образца любому провайдеру.
Активный режим на основе GDB выполняет выбранный локальный ELF. Используйте его только внутри изолированной, авторизованной лаборатории:
aidebug --binary ./sample.elf --mode debug --breakpoint main
Доступные команды включают break, continue, step, next, finish,
registers, changes, io, disassemble и quit. Динамический режим Frida доступен
отдельно для поддерживаемых рабочих процессов локальной или удалённой инструментации.
| Вывод | Предназначение |
|---|---|
| HTML-отчёт | Проверка человеком и заметки по делу |
| Версионированный JSON | Ввод для пользовательской интеграции; не собственная схема или STIX |
| JSON интеллектуального анализа строк | Канонический сохранённый список строк плюс опциональные проверенные AI-аннотации и покрытие |
| YARA-кандидаты | Локально скомпилированные семена детектирования, требующие проверки и тестирования |
| ATT&CK-кандидаты | Гипотезы на уровне техник, требующие валидации аналитиком |
| Визуализация CFG | Проверка потока управления на уровне функций |
| История SQLite | Локальные доказательства сеанса и восстановление находок на основе SHA-256 |
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 только на программном обеспечении и системах, которые вы уполномочены исследовать, внутри изолированной ВМ или лаборатории для анализа вредоносного ПО.
Прочитайте полную модель безопасности, политику безопасности и ограничения и план валидации перед анализом недоверенных образцов.
| Документ | Назначение |
|---|---|
| Рабочий процесс аналитика | Повторяемый процесс анализа |
| Модель безопасности | Границы доверия и безопасная эксплуатация |
| План валидации | Проверяемые заявления о возможностях |
| Примеры доказательств | Иллюстративные скриншоты и имитационные артефакты |
| Сравнение | Область применения и позиционирование |
| Готовность к выпуску | Воспроизводимые ворота выпуска |
| Примечания к выпуску AIDebug 3.1 | Изменения текущего исходного выпуска |
| Примечания к выпуску AIDebug 3.0 | Изменения предыдущего опубликованного выпуска |
| Журнал изменений | История версий |
Запустите быстрые локальные проверки:
python -m ruff check .
python -m pytest -q
Запустите полные изолированные ворота выпуска:
./scripts/release-readiness.sh
См. CONTRIBUTING.md для руководства по внесению вклада. Не прикрепляйте живое вредоносное ПО, учётные данные, приватные данные дел или неотредактированные доказательства к проблемам или запросам на включение.
AIDebug выпущен под лицензией MIT.