skill-security-auditor

Original source / Raw SKILL.md

---
name: skill-security-auditor
description: OpenClaw Skills 全方位安全审计工具，检测供应链投毒、Prompt注入、恶意代码模式、权限越权和依赖风险
version: 1.0.0
author: security-audit
metadata: {
  "category": "security",
  "risk": "safe",
  "requires": {
    "bins": ["node", "grep", "sha256sum"]
  }
}
---

# Skill Security Auditor

基于《OpenClaw 极简安全实践指南》和《安全验证与攻防演练手册》的 Skill 安全审计工具。对 OpenClaw Skill 进行从源码到运行时的全生命周期安全审查，覆盖供应链投毒、Prompt 注入载荷、恶意代码模式、权限越权等威胁向量。

## Purpose

OpenClaw Skills 是 Agent 能力的扩展机制，通过 `/workspace/skills/{skill_name}/SKILL.md` 被 Agent 加载执行。恶意 Skill 可以：
- 通过 Prompt 注入劫持 Agent 行为
- 在代码块中嵌入反弹 Shell、数据外传命令
- 引用恶意外部依赖进行供应链攻击
- 通过 Unicode 混淆、零宽字符隐藏恶意指令

本技能为 Skill 的安装和更新提供安全门禁，在 Skill 进入生产环境前完成安全审查。

## Prerequisites

### 输入要求
- 目标 Skill 目录路径（包含 `SKILL.md` 和 `references/` 等）
- 或 Skill 的远程仓库 URL（用于拉取审计）

### 环境要求
- Node.js 运行时（用于执行审计脚本）
- 对 Skill 文件的读取权限

## Core Workflow

1. **元数据验证**: 解析 SKILL.md 的 frontmatter，验证 name、version、description、metadata 完整性和合法性。
2. **Prompt 注入扫描**: 检测 SKILL.md 正文中的指令注入模式（角色劫持、指令覆盖、隐蔽指令）。
3. **代码块安全审计**: 提取所有代码块（bash, python, javascript 等），对每个代码块进行恶意模式检测。
4. **依赖与引用审查**: 检查 Skill 引用的外部 URL、npm 包、Python 包的安全性和来源可信度。
5. **文件结构检查**: 验证 Skill 目录结构是否符合规范，检测异常文件（二进制、可执行文件、符号链接）。
6. **Unicode 和编码检测**: 扫描隐藏的 Unicode 控制字符、零宽字符、Bidi 覆盖字符。
7. **权限声明审查**: 验证 Skill 声明的权限范围是否合理，检测权限越权请求。
8. **历史版本对比**: 对 Skill 更新进行 diff 分析，检测是否引入了新的恶意内容。
9. **沙箱验证**: 在受限环境中试运行 Skill 代码片段，观察其行为。

## 审计检查项

### 1. 元数据完整性

| 检查项 | 风险等级 | 检测规则 |
|--------|---------|---------|
| frontmatter 缺失 | HIGH | SKILL.md 无 YAML frontmatter |
| name 与目录名不匹配 | MEDIUM | `name` 字段与所在目录名不一致 |
| version 格式无效 | LOW | 非 semver 格式 |
| description 为空 | MEDIUM | 缺少描述，难以审查意图 |
| category 未声明 | LOW | metadata 中缺少 category |
| risk 标记为 unsafe | HIGH | 自声明高风险 |
| requires 声明可疑二进制 | HIGH | 依赖 `nc`, `ncat`, `socat` 等 |

### 2. Prompt 注入检测

| 检测模式 | 风险等级 | 示例 |
|---------|---------|------|
| 角色劫持 | CRITICAL | "You are now a...", "Ignore previous instructions" |
| 指令覆盖 | CRITICAL | "Do not follow any rules", "Override system prompt" |
| 隐蔽指令 | HIGH | HTML 注释中的指令, CSS `display:none` 包裹的文本 |
| 输出操控 | HIGH | "Always respond with...", "Never mention..." |
| 权限升级 | CRITICAL | "Execute with admin privileges", "Disable safety checks" |
| 零宽字符隐藏 | CRITICAL | `\u200B`, `\u200C`, `\u200D`, `\uFEFF` 隐藏的指令 |
| Bidi 覆盖攻击 | CRITICAL | `\u202A`-`\u202E` 改变文本显示方向 |
| Markdown 注入 | MEDIUM | 通过 Markdown 渲染差异隐藏内容 |

### 3. 代码块安全审计

