solidity-audit

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)

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

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)

# 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)

# Installation
cargo install aderyn

# Scan
aderyn .

# Output report
aderyn . -o report.md

Tool Output Mapping to EEA Specification

Compiler Version Check

# 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

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

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

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

// 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?

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

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

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

// 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 & Stake Synchronization

// Dangerous example: State sync uses wrong account balance
function notifyFor(address account) external {
    _notifyFor(account, balanceOf(msg.sender));  // Wrong!
    // Should be balanceOf(account)
}

// Check points:
// 1. Is governance module synchronized with main contract state
// 2. Does notify function use correct account address
// 3. Is stake increase/decrease order correct

3.14 Voting Mechanism Security

• Can users manipulate results through extreme voting
• Is voting weight calculation correct
• Is voting cooldown period reasonable

3.15 Copy-Paste Error Detection

// High-risk pattern: Similar code blocks
function _beforeTokenTransfer(address from, address to, uint256 amount) {
    uint256 balanceFrom = (from != address(0)) ? balanceOf(from) : 0;
    uint256 balanceTo = (from != address(0)) ? balanceOf(to) : 0;  // Copy-paste error!
    // Should be: (to != address(0)) ? balanceOf(to) : 0
}

// Detection method:
// 1. Find code blocks with > 80% similarity
// 2. Compare each difference character by character
// 3. Verify each difference is intentional

Special Focus: System Architecture

3.16 Contract Dependency Analysis

Must Complete:

1. Draw contract dependency graph
2. Mark external call directions
3. Identify trust boundaries

Example dependency graph:
┌─────────────────┐
│ GovernanceMothership │
│ (Master)        │
└────────┬────────┘
         │ notify
         ▼
┌─────────────────┐    ┌─────────────────┐
│ FactoryGovernance │    │ RewardsGovernance │
│ (Slave 1)       │    │ (Slave 2)       │
└─────────────────┘    └─────────────────┘

Check Points:

• Do Slave contracts trust Master
• Can external contract addresses be replaced
• Is state synchronization safe

3.17 Trust Assumption Verification

• "Only contracts deployed by factory are trusted" → Is there verification?
• "Governance tokens have no callbacks" → Is there checking?
• "Price oracle returns real price" → Is there boundary checking?

Special Focus: Permission Model

3.18 Admin Permission Scope

// List all onlyOwner/onlyAdmin functions
// Analyze impact scope of each function

// Dangerous pattern: Admin can lock user funds
function emergencyPause() external onlyOwner {
    paused = true;  // Users cannot withdraw funds!
}

// Dangerous pattern: Parameter modification without timelock
function setFeeReceiver(address newReceiver) external onlyOwner {
    feeReceiver = newReceiver;  // Can immediately set malicious contract
}

3.19 Permission Bypass Check

• Can removeMarket + addMarket bypass time restrictions
• Does adding/removing sub-modules affect fund safety
• Does modifying contract addresses bypass security checks

3.20 Timelock Integrity

• Do all critical parameter changes have timelock
• Does timelock cover all bypass paths
• Do users have enough time to respond

Special Focus: Flash Loans & Oracles

3.21 Flash Loan Attack Surface

// Check point: State validation after flash loan callback
// Dangerous example: Only check balance, not mapping
function flashLoan(uint256 amount) external {
    uint256 balanceBefore = address(this).balance;
    IFlashLoanReceiver(msg.sender).execute{value: amount}();
    // ⚠️ Only check balance, not balances mapping!
    if (address(this).balance < balanceBefore) revert RepayFailed();
}

// Correct approach: Check all relevant states
function flashLoan(uint256 amount) external {
    uint256 balanceBefore = address(this).balance;
    uint256 depositsBefore = totalDeposits;  // Record mapping state
    IFlashLoanReceiver(msg.sender).execute{value: amount}();
    require(address(this).balance >= balanceBefore, "Balance not restored");
    require(totalDeposits == depositsBefore, "Deposits changed");  // Verify mapping
}

3.22 Oracle Manipulation Protection

// Dangerous: Using current reserves as price
function _computePrice() private view returns (uint256) {
    return uniswapPair.balance * 1e18 / token.balanceOf(uniswapPair);
    // ⚠️ Reserves can be manipulated by large trades!
}

// Safe: Use TWAP or Chainlink
function _computePrice() private view returns (uint256) {
    (uint256 price0Cumulative, uint256 price1Cumulative,) = 
        UniswapV2OracleLibrary.currentCumulativePrices(pair);
    // Use time-weighted average price
}

// Safe Chainlink usage
function getPrice() public view returns (uint256) {
    (, int256 price,, uint256 timestamp,) = oracle.latestRoundData();
    require(price > 0, "Invalid price");
    require(block.timestamp - timestamp < HEARTBEAT, "Stale data");
    return uint256(price);
}

3.23 Governance Voting Power Persistence

