h30s/PolkaSentinel
GitHub: h30s/PolkaSentinel
首个在 Polkadot 上运行的完全链上 AI 安全引擎，通过决策树分类器实时检测并拦截 DeFi 攻击，而非仅生成评分或事后告警。
Stars: 0 | Forks: 0
# PolkaSentinel
**首个 Polkadot 链上交易卫士**
一个实时安全引擎，利用决策树分类器检测并拦截 DeFi 漏洞利用 —— 已在 Polkadot Hub TestNet 实时部署。
## 实时部署 (Polkadot Hub TestNet — Chain ID: 420420417)
| 合约 | 地址 |
|---|---|
| **GuardianProxy** | `0xeEC1F62F2E03908f47Eb4d5fE7281fD25d387480` |
| **ProtectedVault** | `0x0927a3c71cE3D3DFf2886236efA4622C2de31ECe` |
| **VulnerableVault** | `0x02cDC030bd8917522f339F7faD40FCE2aaE990ee` |
| **ReentrancyAttacker** | `0xb225669E1B22C1296CA291cA17Eb45BCB54d47cd` |
**网络：** Polkadot Hub TestNet
**RPC：** `https://services.polkadothub-rpc.com/testnet`
**部署者：** `0x9574eB0855781c02f64C562ffF7064d2C6047DF8`
**部署日期：** 2026年3月19日
### 实时测试网交易证明
所有交易均在 Polkadot Hub TestNet (Chain ID: 420420417) 上执行：
| 操作 | 交易哈希 | 结果 |
|---|---|---|
| 为漏洞金库注资 (10 ETH) | `0x55169a07a02971c8d234498f8d412a890e86337b0176a04ae5106ee80b060796` | 成功 |
| 为受保金库注资 (10 ETH) | `0xf1eecb7caae2aff6c1898afa7a9e1ce8fb595189b7ae1012fdfb28fd31ab727c` | 成功 |
| 正常提款 (受保) | `0x0760c86903931318e7a096a2a1e4c3abb18faef70bedd4303373336fcf5c10c5` | SAFE (安全) |
| 正常提款 (漏洞) | `0xef8ff1c80bb1913db36482206bd63368bfa513631ec9eec158627cc0f279a5aa` | 成功 |
| **重入攻击 → 漏洞金库** | `0x8b75df8848bcdc8a9da2f946b533f1418e040e8d65e2035a25756dbb72149e45` | **被清空: 9→5 ETH** |
| **重入攻击 → 受保金库** | `0x0956215ff1a8728c973214b5b3e06b6c753f3403f29fe1cf704fc16a2f973d72` | **已拦截: 9→9 ETH** |
| 攻击后正常提款 | `0x6ac45439450307158ccff6feb135ee0e64523b5b8c0be030af9a2fe16c467d6f` | SAFE (安全) — 金库仍可操作 |
### 实时 Gas 报告 (在 Polkadot Hub TestNet 上测量)
| 操作 | Gas 消耗 |
|---|---|
| 受保提款 | 107,314 gas |
| 无保提款 | 1,492 gas |
| Sentinel 开销 | 105,822 gas |
| 攻击漏洞金库 | 91,002 gas |
| 攻击受保金库 (已拦截) | 151,227 gas |
## 问题
DeFi 协议因漏洞利用已损失 **超过30亿美元**。当前的安全工具存在以下问题：
- **审计** — 在部署前发现 Bug，但在运行时无能为力
- **链下机器人** — 在确认后检测攻击，无法预防
- **AI 评分器** — 生成评分，但不执行任何强制措施
**目前不存在能够在运行时检测并拦截漏洞利用、完全链上且零链下依赖的解决方案。**
## 解决方案
PolkaSentinel 是一个 **Guardian Modifier**，任何 DeFi 协议都可以将其添加到敏感函数中。它提供两层保护：
**第一层 — 内置重入保护：**
`guard()` 函数追踪每个调用者的调用深度。如果受保函数的外部调用重新进入 `guard()`，它会检测到 `_guardDepth > 0` 并 **立即强制回滚** —— 机制与 OpenZeppelin 的 ReentrancyGuard 相同，但已内置到卫士中。
**第二层 — 多信号威胁分类：**
GuardianProxy 从链上数据（发送者合约分析、金库抽干比例、单块提款追踪、首次出现时间）收集 **10 个实时特征**，并运行决策树分类器来检测仅靠 ReentrancyGuard 无法识别的模式：
- 本区块部署的新合约试图抽干 >30% 的金库 → CRITICAL (危急)
- 已知合约试图抽干 >70% → SUSPICIOUS (可疑)
- EOA 抽干 >90% → SUSPICIOUS (可疑)
两层均在链上运行，零链下依赖。
### 验证
我们在 Polkadot Hub TestNet 上部署了两个完全相同的金库 —— 一个由 PolkaSentinel 保护，另一个没有 —— 并使用相同的重入漏洞攻击了两者：
```
╔══════════════════════════════════════════════════════╗
║ Vulnerable Vault: 10.0 ETH → 6.0 ETH (DRAINED) ║
║ Protected Vault: 10.0 ETH → 10.0 ETH (SAFE) ║
╠══════════════════════════════════════════════════════╣
║ Attack: REAL. Protection: REAL. On-chain proof. ║
╚══════════════════════════════════════════════════════╝
```
## 架构
```
User Transaction
│
▼
┌─────────────────────────────────────────────┐
│ SOLIDITY LAYER │
│ │
│ ProtectedVault ──► GuardianProxy │
│ (onlyGuarded) (collects 10 features) │
│ │ │
│ ═══════════════════════╪══════════════════ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ DECISION TREE CLASSIFIER │ │
│ │ 13-node hand-crafted tree │ │
│ │ → SAFE / SUSPICIOUS / CRITICAL │ │
│ └──────────────────────────────────────┘ │
│ │
│ Result: CRITICAL? → revert (funds safe) │
│ SAFE? → execute normally │
└─────────────────────────────────────────────┘
PVM Rust Engine (identical logic, ready for
cross-VM deployment when PVM↔EVM calling is stable)
```
## 收集的特征 (全部真实，全部链上)
| # | 特征 | 来源 | 原因 |
|---|---|---|---|
| 0 | `reentrancy_flag` | Storage 计数器 | 检测重入 |
| 1 | `withdraw_amount` | 函数参数 | 交易值信号 |
| 2 | `calldata_size` | `msg.data.length` | 异常 calldata = 可疑 |
| 3 | `function_selector` | `bytes4(msg.data)` | 匹配已知危险选择器 |
| 4 | `sender_is_contract` | `msg.sender.code.length` | 95%+ 的漏洞利用使用合约 |
| 5 | `sender_first_seen_gap` | Storage mapping | 新实体风险更高 |
| 6 | `withdrawals_this_block` | 单块计数器 | 多次提款 = 重入信号 |
| 7 | `cumulative_value_this_block` | 单块累加器 | 单块总抽干量 |
| 8 | `vault_balance_ratio` | `amount * 1000 / balance` | 正在被抽干的金库百分比 |
| 9 | `contract_age` | `block.number - deployBlock` | 年轻合约风险更高 |
## 技术栈
| 层级 | 技术 |
|---|---|
| Smart Contracts | Solidity 0.8.24, OpenZeppelin (Pausable, AccessControl, ReentrancyGuard) |
| Security Engine | 13节点决策树分类器 (Solidity 链上 + Rust PVM-ready) |
| Testing | Hardhat, ethers.js, Chai (30 Solidity + 15 Rust = 45 tests) |
| Frontend | React 18, Vite, TailwindCSS, ethers.js v6 |
| Deployment | Polkadot Hub TestNet (Chain ID: 420420417) |
## 赛道
**Track 2: PVM Smart Contracts** — Polkadot Solidity Hackathon 2026
- **PVM 实验** — 为 PVM 编译的 Rust 决策树引擎 (逻辑与 Solidity 分类器一致)
- **Polkadot 原生资产** — 监控并保护原生 PAS 代币转移
- **原生功能** — 为 PVM 跨 VM 集成设计
**OpenZeppelin 赞助赛道** — 使用 Pausable, AccessControl, ReentrancyGuard
## 项目结构
```
polkasentinel/
├── contracts/
│ ├── GuardianProxy.sol # Core: feature collection + classifier + enforcement
│ ├── ProtectedVault.sol # Demo vault WITH PolkaSentinel protection
│ ├── VulnerableVault.sol # Demo vault WITHOUT protection (for proof)
│ ├── interfaces/
│ │ └── IPolkaSentinel.sol # Public interface
│ ├── libraries/
│ │ └── SentinelProtected.sol # Integration abstract contract
│ └── test/
│ └── ReentrancyAttacker.sol # Real reentrancy exploit contract
├── rust-engine/
│ ├── src/
│ │ ├── lib.rs # Entry point + ABI decoding
│ │ ├── classifier/
│ │ │ └── decision_tree.rs # 13-node decision tree (identical to Solidity)
│ │ └── signatures/
│ │ └── mod.rs # Attack signature documentation
│ └── Cargo.toml
├── frontend/ # React dashboard + attack demo
├── scripts/
│ ├── deploy.js # Deploy all contracts
│ └── demo-attack.js # Full attack demo with proof-of-value
├── test/
│ └── PolkaSentinel.test.js # 30 tests including side-by-side proof
└── hardhat.config.js
```
## 快速开始
### 前置条件
- Node.js >= 18
- Rust >= 1.70
### 安装与测试
```
# 克隆
git clone https://github.com/pnkr01/polkasentinel.git
cd polkasentinel
# 安装依赖
npm install
# 运行 30 个 Solidity 测试
npx hardhat test
# 运行 15 个 Rust 引擎测试
cd rust-engine && cargo test && cd ..
# 运行完整攻击演示 (本地部署 + 攻击)
npx hardhat run scripts/demo-attack.js
# 启动前端
cd frontend && npm install && npm run dev
```
### 部署到 Polkadot Hub TestNet
```
# 配置 .env
cp .env.example .env
# 添加你的 PRIVATE_KEY
# 部署
npx hardhat run scripts/deploy.js --network polkadotHub
```
## 集成 (3 行代码)
Polkadot Hub 上的任何 DeFi 协议都可以集成 PolkaSentinel：
```
import {SentinelProtected} from "./SentinelProtected.sol";
contract MyVault is SentinelProtected {
constructor(address sentinel) SentinelProtected(sentinel) {}
function withdraw(uint256 amount) external onlyGuarded(amount) {
// Your logic here — only runs if PolkaSentinel says SAFE
}
}
```
## 测试结果
```
30 passing (Solidity)
15 passing (Rust)
Gas Report:
Protected withdrawal: 172,664 gas
Unprotected withdrawal: 40,143 gas
Sentinel overhead: 132,521 gas
classifyView (pure): 24,600 gas
```
## 许可证
MIT
标签：Apex, CISA项目, DeFi安全, DNS 反向解析, GuardianProxy, Polkadot, TGT, Web报告查看器, 人工智能, 代币保险库, 决策树分类器, 区块链安全, 去中心化金融, 反欺诈, 可视化界面, 威胁拦截, 实时交易监控, 攻防演练, 智能合约审计, 智能合约防火墙, 机器学习, 波卡生态, 用户模式Hook绕过, 网络安全, 自定义脚本, 重入攻击防护, 链上防火墙, 隐私保护