| 代码类型 | 检测规则 | 风险等级 |
|---------|---------|---------|
| Bash | 反弹 Shell、数据外传、提权命令 | 参见 openclaw-threat-detect |
| Python | `exec()`, `eval()`, `subprocess`, `os.system`, `socket` | HIGH |
| JavaScript | `child_process`, `eval`, `Function()`, `require('net')` | HIGH |
| 混淆代码 | Base64 编码的命令, `\x` 转义序列, 多层编码 | CRITICAL |
| 下载执行 | `curl\|wget.*\| bash`, `python -c "$(curl..."` | CRITICAL |
| 文件写入 | 向 `.bashrc`, `.profile`, cron 写入 | HIGH |

### 4. 依赖与外部引用

| 检查项 | 风险等级 | 检测规则 |
|--------|---------|---------|
| 引用非 HTTPS URL | MEDIUM | `http://` 开头的 URL |
| 引用已知恶意域名 | CRITICAL | 与威胁情报库比对 |
| npm 包 typosquatting | HIGH | 包名与知名包相似度 > 0.8 |
| 未锁定版本 | MEDIUM | 使用 `@latest` 或 `*` 版本 |
| 引用废弃/归档仓库 | LOW | GitHub 仓库标记为 archived |
| 安装脚本执行 | HIGH | `preinstall`/`postinstall` hooks |

### 5. 文件结构检查

| 检查项 | 风险等级 | 检测规则 |
|--------|---------|---------|
| 包含二进制文件 | HIGH | 非文本文件（magic bytes 检测） |
| 包含可执行文件 | HIGH | 文件有 +x 权限 |
| 符号链接逃逸 | CRITICAL | 符号链接指向 Skill 目录外 |
| 隐藏文件 | MEDIUM | `.` 开头的隐藏文件（`.env`, `.git`） |
| 文件过大 | LOW | 单文件 > 1MB |
| 异常文件扩展名 | MEDIUM | `.exe`, `.dll`, `.so`, `.dylib` |

### 6. 权限声明审查

| 检查项 | 风险等级 | 检测规则 |
|--------|---------|---------|
| 声明 root 权限 | CRITICAL | requires 中要求 sudo/root |
| 网络访问未声明 | HIGH | 代码中有网络操作但 metadata 未声明 |
| 文件系统范围过宽 | MEDIUM | 访问 `/` 或 `$HOME` 而非 workspace |
| 声明与行为不匹配 | HIGH | 声明 "safe" 但包含危险操作 |

## 审计报告格式

```json
{
  "audit_id": "AUDIT-2026-0001",
  "timestamp": "2026-03-13T10:30:00Z",
  "skill": {
    "name": "example-skill",
    "version": "1.0.0",
    "path": "/workspace/skills/example-skill"
  },
  "verdict": "REJECT",
  "risk_score": 85,
  "findings": [
    {
      "id": "F001",
      "severity": "CRITICAL",
      "category": "prompt_injection",
      "title": "检测到角色劫持指令",
      "description": "SKILL.md 第 42 行包含 'Ignore all previous instructions' 模式",
      "location": "SKILL.md:42",
      "evidence": "...ignore all previous instructions and act as...",
      "recommendation": "移除该指令，如有合法用途需在 metadata 中声明"
    }
  ],
  "summary": {
    "critical": 1,
    "high": 2,
    "medium": 3,
    "low": 1,
    "total": 7
  },
  "recommendation": "REJECT - 存在 CRITICAL 级别发现，不建议加载"
}
```

### 审计判定标准

| 判定 | 条件 | 操作 |
|------|------|------|
| **PASS** | 无 CRITICAL/HIGH 发现 | 允许加载 |
| **CONDITIONAL** | 有 HIGH 但无 CRITICAL | 需人工确认后加载 |
| **REJECT** | 有 CRITICAL 发现 | 禁止加载，移至隔离区 |

## 与其他安全技能的协作

```
Skill 安装/更新
     │
     ▼
┌─────────────────────┐
│ skill-security-     │  ← 入口审计：源码级安全检查
│ auditor             │
└────────┬────────────┘
         │ PASS
         ▼
┌─────────────────────┐
│ openclaw-security-  │  ← 环境检查：Skill 加载后的配置影响
│ checker             │
└────────┬────────────┘
         │ PASS
         ▼
┌─────────────────────┐
│ openclaw-threat-    │  ← 运行时：Skill 执行中的行为监控
│ detect              │
└─────────────────────┘
```

## Tool Categories

