Framework di analisi della sicurezza degli Smart Contract e generazione di PoC basato su IA

Novità nella v5.0

Memoria istituzionale SAGE — Aether ora impara da ogni audit, riducendo i falsi positivi e migliorando la qualità dei risultati nel tempo:

• Knowledge base pre-addestrata — Include 170 memorie istituzionali: 75 pattern di exploit, 63 checklist di archetipi di protocollo, 12 categorie di token quirks, 20 exploit storici curati (DAO, Wormhole, Euler, Ronin, Curve e altri)
• Integrazione nella pipeline — SAGE richiama risultati storici e pattern di exploit nei Passaggi 3 e 5 dell'analisi profonda; memorizza gli apprendimenti dell'audit dopo la pipeline per un richiamo futuro
• Ciclo di feedback — I risultati confermati vengono memorizzati come fatti ad alta confidenza; i risultati rifiutati (falsi positivi) vengono memorizzati affinché i futuri audit li evitino. Gli esiti di AccuracyTracker confluiscono automaticamente in SAGE
• Pipeline di validazione — Nuovo Stage -1: il controllo SAGE known FP filtra i risultati che corrispondono a pattern precedentemente rifiutati prima che venga eseguita qualsiasi altra validazione
• Sincronizzazione dell'accuratezza dei rilevatori — SageFeedbackManager.sync_detector_accuracy() identifica i rilevatori ad alte/basse prestazioni e memorizza riflessioni di dos/don'ts
• Auto-seed all'avvio — Al primo avvio con Docker SAGE in esecuzione, la knowledge base pre-addestrata viene caricata automaticamente. Consapevole della versione: salta se già caricata
• Integrazione TUI — Stato SAGE ON/OFF con conteggio delle memorie visualizzato nella CostBar
• Deployment Docker — docker compose up -d avvia SAGE; configurazione tramite sage_enabled/sage_url in ~/.aether/config.yaml
• Degrado graduale — La non disponibilità di SAGE non interrompe mai alcuna funzionalità di audit

