Lord1Egypt/MaatEye

# 👁️⚖️ MaatEye — 智能合约的永恒守护者

🏛️ 以玛阿特 (Ma'at / ماعت) 命名 — 古埃及神话中代表真理、平衡与正义的女神。
“她将心脏与羽毛相权衡。”

## 🚀 愿景 **MaatEye** 是一款开源的、由社区驱动的**智能合约漏洞扫描器**，可自动检测 **24 条 EVM 链**上的 **20 多种危险模式**，追踪来自 CoinGecko + RPC 事件日志 + 区块链浏览器 API 的 **15,000 多种 token**。 ### 🔥 MaatEye 为何与众不同？ | 功能 | MaatEye | 其他工具 | |---------|---------|--------| | 🆓 **100% 免费** (运行在 GitHub Actions 上) | ✅ | ❌ 付费 API ($100+/月) | | 🌐 **大规模 token 发现** (15K+ token) | ✅ CoinGecko + RPC 日志 | ❌ 仅前 50 名 | | 🔄 **自动更新** (新模式自动部署) | ✅ | ❌ 手动更新 | | 🚩 **实时红旗标记注册表** (公开 Issues) | ✅ | ❌ 私有数据库 | | 🧩 **社区模式** (任何人都可以提交 PR) | ✅ | ❌ 闭源 | | 🔍 **多种发现来源** | ✅ 结合 6 种来源 | ❌ 1-2 种来源 | | 🗄️ **持久化 token 存储** (去重，增量更新) | ✅ | ❌ 无状态 | ## 🪙 Token 发现 — 结合 6 种来源 MaatEye 不仅仅是扫描“前 30 名”的 token — 它通过结合 **6 种来源**发现**一切**。 ### 来源 1：🪙 CoinGecko API (主要来源) | 详情 | 内容 | |--------|-------| | 覆盖范围 | 覆盖 100 多条链的 **15,000 多种 token** | | Endpoint | `api.coingecko.com/api/v3/coins/list?include_platform=true` | | 成本 | 免费 (无需 API key) | | 支持链 | Ethereum, BSC, Polygon, Arbitrum, Optimism, Base, Avalanche，以及另外 14 条链 | ### 来源 2：🧾 RPC 事件日志 (实时) | 详情 | 内容 | |--------|-------| | 方法 | `eth_getLogs` → `Transfer(address,address,uint256)` 事件 | | 覆盖范围 | 任何曾发出过 Transfer 事件的 ERC20/ERC721 | | 粒度 | 逐块实时发现 | | 去重 | 与其他来源自动合并 | ### 来源 3：🔭 浏览器 API (已验证) | 详情 | 内容 | |--------|-------| | 覆盖范围 | 每条链上排名前 50 的已验证合约 | | API | 兼容 Etherscan 的 API + Blockscout | | 来源 | 直接获取已验证的源代码 | ### 来源 4：📚 已知 Token 列表 (精选) | 详情 | 内容 | |--------|-------| | 覆盖范围 | 每条链上 10-18 种主要 token | | 目的 | 为低活跃度链提供种子注册表 | | 维护 | 通过 PR 更新 | ### 来源 5：🦎 DexScreener 推广 (实时) | 详情 | 内容 | |--------|-------| | Endpoint | `api.dexscreener.com/token-boosts/latest/v1` | | 覆盖范围 | **所有链**上新获得推广/热门的 token | | 成本 | 免费 (无需 API key) | | 优势 | 在 CoinGecko 之前捕获 token — 新发行、memecoin、低市值 token | ### 来源 6：🦙 DeFiLlama 币种列表 (全面) | 详情 | 内容 | |--------|-------| | Endpoint | `coins.llama.fi/list` | | 覆盖范围 | 覆盖 100 多条链的 **500K+ 条目** | | 成本 | 免费 (无需 API key) | | 优势 | 在较新的/L2 链上比 CoinGecko 覆盖面更广 | ### 🗄️ 持久化 Token 存储 所有发现的 token 都存储在一个**去重的 JSON 注册表**中： ``` 📁 data/token_registry.json ├── 🔑 chain + address (primary key, guaranteed unique) ├── 📝 symbol, name, decimals (enriched via eth_call) ├� 📅 discovered_at, last_scanned, scan_count ├── 🔍 has_source, vuln_count, max_severity └── 🔗 source (coingecko/rpc/explorer/known) ``` **仅限增量更新** — 新的发现会添加到现有数据中，绝不会重复。 ## 📋 20 场灾难 — 检测模式 | # | 模式 | 严重性 | 检测内容 | |---|---------|----------|-----------| | 🎭 | **P01 — 未受保护的 Mint** | 🔴 危急 | 任何人都可以铸造 token | | 💀 | **P02 — 任何人可触发 Selfdestruct** | 🔴 危急 | 任何人都可以销毁合约 | | 🔄 | **P03 — 重入攻击** | 🔴 危急 | 状态更新前的不安全外部调用 | | 📐 | **P04 — 整数溢出/下溢** | 🔴 危急 | 未使用 SafeMath 的算术运算 | | 🚪 | **P05 — tx.origin 身份验证** | 🟡 高危 | 易受钓鱼攻击的身份验证 | | 📞 | **P06 — 未检查的 Call** | 🟡 高危 | 调用未检查返回值 | | 🎪 | **P07 — Delegatecall 注入** | 🔴 危急 | 任意 delegatecall 目标 | | 🗂️ | **P08 — 存储冲突** | 🟡 高危 | 代理合约存储布局不匹配 | | 🎯 | **P09 — 无输入验证** | 🟡 高危 | 无界循环，未验证的参数 | | 🏷️ | **P10 — 预言机操纵** | 🔴 危急 | 没有操纵检查的价格馈送 | | 💧 | **P11 — 闪电贷攻击向量** | 🟡 高危 | 易受闪电贷价格操纵影响 | | ✍️ | **P12 — 签名重放** | 🟡 高危 | 没有 nonce/chainId 的 EIP-712 | | 🗳️ | **P13 — 治理攻击** | 🔴 危急 | 低法定人数，投票操纵 | | 👑 | **P14 — 放弃所有权 (不安全)** | 🟡 中危 | 没有 timelock 的所有权放弃 | | 🔍 | **P15 — 错误的可见性** | 🟡 中危 | 内部函数被公开暴露 | | 🍼 | **P16 — 未初始化的代理合约** | 🔴 危急 | 没有初始化守卫的代理合约 | | 🎪 | **P17 — 任意外部调用** | 🔴 危急 | 无限制的外部调用目的地 | | 🚫 | **P18 — 缺少访问控制** | 🟡 高危 | 关键函数缺少 onlyOwner | | 🛡️ | **P19 — 未使用 SafeERC20** | 🟡 中危 | 未检查返回值的直接转账 | | ⏰ | **P20 — 时间戳依赖** | 🟡 中危 | 关键逻辑使用了 `block.timestamp` | ## 🏗️ 架构 ``` flowchart TB subgraph "🪙 Token Discovery Layer" A1[🪙 CoinGecko API
15K+ tokens] --> D[🗄️ Token Registry
Dedup + Incremental] A2[🧾 RPC Event Logs
eth_getLogs Transfer] --> D A3[🔭 Explorer APIs
Etherscan/Blockscout] --> D A4[📚 Known Token Lists
Curated] --> D A5[🦎 DexScreener Boosts
Real-time trending] --> D A6[🦙 DeFiLlama Coin List
500K+ entries] --> D end subgraph "🔍 Scanning Pipeline" D --> E[📡 Source Fetcher
Etherscan/Blockscout/RPC] E --> F[🔬 Static Analyzer
20 Plagues Engine] F --> G[🎯 Pattern Matcher
Regex + Function Sig + AST] end subgraph "🚩 Reporting Layer" G --> H{Threat Found?} H -->|🔴 Critical| I[🚨 Red Flag Issue] H -->|🟡 High| J[⚠️ Advisory Issue] H -->|🟢 Clean| K[📋 Registry Update] I & J & K --> L[📊 Dashboard + Badges] end subgraph "⏰ Schedule" M1[🌅 Daily 08:00 UTC
Cross-Chain Vuln Scan] --> E M2[⚡ Hourly RPC Scan
New token discovery] --> D M3[📅 Weekly Full Scan
All 15K+ tokens] --> E end subgraph "🧠 Self-Evolution" N[🆕 Community Pattern PR] --> O[🧪 CI Validation] O -->|✅ Pass| P[➕ Auto-register Pattern] P --> F end ``` ### 数据流 ``` User / Time Trigger │ ▼ ┌──────────────────────┐ ┌────────────────────┐ ┌──────────────────┐ │ Token Discovery │────▶│ Token Registry │────▶│ Scan Engine │ │ (6 sources, dedup) │ │ (persistent JSON) │ │ (20 patterns) │ └──────────────────────┘ └────────────────────┘ └──────────────────┘ │ ▼ ┌──────────────────────┐ ┌────────────────────┐ ┌──────────────────┐ │ Update README │◀────│ Create GitHub │◀────│ Classify │ │ + Registry │ │ Issue (if vuln) │ │ Severity │ └──────────────────────┘ └────────────────────┘ └──────────────────┘ ``` ## 🚦 快速开始 ### 1. 提交合约 打开一个[合约提交 Issue](https://github.com/Lord1Egypt/MaatEye/issues/new?template=submit_contract.yml) 并附上合约地址。 ### 2. 在本地运行 ``` # Clone git clone https://github.com/Lord1Egypt/MaatEye.git cd MaatEye # 安装 pip install -r requirements.txt # 扫描单个合约 python -m scanner.main scan --address 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18 # 扫描多个 python -m scanner.main scan --file contracts.txt ``` ### 3. Token 注册表命令 ``` # 从 CoinGecko 导入代币 (15K+ 代币) python -m scanner.main tokens import --coingecko # 从 RPC 事件日志导入 (实时) python -m scanner.main tokens import --rpc # 显示 registry 统计信息 python -m scanner.main tokens stats # 列出新发现的代币 python -m scanner.main tokens new # 导出完整 registry python -m scanner.main tokens export --format json ``` ### 4. 扫描链 ``` # 列出所有支持的链 python -m scanner.main chains # 扫描 BNB Chain 上的顶级代币 python -m scanner.main scan-chain bnb --count 50 --format markdown # 扫描所有 24 条 EVM 链 python -m scanner.main scan-all --tokens-per-chain 20 --format json --output cross_chain.json # 专门从 registry 扫描 python -m scanner.main scan-registry --chain ethereum --limit 100 ``` ## 🌐 支持的链 (24 种 EVM) MaatEye 使用来自 [publicnode.com](https://publicnode.com) 的免费公共 RPC endpoint 扫描 **24 条兼容 EVM 的区块链**。 | # | 链 | Chain ID | Token | 发现来源 | |---|-------|----------|-------|-------------------| | 🔵 | **Ethereum** | 1 | ETH | 🪙🧾🔭📚 | | 🟡 | **BNB Chain** | 56 | BNB | 🪙🧾🔭📚 | | 🟣 | **Polygon** | 137 | MATIC | 🪙🧾🔭📚 | | 🔷 | **Base** | 8453 | ETH | 🪙🧾🔭📚 | | 🌀 | **Arbitrum One** | 42161 | ETH | 🪙🧾🔭📚 | | 🔴 | **Optimism** | 10 | ETH | 🪙🧾🔭📚 | | 🔺 | **Avalanche C-Chain** | 43114 | AVAX | 🪙🧾🔭📚 | | ⬛ | **Linea** | 59144 | ETH | 🪙🔭📚 | | 📜 | **Scroll** | 534352 | ETH | 🪙🔭📚 | | 💥 | **Blast** | 81457 | ETH | 🪙🔭📚 | | 🦉 | **Gnosis** | 100 | xDAI | 🪙🔭📚 | | 🌿 | **Celo** | 42220 | CELO | 🪙🔭📚 | | 🌕 | **Moonbeam** | 1284 | GLMR | 🪙🔭📚 | | 🏛 | **Metis** | 1088 | METIS | 🪙🔭📚 | | 🟨 | **opBNB** | 204 | BNB | 🪙🔭📚 | | 💓 | **PulseChain** | 369 | PLS | 🪙🔭📚 | | ⚙️ | **Mantle** | 5000 | MNT | 🪙🔭📚 | | 🥁 | **Taiko** | 167000 | ETH | 🪙🔭📚 | | 🐻 | **Berachain** | 80094 | BERA | 🪙🔭📚 | | 🌊 | **Soneium** | 1868 | ETH | 🪙🔭📚 | | 🦄 | **Unichain** | 130 | ETH | 🪙🔭📚 | | ⬜ | **Fraxtal** | 252 | frxETH | 🪙🔭📚 | | 🌶 | **Chiliz** | 88888 | CHZ | 🪙🔭📚 | | ⚡ | **Sonic** | 146 | S | 🪙🔭📚 | **Token 发现来源图例：** 🪙=CoinGecko 🧾=RPC 日志 🔭=浏览器 📚=已知列表 ## 🧪 项目状态 | 里程碑 | 状态 | 版本 | |-----------|--------|---------| | 🏗️ 仓库结构与 CI/CD | ✅ 完成 | v0.1 | | 🔴 20 场灾难模式 | ✅ 完成 | v0.2 | | 🌐 支持 24 条 EVM 链 | ✅ 完成 | v0.3 | | 📅 每日跨链扫描 | ✅ 完成 | v0.3 | | 🚩 自动红旗标记 Issues | ✅ 完成 | v0.3 | | 🪙 CoinGecko Token 发现 | ✅ 完成 | v0.4 | | 🧾 RPC 事件日志发现 | ✅ 完成 | v0.4 | | 🗄️ 持久化 Token 存储 | ✅ 完成 | v0.4 | | 📊 Token 注册表 CLI | ✅ 完成 | v0.4 | | 🌐 GitHub Pages 仪表板 | 🚀 进行中 | v0.6 | | 🔬 Slither 集成 | 📅 计划中 | v0.7 | | 🔥 可利用性评分 | 📅 计划中 | v0.8 | | 📬 Telegram/Discord 警报 | 📅 计划中 | v0.9 | | 🌉 非 EVM 支持 | 📅 计划中 | v1.0 | | 🌐 Web 仪表板 | 📅 计划中 | v1.0 | ## 📜 许可证 MIT — 对所有人免费。开源。社区所有。 ## ⚠️ 免责声明 **MaatEye 仅用于防御/教育目的。**它分析公开可用的合约源代码并识别潜在漏洞。用户有责任遵守所有适用的法律和法规。作者不对滥用行为承担责任。 **所有扫描均为只读静态分析。**我们： - ❌ 绝不发送交易 - ❌ 绝不部署合约 - ❌ 绝不利用漏洞 - ✅ 仅从浏览器和 RPC 读取公开数据 ## 🏛️ 玛阿特 (Ma'at) 的哲学

由 Lord1Egypt 用 ❤️ 和 🔥 打造
⚖️ 愿您的合约在玛阿特的羽毛上保持平衡 ⚖️

标签：EVM, Web3安全, 区块链, 智能合约, 逆向工具