# ClawHub Skill 安全扫描机制

**Sources**：
- [raw/clawhub-security-scan-xiangqin-2026-04-23.md](../../raw/clawhub-security-scan-xiangqin-2026-04-23.md)（扫描结果完整原文）
- [raw/clawhub-deep-dive-2026-04-23.md](../../raw/clawhub-deep-dive-2026-04-23.md)（2026-04-23 深调研，官方 docs / REST API / CLI 全覆盖）
- [archive issue #048](../../issues/archive/048-clawhub-security-flag.md)（老问题复盘；若归档）

## 机制

ClawHub 对每个 skill version push 都**自动重扫**，结果展示在 skill 页面 `Security Scan` 面板（API 里 inspect 没暴露字段，只能 scrape HTML 或 UI 看）。

### 两个扫描器

| 扫描器 | 性质 | 模型 / 来源 | 输出 |
|---|---|---|---|
| **VirusTotal** | 传统病毒库扫 + Code insights | `security.scanners.vt.source = palm`（VT 内部 Code Insights 标识） | `Benign` / `Suspicious` / `Malicious` + 报告链接 |
| **OpenClaw** | ClawHub 自家 AI-driven skill 专用分析器 | `gpt-5-mini`（`security.scanners.llm.model` 字段明示） | 5 维度 + 整体 assessment + 置信度 |

### OpenClaw 五维度

1. **Purpose & Capability** — skill 宣称的用途和要求的能力是否相称
2. **Instruction Scope** — 指令范围是否越权（读写文件 / 跑命令 / 调网络）
3. **Install Mechanism** — 安装机制（PyPI / npm / 裸脚本下载）的风险
4. **Credentials** — 是否要求不相关的凭证 / 环境变量
5. **Persistence & Privilege** — 是否请求系统级持久化 / 特权

每个维度结果：`✓ benign` / `ℹ info note` / `flag`。

### 触发 suspicious 的典型模式

- 敏感关键字（手机号 / vault / credentials / 身份证 / 支付）未配清晰说明段
- **CLI 样例里有 `<用户输入>` 占位**（如 `xq query '<where>'`）—— **VT Code insights 会推断 shell injection 风险**，即便实际有白名单 DSL 也会被误判（2026-04-23 v0.6.0 踩坑）
- 指令让 agent 运行任意代码 / 下载二进制
- Install 机制越过包管理器（curl | bash 直接跑 shell）
- 要求系统 root / 全局 env / 持续后台任务

### VT Code insights ≠ 病毒扫描

ClawHub "Security Scan" 面板里的 VirusTotal 行其实有两层：
- **64 个反病毒引擎**（传统病毒库）—— 标签 Undetected 即 clean
- **Code insights**（VT 自家 AI 代码分析）—— 看 SKILL.md 文本推断风险

**只要其中任一判 Suspicious**，ClawHub 顶部就会 "Skill flagged" banner。即使病毒扫描 0/64 全过，AI 判 shell injection 风险一样 flag。

修法：SKILL.md 加「安全」段显式披露**具体实现的安全机制**（DSL 白名单 / hash 存储 / 域名白名单 / 凭证边界），让扫描器 AI 读到这个 context 后下次不误判。

### 触发 flag 后的修复路径

1. **更新 SKILL.md**：加清晰的 section 自我披露处理方式（Privacy / Runtime / Credentials）
2. **push 新 version tag**：ClawHub 自动重扫，老 flag 被新扫描覆盖
3. 不需要人工申诉 / 等待

### ⚠️ 静态分析硬阻断（更严的一条）

`docs/security.md`：如果 skill 文本含 obfuscated shell payload（base64 解码的 `curl|bash` 之类）→ 触发**跨 skill 联动**：

1. 该 skill 立即 hidden
2. 上传者进入 manual moderation
3. **该用户已发布的所有 skill 全部 hidden 直到 staff 人工 review**

一人踩坑全军隐藏。obfuscated shell **绝对红线**，xiangqin SKILL.md 永远不要出现 `echo "..." | base64 -d | bash` 这种 pattern，哪怕是在"禁止事项"说明里。

### Report auto-hide 阈值（修正）

- **> 3 个独立 reporter 触发**（第 4 次 report 才 hide）——之前说的 "≥ 3" 错
- per-user cap：20 个活跃 report
- abuse of reporting 本身也会被 ban

### GitHub 账号年龄门槛（修正）

- publish + comment 都要求 **≥ 14 天**——之前说的 "约 1 周" 错
- 走 GitHub API 查 `created_at`，缓存到 user.githubCreatedAt
- 429/403 时 publish 失败并提示 rate limit

### Capability tags（独立于 verdict）

`GET /api/v1/skills/<slug>/scan` 返回确定性 capability 标签，独立于 clean/suspicious：
- `crypto` / `requires-wallet` / `can-make-purchases` / `can-sign-transactions`
- `requires-oauth-token` / `posts-externally`

xiangqin 0.6.1 `capabilityTags: []`（空），未来如果 skill 引入支付 / OAuth 要关注这些标签。

### Comment scam scanner

ClawHub 对 comment 也有独立 AI 扫（与 skill 扫分离）：
- `scamScanVerdict`: `not_scam | likely_scam | certain_scam`
- `scamScanConfidence`: `low | medium | high`
- 只有 `certain_scam + high` 才 auto-ban 账号
- moderator / admin 永不被 auto-ban

xiangqin 的实际路径：v0.3.0 → 0.3.1 → 0.4.x → 0.5.x 多次 release，0.5.4 时扫描已 Benign，**没有主动做过 privacy section 修改**，是 SKILL.md 自然演进 + 多版本重扫累积的结果。

### CLI 权威 API（不走 HTML scrape）

API 返回结构化 scan 结果，比 GUI 靠谱（GUI 有渲染延迟、未来改版风险）：

```bash
# version.security：LLM + VT 扫描细节，含 virustotalUrl
curl -sS "https://clawhub.ai/api/v1/skills/<slug>/versions/<v>"

# moderation：最终决策（isSuspicious / isMalwareBlocked / verdict）
# 需要 Authorization: Bearer <CLAWHUB_TOKEN>
curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://clawhub.ai/api/v1/skills/<slug>/moderation"
```

`clawhub inspect --json` 子命令**不暴露** scan 字段（CLI 过滤掉了），必须直接走 REST API。

完整脚本（退出码 0/1 给 CI 用）：`xiangqin/scripts/check-clawhub-scan.sh`（`release.yml` 的 publish-clawhub job 发完 skill 自动调）。

### VT Sandbox 的"Sagent"实际会按 SKILL.md 跑命令

2026-04-23 0.6.1 VT behavior report 观察到：`C:\Program Files (x86)\Sagent\skill-analyzer.exe` 这个进程做了：
1. 解压 skill.zip 到 `C:\...\Temp\skill_<id>\` (含 SKILL.md + README.md + _meta.json)
2. 读 SKILL.md 的安装段 → 真跑：
   - `python --version`
   - `python -m pip install pipx`（pip 真下载）
   - `pipx --version`
   - `where pipx`
3. 监控 subprocess + 文件 + 注册表 + 网络所有行为

**意味**：
- 之前"扫描器只读文本"的说法**不完整**。Sagent 会**部分执行** SKILL.md 里的安装命令
- 本次只跑到"装 pipx"就停（可能 sagent 设计 / 超时），没跑 `pipx install acong-tech-xiangqin`
- **但这路径是开通的**：未来 Sagent 升级可能继续跑 `xq register` / `xq query` 等 —— 真发请求到你的服务端
- SKILL.md 里写的**所有指令都可能被实锤验证**，不能只给 LLM 看的 disclaimer，要和实际实现一致
- 生产服务端会看到类似 "虚拟机 sandbox 测试" 流量（文档正常情况下不接入业务）

意义：这让 pytest lint Rule 2（`<占位>` → 必须声明"不经 shell"）**双重有效**：
- LLM 读到 disclaimer → 静态不误判
- Sandbox 实测 → 真验证 `xq query` 确实不触发 shell（如果真触发 shell，sandbox 会抓到并判 Malicious）

## 给 xiangqin 的行动要点

- 未来发 skill 新版本前 review SKILL.md 有没有**新的敏感关键字** 没 context
- 每次 tag push 后访问 `https://clawhub.ai/<owner>/<slug>` 看 Security Scan 面板
- API 路径 `clawhub inspect <slug> --json` 只返 stats，不含 scan 结果 → 要 HTML scrape
- 当前 0.5.4 Benign 状态的原始证据在 [raw/clawhub-security-scan-xiangqin-2026-04-23.md](../../raw/clawhub-security-scan-xiangqin-2026-04-23.md)
