🛡️ AW3SS v4.16 — Automated Web3 Security Scanner & PoC Engine

AW3SS (Automated Web3 Security Scanner) is an enterprise-grade, autonomous smart contract security framework designed for vulnerability research, deep AST data-flow analysis, multi-agent AI orchestration, stateful invariant fuzzing, and deterministic Proof of Concept (PoC) validation under isolated Docker Foundry sandboxes.

🏗️ End-to-End Architecture Pipeline

flowchart TD
    subgraph INGESTION ["1. Pre-build & Static Analysis"]
        A[Target Smart Contracts .sol / .rs / .cairo] --> B[Solc Selection & Hybrid Remappings]
        B --> C[Slither & Slitherin AST Data-Flow / Call-Graph]
    end

    subgraph RAG_AGENTS ["2. Threat Intelligence & Multi-Agent AI"]
        C --> D[RAG Engine : 1,015 Indexed Exploit Templates]
        D --> E[Multi-Agent Analysis: Finance, Access, EVM, MEV]
        E --> F[Vulnerability Deduplication AST Sink Hash]
    end

    subgraph SANDBOX ["3. Docker Sandbox & Deterministic PoC"]
        F --> G[Dual-Level Simulation : Level 1 Mock / Level 2 Fork]
        G --> H[Docker Sandbox : --cap-drop=ALL --dns 1.1.1.1]
        H --> I{Universal 8 Formal Assertions & forge test}
        I -->|FAIL / Revert| J[Autonomous Self-Healing Loop : Max 3 Retries]
        J --> H
    end

    subgraph REPORTING ["4. Verified Outputs & CI/CD"]
        I -->|PASS| K[Non-LLM Markdown Report C4 / Sherlock / Immunefi]
        I -->|PASS| L[SARIF v2.1.0 JSON & Discord/Telegram Webhooks]
        I -->|Exhausted| M[FALSE_POSITIVE Auto-Discard]
    end

⚡ Core Innovations & Features (v4.16)

1. 🧠 Multi-Chain Native RPC Routing & Dual-Level Sandbox

• Level 1 (Local Mocks) : Instant local compilation with mocks for Uniswap V2/V3, Chainlink Aggregators, and WETH9.
• Level 2 (Deterministic Mainnet Forking) : Native, dynamic multi-chain state forking via official high-speed RPCs:
  • Ethereum Mainnet, Arbitrum One, Base, Flare Network, Cronos, Polygon, Optimism, BSC.
• Container Hardening : Strict container constraints (--cap-drop=ALL --dns 1.1.1.1 --memory=4g, non-root user).

2. 📚 Vector RAG Knowledge Base (1,015 Curated Exploits)

• Integrated SQLite vector index covering real-world exploit patterns:
  • Tokenomics & DeFi Logic (420 templates)
  • Price Oracles & TWAP Manipulation (145 templates)
  • ERC-4626 Vault Inflation & Accounting (71 templates)
  • Privilege Escalation & Access Control (58 templates)
  • Read-Only & Cross-Function Reentrancy (15 templates)

3. 🎯 Universal 8 Formal Invariant Assertions

AW3SS validates vulnerabilities across the complete severity spectrum without false validations:

• CRITICAL: Direct Asset Drain (assertGt), Admin Takeover (assertEq(owner, attacker)), Permanent Lock.
• HIGH: Undercollateralized Bad Debt (borrowed > collateral), Signature Replay (EIP-712), Unclaimed Yield Theft.
• MEDIUM: Stale Oracle Acceptance (vm.warp), Share Ratio Discontinuity, Gas Limit Exhaustion (> 30M gas).
• LOW: Precision Loss / Dust Truncation (previewDeposit(dust) == 0).

4. 🔄 Autonomous Self-Healing Engine (3 Retries Max)

When a generated PoC encounters compilation or execution issues, the Self-Healing engine automatically iterates with temperature-controlled adjustments:

• Attempt 1 (T=0.1) : Solidity syntax, pragma alignments, imports.
• Attempt 2 (T=0.3) : Remappings, interfaces, mock setups.
• Attempt 3 (T=0.5) : Minimal vector isolation & state adjustments.

🚀 Quickstart

Prerequisites

• Python 3.11+
• Docker Desktop (active engine)
• Foundry (forge / cast)
• Git

Installation

# Clone the repository
git clone https://github.com/<your-username>/AW3SS.git
cd AW3SS

# Install Python dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env

# Initialize SQLite database and RAG embeddings
python aw3ss.py init-db

Running Scans

# 1. Scan an EVM Solidity target on Ethereum Mainnet Fork
python aw3ss.py scan ./target/my_protocol --network mainnet

# 2. Scan on Arbitrum / Base / Flare
python aw3ss.py scan ./target/arbitrum_vault --network arbitrum

# 3. Multi-Ecosystem Plugins (Cairo / Solana / Soroban)
python aw3ss.py scan ./tests/cairo_target --network mainnet
python aw3ss.py scan ./tests/solana_target --network mainnet

📊 Standardized Outputs

• Markdown Audit Report : Ready for submission on Code4rena, Sherlock, and Immunefi.
• SARIF v2.1.0 : data/reports/<scan_id>.sarif.json for GitHub Advanced Security and VS Code SARIF Viewer.
• PoC Artifacts : Standalone, runnable Foundry test file stored in data/pocs/ with exact reproduction steps.

🧪 Testing & Verification

Execute the complete test suite:

pytest tests/test_v415_integration.py tests/test_env_config.py -v

📄 License

Distributed under the MIT License. See LICENSE for more information.