solidity-audit

Solidity smart contract security audit assistant following EEA EthTrust V3 specification. Performs structured audit workflow: vulnerability scanning, security analysis, audit reports. Detects reentrancy, integer overflow, access control issues, and more. Supports Slither/Aderyn static analysis and Foundry testing. Triggers: smart contract audit, solidity audit, security review, vulnerability assessment.

# Solidity Smart Contract Audit Assistant

A structured smart contract security audit workflow based on EEA EthTrust Security Levels V3 specification.

## Audit Process Overview

```
1. Project Preparation → 2. Automated Scanning → 3. Manual Review → 4. Testing & Verification → 5. Report Generation
```

### ⚡ Quick Audit Mode (Within 30 minutes)

Suitable for emergency situations or preliminary assessment:

```
1. Access Control Check (5 minutes)
   - Owner permissions
   - Sensitive function modifiers
   
2. Reentrancy Risk Check (5 minutes)
   - External call positions
   - State update order
   
3. Token Security Check (10 minutes)
   - SafeERC20 usage
   - Return value checks
   
4. Critical Vulnerability Scan (10 minutes)
   - Integer overflow
   - Signature verification
   - Permission bypass
```

### 📊 Audit Capability Baseline (Based on 10 rounds of training)

| Capability Dimension | AI Audit | Professional Audit | Gap |
|---------------------|----------|-------------------|-----|
| Basic Vulnerabilities | 90% | 100% | -10% |
| Business Logic | 75% | 95% | -20% |
| Math Boundaries | 50% | 85% | -35% |
| Complex Interactions | 60% | 90% | -30% |

**AI Advantages**: Fast coverage, pattern matching, broad knowledge
**AI Disadvantages**: Missing toolchain, limited depth analysis, boundary conditions

## Step 1: Project Scope & Preparation

### Input Confirmation
- Contract source code (preferably frozen version for audit)
- Compiler version and optimization settings
- Project documentation (architecture diagrams, functional descriptions)
- Test cases (if available)

### Audit Scope Definition
```
□ Number of logic contracts and their functions
□ Whether proxy contracts are included (upgradeability)
□ External dependencies (oracles, cross-chain bridges, etc.)
□ Deployment network (mainnet/L2/testnet)
```

### Security Level Selection
| Level | Applicable Scenarios | Core Requirements |
|-------|---------------------|-------------------|
| [S] Basic | Simple token contracts, basic DeFi | No known high-risk vulnerabilities, basic protection |
| [M] Intermediate | Complex DeFi, NFT markets, DAOs | External call security, access control, oracle verification |
| [Q] Advanced | Cross-chain bridges, lending protocols, treasury management | Business logic verification, MEV protection, complete documentation |

### Pre-Audit Checklist
- [ ] Code is frozen, no modifications during audit period
- [ ] Compiler version is fixed (e.g., `pragma solidity 0.8.20`)
- [ ] All dependency versions are locked
- [ ] Deployment scripts or configurations are provided
- [ ] Test coverage report is available (if exists)

## Step 2: Automated Tool Scanning

### Static Analysis Tools

**Slither (Trail of Bits)**
```bash
# Installation
pip install slither-analyzer

# Basic scan
slither . --exclude-dependencies

# Output JSON format
slither . --exclude-dependencies --json output.json

# Specific detectors
slither . --detect reentrancy-eth,uninitialized-state
```

**Aderyn (Rust-based, fast)**
```bash
# Installation
cargo install aderyn

# Scan
aderyn .

# Output report
aderyn . -o report.md
```

### Tool Output Mapping to EEA Specification

| Tool Detection | EEA Requirement | Security Level |
|----------------|-----------------|----------------|
| `tx.origin` usage | [S] No tx.origin | S |
| `selfdestruct` | [S] No selfdestruct() | S |
| `CREATE2` | [S] No CREATE2 | S |
| `assembly` blocks | [S] No assembly {} | S |
| Reentrancy detection | [M] External Calls | M |
| Uninitialized variables | [S] Initialize State | S |
| Unchecked return values | [M] Check Return Values | M |

### Compiler Version Check
```bash
# Check for known compiler bugs
slither . --check-compiler-bugs
```

Refer to EEA § 3.9 Source code, pragma, and compilers for compiler-related security requirements.

## Step 3: Manual Review Checklist

### [S] Basic Level Review

