Skill Scan

Security scanner for OpenClaw skill packages. Scans skills for malicious code, evasion techniques, prompt injection, and misaligned behavior BEFORE installation. Use to audit any skill from ClawHub or local directories.

Security Scan

The package is largely coherent with a security-scanner (LLM-backed static analyzer) but contains a few noteworthy inconsistencies and prompt-injection signals and asks to modify agent configuration, so review carefully before enabling automatic integration.

Purpose & Capability

The name/description match the included functionality: a multi-layer scanner with optional LLM analysis and ClawHub integration. Requested environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, PROMPTINTEL_API_KEY, alert channel vars) are consistent with LLM scanning and alerting. One mismatch: the registry metadata says 'instruction-only / no install spec' but the package contains a full Python project (CLI, analyzers, tests, 100+ files). That isn't necessarily malicious, but it's an inconsistency you should be aware of (code will be present in the skill directory even though no platform-level installer is declared).

Instruction Scope

The SKILL.md contains explicit runtime instructions for the agent (scan-before-install workflow) and templates to insert into AGENTS.md. Option A uses strong language ('non-negotiable — never skip the scan') and recommends automatic pre-install scanning/blocking behavior. While this is plausible for a security tool, it also instructs the agent to alter its install workflow and to block installs automatically — a higher-scope action than simply providing a scanner. Additionally, automated alerting and LLM-provider auto-detection are described; the SKILL.md also includes content that triggered prompt-injection detections (see scan_findings_in_context).

Install Mechanism

No external install spec or remote download is declared (low install-mechanism risk). However, the repository includes a full Python CLI and many code files that would be written into the workspace when the skill is installed. There are no suspicious remote URLs or archive installs in the metadata, but because code is present, review the included source before running any CLI or LLM-enabled features.

Credentials

Environment variables mentioned are appropriate for the stated features: LLM provider keys for optional deep analysis (OPENAI_API_KEY, ANTHROPIC_API_KEY), a PROMPTINTEL key for an optional integration, and alert-channel variables for sending notifications. No unrelated or excessive credentials are demanded in SKILL.md or project metadata.

Persistence & Privilege

The skill suggests automatically modifying your AGENTS.md (agent instruction file) during installation to enforce pre-install scanning. That amounts to persistent changes to the agent's behavior/configuration and is outside a simple on-demand scanner's minimal scope. The skill does not set always:true, but it does recommend automatic, non-optional integration which increases its effective privilege. If you allow the skill to edit agent instructions, you should review/approve the exact changes.

Scan Findings in Context

[ignore-previous-instructions] unexpected: Pre-scan detected 'ignore previous/prior instructions' style phrasing (a common prompt-injection pattern). A security scanner describing how to insert itself into agent workflows should not include hidden or coercive override instructions; this may be present in SKILL.md or in supplied AGENTS.md templates and should be inspected for malicious phrasing or hidden characters.

[unicode-control-chars] unexpected: Pre-scan detected unicode control / invisible characters in SKILL.md content. These can be used for stealthy prompt-injection or hiding directives. If you plan to install, inspect the SKILL.md and any AGENTS.md templates for hidden characters and render them in a safe editor that can show such characters.

What to consider before installing

This package appears to be a legitimate, featureful skill-scanner, but there are some red flags you should act on before installing or enabling automatic behavior: 1) Inspect the SKILL.md and AGENTS.md templates for hidden or coercive instructions (look for 'ignore previous instructions' language and any invisible/unicode-control characters). If present, remove or sanitize those lines. 2) Review the included source files (skill_scan/ and test-fixtures/) locally or in a sandbox before running the CLI, especially if you will grant it permission to edit AGENTS.md or run LLM-enabled analysis. The code bundle contains both safe test fixtures and explicit malicious examples used for evaluation — confirming behaviour matters. 3) Be cautious about granting LLM API keys (OPENAI_API_KEY/ANTHROPIC_API_KEY) to the environment unless you trust the skill; LLM layers run arbitrary prompt content against those providers. 4) Prefer manual (on-demand) scanning over automatic installation hooks. If you choose automatic integration, require an explicit review step and backup the current AGENTS.md before allowing modifications. 5) If you accept the skill, run it initially with static analysis only (no --llm) and examine JSON output (--json) to verify the scanner's behavior; only enable alerting channels after testing. If you want, I can: (a) show the exact AGENTS.md templates included so you can inspect them, (b) list files in skill_scan/ that perform code execution or network calls, or (c) produce a sanitized AGENTS.md patch you can apply manually instead of allowing the skill to change it automatically.

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, --quiet
• 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

# 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

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)
• 1 — MEDIUM or higher (block installation)

LLM Options

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

Provider auto-detected from environment:

• OPENAI_API_KEY -> gpt-4o-mini
• ANTHROPIC_API_KEY -> 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
2. 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:

🛡️ 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 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.

## 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. 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:

skill-scan batch {skillsDir}

LLM Deep Analysis

For high-stakes installs or when pattern scan returns MEDIUM, escalate to LLM analysis:

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

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.
2. 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+
• httpx>=0.27 (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