skill-vettr

# skill-vettr v2.0.3

Security scanner for third-party OpenClaw skills. Analyses source code, dependencies, and metadata before installation using tree-sitter AST parsing and regex pattern matching.

## Installation

```bash
npm install
```

This installs all Node.js dependencies, including tree-sitter `.wasm` grammar files required at runtime for AST-based analysis. The `.wasm` files are located in `node_modules` and must be present for the skill to function.

> ⚠️ **Install safety:** `npm install` runs dependency lifecycle scripts, which can execute arbitrary code. For stronger isolation, run `npm ci --ignore-scripts` — but note that tree-sitter native/WASM artifacts may not build, breaking AST analysis. Prefer installing inside a container or VM when possible.

## External Binaries

The `vet-url` and `vet-clawhub` commands invoke external binaries via `execSafe` (which uses `execFile` — no shell is spawned). Only the following commands are permitted:

| Binary | Used By | Purpose |
|--------|---------|---------|
| `git` | `vet-url` | Clone `.git` URLs (with hooks disabled) |
| `curl` | `vet-url` | Download archive URLs |
| `tar` | `vet-url` | Extract downloaded archives |
| `clawhub` | `vet-clawhub` | Fetch skills from ClawHub registry |

The `/skill:vet` command (local path vetting) requires only `node` and no external binaries.

## Commands

- `/skill:vet --path <directory>` — Vet a local skill directory
- `/skill:vet-url --url <https://...>` — Download and vet from URL
- `/skill:vet-clawhub --skill <slug>` — Fetch and vet from ClawHub

## Detection Categories

| Category | Method | Examples |
|----------|--------|----------|
| Code execution | AST | eval(), new Function(), vm.runInThisContext() |
| Shell injection | AST | exec(), execSync(), spawn("bash"), child_process imports |
| Dynamic require | AST | require(variable), require(templateString) |
| Prototype pollution | AST | __proto__ assignment |
| Prompt injection...

# skill-vettr v2.0.3

Static analysis security scanner for OpenClaw skills. Analyses code before installation to detect common threats.

## Quick Start

```bash
cd ~/.openclaw/skills/skill-scanner
npm install
npm run build
npm test
```

> ⚠️ `npm install` runs dependency lifecycle scripts (tree-sitter includes native builds). For stronger isolation, install inside a container or use `npm ci --ignore-scripts` (note: AST analysis may break without tree-sitter WASM artifacts).

## What It Does

skill-vettr scans a skill's source code, dependencies, and metadata for security issues. It uses:

- **tree-sitter AST parsing** for structural code analysis (eval, exec, spawn, dynamic require, prototype pollution, etc.)
- **Regex patterns** for things AST can't detect (prompt injection, homoglyph attacks, encoded function names)
- **Dependency analysis** for known malicious packages, suspicious prefixes, lifecycle scripts
- **Metadata analysis** for typosquatting (Levenshtein distance), dangerous permissions, blocked authors

## What It Doesn't Do

This is a heuristic scanner. It has inherent limitations:

- Cannot detect runtime-only behaviour (e.g., code that downloads malware at runtime from an innocuous-looking URL)
- AST queries can be evaded by sufficiently motivated attackers (e.g., multi-stage string construction)
- Only scans JS/TS code files — binary payloads, images, and other non-text files are skipped
- Does not sandbox or execute the target skill
- Malicious package lists are small and non-exhaustive

For high-security environments, combine with sandboxing and manual review.

## External Binaries

The `vet-url` and `vet-clawhub` commands invoke external binaries via `execSafe` (uses `execFile`, no shell spawned):

| Binary | Command | Purpose |
|--------|---------|---------|
| `git` | `vet-url` | Clone `.git` URLs (hooks disabled via `-c core.hooksPath=/dev/null`) |
| `curl` | `vet-url` | Download archive URLs (max 50 MB...