rugpullnet/solana-rug
GitHub: rugpullnet/solana-rug
开源的 Solana 代币安全分析工具，通过 13 项链上检查自动检测「抽地毯」骗局并输出安全评分。
Stars: 7 | Forks: 10
# Solana Rug Guard $RUG
[](https://github.com/rugpullnet/solana-rug/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](LICENSE)
**针对 Solana 代币和钱包的 13 项链上抽地毯（rug-pull）检测方案。无需付费 API。无需注册。只需一个 Python 脚本和一个 Hermes 技能。**
你可以将其作为一次性 CLI 针对任何代币或钱包运行。或者将其作为 Hermes Agent 技能安装，并用自然语言提问：*"Hey Hermes, is this token safe?"* 每一项检查都是确定性的 —— 相同的输入总是产生相同的分数，并附带完整的详细原因。
## 安装与入门
### 前置条件
- Python 3.11+
- [Hermes Agent](https://hermes-agent.nousresearch.com)（可选 —— CLI 可独立运行）
- 无需 API 密钥。本工具使用公共 Solana RPC 和免费的 DexScreener API。
### 选项 A：作为 Hermes 技能安装（推荐）
```
# 来自 Hermes Agent repo：
hermes skills install official/blockchain/solana-rug
# 或从本地 checkout：
cd optional-skills/blockchain/solana-rug/
hermes skills install ./SKILL.md
```
然后用自然语言提问：
```
"Is token DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 safe?"
"Rug-check F4J5LKyEQraMem8nspPAzwHXaaKMMDsxyt7GUK94pump"
"Scan wallet 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM for risky tokens"
```
### 选项 B：独立运行 CLI
```
# 单个文件 — 无需安装（来自 GitHub Releases）
curl -OL https://github.com/rugpullnet/solana-rug/releases/latest/download/rugguard.py
python3 rugguard.py token DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 --md
```
```
# 或 clone 该 repo
git clone https://github.com/rugpullnet/solana-rug.git
cd solana-rug
python3 scripts/rugguard.py --help
```
```
# 或通过 PyPI 进行 pip install（可信来源）
pip install solana-rug
solana-rug token DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
```
### 验证是否生效
```
python3 rugguard.py token DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 --json
```
预期结果：BONK 返回 `safety_score: 100`，零警告，市场数据显示在 Meteora 上拥有 $682k 流动性。
## 使用说明
### 代币分析
```
# JSON output（默认）— 通过 jq 管道传输
python3 rugguard.py token
# 易读的 Markdown report
python3 rugguard.py token --md
# 完整示例
python3 rugguard.py token DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 --md
```
JSON 输出包含带有 DexScreener 扩展数据的 `market_data` 块：
```
{
"safety_score": 100,
"risk_level": "LOW",
"flags": {
"mint_authority_active": false,
"freeze_authority_active": false,
"sniper_detected": false,
"suspicious_name": false,
"sub_penny_price": false,
"deployer_can_crash_price": false
},
"market_data": {
"dex": "meteora",
"liquidity_usd": 682156.92,
"volume_24h": 936.68,
"price_usd": 0.000004892,
"price_change_24h": -2.92,
"txns_24h": 212
}
}
```
### 钱包扫描
```
python3 rugguard.py wallet
```
扫描钱包持有的所有 SPL 代币。对于每种具有实际余额的代币，检查其铸币权限。返回按安全分数排序的风险代币优先列表（分数最低的排在最前）。
### 监控模式、历史记录和 Webhooks
```
# 执行一次 check，存储一条 SQLite history row，然后退出
python3 rugguard.py watch --iterations 1
# 每 60 秒 continuous monitoring
python3 rugguard.py watch --interval 60
# 每当 score/flags/warnings 发生更改，或每当 safety <= 70 时 alert
python3 rugguard.py watch --threshold 70 --webhook https://example.com/webhook
```
监控模式将每次运行存储在本地 SQLite 数据库中，并在每次检查时打印一个 JSON 事件：
```
{
"mint": "...",
"safety_score": 79,
"risk_level": "LOW",
"changed": true,
"reasons": ["score changed 82 -> 79"],
"history_db": "~/.solana-rug/history.sqlite3"
}
```
Webhook 负载使用相同的 JSON 事件结构，且仅在触发更改/阈值警报时发送。
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | 覆盖 RPC 端点。在生产环境中建议设置为私有节点 以提高可靠性。 |
| `SOLANA_RUG_HISTORY_DB` | `~/.solana-rug/history.sqlite3` | 用于监控模式分数历史的 SQLite 路径。 |
| `SOLANA_RUG_WEBHOOK_URL` | 空 | 用于监控模式警报的可选 webhook URL。 |
| `SOLANA_RUG_WATCH_INTERVAL` | `60` | 默认监控间隔（以秒为单位）。 |
| `SOLANA_RUG_HISTORY_RETENTION_DAYS` | `90` | 自动清理超过指定天数的旧历史记录。 |
| `SOLANA_RUG_LIQ_THRESHOLD_CRITICAL` | `1000` | 流动性低于此金额（美元）被评为严重风险 (5分)。 |
| `SOLANA_RUG_LIQ_THRESHOLD_HIGH` | `5000` | 流动性低于此金额被评为高风险 (4分)。 |
| `SOLANA_RUG_LIQ_THRESHOLD_MEDIUM` | `20000` | 流动性低于此金额被评为中等风险 (3分)。 |
| `SOLANA_RUG_LIQ_THRESHOLD_LOW` | `100000` | 流动性低于此金额被评为低风险 (1分)。 |
| `SOLANA_RUG_LIQ_VOL_RATIO_WARNING` | `15` | 交易量/流动性比率高于此值将触发洗盘警告 (+3分)。 |
| `SOLANA_RUG_LIQ_VOL_RATIO_MIN` | `0.05` | 交易量/流动性比率低于此值将标记为不活跃/死亡池 (+3分)。 |
| `WALLET_SCAN_WORKERS` | `4` | 钱包代币扫描的最大并发限制 (最大 10)。 |
## 架构
### 数据流
```
User Input (mint address)
│
▼
┌─────────────────────┐
│ fetch_token_meta │──► Solana RPC: getAccountInfo (jsonParsed)
│ (on-chain data) │──► Token-2022 extension detection
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ check_authorities │──► Mint authority, freeze authority, token program
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ fetch_token_holders│──► RPC: getTokenLargestAccounts
│ │──► Falls back to DexScreener tx-count estimates
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ detect_liquidity │──► RPC: getProgramAccounts (Raydium, pumpSwap, Orca)
│ │──► Falls back to DexScreener for pool data
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ check_sniper_pat. │──► First 15 mint signatures → rapid-buy detection
│ estimate_token_age │──► Signature pagination + DexScreener fallback
│ check_suspicious │──► Name/symbol keyword blacklist
│ check_honeypot │──► Jupiter quote API (optional check)
│ compute_dump_risk │──► Deployer % vs pool liquidity
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ DexScreener enrich │──► Price, volume, liquidity, 24h change, tx count
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Scoring Engine │──► 13 risk factors → 0-100 safety score
│ + Markdown/JSON │──► Human-readable report or structured data
└─────────────────────┘
```
### 目录结构
```
solana-rug/
├── SKILL.md # Hermes skill definition (docs all 13 checks)
├── scripts/
│ └── rugguard.py # Core engine (~1470 lines, stdlib-only)
├── solana_rug/ # PyPI package wrapper
│ ├── __init__.py
│ └── py.typed
├── pyproject.toml
├── tests/
│ └── test_checks.py # 20 tests (13 unit + 7 blockchain integration)
├── README.md
├── CONTRIBUTING.md
└── LICENSE # MIT
```
### 13 项风险因素
每个因素对总分贡献零分或更多分。总风险越高 = 安全分数越低。
| # | 因素 | 最高分 | 捕获内容 | 数据来源 |
|---|--------|:---:|-----------------|-------------|
| 1 | Mint 权限 | 15 | 开发者可以无限增发新代币 | RPC |
| 2 | 冻结权限 | 5 | 开发者可以冻结账户 | RPC |
| 3 | LP 锁定/销毁 | 15 | LP 代币可被抽走，不存在流动性池 | RPC + DexScreener |
| 4 | 流动性规模 | 5 | 池子不足 $20k → 极高的价格滑点 | DexScreener |
| 5 | 持有者集中度 | 10 | 前 10 名钱包拥有 >50% 的供应量 | RPC + DexScreener |
| 6 | 开发者风险 | 5 | 开发者持有 >15% 的供应量 | RPC |
| 7 | 代币存在时间 | 5 | 存在不到 7 天 → 统计学上风险更高 | DexScreener |
| 8 | 铸币历史 | 5 | 开发者在发布后铸造了更多代币 | RPC |
| 9 | 蜜罐 | 10 | 卖出模拟失败 | Jupiter API |
| 10 | 狙击机器人 | 10 | 机器人在前 20 秒内买入 | RPC 签名分析 |
| 11 | 可疑名称 | 5 | 名称包含 "rug"、"scam"、"ponzi" 等 | 链上 + DexScreener |
| 12 | 不足一分价格 | 5 | 年轻或流动性差的代币价格 < $0.0001 | DexScreener |
| 13 | 部署者砸盘风险 | 5 | 开发者可能通过抛售导致价格暴跌 | DexScreener + RPC |
### 风险如何评分
每项检查都是独立且确定性的。总风险分**没有上限** —— 每个指标都达到最大值的代币将获得 0/100 的评分。这 13 个因素分为：
- **3 项链上结构性检查**（铸币权限、冻结权限、LP 锁定/销毁）—— 典型的抽地毯攻击向量
- **4 项市场健康度检查**（流动性规模、持有者集中度、存在时间、铸币历史）—— 可持续性信号
- **3 项行为检查**（蜜罐、狙击机器人、名称污名）—— 对抗性模式检测
- **3 项头寸检查**（开发者风险、不足一分价格、部署者砸盘风险）—— 谁持有什么以及这意味着什么
分数段：
| 分数 | 风险 | 含义 |
|:-----:|:----:|---------|
| 80-100 | 低 | 链上机制干净。仅存在标准 DeFi 风险。 |
| 50-79 | 中等 | 存在某些风险因素。请检查标记的警告。 |
| 20-49 | 高 | 存在多个危险信号。很可能是一个高风险代币。 |
| 0-19 | 严重 | 有强烈证据表明存在恶意设置。 |
### 数据来源（按优先顺序）
1. **Solana 公共 RPC** —— 铸币账户、代币持有者、签名、程序账户。使用轮询回退机制在 4 个公共端点上重试。
2. **DexScreener API** —— 当 `getProgramAccounts` 受到速率限制时提供真实的池子数据。提供价格、流动性、交易量、交易对信息和创建时间。
3. **Jupiter 报价 API** —— 可选的蜜罐检查。模拟买入/卖出以检测交易限制。
所有调用都在内存中缓存，TTL 为 5 分钟，以避免多余的网络请求。
## 支持
Solana Rug Guard 是免费、开源的 MIT 软件。没有付费墙，无需 API 密钥，无需注册。
或者在 DexScreener 上查看当前图表：
```
https://dexscreener.com/solana/4sHKYieWsGtrmtqjdXPRzSdVywXZ1jUQGbM8QbkBXMB9
```
每一次购买都会为池子增加流动性，并帮助维持本项目的可持续发展。
*MIT 许可证 · 为 Hermes Agent 构建 · 无需付费 API*
标签：DeFi, Hermes Agent, Python, Rug Pull检测, Solana, Web3安全, 代币安全审计, 加密货币风险评估, 区块链安全, 去中心化金融, 实时处理, 开源安全工具, 无后门, 智能合约分析, 逆向工程平台, 钱包风险扫描, 链上数据分析, 防撤资诈骗