Aether v6.0 — Marco de análisis de seguridad de contratos inteligentes

Versión 6.0 | Novedades en v6.0 | Registro de cambios

Aether es un marco basado en Python para analizar contratos inteligentes Solidity, generar hallazgos de vulnerabilidades, producir pruebas de concepto (PoC) basadas en Foundry y validar explotaciones en forks de mainnet. Combina análisis de AST de Solidity, análisis de flujo de datos (taint analysis), análisis de grafos de flujo de control, análisis entre contratos, ejecución simbólica con Halmos, más de 180 detectores estáticos basados en patrones, un pipeline colaborativo multi-agente LLM (GPT/Gemini/Claude) con memoria institucional SAGE compartida, 14 arquetipos de protocolos, una base de conocimiento de más de 75 explotaciones, detección calibrada con ML, detección de peculiaridades de tokens, extracción de invariantes, resolución de contexto de contratos relacionados y filtrado avanzado sensible al contexto, todo en una única TUI persistente de pantalla completa.

Novedades en v6.0

Pipeline de agentes colaborativos — El pipeline de análisis profundo pasa de 5 ejecuciones independientes a 5 agentes colaborativos que comparten conocimiento estructurado a través de la memoria institucional SAGE:

• Memoria de sesión compartida — Cada ejecución almacena hallazgos, descartes y protecciones verificadas en una sesión SAGE por auditoría. Las ejecuciones posteriores reciben "Inteligencia de Ejecuciones Previas" en lugar de resúmenes de texto planos.
• Descartes como registros de primera clase — Cuando la Ejecución 3 descarta una preocupación (p. ej., "reentrancy protegida por el modificador nonReentrant"), la Ejecución 5 no la volverá a marcar. Esto elimina directamente la fuente #1 de hallazgos duplicados.
• Mecanismo de desafío — Las ejecuciones posteriores pueden anular descartes previos, pero deben aportar NUEVAS evidencias. "La Ejecución 3 no vio la ruta de callback a través de esta otra función" es válido. "No estoy de acuerdo" no lo es.
• Confirmación entre ejecuciones — Cuando varias ejecuciones confirman un hallazgo de forma independiente, la confianza recibe un impulso del 15%. Los hallazgos confirmados entre ejecuciones se priorizan en los informes.
• SAGE obligatorio — La memoria institucional ahora es obligatoria, no opcional. Sin SAGE = sin auditoría. Ejecute docker compose up -d para iniciarlo.

Novedades en v5.0

Memoria institucional SAGE — Aether ahora aprende de cada auditoría, reduciendo falsos positivos y mejorando la calidad de los hallazgos con el tiempo:

• Base de conocimiento preentrenada — Incluye 170 memorias institucionales: 75 patrones de explotación, 63 listas de verificación de arquetipos de protocolos, 12 categorías de peculiaridades de tokens, 20 explotaciones históricas seleccionadas (DAO, Wormhole, Euler, Ronin, Curve y más)
• Integración en el pipeline — SAGE recuerda hallazgos históricos y patrones de explotación en las Ejecuciones 3 y 5 del análisis profundo; almacena aprendizajes de auditorías después del pipeline para su recuperación futura
• Bucle de retroalimentación — Los hallazgos confirmados se almacenan como hechos de alta confianza; los hallazgos rechazados (falsos positivos) se almacenan para que futuras auditorías los eviten. Los resultados de AccuracyTracker alimentan automáticamente a SAGE
• Pipeline de validación — Nueva Etapa -1: la verificación de FP conocidos de SAGE filtra hallazgos que coinciden con patrones previamente rechazados antes de que se ejecute cualquier otra validación
• Sincronización de precisión de detectores — SageFeedbackManager.sync_detector_accuracy() identifica detectores de alto/bajo rendimiento y almacena reflexiones de hacer/no hacer
• Auto-siembra al iniciar — El primer lanzamiento con Docker de SAGE en ejecución siembra automáticamente la base de conocimiento preentrenada. Consciente de versiones: omite si ya está sembrada
• Integración TUI — Estado SAGE ON/OFF con recuento de memoria mostrado en la CostBar
• Despliegue con Docker — docker compose up -d inicia SAGE; configuración mediante sage_enabled/sage_url en ~/.aether/config.yaml
• Degradación elegante — La indisponibilidad de SAGE nunca rompe ninguna funcionalidad de auditoría

