AI Smart Contract Security Analysis and PoC Generation Framework

What's New in v5.0

SAGE Institutional Memory — Aether now learns from every audit, reducing false positives and improving finding quality over time:

• Pre-trained knowledge base — Ships with 170 institutional memories: 75 exploit patterns, 63 protocol archetype checklists, 12 token quirk categories, 20 curated historical exploits (DAO, Wormhole, Euler, Ronin, Curve, and more)
• Pipeline integration — SAGE recalls historical findings and exploit patterns in deep analysis Passes 3 and 5; stores audit learnings post-pipeline for future recall
• Feedback loop — Confirmed findings get stored as high-confidence facts; rejected findings (false positives) get stored so future audits avoid them. AccuracyTracker outcomes automatically feed into SAGE
• Validation pipeline — New Stage -1: SAGE known FP check filters findings that match previously rejected patterns before any other validation runs
• Detector accuracy sync — SageFeedbackManager.sync_detector_accuracy() identifies high/low performing detectors and stores dos/don'ts reflections
• Auto-seed on startup — First launch with SAGE Docker running auto-seeds the pre-trained knowledge base. Version-aware: skips if already seeded
• TUI integration — SAGE ON/OFF status with memory count displayed in the CostBar
• Docker deployment — docker compose up -d starts SAGE; config via sage_enabled/sage_url in ~/.aether/config.yaml
• Graceful degradation — SAGE being unavailable never breaks any audit functionality

