Skill-Scan —— 智能体技能安全审计工具

专为OpenClaw技能包打造的多层安全扫描器。通过静态分析与可选的LLM深度检测，识别恶意代码、规避技术、提示注入及行为偏差。请在安装或启用任何非受信技能前务必运行本工具。

核心功能

• 六层分析架构—— 模式匹配、AST/规避检测、提示注入分析、LLM深度审查、对齐验证、元分析
• 60余项检测规则—— 执行威胁、凭证窃取、数据外泄、代码混淆、行为特征识别
• 情境感知评分—— 有效降低合法API技能的误报率
• ClawHub集成—— 支持通过技能标识符直接扫描注册库中的技能
• 多重输出模式—— 文本报告（默认）、JSON格式、紧凑模式、静默模式
• 退出代码— 0表示安全，1表示有风险（易于脚本集成）

使用时机

必须使用在安装或启用前：

• 来自 ClawHub 的技能（任何非您创建的技能）
• 其他用户或团队共享的技能
• 来自公共仓库的技能
• 任何您未亲自审核的技能包

推荐使用用于对已安装技能的定期审计。

快速开始

# Scan a local skill directory
skill-scan scan /path/to/skill

# Scan a skill from ClawHub before installing it
skill-scan scan-hub some-skill-slug

# Batch scan all installed skills
skill-scan batch /path/to/skills-directory

# JSON output for programmatic use
skill-scan scan-hub some-skill-slug --json

# Quiet mode (just score + verdict)
skill-scan scan-hub some-skill-slug --quiet

风险评分

退出代码

• 0——低风险（可继续执行）
• 1——中等或更高风险（阻止安装）

大语言模型选项

skill-scan scan-hub slug --llm        # Always run deep analysis (layers 4-5)
skill-scan scan-hub slug --llm-auto   # LLM only if pattern scan finds MEDIUM+
skill-scan scan-hub slug --llm-only   # Skip patterns, LLM analysis only

提供方根据环境自动检测：

• OPENAI_API_KEY-> gpt-4o-mini
• ANTHROPIC_API_KEY-> claude-sonnet-4-5

针对代理

当用户要求从ClawHub安装技能时，请遵循以下工作流程：

1. 首先扫描——运行skill-scan scan-hub <slug>在安装之前
2. 检查结果：
   • 如果低风险（退出代码 0）：继续安装
   • 如果中等风险：向用户展示检测结果并询问是否继续
   • 如果高风险或严重风险：阻止安装并显示报告
3. 报告— 始终向用户展示扫描摘要（分数、风险等级、发现数量）

警报格式

当扫描发现中等或更高风险时：

🛡️ Skill-Scan Alert: {RISK_LEVEL} ({SCORE}/100)
Skill: {slug}
Findings: {count} issue(s) detected
Top threat: {highest severity finding title}
Action: Installation blocked pending review.

AGENTS.md 集成

要将 skill-scan 集成到你的代理工作流中，请将以下模板之一添加到你的AGENTS.md（或等效的代理指令文件）。

选项 A：自动扫描（推荐）

所有 ClawHub 技能的安装都会在安装前自动扫描。无需手动步骤。

## Skill-Scan — Automatic Pre-Install Security Scanning

BEFORE installing any skill from ClawHub, you MUST scan it with skill-scan first. This is non-negotiable — never skip the scan.

### Workflow

1. When the user asks to install a skill (e.g. `clawhub install <slug>`), run the scan FIRST:
   ```bash
   skill-scan scan-hub <slug>

2. 检查退出代码和输出：
   • 退出代码 0（低风险）— 继续执行clawhub install <slug>
   • 退出代码 1（中等风险）— 向用户展示检测结果，询问是否继续
   • 退出代码 1（高/严重风险）— 阻止安装，展示完整报告
3. 切勿安装高风险或严重风险的技能除非用户明确要求覆盖
4. 在继续安装之前，始终向用户展示扫描摘要定期审计

当要求审计已安装技能时，批量扫描技能目录：

LLM 深度分析

skill-scan batch {skillsDir}

对于高风险安装或当模式扫描返回中等风险时，升级至 LLM 分析：

安装时设置

skill-scan scan-hub <slug> --llm-auto

### Option B: Manual On-Demand Scanning

Skills are only scanned when the user explicitly asks. Installation proceeds without automatic checks.

```markdown
## Skill-Scan — On-Demand Skill Security Scanning

skill-scan is available to audit skill packages for security threats. Use it when the user requests a security scan.

### Commands

- **Scan a ClawHub skill**: `skill-scan scan-hub <slug>`
- **Scan a local skill**: `skill-scan scan /path/to/skill`
- **Batch scan installed skills**: `skill-scan batch {skillsDir}`
- **Deep analysis with LLM**: add `--llm` or `--llm-auto` to any scan command

### Risk Levels

- **LOW (80-100)** — safe, no significant threats
- **MEDIUM (50-79)** — review findings, use caution
- **HIGH (20-49)** — serious threats, do not install
- **CRITICAL (0-19)** — multiple critical threats, do not install

### When the User Asks to Scan

1. Run the appropriate scan command
2. Show the scan summary (score, risk level, finding count)
3. If MEDIUM+, list the top findings with severity and description
4. Let the user decide what to do

当首次安装此技能时，询问用户：

技能扫描应如何与您的工作流程集成？

自动

1. （推荐）— 每次clawhub installclawhub install会首先进行扫描。高风险/严重风险的安装会被自动阻止。
2. 手动模式— 扫描仅在您明确要求时才会进行。

根据他们的选择，将相应的模板（上面的选项A或选项B）添加到项目的AGENTS.md文件中。

检测类别

执行威胁—eval()、exec()、child_process、动态导入

凭据窃取—.env文件访问、API密钥、令牌、私钥、钱包文件

数据外泄—fetch()、axios请求套接字、网络钩子文件系统操作

——写入/删除/重命名操作混淆

——Base64、十六进制、Unicode编码，字符串构造提示注入

——越狱、不可见字符、同形异义词、角色扮演框架、编码指令行为特征

——复合模式：数据泄露、木马技能、规避性恶意软件、持久性后门要求

Python 3.10+

• httpx>=0.27
• （仅用于LLM API调用）API密钥仅用于
• --llm模式（静态分析是自包含的）相关技能

输入防护

• ——外部输入扫描内存扫描
• memory-scan— 代理记忆安全
• 护栏— 安全策略配置