技能卫士 — 恶意模式扫描器

何时运行

自动触发

1. 新技能安装时— 立即运行scan_skill.py在允许使用前对其进行扫描
2. 技能更新时— 技能目录中任何文件变更后重新扫描
3. 定期审计— 在需要时对所有已安装技能进行批量扫描

手动触发

• 用户说"扫描技能X" → 扫描该特定技能
• 用户说"扫描所有技能" → 批量扫描所有技能
• 用户说"安全检查"或"审计技能" → 同上

脚本

scripts/scan_skill.py— 单技能扫描器

扫描单个技能目录以检测恶意模式。生成JSON或人类可读的输出。

scripts/aggregate_scan.py— 批量扫描器

扫描所有已安装的技能并生成一份JSON报告。包含内置白名单，以减少来自安全相关技能、API技能和其他已知安全模式的误报。

如何运行

# Scan a single skill (human-readable)
python3 scripts/scan_skill.py /path/to/skill-dir

# Scan a single skill (JSON output)
python3 scripts/scan_skill.py /path/to/skill-dir --json

# Scan ALL installed skills (JSON aggregate report)
python3 scripts/aggregate_scan.py

# With custom skills directory
python3 scripts/aggregate_scan.py --skills-dir /path/to/skills

# With verbose warnings
python3 scripts/scan_skill.py /path/to/skill-dir --verbose

# Exclude false positives
python3 scripts/scan_skill.py /path/to/skill-dir --exclude "pattern1" "pattern2"

退出代码 (scan_skill.py)

• 0= 干净或仅信息性
• 1= 可疑（中/高级发现）
• 2= 危险（关键发现）
• 3= 错误

输出格式 (aggregate_scan.py)

{
  "skills": [
    {
      "name": "skill-name",
      "verdict": "clean|suspicious|dangerous|error",
      "findingsCount": 0,
      "findings": []
    }
  ],
  "summary": "All 37 skills passed with no significant issues.",
  "totalSkills": 37,
  "cleanCount": 37,
  "suspiciousCount": 0,
  "dangerousCount": 0,
  "errorCount": 0,
  "timestamp": "2026-02-02T06:00:00+00:00"
}

自动检测

两个脚本均自动检测路径：

• 技能目录: 从脚本位置检测（向上查找至skills/父目录），回退到~/clawd/skills、~/skills、~/.openclaw/skills
• 扫描脚本:aggregate_scan.py查找scan_skill.py位于同一目录中

处理结果

✅ 安全 (判定: "安全")

• 无需操作——技能安全

⚠️ 可疑 (判定: "可疑")

• 向用户发出警告并总结发现内容
• 显示每项发现的类别和严重性

🚨 危险 (判定: "危险")

• 阻止该技能——请勿继续安装或使用
• 向用户显示完整的详细发现内容
• 需要用户明确同意才能继续

内置允许名单

聚合扫描器包含一个已知误报的允许列表：

• 安全扫描器(skill-defender, clawdbot-security-check) — 其文档/脚本包含它们检测的特定模式
• 依赖认证的技能(tailscale, reddit, n8n, event-planner) — 合法地引用凭据路径和API密钥
• 配置感知技能(memory-setup, eightctl, summarize) — 在文档中引用配置路径
• 代理编写技能(self-improving-agent) — 设计用于修改代理文件

模式参考

请参阅references/threat-patterns.md以获取所有检测模式的完整文档，按类别组织并解释了每个模式为何危险。

重要说明

• 无外部依赖— 仅使用标准库（Python 3.9+）
• 快速— 每个技能扫描时间低于1秒，扫描30多个技能的完整批次约需30秒
• 这是确定性模式匹配（第二层防御）。非基于LLM。
• 可能存在误报——允许列表和--exclude标志有助于
• 扫描器会标记自身如果在没有允许列表的情况下扫描——这是预期情况