aether

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

★ 65 Open GitHub ↗

AI Smart Contract Security Analysis and PoC Generation Framework

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Aether v6.0 — Smart Contract Security Analysis Framework

**Version 6.0** | [What's New in v6.0](#whats-new-in-v60) | [Changelog](#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 **collaborative multi-agent LLM pipeline** (GPT/Gemini/Claude) with shared [SAGE](https://github.com/l33tdawg/sage) institutional memory, 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 v6.0

**Collaborative Agent Pipeline** — The deep analysis pipeline transforms from 5 independent passes to 5 collaborative agents sharing structured knowledge through SAGE institutional memory:

- **Shared session memory** — Each pass stores findings, dismissals, and verified protections in a per-audit SAGE session. Later passes receive "Prior Pass Intelligence" instead of flat text summaries.
- **Dismissals as first-class records** — When Pass 3 dismisses a concern (e.g., "reentrancy protected by nonReentrant modifier"), Pass 5 won't re-flag it. This directly eliminates the #1 source of duplicate findings.
- **Challenge mechanism** — Later passes can override prior dismissals, but must provide NEW evidence. "Pass 3 didn't see the callback path through this other function" is valid. "I disagree" is not.
- **Cross-pass confirmation** — When multiple passes independently confirm a finding, confidence gets a 15% boost. Cross-confirmed findings are prioritized in reports.
- **SAGE required** — Institutional memory is now required, not optional. No SAGE = no audit. Run `docker compose up -d` to start.

---

## 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](https://github.com/sashavdv) for fixing hardcoded path variables ([PR #1](../../pull/1)) and [@pro258b](https://github.com/pro258b) for identifying the missing `validate_anthropic_key()` method ([PR #2](../../pull/2)).

### SAGE Quick Start

SAGE is a persistent institutional memory system powered by BFT consensus. See the [SAGE project](https://github.com/l33tdawg/sage) for full documentation.

```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()"
```

### How SAGE Improves Audits

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

---

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

| 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

```bash
python setup.py          # Interactive installer (recommended)
```

### 2. Launch Aether

```bash
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:

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

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

# Python dependencies
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
```

## Configuration

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

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

Or set environment variables directly:

```bash
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...
export ANTHROPIC_API_KEY=...
```

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

Database locations:
- Engine results: `~/.aether/aetheraudit.db`
- GitHub audit workflow: `~/.aether/aether_github_audit.db`

---

## TUI Guide

All interaction happens via keyboard shortcuts from the main screen:

### `n` — New Audit

Multi-step wizard with three source types:

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

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

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

### `r` — Resume Audit

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

### `h` — Audit History

Unified view of all past audits from both databases (local + GitHub). Select any entry for a submenu:
- **View Details** — scope breakdown with progress and status
- **Generate PoCs** — redirect to PoC wizard with project pre-selected
- **Re-audit** — select contracts via ContractSelectorDialog, launch as background job

### `p` — Generate PoCs

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

### `o` — Reports

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

### `f` — Fetch Contract

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

### `s` — Settings

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

### `Enter` — Job Detail

Press Enter on any row in the jobs table to see:
- Live scrolling log output (updated every second)
- Phase progress bar
- Job metadata (type, target, status, cost, elapsed time)

### `q` — Quit

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

---

## Scope and Capabilities

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

```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
```

## 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](LICENSE) file for details.

## Author

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

## Contributing

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

aether

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README