web3-ai-tools

# AI TOOLS ARSENAL > AI-powered automation for every phase of Web3 bug hunting. > Replaces: 28-cai-framework, 29-claude-skills-security, 30-shannon-ai-pentester, > 31-luan1ao-agent, 32-ai-generated-code-hunting, 33-smartguard-agent --- ## TOOL SELECTION GUIDE | Tool | Target Type | Best For | Cost | |------|------------|----------|------| | **Shannon** | Web apps + API (white-box) | IDOR, SQLi, SSRF, auth bypass | ~$50/run | | **LuaN1ao** | Any web target | Autonomous OWASP Top 10 | $0.09/exploit | | **CAI** | Web/network/IoT | Bug bounty recon + validation | API cost only | | **SmartGuard** | Solidity files | Auto PoC generation for SC bugs | API cost | | **AI Code Hunt** | AI-written contracts | Bugs Slither/Forge miss | Manual (patterns) | **For DeFi smart contracts:** SmartGuard + AI Code Hunt patterns **For DeFi web frontends:** Shannon (web layer) + skills 01-07 (contract layer) **For CTF/web targets:** LuaN1ao or CAI --- ## TOOL 1: SHANNON — AUTONOMOUS WEB PENTESTER **Source:** github.com/KeygraphHQ/shannon **Score:** 96.15% on XBOW source-aware benchmark (100/104 exploits) **Model:** Claude Agent SDK (Anthropic) **Cost:** ~$50/run | ~1-1.5 hours ### What Shannon Finds ``` ✅ IDOR — changes IDs across accounts, tests all API routes ✅ SQLi — error-based and time-based blind ✅ Command injection — OS separators in all inputs ✅ XSS — reflected + stored (confirmed in real browser) ✅ SSRF — webhook/fetch URL inputs, OOB callbacks ✅ JWT attacks — alg:none, RS256→HS256 confusion, weak keys ✅ Auth bypass — session fixation, forgot-password flaws ✅ Privilege escalation — viewer→admin, cross-tenant ✅ OAuth misconfigs — state parameter, redirect_uri ❌ Race conditions (sequential, not concurrent) ❌ Business logic (needs domain expertise) ❌ Smart contract bugs — use files 01-07 for these ❌ Novel techniques not in prompt templates ``` ### Setup ```bash git clone https://github.com/KeygraphHQ/shannon cd shannon && npm install cp .env.example .env # Add: ANTHROPIC_API_KEY=sk-ant-... npm run build # Direct mode (simple): node dist/index.js --config configs/my-target.yaml # Docker (includes nmap, subfinder, whatweb): docker run --env-file .env \ -v ./configs:/app/configs \ keygraph/shannon:latest \ --config configs/my-target.yaml ``` ### Config Template ```yaml # configs/target.yaml target: name: "DeFi App Frontend" url: "https://app.DEFI.com" source_path: "/path/to/frontend/clone" # white-box = much better additional_context: | DeFi app. Users connect MetaMask wallets. Focus on: IDOR in /api/portfolio?address=0x..., GraphQL introspection, JWT handling, SSRF via webhooks. DO NOT interact with smart contracts. authentication: login_type: form # form | sso | api | basic login_url: "https://app.DEFI.com/login" credentials: username: "attacker@test.com" password: "testpassword" login_flow: - "Fill in username field with $username" - "Fill in password field with $password" - "Click the login button" success_condition: type: url value: "/dashboard" test_accounts: - username: "attacker@test.com" password: "testpassword" role: "viewer" - username: "victim@test.com" password: "victimpassword" role: "admin" scope: include: ["https://app.DEFI.com/*"] exclude: ["https://app.DEFI.com/admin/destroy-all"] ``` ### The Shannon Workflow ``` YOUR PLAN: 1. Setup config + 2 test accounts (15 min) 2. Run Shannon (90 min) → do MANUAL business logic testing while it runs 3. Review Shannon findings (30 min) → verify each PoC manually 4. Manual hunting for what Shannon misses: race conditions, business logic, contract layer (60 min) 5. Write reports adapting Shannon's PoC to Immunefi/H1 format (30 min) Shannon + manual = 4 hours → coverage that takes 2 days manually. ``` **WARNINGS:** - NEVER run on production without explicit written authorization - Check program rules: many prohibit automated scanning → instant rejection + ban - Only worth it for targets with max bounty ≥ $5K (costs ~$50) - Always verify findings manually before submitting — LLMs can hallucinate --- ## TOOL 2: LUAN1AO — DUAL-GRAPH AUTONOMOUS PENTESTER **Source:** github.com/SanMuzZzZz/LuaN1aoAgent **Score:** 90.4% on XBOW Benchmark (beats commercial XBOW at 85%) **Architecture:** Causal Graph + Plan-on-Graph (PoG) | P-E-R (Planner-Executor-Reflector) **Cost:** $0.09 median per exploit ### What Makes LuaN1ao Different - **Causal Graph:** Every action requires evidence → no hallucinated attacks - **Plan-on-Graph:** DAG that rewrites itself mid-test → parallel independent paths - **Reflector:** L1-L4 failure attribution → learns from failures mid-run ### Evidence Chain Example ``` Port scan → 3306/tcp open → Hypothesis: MySQL running (confidence 0.8) → Validated: banner confirms MySQL 5.7 → Vulnerability: empty root password → Exploit: mysql -h target -u root -p ``` ### Setup ```bash git clone https://github.com/SanMuzZzZz/LuaN1aoAgent && cd LuaN1aoAgent python3 -m venv venv && source venv/bin/activate pip install -r requirements.txt cp .env.example .env # Edit .env: set LLM_API_KEY + LLM_API_BASE_URL # Build RAG knowledge base (one-time, ~5 min): mkdir -p knowledge_base git clone https://github.com/swisskyrepo/PayloadsAllTheThings knowledge_base/PayloadsAllTheThings cd rag && python -m rag_kdprepare && cd .. # Run: python agent.py \ --goal "Comprehensive web security testing on http://target.com" \ --task-name "hunt_01" \ --web # enables Web UI at localhost:8088 ``` ### Key Config ```ini LLM_PLANNER_MODEL=claude-sonnet-4-6 LLM_EXECUTOR_MODEL=claude-sonnet-4-6 LLM_REFLECTOR_MODEL=claude-sonnet-4-6 SCENARIO_MODE=general # or: ctf EXECUTOR_MAX_STEPS=12 EXECUTOR_FAILURE_THRESHOLD=3 HUMAN_IN_THE_LOOP=true # pause before high-risk actions RAG_TOP_K=5 ``` ### For Web3 / DeFi Targets ```bash python agent.py \ --goal "Audit Ern protocol smart contracts for: 1. Missing access control on distributeRewards() and harvest() 2. Accounting desync between totalDeposited and aToken balance 3. Any role never granted (permanent lock bugs) 4. Reentrancy in harvest→distributeRewards sequence Target: github.com/[ern-repo]" \ --task-name "ern_audit" # HITL injection during run: # "Check if harvest() can be called before any deposit — divide by zero?" ``` --- ## TOOL 3: CAI FRAMEWORK — OFFENSIVE SECURITY AGENT **Source:** github.com/aliasrobotics/cai **Score:** Top-1 in HTB "Human vs AI" CTF | 3,600× faster than humans in CTF benchmarks **Used at:** HackerOne, Mercado Libre, Ecoforest, MiR Industrial ### Setup ```bash python3.12 -m venv cai_env && source cai_env/bin/activate pip install cai-framework cat > .env << 'EOF' ANTHROPIC_API_KEY="your-key-here" CAI_MODEL="claude-sonnet-4-6" CAI_STREAM=false PROMPT_TOOLKIT_NO_CPR=1 EOF cai ``` ### Bug Bounty Workflow ```bash # Step 1: Recon CAI_AGENT_TYPE=bug_bounter CAI_DEBUG=1 cai # "Target: target.com — enumerate all endpoints, check Shodan, find exposed services" # Step 2: Hunt specific class # "Focus on /api/v2/ endpoints. Look for IDOR in user ID params. # Test authenticated vs unauthenticated. Document each finding." # Step 3: Validate before submitting CAI_AGENT_TYPE=retester cai # "Validate this finding: [paste finding]. Confirm exploitable." # Step 4: Generate report CAI_AGENT_TYPE=reporter CAI_REPORT=pentesting cai # "Generate bug bounty report for: [paste validated findings]" ``` ### For Smart Contract Investigation ```bash # Tell CAI to use cast/foundry: "Use cast and foundry to analyze this contract: 0x9f76037494092aceac5b23e21c20b1970a866ef5 Check: 1. What roles exist? cast call addr 'getRoleMember(bytes32,uint256)' ROLE_HASH 0 2. Who has DISTRIBUTOR_ROLE? cast logs with RoleGranted topic 3. Can distributeRewards() be called without DISTRIBUTOR_ROLE? 4. Any MEV opportunity in harvest→distribute flow?" ``` ### Key Agents | Agent | Use For | |-------|---------| | `bug_bounter` | General recon + vulnerability discovery | | `retester` | Validate findings, eliminate false positives | | `web_pentester` | HTTP analysis, JS surface extraction, GraphQL | | `red_teamer` | Offensive ops | | `reporter` | Auto-generate CTF/pentesting/NIS2 reports | | `bb_triage` | Bug bounty discover → validate → deduplicate → report | **Burp Suite + MCP:** ```bash CAI>/mcp load http://localhost:9876/sse burp CAI>/mcp add burp bug_bounter # Now has: send_http_request, proxy history, intruder, repeater, +16 more ``` --- ## TOOL 4: SMARTGUARD — MULTI-AGENT SOLIDITY AUDITOR **Source:** github.com/advaitbd/smartguard **Pipeline:** Slither → RAG → 5 agents → Foundry PoC → auto-run → self-fix loop ### What It Does 1. **AnalysisAgent:** Runs Slither, returns JSON of potential vulns 2. **RAG Enhancement:** Retrieves similar findings from DeFiHackLabs 3. **ValidationAgent:** Filters false positives (checks context, access control) 4. **SkepticAgent:** Kills findings that require impossible preconditions 5. **PlannerAgent:** Creates exploit strategy 6. **ExploitRunnerAgent:** Writes + runs Foundry PoC, self-corrects failures ### Setup ```bash git clone https://github.com/advaitbd/smartguard && cd smartguard pip install -r requirements.txt cp .env.example .env # Set OPENAI_API_KEY or ANTHROPIC_API_KEY ``` ### Usage ```bash # Audit a file python main.py --contract src/Vault.sol # Audit a directory python main.py --contract src/ # Audit deployed contract (fetches from Etherscan) python main.py --address 0x9f76... --network mainnet # Output: console (default) or JSON python main.py --contract src/Vault.sol --output json > findings.json ``` ### When to Use SmartGuard - First-pass scan before manual review (catches 60-80% of standard bugs) - Generate PoC scaffolding for bugs you found manually - Validate whether a finding is exploitable before writing full PoC - When you have many contracts to triage (batch scan) --- ## TOOL 5: HUNTING AI-GENERATED CONTRACTS **Source:** SolAgent paper (arxiv.org/abs/2601.23009) — AI writes 64% pass@1 vs 25% vanilla Solidity ### Why AI-Written Code Is Vulnerable AI code generators (SolAgent, Copilot, Cursor) pass basic tests but consistently miss: 1. **Cross-function reentrancy** — CEI in function A, shared state with function B 2. **Off-by-one at boundaries** — tests cover normal range, not boundary+1 3. **Missing state on error path** — happy path updates state, revert path doesn't 4. **Sibling function access control** — one function has guard, sibling doesn't 5. **Constructor role grants missing** — role defined but never assigned ### Signatures of AI-Generated Code ```bash # AI code is longer and more complex than human code (1.45× lines, 1.56× cyclomatic complexity) # Look for these patterns: grep -rn "// AI generated\|// Generated by\|// Copilot" src/ --include="*.sol" # AI code: comprehensive NatSpec but missing edge cases grep -rn "@notice\|@param\|@return" src/ --include="*.sol" | wc -l # High NatSpec count but low test coverage = likely AI-generated # AI code: defensive redundancy (lots of require statements) grep -rn "require(" src/ --include="*.sol" | wc -l # AI code: modifier + CEI pattern used correctly, but misses CROSS-FUNCTION case grep -rn "nonReentrant" src/ --include="*.sol" grep -rn "modifier only\|onlyRole" src/ --include="*.sol" # Then check: do sibling functions that share state also have nonReentrant? ``` ### Hunt Strategy for AI-Written Contracts ```bash # Step 1: Find all state variables that two+ functions write grep -rn "^\s*\(uint\|int\|bool\|address\|mapping\|bytes\)\b" src/ --include="*.sol" # For each: which functions write it? Do ALL those functions have same guards? # Step 2: Find functions that DON'T revert but have side effects grep -rn "function.*external\|function.*public" src/ --include="*.sol" -A20 | \ grep -B10 "return\b" | grep -v "revert\|require\|assert" # Step 3: Find constructors without role grants grep -rn "constructor" src/ --include="*.sol" -A20 grep -rn "grantRole\|_grantRole\|_setupRole" src/ --include="*.sol" # If constructor exists but no grantRole = role-based access likely broken # Step 4: Slither with specific AI-code detectors slither . --detect reentrancy-no-eth,tautology,msg-value-loop,uninitialized-state ``` ### What Slither Misses in AI Code ``` ✅ Slither catches: classic reentrancy, unprotected upgrades, dangerous delegatecall ❌ Slither misses: - Cross-function reentrancy via shared state - Economic invariant violations (correct code, wrong incentives) - Incorrect mathematical reasoning (formula is syntactically valid but semantically wrong) - Missing constructor role grants (role defined but never assigned) - Off-by-one in complex state machine transitions ``` --- ## TOOL 6: CLAUDE SECURITY SKILLS Install via plugin: ``` /plugin marketplace add Eyadkelleh/awesome-claude-skills-security /plugin install security-payloads@awesome-security-skills /plugin install security-fuzzing@awesome-security-skills /plugin install llm-testing@awesome-security-skills ``` ### 5 Most Useful Slash Commands **`/api-keys`** — Scan codebase for exposed secrets ``` Patterns: AKIA[0-9A-Z]{16} (AWS), sk-[a-z]{48} (OpenAI),