Developed by https://x.com/SlimeVerse_

Preconfigured OpenClaw website:https://www.readyclaw.org/en

SafeSkillScan

Multi-stage security scanner for AI Agent skill files (SKILL.md).

Designed to detect malicious patterns in community-contributed skill packages before they are installed into AI coding assistants (Claude Code, OpenClaw, etc.).

Pipeline Overview

Stage 0: Intake       →  Normalize, dedup, encoding/size checks
Stage 1: Rules + AST  →  Regex rules, IOC domain matching, AST analysis
Stage 2: Semantic      →  Embedding-based coherence, structural entropy
Stage 3: LLM Audit    →  Multi-model voting (Claude, GPT, Gemini)

Each stage filters sequentially. Skills rejected at an earlier stage are not re-evaluated by later stages.

Threat Classes

Quick Start

1. Install

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-scanner.txt

2. Configure

cp .env.example .env
# Edit .env and add your API keys (required for Stage 3 only)

3. Prepare Data

Place skill files in data/files/ with one directory per skill:

data/
└── files/
    ├── my-skill/
    │   └── SKILL.md
    ├── another-skill/
    │   └── SKILL.md
    └── ...

Or provide a SQLite database at data/skills.db with a skill_content table containing slug and skill_md columns.

4. Run

Single skill scan:

python -m skill_scanner scan --slug my-skill

Full scan (Stage 0-2, no API keys needed):

python -m skill_scanner scan --all --stage 2

Full pipeline with LLM audit:

python -m skill_scanner scan --all

View results:

python -m skill_scanner report --summary
python -m skill_scanner report --findings --severity CRITICAL
python -m skill_scanner report --export-csv results.csv

Batch Scanning

For large-scale scans (10k+ skills), use the batch runners:

# Stage 0-2 (deterministic + semantic)
python batch_scan.py

# Stage 3 (LLM audit, requires API keys)
python batch_scan_s3.py

Job System

Scan ad-hoc skill batches in isolation:

# Scan a .tar.gz batch
python job_scan.py input.tar.gz --name mybatch --stages 0,1,2,3 --concurrency 5

# List all jobs
python job_report.py --list

# Regenerate report
python job_report.py --job-id mybatch-abc123

Each job gets its own database and report under jobs/{job_id}/.

Rule Files

Detection rules are defined in YAML under skill_scanner/rules/:

Output

Scan results are stored in SQLite at scan_results/scan.db:

• scan_results — Per-skill verdict (PASS / REJECT / HUMAN_REVIEW)
• scan_findings — Individual findings with severity, rule_id, evidence
• llm_verdicts — Stage 3 LLM responses and reasoning

Running Tests

pytest tests/ -v

Architecture

skill_scanner/
├── config.py          # Central configuration & thresholds
├── models.py          # Pydantic data models
├── db/
│   ├── schema.py      # SQLite DDL & migrations
│   └── store.py       # CRUD operations
├── stages/
│   ├── stage0_intake.py      # Normalization & dedup
│   ├── stage1_ast.py         # AST analysis for code blocks
│   ├── stage1_rules.py       # YAML rule engine
│   ├── stage2_entropy.py     # Structural entropy
│   ├── stage2_semantic.py    # Embedding-based analysis
│   ├── stage2_aggregator.py  # Score aggregation & thresholds
│   ├── stage3_llm.py         # Multi-model LLM audit
│   └── stage3_voting.py      # Voting consensus
├── embedding/
│   ├── model_loader.py       # Sentence-transformer loader
│   └── semantic_zones.py     # Drift direction classification
├── utils/
│   ├── markdown_parser.py    # Frontmatter parsing & hashing
│   ├── text_segments.py      # Markdown segmentation
│   ├── base64_decoder.py     # Obfuscation detection
│   └── url_extractor.py      # URL extraction & classification
└── reports/
    ├── dashboard.py           # Rich console summaries
    └── export.py              # CSV/JSON exports

License

MIT