Wallet Hunter — Automated EVM Wallet Vulnerability Hunting

Wallet Hunter is a local-first audit workflow and helper CLI for finding high-value EVM / Ethereum-family crypto wallet bugs in account abstraction, delegated authority, session permissions, modules, paymasters, passkeys, permits, and signature validation.

It is built around one question:

A proof may be valid, but is it valid authorization for this exact account, chain, target, selector, calldata, value, token, recipient, nonce, deadline, policy, executor, and sink?

Wallet Hunter is not a generic wallet scanner. v1.0.0 is focused on EVM/Ethereum-family wallets and account-authority systems. It is not a Solana, Cosmos, Bitcoin, Lightning, Aptos, Sui, Move, hardware-wallet firmware, or UI-phishing audit tool; those ecosystems need separate adapters and threat models.

Safety boundary: use repository source, local forks, mocks, sandbox accounts, and canary assets only. Do not request real signatures, submit live transactions, move real funds, or mutate production wallet state.

Best-fit targets

Wallet Hunter is strongest when a wallet has a complex authorization boundary:

1. ERC-4337 / account abstraction smart accounts

   • Smart account implementations, EntryPoint integrations, bundlers, aggregators, paymasters, validateUserOp, userOpHash, nonce lanes, callData, paymasterAndData, and gas-field binding.
   • High-value bugs: validation/execution drift, missing UserOperation fields, paymaster sponsorship bypass, nonce-lane replay, wrong EntryPoint/version or chain binding.

2. Modular wallets and Safe-style accounts

   • ERC-7579 / ERC-6900 accounts, modules, validators, executors, hooks, fallback handlers, guards, plugin lifecycle, install/uninstall flows.
   • High-value bugs: validator-as-executor confusion, module bypass of guards, weak fallback paths, persistent module authority, malicious uninstall/revert recovery failure.

3. Session-key and delegated-permission wallets

   • Session keys, spending limits, allowlists, scoped permissions, delegation toolkits, agent wallets, recurring authorization.
   • High-value bugs: selector-only checks, missing target/token/recipient/amount binding, wrapper/router/multicall smuggling, aggregate batch effects, delegatecall semantic drift, permission object vs enforcement mismatch.

4. EIP-7702 delegated EOA systems

   • tx.origin, msg.sender == tx.origin, address.code.length == 0, EXTCODESIZE, EOA-only gates, delegated code, set-code transaction flows.
   • High-value bugs: code-bearing EOAs passing legacy EOA gates, initialization/storage migration races, delegated-code persistence mistakes, relayer or sponsor misclassification.

5. Permit / ERC-1271 / signature-heavy wallets

   • EIP-712, ERC-1271, ERC-2612, Permit2, meta-transactions, relayers, forwarders.
   • High-value bugs: missing chain/account/target/spender/nonce/deadline binding, dynamic ERC-1271 validity treated as static authorization, Permit2 one-shot vs allowance confusion.

6. Passkey, WebAuthn, embedded, and WaaS wallets

   • Passkey wallets, WebAuthn/P-256 verifiers, social login, embedded custody, backend-controlled wallet APIs, Privy-like or WaaS-like systems.
   • High-value bugs: challenge not bound to account/chain/action digest, RP ID/origin only checked outside the decisive boundary, weaker recovery paths, backend API policy bypass, authorization-key/manual-approval drift.

Poor-fit targets

Use a different adapter or manual methodology for:

• Non-EVM ecosystems: Solana, Cosmos, Bitcoin, Lightning, Aptos, Sui, Move.
• Pure wallet UI or phishing review without a contract/API/signer policy boundary.
• Fully custodial CEX wallets with no public contract, SDK, API policy, or bounty scope.
• Hardware-wallet firmware, secure elements, USB/HID signing flows, side-channel work, or supply-chain review.

What it produces

• Source scan markers for EVM wallet authority surfaces.
• Wallet feature profile and audit focus areas.
• Binding analysis for UserOperation, EIP-712, Permit, and related proof paths.
• Greedy attacker risk matrix and ranked attack-path hypotheses.
• Foundry harness skeletons for target-bound reproduction work.
• Admission checks for safe traces and content-bound evidence receipts.