// Dangerous: Only check current voting power
function queueAction(...) external returns (uint256) {
    if (!_hasEnoughVotes(msg.sender)) revert NotEnoughVotes();
    // ⚠️ Attacker can temporarily gain voting power via flash loan!
}

// Safe: Require voting power holding time
function queueAction(...) external returns (uint256) {
    if (!_hasHeldVotesFor(msg.sender, VOTING_DELAY)) revert NotEnoughVotes();
    // Check voting power for past N blocks
}

function _hasHeldVotesFor(address who, uint256 blocks) private view returns (bool) {
    for (uint256 i = 0; i < blocks; i++) {
        if (getVotesAtBlock(who, block.number - i) <= threshold) return false;
    }
    return true;
}

SecureUM Quick Checklist

See references/secureum-knowledge.md for details

Top 30 Must-Check Items

Audit Process

1. Read specification docs → 2. Run static analyzers → 3. Manual code review
4. Run deep tools → 5. Discuss with team → 6. Write report

Manual Review Approaches

Security Design Principles

1. Least Privilege - Grant only necessary permissions
2. Separation of Privilege | Critical operations require multiple authorizations
3. Fail-safe Defaults - Default to deny, not allow
4. Complete Mediation - Check permissions on every access
5. Open Design - Security doesn't depend on secrecy

Step 4: Testing & Verification

Foundry Test Framework

# Installation
curl -L https://foundry.paradigm.xyz | bash
foundryup

# Initialize
forge init my-test

# Run tests
forge test -vvv

# Fuzz testing
forge test --fuzz-runs 10000

# Gas report
forge test --gas-report

Vulnerability PoC Template

// test/ReentrancyPoC.t.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "forge-std/Test.sol";
import "../src/VulnerableContract.sol";

contract ReentrancyPoC is Test {
    VulnerableContract target;
    Attacker attacker;
    
    function setUp() public {
        target = new VulnerableContract();
        attacker = new Attacker(address(target));
        vm.deal(address(target), 10 ether);
        vm.deal(address(attacker), 1 ether);
    }
    
    function test_Reentrancy() public {
        uint256 initialBalance = address(attacker).balance;
        
        // Execute attack
        attacker.attack{value: 1 ether}();
        
        // Verify: Attacker balance should be greater than initial
        assertGt(address(attacker).balance, initialBalance);
        console.log("Stolen:", address(attacker).balance - initialBalance);
    }
}

contract Attacker {
    VulnerableContract target;
    
    constructor(address _target) {
        target = VulnerableContract(_target);
    }
    
    function attack() external payable {
        target.deposit{value: msg.value}();
        target.withdraw();
    }
    
    receive() external payable {
        if (address(target).balance > 0) {
            target.withdraw();
        }
    }
}

Fuzz Testing Example

// test/FuzzTest.t.sol
function testFuzz_Transfer(address to, uint256 amount) public {
    vm.assume(to != address(0));
    vm.assume(to != address(this));
    vm.assume(amount <= token.balanceOf(address(this)));
    
    uint256 balanceBefore = token.balanceOf(to);
    token.transfer(to, amount);
    uint256 balanceAfter = token.balanceOf(to);
    
    assertEq(balanceAfter - balanceBefore, amount);
}

Test Coverage Requirements

Step 5: Report Generation

Report Structure Template

# [Project Name] Smart Contract Security Audit Report

## 1. Summary
- **Audit Period**: YYYY-MM-DD to YYYY-MM-DD
- **Audit Scope**: Contract list and versions
- **Security Level Target**: [S]/[M]/[Q]
- **Total Findings**: High X / Medium Y / Low Z / Informational W

## 2. Audit Scope
| File | Lines | Description |
|------|-------|-------------|
| ContractA.sol | 123 | Core logic |
| ContractB.sol | 456 | Proxy contract |

## 3. Findings Details

### [High] R-01: Reentrancy Vulnerability
**Location**: `Vault.sol#withdraw()` line 42  
**EEA Spec**: Violates [M] External Calls  
**Description**: External call before state update, attacker can reenter to drain funds  
**Impact**: Funds can be completely stolen  

**Reproduction Steps**:
1. Deploy attacker contract
2. Call deposit to deposit 1 ETH
3. Call withdraw to trigger reentrancy
4. Verify contract balance is zero

