Aether v4.7 — Smart Contract Security Analysis Framework

Version 4.7 | What's New in v4.7 | Changelog

Aether is a Python-based framework for analyzing Solidity smart contracts, generating vulnerability findings, producing Foundry-based proof-of-concept (PoC) tests, and validating exploits on mainnet forks. It combines Solidity AST parsing, taint analysis, control flow graph analysis, cross-contract analysis, Halmos symbolic execution, 180+ pattern-based static detectors, a structured deep analysis LLM pipeline (GPT/Gemini/Claude), 14 protocol archetypes, a 75+ exploit knowledge base, ML-calibrated detection, token quirks detection, invariant extraction, related contract context resolution, and advanced context-aware filtering into a single persistent full-screen TUI.

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:

Category	Severity	Example Tokens
Fee-on-transfer	HIGH	USDT, STA, PAXG
Rebasing tokens	HIGH	stETH, AMPL, OHM
ERC-777 callbacks	HIGH	imBTC
Flash-mintable	HIGH	DAI
Non-standard return	MEDIUM	Old USDT
Blocklist tokens	MEDIUM	USDC, USDT
Pausable tokens	MEDIUM	USDC
Low-decimal tokens	MEDIUM	USDC (6), WBTC (8)
Transfer hooks	MEDIUM	LINK (ERC-677)
Approval race	LOW	Various
Multiple entry points	LOW	TUSD
Upgradeable tokens	LOW	USDC v2

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:

Pass	Purpose	Model Tier
Pass 1	Protocol Understanding — what the protocol IS, its invariants, value flows, trust assumptions	Cheap (cached)
Pass 2	Attack Surface Mapping — every entry point, state reads/writes, reentrancy windows	Cheap (cached)
Pass 3	Invariant Violation Analysis — systematically check every invariant against every code path	Strong
Pass 4	Cross-Function Interaction — state dependency analysis, temporal dependencies, flash loan sequences	Strong
Pass 5	Adversarial Modeling — explicit attacker perspective with flash loans, MEV, multiple accounts	Strong
Pass 6	Boundary & Edge Cases — first/last operations, zero values, max values, self-referential ops	Medium

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:

Archetype	Example Checklist Items
ERC-4626 Vault	First depositor inflation, rounding direction, share price manipulation via donation
Lending Pool	Oracle price manipulation, liquidation threshold manipulation, bad debt cascade, interest rate manipulation
DEX/AMM	First LP manipulation, sandwich attacks, price oracle via reserves
Bridge	Cross-chain replay, validator compromise, token mapping mismatch, withdrawal proof forgery
Staking	Reward calculation manipulation, reward rate overflow, unstaking reentrancy
Governance	Flash loan governance attacks, timelock bypass, quorum manipulation
Oracle	Stale price data, price deviation, L2 sequencer downtime

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:

Category	Patterns	Examples
Inflation/Share Attacks	6	ERC-4626 first depositor, LP token inflation, donation-based manipulation
Reentrancy	7	Classic, read-only, cross-function, cross-contract, ERC-777/1155 hooks, flash loan callbacks
Oracle	5	Spot price manipulation, TWAP manipulation, staleness, decimals mismatch, L2 sequencer
Governance	4	Flash loan voting (Beanstalk), timelock bypass, quorum manipulation
Bridge	5	Message replay (Nomad), validator compromise (Ronin), token mapping (Wormhole)
Precision/Rounding	4	Rounding direction, unchecked overflow, fee-on-transfer, rebasing token drift
Access Control	5	Uninitialized proxy, storage collision, selector collision, delegatecall injection
Economic/DeFi	8	Sandwich attacks, JIT liquidity, bad debt cascade, returndata bomb, signature replay
Logic	6	Off-by-one, missing deadline/slippage, unchecked returns, self-transfer accounting

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:

NatSpec @invariant tags in contract comments
LLM-discovered invariants from Pass 1 of deep analysis
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:

Job Type	Description
`local`	Single or parallel contract audits
`github`	GitHub repository audits with pre-selected scope
`poc`	Foundry proof-of-concept generation
`report`	Audit report generation (markdown/json/html)

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

python setup.py          # Interactive installer (recommended)

2. Launch Aether

python aether.py         # Launches the full-screen Textual TUI

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:

# 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:

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:

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

GitHub URL:

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

Block explorer URL / address:

Enter address or explorer URL
Aether fetches verified source code
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:

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

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: l33tdawg@hitb.org
Twitter: @l33tdawg
GitHub: @l33tdawg

Contributing

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

Name		Name	Last commit message	Last commit date
Latest commit History 217 Commits
assets		assets
bs4		bs4
cli		cli
configs		configs
core		core
data/learning		data/learning
examples		examples
scripts		scripts
tests		tests
utils		utils
.gitignore		.gitignore
.gitmodules		.gitmodules
.node-version-fix		.node-version-fix
.nojekyll		.nojekyll
LICENSE		LICENSE
README.md		README.md
aether.py		aether.py
aether_console.py		aether_console.py
env.example		env.example
foundry.lock		foundry.lock
foundry.toml		foundry.toml
index.html		index.html
requirements.txt		requirements.txt
setup.py		setup.py
sitecustomize.py		sitecustomize.py
watch_audit_progress.sh		watch_audit_progress.sh

Folders and files

Latest commit

History

Repository files navigation

Aether v4.7 — Smart Contract Security Analysis Framework

What's New in v4.7

What's New in v4.0

What's New in v3.5

Deep Analysis Engine (6-Pass LLM Pipeline)

Protocol Archetype System

Exploit Knowledge Base (50+ Patterns)

Invariant Engine

Pipeline Fixes

What's New in v3.0

Quick Start

1. Setup

2. Launch Aether

Requirements

Manual Setup

Configuration

TUI Guide

n — New Audit

r — Resume Audit

h — Audit History

p — Generate PoCs

o — Reports

f — Fetch Contract

s — Settings

Enter — Job Detail

q — Quit

Scope and Capabilities

Output Directories

Architecture

Entry Points

TUI Layer (cli/tui/)

Background Execution

Core Orchestration

Deep Analysis Layer (v4.7)

Detection Layer

Validation Layer

LLM & AI Layer

PoC Generation Layer

Persistence Layer

Integrations

Flow-Based Execution

Tests

Troubleshooting

Changelog

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

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

v3.8 — Enhanced Detection & PoC Generation

v3.7 — Expanded Archetypes & Exploit Patterns

v3.5.2 — False Positive Reduction

v3.5 — Deep Analysis Engine

v3.2 — Job Stats & UI Fixes

v3.0 — Fully Inline Textual TUI

v2.2 — Textual TUI Dashboard

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

v2.0 — Interactive Menu TUI

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

License

Author

Contributing

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 15

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`n` — New Audit

`r` — Resume Audit

`h` — Audit History

`p` — Generate PoCs

`o` — Reports

`f` — Fetch Contract

`s` — Settings

`Enter` — Job Detail

`q` — Quit

TUI Layer (`cli/tui/`)

Packages