skill-scan

核心用法

skill-scan 是 OpenClaw 生态系统的官方安全审计工具，专为 Agent Skill 包提供安装前安全检测。用户可通过 skill-scan scan-hub <slug>> 直接扫描 ClawHub 注册表中的技能，或使用 skill-scan scan /path/to/skill 审计本地技能目录。工具支持批量扫描、JSON 输出、静默模式等多种用法，并可集成 --llm 选项启用 GPT-4o-mini 或 Claude 的深度语义分析。

显著优点

该工具采用业界领先的六层分析架构：模式匹配层（60+ 检测规则）、AST/逃避分析层、提示注入检测层、LLM 深度分析层、对齐验证层和元分析层。这种分层设计既能实现毫秒级快速筛查，又能通过语义理解捕获复杂威胁。特别值得称道的是其上下文感知评分系统，能智能识别合法的 API 调用（如 GitHub API）并降低误报，避免对正常技能过度告警。此外，工具提供完整的 CI/CD 集成能力，通过退出码（0/1）实现自动化决策，并内置随机分隔符机制防止 LLM 提示注入攻击。

潜在缺点与局限性

作为安全扫描工具，skill-scan 的LLM 深度分析功能依赖外部 API（OpenAI/Anthropic），这意味着：需要额外配置 API 密钥、产生调用成本、存在网络延迟（15-60 秒超时），且可能受限于服务商的可用性。虽然静态分析层完全离线运行，但最高级别的威胁检测能力并非开箱即用。此外，工具的检测规则基于已知威胁模式，对于零日攻击或高度定制化的恶意代码可能存在检测盲区，需要结合人工审计弥补。

适合的目标群体

• OpenClaw Agent 用户：任何从 ClawHub 安装技能的终端用户，尤其是非技术背景用户
• 企业安全团队：需要将技能安全审查纳入 DevSecOps 流程的组织
• 技能开发者：在发布前自检技能包，确保通过安全扫描
• 平台运营方：构建自动化技能审核 pipeline 的基础设施团队

使用风险

• 性能开销：LLM 模式下的深度分析可能显著延长扫描时间
• 依赖项风险：虽仅依赖 httpx 一个外部库，但仍需关注其供应链安全
• 子进程调用：工具内部调用 clawhub 和 openclaw CLI，若这些工具被篡改可能影响扫描结果
• 临时目录管理：scan-hub 功能会创建临时目录下载技能，虽使用 mkdtemp 安全创建，但在极端情况下（如磁盘满、权限问题）可能引发异常

核心用途

skill-scan 是专为 OpenClaw 生态设计的多层安全扫描器，用于在技能安装前检测潜在威胁。它通过 6 层分析架构（模式匹配、AST/规避检测、提示注入扫描、LLM 深度分析、对齐验证、元分析）和 60+ 条检测规则，识别执行威胁、凭证窃取、数据外渗、混淆代码及行为特征。

显著优点

分层防御体系 — 静态规则引擎可独立运行（无需 API 密钥），LLM 分析层作为可选增强，兼顾效率与深度
生态深度集成 — 原生支持 ClawHub 注册表扫描（scan-hub）、批量审计（batch）及自动工作流嵌入，提供清晰的退出码（0/1）便于 CI/CD 集成
误报控制机制 — 上下文感知评分系统能区分合法 API 技能与真正威胁，减少过度警报
透明可审计 — 完整的规则库开源（dangerous-patterns.json），支持 --dry-run 预览和 JSON/compact 多格式输出

潜在局限

LLM 模式隐私权衡 — 启用 --llm 时需将技能代码传输至 OpenAI/Anthropic 服务器，敏感代码存在第三方暴露风险
subprocess 依赖链 — 核心功能依赖外部 clawhub/openclaw CLI 工具，若工具未安装或版本不兼容会导致功能失效
规则库误报边界 — 安全研究类、教学演示类技能可能因合法使用危险函数（如 eval 教学示例）触发警报
网络依赖瓶颈 — ClawHub 下载环节缺乏细粒度超时控制，弱网环境可能影响体验

适合人群

• 安全运维团队 — 需要为组织建立技能安装白名单/黑名单机制
• 开发者/技术负责人 — 在引入第三方技能前进行尽职调查
• CI/CD 工程师 — 将技能扫描纳入自动化部署流水线
• 安全意识强的个人用户 — 避免安装来自公共仓库的未经验证技能

常规风险

| 风险场景 | 等级 | 说明 |

|---------|------|------|

| 禁用 LLM 分析时的漏报 | MEDIUM | 纯静态分析可能遗漏新型混淆技术 |

| 高敏感度代码的 LLM 上传 | MEDIUM | `--llm` 模式需权衡检测深度与数据保密 |

| slug 参数注入 | LOW | 已使用参数列表传递，但建议增加字符白名单验证 |

| 临时目录残留 | LOW | 异常中断时可能留下 `skillguard-*` 临时文件 |

安全认证摘要

• 来源可信度: T2（GitHub 组织账号 clawdbot 维护，开源安全工具）
• 安全等级: A（78/100），主要扣分项为功能必需的 subprocess 调用和网络请求
• 关键发现: 8 项中风险点均为功能设计所需（subprocess、LLM API、环境变量读取），无恶意行为或隐藏后门

使用建议

高安全环境: 禁用 LLM 模式，仅使用静态分析 + 人工审查
效率优先场景: 启用 --llm-auto 仅在静态分析触发 MEDIUM+ 时启动深度检测
关键基础设施: 建立私有的 ClawHub 镜像，配合离线扫描模式使用