skill-scan

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

用于 OpenClaw 技能包的多层安全扫描器。通过静态分析和可选的 LLM 深度检查，检测恶意代码、规避技术、提示词注入和行为偏离。安装或启用任何不可信技能之前，请先运行此工具。

功能

• 6 层分析 — 模式匹配、AST/规避、提示词注入、LLM 深度分析、对齐验证、元分析
• 60 多条检测规则 — 执行威胁、凭据窃取、数据泄露、混淆、行为特征
• 上下文感知评分 — 降低对合法 API 技能的误报
• ClawHub 集成 — 可通过 slug 直接扫描注册表中的技能
• 多种输出模式 — 文本报告（默认）、--json、--compact、--quiet
• 退出代码 — 安全时返回 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

风险评分

风险	评分	操作
LOW	80-100	可安全安装
MEDIUM	50-79	安装前审查检测结果
HIGH	20-49	请勿安装 — 检测到严重威胁
CRITICAL	0-19	请勿安装 — 检测到多个严重威胁

退出代码

• 0 — LOW 风险（可安全继续）
• 1 — MEDIUM 或更高风险（阻止安装）

LLM 选项

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

面向 Agent

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

1. 先扫描 — 安装前运行 skill-scan scan-hub <slug>
2. 检查结果：
   • 如果风险为 LOW（退出代码 0）：继续安装
   • 如果风险为 MEDIUM：向用户展示检测结果，并询问是否继续
   • 如果风险为 HIGH 或 CRITICAL：阻止安装并展示报告
3. 报告 — 始终向用户展示扫描摘要（评分、风险等级、检测结果数量）

警报格式

扫描发现 MEDIUM 或更高风险时：

🛡️ 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 集成到 Agent 的工作流中，请将以下模板之一添加到 AGENTS.md（或同等的 Agent 指令文件）中。

选项 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（LOW 风险） — 继续运行 clawhub install <slug>
   • 退出代码 1（MEDIUM 风险） — 向用户展示检测结果，并询问是否继续
   • 退出代码 1（HIGH/CRITICAL 风险） — 阻止安装，并展示完整报告
3. 除非用户明确覆盖限制，否则绝不安装 HIGH 或 CRITICAL 风险的技能
4. 继续安装前，始终向用户展示扫描摘要

定期审计

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

skill-scan batch {skillsDir}

LLM 深度分析

对于高风险安装，或模式扫描结果为 MEDIUM 时，升级至 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

安装时设置

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

skill-scan 应如何集成到你的工作流中？

1. 自动（推荐）— 每次运行 clawhub install 前都会先扫描。自动阻止 HIGH/CRITICAL 风险的安装。
2. 手动 — 仅在你明确要求时才进行扫描。

根据用户的选择，将相应的模板（上方的选项 A 或选项 B）添加到项目的 AGENTS.md 中。

检测类别

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

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

数据外泄 — fetch()、axios、requests、套接字、Webhook

文件系统操作 — 写入／删除／重命名操作

混淆 — Base64、十六进制、Unicode 编码、字符串构造

提示词注入 — 越狱、不可见字符、同形异义字符、角色扮演框架、编码指令

行为特征 — 复合模式：数据外泄、木马技能、规避检测的恶意软件、持久化后门

要求

• Python 3.10+
• httpx>=0.27（仅用于 LLM API 调用）
• 仅 --llm 模式需要 API 密钥（静态分析可独立运行）

相关技能

• input-guard — 外部输入扫描
• memory-scan — Agent 记忆安全
• guardrails — 安全策略配置