Skill-Scan — Security Auditor for Agent Skills
Multi-layered security scanner for OpenClaw skill packages. Detects malicious code, evasion techniques, prompt injection, and misaligned behavior through static analysis and optional LLM-powered deep inspection. Run this BEFORE installing or enabling any untrusted skill.
Features
- - 6 analysis layers — pattern matching, AST/evasion, prompt injection, LLM deep analysis, alignment verification, meta-analysis
- 60+ detection rules — execution threats, credential theft, data exfiltration, obfuscation, behavioral signatures
- Context-aware scoring — reduces false positives for legitimate API skills
- ClawHub integration — scan skills directly from the registry by slug
- Multiple output modes — text report (default),
--json, --compact, INLINECODE2 - Exit codes — 0 for safe, 1 for risky (easy scripting integration)
When to Use
MANDATORY before installing or enabling:
- - Skills from ClawHub (any skill not authored by you)
- Skills shared by other users or teams
- Skills from public repositories
- Any skill package you haven't personally reviewed
RECOMMENDED for periodic audits of already-installed skills.
Quick Start
CODEBLOCK0
Risk Scoring
| Risk | Score | Action |
|---|
| LOW | 80-100 | Safe to install |
| MEDIUM |
50-79 | Review findings before installing |
| HIGH | 20-49 | Do NOT install — serious threats detected |
| CRITICAL | 0-19 | Do NOT install — multiple critical threats |
Exit Codes
- -
0 — LOW risk (safe to proceed) - INLINECODE4 — MEDIUM or higher (block installation)
LLM Options
CODEBLOCK1
Provider auto-detected from environment:
- -
OPENAI_API_KEY -> gpt-4o-mini - INLINECODE6 -> claude-sonnet-4-5
For the Agent
When the user asks to install a skill from ClawHub, follow this workflow:
- 1. Scan first — run
skill-scan scan-hub <slug> BEFORE installing - Check the result:
- If
LOW risk (exit code 0): proceed with installation
- If
MEDIUM risk: show findings to the user and ask whether to proceed
- If
HIGH or CRITICAL risk: block installation and show the report
- 3. Report — always show the user the scan summary (score, risk level, finding count)
Alert Format
When a scan finds MEDIUM or higher risk:
CODEBLOCK2
AGENTS.md Integration
To integrate skill-scan into your agent's workflow, add ONE of the following templates to your AGENTS.md (or equivalent agent instructions file).
Option A: Automatic Scanning (Recommended)
All ClawHub skill installs are automatically scanned before installation. No manual step needed.
CODEBLOCK3 bash
skill-scan scan-hub
2. **Check the exit code and output**:
- **Exit code 0 (LOW risk)** — proceed with `clawhub install <slug>`
- **Exit code 1 (MEDIUM risk)** — show findings to the user, ask whether to proceed
- **Exit code 1 (HIGH/CRITICAL risk)** — BLOCK installation, show the full report
3. **Never install a HIGH or CRITICAL risk skill** without explicit user override
4. **Always show the scan summary** to the user before proceeding with installation
### Periodic Audits
When asked to audit installed skills, batch scan the skills directory:
bash
skill-scan batch {skillsDir}
### LLM Deep Analysis
For high-stakes installs or when pattern scan returns MEDIUM, escalate to LLM analysis:
bash
skill-scan scan-hub --llm-auto
CODEBLOCK6
Option B: Manual On-Demand Scanning
Skills are only scanned when the user explicitly asks. Installation proceeds without automatic checks.
CODEBLOCK7
Install-Time Setup
When this skill is first installed, ask the user:
How should skill-scan integrate with your workflow?
- 1. Automatic (Recommended) — Every
clawhub install is scanned first. HIGH/CRITICAL installs are blocked automatically. - Manual — Scanning only happens when you explicitly ask for it.
Based on their choice, add the corresponding template (Option A or Option B above) to the project's AGENTS.md.
Detection Categories
Execution threats — eval(), exec(), child_process, dynamic imports
Credential theft — .env access, API keys, tokens, private keys, wallet files
Data exfiltration — fetch(), axios, requests, sockets, webhooks
Filesystem manipulation — Write/delete/rename operations
Obfuscation — Base64, hex, unicode encoding, string construction
Prompt injection — Jailbreaks, invisible characters, homoglyphs, roleplay framing, encoded instructions
Behavioral signatures — Compound patterns: data exfiltration, trojan skills, evasive malware, persistent backdoors
Requirements
- - Python 3.10+
- INLINECODE18 (for LLM API calls only)
- API key only needed for
--llm modes (static analysis is self-contained)
Related Skills
- - input-guard — External input scanning
- memory-scan — Agent memory security
- guardrails — Security policy configuration
Skill-Scan — 智能体技能安全审计工具
针对OpenClaw技能包的多层安全扫描器。通过静态分析和可选的LLM深度检测，识别恶意代码、规避技术、提示注入和异常行为。在安装或启用任何不可信技能之前，请务必运行此工具。
功能特性
- - 6层分析 — 模式匹配、AST/规避检测、提示注入、LLM深度分析、对齐验证、元分析
- 60+检测规则 — 执行威胁、凭证窃取、数据泄露、混淆技术、行为特征
- 上下文感知评分 — 减少对合法API技能的误报
- ClawHub集成 — 通过slug直接从注册表扫描技能
- 多种输出模式 — 文本报告（默认）、--json、--compact、--quiet
- 退出码 — 0表示安全，1表示有风险（便于脚本集成）
使用时机
必须使用于安装或启用以下技能之前：
- - 来自ClawHub的技能（非你本人编写的任何技能）
- 其他用户或团队分享的技能
- 来自公共仓库的技能
- 任何你未亲自审查的技能包
建议使用于对已安装技能进行定期审计。
快速开始
bash
扫描本地技能目录
skill-scan scan /path/to/skill
安装前扫描ClawHub上的技能
skill-scan scan-hub some-skill-slug
批量扫描所有已安装技能
skill-scan batch /path/to/skills-directory
JSON输出，便于程序化使用
skill-scan scan-hub some-skill-slug --json
静默模式（仅显示分数+判定结果）
skill-scan scan-hub some-skill-slug --quiet
风险评分
50-79 | 安装前需审查发现的问题 |
| 高 | 20-49 | 请勿安装 — 检测到严重威胁 |
| 严重 | 0-19 | 请勿安装 — 检测到多个严重威胁 |
退出码
- - 0 — 低风险（可继续操作）
- 1 — 中风险或更高（阻止安装）
LLM选项
bash
skill-scan scan-hub slug --llm # 始终运行深度分析（第4-5层）
skill-scan scan-hub slug --llm-auto # 仅在模式扫描发现中风险+时使用LLM
skill-scan scan-hub slug --llm-only # 跳过模式扫描，仅进行LLM分析
从环境变量自动检测提供商：
- - OPENAIAPIKEY -> gpt-4o-mini
- ANTHROPICAPIKEY -> claude-sonnet-4-5
智能体操作指南
当用户要求从ClawHub安装技能时，请遵循以下工作流程：
- 1. 先扫描 — 在安装前运行 skill-scan scan-hub
- 检查结果：
- 如果
低风险（退出码0）：继续安装
- 如果
中风险：向用户展示发现的问题并询问是否继续
- 如果
高风险或严重风险：阻止安装并显示报告
- 3. 报告 — 始终向用户展示扫描摘要（分数、风险等级、发现数量）
警报格式
当扫描发现中风险或更高风险时：
🛡️ Skill-Scan 警报：{风险等级}（{分数}/100）
技能：{slug}
发现：检测到 {数量} 个问题
最高威胁：{最严重问题的标题}
操作：安装已被阻止，等待审查。
AGENTS.md集成
要将skill-scan集成到智能体的工作流程中，请将以下模板之一添加到你的 AGENTS.md（或等效的智能体指令文件）中。
选项A：自动扫描（推荐）
所有ClawHub技能安装前都会自动扫描。无需手动操作。
markdown
Skill-Scan — 安装前自动安全扫描
在从ClawHub安装任何技能之前，你必须先用skill-scan进行扫描。这是强制要求 — 绝不能跳过扫描。
工作流程
- 1. 当用户要求安装技能时（例如 clawhub install ），先运行扫描：
bash
skill-scan scan-hub
- 2. 检查退出码和输出：
- 退出码0（低风险） — 继续执行 clawhub install
- 退出码1（中风险） — 向用户展示发现的问题，询问是否继续
- 退出码1（高风险/严重风险） — 阻止安装，显示完整报告
- 3. 未经用户明确授权，绝不安装高风险或严重风险的技能
- 在继续安装前，始终向用户展示扫描摘要
定期审计
当被要求审计已安装的技能时，批量扫描技能目录：
bash
skill-scan batch {skillsDir}
LLM深度分析
对于高风险安装或当模式扫描返回中风险时，升级到LLM分析：
bash
skill-scan scan-hub --llm-auto
选项B：手动按需扫描
仅在用户明确要求时扫描技能。安装过程无需自动检查。
markdown
Skill-Scan — 按需技能安全扫描
skill-scan可用于审计技能包的安全威胁。当用户请求安全扫描时使用。
命令
- - 扫描ClawHub技能：skill-scan scan-hub
- 扫描本地技能：skill-scan scan /path/to/skill
- 批量扫描已安装技能：skill-scan batch {skillsDir}
- 使用LLM深度分析：在任何扫描命令后添加 --llm 或 --llm-auto
风险等级
- - 低（80-100） — 安全，无重大威胁
- 中（50-79） — 审查发现的问题，谨慎使用
- 高（20-49） — 严重威胁，请勿安装
- 严重（0-19） — 多个严重威胁，请勿安装
当用户要求扫描时
- 1. 运行相应的扫描命令
- 展示扫描摘要（分数、风险等级、发现数量）
- 如果中风险+，列出最严重的问题及其严重程度和描述
- 让用户决定如何处理
安装时设置
当首次安装此技能时，询问用户：
你希望skill-scan如何集成到你的工作流程中？
- 1. 自动（推荐）— 每次 clawhub install 都会先进行扫描。高风险/严重风险的安装将被自动阻止。
- 手动 — 仅在你明确要求时进行扫描。
根据他们的选择，将相应的模板（上述选项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 — 智能体内存安全
- guardrails — 安全策略配置