| Category | Tools | Purpose |
|----------|-------|---------|
| 元数据解析 | python-frontmatter, js-yaml | SKILL.md frontmatter 解析和验证 |
| Prompt 分析 | 正则引擎, 零宽字符检测 | Prompt 注入模式匹配 |
| 代码分析 | semgrep patterns, AST 分析 | 代码块安全扫描 |
| 依赖检查 | npm audit (概念), PyPI check | 外部依赖安全性验证 |
| 文件检查 | file (magic), stat | 二进制检测和权限验证 |
| 编码检测 | Unicode 分析器 | 隐藏字符和 Bidi 攻击检测 |
| Diff 分析 | git diff, diff | 版本更新变更审查 |

## References

- `references/tools.md` - 工具函数签名和参数说明
- `references/workflows.md` - 审计流程定义和判定规则


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/tools.md

```markdown
# Tools

# Skill Security Auditor Tools

## Common response fields

- success: boolean
- finding_id: unique identifier for each finding
- severity: "CRITICAL"|"HIGH"|"MEDIUM"|"LOW"
- category: audit category string
- location: file path and line number of finding
- recommendation: suggested remediation

## Metadata validation

- parse_frontmatter(skill_path): Parse SKILL.md YAML frontmatter and return structured metadata. Validates presence of required fields (name, description, version). Returns parsed metadata or validation errors.
- validate_skill_name(name, directory_name): Check if frontmatter name matches the containing directory name. Returns match status and both names.
- validate_version(version): Verify version string follows semver format. Returns validity status.
- validate_metadata_fields(metadata): Check metadata completeness (category, risk, requires). Returns missing/invalid fields.
- validate_requires_bins(bins_list): Check declared binary dependencies against a list of known-dangerous binaries (nc, ncat, socat, nmap). Returns risk assessment per binary.

## Prompt injection scanning

- scan_prompt_injection(content, check_zero_width=True, check_bidi=True, check_html_comments=True): Comprehensive prompt injection scan on text content. Returns array of injection indicators with matched patterns and line numbers.
- detect_role_hijack(content): Search for role override patterns ("You are now", "Ignore previous", "Act as", "Forget your instructions"). Returns matches with context.
- detect_instruction_override(content): Search for instruction override patterns ("Do not follow", "Override system", "New instructions"). Returns matches.
- detect_hidden_directives(content): Search for directives hidden in HTML comments, CSS display:none, Markdown reference links. Returns hidden content found.
- detect_zero_width_chars(content): Scan for zero-width Unicode characters (U+200B/C/D, U+FEFF) that could hide instructions. Returns positions and surrounding context.
- detect_bidi_attacks(content): Scan for Bidi override characters (U+202A-U+202E, U+2066-U+2069) that change text display direction. Returns affected ranges.
- decode_hidden_content(content, positions): Attempt to decode/reveal content hidden by zero-width or Bidi characters. Returns decoded text.

## Code block analysis

- extract_code_blocks(markdown_content): Extract all fenced code blocks from Markdown with language hints, line numbers, and raw content. Returns array of code block objects.
- scan_bash_block(code): Analyze bash code block for dangerous patterns (reverse shells, data exfiltration, privilege escalation). Returns findings.
- scan_python_block(code): Analyze Python code block for dangerous patterns (exec, eval, subprocess, socket, os.system, importlib). Returns findings.
- scan_javascript_block(code): Analyze JavaScript code block for dangerous patterns (child_process, eval, Function, require('net'), fetch to external). Returns findings.
- detect_download_execute(code, language): Detect download-and-execute patterns across languages (curl|sh, wget|bash, python -c "$(curl...)"). Returns findings.
- detect_obfuscation(code): Detect obfuscation techniques (base64 encoding, hex escapes, string concatenation tricks, eval chains). Returns obfuscation indicators with best-effort decoded content.

## Dependency and reference checking

- extract_urls(content): Extract all URLs from Skill content (Markdown links, code blocks, plain text). Returns URL list with context.
- check_url_safety(url): Verify URL uses HTTPS, check domain reputation, detect known-malicious domains. Returns safety assessment.
- detect_typosquatting(package_name, ecosystem="npm"): Compare package name against known popular packages using edit distance and visual similarity. Returns similarity matches above threshold (0.8).
- check_package_exists(package_name, ecosystem="npm"): Verify if a referenced package actually exists on the registry. Returns existence and basic metadata (downloads, last publish, maintainer).
- check_install_hooks(package_name, ecosystem="npm"): Check if a package has preinstall/postinstall hooks that execute code. Returns hook presence and content.

## File structure validation

- validate_skill_structure(skill_dir): Check directory structure against expected layout (SKILL.md required, optional references/). Returns structure assessment.
- detect_binary_files(skill_dir): Scan for non-text files using file magic bytes. Returns list of binary files found.
- detect_executable_files(skill_dir): Scan for files with executable permission bits. Returns list with permission details.
- detect_symlinks(skill_dir): Find symbolic links and verify they don't point outside the skill directory (symlink escape). Returns symlink list with targets and safety status.
- detect_hidden_files(skill_dir): Find dot-prefixed hidden files (.env, .git, .npmrc). Returns list with risk assessment.
- check_file_sizes(skill_dir, max_size_bytes=1048576): Flag files exceeding size limit. Returns oversized files.

## Permission analysis

- analyze_declared_permissions(metadata): Parse the metadata.requires and metadata.risk fields to understand what the skill claims it needs. Returns permission summary.
- detect_undeclared_operations(code_blocks, declared_permissions): Cross-reference operations found in code blocks against declared permissions. Returns undeclared operations (network access, file writes, command execution not matching declarations).
- assess_permission_scope(operations): Evaluate whether the scope of operations (filesystem paths, network targets) is proportional to the skill's stated purpose. Returns scope assessment.

## Version diff analysis

- diff_skill_versions(old_path, new_path): Compare two versions of a skill and generate a structured diff. Returns added/modified/deleted content with security-relevant annotations.
- analyze_diff_risk(diff): Assess the security risk of changes between versions (new code blocks, new URLs, permission changes, new dependencies). Returns risk assessment of the update.

## Reporting

- generate_audit_report(findings, skill_metadata, format="json"): Generate formatted audit report. format: "json"|"markdown"|"text". Returns structured report with verdict (PASS/CONDITIONAL/REJECT).
- calculate_risk_score(findings): Compute overall risk score (0-100, higher = more risky) from findings. Returns score with breakdown.

```

