Metadata-Version: 2.4
Name: skill-vet
Version: 0.1.0
Summary: Security scanner for AI agent skills — like `npm audit` for skills
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 🔍 skill-vet

<p align="center">
  <strong>🛡️ "npm audit" for AI Agent Skills & MCP Servers.</strong><br>
  Scan third-party skill directories for malicious code and dangerous patterns <strong>before</strong> they touch your local machine.
</p>

<p align="center">
  <a href="https://pypi.org/project/skill-vet/"><img src="https://img.shields.io/pypi/v/skill-vet.svg?style=flat-square&color=blue" alt="PyPI Version"></a>
  <img src="https://img.shields.io/badge/python-3.10+-blue?style=flat-square" alt="Python">
  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License">
  <img src="https://img.shields.io/badge/dependencies-0-lightgrey?style=flat-square" alt="Zero Dependencies">
  <img src="https://img.shields.io/badge/built--in%20rules-19-orange?style=flat-square" alt="Rules">
</p>

---

[English](#why) | [中文说明](#为什么需要-skill-vet)

---

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

```bash
pip install skill-vet
```

### Basic Usage

```bash
# 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

```bash
$ 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`:

```yaml
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`:

```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

- [x] CLI & Batch scanning options
- [x] JSON and raw text reporting structures
- [x] Native GitHub Actions setup
- [x] 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](https://github.com/checkzhao8888). Feel free to learn, fork, and build upon this!
*(AI agent security requires a collective effort to thrive. Contributions are welcome!)*