**Recommendation**:
```solidity
// Use ReentrancyGuard or CEI pattern
function withdraw() external nonReentrant {
    // ...
}

4. Test Coverage

• Static analysis: Slither 4.12.0
• Dynamic testing: Foundry fuzz + unit tests
• Coverage: XX%

5. EEA Compliance Statement

6. Appendix

• Compiler version: solc 0.8.20
• Optimization settings: enabled, runs=200
• Deployment network: Ethereum Mainnet

## References

### Detailed Reference Documents
- **EEA Specification Details**: See [references/eea-requirements.md](references/eea-requirements.md)
- **Vulnerability Checklist**: See [references/vulnerability-checklist.md](references/vulnerability-checklist.md)
- **Testing Guide**: See [references/testing-guide.md](references/testing-guide.md)
- **SecureUM Knowledge Base**: See [references/secureum-knowledge.md](references/secureum-knowledge.md) - 200+ audit knowledge points

### External Resources
- EEA EthTrust V3 Specification: https://entethalliance.org/specs/ethtrust-sl/v3/
- Secureum Knowledge Graph: https://github.com/x676f64/secureum-mind_map
- OpenZeppelin Contracts: https://docs.openzeppelin.com/contracts
- EIP Standards List: https://eips.ethereum.org/all
- Mastering Ethereum: https://masteringethereum.xyz/

### Common Tools
| Tool | Purpose | Link |
|------|---------|------|
| Slither | Static analysis | https://github.com/crytic/slither |
| Aderyn | Fast scanning | https://github.com/Cyfrin/aderyn |
| Foundry | Test framework | https://github.com/foundry-rs/foundry |
| Echidna | Fuzz testing | https://github.com/crytic/echidna |
| Mythril | Symbolic execution | https://github.com/ConsenSys/mythril |

## Usage Example

User: Help me audit this ERC20 contract for security

AI: I will perform a basic audit following EEA EthTrust specification:

1. Project Preparation

   • Please provide contract source code
   • Target security level: [S] Basic

2. Execute Scanning

   • Running Slither static analysis...
   • Detected the following issues...

3. Manual Review

   • Checking access control...
   • Checking reentrancy risks...

## Audit Capability Assessment Framework

### Audit Quality Self-Assessment

After completing an audit, use this framework for self-evaluation:

| Dimension | Check Item | Assessment Method |
|-----------|------------|-------------------|
| Coverage | Did you review all core contracts | Contract checklist |
| Depth | Did you discover complex logic vulnerabilities | PoC verification |
| Tools | Did you use automated tools | Slither/Aderyn reports |
| Comparison | Compare with professional reports | Gap analysis |

### Capability Level Classification

| Level | Standard | Typical Performance |
|-------|----------|---------------------|
| Junior | Can find basic vulnerabilities | Reentrancy, permission issues, overflow |
| Intermediate | Can find business logic issues | Price manipulation, liquidation issues |
| Senior | Can find complex interaction vulnerabilities | Cross-chain, composability attacks |
| Expert | Can design security architecture | Formal verification, zero-knowledge proofs |

### Audit Time Reference

| Contract Size | Junior | Intermediate | Senior |
|---------------|--------|--------------|--------|
| <500 lines | 2 hours | 1 hour | 30 minutes |
| 500-2000 lines | 8 hours | 4 hours | 2 hours |
| 2000-10000 lines | 40 hours | 20 hours | 10 hours |
| >10000 lines | 2 weeks+ | 1 week+ | 3 days+ |

### Common Missed Checks

After completing an audit, check if you missed:

- [ ] Callback function security
- [ ] Multi-signature/timelock configuration
- [ ] Special token compatibility (rebasing, fee-on-transfer)
- [ ] Cross-chain message verification
- [ ] Price precision issues
- [ ] Gas limit boundary conditions
- [ ] Upgrade pattern security
- [ ] Signature verification security

### 🎯 Professional Audit Comparison Template

After completing an audit, compare using this format:

```markdown
## My Findings vs Professional Audit

### Matched Items
| My Finding | Professional Audit Finding | Match Level |
|------------|---------------------------|-------------|
| Reentrancy risk | ✅ Usually found | High |
| Permission issues | ✅ Usually found | High |

### Missed Items
| Professional Finding | Why I Missed It |
|---------------------|-----------------|
| Math boundaries | Need fuzz testing |
| Interaction vulnerabilities | Need symbolic execution |

### Capability Score
- This round score: X/100
- Cumulative average: Y/100

📈 Audit Capability Improvement Path

🔧 Toolchain Gap Solution (Addressing 60% gap)

Problem: AI cannot directly run Slither/Foundry

Solution: Request user to run tools, AI analyzes results

Please provide tool scan results for audit:

# Slither quick scan
slither . --exclude-dependencies --json slither.json

# Or Aderyn scan
aderyn . -o report.md

Provide the output to me, and I will combine tool findings with deep analysis.

Tool Output Mapping:

⏱️ Time Optimization Solution (Addressing 25% gap)

Problem: Limited audit time

Solution: Focus on high-risk modules

35-minute Allocation:

Access Control (5 minutes): owner/governor/permission modifiers
Reentrancy Check (5 minutes): external calls + state update order
Token Security (10 minutes): SafeERC20/return value checks
Critical Vulnerabilities (10 minutes): liquidation/price/permission bypass
Report Output (5 minutes): formatted output

High-Risk Function Priority:

1. withdraw/transfer/claim
2. liquidate/absorb/seize
3. setOwner/setConfig
4. getPrice/updatePrice

📚 Knowledge Gap Solution (Addressing 15% gap)

Problem: Unfamiliar with new protocol features

Solution: Protocol type knowledge base

See: references/toolchain-guide.md for details