#### 3.1 Replay Attack Protection
```solidity
// Check: Does transaction hash include chainId?
// Correct example:
keccak256(abi.encodePacked(
    "\x19\x01",
    DOMAIN_SEPARATOR,  // Includes chainId
    hashStruct
))

// Dangerous: Without chainId allows cross-chain replay
```

#### 3.2 Dangerous Opcodes
- [ ] Check `CREATE2` usage justification, whether necessary
- [ ] Check `selfdestruct` calls, confirm legitimate reason
- [ ] Verify `delegatecall` target address controllability

#### 3.3 Permission Verification
```solidity
// Dangerous: Using tx.origin for authorization
require(tx.origin == owner);  // Phishing attack risk

// Correct: Use msg.sender
require(msg.sender == owner);
```

#### 3.4 Encoding Security
```solidity
// Dangerous: Hash collision with consecutive variable-length parameters
keccak256(abi.encodePacked(str1, str2));  // str1="ab", str2="c" == str1="a", str2="bc"

// Safe: Use encode or fixed length
keccak256(abi.encode(str1, str2));
```

#### 3.5 Inline Assembly
- [ ] List all `assembly` blocks
- [ ] Check if detailed comments explain the reason
- [ ] Focus on memory operations and storage operations

### [M] Intermediate Level Review

#### 3.6 External Calls & Reentrancy
```solidity
// CEI Pattern Check (Checks-Effects-Interactions)
function withdraw() external {
    // 1. Checks
    require(balances[msg.sender] > 0, "No balance");
    
    // 2. Effects (update state first)
    balances[msg.sender] = 0;
    
    // 3. Interactions (external calls last)
    (bool success, ) = msg.sender.call{value: amount}("");
    require(success, "Transfer failed");
}

// Read-only reentrancy check: Are view functions called externally before state updates?
```

#### 3.7 Oracle Dependencies
- [ ] Is the price data source trustworthy?
- [ ] Is there a TWAP time window?
- [ ] Is there a data staleness detection mechanism?
- [ ] Is there a failover plan?

```solidity
// Check: Is there price deviation detection?
uint256 price = oracle.getPrice();
require(price > 0 && price < MAX_PRICE, "Invalid price");

// Check: Is there timestamp validation?
require(block.timestamp - oracle.lastUpdate() < HEARTBEAT, "Stale data");
```

#### 3.8 Access Control
- [ ] Check permission modifiers on critical functions
- [ ] Is role management correctly implemented
- [ ] Can initialization functions be called repeatedly

```solidity
// Dangerous: Unprotected initialization function
function initialize() external {
    owner = msg.sender;  // Anyone can call!
}

// Safe: Use OpenZeppelin Initializable
function initialize() external initializer {
    owner = msg.sender;
}
```

#### 3.9 Integer Overflow
```solidity
// Solidity 0.8+ checks overflow by default
// But need to check unchecked blocks:
unchecked {
    // Overflow here will not be detected!
    uint256 result = a + b;  // Dangerous
}

// Special case: Loop counters can safely use unchecked
for (uint256 i; i < n; ) {
    // ...
    unchecked { i++; }
}
```

### [Q] Advanced Level Review

#### 3.10 Logic & Documentation Consistency
- [ ] Compare code implementation with whitepaper/documentation
- [ ] Check for undocumented "hidden features"
- [ ] Verify mathematical formula implementation correctness

#### 3.11 MEV Attack Surface
- [ ] Sandwich attack risk (AMM pricing)
- [ ] Front-running risk (public mempool)
- [ ] Liquidation mechanism exploitable

```solidity
// AMM sandwich attack example
// User transaction: A -> B
// Attacker: Buy B before user transaction, sell B after
// Protection: Use TWAP, slippage protection
```

#### 3.12 Upgradeable Contract Security
```solidity
// Check items:
// 1. Is the proxy contract implementation correct?
// 2. Is the initialization function protected against reentry?
// 3. Are upgrade permissions reasonable?
// 4. Is there storage layout conflict?

// Dangerous: Storage layout conflict
// V1: uint256 a; uint256 b;
// V2: uint256 a; address c; uint256 b;  // c overwrites b's slot!
```

### Special Focus: Governance Module

Governance contract vulnerabilities are often more subtle but have greater impact, requiring specialized review.

#### 3.13 Voting Power