Scanner output is always HYPOTHESIS_ONLY until a local/fork/mock reproduction, accepted proof, measurable sink effect, and control case prove the issue.

Files

• SKILL.md — main Hermes operating procedure.
• INSTALL.md — install guide for Hermes, Claude Code, Codex, and AGENTS.md-compatible agents.
• AGENTS.md — repository-level instructions for coding agents.
• .claude/skills/wallet-hunter.md — Claude Code skill adapter.
• adapters/codex/AGENTS.md — portable adapter for Codex and other AGENTS.md readers.
• references/standards-notes.md — source-grounded notes for ERC-4337, EIP-7702, EIP-712, ERC-1271, ERC-2612, Permit2, ERC-7579, and ERC-6900.
• references/current-wallet-features.md — current EVM wallet market-feature map: programmable accounts, delegated permissions, gas abstraction, chain abstraction, embedded custody controls, passkeys, recovery, and agent wallets.
• references/greedy-attacker-playbook.md — profit-first attacker ordering: largest sink, cheapest accepted proof, missing binding, composition, persistence.
• references/attack-matrix.md — concrete high-value probes.
• references/admission-and-reporting.md — confirmation gates and report shape.
• templates/*.json — starting artifacts.
• scripts/wallet_hunter.py — stdlib-only helper CLI.
• scripts/tests/test_wallet_hunter.py — smoke tests for the helper and bundle.
• assets/lab/ — Foundry lab with weak/strong wallet control cases.
• assets/fixtures/minimal-wallet-target/ — stable miniature wallet target used to verify triage artifact generation.

Quick start

git clone https://github.com/75day/wallet-hunter.git ~/.wallet-hunter
cd ~/.wallet-hunter
python3 scripts/wallet_hunter.py validate-bundle .
python3 -m unittest discover -s scripts/tests -v

Run a local triage against an EVM wallet repository:

python3 ~/.wallet-hunter/scripts/wallet_hunter.py triage /path/to/target --scope production --output-dir /path/to/target/.wallet-hunter

Verify the built-in fixture:

python3 scripts/wallet_hunter.py triage assets/fixtures/minimal-wallet-target --scope production --output-dir /tmp/wallet-hunter-fixture-triage

Run the Foundry lab if forge is installed:

(cd assets/lab && forge test -vvv)

Agent installation

See INSTALL.md for Hermes Agent, Claude Code, Codex, and other AGENTS.md-compatible coding agents.

v1.0 Commands

python3 scripts/wallet_hunter.py triage <target-root> --scope production --output-dir <out-dir>
python3 scripts/wallet_hunter.py profile-bytecode --bytecode-file <artifact-or-bytecode-file>
python3 scripts/wallet_hunter.py rank-paths --scan-json <scan.json> --binding-json <binding-analysis.json> --bytecode-profile-json <bytecode-profile.json>
python3 scripts/wallet_hunter.py triage-bytecode --bytecode-file <artifact-or-bytecode-file> --output-dir <out-dir>
python3 scripts/wallet_hunter.py policy-check <policy.json> <trace.json>

v1.0 Hardening

• Foundry lab output is configured outside the skill tree so normal lab runs do not poison bundle validation.
• validate-trace rejects live/prod execution environments, missing explicit safety flags, and whitespace-only impact bounds for confirmed/exploitable traces.
• rank-paths is a bounded hypothesis scheduler, not a finding engine; unrelated binding gaps are not applied globally.
• profile-bytecode reports selector/opcode hints as RAW_PUSH4_HINTS_ONLY until dispatcher reachability and sink control are proven.

SEO keywords

EVM wallet security, Ethereum wallet audit, smart account security, account abstraction security, ERC-4337 audit, EIP-7702 security, session key security, delegated permissions, modular wallet security, Safe module audit, ERC-7579, ERC-6900, ERC-1271, EIP-712, Permit2, paymaster security, bundler security, WebAuthn wallet security, passkey wallet audit, crypto wallet vulnerability hunting, bug bounty wallet security.