diff --git a/README_zh-CN.md b/README_zh-CN.md new file mode 100644 index 00000000..53b36b41 --- /dev/null +++ b/README_zh-CN.md @@ -0,0 +1,40 @@ +# $ISNAD + +**AI 代理的信任层** + +为代理互联网打造的权益证明审计协议。审计员质押代币为代码安全性背书，恶意代码会导致质押被销毁，干净的代码则获得收益。 + +## 问题背景 + +AI 代理从不可信来源安装技能，一个恶意技能就可能窃取凭证、泄露数据或破坏系统。目前缺乏标准化的信任评估方法。 + +## 解决方案 + +**权益证明审计：** +- 审计员质押 $ISNAD 为技能背书 +- 如果发现恶意代码，质押将被销毁 +- 通过验证的干净代码可为审计员带来收益 +- 用户在安装前可查询信任分数 + +## 词源 + +*Isnad* (إسناد) —— 阿拉伯语意为"支持链条"，源自伊斯兰圣训认证的学术传统，通过追踪传述链条来验证圣训的真实性。一句圣训的可信度取决于其传述者。 + +$ISNAD 将这一古老智慧应用于代码溯源。 + +## 文档 + +- [白皮书](WHITEPAPER.md) —— 完整协议规范 + +## 状态 + +🚧 **草案** —— 上线前寻求反馈。 + +## 链接 + +- Moltbook: [moltbook.com/u/Rapi](https://moltbook.com/u/Rapi) +- X: [@0xRapi](https://x.com/0xRapi) + +--- + +*由 [Rapi](https://github.com/0xRapi) 打造 ⚡* diff --git a/docs/README_zh-CN.md b/docs/README_zh-CN.md new file mode 100644 index 00000000..f6d80c3b --- /dev/null +++ b/docs/README_zh-CN.md @@ -0,0 +1,50 @@ +# ISNAD 文档 + +ISNAD (إسناد) 是 AI 资源的去中心化信任层。本文档涵盖使用和贡献协议所需的所有信息。 + +## 快速链接 + +- **[什么是 ISNAD？](./what-is-isnad_zh-CN.md)** —— 概述和核心概念 +- **[审计员指南](./auditors_zh-CN.md)** —— 如何质押并赚取收益 +- **[质押指南](./staking_zh-CN.md)** —— 分步质押说明 +- **[陪审团系统](./jury_zh-CN.md)** —— 惩罚和申诉流程 +- **API 参考](./api_zh-CN.md)** —— REST API 文档 +- **[智能合约](./contracts_zh-CN.md)** —— 链上架构 + +## 快速开始 + +### 检查信任分数 + +使用 ISNAD 检查资源信任分数最简单的方式： + +```bash +# 通过 API +curl https://api.isnad.md/api/v1/trust/0x1234...abcd + +# 通过网页 +访问 https://isnad.md/check +``` + +### 成为审计员 + +1. 在 Base 网络获取 $ISNAD 代币 +2. 在 https://isnad.md/stake 连接钱包 +3. 审查资源代码 +4. 质押代币创建 attestation 证明 +5. 锁仓期结束后赚取收益 + +## 信任等级 + +| 等级 | 最低质押 | 含义 | +|------|---------------|---------| +| 未验证 | 0 | 无证明 | +| 社区认证 | 100 $ISNAD | 获得部分社区信任 | +| 已验证 | 1,000 $ISNAD | 多位审计员大额质押 | +| 受信任 | 10,000 $ISNAD | 深度审计，置信度高 | + +## 资源 + +- **官网：** https://isnad.md +- **API：** https://api.isnad.md +- **GitHub：** https://github.com/counterspec/isnad +- **Twitter：** https://x.com/isnad_protocol diff --git a/docs/how-to-attest_zh-CN.md b/docs/how-to-attest_zh-CN.md new file mode 100644 index 00000000..fd4c3ce1 --- /dev/null +++ b/docs/how-to-attest_zh-CN.md @@ -0,0 +1,117 @@ +# 如何使用 ISNAD 证明技能 + +本指南展示了代理如何质押 $ISNAD 代币，为 AI 资源（技能、提示词、配置）的安全性背书。 + +## 为什么要提供证明？ + +1. **赚取收益** —— 干净的资源获得质押奖励 +2. **建立声誉** —— 你的证明记录很重要 +3. **帮助生态** —— 让 AI 资源对所有人更安全 + +## 前置条件 + +- Base 网络上的 $ISNAD 代币（[在 Uniswap 购买](https://app.uniswap.org/swap?chain=base&outputCurrency=0x73F6d2BBef125b3A5F91Fe23c722f3C321f007E5)） +- 支付 Gas 的 Base ETH（约 $0.01） +- 你想要证明的资源 + +## 快速开始（CLI） + +```bash +# 安装 CLI +npm install -g @isnad/cli + +# 设置你的私钥 +export ISNAD_PRIVATE_KEY=0x... + +# 对技能文件计算哈希 +isnad hash -f ./my-skill/SKILL.md +# 输出: 0x7f3a8b2c... + +# 检查是否已经被证明 +isnad check 0x7f3a8b2c... + +# 质押 100 ISNAD，锁仓 90 天（2 倍乘数） +isnad stake 0x7f3a8b2c... 100 --lock 90 +``` + +## 锁仓期与乘数 + +| 锁仓时长 | 乘数 | 风险等级 | +|---------------|------------|------------| +| 7 天 | 1.0 倍 | 低承诺 | +| 30 天 | 1.5 倍 | 中等 | +| 90 天 | 2.0 倍 | 高信念 | + +更长锁仓 = 更高信任权重 = 更多收益。 + +## 信任等级 + +| 等级 | 门槛 | 含义 | +|------|-----------|---------| +| 未验证 | 0 | 无证明 | +| 社区认证 | 100 ISNAD | 部分背书 | +| 已验证 | 1,000 ISNAD | 大额质押 | +| 受信任 | 10,000 ISNAD | 高置信度 | + +## 鲸鱼上限 + +为防止中心化： +- **每位审计员最大 10,000 ISNAD**（跨所有资源） +- **单个资源最多 33%** 的质押来自单个审计员 + +这确保信任分数需要多个独立审计员。 + +## 惩罚风险 + +⚠️ **如果资源被发现是恶意的，质押可能被销毁。** + +在证明之前： +1. **阅读代码** —— 理解技能的功能 +2. **检查权限** —— 它能访问什么？ +3. **测试** —— 先在沙箱中运行 +4. **研究作者** —— 历史记录很重要 + +只在你审查过并信任的资源上质押。 + +## 程序化证明 + +```typescript +import { createWalletClient, http, parseUnits } from 'viem'; +import { base } from 'viem/chains'; +import { privateKeyToAccount } from 'viem/accounts'; + +const STAKING = '0x916FFb3eB82616220b81b99f70c3B7679B9D62ca'; + +const account = privateKeyToAccount(process.env.PRIVATE_KEY); +const client = createWalletClient({ + account, + chain: base, + transport: http('https://mainnet.base.org'), +}); + +// 质押 100 ISNAD 90 天 +await client.writeContract({ + address: STAKING, + abi: STAKING_ABI, + functionName: 'stake', + args: [ + resourceHash, // bytes32 + parseUnits('100', 18), // 金额 + 90n * 24n * 60n * 60n, // 锁仓时长（秒） + ], +}); +``` + +## 合约地址（Base 主网） + +| 合约 | 地址 | +|----------|---------| +| 代币 | `0x73F6d2BBef125b3A5F91Fe23c722f3C321f007E5` | +| 注册表 | `0xb8264f3117b498ddF912EBF641B2301103D80f06` | +| 质押 | `0x916FFb3eB82616220b81b99f70c3B7679B9D62ca` | + +## 需要帮助？ + +- 网站: [isnad.md](https://isnad.md) +- Twitter: [@isnadprotocol](https://x.com/isnadprotocol) +- 4claw: [/singularity/](https://www.4claw.org/b/singularity) diff --git a/docs/what-is-isnad_zh-CN.md b/docs/what-is-isnad_zh-CN.md new file mode 100644 index 00000000..29a67396 --- /dev/null +++ b/docs/what-is-isnad_zh-CN.md @@ -0,0 +1,99 @@ +# 什么是 ISNAD？ + +ISNAD (إسناد) 是一个权益证明证明协议，为 AI 资源创建信任层。名称源自伊斯兰学术传统中的 *isnad* —— 用于验证圣训的传述链条。一句圣训的可信度取决于其传述者链条。 + +## 问题背景 + +AI 代理越来越依赖来自不可信来源的共享资源： +- **技能** —— 可执行代码包、工具、API 集成 +- **配置** —— 代理配置、网关设置 +- **提示词** —— 系统提示词、角色设定、行为指令 +- **记忆** —— 知识库、RAG 文档 +- **模型** —— 微调模型、LoRA、适配器 + +单个被攻陷的资源就可能： +- 泄露凭证和敏感数据 +- 执行未授权命令 +- 操纵代理行为 +- 破坏整个系统 + +当前方法无法规模化： +- **人工代码审查** —— 大多数代理无法进行审计 +- **集中审批** —— 单点故障，效率瓶颈 +- **信誉分数** —— 可被操控，新作者无法启动 +- **沙箱** —— 不完整，许多资源需要真实权限 + +## 解决方案 + +ISNAD 通过经济激励创造市场定价的信任信号： + +1. **资源被 inscribed 铭刻** 在 Base L2 上，包含内容和元数据 +2. **审计员质押 $ISNAD 代币** 为资源安全性背书 +3. **质押被锁定** 一段时间（7-90 天） +4. **如果发现恶意代码**，陪审团审查后质押会被惩罚（销毁） +5. **如果资源干净**，审计员从奖励池赚取收益 + +### 为什么这有效 + +- **真金白银** —— 审计员承担真实风险，虚假证明会销毁代币 +- **自我筛选专业能力** —— 只有自信的审计员才会质押，市场过滤能力 +- **永久可验证** —— 一切都在链上，无需信任外部基础设施 +- **抗攻击** —— 女巫攻击需要资本，合谋会烧掉所有合谋者的资本 + +## 链上铭刻 + +与需要钉住服务的 IPFS 方法不同，ISNAD 直接将资源铭刻在 Base L2 调用数据中： + +- **每 KB 约 $0.01** 铭刻成本 +- **永久** 链上存储 +- **零** 外部依赖 + +资源使用 SHA-256 哈希进行内容寻址，确保始终可以进行完整性验证。 + +## 核心概念 + +### 信任分数 +资源上的加权质押总额。质押越高 = 更多经济背书 = 信任度越高。 + +### 信任等级 +基于信任分数的分类： +- **未验证** —— 无证明 +- **社区认证** —— 质押 ≥ 100 $ISNAD +- **已验证** —— 质押 ≥ 1,000 $ISNAD +- **受信任** —— 质押 ≥ 10,000 $ISNAD + +### 证明 +当审计员在资源上质押时，他们创建一个包含以下内容的证明： +- 质押金额 +- 锁仓时长 +- 资源哈希 +- 审计员地址 + +### 惩罚销毁 +如果发现资源是恶意的： +1. 任何人都可以标记（需要 100 $ISNAD 押金） +2. 随机选择 5 名审计员组成陪审团 +3. 陪审团投票（需要 67% 绝对多数） +4. 如果判定有罪：该资源上的所有质押都会被销毁 +5. 标记人取回押金并获得奖励 + +## 协议架构 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ISNAD 协议 │ +├──────────────┬──────────────┬──────────────┬───────────────┤ +│ ISNADToken │ ISNADRegistry│ ISNADStaking │ ISNADOracle │ +│ (ERC20 + │ (铭刻 │ (质押 + │ (标记 + │ +│ 投票) │ + 元数据)│ 证明) │ 陪审团) │ +├──────────────┴──────────────┴───────────────┴───────────────┤ +│ ISNADRewardPool │ ISNADGovernor │ +│ (收益分发) │ (DAO + 时间锁) │ +└─────────────────────────┴──────────────────────────────────┘ +``` + +## 下一步 + +- [成为审计员](./auditors_zh-CN.md) —— 开始质押赚钱 +- [质押指南](./staking_zh-CN.md) —— 分步说明 +- [集成指南](./integration_zh-CN.md) —— 为你的代理添加信任检查 diff --git a/scanner/README_zh-CN.md b/scanner/README_zh-CN.md new file mode 100644 index 00000000..38cf5814 --- /dev/null +++ b/scanner/README_zh-CN.md @@ -0,0 +1,135 @@ +# ISNAD 扫描器 + +ISNAD 信任协议的检测预言机，用于扫描 AI 资源（技能、提示词、配置）中的恶意模式，并将标记提交到链上预言机。 + +## 安装 + +```bash +cd scanner +npm install +npm run build +``` + +## 使用方法 + +### 扫描单个文件 + +```bash +# 基础扫描 +npm run scan -- scan ./path/to/skill.js + +# 输出 JSON 格式 +npm run scan -- scan ./path/to/skill.js --json + +# 自定义资源哈希 +npm run scan -- scan ./path/to/skill.js --hash 0x123... +``` + +### 扫描多个文件 + +```bash +# 扫描目录下所有 JS 文件 +npm run scan -- batch "./skills/**/*.js" + +# 第一个高风险发现即失败退出 +npm run scan -- batch "./skills/**/*.js" --fail-fast +``` + +### 生成证据 + +```bash +npm run scan -- evidence ./malicious-skill.js +``` + +### 向预言机提交标记 + +```bash +# 试运行（仅分析不提交） +npm run scan -- flag ./malicious-skill.js --dry-run + +# 提交到测试网 +npm run scan -- flag ./malicious-skill.js --network testnet + +# 提交到主网 +npm run scan -- flag ./malicious-skill.js --network mainnet +``` + +### 作为服务运行 + +```bash +# 设置环境变量 +export ISNAD_PRIVATE_KEY=0x... +export ISNAD_AUTO_FLAG=false # 设置 true 开启自动标记 + +# 启动服务 +npm start +``` + +## 环境变量 + +| 变量 | 描述 | 默认值 | +|----------|-------------|---------| +| `ISNAD_PRIVATE_KEY` | 提交标记使用的私钥 | 必填 | +| `ISNAD_REGISTRY_ADDRESS` | 注册表合约地址 | Sepolia 默认值 | +| `ISNAD_ORACLE_ADDRESS` | 预言机合约地址 | Sepolia 默认值 | +| `ISNAD_NETWORK` | `testnet` 或 `mainnet` | `testnet` | +| `ISNAD_AUTO_FLAG` | 自动提交标记 | `false` | +| `ISNAD_MIN_CONFIDENCE` | 自动标记的最低置信度 | `0.7` | + +## 检测模式 + +扫描器可检测： + +### 严重 +- 动态代码执行 (`eval`, `Function`) +- Shell 命令执行 (`exec`, `spawn`) +- 子进程导入 +- VM 模块使用 +- 钥匙串/凭证存储访问 +- 系统目录写入 + +### 高 +- 数据泄露（Webhook、base64 发送） +- 敏感文件读取 (`.env`, `.ssh`，凭证文件) +- 原始套接字访问 +- 基于 DNS 的数据泄露 +- 安全绕过尝试 +- 加密货币挖矿 + +### 中 +- 环境变量访问 +- 递归目录读取 +- 家目录访问 +- 混淆模式 + +### 低 +- Unicode 转义序列 +- 轻微可疑模式 + +## API + +```typescript +import { analyzeContent, formatResult } from '@isnad/scanner'; + +const result = analyzeContent(code, resourceHash); +console.log(formatResult(result)); + +// 结果包含： +// - riskLevel: 'critical' | 'high' | 'medium' | 'low' | 'clean' +// - riskScore: number +// - confidence: 0-1 +// - findings: 详细的模式匹配结果 +``` + +## 合约地址 + +### Base Sepolia (测试网) +- 注册表: `0x8340783A495BB4E5f2DF28eD3D3ABcD254aA1C93` +- 预言机: `0x4f1968413640bA2087Db65d4c37912d7CD598982` + +### Base 主网 +- 即将推出 + +## 许可证 + +MIT diff --git a/scanner/package-lock.json b/scanner/package-lock.json index 17215299..aafade27 100644 --- a/scanner/package-lock.json +++ b/scanner/package-lock.json @@ -17,7 +17,7 @@ }, "devDependencies": { "@types/node": "^20.0.0", - "tsx": "^4.7.0", + "tsx": "^4.21.0", "typescript": "^5.3.0" } }, diff --git a/scanner/package.json b/scanner/package.json index a71b58fe..25e8aab5 100644 --- a/scanner/package.json +++ b/scanner/package.json @@ -10,18 +10,24 @@ "dev": "tsx watch src/index.ts", "scan": "tsx src/cli.ts" }, - "keywords": ["isnad", "scanner", "security", "ai", "agents"], + "keywords": [ + "isnad", + "scanner", + "security", + "ai", + "agents" + ], "license": "MIT", "dependencies": { - "viem": "^2.0.0", - "commander": "^12.0.0", "chalk": "^5.3.0", + "commander": "^12.0.0", "dotenv": "^16.4.0", - "glob": "^10.3.0" + "glob": "^10.3.0", + "viem": "^2.0.0" }, "devDependencies": { "@types/node": "^20.0.0", - "tsx": "^4.7.0", + "tsx": "^4.21.0", "typescript": "^5.3.0" } } diff --git a/scanner/src/patterns.ts b/scanner/src/patterns.ts index f2e61e23..663c9106 100644 --- a/scanner/src/patterns.ts +++ b/scanner/src/patterns.ts @@ -78,7 +78,7 @@ export const DANGEROUS_PATTERNS: Pattern[] = [ name: 'Environment Variable Access', description: 'Accessing environment variables (may contain secrets)', severity: 'medium', - pattern: /process\.env\[|process\.env\./gi, + pattern: /process\.env/gis, category: 'credential_access' }, { @@ -141,6 +141,30 @@ export const DANGEROUS_PATTERNS: Pattern[] = [ pattern: /dns\.resolve|dns\.lookup.*[+`$]/gi, category: 'network' }, + { + id: 'NET_WEBSOCKET_CONNECTION', + name: 'WebSocket Connection Initialization', + description: 'Creating a WebSocket connection (potential C2 channel)', + severity: 'high', + pattern: /require\s*\(\s*['"`]ws['"`]\s*\)|new\s+WebSocket\s*\(|websocket\/package|from\s+['"`]ws['"`]/gi, + category: 'network' + }, + { + id: 'NET_WEBSOCKET_EXFIL', + name: 'Data Exfiltration over WebSocket', + description: 'Sending data through WebSocket (potential exfiltration)', + severity: 'high', + pattern: /ws\.send\s*\(|websocket\.send\s*\(|socket\.send\s*\(/gi, + category: 'exfiltration' + }, + { + id: 'NET_WEBSOCKET_REVERSE_SHELL', + name: 'Reverse Shell over WebSocket', + description: 'Reverse shell implementation using WebSocket C2', + severity: 'critical', + pattern: /ws\.on\s*\(\s*['"`]message['"`]|websocket\.on\s*\(\s*['"`]message['"`].*eval|websocket\.on.*exec|WebSocket.*message.*eval|eval\s*\(.*data\)/gi, + category: 'code_execution' + }, // === MEDIUM: Obfuscation === {