Aether is a Python-based framework for analyzing Solidity smart contracts, generating vulnerability findings, producing Foundry-based proof-of-concept (PoC) tests, and optionally validating those tests on mainnet forks. It combines static analysis, prompt-driven LLM analysis, and AI-ensemble reasoning with reporting and persistence.

Enhanced PoC Generation: Aether now features advanced AST-based contract analysis, iterative compilation fixes, and production-ready LLM prompts that generate exploits suitable for bug bounty submissions.

Advanced False Positive Filtering ✨: Aether includes a production-ready multi-stage validation system that reduces false positives from 66% to ~30-35%, improving accuracy from 33% to 65-70%. Features include:

• Governance Detection: Identifies onlyOwner/onlyGovernor protected parameters
• Deployment Analysis: Verifies code paths are actually used in production
• Built-in Protection Checks: Recognizes Solidity 0.8+ auto-protection and SafeMath usage
• Governance-Aware LLM Validation: Enhanced prompts with 4-stage validation checklist
• Accuracy Tracking: Monitors submission outcomes and bounty earnings
• Smart Caching: 2x faster analysis with intelligent result caching

Move Vulnerability Database Integration 🔄: Aether now incorporates patterns from the Move Vulnerability Database (128 Critical/High findings from 77 audits), adapted for Solidity/EVM analysis:

• Business Logic Detection: Backwards validation, self-comparison bugs, reward calculation errors
• State Management: Missing state updates, inconsistent tracking, desynchronization issues
• Data Inconsistency: Loop variables not updated, sorting violations, array length mismatches
• Centralization Risks: Excessive permissions, unlimited minting/burning, missing multisig
• Looping Issues: Infinite loops, termination errors, unbounded iterations
• Enhanced Input Validation: Token address validation, identifier checks, signature validation

• Static analysis

  • Slither integration when available
  • Enhanced pattern-based detectors in core/enhanced_vulnerability_detector.py

• LLM analysis

  • core/enhanced_llm_analyzer.py performs structured, validation-oriented analysis
  • Requires OPENAI_API_KEY and/or GEMINI_API_KEY
  • Strict JSON output and post-processing to reduce false positives

• False Positive Filtering & Validation ✨

  • Multi-stage validation pipeline (core/validation_pipeline.py) with 4 filtering stages:
    • Built-in protection check (Solidity 0.8+, SafeMath)
    • Governance control detection (onlyOwner, onlyGovernor)
    • Deployment verification (checks if features are actually used)
    • Local validation detection (require statements, bounds checks)
  • Governance detector (core/governance_detector.py) identifies access-controlled parameters
  • Deployment analyzer (core/deployment_analyzer.py) verifies production code paths
  • Enhanced LLM validation (core/llm_false_positive_filter.py) with governance-aware prompts
  • Accuracy tracking (core/accuracy_tracker.py) monitors submission outcomes and earnings
  • Smart caching (core/analysis_cache.py) for 2x faster repeated analysis
  • 163 comprehensive tests ensuring reliability and accuracy

• AI ensemble

  • core/ai_ensemble.py coordinates multiple specialized agents, aggregates results, and attempts consensus
  • Requires API keys and model availability

• GitHub audit workflow

  • core/github_auditor.py clones repositories, detects frameworks, discovers contracts, and coordinates analysis
  • Interactive scope selection via core/scope_manager.py
  • Audit results persisted via core/database_manager.AetherDatabase to ~/.aether/aether_github_audit.db

• Foundry integration and PoC generation

  • AST-based contract analysis for 100% accurate function and modifier extraction
  • Enhanced LLM prompts with production-ready exploit generation for $100k+ bounties
  • Iterative compilation feedback loop that fixes errors automatically using LLM
  • Vulnerability-aware contract context extraction based on vulnerability type
  • LLM-based Foundry tests via core/llm_foundry_generator.py
  • Enhanced Foundry validation and submission formatting via core/enhanced_foundry_integration.py
  • Optional exploit testing and fork verification via core/exploit_tester.py and the fork-verify command (implemented by core/fork_verifier.py)

• Reporting

  • Markdown/JSON/HTML report generation from audit data
  • GitHub audit reporting via core/github_audit_report_generator.py

• Persistence

  • Two SQLite databases are used:
    • ~/.aether/aetheraudit.db for engine-driven results
    • ~/.aether/aether_github_audit.db for GitHub audit workflow

New users: Run the automated installer for a guided setup experience:

python setup.py

This interactive installer will:

• ✓ Check system requirements (Python 3.11+)
• ✓ Install Foundry (forge/anvil) if needed
• ✓ Set up Python virtual environment
• ✓ Install all Python dependencies
• ✓ Configure API keys with validation
• ✓ Create configuration files
• ✓ Verify everything works

Non-interactive mode (for CI/CD):