Colaboradores: Gracias a @sashavdv por corregir variables de ruta codificadas (PR #1) y a @pro258b por identificar el método faltante validate_anthropic_key() (PR #2).

Inicio rápido de SAGE

SAGE es un sistema de memoria institucional persistente impulsado por consenso BFT. Consulte el proyecto SAGE para obtener documentación completa.```bash

Install SAGE Python SDK

pip install sage-agent-sdk

Start SAGE (Docker required)

docker compose up -d

Run Aether — SAGE auto-seeds on first launch

python aether.py

Regenerate seed fixtures after updating knowledge bases (dev only)

python -c "from core.sage_seeder import SageSeeder; SageSeeder.generate_seed_fixtures()"

### Cómo SAGE mejora las auditorías```
Audit 1 → Findings + FPs → Record outcomes in SAGE
                                    ↓
Audit 2 → SAGE recalls FP patterns → Fewer false positives
                                    ↓
Audit 3 → Richer institutional context → Better severity calibration
                                    ↓
Audit N → Institutional expert-level knowledge → Bug-bounty-quality findings

Novedades en v4.7

Ejecución automática de PoC — Los PoC de Foundry generados ahora se compilan y ejecutan automáticamente:

• La integración con forge test --json ejecuta los PoC inmediatamente después de la compilación
• Análisis de resultados JSON con el dataclass PoCTestResult para informes estructurados de aprobado/fallo/error
• Soporte de modo fork para validar exploits en mainnet contra el estado en vivo
• Nueva fase POC_TESTING en JobManager para el seguimiento en vivo del progreso en la TUI

Ejecución simbólica de Halmos — Verificación formal mediante ejecución simbólica:

• HalmosRunner para ejecutar pruebas simbólicas de Halmos contra las propiedades generadas
• HalmosPropertyGenerator para auto-generar propiedades de verificación a partir de invariantes extraídas
• Nodo de pipeline HalmosSymbolicNode integrado en la Etapa 1.95 de validación
• Opciones de configuración: enable_symbolic_verification, halmos_timeout
• Degradación elegante si Halmos no está instalado: omite la verificación simbólica sin errores

Análisis de grafo de flujo de control — Comprensión del flujo de control a nivel de compilador:

• Dataclasses BasicBlock, CFGEdge, ControlFlowGraph en solidity_ast.py
• build_cfg(), get_dominators(), get_loop_headers(), format_cfg_for_llm() para análisis estructural
• Análisis de bloques de ensamblador mediante parse_assembly_block() para soporte de ensamblador inline
• Propagación de taint con conocimiento de ramas en el analizador de taint para análisis sensible a la ruta
• Contexto CFG inyectado en el Pass 2 del análisis profundo junto con los datos de taint

Bucle de retroalimentación de ML — Calibración basada en resultados históricos:

• AccuracyTracker.record_finding_outcome() para registrar resultados de envíos y recompensas de bounty
• get_detector_accuracy() y get_detector_weights() para estadísticas de rendimiento por detector
• Dataclass DetectorStats que rastrea verdaderos/falsos positivos y precisión histórica
• Ajuste del peso de confianza en EnhancedVulnerabilityDetector según el historial del detector
• Calibración de severidad a partir de datos históricos inyectada en el Pass 5 del análisis profundo

Contexto de contratos relacionados — El análisis LLM ahora ve el código fuente completo de las dependencias:

• RelatedContractResolver descubre automáticamente contratos padre, interfaces, librerías y dependencias
• El modo proyecto usa análisis de relaciones entre contratos; el modo de archivo único analiza las declaraciones de import
• Sistema de presupuesto por pass: 200K caracteres para passes de Gemini Flash, 100K para Claude, 50K para GPT
• Las librerías estándar (@openzeppelin, solmate, solady) se resumen solo a interfaces para ahorrar presupuesto
• Las auditorías de archivo único descubren automáticamente archivos .sol hermanos para contexto

Limpieza de deuda técnica — Se eliminaron 8,500 líneas de código muerto:

• Eliminados: ai_ensemble.py, audit_engine.py, fork_verifier.py
• Se eliminaron todas las referencias a ai_ensemble de la CLI, el ejecutor de auditorías, las pantallas de la TUI y el generador de informes
• Se eliminó slither_project_cache del gestor de base de datos
• Se eliminaron los stubs de verificación formal del motor de auditoría mejorado

Novedades en v4.0

Análisis AST de Solidity — Aether v4.0 añade análisis de código respaldado por compilador mediante py-solc-x, superando el análisis estático basado solo en regex:

• Integración completa de solc --ast-json para resolución correcta de herencia, visibilidad de funciones, diseño de almacenamiento con números de slot y seguimiento de lecturas/escrituras de variables de estado por función
• Retroceso elegante a regex cuando la compilación falla (imports faltantes, versión incorrecta del compilador)
• Resumen estructural del AST alimentado automáticamente al pipeline LLM de análisis profundo para una mejor comprensión del protocolo

Motor de análisis de taint — Rastrea entradas controladas por el usuario a través de los contratos para identificar flujos de datos peligrosos:

• 8 tipos de fuentes de taint: parámetros de función, msg.sender, msg.value, calldata, retornos de llamadas externas, block.timestamp, block.number, tx.origin
• 12 tipos de sinks peligrosos: delegatecall, selfdestruct, llamadas externas, transferencias de ETH, escrituras en almacenamiento, indexado de arrays, división por cero y más
• Detección de sanitizadores: reconoce comprobaciones de límites con require, modificadores de control de acceso, reverts condicionales, límites con Math.min/max, SafeCast
• Rastreo de taint entre contratos a través de múltiples archivos
• Integrado en el pipeline de validación (Etapa 1.85) para corroboración/refutación de hallazgos consciente del taint

Análisis entre contratos (Pass 3.5) — Nuevo pass de análisis profundo dirigido a vulnerabilidades multi-contrato:

• Analizador de relaciones entre contratos: detecta herencia, llamadas a interfaces, delegatecall, staticcall y relaciones tipadas de variables de estado
• Agrupación union-find de contratos relacionados con detección de límites de confianza
• Pass LLM dedicado que analiza: violaciones de límites de confianza, consistencia de estado entre contratos, reentrancy entre contratos, cumplimiento de interfaces, interacciones de actualización y escalada de privilegios
• El contexto entre contratos también se alimenta al Pass 4 para conciencia entre funciones

Base de datos de peculiaridades de tokens — 12 categorías de comportamientos ERC-20 no estándar que causan exploits reales:

Integrada en el pipeline de detección estática y en las listas de verificación de arquetipos.

Motor de precisión mejorado — Detección avanzada de vulnerabilidades de redondeo y precisión:

• Inflación de participaciones / ataque del primer depositante para vaults ERC-4626, pools de préstamo y staking
• Análisis de dirección de redondeo — los depósitos deben redondear hacia ABAJO, los retiros hacia ARRIBA
• Seguimiento de truncamiento de división — detecta variables de tasa truncadas que luego se usan en multiplicaciones
• Detección de explotación de dust — redondear a cero permite operaciones gratuitas
• Desbordamiento de acumulador — evaluación del riesgo de desbordamiento del acumulador de recompensas

Generación de PoC ejecutables — Las pruebas Foundry generadas ahora realmente se compilan y ejecutan:

• Librería de contratos mock: MockERC20, MockOracle, MockWETH, MockFlashLoanProvider
• Generador inteligente de setUp(): extrae parámetros del constructor, despliega mocks, maneja contratos actualizables, mintea tokens y establece aprobaciones
• El número máximo de intentos de compilación aumentó de 3 a 5
• Los prompts de LLM incluyen documentación de la API mock y un setUp recomendado

Mejoras en el pipeline de LLM:

• Ejemplos few-shot en los Passes 3, 4 y 5: ejemplos de vulnerabilidades reales y falsos positivos de la base de conocimiento de exploits
• Calibración de severidad — umbrales concretos vinculados al impacto financiero (Critical >$1M, High >$100K, Medium >$10K)
• Aplicación de chain-of-thought — razonamiento obligatorio en 5 pasos antes de la salida JSON
• Rotación multi-proveedor — Gemini Flash para passes baratos, Anthropic Claude para razonamiento, OpenAI GPT para diversidad
• Ensemble de IA retirado — el ensemble de 6 agentes (6 veces el costo, peor contexto) se reemplazó por rotación de proveedores dentro del pipeline estructurado

Novedades en v3.5

Motor de análisis profundo — Aether v3.5 transforma fundamentalmente la forma en que la herramienta encuentra vulnerabilidades, pasando de una llamada LLM de una sola vez para "encontrar bugs" a un pipeline estructurado de 6 passes que refleja cómo los auditores profesionales abordan la revisión de código: primero entender, luego atacar sistemáticamente.

Motor de análisis profundo (pipeline LLM de 6 passes)

En lugar de enviar un contrato completo a un LLM con un solo prompt, Aether ahora ejecuta seis passes de análisis secuenciales con contexto acumulado:

Los Passes 1 y 2 se almacenan en caché por hash del contenido del contrato, por lo que las re-auditorías omiten la fase de comprensión. Cada pass posterior recibe todo el contexto previo, construyendo un modelo de ataque integral. Activado mediante la feature flag AETHER_DEEP_ANALYSIS=1 (activada por defecto); en caso de fallo, se recurre al modo de una sola vez.

Sistema de arquetipos de protocolo

Antes de analizar en busca de bugs, Aether detecta qué tipo de protocolo implementa el contrato y carga listas de verificación de vulnerabilidades específicas del arquetipo:

10 arquetipos en total, cada uno con 3-7 elementos específicos de la lista extraídos de exploits reales.

Base de conocimiento de exploits (50+ patrones)

Una base de datos estructurada de más de 50 patrones de exploits reales categorizados reemplaza la anterior lista estática de 10 patrones:

Cada patrón incluye indicadores de código, protecciones faltantes, mecanismo de exploit paso a paso y precedentes del mundo real (con montos en dólares). Los patrones se filtran por el arquetipo detectado y el área de enfoque del agente.

Motor de invariantes

Extrae automáticamente invariantes de protocolo de tres fuentes:

1. Etiquetas NatSpec @invariant en los comentarios del contrato
2. Invariantes descubiertas por LLM del Pass 1 del análisis profundo
3. Invariantes comunes detectadas por patrones (conservación de saldos, producto constante de AMM, ratios de colateralización, etc.)

Genera suites de pruebas invariant_*() de Foundry que sirven como pruebas de verificación formal ligera: una prueba de invariante que falla demuestra que el bug es real.

Correcciones del pipeline

• Calibración de severidad sensible al contexto — ya no degrada automáticamente division_by_zero, integer_underflow, etc. a bajo. Ahora comprueba si el hallazgo está en un bloque unchecked{}, cerca de transferencias de valor, en cálculos de precios o en contextos de oráculo antes de decidir
• Corrección de la puerta de validación — los hallazgos "pending" ahora pasan al análisis LLM (antes solo pasaban los "validated", descartando silenciosamente muchos hallazgos reales)
• Penalización de confianza consciente del especialista — los hallazgos de un solo agente provenientes de un especialista en su dominio (p. ej., AnthropicReasoningSpecialist que encuentra un bug lógico complejo) reciben solo -0.05 de penalización en lugar de -0.15
• Corrección de deduplicación por grupos de líneas — se eliminó la agrupación arbitraria (line // 10) * 10 que separaba hallazgos con 2 líneas de diferencia en grupos distintos
• Integración del detector DeFi — DeFiVulnerabilityDetector (análisis de presencia/ausencia en dos etapas) ahora se ejecuta en el motor de auditoría mejorado principal, no solo en el pipeline basado en flujos

Novedades en v3.0

TUI textual totalmente integrada — Aether v3.0 es una aplicación persistente de pantalla completa que nunca vuelve a una terminal sin formato. Cada operación (auditorías, generación de PoC, generación de informes, selección de alcance en GitHub, configuración de ajustes) se ejecuta íntegramente dentro de la TUI:

• Cero llamadas a app.suspend() — la TUI nunca desaparece, sin cambios bruscos de terminal
• Trabajos en segundo plano para todo — auditorías locales, auditorías de GitHub, generación de PoC y generación de informes se ejecutan como hilos daemon con transmisión de salida en vivo
• Tabla de trabajos en vivo — vista estilo htop de todos los trabajos en ejecución/completados con estado en tiempo real, progreso por fases, número de hallazgos, costo y tiempo transcurrido
• Desglose por trabajo — pulsa Enter en cualquier trabajo para ver salida desplazable en vivo, barra de progreso de fases y metadatos
• Operaciones concurrentes — inicia múltiples auditorías, generaciones de PoC e informes simultáneamente; todo visible y rastreable
• Diálogo de selección de contratos — selección múltiple filtrable y casi a pantalla completa que reemplaza al antiguo selector basado en curses. Espacio para alternar, a/n para todos/ninguno, escribir para filtrar, contratos auditados previamente codificados por color
• Flujo de auditoría de GitHub integrado — clona, descubre, selecciona contratos y lanza auditorías sin salir de la TUI. Gestión de alcance (continuar, re-auditar, nuevo alcance) mediante diálogos nativos de Textual
• Ajustes integrados — configuración de la clave API y selección de modelo mediante TextInputDialog y SelectDialog, sin necesidad de asistente de configuración externo
• Barra de costo de sesión — seguimiento del costo de LLM en tiempo real por proveedor (OpenAI, Gemini, Anthropic)
• Control por teclado — n Nueva auditoría, r Reanudar, h Historial, PoCs, Informes, Obtener, Ajustes, Salir

Cuatro tipos de trabajos en segundo plano: Todas las operaciones pesadas se ejecutan como hilos daemon en segundo plano mediante AuditRunner, con la salida capturada por ThreadDemuxWriter y visible en JobDetailScreen:

Soporte LLM de tres proveedores: OpenAI (GPT-5/5.3), Google Gemini (2.5/3.0) y Anthropic Claude (Sonnet 4.5/Opus 4.6) para máxima flexibilidad y redundancia.

Generación mejorada de PoC: Análisis de contratos basado en AST, correcciones iterativas de compilación y prompts de LLM listos para producción que generan exploits adecuados para envíos a bug bounty.

Filtrado avanzado de falsos positivos: La validación en múltiples etapas reduce los falsos positivos del 66% a ~20-25%, mejorando la precisión del 33% al 75-80%:

• Detección de scripts — los scripts de despliegue (script/, .s.sol, forge-std/Script.sol) se excluyen automáticamente del análisis de vulnerabilidades
• Marcadores de contexto de archivo — los prompts de LLM incluyen etiquetas [PRODUCTION]/[DEPLOYMENT SCRIPT] para que los modelos se centren en el código de producción
• Detección dinámica de modificadores — modificadores de control de acceso personalizados (p. ej. onlyDistributor, authorized) extraídos del código fuente del contrato y reconocidos junto con patrones codificados
• Deduplicación por ámbito de función — los hallazgos duplicados en la misma función se fusionan en lugar de usar la frágil proximidad por número de línea
• Detección de constructor atómico — deploy+initialize en el mismo constructor se reconoce como no susceptible de front-running
• Detección de gobernanza (parámetros protegidos por onlyOwner/onlyGovernor)
• Análisis de despliegue (verifica que las rutas de código se usan realmente en producción)
• Comprobaciones de protección integradas (auto-protección de Solidity 0.8+, SafeMath)
• Validación LLM consciente de gobernanza con lista de verificación de 18 patrones
• Seguimiento de precisión con resultados de envíos y ganancias de bounty
• Caché inteligente para análisis repetidos 2x más rápidos

Integración de la base de datos de vulnerabilidades de Move: Patrones de 128 hallazgos Critical/High en 77 auditorías, adaptados para Solidity/EVM:

• Lógica de negocio, gestión de estado, inconsistencia de datos, centralización, problemas de bucles y validación de entrada mejorada

Inicio rápido

1. Configuración```bash

python setup.py # Interactive installer (recommended)

### 2. Lanzar Aether```bash
python aether.py         # Launches the full-screen Textual TUI

Eso es todo. La TUI te guía a través de todo mediante atajos de teclado y diálogos modales.

Requisitos

• Python 3.11+ (probado con 3.12.8)
• Node.js 22+ (para proyectos basados en Hardhat/npm)
• Foundry (forge/anvil) en PATH para la generación y validación de PoC
• solc-select para múltiples versiones del compilador Solidity
• py-solc-x (opcional) para el parseo del AST de Solidity — usa análisis mediante regex como alternativa si no está disponible
• Claves API para las funciones de LLM:
  • OPENAI_API_KEY (para modelos GPT)
  • GEMINI_API_KEY (para modelos Gemini)
  • ANTHROPIC_API_KEY (para modelos Claude)
  • ETHERSCAN_API_KEY (opcional, para obtener contratos verificados)

Instalación Manual

Si prefieres la instalación manual:```bash

Foundry

curl -L https://foundry.paradigm.xyz | bash && foundryup export PATH="$PATH:$HOME/.foundry/bin"

solc-select

pip install solc-select solc-select install 0.4.26 0.8.0 0.8.19 0.8.20 latest

Python dependencies

python -m venv venv && source venv/bin/activate pip install -r requirements.txt

## Configuration

The setup wizard (`python setup.py`) handles everything. You can also configure from within the TUI via `s` (Settings):

- **Configure API Keys** — sequential prompts for OpenAI, Gemini, Anthropic, Etherscan keys with masked current values
- **Configure Models** — select models per provider from available options
- **Full Wizard** — runs API keys followed by model selection
- **Triage Settings** — adjust severity thresholds, confidence levels, max findings

Or set environment variables directly:```bash
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...
export ANTHROPIC_API_KEY=...

Configuration is stored in ~/.aether/config.yaml.

Database locations:

• Engine results: ~/.aether/aetheraudit.db
• GitHub audit workflow: ~/.aether/aether_github_audit.db

TUI Guide

All interaction happens via keyboard shortcuts from the main screen:

n — New Audit

Multi-step wizard with three source types:

Local file or directory:

1. Select path via PathDialog
2. If directory, select contracts via CheckboxDialog
3. Choose features (Enhanced, LLM Validation, Foundry PoC, Enhanced Reports)
4. Set output directory
5. Confirm and launch as background job(s)

GitHub URL:

1. Enter repository URL
2. Aether clones the repo and discovers contracts (progress shown inline)
3. If previous scopes exist, choose: continue, re-audit, or create new scope
4. Select contracts via ContractSelectorDialog (filterable, space to toggle, a/n for all/none)
5. Audit launches as a background job — visible in the jobs table

Block explorer URL / address:

1. Enter address or explorer URL
2. Aether fetches verified source code
3. Continue through features and output selection

r — Resume Audit

Table of all in-progress GitHub audits with project name, scope, progress (N/M contracts), and last update time. Select one to verify pending contracts and launch as a background job.

h — Audit History

Unified view of all past audits from both databases (local + GitHub). Select any entry for a submenu:

• View Details — scope breakdown with progress and status
• Generate PoCs — redirect to PoC wizard with project pre-selected
• Re-audit — select contracts via ContractSelectorDialog, launch as background job

p — Generate PoCs

Select a project, configure max items, minimum severity, and consensus-only filtering. PoC generation runs as a background job — watch progress in the jobs table.

o — Reports

Select project, scope, and format (markdown/json/html/all). Report generation runs as a background job.

f — Fetch Contract

Pick a network from 10+ supported chains, enter an address or paste an explorer URL, fetch the verified source code, and optionally audit it immediately.

s — Settings

• Run full setup wizard — API keys then model selection, all inline
• View current configuration — formatted display of all settings
• Reconfigure API keys — TextInputDialog prompts with masked current values
• Reconfigure model selections — SelectDialog per provider
• Triage settings — severity, confidence threshold, max findings
• Clear data — wipe local audit DB, GitHub audit DB, analysis cache, or all at once (with confirmation)

Enter — Job Detail

Press Enter on any row in the jobs table to see:

• Live scrolling log output (updated every second)
• Phase progress bar
• Job metadata (type, target, status, cost, elapsed time)

q — Quit

Exits the TUI. If jobs are running, prompts for confirmation.

Scope and Capabilities

• Solidity AST parsing — Compiler-backed code analysis via py-solc-x for proper inheritance resolution, function visibility, storage layout, and state variable read/write tracking; graceful regex fallback
• Control flow graph analysis — build_cfg() constructs basic blocks with dominator trees and loop header detection; assembly block parsing; CFG context fed into deep analysis and taint propagation
• Taint analysis engine — Tracks user-controlled inputs (8 source types) through contracts to 12 dangerous sink types with sanitizer detection, cross-contract tracking, and branch-aware CFG propagation
• Cross-contract analysis — Inter-contract relationship analyzer with trust boundary detection, union-find grouping, dedicated LLM pass (Pass 3.5) for multi-contract vulnerabilities, and RelatedContractResolver for dependency context
• Deep analysis engine — 6-pass LLM pipeline plus Pass 3.5 (cross-contract): understand → map attack surface → check invariants → cross-contract analysis → cross-function analysis → adversarial modeling → edge cases; per-pass model tier selection, caching, few-shot examples, chain-of-thought enforcement, CFG context in Pass 2, ML severity calibration in Pass 5, related contract context per pass
• Halmos symbolic execution — HalmosRunner + HalmosPropertyGenerator for formal verification of invariants; integrated at validation Stage 1.95; graceful degradation if Halmos not installed
• ML feedback loop — AccuracyTracker records submission outcomes and generates per-detector confidence weights; severity calibration from historical data injected into deep analysis
• Related contract context — RelatedContractResolver discovers parent, interface, library, and dependency contracts; per-pass budget system with standard library summarization

Output Directories

• ./output/ — General output root
• ./output/reports/ — Generated reports
• ./output/pocs/ — Generated Foundry PoC suites
• ./output/exploit_tests/ — Results from exploit testing

Architecture

Entry Points

• aether.py — Sole entry point; launches the Textual TUI
• cli/interactive_menu.py — Thin shim creating JobManager + AetherApp
• cli/tui/app.py — AetherApp(App) — main Textual app with key bindings and 1-second refresh timer

TUI Layer (cli/tui/)

• Screens: MainScreen (jobs table + cost bar), JobDetailScreen (live log + phase + metadata), NewAuditScreen, HistoryScreen, ResumeScreen, PoCScreen, ReportsScreen, FetchScreen, SettingsScreen
• Widgets: JobsTable (DataTable polling JobManager), CostBar (session cost by provider), LogViewer (RichLog with incremental refresh), PhaseBar (Unicode block progress)
• Dialogs: ConfirmDialog, , , , , — all ModalScreen subclasses

Background Execution

• cli/audit_runner.py — AuditRunner class running audits, PoCs, reports, and GitHub audits in daemon threads
• core/job_manager.py — JobManager singleton: session job registry (QUEUED/RUNNING/COMPLETED/FAILED/CANCELLED)
• core/audit_progress.py — ContractAuditStatus with per-job log buffers, ThreadDemuxWriter for stdout/stderr capture
• core/llm_usage_tracker.py — Thread-safe singleton with snapshot() for per-job cost deltas

Core Orchestration

• cli/main.py — AetherCLI class (~2600 lines) — internal audit orchestrator used by AuditRunner
• core/enhanced_audit_engine.py — Main audit engine with deep analysis integration
• core/post_audit_summary.py — Post-audit panel with cost-by-provider breakdown

Deep Analysis Layer (v4.7)

• core/deep_analysis_engine.py — 6-pass LLM pipeline plus Pass 3.5 (cross-contract): understand → attack surface → invariants → cross-contract → cross-function → adversarial → edge cases; model tier selection, caching, few-shot examples, chain-of-thought enforcement, CFG context in Pass 2, ML severity calibration in Pass 5, related contract context per pass
• core/protocol_archetypes.py — Protocol archetype detection (14 types including LIQUID_STAKING, PERPETUAL_DEX, CDP_STABLECOIN, YIELD_AGGREGATOR) with per-archetype vulnerability checklists
• core/exploit_knowledge_base.py — 75+ categorized real-world exploit patterns across 14 categories (including CROSS_CONTRACT, SIGNATURE_AUTH, TOKEN_INTEGRATION, PROXY_UPGRADE, TYPE_SAFETY)
• core/invariant_engine.py — Invariant extraction (NatSpec + LLM + pattern) and Foundry invariant test generation + Halmos property generation
• core/solidity_ast.py — Solidity AST parsing via py-solc-x with regex fallback for inheritance, visibility, storage layout, state read/write tracking; control flow graph construction (build_cfg(), get_dominators(), get_loop_headers())
• core/taint_analyzer.py — Data flow / taint analysis with 8 source types, 12 sink types, sanitizer detection, cross-contract tracking, branch-aware CFG propagation

Detection Layer

• core/enhanced_vulnerability_detector.py — Primary detector with 60+ patterns
• core/business_logic_detector.py, core/state_management_detector.py, core/data_inconsistency_detector.py, core/centralization_detector.py, core/looping_detector.py — Move-inspired detectors
• core/defi_vulnerability_detector.py, core/mev_detector.py, core/oracle_manipulation_detector.py — DeFi-specific detectors (DeFi detector integrated into enhanced engine in v3.5)
• core/arithmetic_analyzer.py, core/precision_analyzer.py, core/gas_analyzer.py, , — Specialized analyzers (precision analyzer enhanced with share inflation, rounding direction, division truncation, dust exploitation, accumulator overflow detection)

Validation Layer

• core/validation_pipeline.py — Multi-stage pipeline: built-in protection check, governance detection, taint-aware validation (Stage 1.85), Halmos symbolic verification (Stage 1.95), deployment verification, local validation
• core/governance_detector.py, core/deployment_analyzer.py, core/llm_false_positive_filter.py
• core/control_flow_guard_detector.py, core/inheritance_verifier.py
• core/nodes/halmos_node.py — HalmosSymbolicNode pipeline node for symbolic execution validation

LLM & AI Layer

• core/enhanced_llm_analyzer.py — Structured LLM analysis (GPT/Gemini/Claude) with JSON output and multi-provider rotation
• core/enhanced_prompts.py — Production prompt templates with dynamic exploit pattern loading from knowledge base, few-shot examples, severity calibration, and chain-of-thought enforcement

PoC Generation Layer

• core/foundry_poc_generator.py (~8000 lines) — AST-based analysis, iterative compilation feedback (up to 5 attempts), auto-execution via forge test --json with PoCTestResult parsing and fork-mode support
• core/llm_foundry_generator.py — LLM-based test generation with mock API documentation and recommended setUp patterns
• core/enhanced_foundry_integration.py — Foundry validation and formatting
• core/poc_templates.py — Mock contract templates (MockERC20, MockOracle, MockWETH, MockFlashLoanProvider)
• core/poc_setup_generator.py — Intelligent setUp() generation: constructor param extraction, mock deployment, upgradeable contract handling, token minting and approvals

Persistence Layer

• core/database_manager.py — DatabaseManager (local audits) + AetherDatabase (GitHub audits)
• core/analysis_cache.py — Smart caching for 2x faster repeated analysis
• core/accuracy_tracker.py — ML feedback loop: submission outcomes, bounty earnings, per-detector accuracy stats, confidence weight generation

Integrations

• core/github_auditor.py — Clone repos, detect frameworks, discover contracts, coordinate analysis
• core/etherscan_fetcher.py, core/basescan_fetcher.py — Fetch verified contracts from block explorers
• core/exploit_tester.py — Validate exploits against Anvil forks

Flow-Based Execution

Audit flows defined in YAML configs (configs/). Enhanced audit pipeline: FileReaderNode -> StaticAnalysisNode -> LLMAnalysisNode -> EnhancedExploitabilityNode -> [FixGeneratorNode -> ValidationNode -> HalmosSymbolicNode] -> ReportNode

Tests

2059 tests across 76 test files, running in ~23 seconds:```bash python -m pytest tests/ # All tests (~23s, 2059 tests) python -m pytest tests/test_enhanced_detectors.py -v # Single file python -m pytest tests/test_enhanced_detectors.py::TestArithmeticAnalyzer -v # Single class python -m pytest tests/ -k "governance" -v # Pattern match python -m pytest tests/ --cov=core --cov-report=html # With coverage

## Solución de problemas

- **Foundry no encontrado** — Asegúrate de que `forge`/`anvil` estén instalados y en el `PATH` (`foundryup` y `export PATH="$PATH:$HOME/.foundry/bin"`)
- **solc no encontrado** — Instala `solc-select` y las versiones requeridas: `solc-select install 0.8.20 latest`
- **Las funciones LLM no funcionan** — Verifica que las claves de API estén configuradas. Es posible que algunos modelos no estén disponibles en tu cuenta/región; el sistema recurre automáticamente a una alternativa
- **Base de datos no encontrada** — Para informes de GitHub, asegúrate de que el flujo de trabajo de auditoría se haya ejecutado primero
- **Textual no carga** — Ejecuta `pip install textual>=1.0.0` si falta

---

## Registro de cambios

### v4.7 — Auto-ejecución de PoC, verificación simbólica con Halmos, análisis de CFG y bucle de retroalimentación de ML
- **Auto-ejecución de PoC** — los PoCs de Foundry generados se compilan y ejecutan automáticamente mediante `forge test --json` con análisis de `PoCTestResult` y soporte de modo fork; fase `POC_TESTING` para seguimiento en vivo en la TUI
- **Ejecución simbólica con Halmos** — nodo de pipeline `HalmosRunner`, `HalmosPropertyGenerator` y `HalmosSymbolicNode` (etapa de validación 1.95) para verificación formal de invariantes; degradación controlada si Halmos no está instalado
- **Análisis de grafo de flujo de control** — `BasicBlock`, `CFGEdge`, `ControlFlowGraph` con `build_cfg()`, árboles de dominancia, detección de cabeceras de bucle, análisis de bloques de ensamblador; contexto CFG inyectado en el Paso 2 del análisis profundo; propagación de taint consciente de ramas
- **Bucle de retroalimentación de ML** — `AccuracyTracker` registra los resultados de los envíos con `get_detector_accuracy()` y `get_detector_weights()` para estadísticas por detector; ajuste de peso de confianza en `EnhancedVulnerabilityDetector`; calibración de severidad en el Paso 5 del análisis profundo
- **Contexto de contratos relacionados** — `RelatedContractResolver` descubre contratos padre, de interfaz, de biblioteca y de dependencia con un sistema de presupuesto por pasada (200K/100K/50K caracteres); resumen de la biblioteca estándar; descubrimiento de contratos hermanos en un solo archivo
- **Limpieza de deuda técnica** — se eliminaron 8.500 líneas de código muerto: se borraron `ai_ensemble.py`, `audit_engine.py`, `fork_verifier.py`; se quitaron todas las referencias a ai_ensemble de la CLI, el ejecutor de auditorías, las pantallas TUI y el generador de informes
- **2059 pruebas** superadas en 76 archivos de prueba

### v4.0 — Análisis del AST de Solidity, análisis de taint y seguimiento del flujo de datos
- **Analizador de AST de Solidity** — integración completa con solc mediante py-solc-x para una resolución de herencia correcta, visibilidad de funciones, disposición del almacenamiento, seguimiento de lectura/escritura de estado; respaldo elegante mediante regex
- **Motor de análisis de taint** — rastrea entradas controladas por el usuario a través de 8 tipos de fuentes hasta 12 sumideros peligrosos con detección de saneamiento y seguimiento entre contratos
- **Integración del pipeline** — los datos del AST alimentan el Paso 1, los datos de taint alimentan el Paso 2, etapa de validación 1.85 consciente de taint
- **1839 pruebas** superadas en 67 archivos de prueba (~23 segundos)

### v3.8 — Detección mejorada y generación de PoC
- **Análisis entre contratos** — nuevo Paso 3.5 con analizador de relaciones entre contratos, detección de límites de confianza y agrupación union-find
- **Base de datos de peculiaridades de tokens** — 12 categorías de comportamientos ERC-20 no estándar (fee-on-transfer, rebasing, ERC-777, etc.)
- **Motor de precisión mejorado** — detección de inflación de participaciones, análisis de dirección de redondeo, seguimiento de truncamiento de divisiones, explotación de residuos (dust), desbordamiento de acumuladores
- **Generación de PoC ejecutables** — biblioteca de contratos mock (ERC20, Oracle, WETH, FlashLoan), setUp() inteligente, máximo de intentos de compilación 3→5
- **Ejemplos few-shot** en los Pasos 3, 4 y 5 del análisis profundo con ejemplos reales de vulnerabilidades y falsos positivos
- **Calibración de severidad** — umbrales concretos (Crítica >$1M, Alta >$100K, Media >$10K, Baja teórica)
- **Aplicación de la cadena de pensamiento** — razonamiento obligatorio en 5 pasos antes de la salida JSON
- **Ensamble de IA retirado** — reemplazado por rotación de múltiples proveedores en los pasos de análisis profundo
- **Rotación de múltiples proveedores** — Gemini Flash (pasadas económicas), Anthropic Claude (razonamiento), OpenAI GPT (diversidad)
- **1682 pruebas** superadas

### v3.7 — Arquetipos ampliados y patrones de exploit
- **4 nuevos arquetipos de protocolo** — LIQUID_STAKING, PERPETUAL_DEX, CDP_STABLECOIN, YIELD_AGGREGATOR (10→14 en total)
- **25 nuevos patrones de exploit** — categorías CROSS_CONTRACT, SIGNATURE_AUTH, TOKEN_INTEGRATION, PROXY_UPGRADE, TYPE_SAFETY (50→75 en total)
- **Escáner de contratos mejorado** — ahora se puntúan los contratos abstractos y se ajustaron los umbrales para soporte de monorepos
- **1528 pruebas** superadas

### v3.5.2 — Reducción de falsos positivos
- **Detección de scripts en el descubrimiento de contratos** — los archivos en `script/`/`scripts/`, los archivos `.s.sol` y los contratos que importan `forge-std/Script.sol` o heredan `is Script` se etiquetan como scripts de despliegue y se excluyen del análisis de vulnerabilidades por LLM. Elimina toda una clase de falsos positivos provocados por los asistentes de despliegue de Foundry analizados como código de producción
- **Marcadores de contexto de archivo en los prompts de LLM** — el contenido combinado ahora incluye marcadores `// FILE: <name>` por archivo, y los pasos 1 y 3 del análisis profundo reciben un encabezado `## Project Files` que etiqueta cada archivo como `[PRODUCTION]` o `[DEPLOYMENT SCRIPT]` para que los LLM se centren en el código correcto
- **Detección dinámica de modificadores** — `GovernanceDetector` ahora extrae los modificadores personalizados de control de acceso definidos en el contrato (p. ej. `onlyDistributor`, `onlyMinter`, `authorized`) escaneando definiciones de modificadores con prefijo `only` o comprobaciones de `msg.sender`. Estos se fusionan con la lista de modificadores fijos para `has_access_control()` y `is_governance_function()`
- **Desduplicación por ámbito de función** — `VulnerabilityDeduplicator` ahora agrupa los hallazgos por `(function_name, vuln_type)` cuando el código del contrato está disponible, reemplazando el frágil emparejamiento por línea exacta que omitía duplicados en líneas adyacentes de la misma función. Recurre a la agrupación por bloques de 20 líneas cuando el contexto de la función no está disponible
- **Ampliada la tolerancia de líneas del ensamble de IA** — la tolerancia de `_findings_match_fuzzy()` aumentó de ±5 a ±15 líneas para detectar duplicados de la misma función entre agentes
- **Patrón de falso positivo en constructor atómico** — `_check_constructor_context()` ahora detecta cuando un contrato se despliega (`new`/`Create2`) y se inicializa (`.initialize()`) en el mismo constructor, marcando las preocupaciones de front-running como falsos positivos, ya que las operaciones son atómicas
- **Patrón de validación LLM #18** — se añadió "Atomic Deployment + Initialization" a la lista de verificación de falsos positivos de 18 patrones en el prompt de validación del LLM
- **1489 pruebas** superadas en 56 archivos de prueba (~40 segundos), frente a 1461

### v3.5 — Motor de análisis profundo
- **Pipeline de análisis profundo de 6 pasadas** — reemplaza las llamadas LLM de una sola pasada con razonamiento estructurado de múltiples pasadas: Comprensión del Protocolo → Mapeo de la Superficie de Ataque → Análisis de Violación de Invariantes → Interacción entre Funciones → Modelado Adversario → Casos Límite y Extremos. Cada pasada recibe el contexto acumulado de las pasadas anteriores. Las pasadas 1-2 se cachean mediante hash de contenido para reauditorías rápidas
- **Detección de arquetipo de protocolo** — identifica automáticamente el tipo de protocolo (Vault ERC-4626, Lending Pool, DEX/AMM, Bridge, Staking, Gobernanza, Oracle, Marketplace NFT, Token, Orderbook) con listas de verificación de vulnerabilidades por arquetipo extraídas de exploits reales
- **Base de conocimientos de exploits** — más de 50 patrones de exploits categorizados en 9 categorías (Inflation/Share, Reentrancy, Oracle, Governance, Bridge, Precision/Rounding, Access Control, Economic/DeFi, Logic) que reemplazan la lista estática de 10 patrones. Cada patrón incluye indicadores de código, protecciones faltantes, mecanismo de exploit paso a paso, precedentes del mundo real con montos en dólares y aplicabilidad por arquetipo
- **Motor de invariantes** — extrae invariantes de protocolo de las etiquetas NatSpec `@invariant`, del análisis LLM y de 6 detectores de patrones comunes (conservación del vault, seguimiento de saldos, contabilidad de suministro, producto constante de AMM, colateralización de préstamos, recompensas de staking). Genera suites de pruebas `invariant_*()` de Foundry como pruebas de verificación formal ligera
- **Calibración de severidad consciente del contexto** — reemplaza las rebajas generalizadas de severidad por comprobaciones de contexto de riesgo. Los hallazgos en bloques `unchecked{}`, cerca de transferencias de valor (`call{value:}`, `_mint`, `safeTransfer`), cálculos de precios o contextos de oráculo conservan su severidad original
- **Corrección de la puerta de validación** — los hallazgos `"pending"` ahora pasan al análisis LLM con la bandera `needs_llm_validation`. Solo se descartan los hallazgos explícitamente `"false_positive"` (antes, todos los hallazgos que no fueran `"validated"` se filtraban silenciosamente)
- **Penalización de confianza según especialización** — los hallazgos de un solo agente que coinciden con la especialización del agente (p. ej., AnthropicReasoningSpecialist + ataques económicos) reciben una penalización de -0.05; los hallazgos no especializados mantienen -0.15
- **Corrección de desduplicación por bloques de líneas** — se eliminó la agrupación `(line // 10) * 10` que causaba problemas arbitrarios de límites (líneas 9 y 11 en bloques diferentes). La desduplicación ahora usa solo el tipo de vulnerabilidad normalizado, siendo `_findings_match_fuzzy()` quien gestiona la proximidad de líneas
- **Integración del detector DeFi** — `DeFiVulnerabilityDetector` (análisis semántico de presencia/ausencia en dos etapas) ahora se ejecuta en el motor de auditoría mejorado junto con `EnhancedVulnerabilityDetector`
- **Patrones de exploits dinámicos en prompts** — `enhanced_prompts.py` ahora carga patrones de ExploitKnowledgeBase filtrados por área de enfoque, con respaldo a los patrones estáticos
- **1461 pruebas** superadas en 55 archivos de prueba (~50 segundos)

### v3.2 — Estadísticas de trabajos y correcciones de UI
- **Corregidas las estadísticas de hallazgos/costo/LLM de trabajos que siempre mostraban cero** — el worker de auditoría ahora captura el dict de resultados de `run_audit()` para extraer el número de hallazgos; se eliminó `LLMUsageTracker.reset()`, que dejaba referencias huérfanas al singleton; los 4 tipos de worker calculan las estadísticas por trabajo a partir de deltas de snapshots
- **Corregido el artefacto de repintado de la UI al cambiar de ventana** — se reemplazaron los contenedores desplazables por un `Container` simple + `overflow: hidden` en JobDetailScreen para evitar frames obsoletos del compositor
- **Se movió "Job Details" a border_title** para un renderizado más limpio del panel de metadatos
- Se eliminó `CLAUDE.md` del seguimiento de git

### v3.0 — TUI Textual totalmente integrada
- **Cero llamadas a `app.suspend()`** — la TUI nunca cae a una terminal en bruto; cada operación se ejecuta de forma integrada
- **Generación de PoC en segundo plano** — se ejecuta como hilo daemon mediante `AuditRunner.start_poc_generation()` con salida en vivo en JobDetailScreen
- **Generación de informes en segundo plano** — se ejecuta como hilo daemon mediante `AuditRunner.start_report_generation()` con salida en vivo
- **Auditorías de GitHub en segundo plano** — selección de alcance mediante diálogos de Textual; la auditoría se ejecuta como hilo daemon a través de `AuditRunner.start_github_audit()`
- **ContractSelectorDialog** — modal de selección múltiple filtrable casi a pantalla completa que reemplaza al `ScopeManager.interactive_select()` basado en curses. Espacio para alternar, `a`/`n` para todos/ninguno, escribir para filtrar, contratos previamente auditados con código de colores
- **GitHubAuditHelper** — envoltorio descompuesto alrededor de `GitHubAuditor`/`AetherDatabase` que proporciona operaciones atómicas (`clone_and_discover`, `get_scope_state`, `save_new_scope`, `get_pending_contracts`, `handle_reaudit`) invocables desde las pantallas de Textual
- **Configuración integrada** — configuración de claves de API y modelos mediante TextInputDialog/SelectDialog nativos, sin necesidad de un asistente de configuración externo
- **Gestión integrada del alcance de GitHub** — continuar, reauditar o crear un nuevo alcance mediante SelectDialog; selección de contratos mediante ContractSelectorDialog
- **6 pantallas reescritas** — PoCScreen, ReportsScreen, SettingsScreen, NewAuditScreen, HistoryScreen, ResumeScreen — todas totalmente integradas
- **770 pruebas** superadas en 50 archivos de prueba

### v2.2 — Panel de control TUI Textual
- TUI Textual a pantalla completa con aplicación persistente, atajos de teclado y temporizador de actualización de 1 segundo
- MainScreen con tabla de trabajos en vivo y barra de costo de sesión
- JobDetailScreen con visor de registros en vivo, barra de progreso de fases y metadatos
- Diálogos modales (confirmación, entrada de texto, selección, casilla de verificación, selector de rutas) que reemplazan los prompts de questionary
- Ejecución de auditoría en segundo plano mediante AuditRunner con captura de salida por ThreadDemuxWriter
- JobManager singleton como registro de trabajos de la sesión
- Seguimiento de costo por trabajo mediante snapshots de LLMUsageTracker

### v2.1 — Auditorías paralelas, eliminación de Slither y limpieza de pruebas
- Motor de auditoría paralela — ejecuta múltiples contratos de forma concurrente con `ThreadPoolExecutor`, configurable hasta 8 workers paralelos
- Seguimiento de progreso thread-safe — `ContractAuditStatus` con bloqueos, `ThreadDemuxWriter` para multiplexar stdout
- Resumen posterior a la auditoría — vista consolidada de resultados tras completar las auditorías paralelas
- Seguimiento de uso de LLM — rastrea el uso de tokens, costos y llamadas de API en los tres proveedores
- Slither eliminado por completo — se borraron todas las dependencias, el código de integración y las pruebas (~1200 líneas); los detectores basados en patrones + ABI de Foundry + regex son las únicas herramientas de análisis
- Limpieza del conjunto de pruebas — se eliminaron más de 40 archivos de prueba antiguos/lentos/de integración

### v2.0 — TUI de menú interactivo
- TUI interactiva controlada por menús como interfaz principal
- Asistente de auditoría guiado con selección de fuente, casillas de verificación de funciones y confirmación
- Capacidad de reanudar auditorías de GitHub en curso
- Navegador unificado del historial de auditorías en bases de datos locales y de GitHub
- Flujos de trabajo integrados de generación de PoC e informes desde el menú
- Obtención de contratos de múltiples cadenas con auditoría inmediata opcional
- Gestión de configuración desde el menú
- Lanzamiento/retorno a consola desde el menú

### v1.5 — Soporte LLM de tres proveedores y análisis mejorado
- Integración de Anthropic Claude (Sonnet 4.5, Opus 4.6, Haiku 4.5) como tercer proveedor de LLM
- Ensamble de IA de 6 agentes: 2 agentes especialistas de OpenAI + 2 de Gemini + 2 de Anthropic
- Respaldo automático entre proveedores para máxima disponibilidad
- Modelos actualizados de OpenAI (GPT-5.3) y de Google Gemini (3.0 Flash/Pro)
- Asistente de configuración actualizado con la configuración de la clave API de Anthropic y la selección de modelos
- Corregido el comando CLI generate-foundry que estaba roto

---

## Licencia

Aether se distribuye bajo la **Licencia MIT**. Consulta el archivo [LICENSE](https://github.com/l33tdawg/aether/blob/HEAD/LICENSE) para más detalles.

## Autor

**Dhillon Andrew Kannabhiran** (@l33tdawg)
- Email: [email protected]
- Twitter: [@l33tdawg](https://twitter.com/l33tdawg)
- GitHub: [@l33tdawg](https://github.com/l33tdawg)

## Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar issues, hacer fork del repositorio y crear pull requests.