SkillScan

LLM-powered security risk analysis for OpenClaw skills. Detects malicious skills before they can steal SSH keys, exfiltrate data, or escalate privileges.

What This Does

• 7-dimension security scoring via your configured LLM model (0-100 risk score)
• Install-time blocking — risky skills are flagged or blocked before installation
• CLI audit command — scan all installed skills on demand
• Content-hash caching — scores are cached so unchanged skills aren't re-scored

Scoring Dimensions

Dimension	Weight	Description
suspicious_urls	1x	Non-well-known domains, IP-based URLs, non-standard ports
suspicious_contacts	1x	Webhook URLs, bot links, C2 communication channels
sensitive_path_access	1.5x	References to ~/.ssh, ~/.aws, credentials, etc.
exfiltration_intent	2x	Read sensitive files → send to external services
description_consistency	1.5x	Bait-and-switch detection (name vs actual instructions)
permission_escalation	2x	Config modification, sandbox disable, privilege escalation
obfuscation	1x	Base64 payloads, hidden instructions, unicode tricks

Risk Levels

Level	Score Range	Behavior
safe	0-29	No action
caution	30-59	Logged for review
danger	60-79	Warning shown (configurable)
critical	80-100	Blocked (if blockThreshold set)

Installation

Prerequisites

• An existing OpenClaw repository checkout
• Git

Install (Linux/macOS)

cd /path/to/openclaw
bash /path/to/skill-security-patch/install.sh

Install (Windows PowerShell)

cd C:\path\to\openclaw
.\path\to\skill-security-patch\install.ps1

Manual Install

1. Copy new files into the openclaw repo:

   new-files/src/agents/skills/security-score.ts      → src/agents/skills/security-score.ts
   new-files/src/agents/skills/security-score.test.ts  → src/agents/skills/security-score.test.ts
   new-files/src/config/config.skills-security.test.ts → src/config/config.skills-security.test.ts
   

2. Apply the patch:

   cd /path/to/openclaw
   git apply /path/to/skill-security-patch/patches/skill-security-scoring.patch

3. If the patch fails (due to version differences), apply with 3-way merge:

   git apply --3way /path/to/skill-security-patch/patches/skill-security-scoring.patch

Configuration

Add to your OpenClaw config:

skills:
  security:
    warnThreshold: 60    # Show warning when risk score >= 60
    blockThreshold: 85   # Block installation when risk score >= 85

• warnThreshold — default: 60. Set to 0 to warn on everything, or 100 to disable.
• blockThreshold — no default (disabled). Set this to enable install-time blocking.

Usage

CLI Audit

# Audit all installed skills
openclaw skills audit

# Verbose: show per-dimension scores and evidence
openclaw skills audit --verbose

# Audit a specific skill
openclaw skills audit --skill github

# Force re-scoring (bypass cache)
openclaw skills audit --no-cache

# JSON output
openclaw skills audit --json

Automatic Install-Time Scanning

When installing a skill via openclaw, the security scoring runs automatically:

• If score >= warnThreshold → warning is shown, install continues
• If score >= blockThreshold → install is blocked
• If no LLM config is available → scoring is skipped gracefully

Files Modified

File	Change
src/agents/skills/types.ts	Added SkillSecurityScore and related types
src/config/types.skills.ts	Added SkillsSecurityConfig type
src/config/zod-schema.ts	Added security field to skills schema
src/agents/skills-install.ts	Integrated security scoring into install flow
src/cli/skills-cli.ts	Added openclaw skills audit subcommand

Files Added

File	Purpose
src/agents/skills/security-score.ts	Core scoring engine (LLM call + cache + hash)
src/agents/skills/security-score.test.ts	Unit tests for scoring engine
src/config/config.skills-security.test.ts	Config schema validation tests

Running Tests

npx vitest run src/agents/skills/security-score.test.ts src/config/config.skills-security.test.ts src/agents/skills-install.test.ts

Architecture

User installs skill → installSkill()
                         ├── Static scanner (regex rules)     ← existing
                         └── SkillScan LLM scoring (new)      ← this patch
                               ├── SHA-256 content hash
                               ├── Cache check (~/.openclaw/cache/skill-security-scores/)
                               ├── LLM 7-dimension analysis
                               ├── Weighted risk score (0-100)
                               └── warn / block decision

User runs audit → openclaw skills audit
                    ├── Load all skill entries
                    ├── Read SKILL.md content
                    ├── SkillScan scores each via LLM (with cache)
                    └── Render risk report (table + risk bars)

License

Same as OpenClaw.