python setup.py --non-interactive

• Python 3.11+ (currently tested with Python 3.12.8)
• Node.js 22+ (required for Hardhat/npm-based projects)
  • If using NVM: nvm install 22 && nvm use 22
  • Hardhat projects require Node 22.10.0 or later
• Foundry (forge/anvil) installed and on PATH for Foundry-related features
• solc-select for multiple Solidity compiler versions (supports 0.4.x through 0.8.x)
• Optional: Slither for static analysis integration (v0.10.0 recommended)
• API keys for LLM features:
  • OPENAI_API_KEY (for GPT models)
  • GEMINI_API_KEY (for Gemini models)
  • ETHERSCAN_API_KEY (optional, for fetching verified contracts)

If you prefer manual installation or the automated setup fails:

# Foundry (required for PoC generation)
curl -L https://foundry.paradigm.xyz | bash
foundryup

# Add Foundry to PATH if needed
export PATH="$PATH:$HOME/.foundry/bin"

# Slither (optional but recommended for static analysis)
pip install slither-analyzer==0.10.0

# solc-select (required for multiple Solidity versions)
pip install solc-select

# Install common Solidity compiler versions
solc-select install 0.4.26 0.8.0 0.8.19 0.8.20 latest

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

The setup.py installer will guide you through configuring all API keys.

Set environment variables:

# Required for LLM features
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=gsk-...

# Optional
export AETHER_LOG_LEVEL=INFO

Or copy the example environment file and fill in your keys:

cp env.example .env
# Edit .env with your API keys

Database locations:

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

To reset the GitHub audit database:

rm ~/.aether/aether_github_audit.db

The primary entrypoint is python main.py. Key subcommands implemented in main.py and cli/main.py:

• audit — Analyze a local contract path or a GitHub repository URL
• report — Generate reports from the GitHub audit database
• generate-foundry — Generate Foundry PoCs from a structured results file or report
• foundry — Run Foundry validation with PoC generation for bug bounty submissions
• fork-verify — Run generated Foundry tests against an Anvil fork
• exploit-test — Test generated exploit code against audited contracts (database-backed)
• console — Interactive console
• config — Manage configuration settings
• fetch, db, version — Utilities

Use python main.py <command> --help for full options.

python main.py audit ./contracts --enhanced --ai-ensemble --llm-validation -o ./output

Notes:

• --enhanced enables the enhanced audit engine.
• --ai-ensemble activates experimental multi-agent analysis if API keys are configured.
• --llm-validation adds LLM-based validation and triage.

python main.py audit https://github.com/owner/repo --interactive-scope --github-token <token>

Notes:

• Contracts are discovered and presented for interactive selection.
• Results are persisted to ~/.aether/aether_github_audit.db.

python main.py report --format markdown --output ./output/reports --list-projects
python main.py report --format json --project-id 1 -o ./output/reports

You can list projects or scopes before generating a report:

python main.py report --list-projects
python main.py report --list-scopes 1

# Preferred: from a structured results.json produced by prior analysis
python main.py generate-foundry --from-results ./output/results.json --out ./output/pocs --max-items 20 --only-consensus

# Fallback: from a markdown report (limited parsing)
python main.py generate-foundry --from-report ./output/report.md --out ./output/pocs

LLM-based PoC generation is the default. Ensure OPENAI_API_KEY (and/or GEMINI_API_KEY) is set for best results. Template-only mode (no LLM) is available but not recommended except for offline/CI smoke runs:

python scripts/generate_foundry_pocs.py \
  --results ./output/results.json \
  --contract ./contracts/MyContract.sol \
  --output ./output/pocs \
  --template-only

Enhanced PoC Generation Features:

• AST-based analysis provides 100% accurate contract function extraction
• Production-ready prompts generate exploits suitable for $100k+ bug bounty submissions
• Iterative compilation fixes automatically resolve compilation errors using LLM feedback
• Vulnerability-specific attack chains for different vulnerability types (access control, reentrancy, oracle manipulation, etc.)
• Enhanced contract context provides vulnerability-focused analysis around vulnerable code locations

python main.py foundry ./contracts/MyContract.sol -o ./output/foundry

# Start Anvil locally (in another terminal) or provide an RPC URL to fork-verify
anvil --fork-url https://eth-mainnet.g.alchemy.com/v2/<key>

# Verify generated tests against a fork
python main.py fork-verify ./output/pocs --rpc-url https://eth-mainnet.g.alchemy.com/v2/<key> --block 19000000

python main.py exploit-test <project_name>

This uses findings persisted by the GitHub audit workflow and attempts PoC generation and execution.

The validation system automatically runs during audits with --llm-validation, but you can also use it programmatically:

from pathlib import Path
from core.validation_pipeline import validate_vulnerability
from core.immunefi_formatter import ImmunefFormatter
from core.accuracy_tracker import AccuracyTracker

