Evidencia centrada en la ingeniería inversa de malware con inspección profunda de PE/.NET, reconstrucción con Ghidra, verificaciones cruzadas con IA, YARA y depuración de ELF.
AIDebug es una CLI e interfaz de terminal centrada en la evidencia para la ingeniería inversa de malware. Combina triaje offline determinista, inspección hexadecimal de archivos completos, análisis profundo de la estructura PE, desensamblado con Capstone, reconstrucción con Ghidra, verificaciones cruzadas opcionales con LLM, depuración local de ELF, ejercicios de aprendizaje compilados e informes para revisión de analistas.
Versión de fuente actual: AIDebug 3.1.0. Consulte las notas de la versión 3.1.0.
La última versión publicada e inmutable sigue siendo AIDebug v3.0.0, disponible como
1200km-aidebug, hasta que la etiqueta 3.1.0 coincidente con la versión y la publicación en GitHub completen el flujo de publicación verificado.
Instale el paquete estable desde 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
Instale capacidades opcionales según sea necesario:
# Proveedores LLM remotos/locales y generación YARA validada
python -m pip install "1200km-aidebug[ai]==3.0.0"
# Instrumentación dinámica con Frida
python -m pip install "1200km-aidebug[dynamic]==3.0.0"
# Todas las integraciones Python opcionales
python -m pip install "1200km-aidebug[all]==3.0.0"
Para desarrollo:
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, un compilador de C y los componentes objetivo de Frida son herramientas externas utilizadas únicamente por los flujos de trabajo que las requieren.
Abra una muestra PE o ELF en la interfaz principal de terminal:
aidebug --binary /path/to/sample.exe --offline
Ejecute análisis determinista sin la interfaz de pantalla completa y exporte evidencia:
aidebug --binary /path/to/sample.exe \
--offline --no-tui --report --json-export --yara \
--out-dir reports/
Use la reconstrucción con 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
Analice una unidad de traducción C mediante un artefacto ELF temporal y no ejecutado:
aidebug --source /path/to/example.c --offline --no-tui
Identifique un archivo arbitrario independientemente de su extensión de nombre:
aidebug --identify /path/to/renamed-or-unknown-file --offline
--identify informa JSON estructurado con el tipo declarado, tipo MIME, extensiones comunes,
confianza, método, evidencia, SHA-256 y tamaño. La cobertura determinista
incluye formatos ejecutables y de bytecode comunes, archivos e imágenes de disco,
contenedores Office/OpenDocument/EPUB, documentos, imágenes, audio/video,
capturas de paquetes, bases de datos, artefactos de registro/registro de eventos, scripts y texto.
Los formatos basados en ZIP se inspeccionan mediante nombres de miembros acotados y lecturas pequeñas de metadatos;
los archivos nunca se ejecutan ni se extraen.
Instale python-magic junto con la base de datos libmagic del sistema operativo para
firmas adicionales conocidas por la plataforma local:
python -m pip install python-magic
Cuando ninguna firma determinista, estructura o regla de texto coincide, un
proveedor de IA configurado puede inferir un candidato a partir de metadatos acotados: la extensión, tamaño,
SHA-256, hasta 96 bytes de cabecera, 32 bytes finales, entropía de muestra y relación NUL.
El cuerpo del archivo, las cadenas extraídas y la ruta del sistema de archivos no se envían. Los resultados
solo de IA se etiquetan ai-inference, se limitan al 60% de confianza y requieren
validación del analista. Use --offline para deshabilitar el respaldo por completo; un
tipo no resuelto se informa como Unknown con estado de salida 2.
Presione S en la interfaz principal de terminal, o inicie directamente en el espacio de trabajo:
aidebug --binary /path/to/sample.exe --offline --strings
El espacio de trabajo conserva desplazamientos de archivo, direcciones mapeadas cuando están disponibles, codificación, longitudes de bytes y caracteres, información de ocurrencias duplicadas, contexto de sección, confianza, puntuación de triaje y las razones deterministas de cada clasificación. Los filtros cubren longitud mínima, codificación, categoría y búsqueda de texto libre; la ordenación de columnas y la paginación mantienen inventarios grandes utilizables. Cada codificación seleccionada escanea el artefacto completo acotado por tamaño. El inventario retenido está limitado a 25,000 registros y 4,096 caracteres mostrados por valor; los recuentos exactos de candidatos/omisiones y la cobertura completa de bytes hacen visible cualquier límite. Cada registro conserva como máximo 32 anotaciones DLL/API y 4,096 caracteres de descripción; los desbordamientos adversarios se informan en las razones del registro.
La detección es de múltiples etiquetas. Un solo valor puede ser simultáneamente una DLL, ruta de Windows,
URL, dirección IP, clave de registro, comando, fragmento de PowerShell, canal con nombre,
hash, candidato de credencial, agente de usuario u otro tipo de evidencia compatible.
Los candidatos de dominio se normalizan con IDNA y se verifican contra una instantánea offline empaquetada
de la zona raíz de IANA; las direcciones IP deben ocupar un token válido completo, y
las asignaciones de configuración deben coincidir con una gramática conservadora de línea completa. Esto
evita que fragmentos binarios cortos se promuevan simplemente porque contienen un
punto, dos puntos o signo igual. Las etiquetas relacionadas comparten una familia de confianza, por lo que
ip_address más ipv6 no se trata como dos observaciones independientes.
Las DLL y API conocidas reciben descripciones de capacidad cortas y neutrales; los nombres
desconocidos reciben un respaldo explícito no verificado en lugar de un propósito adivinado.
Un nombre extraído es evidencia de presencia, no prueba de que el código lo invocó o
que la muestra sea maliciosa.
Imprima el inventario determinista localmente, filtre la vista CLI mostrada o escriba el inventario completo canónico como JSON solo para el propietario:
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
La revisión de cadenas con IA es una acción opcional separada. Presione A dentro del espacio de trabajo
y confirme la advertencia de privacidad/costo, o solicítela explícitamente en modo CLI:
aidebug --binary /path/to/sample.exe --strings --no-tui \
--analyze-strings --accept-ai-cost \
--strings-output reports/sample-strings-ai.json
Cada cadena retenida recibe un ID de evidencia estable. Después de la
confirmación explícita, la ruta de IA planifica cada registro retenido en
fragmentos deterministas y acotados; los fallos del proveedor o de validación se detienen de forma segura y permanecen visibles.
Las respuestas deben dar cuenta de cada ID proporcionado y
pasar una validación estricta local de esquema, enumeración, referencia y fundamento de IOC antes de ser
aceptadas. Un reductor final ve hallazgos validados en lugar del
inventario sin procesar. Los límites de extracción, los lotes fallidos
y los recuentos revisados/enviados siempre se informan; la cobertura incompleta fuerza una
evaluación general unknown. Las cadenas pueden contener contraseñas, tokens de API,
datos de clientes e inyección de prompts creada por atacantes, por lo que debe revisar el límite
de IA remota antes de habilitar esta función.
Inspeccione análisis anteriores por archivo o SHA-256:
aidebug --history /path/to/sample.exe
aidebug --history 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
Cargue un archivo PE y presione X (o P) en la GUI principal. AIDebug presenta los
bytes exactos que ha generado el hash y organiza la evidencia estructural en vistas
acotadas y navegables.
| Área | Evidencia |
|---|---|
| Cabeceras | DOS, NT, COFF, Cabecera opcional, características, directorios de datos y banderas de mitigación |
| Secciones | Campos completos de IMAGE_SECTION_HEADER, rangos mapeados, entropía y permisos |
| Importaciones y exportaciones | Descriptores de importación, entradas INT/IAT, importaciones retrasadas, ordinales, nombres, RVA y reenviadores |
| Recursos | Jerarquía de tipo/nombre/idioma, metadatos, hashes, vistas previas y exportación segura sin sobrescritura |
| Reubicaciones y ASLR | Bloques/entradas de reubicación y evaluación estructural de compatibilidad con ASLR |
| TLS | Directorio TLS, datos de plantilla, índice, tabla de callbacks, mapeos y evidencia de terminación |
| Excepciones y desenrollado | Funciones de runtime x64, UNWIND_INFO, operaciones, manejadores y registros encadenados |
| Configuración de carga | Campos versionados, banderas Guard, evidencia de cookie de pila y mitigación de explotación |
| CFG | Punteros de verificación/despacho, objetivos de ID de función Guard, ordenación, supresión y verificaciones de consistencia |
| Authenticode | Registros de certificados, evidencia PKCS#7/X.509, comparación de digest de imagen PE y verificación de firmante |
| Depuración y procedencia | Cabecera Rich, Directorio de depuración, CodeView RSDS/NB10, GUID de PDB, edad y ruta |
| Superposiciones | Desplazamiento exacto, tamaño, hash, entropía, vista previa y exportación segura |
| .NET / CLR | Cabecera COR20, raíz y flujos de metadatos, tablas ECMA-335, ensamblados, referencias y recursos |
AIDebug no ejecuta un PE mientras construye estas vistas. La verificación estática de certificados no es confianza raíz de Windows ni validación de revocación, los metadatos Rich no son atribución, los metadatos de nombre seguro no son confianza del editor, y las banderas de mitigación estáticas no son prueba de política de runtime efectiva.
Estos artículos proporcionan los flujos de trabajo detallados y capturas de pantalla que complementan la documentación del repositorio:
Abra el catálogo completo o comience con un caso específico:
aidebug --learn
aidebug --learn mov-load
aidebug --learn lea-arithmetic
aidebug --learn switch-dispatch
Cada caso incluido es un archivo independiente en learning/cases/.
AIDebug compila el caso seleccionado en un ELF x86-64 temporal, muestra el
código C exacto y las instrucciones generadas por el compilador, solicita a Ghidra una
reconstrucción independiente, registra la procedencia de la compilación y elimina el artefacto temporal.
El binario de lección generado nunca se ejecuta.
Use --no-tui para salida de texto, o cargue una colección externa revisada:
aidebug --learn movsxd --no-tui
aidebug --learn --learning-collection /path/to/reviewed-cases
El análisis con IA es opcional. El modo offline determinista sigue disponible sin credenciales.
python -m pip install "1200km-aidebug[ai]==3.0.0"
cp .env.example .env
chmod 600 .env
Configure exactamente un proveedor, o establezca AIDEBUG_LLM_PROVIDER explícitamente cuando
existan varias credenciales:
AIDEBUG_LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=replace_with_your_key
# Alternativas:
# 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 para mantener la configuración alejada
de directorios de análisis no confiables. El análisis remoto por lotes requiere el reconocimiento
explícito --accept-ai-cost. Revise el límite de datos de IA remota
antes de enviar evidencia de muestras a cualquier proveedor.
El modo activo respaldado por GDB ejecuta el ELF local seleccionado. Úselo solo dentro de un laboratorio aislado y autorizado:
aidebug --binary ./sample.elf --mode debug --breakpoint main
Los comandos disponibles incluyen break, continue, step, next, finish,
registers, changes, io, disassemble y quit. El modo dinámico de Frida está
disponible por separado para flujos de trabajo de instrumentación locales o remotos compatibles.
| Salida | Uso previsto |
|---|---|
| Informe HTML | Revisión humana y notas de caso |
| JSON versionado | Entrada para integración personalizada; no es un esquema nativo de proveedor ni STIX |
| JSON de inteligencia de cadenas | Inventario canónico de cadenas retenidas más anotaciones de IA validadas opcionales y cobertura |
| Candidatos YARA | Semillas de ingeniería de detección compiladas localmente que requieren revisión y pruebas |
| Candidatos ATT&CK | Hipótesis a nivel de técnica que requieren validación del analista |
| Visualización CFG | Revisión de flujo de control a nivel de función |
| Historial SQLite | Evidencia de sesión local y restauración de hallazgos basada en 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]Use AIDebug únicamente en software y sistemas que esté autorizado a examinar, dentro de una VM o laboratorio de análisis de malware aislado.
Lea el modelo de seguridad completo, la política de seguridad y el plan de limitaciones y validación antes de analizar muestras no confiables.
| Documento | Propósito |
|---|---|
| Flujo de trabajo del analista | Proceso de análisis repetible |
| Modelo de seguridad | Límites de confianza y operación segura |
| Plan de validación | Afirmaciones de capacidad comprobables |
| Evidencia de muestra | Capturas de pantalla ilustrativas y artefactos simulados |
| Comparación | Alcance y posicionamiento |
| Preparación para publicación | Puertas de publicación reproducibles |
| Notas de la versión AIDebug 3.1 | Cambios de la versión de fuente actual |
| Notas de la versión AIDebug 3.0 | Cambios de la versión publicada anterior |
| Registro de cambios | Historial de versiones |
Ejecute las verificaciones locales rápidas:
python -m ruff check .
python -m pytest -q
Ejecute la puerta de publicación aislada completa:
./scripts/release-readiness.sh
Consulte CONTRIBUTING.md para obtener orientación sobre contribuciones. No adjunte malware en vivo, credenciales, datos de casos privados o evidencia sin redactar a problemas o solicitudes de extracción.
AIDebug se publica bajo la Licencia MIT.