Contributors: Thanks to @sashavdv for fixing hardcoded path variables (PR #1) and @pro258b for identifying the missing validate_anthropic_key() method (PR #2).

SAGE Quick Start

SAGE is a persistent institutional memory system powered by BFT consensus. See the SAGE project for full documentation.

How SAGE Improves Audits

What's New in v4.7

PoC Auto-Execution — Generated Foundry PoCs now automatically compile and execute:

• forge test --json integration runs PoCs immediately after compilation
• JSON result parsing with PoCTestResult dataclass for structured pass/fail/error reporting
• Fork-mode support for mainnet validation of exploits against live state
• New POC_TESTING phase in JobManager for live progress tracking in the TUI

Halmos Symbolic Execution — Formal verification via symbolic execution:

• HalmosRunner for executing Halmos symbolic tests against generated properties
• HalmosPropertyGenerator for auto-generating verification properties from extracted invariants
• HalmosSymbolicNode pipeline node integrated at validation Stage 1.95
• Config options: enable_symbolic_verification, halmos_timeout
• Graceful degradation if Halmos is not installed — skips symbolic verification without errors

Control Flow Graph Analysis — Compiler-level control flow understanding:

• BasicBlock, CFGEdge, ControlFlowGraph dataclasses in solidity_ast.py
• build_cfg(), get_dominators(), get_loop_headers(), format_cfg_for_llm() for structural analysis
• Assembly block parsing via parse_assembly_block() for inline assembly support
• Branch-aware taint propagation in the taint analyzer for path-sensitive analysis
• CFG context injected into deep analysis Pass 2 alongside taint data

ML Feedback Loop — Historical outcome-based calibration:

• AccuracyTracker.record_finding_outcome() for tracking submission results and bounty earnings
• get_detector_accuracy() and get_detector_weights() for per-detector performance stats
• DetectorStats dataclass tracking true/false positives and historical accuracy
• Confidence weight adjustment in EnhancedVulnerabilityDetector based on detector track record
• Severity calibration from historical data injected into deep analysis Pass 5

Related Contract Context — LLM analysis now sees full dependency source code:

• RelatedContractResolver automatically discovers parent, interface, library, and dependency contracts
• Project mode uses inter-contract relationship analysis; single-file mode parses import statements
• Per-pass budget system: 200K chars for Gemini Flash passes, 100K for Claude, 50K for GPT
• Standard libraries (@openzeppelin, solmate, solady) summarized to interface-only to save budget
• Single-file audits auto-discover sibling .sol files for context

Tech Debt Cleanup — 8,500 lines of dead code removed:

• Deleted: ai_ensemble.py, audit_engine.py, fork_verifier.py
• Removed all ai_ensemble references from CLI, audit runner, TUI screens, report generator
• Removed slither_project_cache from database manager
• Removed formal verification stubs from enhanced audit engine

What's New in v4.0

Solidity AST Parsing — Aether v4.0 adds compiler-backed code analysis via py-solc-x, moving beyond regex-only static analysis:

• Full solc --ast-json integration for proper inheritance resolution, function visibility, storage layout with slot numbers, and state variable read/write tracking per function
• Graceful regex fallback when compilation fails (missing imports, wrong compiler version)
• AST structural summary automatically fed into the deep analysis LLM pipeline for better protocol understanding

Taint Analysis Engine — Tracks user-controlled inputs through contracts to identify dangerous data flows:

• 8 taint source types: function parameters, msg.sender, msg.value, calldata, external call returns, block.timestamp, block.number, tx.origin
• 12 dangerous sink types: delegatecall, selfdestruct, external calls, ETH transfers, storage writes, array indexing, division by zero, and more
• Sanitizer detection: recognizes require bounds checks, access control modifiers, conditional reverts, Math.min/max clamping, SafeCast
• Cross-contract taint tracking across multiple files
• Integrated into the validation pipeline (Stage 1.85) for taint-aware finding corroboration/refutation

Cross-Contract Analysis (Pass 3.5) — New deep analysis pass targeting multi-contract vulnerabilities:

• Inter-contract relationship analyzer: detects inheritance, interface calls, delegatecall, staticcall, typed state variable relationships
• Union-find grouping of related contracts with trust boundary detection
• Dedicated LLM pass analyzing: trust boundary violations, cross-contract state consistency, cross-contract reentrancy, interface compliance, upgrade interactions, privilege escalation
• Cross-contract context also fed into Pass 4 for cross-function awareness

Token Quirks Database — 12 categories of non-standard ERC-20 behaviors that cause real exploits:

Integrated into static detection pipeline and archetype checklists.

Enhanced Precision Engine — Advanced rounding and precision vulnerability detection:

• Share inflation / first depositor attack detection for ERC-4626 vaults, lending pools, staking
• Rounding direction analysis — deposits should round DOWN, withdrawals should round UP
• Division truncation tracking — catches truncated rate variables later used in multiplication
• Dust exploitation detection — rounding to zero allows free operations
• Accumulator overflow — reward accumulator overflow risk assessment

Runnable PoC Generation — Generated Foundry tests now actually compile and run:

• Mock contract library: MockERC20, MockOracle, MockWETH, MockFlashLoanProvider
• Intelligent setUp() generator: extracts constructor params, deploys mocks, handles upgradeable contracts, mints tokens, sets approvals
• Max compile attempts increased from 3 to 5
• LLM prompts include mock API documentation and recommended setUp

LLM Pipeline Improvements:

• Few-shot examples in Passes 3, 4, 5 — real vulnerability + false positive examples from exploit knowledge base
• Severity calibration — concrete thresholds tied to financial impact (Critical >$1M, High >$100K, Medium >$10K)
• Chain-of-thought enforcement — mandatory 5-step reasoning before JSON output
• Multi-provider rotation — Gemini Flash for cheap passes, Anthropic Claude for reasoning, OpenAI GPT for diversity
• AI ensemble retired — the 6-agent ensemble (6x cost, worse context) replaced by provider rotation within the structured pipeline

What's New in v3.5

Deep Analysis Engine — Aether v3.5 fundamentally transforms how the tool finds vulnerabilities, moving from a one-shot "find bugs" LLM call to a structured 6-pass pipeline that mirrors how professional auditors approach code review: understand first, then systematically attack.

Deep Analysis Engine (6-Pass LLM Pipeline)

Instead of sending an entire contract to an LLM with a single prompt, Aether now runs six sequential analysis passes with accumulated context:

Passes 1-2 are cached by contract content hash, so re-audits skip the understanding phase. Each subsequent pass receives all prior context, building a comprehensive attack model. Feature-flagged with AETHER_DEEP_ANALYSIS=1 (default ON); falls back to one-shot on failure.

Protocol Archetype System

Before analyzing for bugs, Aether detects what kind of protocol the contract implements and loads archetype-specific vulnerability checklists:

10 archetypes total, each with 3-7 specific checklist items drawn from real-world exploits.

Exploit Knowledge Base (50+ Patterns)

A structured database of 50+ categorized real-world exploit patterns replaces the previous static 10-pattern list:

Each pattern includes code indicators, missing protections, step-by-step exploit mechanism, and real-world precedents (with dollar amounts). Patterns are filtered by detected archetype and agent focus area.

Invariant Engine

Automatically extracts protocol invariants from three sources:

1. NatSpec @invariant tags in contract comments
2. LLM-discovered invariants from Pass 1 of deep analysis
3. Pattern-detected common invariants (balance conservation, AMM constant product, collateralization ratios, etc.)

Generates Foundry invariant_*() test suites that serve as formal-verification-lite proofs — a failing invariant test proves the bug is real.

Pipeline Fixes

• Context-aware severity calibration — no longer blanket-downgrades division_by_zero, integer_underflow, etc. to low. Now checks if the finding is in an unchecked{} block, near value transfers, in price calculations, or in oracle contexts before deciding
• Validation gate fix — "pending" findings now pass through to LLM analysis (previously only "validated" passed, silently dropping many real findings)
• Specialist-aware confidence penalty — single-agent findings from a specialist in their domain (e.g., AnthropicReasoningSpecialist finding a complex logic bug) get only -0.05 penalty instead of -0.15
• Line-bucket dedup fix — removed arbitrary (line // 10) * 10 bucketing that split findings 2 lines apart into different groups
• DeFi detector integration — DeFiVulnerabilityDetector (two-stage presence/absence analysis) now runs in the main enhanced audit engine, not just the flow-based pipeline

What's New in v3.0

Fully Inline Textual TUI — Aether v3.0 is a persistent full-screen application that never drops to a raw terminal. Every operation — audits, PoC generation, report generation, GitHub scope selection, settings configuration — runs entirely within the TUI:

• Zero app.suspend() calls — the TUI never disappears, no jarring terminal switches
• Background jobs for everything — local audits, GitHub audits, PoC generation, and report generation all run as daemon threads with live output streaming
• Live jobs table — htop-style view of all running/completed jobs with real-time status, phase progress, findings count, cost, and elapsed time
• Per-job drill-down — press Enter on any job to see live scrolling output, phase progress bar, and metadata
• Concurrent operations — start multiple audits, PoC generations, and reports simultaneously; all visible and trackable
• Contract selector dialog — filterable, near-fullscreen multi-select replacing the old curses-based selector. Space to toggle, a/n for all/none, type to filter, color-coded previously-audited contracts
• Inline GitHub audit flow — clone, discover, select contracts, and launch audits without leaving the TUI. Scope management (continue, re-audit, new scope) via native Textual dialogs
• Inline settings — API key configuration and model selection via TextInputDialog and SelectDialog, no external setup wizard needed
• Session cost bar — real-time LLM cost tracking by provider (OpenAI, Gemini, Anthropic)
• Keyboard-driven — n New Audit, r Resume, h History, p PoCs, o Reports, f Fetch, s Settings, q Quit

Four Background Job Types: All heavy operations run as background daemon threads via AuditRunner, with output captured by ThreadDemuxWriter and visible in JobDetailScreen:

Three-Provider LLM Support: OpenAI (GPT-5/5.3), Google Gemini (2.5/3.0), and Anthropic Claude (Sonnet 4.5/Opus 4.6) for maximum flexibility and redundancy.

Enhanced PoC Generation: AST-based contract analysis, iterative compilation fixes, and production-ready LLM prompts generating exploits suitable for bug bounty submissions.

Advanced False Positive Filtering: Multi-stage validation reduces false positives from 66% to ~20-25%, improving accuracy from 33% to 75-80%:

• Script detection — deployment scripts (script/, .s.sol, forge-std/Script.sol) automatically excluded from vulnerability analysis
• File context markers — LLM prompts include [PRODUCTION]/[DEPLOYMENT SCRIPT] labels so models focus on production code
• Dynamic modifier detection — custom access-control modifiers (e.g. onlyDistributor, authorized) extracted from contract source and recognized alongside hardcoded patterns
• Function-scope deduplication — duplicate findings in the same function are merged instead of using fragile line-number proximity
• Atomic constructor detection — deploy+initialize in the same constructor recognized as non-front-runnable
• Governance detection (onlyOwner/onlyGovernor protected parameters)
• Deployment analysis (verifies code paths are actually used in production)
• Built-in protection checks (Solidity 0.8+ auto-protection, SafeMath)
• Governance-aware LLM validation with 18-pattern checklist
• Accuracy tracking with submission outcomes and bounty earnings
• Smart caching for 2x faster repeated analysis

Move Vulnerability Database Integration: Patterns from 128 Critical/High findings across 77 audits, adapted for Solidity/EVM:

• Business logic, state management, data inconsistency, centralization, looping issues, and enhanced input validation

Quick Start

1. Setup

2. Launch Aether

That's it. The TUI guides you through everything via keyboard shortcuts and modal dialogs.

Requirements

• Python 3.11+ (tested with 3.12.8)
• Node.js 22+ (for Hardhat/npm-based projects)
• Foundry (forge/anvil) on PATH for PoC generation and validation
• solc-select for multiple Solidity compiler versions
• py-solc-x (optional) for Solidity AST parsing — falls back to regex analysis if unavailable
• API keys for LLM features:
  • OPENAI_API_KEY (for GPT models)
  • GEMINI_API_KEY (for Gemini models)
  • ANTHROPIC_API_KEY (for Claude models)
  • ETHERSCAN_API_KEY (optional, for fetching verified contracts)

Manual Setup

If you prefer manual installation:

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:

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
• Protocol archetype detection — Automatic identification of 14 protocol types (vault, lending, DEX, bridge, staking, governance, oracle, liquid staking, perpetual DEX, CDP stablecoin, yield aggregator, and more) with archetype-specific vulnerability checklists
• Exploit knowledge base — 75+ categorized real-world exploit patterns across 14 categories with code indicators, missing protections, and precedents; filterable by archetype and focus area
• Token quirks database — 12 categories of non-standard ERC-20 behaviors (fee-on-transfer, rebasing, ERC-777, flash-mintable, blocklist, pausable, low-decimal, etc.) integrated into detection pipeline
• Invariant engine — Extracts protocol invariants from NatSpec, LLM analysis, and code patterns; generates Foundry invariant tests
• Static analysis — 180+ pattern-based detectors (reentrancy, access control, arithmetic, oracle manipulation, flash loans, MEV, governance, DeFi-specific, token quirks, precision/rounding, and more)
• Enhanced precision engine — Share inflation detection, rounding direction analysis, division truncation tracking, dust exploitation, accumulator overflow assessment
• LLM analysis — Structured, validation-oriented analysis with OpenAI, Gemini, and Claude; multi-provider rotation with automatic fallback; severity calibration tied to financial impact thresholds
• Context-aware filtering — Severity calibration that checks risk context (unchecked blocks, value operations, oracle usage) before downgrading; taint-aware validation stage; pending findings preserved for LLM validation
• Parallel auditing — Concurrent multi-contract analysis with live progress in the jobs table
• GitHub audit workflow — Clone repos, detect frameworks, discover contracts, inline scope selection, persistent state
• Foundry PoC generation — AST-based analysis, iterative compilation feedback (up to 5 attempts), mock contract library (ERC20, Oracle, WETH, FlashLoan), intelligent setUp() generation, production-ready exploit prompts, auto-execution via forge test --json with fork-mode support
• Multi-chain contract fetching — 10+ EVM networks + Solana support
• Reporting — Markdown, JSON, HTML report generation from audit data
• LLM usage tracking — Token usage, cost tracking, and post-audit summary across all providers
• Persistence — Two SQLite databases for engine results and GitHub audit workflow

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, TextInputDialog, SelectDialog, CheckboxDialog, PathDialog, ContractSelectorDialog — all ModalScreen subclasses
• Helpers: GitHubAuditHelper — decomposed GitHub audit operations for TUI integration
• Theme: theme.tcss — cyan-themed Textual CSS

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
• core/cross_contract_analyzer.py — Inter-contract relationship analysis with trust boundary detection, union-find grouping, and RelatedContractResolver for dependency context
• core/token_quirks.py — Token quirks database (12 categories of non-standard ERC-20 behaviors)
• core/halmos_runner.py — Halmos symbolic execution runner for formal verification
• core/halmos_property_generator.py — Auto-generates Halmos verification properties from invariants
• core/accuracy_tracker.py — ML feedback loop: per-detector accuracy tracking, confidence weight adjustment, severity calibration

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, core/input_validation_detector.py, core/data_decoding_analyzer.py — Specialized analyzers (precision analyzer enhanced with share inflation, rounding direction, division truncation, dust exploitation, accumulator overflow detection)
• Token quirks detection integrated into static detection pipeline via core/token_quirks.py

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:

Troubleshooting

• Foundry not found — Ensure forge/anvil are installed and on PATH (foundryup and export PATH="$PATH:$HOME/.foundry/bin")
• solc not found — Install solc-select and required versions: solc-select install 0.8.20 latest
• LLM features not working — Verify API keys are set. Some models may be unavailable in your account/region; the system falls back automatically
• Database not found — For GitHub reports, ensure the audit workflow has been run first
• Textual not loading — Run pip install textual>=1.0.0 if missing

Changelog

v4.7 — PoC Auto-Execution, Halmos Symbolic Verification, CFG Analysis & ML Feedback Loop

• PoC auto-execution — generated Foundry PoCs automatically compile and execute via forge test --json with PoCTestResult parsing and fork-mode support; POC_TESTING phase for live TUI tracking
• Halmos symbolic execution — HalmosRunner, HalmosPropertyGenerator, and HalmosSymbolicNode pipeline node (validation Stage 1.95) for formal verification of invariants; graceful degradation if Halmos not installed
• Control flow graph analysis — BasicBlock, CFGEdge, ControlFlowGraph with build_cfg(), dominator trees, loop header detection, assembly block parsing; CFG context injected into deep analysis Pass 2; branch-aware taint propagation
• ML feedback loop — AccuracyTracker records submission outcomes with get_detector_accuracy() and get_detector_weights() for per-detector stats; confidence weight adjustment in EnhancedVulnerabilityDetector; severity calibration in deep analysis Pass 5
• Related contract context — RelatedContractResolver discovers parent, interface, library, and dependency contracts with per-pass budget system (200K/100K/50K chars); standard library summarization; single-file sibling discovery
• Tech debt cleanup — 8,500 lines of dead code removed: deleted ai_ensemble.py, audit_engine.py, fork_verifier.py; removed all ai_ensemble references from CLI, audit runner, TUI screens, report generator
• 2059 tests passing across 76 test files

v4.0 — Solidity AST Parsing, Taint Analysis & Data Flow Tracking

• Solidity AST parser — full solc integration via py-solc-x for proper inheritance resolution, function visibility, storage layout, state read/write tracking; graceful regex fallback
• Taint analysis engine — tracks user-controlled inputs through 8 source types to 12 dangerous sinks with sanitizer detection and cross-contract tracking
• Pipeline integration — AST data fed into Pass 1, taint data fed into Pass 2, taint-aware validation stage 1.85
• 1839 tests passing across 67 test files (~23 seconds)

v3.8 — Enhanced Detection & PoC Generation

• Cross-contract analysis — new Pass 3.5 with inter-contract relationship analyzer, trust boundary detection, union-find grouping
• Token quirks database — 12 categories of non-standard ERC-20 behaviors (fee-on-transfer, rebasing, ERC-777, etc.)
• Enhanced precision engine — share inflation detection, rounding direction analysis, division truncation tracking, dust exploitation, accumulator overflow
• Runnable PoC generation — mock contract library (ERC20, Oracle, WETH, FlashLoan), intelligent setUp(), max compile attempts 3→5
• Few-shot examples in deep analysis Passes 3, 4, 5 with real vulnerability and false positive examples
• Severity calibration — concrete thresholds (Critical >$1M, High >$100K, Medium >$10K, Low theoretical)
• Chain-of-thought enforcement — mandatory 5-step reasoning before JSON output
• AI ensemble retired — replaced by multi-provider rotation across deep analysis passes
• Multi-provider rotation — Gemini Flash (cheap passes), Anthropic Claude (reasoning), OpenAI GPT (diversity)
• 1682 tests passing

v3.7 — Expanded Archetypes & Exploit Patterns

• 4 new protocol archetypes — LIQUID_STAKING, PERPETUAL_DEX, CDP_STABLECOIN, YIELD_AGGREGATOR (10→14 total)
• 25 new exploit patterns — CROSS_CONTRACT, SIGNATURE_AUTH, TOKEN_INTEGRATION, PROXY_UPGRADE, TYPE_SAFETY categories (50→75 total)
• Improved contract scanner — abstracts now scored, adjusted thresholds for monorepo support
• 1528 tests passing

v3.5.2 — False Positive Reduction

• Script detection in contract discovery — files under script//scripts/, .s.sol files, and contracts importing forge-std/Script.sol or inheriting is Script are tagged as deployment scripts and excluded from LLM vulnerability analysis. Eliminates an entire class of false positives from Foundry deployment helpers being analyzed as production code
• File context markers in LLM prompts — combined content now includes // FILE: <name> markers per file, and deep analysis passes 1 and 3 receive a ## Project Files header labeling each file as [PRODUCTION] or [DEPLOYMENT SCRIPT] so LLMs focus on the right code
• Dynamic modifier detection — GovernanceDetector now extracts custom access-control modifiers defined in the contract (e.g. onlyDistributor, onlyMinter, authorized) by scanning for modifier definitions with only prefix or msg.sender checks. These are merged with the hardcoded modifier list for has_access_control() and is_governance_function()
• Function-scope deduplication — VulnerabilityDeduplicator now groups findings by (function_name, vuln_type) when contract code is available, replacing the fragile exact-line matching that missed adjacent-line duplicates in the same function. Falls back to 20-line bucket grouping when function context is unavailable
• Widened AI ensemble line tolerance — _findings_match_fuzzy() tolerance increased from ±5 to ±15 lines to catch same-function duplicates across agents
• Atomic constructor false positive pattern — _check_constructor_context() now detects when a contract is deployed (new/Create2) and initialized (.initialize()) in the same constructor, marking front-running concerns as false positives since the operations are atomic
• LLM validation pattern #18 — added "Atomic Deployment + Initialization" to the 18-pattern false positive checklist in the LLM validation prompt
• 1489 tests passing across 56 test files (~40 seconds), up from 1461

v3.5 — Deep Analysis Engine

• 6-pass deep analysis pipeline — replaces one-shot LLM calls with structured multi-pass reasoning: Protocol Understanding → Attack Surface Mapping → Invariant Violation Analysis → Cross-Function Interaction → Adversarial Modeling → Boundary & Edge Cases. Each pass receives accumulated context from prior passes. Passes 1-2 cached by content hash for fast re-audits
• Protocol archetype detection — automatically identifies protocol type (ERC-4626 Vault, Lending Pool, DEX/AMM, Bridge, Staking, Governance, Oracle, NFT Marketplace, Token, Orderbook) with per-archetype vulnerability checklists drawn from real-world exploits
• Exploit knowledge base — 50+ categorized exploit patterns across 9 categories (Inflation/Share, Reentrancy, Oracle, Governance, Bridge, Precision/Rounding, Access Control, Economic/DeFi, Logic) replacing the static 10-pattern list. Each pattern includes code indicators, missing protections, step-by-step exploit mechanism, real-world precedents with dollar amounts, and archetype applicability
• Invariant engine — extracts protocol invariants from NatSpec @invariant tags, LLM analysis, and 6 common pattern detectors (vault conservation, balance tracking, supply accounting, AMM constant product, lending collateralization, staking rewards). Generates Foundry invariant_*() test suites as formal-verification-lite proofs
• Context-aware severity calibration — replaces blanket severity downgrades with risk context checks. Findings in unchecked{} blocks, near value transfers (call{value:}, _mint, safeTransfer), price calculations, or oracle contexts preserve their original severity
• Validation gate fix — "pending" findings now pass through to LLM analysis with needs_llm_validation flag. Only explicit "false_positive" findings are dropped (previously, all non-"validated" findings were silently filtered)
• Specialist-aware confidence penalty — single-agent findings matching the agent's specialization (e.g., AnthropicReasoningSpecialist + economic attacks) get -0.05 penalty; non-specialist findings keep -0.15
• Line-bucket dedup fix — removed (line // 10) * 10 bucketing that caused arbitrary boundary issues (lines 9 and 11 in different buckets). Dedup now uses only normalized vulnerability type, with _findings_match_fuzzy() handling line proximity
• DeFi detector integration — DeFiVulnerabilityDetector (two-stage presence/absence semantic analysis) now runs in the enhanced audit engine alongside EnhancedVulnerabilityDetector
• Dynamic exploit patterns in prompts — enhanced_prompts.py now loads patterns from ExploitKnowledgeBase filtered by focus area, with fallback to static patterns
• 1461 tests passing across 55 test files (~50 seconds)

v3.2 — Job Stats & UI Fixes

• Fixed job findings/cost/LLM stats always showing zero — audit worker now captures the results dict from run_audit() to extract findings count; removed LLMUsageTracker.reset() that orphaned singleton references; all 4 worker types compute per-job stats from snapshot deltas
• Fixed UI repaint artifact on window switch — replaced scrollable containers with plain Container + overflow: hidden in JobDetailScreen to prevent stale compositor frames
• Moved "Job Details" to border_title for cleaner metadata panel rendering
• Removed CLAUDE.md from git tracking

v3.0 — Fully Inline Textual TUI

• Zero app.suspend() calls — the TUI never drops to a raw terminal; every operation runs inline
• Background PoC generation — runs as a daemon thread via AuditRunner.start_poc_generation() with live output in JobDetailScreen
• Background report generation — runs as a daemon thread via AuditRunner.start_report_generation() with live output
• Background GitHub audits — scope selection via Textual dialogs, audit runs as a daemon thread via AuditRunner.start_github_audit()
• ContractSelectorDialog — near-fullscreen filterable multi-select modal replacing curses-based ScopeManager.interactive_select(). Space to toggle, a/n for all/none, type to filter, color-coded previously-audited contracts
• GitHubAuditHelper — decomposed wrapper around GitHubAuditor/AetherDatabase providing atomic operations (clone_and_discover, get_scope_state, save_new_scope, get_pending_contracts, handle_reaudit) callable from Textual screens
• Inline settings — API key and model configuration via native TextInputDialog/SelectDialog, no external setup wizard needed
• Inline GitHub scope management — continue, re-audit, or create new scope via SelectDialog; contract selection via ContractSelectorDialog
• 6 screens rewritten — PoCScreen, ReportsScreen, SettingsScreen, NewAuditScreen, HistoryScreen, ResumeScreen — all fully inline
• 770 tests passing across 50 test files

v2.2 — Textual TUI Dashboard

• Full-screen Textual TUI with persistent app, key bindings, and 1-second refresh timer
• MainScreen with live jobs table and session cost bar
• JobDetailScreen with live log viewer, phase progress bar, and metadata
• Modal dialogs (confirm, text input, select, checkbox, path picker) replacing questionary prompts
• Background audit execution via AuditRunner with ThreadDemuxWriter output capture
• JobManager singleton for session job registry
• Per-job cost tracking via LLMUsageTracker snapshots

v2.1 — Parallel Audits, Slither Removal & Test Cleanup

• Parallel audit engine — run multiple contracts concurrently with ThreadPoolExecutor, configurable up to 8 parallel workers
• Thread-safe progress tracking — ContractAuditStatus with locking, ThreadDemuxWriter for stdout multiplexing
• Post-audit summary — consolidated results view after parallel audits complete
• LLM usage tracking — track token usage, costs, and API calls across all three providers
• Slither fully removed — all dependencies, integration code, and tests deleted (~1200 lines); pattern-based detectors + Foundry ABI + regex are the sole analysis tools
• Test suite cleanup — removed 40+ old/slow/integration test files

v2.0 — Interactive Menu TUI

• Interactive menu-driven TUI as the primary interface
• Guided audit wizard with source selection, feature checkboxes, and confirmation
• Resume audit capability for in-progress GitHub audits
• Unified audit history browser across local and GitHub databases
• Integrated PoC generation and report workflows from menu
• Multi-chain contract fetching with optional immediate audit
• Settings management from menu
• Console launch/return from menu

v1.5 — Three-Provider LLM Support & Enhanced Analysis

• Anthropic Claude integration (Sonnet 4.5, Opus 4.6, Haiku 4.5) as third LLM provider
• 6-agent AI ensemble: 2 OpenAI + 2 Gemini + 2 Anthropic specialist agents
• Automatic cross-provider fallback for maximum availability
• Updated OpenAI models (GPT-5.3) and Google Gemini models (3.0 Flash/Pro)
• Setup wizard updated with Anthropic API key configuration and model selection
• Fixed broken generate-foundry CLI command

License

Aether is distributed under the MIT License. See the LICENSE file for details.

Author

Dhillon Andrew Kannabhiran (@l33tdawg)

• Email: [email protected]
• Twitter: @l33tdawg
• GitHub: @l33tdawg

Contributing

Contributions are welcome! Please feel free to submit issues, fork the repository, and create pull requests.