# Validate a single vulnerability
result = validate_vulnerability(
    vulnerability={
        'vulnerability_type': 'integer_overflow',
        'description': 'Potential overflow in balance calculation',
        'line': 42,
        'code_snippet': 'balance += amount;'
    },
    contract_code=source_code,
    project_path=Path('./contracts')
)

if result['is_false_positive']:
    print(f"❌ Filtered: {result['reasoning']}")
else:
    # Generate Immunefi report for real vulnerabilities
    formatter = ImmunefFormatter()
    report = formatter.generate_report(vulnerability, deployment_info)
    formatter.save_report(report, 'immunefi_submission.md')
    
    # Track submission outcome
    tracker = AccuracyTracker()
    tracker.record_submission(vulnerability, 'accepted', bounty_amount=15000)

See examples/use_validation_system.py for more examples.

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

• Foundry not found

  • Ensure forge/anvil are installed and on PATH (foundryup and export PATH="$PATH:$HOME/.foundry/bin").

• Slither not found

  • Install with pip install slither-analyzer==0.10.0. If unavailable, the pipeline skips Slither.
  • Note: Slither may not be detected by the dependency checker if installed outside PATH, but should still work.

• solc not found or wrong version

  • Install solc-select: pip install solc-select
  • Install required versions: solc-select install 0.4.26 0.8.0 0.8.19 0.8.20 latest
  • Switch versions as needed: solc-select use 0.8.19

• LLM features not working

  • Verify OPENAI_API_KEY and/or GEMINI_API_KEY are set.
  • Some ensemble models may be unavailable in your account/region. The system falls back where possible.

• Database not found

  • For GitHub reports, ensure the audit workflow has been run and ~/.aether/aether_github_audit.db exists.

• Code paths used by the CLI:

  • Main entrypoint: main.py
  • CLI coordinator: cli/main.py
  • Enhanced audit engine: core/enhanced_audit_engine.py
  • LLM analyzer: core/enhanced_llm_analyzer.py
  • AI ensemble: core/ai_ensemble.py (experimental)
  • GitHub auditor: core/github_auditor.py
  • Enhanced Foundry generation: core/foundry_poc_generator.py (AST analysis, iterative fixes, production-ready prompts)
  • Foundry generation and validation: core/llm_foundry_generator.py, core/enhanced_foundry_integration.py
  • Exploit testing: core/exploit_tester.py
  • Validation system ✨:
    • core/validation_pipeline.py - Multi-stage false positive filtering
    • core/governance_detector.py - Governance control detection
    • core/deployment_analyzer.py - Deployment verification
    • core/llm_false_positive_filter.py - Enhanced LLM validation with governance awareness
    • core/immunefi_formatter.py - Professional bug bounty report generation
    • core/accuracy_tracker.py - Submission tracking and metrics
    • core/analysis_cache.py - Smart caching for performance
  • Reporting: core/report_generator.py, core/github_audit_report_generator.py
  • Persistence: core/database_manager.py

• Comprehensive test suite for enhanced features:

  • tests/test_poc_generator_enhancements.py - AST analysis and enhanced prompts
  • tests/test_iterative_compilation_fixes.py - Compilation feedback loop
  • tests/test_enhanced_llm_integration.py - LLM integration improvements
  • tests/test_poc_generator_improvements.py - Integration testing
  • Validation system tests ✨ (163 tests):
    • tests/test_governance_detector.py - Governance detection (32 tests)
    • tests/test_deployment_analyzer.py - Deployment analysis (20 tests)
    • tests/test_validation_pipeline.py - Pipeline integration (24 tests)
    • tests/test_immunefi_formatter.py - Report generation (35 tests)
    • tests/test_accuracy_tracker.py - Metrics tracking (18 tests)
    • tests/test_analysis_cache.py - Caching system (25 tests)
    • tests/test_false_positive_reduction_integration.py - End-to-end integration (9 tests)
  • Move integration tests 🔄 (46 tests):
    • tests/test_move_detector_integration.py - Integration validation (15 tests)
    • tests/test_business_logic_detector.py - Business logic detection (8 tests)
    • tests/test_state_management_detector.py - State management (5 tests)
    • tests/test_centralization_detector.py - Centralization risks (7 tests)
    • tests/test_looping_detector.py - Looping issues (6 tests)
    • tests/test_data_inconsistency_detector.py - Data inconsistency (5 tests)

• Known inconsistencies and caveats:

  • AI ensemble is experimental and subject to change.
  • Some modules print colored output or symbols; functionality does not depend on them.

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

Dhillon Andrew Kannabhiran (@l33tdawg)

• Email: l33tdawg@hitb.org
• Twitter: @l33tdawg
• GitHub: @l33tdawg

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