skill-security-auditor

Skill Security Auditor

A Skill security audit tool based on the "OpenClaw Minimal Security Practice Guide" and the "Security Verification and Attack-Defense Drill Manual." It conducts full lifecycle security review of OpenClaw Skills from source code to runtime, covering threat vectors such as supply chain poisoning, prompt injection payloads, malicious code patterns, and privilege escalation.

Purpose

OpenClaw Skills are an extension mechanism for Agent capabilities, loaded and executed by the Agent through /workspace/skills/{skill_name}/SKILL.md . Malicious Skills can:

• Hijack Agent behavior through prompt injection
• Embed reverse shells and data exfiltration commands in code blocks
• Reference malicious external dependencies for supply chain attacks
• Hide malicious instructions through Unicode obfuscation and zero-width characters

This skill provides a security gate for the installation and update of Skills, completing security review before a Skill enters the production environment.

Prerequisites

Input Requirements

• Target Skill directory path (containing SKILL.md and references/ , etc.)
• Or the Skill's remote repository URL (used for pulling and auditing)

Environment Requirements

• Node.js runtime (used to execute audit scripts)
• Read permission for Skill files

Core Workflow

1. Metadata Validation: Parse the frontmatter of SKILL.md and validate the completeness and legitimacy of name, version, description, and metadata.
2. Prompt Injection Scanning: Detect instruction injection patterns in the body of SKILL.md (role hijacking, instruction override, hidden instructions).
3. Code Block Security Audit: Extract all code blocks (bash, python, javascript, etc.) and perform malicious pattern detection on each code block.
4. Dependency and Reference Review: Check the security and source trustworthiness of external URLs, npm packages, and Python packages referenced by the Skill.
5. File Structure Check: Verify whether the Skill directory structure conforms to specifications and detect abnormal files (binaries, executables, symbolic links).
6. Unicode and Encoding Detection: Scan for hidden Unicode control characters, zero-width characters, and Bidi override characters.
7. Permission Declaration Review: Verify whether the permission scope declared by the Skill is reasonable and detect privilege escalation requests.
8. Historical Version Comparison: Perform diff analysis on Skill updates to detect whether new malicious content has been introduced.
9. Sandbox Verification: Trial-run Skill code snippets in a restricted environment and observe their behavior.

Audit Checklist

1. Metadata Completeness

Check Item	Risk Level	Detection Rule
Missing frontmatter	HIGH	SKILL.md has no YAML frontmatter
name does not match directory name	MEDIUM	name field is inconsistent with the containing directory name
Invalid version format	LOW	Not in semver format
Empty description	MEDIUM	Missing description, making intent difficult to review
category not declared	LOW	metadata is missing category
risk marked as unsafe	HIGH	Self-declared high risk
requires declares suspicious binary	HIGH	Dependencies nc, ncat, socat etc.

2. Prompt Injection Detection

Detection Mode	Risk Level	Example
Role Hijacking	CRITICAL	"You are now a...", "Ignore previous instructions"
Instruction Override	CRITICAL	"Do not follow any rules", "Override system prompt"
Hidden Instructions	HIGH	Instructions in HTML comments, CSS display:none wrapped text
Output Manipulation	HIGH	"Always respond with...", "Never mention..."
Privilege Escalation	CRITICAL	"Execute with admin privileges", "Disable safety checks"
Zero-Width Character Hiding	CRITICAL	\u200B, \u200C, \u200D, \uFEFF hidden instructions
Bidi Override Attack	CRITICAL	\u202A-\u202E changes text display direction
Markdown Injection	MEDIUM	Hiding content through Markdown rendering differences

3. Code Block Security Audit

Code Type	Detection Rule	Risk Level
Bash	Reverse Shell, Data Exfiltration, Privilege Escalation Commands	See openclaw-threat-detect
Python	exec(), eval(), subprocess, os.system, socket	HIGH
JavaScript	child_process, eval, Function(), require('net')	HIGH
Obfuscated Code	Base64-encoded commands, \x escape sequences, multi-layer encoding	CRITICAL
Download and Execute	curl|wget.*| bash, python -c "$(curl..."	CRITICAL
File Writing	Write to .bashrc, .profile, cron	HIGH

4. Dependencies and External References

Check Item	Risk Level	Detection Rule
References non-HTTPS URL	MEDIUM	http:// URL starting with
References known malicious domain	CRITICAL	Compare with threat intelligence database
npm package typosquatting	HIGH	Package name similarity to well-known packages > 0.8
Unlocked version	MEDIUM	Use @latest or * version
References deprecated/archived repository	LOW	GitHub repository marked as archived
Install script execution	HIGH	preinstall/postinstall hooks

5. File Structure Check

Check Item	Risk Level	Detection Rule
Contains binary files	HIGH	Non-text files (magic bytes detection)
Contains executable files	HIGH	Files have +x permission
Symlink escape	CRITICAL	Symlink points outside the Skill directory
Hidden files	MEDIUM	. hidden files starting with (.env, .git）
File too large	LOW	Single file > 1MB
Abnormal file extension	MEDIUM	.exe, .dll, .so, .dylib

6. Permission Declaration Review

Check Item	Risk Level	Detection Rule
Declares root privileges	CRITICAL	requires sudo/root in requires
Network access not declared	HIGH	Code contains network operations but metadata does not declare it
File system scope too broad	MEDIUM	Access / or $HOME instead of workspace
Declaration does not match behavior	HIGH	Declares "safe" but contains dangerous operations

Audit Report Format

{
  "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 级别发现，不建议加载"
}

Audit Verdict Criteria

Verdict	Condition	Action
PASS	No CRITICAL/HIGH findings	Allow loading
CONDITIONAL	Has HIGH but no CRITICAL	Requires manual confirmation before loading
REJECT	Has CRITICAL findings	Prohibit loading, move to quarantine zone

Collaboration with other security skills

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

Tool Categories

Category	Tools	Purpose
Metadata parsing	python-frontmatter, js-yaml	SKILL.md frontmatter parsing and validation
Prompt analysis	Regex engine, zero-width character detection	Prompt injection pattern matching
Code analysis	semgrep patterns, AST analysis	Code block security scanning
Dependency check	npm audit (concept), PyPI check	External dependency security verification
File check	file (magic), stat	Binary detection and permission verification
Encoding detection	Unicode analyzer	Hidden character and Bidi attack detection
Diff analysis	git diff, diff	Version update change review

References

• references/tools.md - Tool function signatures and parameter descriptions
• references/workflows.md - Audit process definition and decision rules