Contributori: Grazie a @sashavdv per aver corretto le variabili di percorso hardcoded (PR #1) e a @pro258b per aver individuato il metodo mancante validate_anthropic_key() (PR #2).

Avvio rapido di SAGE

SAGE è un sistema di memoria istituzionale persistente basato sul consenso BFT. Consulta il progetto SAGE per la documentazione 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()"

Novità nella v4.7

Auto-esecuzione dei PoC — I PoC Foundry generati ora vengono compilati ed eseguiti automaticamente:

• L'integrazione con forge test --json esegue i PoC subito dopo la compilazione
• Parsing dei risultati JSON con la dataclass PoCTestResult per report strutturati di superamento/fallimento/errore
• Supporto della modalità fork per la validazione su mainnet degli exploit rispetto allo stato live
• Nuova fase POC_TESTING in JobManager per il monitoraggio live dei progressi nella TUI

Esecuzione simbolica con Halmos — Verifica formale tramite esecuzione simbolica:

• HalmosRunner per eseguire test simbolici Halmos sulle proprietà generate
• HalmosPropertyGenerator per generare automaticamente proprietà di verifica dagli invarianti estratti
• Nodo di pipeline HalmosSymbolicNode integrato allo Stage 1.95 di validazione
• Opzioni di configurazione: enable_symbolic_verification, halmos_timeout
• Degradazione controllata se Halmos non è installato: salta la verifica simbolica senza errori

Analisi del grafo di flusso di controllo — Comprensione del flusso di controllo a livello di compilatore:

• Dataclass BasicBlock, CFGEdge, ControlFlowGraph in solidity_ast.py
• build_cfg(), get_dominators(), get_loop_headers(), format_cfg_for_llm() per l'analisi strutturale
• Parsing dei blocchi assembly tramite parse_assembly_block() per il supporto all'assembly inline
• Propagazione del taint sensibile ai rami nell'analizzatore di taint per l'analisi sensibile al percorso
• Il contesto CFG viene iniettato nell'analisi profonda Pass 2 insieme ai dati di taint

Ciclo di feedback ML — Calibrazione basata sui risultati storici:

• AccuracyTracker.record_finding_outcome() per monitorare i risultati delle submission e i guadagni dei bounty
• get_detector_accuracy() e get_detector_weights() per le statistiche di performance dei singoli detector
• La dataclass DetectorStats tiene traccia di veri/falsi positivi e dell'accuratezza storica
• Regolazione del peso di confidenza in EnhancedVulnerabilityDetector in base allo storico del detector
• Calibrazione della severità dai dati storici iniettata nell'analisi profonda Pass 5

Contesto dei contratti correlati — L'analisi LLM ora vede il codice sorgente completo delle dipendenze:

• RelatedContractResolver scopre automaticamente contratti genitore, interfacce, librerie e contratti dipendenti
• La modalità progetto usa l'analisi delle relazioni tra contratti; la modalità file singolo analizza le dichiarazioni di import
• Sistema di budget per pass: 200K caratteri per i pass Gemini Flash, 100K per Claude, 50K per GPT
• Le librerie standard (@openzeppelin, solmate, solady) vengono riassunte alla sola interfaccia per risparmiare budget
• Gli audit a file singolo scoprono automaticamente i file .sol adiacenti per il contesto

Pulizia del debito tecnico — Rimossi 8.500 righe di codice morto:

• Eliminati: ai_ensemble.py, audit_engine.py, fork_verifier.py
• Rimossi tutti i riferimenti ad ai_ensemble da CLI, audit runner, schermate TUI e generatore di report
• Rimossa slither_project_cache dal database manager
• Rimossi gli stub di verifica formale dal motore di audit avanzato

Novità nella v4.0

Parsing dell'AST Solidity — Aether v4.0 aggiunge l'analisi del codice basata sul compilatore tramite py-solc-x, superando l'analisi statica basata solo su regex:

• Integrazione completa con solc --ast-json per una corretta risoluzione dell'ereditarietà, visibilità delle funzioni, layout di storage con numeri di slot e tracciamento delle letture/scritture delle variabili di stato per funzione
• Fallback regex controllato quando la compilazione fallisce (import mancanti, versione del compilatore errata)
• Il riepilogo strutturale dell'AST viene automaticamente iniettato nella pipeline LLM dell'analisi profonda per una migliore comprensione del protocollo

Motore di analisi del taint — Traccia gli input controllati dall'utente attraverso i contratti per identificare flussi di dati pericolosi:

• 8 tipi di sorgenti di taint: parametri di funzione, msg.sender, msg.value, calldata, return di chiamate esterne, block.timestamp, block.number, tx.origin
• 12 tipi di sink pericolosi: delegatecall, selfdestruct, chiamate esterne, trasferimenti ETH, scritture di storage, indicizzazione di array, divisione per zero e altri
• Rilevamento dei sanitizer: riconosce controlli di bound con require, modificatori di access control, revert condizionali, clamping con Math.min/max, SafeCast
• Tracciamento del taint cross-contract attraverso più file
• Integrato nella pipeline di validazione (Stage 1.85) per la conferma/confutazione dei finding basata sul taint

Analisi Cross-Contract (Pass 3.5) — Nuovo pass di analisi profonda mirato alle vulnerabilità multi-contratto:

• Analizzatore delle relazioni tra contratti: rileva ereditarietà, chiamate a interfacce, delegatecall, staticcall, relazioni tipizzate tra variabili di stato
• Raggruppamento union-find dei contratti correlati con rilevamento dei confini di fiducia
• Pass LLM dedicato che analizza: violazioni dei confini di fiducia, consistenza dello stato cross-contract, rientranza cross-contract, conformità alle interfacce, interazioni di upgrade, escalation dei privilegi
• Il contesto cross-contract viene anche iniettato nel Pass 4 per la consapevolezza cross-funzione

Database delle anomalie dei token — 12 categorie di comportamenti ERC-20 non standard che causano exploit reali:

Integrato nella pipeline di rilevamento statico e nelle checklist degli archetipi.

Motore di precisione avanzato — Rilevamento avanzato delle vulnerabilità di arrotondamento e precisione:

• Rilevamento dell'inflazione delle quote / attacco del primo depositante per vault ERC-4626, pool di prestito e staking
• Analisi della direzione di arrotondamento — i depositi dovrebbero arrotondare per difetto, i prelievi per eccesso
• Tracciamento del troncamento delle divisioni — individua variabili di tasso troncate successivamente usate in moltiplicazioni
• Rilevamento dello sfruttamento del dust — l'arrotondamento a zero consente operazioni gratuite
• Overflow dell'accumulatore — valutazione del rischio di overflow dell'accumulatore di ricompense

Generazione di PoC eseguibili — I test Foundry generati ora compilano ed eseguono davvero:

• Libreria di contratti mock: MockERC20, MockOracle, MockWETH, MockFlashLoanProvider
• Generatore intelligente di setUp(): estrae i parametri del costruttore, distribuisce i mock, gestisce i contratti aggiornabili, conia token e imposta le approval
• Tentativi massimi di compilazione aumentati da 3 a 5
• I prompt LLM includono la documentazione dell'API dei mock e il setUp consigliato

Miglioramenti alla pipeline LLM:

• Esempi few-shot nei Pass 3, 4, 5 — esempi di vulnerabilità reali e falsi positivi tratti dalla knowledge base degli exploit
• Calibrazione della severità — soglie concrete legate all'impatto finanziario (Critical >$1M, High >$100K, Medium >$10K)
• Applicazione della catena di pensiero — ragionamento obbligatorio in 5 passaggi prima dell'output JSON
• Rotazione multi-provider — Gemini Flash per i pass economici, Anthropic Claude per il ragionamento, OpenAI GPT per la diversità
• Ensemble AI ritirato — l'ensemble a 6 agenti (costo 6x, contesto peggiore) è stato sostituito dalla rotazione dei provider all'interno della pipeline strutturata

Novità nella v3.5

Motore di analisi profonda — Aether v3.5 trasforma radicalmente il modo in cui lo strumento trova le vulnerabilità, passando da una chiamata LLM one-shot "trova i bug" a una pipeline strutturata a 6 pass che rispecchia l'approccio degli auditor professionisti alla revisione del codice: prima comprendere, poi attaccare sistematicamente.

Motore di Analisi Profonda (Pipeline LLM a 6 Pass)

Invece di inviare un intero contratto a un LLM con un singolo prompt, Aether ora esegue sei pass di analisi sequenziali con contesto accumulato:

I Pass 1-2 sono memorizzati nella cache tramite hash del contenuto del contratto, quindi i nuovi audit saltano la fase di comprensione. Ogni pass successivo riceve tutto il contesto precedente, costruendo un modello d'attacco completo. Abilitato tramite feature flag AETHER_DEEP_ANALYSIS=1 (ON di default); in caso di errore torna al one-shot.

Sistema degli Archetipi di Protocollo

Prima di analizzare alla ricerca di bug, Aether rileva che tipo di protocollo implementa il contratto e carica checklist di vulnerabilità specifiche per archetipo:

10 archetipi in totale, ognuno con 3-7 voci di checklist specifiche tratte da exploit reali.

Knowledge Base degli Exploit (50+ Pattern)

Un database strutturato di oltre 50 pattern di exploit reali categorizzati sostituisce la precedente lista statica di 10 pattern:

Ogni pattern include indicatori di codice, protezioni mancanti, meccanismo di exploit passo-passo e precedenti reali (con importi in dollari). I pattern vengono filtrati in base all'archetipo rilevato e all'area di focus dell'agente.

Motore degli Invarianti

Estrae automaticamente gli invarianti del protocollo da tre fonti:

1. Tag NatSpec @invariant nei commenti dei contratti
2. Invarianti scoperti dall'LLM nel Pass 1 dell'analisi profonda
3. Invarianti comuni rilevati tramite pattern (conservazione del saldo, prodotto costante AMM, rapporti di collateralizzazione, ecc.)

Genera suite di test Foundry invariant_*() che fungono da prove di verifica formale semplificata — un test di invariante fallito dimostra che il bug è reale.

Correzioni alla Pipeline

• Calibrazione della severità sensibile al contesto — non declassa più indiscriminatamente division_by_zero, integer_underflow, ecc. a bassa. Ora verifica se il finding si trova in un blocco unchecked{}, vicino a trasferimenti di valore, in calcoli di prezzo o in contesti oracle prima di decidere
• Correzione del gate di validazione — i finding "pending" ora passano all'analisi LLM (in precedenza passavano solo quelli "validated", scartando silenziosamente molti finding reali)
• Penalità di confidenza consapevole dello specialista — i finding di un singolo agente specialista nel proprio dominio (es. AnthropicReasoningSpecialist che trova un bug logico complesso) ricevono solo -0.05 invece di -0.15
• Correzione della deduplicazione a bucket di righe — rimosso il raggruppamento arbitrario (line // 10) * 10 che separava finding distanti 2 righe in gruppi diversi
• Integrazione del detector DeFi — DeFiVulnerabilityDetector (analisi a due stadi presenza/assenza) ora viene eseguito nel motore di audit avanzato principale, non solo nella pipeline basata sui flussi

Novità nella v3.0

TUI testuale completamente integrata — Aether v3.0 è un'applicazione persistente a schermo intero che non passa mai a un terminale grezzo. Ogni operazione — audit, generazione di PoC, generazione di report, selezione dello scope GitHub, configurazione delle impostazioni — viene eseguita interamente all'interno della TUI:

• Zero chiamate app.suspend() — la TUI non scompare mai, nessun passaggio brusco al terminale
• Job in background per tutto — audit locali, audit GitHub, generazione di PoC e generazione di report vengono eseguiti come thread daemon con streaming live dell'output
• Tabella live dei job — vista stile htop di tutti i job in esecuzione/completati con stato in tempo reale, avanzamento delle fasi, numero di finding, costo e tempo trascorso
• Drill-down per job — premi Enter su un job qualsiasi per vedere l'output scorrevole live, la barra di avanzamento delle fasi e i metadati
• Operazioni concorrenti — avvia più audit, generazioni di PoC e report contemporaneamente; tutti visibili e tracciabili
• Dialogo di selezione dei contratti — multi-selezione filtrabile, quasi a schermo intero, che sostituisce il vecchio selettore basato su curses. Barra spaziatrice per attivare/disattivare, a/n per tutto/niente, scrivi per filtrare, contratti già auditati con codici colore
• Flusso di audit GitHub integrato — clona, scopri, seleziona i contratti e avvia gli audit senza uscire dalla TUI. Gestione dello scope (continua, ri-audit, nuovo scope) tramite dialoghi nativi di Textual
• Impostazioni integrate — configurazione delle chiavi API e selezione del modello tramite TextInputDialog e SelectDialog, nessuna procedura guidata esterna necessaria
• Barra dei costi di sessione — monitoraggio in tempo reale dei costi LLM per provider (OpenAI, Gemini, Anthropic)
• Guidato da tastiera — n Nuovo audit, r Riprendi, h Cronologia, p PoC, o Report, f Scarica, s Impostazioni, q Esci

Quattro tipi di job in background: tutte le operazioni pesanti vengono eseguite come thread daemon tramite AuditRunner, con l'output catturato da ThreadDemuxWriter e visibile in JobDetailScreen:

Supporto LLM a tre provider: OpenAI (GPT-5/5.3), Google Gemini (2.5/3.0) e Anthropic Claude (Sonnet 4.5/Opus 4.6) per la massima flessibilità e ridondanza.

Generazione avanzata di PoC: analisi del contratto basata su AST, correzioni iterative della compilazione e prompt LLM pronti per la produzione che generano exploit adatti alle submission di bug bounty.

Filtraggio avanzato dei falsi positivi: la validazione multi-stadio riduce i falsi positivi dal 66% a circa il 20-25%, migliorando l'accuratezza dal 33% al 75-80%:

• Rilevamento degli script — gli script di deployment (script/, .s.sol, forge-std/Script.sol) vengono automaticamente esclusi dall'analisi delle vulnerabilità
• Marcatori di contesto dei file — i prompt LLM includono etichette [PRODUCTION]/[DEPLOYMENT SCRIPT] così i modelli si concentrano sul codice di produzione
• Rilevamento dinamico dei modificatori — i modificatori di controllo accessi personalizzati (es. onlyDistributor, authorized) vengono estratti dal sorgente del contratto e riconosciuti insieme ai pattern hardcoded
• Deduplicazione per ambito di funzione — i finding duplicati nella stessa funzione vengono uniti invece di usare la fragile prossimità dei numeri di riga
• Rilevamento del costruttore atomico — deploy+initialize nello stesso costruttore riconosciuto come non front-runnable
• Rilevamento della governance (parametri protetti da onlyOwner/onlyGovernor)
• Analisi del deployment (verifica che i percorsi di codice siano effettivamente usati in produzione)
• Controlli delle protezioni integrate (auto-protezione Solidity 0.8+, SafeMath)
• Validazione LLM consapevole della governance con checklist a 18 pattern
• Monitoraggio dell'accuratezza con esiti delle submission e guadagni dei bounty
• Cache intelligente per analisi ripetute 2 volte più veloci

Integrazione del database delle vulnerabilità Move: pattern tratti da 128 finding Critical/High in 77 audit, adattati a Solidity/EVM:

• Logica di business, gestione dello stato, incoerenza dei dati, centralizzazione, problemi di loop e validazione avanzata degli input

Avvio Rapido

1. Configurazione```bash

python setup.py # Interactive installer (recommended)

Tutto qui. La TUI ti guida attraverso tutto tramite scorciatoie da tastiera e finestre di dialogo modali.

Requisiti

• Python 3.11+ (testato con 3.12.8)
• Node.js 22+ (per progetti basati su Hardhat/npm)
• Foundry (forge/anvil) nel PATH per la generazione e validazione di PoC
• solc-select per più versioni del compilatore Solidity
• py-solc-x (opzionale) per il parsing dell'AST di Solidity — ripiega sull'analisi regex se non disponibile
• Chiavi API per le funzionalità LLM:
  • OPENAI_API_KEY (per i modelli GPT)
  • GEMINI_API_KEY (per i modelli Gemini)
  • ANTHROPIC_API_KEY (per i modelli Claude)
  • ETHERSCAN_API_KEY (opzionale, per recuperare contratti verificati)

Installazione manuale

Se preferisci l'installazione manuale:```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 is stored in ~/.aether/config.yaml.

Posizioni del database:

• Risultati del motore di analisi: ~/.aether/aetheraudit.db
• Workflow di audit GitHub: ~/.aether/aether_github_audit.db

Guida TUI

Tutte le interazioni avvengono tramite scorciatoie da tastiera nella schermata principale:

n — Nuovo Audit

Procedura guidata in più passaggi con tre tipi di origine:

File o directory locale:

1. Seleziona il percorso tramite PathDialog
2. Se è una directory, seleziona i contratti tramite CheckboxDialog
3. Scegli le funzionalità (Enhanced, LLM Validation, Foundry PoC, Enhanced Reports)
4. Imposta la directory di output
5. Conferma e avvia come job in background

GitHub URL:

1. Inserisci l'URL del repository
2. Aether clona il repository e scopre i contratti (avanzamento mostrato inline)
3. Se esistono scope precedenti, scegli: continua, ri-audita o crea un nuovo scope
4. Seleziona i contratti tramite ContractSelectorDialog (filtrabile, spazio per attivare/disattivare, a/n per tutti/nessuno)
5. L'audit viene avviato come job in background — visibile nella tabella dei job

URL dell'explorer di blocchi / indirizzo:

1. Inserisci un indirizzo o un URL di explorer
2. Aether recupera il codice sorgente verificato
3. Continua tra le funzionalità e la selezione dell'output

r — Riprendi Audit

Tabella di tutti gli audit GitHub in corso con nome del progetto, scope, avanzamento (contratti N/M) e orario dell'ultimo aggiornamento. Selezionane uno per verificare i contratti in sospeso e avviarlo come job in background.

h — Cronologia Audit

Vista unificata di tutti gli audit passati da entrambi i database (locale + GitHub). Seleziona una voce per un sottomenu:

• Visualizza dettagli — ripartizione dello scope con avanzamento e stato
• Genera PoC — reindirizza alla procedura guidata PoC con il progetto già selezionato
• Ri-audit — seleziona i contratti tramite ContractSelectorDialog e avvia come job in background

p — Genera PoC

Seleziona un progetto, configura il numero massimo di elementi, la severità minima e il filtro solo consenso. La generazione dei PoC viene eseguita come job in background — osserva l'avanzamento nella tabella dei job.

o — Report

Seleziona progetto, scope e formato (markdown/json/html/all). La generazione dei report viene eseguita come job in background.

f — Recupera Contratto

Scegli una rete tra 10+ chain supportate, inserisci un indirizzo o incolla un URL di explorer, recupera il codice sorgente verificato e, opzionalmente, esegui subito un audit.

s — Impostazioni

• Esegui la procedura guidata completa — chiavi API e poi selezione del modello, tutto inline
• Visualizza la configurazione attuale — visualizzazione formattata di tutte le impostazioni
• Riconfigura le chiavi API — prompt TextInputDialog con valori correnti mascherati
• Riconfigura le selezioni dei modelli — SelectDialog per provider
• Impostazioni di triage — severità, soglia di confidenza, numero massimo di segnalazioni
• Cancella dati — cancella il database degli audit locali, il database degli audit GitHub, la cache di analisi, oppure tutto in una volta (con conferma)

Enter — Dettaglio Job

Premi Invio su qualsiasi riga della tabella dei job per vedere:

• Output di log scorrevole in tempo reale (aggiornato ogni secondo)
• Barra di avanzamento della fase
• Metadati del job (tipo, target, stato, costo, tempo trascorso)

q — Esci

Esce dalla TUI. Se ci sono job in esecuzione, chiede conferma.

Ambito e Funzionalità

• Parsing AST di Solidity — Analisi del codice basata su compilatore tramite py-solc-x per una corretta risoluzione dell'ereditarietà, visibilità delle funzioni, layout di storage e tracciamento delle letture/scritture delle variabili di stato; fallback regex graduale
• Analisi del grafo di flusso di controllo — build_cfg() costruisce blocchi di base con alberi dei dominatori e rilevamento degli header di ciclo; parsing dei blocchi assembly; il contesto CFG viene iniettato nell'analisi profonda e nella propagazione del taint
• Motore di analisi del taint — Traccia gli input controllati dall'utente (8 tipi di sorgente) attraverso i contratti fino a 12 tipi di sink pericolosi, con rilevamento dei sanitizer, tracciamento cross-contratto e propagazione CFG consapevole dei rami
• Analisi cross-contratto — Analizzatore delle relazioni tra contratti con rilevamento dei confini di fiducia, raggruppamento union-find, pass LLM dedicato (Pass 3.5) per le vulnerabilità multi-contratto e RelatedContractResolver per il contesto delle dipendenze
• Motore di analisi profonda — Pipeline LLM a 6 passaggi più Pass 3.5 (cross-contratto): comprendi → mappa la superficie d'attacco → verifica gli invarianti → analisi cross-contratto → analisi cross-funzione → modellazione avversaria → casi limite; selezione del livello di modello per passaggio, caching, esempi few-shot, imposizione della catena di pensiero, contesto CFG nel Pass 2, calibrazione della severità tramite ML nel Pass 5, contesto dei contratti correlati per passaggio
• Esecuzione simbolica Halmos — HalmosRunner + HalmosPropertyGenerator per la verifica formale degli invarianti; integrato nella fase di validazione 1.95; degradazione graduale se Halmos non è installato
• Ciclo di feedback ML — AccuracyTracker registra gli esiti delle submission e genera pesi di confidenza per singolo rilevatore; la calibrazione della severità dai dati storici viene iniettata nell'analisi profonda
• Contesto dei contratti correlati — RelatedContractResolver individua contratti genitore, interfacce, librerie e contratti di dipendenza; sistema di budget per passaggio con riepilogo delle librerie standard
• Rilevamento degli archetipi di protocollo — Identificazione automatica di 14 tipi di protocollo (vault, lending, DEX, bridge, staking, governance, oracle, liquid staking, perpetual DEX, stablecoin CDP, yield aggregator e altri) con checklist di vulnerabilità specifiche per archetipo
• Base di conoscenza degli exploit — 75+ pattern di exploit reali categorizzati in 14 categorie con indicatori di codice, protezioni mancanti e precedenti; filtrabili per archetipo e area di interesse
• Database delle stranezze dei token — 12 categorie di comportamenti ERC-20 non standard (fee-on-transfer, rebasing, ERC-777, flash-mintable, blocklist, pausable, decimali ridotti, ecc.) integrate nella pipeline di rilevamento
• Motore degli invarianti — Estrae gli invarianti di protocollo da NatSpec, analisi LLM e pattern di codice; genera test di invarianti Foundry
• Analisi statica — 180+ rilevatori basati su pattern (reentrancy, controllo accessi, aritmetica, manipolazione degli oracle, flash loan, MEV, governance, specifici DeFi, stranezze dei token, precisione/arrotondamento e altro)
• Motore di precisione avanzato — Rilevamento dell'inflazione delle quote, analisi della direzione dell'arrotondamento, tracciamento del troncamento delle divisioni, sfruttamento del dust, valutazione dell'overflow degli accumulatori
• Analisi LLM — Analisi strutturata e orientata alla validazione con OpenAI, Gemini e Claude; rotazione multi-provider con fallback automatico; calibrazione della severità legata alle soglie di impatto finanziario
• Filtraggio sensibile al contesto — Calibrazione della severità che verifica il contesto di rischio (blocchi unchecked, operazioni di valore, utilizzo di oracle) prima di declassare; fase di validazione consapevole del taint; le segnalazioni in sospeso vengono conservate per la validazione LLM
• Audit paralleli — Analisi multi-contratto concorrente con avanzamento in tempo reale nella tabella dei job
• Workflow di audit GitHub — Clona repository, rileva framework, scopre contratti, selezione dello scope inline, stato persistente
• Generazione PoC Foundry — Analisi basata su AST, feedback di compilazione iterativo (fino a 5 tentativi), libreria di contratti mock (ERC20, Oracle, WETH, FlashLoan), generazione intelligente di setUp(), prompt di exploit pronti per la produzione, auto-esecuzione tramite forge test --json con supporto fork-mode
• Recupero contratti multi-chain — 10+ reti EVM + supporto Solana
• Reportistica — Generazione di report in Markdown, JSON, HTML dai dati degli audit
• Tracciamento dell'uso LLM — Utilizzo dei token, tracciamento dei costi e riepilogo post-audit su tutti i provider
• Persistenza — Due database SQLite per i risultati del motore e per il workflow di audit GitHub

Directory di Output

• ./output/ — Directory di output principale
• ./output/reports/ — Report generati
• ./output/pocs/ — Suite PoC Foundry generate
• ./output/exploit_tests/ — Risultati dei test degli exploit

Architettura

Punti di Ingresso

• aether.py — Punto di ingresso unico; avvia la TUI Textual
• cli/interactive_menu.py — Shim sottile che crea JobManager + AetherApp
• cli/tui/app.py — AetherApp(App) — app Textual principale con key binding e timer di aggiornamento di 1 secondo

Livello TUI (cli/tui/)

• Schermate: MainScreen (tabella dei job + barra dei costi), JobDetailScreen (log in tempo reale + fase + metadati), NewAuditScreen, HistoryScreen, ResumeScreen, PoCScreen, ReportsScreen, FetchScreen, SettingsScreen
• Widget: JobsTable (DataTable che interroga JobManager), CostBar (costo della sessione per provider), LogViewer (RichLog con aggiornamento incrementale), PhaseBar (avanzamento a blocchi Unicode)
• Dialoghi: ConfirmDialog, TextInputDialog, SelectDialog, CheckboxDialog, PathDialog, ContractSelectorDialog — tutte sottoclassi di ModalScreen
• Helper: GitHubAuditHelper — operazioni di audit GitHub scomposte per l'integrazione nella TUI
• Tema: theme.tcss — CSS Textual con tema ciano

Esecuzione in Background

• cli/audit_runner.py — classe AuditRunner che esegue audit, PoC, report e audit GitHub in thread daemon
• core/job_manager.py — singleton JobManager: registro dei job di sessione (QUEUED/RUNNING/COMPLETED/FAILED/CANCELLED)
• core/audit_progress.py — ContractAuditStatus con buffer di log per job, ThreadDemuxWriter per la cattura di stdout/stderr
• core/llm_usage_tracker.py — singleton thread-safe con snapshot() per i delta di costo per job

Orchestrazione Core

• cli/main.py — classe AetherCLI (~2600 righe) — orchestratore interno degli audit utilizzato da AuditRunner
• core/enhanced_audit_engine.py — motore di audit principale con integrazione dell'analisi profonda
• core/post_audit_summary.py — pannello post-audit con ripartizione dei costi per provider

Livello di Analisi Profonda (v4.7)

• core/deep_analysis_engine.py — pipeline LLM a 6 passaggi più Pass 3.5 (cross-contratto): comprendi → superficie d'attacco → invarianti → cross-contratto → cross-funzione → avversario → casi limite; selezione del livello di modello, caching, esempi few-shot, imposizione della catena di pensiero, contesto CFG nel Pass 2, calibrazione della severità tramite ML nel Pass 5, contesto dei contratti correlati per passaggio
• core/protocol_archetypes.py — rilevamento degli archetipi di protocollo (14 tipi inclusi LIQUID_STAKING, PERPETUAL_DEX, CDP_STABLECOIN, YIELD_AGGREGATOR) con checklist di vulnerabilità per archetipo
• core/exploit_knowledge_base.py — 75+ pattern di exploit reali categorizzati in 14 categorie (inclusi CROSS_CONTRACT, SIGNATURE_AUTH, TOKEN_INTEGRATION, PROXY_UPGRADE, TYPE_SAFETY)
• core/invariant_engine.py — estrazione degli invarianti (NatSpec + LLM + pattern) e generazione di test di invarianti Foundry + generazione di proprietà Halmos
• core/solidity_ast.py — parsing AST di Solidity tramite py-solc-x con fallback regex per ereditarietà, visibilità, layout di storage, tracciamento delle letture/scritture di stato; costruzione del grafo di flusso di controllo (build_cfg(), get_dominators(), get_loop_headers())
• core/taint_analyzer.py — analisi del flusso di dati / taint con 8 tipi di sorgente, 12 tipi di sink, rilevamento dei sanitizer, tracciamento cross-contratto, propagazione CFG consapevole dei rami
• core/cross_contract_analyzer.py — analisi delle relazioni tra contratti con rilevamento dei confini di fiducia, raggruppamento union-find e RelatedContractResolver per il contesto delle dipendenze
• core/token_quirks.py — database delle stranezze dei token (12 categorie di comportamenti ERC-20 non standard)
• core/halmos_runner.py — esecutore di esecuzione simbolica Halmos per la verifica formale
• core/halmos_property_generator.py — genera automaticamente proprietà di verifica Halmos dagli invarianti
• core/accuracy_tracker.py — ciclo di feedback ML: tracciamento dell'accuratezza per rilevatore, regolazione del peso di confidenza, calibrazione della severità

Livello di Rilevamento

• core/enhanced_vulnerability_detector.py — rilevatore primario con 60+ pattern
• core/business_logic_detector.py, core/state_management_detector.py, core/data_inconsistency_detector.py, core/centralization_detector.py, core/looping_detector.py — rilevatori ispirati a Move
• core/defi_vulnerability_detector.py, core/mev_detector.py, core/oracle_manipulation_detector.py — rilevatori specifici DeFi (il rilevatore DeFi è integrato nel motore potenziato nella v3.5)
• core/arithmetic_analyzer.py, core/precision_analyzer.py, core/gas_analyzer.py, core/input_validation_detector.py, core/data_decoding_analyzer.py — analizzatori specializzati (l'analizzatore di precisione è potenziato con inflazione delle quote, direzione dell'arrotondamento, troncamento delle divisioni, sfruttamento del dust, rilevamento dell'overflow degli accumulatori)
• Il rilevamento delle stranezze dei token è integrato nella pipeline di rilevamento statico tramite core/token_quirks.py

Livello di Validazione

• core/validation_pipeline.py — pipeline multi-fase: controllo delle protezioni integrate, rilevamento della governance, validazione consapevole del taint (Stage 1.85), verifica simbolica Halmos (Stage 1.95), verifica del deployment, validazione locale
• 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 — nodo della pipeline HalmosSymbolicNode per la validazione tramite esecuzione simbolica

Livello LLM & AI

• core/enhanced_llm_analyzer.py — analisi LLM strutturata (GPT/Gemini/Claude) con output JSON e rotazione multi-provider
• core/enhanced_prompts.py — template di prompt di produzione con caricamento dinamico dei pattern di exploit dalla base di conoscenza, esempi few-shot, calibrazione della severità e imposizione della catena di pensiero

Livello di Generazione PoC

• core/foundry_poc_generator.py (~8000 righe) — analisi basata su AST, feedback di compilazione iterativo (fino a 5 tentativi), auto-esecuzione tramite forge test --json con parsing di PoCTestResult e supporto fork-mode
• core/llm_foundry_generator.py — generazione di test basata su LLM con documentazione API mock e pattern setUp consigliati
• core/enhanced_foundry_integration.py — validazione e formattazione Foundry
• core/poc_templates.py — template di contratti mock (MockERC20, MockOracle, MockWETH, MockFlashLoanProvider)
• core/poc_setup_generator.py — generazione intelligente di setUp(): estrazione dei parametri del costruttore, deployment dei mock, gestione dei contratti upgradeable, minting e approvazioni dei token

Livello di Persistenza

• core/database_manager.py — DatabaseManager (audit locali) + AetherDatabase (audit GitHub)
• core/analysis_cache.py — caching intelligente per analisi ripetute 2 volte più veloci
• core/accuracy_tracker.py — ciclo di feedback ML: esiti delle submission, guadagni dai bounty, statistiche di accuratezza per rilevatore, generazione dei pesi di confidenza

Integrazioni

• core/github_auditor.py — clona repository, rileva framework, scopre contratti, coordina l'analisi
• core/etherscan_fetcher.py, core/basescan_fetcher.py — recuperano contratti verificati dagli explorer di blocchi
• core/exploit_tester.py — valida gli exploit contro fork Anvil

Esecuzione Basata su Flussi

I flussi di audit sono definiti in configurazioni YAML (configs/). Pipeline di audit potenziata: FileReaderNode -> StaticAnalysisNode -> LLMAnalysisNode -> EnhancedExploitabilityNode -> [FixGeneratorNode -> ValidationNode -> HalmosSymbolicNode] -> ReportNode

Test

2059 test in 76 file di test, esecuzione in ~23 secondi:```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