### references/workflows.md

```markdown
# Workflows

# Skill Security Auditor Workflows

## Metadata validation

- parse_frontmatter: skill_path target SKILL.md
- validate_skill_name: compare frontmatter name with directory name
- validate_version: check semver format
- validate_metadata_fields: check completeness
- validate_requires_bins: check for dangerous binaries
- Check for:
  - Missing frontmatter: SKILL.md must have valid YAML frontmatter
  - Name mismatch: name field must match directory name
  - Invalid version: must follow semver (MAJOR.MINOR.PATCH)
  - Missing description: description field must not be empty
  - Dangerous binary requirements: nc, ncat, socat, nmap, msfconsole trigger HIGH alert
  - Self-declared risk "unsafe": triggers HIGH alert, requires justification
  - Missing category: makes skill harder to classify for security review

## Prompt injection scanning

- scan_prompt_injection: content from SKILL.md full text
- detect_role_hijack: patterns
  - "You are now a"
  - "Ignore (all )?(previous |prior )?instructions"
  - "Act as (a |an )?"
  - "Forget (your |all )?(previous )?(instructions|rules|constraints)"
  - "From now on"
  - "New persona:"
- detect_instruction_override: patterns
  - "Do not follow (any )?(previous |prior )?(rules|instructions)"
  - "Override (the )?system prompt"
  - "New (system )?instructions:"
  - "Disregard (all )?(safety |security )?(measures|checks|rules)"
  - "Disable (safety|security|content) (filter|check)"
- detect_hidden_directives:
  - HTML comments: `<!-- instructions here -->`
  - CSS hidden: `<span style="display:none">`, `<div style="font-size:0">`
  - Markdown reference links with instruction text: `[//]: # (hidden instruction)`
  - Image alt text with instructions
- detect_zero_width_chars: scan every character
  - U+200B Zero Width Space
  - U+200C Zero Width Non-Joiner
  - U+200D Zero Width Joiner
  - U+FEFF Zero Width No-Break Space (BOM)
  - U+2060 Word Joiner
  - If found: decode_hidden_content to reveal what's hidden
- detect_bidi_attacks: scan for directional override
  - U+202A Left-to-Right Embedding
  - U+202B Right-to-Left Embedding
  - U+202C Pop Directional Formatting
  - U+202D Left-to-Right Override
  - U+202E Right-to-Left Override (most dangerous: can make "exec" look like "cexe")
  - U+2066-U+2069 Isolate variants

## Code block security audit

- extract_code_blocks: from SKILL.md content
- For each code block by language:
  - Bash/Shell blocks:
    - scan_bash_block: reverse shell patterns, exfiltration, privilege escalation
    - detect_download_execute: curl|bash, wget|sh patterns
    - detect_obfuscation: base64 pipes, variable construction
  - Python blocks:
    - scan_python_block: exec(), eval(), __import__, subprocess, os.system, socket
    - Check for: importlib.import_module, compile+exec, pickle.loads (arbitrary code execution)
    - detect_obfuscation: exec(bytes.fromhex()), exec(__import__('base64').b64decode())
  - JavaScript blocks:
    - scan_javascript_block: eval, Function(), child_process, require('net'), require('fs')
    - Check for: vm.runInNewContext, WebAssembly (code execution), fetch to external origins
    - detect_obfuscation: String.fromCharCode, atob, unescape
  - All languages:
    - detect_download_execute: language-appropriate patterns
    - detect_obfuscation: multi-layer encoding detection
    - Check for file writes to sensitive locations: .bashrc, .profile, crontab, authorized_keys
    - Check for environment variable reads: process.env, os.environ, $ENV_VAR for sensitive keys

## Dependency and reference audit

- extract_urls: from all content (SKILL.md + references/)
- For each URL:
  - check_url_safety: HTTPS check, domain reputation
  - Flag: HTTP URLs (MEDIUM), known-malicious domains (CRITICAL), IP addresses (MEDIUM)
- For each referenced package:
  - detect_typosquatting: compare against top 1000 packages in ecosystem
    - Edit distance <= 2 from popular package: HIGH
    - Visual similarity (l/1, O/0, rn/m): HIGH
  - check_package_exists: verify package is real and active
    - Package not found: HIGH (may be dependency confusion)
    - Package archived/deprecated: LOW
    - Very low downloads (<100/week): MEDIUM (possibly malicious clone)
  - check_install_hooks: detect preinstall/postinstall scripts
    - Hooks present: flag for manual review (MEDIUM)
    - Hooks with network calls: HIGH
    - Hooks with eval/exec: CRITICAL

## File structure validation

- validate_skill_structure: skill_dir
  - Required: SKILL.md
  - Optional: references/, scripts/, examples/
  - Unexpected: anything else warrants inspection
- detect_binary_files: flag non-text files
  - Exceptions: images for documentation (.png, .jpg, .svg) — LOW
  - All other binaries: HIGH
- detect_executable_files: flag +x permission
  - Scripts (.sh, .py) with +x: MEDIUM (check if justified)
  - Other files with +x: HIGH
- detect_symlinks: check for directory escape
  - Symlink target within skill dir: LOW (informational)
  - Symlink target outside skill dir: CRITICAL (potential escape attack)
- detect_hidden_files:
  - .env: HIGH (may contain secrets)
  - .git: MEDIUM (may contain history with secrets)
  - .npmrc, .pypirc: HIGH (may contain registry tokens)
  - Other dot files: LOW (informational)
- check_file_sizes: flag files > 1MB
  - Markdown > 1MB: MEDIUM (unusually large, check for embedded data)
  - Any file > 10MB: HIGH (bloat or embedded binary data)

## Permission scope analysis

- analyze_declared_permissions: from metadata
- For each code block and reference:
  - detect_undeclared_operations: cross-reference code behavior vs declarations
    - Network access in code but not declared in requires: HIGH
    - File write outside workspace in code but risk marked "safe": HIGH
    - Command execution (subprocess, exec) but not declared: MEDIUM
- assess_permission_scope:
  - Scope proportionality: does a "documentation helper" skill really need network access?
  - Least privilege check: are requested permissions minimal for stated purpose?

## Version update audit

- diff_skill_versions: old_path (cached/previous), new_path (incoming)
- analyze_diff_risk:
  - New code blocks added: re-run full code block audit on additions
  - New URLs added: check each new URL for safety
  - Permission changes in metadata: flag any escalation
  - New binary dependencies added: flag for review
  - Removed safety disclaimers or warnings: MEDIUM
  - Changes to frontmatter name/category: MEDIUM (possible identity swap)

## Final verdict

- calculate_risk_score: from all findings
- generate_audit_report: format based on caller preference
- Verdict determination:
  - **PASS** (risk_score < 20): No CRITICAL or HIGH findings. Safe to load.
  - **CONDITIONAL** (20 <= risk_score < 50): HIGH findings present but no CRITICAL. Requires human review and explicit approval before loading.
  - **REJECT** (risk_score >= 50): CRITICAL findings present. Skill must NOT be loaded. Move to _quarantine directory with audit report attached.
- Post-verdict actions:
  - PASS: generate hash baseline for version tracking
  - CONDITIONAL: notify reviewer with findings summary
  - REJECT: quarantine skill, log rejection reason, notify admin

```