Metadata-Version: 2.4
Name: aw3ss
Version: 4.15.0
Summary: Automated Web3 Smart Contract Security Scanner with Stateful Fuzzing and Executable Foundry PoC Validation
Home-page: https://github.com/amouguibricemartial-stack/AW3SS
Author: Brice Amougui
Author-email: Brice Amougui <contact@aw3ss.dev>
License: MIT
Project-URL: Homepage, https://github.com/amouguibricemartial-stack/AW3SS
Project-URL: Documentation, https://github.com/amouguibricemartial-stack/AW3SS/tree/master/docs
Project-URL: Repository, https://github.com/amouguibricemartial-stack/AW3SS.git
Project-URL: Issues, https://github.com/amouguibricemartial-stack/AW3SS/issues
Keywords: web3,security,smart-contracts,solidity,foundry,slither,static-analysis,fuzzing,defi,poc
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: litellm>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: slither-analyzer>=0.10.0
Requires-Dist: rich>=13.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: torch>=2.0.0
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

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

[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
[![Docker Sandbox](https://img.shields.io/badge/docker-isolated%20sandbox-2496ED.svg)](https://www.docker.com/)
[![Foundry Powered](https://img.shields.io/badge/foundry-forge%20%7C%20cast-orange.svg)](https://getfoundry.sh/)
[![Static Analysis](https://img.shields.io/badge/static%20analysis-Slither%20%7C%20AST-yellow.svg)](https://github.com/crytic/slither)
[![SARIF Export](https://img.shields.io/badge/report-SARIF%20v2.1.0-green.svg)](https://sarifweb.azurewebsites.net/)
[![License](https://img.shields.io/badge/license-MIT-purple.svg)](LICENSE)

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

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

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

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

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

---

## 📄 License
Distributed under the MIT License. See `LICENSE` for more information.
