@elliotllliu/agentshield 0.2.0 → 0.2.1

package/README.md

@@ -1,8 +1,25 @@
 # 🛡️ AgentShield
 
-Security scanner for AI agent skills, MCP servers, and plugins.
+**Security scanner for AI agent skills, MCP servers, and plugins.**
 
-Catch data exfiltration, backdoors, privilege escalation, and supply chain vulnerabilities **before** they reach your agents.
+[![npm](https://img.shields.io/npm/v/@elliotllliu/agentshield)](https://www.npmjs.com/package/@elliotllliu/agentshield)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Catch data exfiltration, backdoors, privilege escalation, credential leaks, and supply chain vulnerabilities **before** they reach your AI agents.
+
+> **We scanned the top ClawHub skill repos — the average security score was 47/100.** [Read the full report →](docs/clawhub-security-report.md)
+
+## Why AgentShield?
+
+AI agents install and execute third-party skills, MCP servers, and plugins with minimal security review. A single malicious skill can:
+
+- 🔑 **Steal credentials** — SSH keys, AWS secrets, API tokens
+- 📤 **Exfiltrate data** — read sensitive files and send them to external servers
+- 💀 **Open backdoors** — `eval()`, reverse shells, dynamic code execution
+- ⛏️ **Mine crypto** — hijack compute for cryptocurrency mining
+- 🕵️ **Bypass permissions** — claim "read-only" but execute shell commands
+
+AgentShield catches these patterns with **16 security rules** in under 50ms.
 
 ## Quick Start
 
@@ -10,27 +27,55 @@ Catch data exfiltration, backdoors, privilege escalation, and supply chain vulne
 npx @elliotllliu/agentshield scan ./my-skill/
 ```
 
-## What It Detects
-
-| Rule | Severity | Description |
-|------|----------|-------------|
-| `data-exfil` | 🔴 Critical | Reads sensitive files (SSH keys, credentials) + sends HTTP requests |
-| `backdoor` | 🔴 Critical | `eval()`, `new Function()`, `child_process.exec()` with dynamic input |
-| `reverse-shell` | 🔴 Critical | Outbound socket connections piped to shell |
-| `crypto-mining` | 🔴 Critical | Mining pool connections, known miners (xmrig, coinhive) |
-| `credential-hardcode` | 🔴 Critical | Hardcoded AWS keys, GitHub PATs, Stripe keys, private keys |
-| `env-leak` | 🔴 Critical | `process.env` access + outbound HTTP (environment variable exfil) |
-| `obfuscation` | 🔴 Critical | base64 + eval combos, hex-encoded strings, `String.fromCharCode` |
-| `typosquatting` | 🔴 Critical | Suspicious npm package names (e.g. `1odash` instead of `lodash`) |
-| `hidden-files` | 🔴 Critical | `.env` files with secrets committed to repo |
-| `network-ssrf` | 🟡 Warning | User-controlled URLs in fetch, AWS metadata endpoint access |
-| `privilege` | 🟡 Warning | SKILL.md declares `read` but code calls `exec` |
-| `supply-chain` | 🟡 Warning | Known CVEs in npm dependencies (`npm audit`) |
-| `sensitive-read` | 🟡 Warning | Accesses `~/.ssh/id_rsa`, `~/.aws/credentials`, etc. |
-| `excessive-perms` | 🟡 Warning | Too many or dangerous permissions in SKILL.md |
-| `phone-home` | 🟡 Warning | Periodic timers + HTTP requests (beacon/heartbeat pattern) |
-| `mcp-manifest` | 🟡 Warning | MCP server: wildcard perms, undeclared capabilities, suspicious tool descriptions |
-| `mcp-manifest` | 🟡 Warning | MCP server tool/resource declarations vs actual code behavior |
+No installation required. Works with Node.js 18+.
+
+## What It Detects — 16 Security Rules
+
+### 🔴 Critical (auto-fail)
+
+| Rule | Detects |
+|------|---------|
+| `data-exfil` | Reads sensitive files + sends HTTP requests (exfiltration pattern) |
+| `backdoor` | `eval()`, `new Function()`, `child_process.exec()` with dynamic input |
+| `reverse-shell` | Outbound socket connections piped to `/bin/sh` |
+| `crypto-mining` | Mining pool connections, xmrig, coinhive patterns |
+| `credential-hardcode` | Hardcoded AWS keys (`AKIA...`), GitHub PATs (`ghp_...`), Stripe keys |
+| `env-leak` | `process.env` secrets + outbound HTTP (environment variable theft) |
+| `obfuscation` | `eval(atob(...))`, hex strings, `String.fromCharCode` obfuscation |
+| `typosquatting` | Suspicious npm names: `1odash` → `lodash`, `axois` → `axios` |
+| `hidden-files` | `.env` files with `PASSWORD`, `SECRET`, `API_KEY` committed to repo |
+
+### 🟡 Warning (review recommended)
+
+| Rule | Detects |
+|------|---------|
+| `network-ssrf` | User-controlled URLs in fetch, AWS metadata endpoint access |
+| `privilege` | SKILL.md permissions vs actual code behavior mismatch |
+| `supply-chain` | Known CVEs in npm dependencies (`npm audit`) |
+| `sensitive-read` | Access to `~/.ssh/id_rsa`, `~/.aws/credentials`, `~/.kube/config` |
+| `excessive-perms` | Too many or dangerous permissions in SKILL.md |
+| `phone-home` | `setInterval` + HTTP requests (beacon/C2 heartbeat pattern) |
+| `mcp-manifest` | MCP server: wildcard perms, undeclared capabilities, suspicious tool descriptions |
+
+## Real-World Results
+
+We scanned the **top 9 ClawHub skill repositories** (700K+ combined installs):
+
+| Repository | Installs | Score | Risk |
+|------------|----------|-------|------|
+| vercel-labs/agent-skills | 157K | 🔴 0/100 | Critical — deploy scripts with `$(curl)` command substitution |
+| obra/superpowers | 94K | 🔴 0/100 | Critical — dynamic code execution in render scripts |
+| coreyhaines31/marketingskills | 42K | 🔴 0/100 | Critical — 122 critical findings (CRM credential patterns) |
+| anthropics/skills | 36K | 🔴 35/100 | Critical — template with exec() |
+| expo/skills | 11K | 🔴 5/100 | Critical — fetch script reads env vars |
+| remotion-dev/skills | 140K | 🟡 80/100 | Moderate — minor warnings |
+| google-labs-code/stitch-skills | 63K | ✅ 100/100 | Clean |
+| supercent-io/skills-template | 106K | ✅ 100/100 | Clean |
+| squirrelscan/skills | 34K | ✅ 100/100 | Clean |
+
+**Average score: 47/100** — over half of popular skill repos have critical security findings.
+
+[📊 Full security report →](docs/clawhub-security-report.md)
 
 ## Example Output
 
@@ -39,80 +84,47 @@ npx @elliotllliu/agentshield scan ./my-skill/
 📁 Scanned: ./my-skill/ (3 files, 44 lines)
 
 🔴 CRITICAL (3)
-  ├─ index.ts:13 — [data-exfil] Reads sensitive data and sends HTTP request — possible exfiltration
+  ├─ index.ts:13 — [data-exfil] Reads sensitive data and sends HTTP request
   ├─ index.ts:20 — [backdoor] eval() with dynamic input
-  └─ index.ts:25 — [backdoor] child_process.exec() — use execFile instead
+  └─ backdoor.sh:6 — [backdoor] shell eval with variable
 
 🟡 WARNING (2)
   ├─ index.ts:23 — [privilege] Code uses 'exec' but SKILL.md doesn't declare it
   └─ index.ts:6  — [sensitive-read] Accesses SSH private key
 
-🟢 INFO (1)
-  └─ SKILL.md — [privilege] Detected capabilities: exec, read, web_fetch
-
 ✅ Score: 0/100 (Critical Risk)
+⏱  16ms
 ```
 
 ## Usage
 
 ```bash
 # Scan a directory
-agentshield scan ./path/to/skill/
+npx @elliotllliu/agentshield scan ./path/to/skill/
 
-# JSON output (for CI/CD)
-agentshield scan ./skill/ --json
+# JSON output (for CI/CD pipelines)
+npx @elliotllliu/agentshield scan ./skill/ --json
 
-# Fail CI if score is below threshold
-agentshield scan ./skill/ --fail-under 70
+# Fail CI if score drops below threshold
+npx @elliotllliu/agentshield scan ./skill/ --fail-under 70
 
 # Disable specific rules
-agentshield scan ./skill/ --disable supply-chain,phone-home
+npx @elliotllliu/agentshield scan ./skill/ --disable supply-chain,phone-home
 
 # Only run specific rules
-agentshield scan ./skill/ --enable backdoor,data-exfil
-
-# Shorthand (directory as first arg)
-agentshield ./skill/
+npx @elliotllliu/agentshield scan ./skill/ --enable backdoor,data-exfil
 
 # Generate config files
-agentshield init
+npx @elliotllliu/agentshield init
 
-# Watch mode (re-scan on changes)
-agentshield watch ./skill/
+# Watch mode — re-scan on file changes
+npx @elliotllliu/agentshield watch ./skill/
 
 # Compare two versions
-agentshield compare ./skill-v1/ ./skill-v2/
-```
-
-## Configuration
-
-Create `.agentshield.yml` in your project (or run `agentshield init`):
-
-```yaml
-rules:
-  disable:
-    - supply-chain    # skip npm audit
-    - phone-home      # allow periodic HTTP
-
-severity:
-  sensitive-read: info   # downgrade to info
-
-failUnder: 70   # CI threshold
+npx @elliotllliu/agentshield compare ./skill-v1/ ./skill-v2/
 
-ignore:
-  - "tests/**"
-  - "*.test.ts"
-```
-
-### `.agentshieldignore`
-
-Exclude files from scanning (same syntax as `.gitignore`):
-
-```
-node_modules/
-dist/
-*.test.ts
-__tests__/
+# Generate a security badge for your README
+npx @elliotllliu/agentshield badge ./skill/
 ```
 
 ## CI Integration
@@ -141,55 +153,103 @@ jobs:
   run: npx -y @elliotllliu/agentshield scan ./skills/ --fail-under 70
 ```
 
-### Action Inputs
+### Action Inputs & Outputs
 
 | Input | Default | Description |
 |-------|---------|-------------|
 | `path` | `.` | Directory to scan |
-| `fail-under` | *(none)* | Fail if score is below threshold (0-100) |
-| `format` | `terminal` | Output format: `terminal` or `json` |
-
-### Action Outputs
+| `fail-under` | — | Fail if score < threshold (0-100) |
+| `format` | `terminal` | `terminal` or `json` |
 
 | Output | Description |
 |--------|-------------|
 | `score` | Security score (0-100) |
 | `findings` | Number of findings |
 
+## Configuration
+
+Create `.agentshield.yml` (or run `agentshield init`):
+
+```yaml
+rules:
+  disable:
+    - supply-chain    # skip npm audit
+    - phone-home      # allow periodic HTTP
+
+severity:
+  sensitive-read: info   # downgrade to info
+
+failUnder: 70   # CI threshold
+
+ignore:
+  - "tests/**"
+  - "*.test.ts"
+```
+
+### `.agentshieldignore`
+
+```
+node_modules/
+dist/
+*.test.ts
+__tests__/
+```
+
 ## Scoring
 
-Starts at 100, deducts per finding:
+| Severity | Points Deducted |
+|----------|----------------|
+| 🔴 Critical | -25 |
+| 🟡 Warning | -10 |
+| 🟢 Info | 0 |
+
+| Score | Risk Level | Recommendation |
+|-------|------------|----------------|
+| 90-100 | ✅ Low Risk | Safe to install |
+| 70-89 | 🟡 Moderate | Review warnings |
+| 40-69 | 🟠 High Risk | Investigate before using |
+| 0-39 | 🔴 Critical | Do not install |
+
+## Supported Platforms
+
+- **AI Agent Skills** — OpenClaw, Codex, Claude Code
+- **MCP Servers** — Model Context Protocol tool servers
+- **npm Packages** — any npm package with executable code
+- **General** — any directory with JS/TS/Python/Shell code
+
+### Supported File Types
 
-| Severity | Deduction |
+| Language | Extensions |
 |----------|-----------|
-| Critical | -25 |
-| Warning | -10 |
-| Info | 0 |
-
-| Score | Risk Level |
-|-------|------------|
-| 90-100 | Low Risk ✅ |
-| 70-89 | Moderate Risk 🟡 |
-| 40-69 | High Risk 🟠 |
-| 0-39 | Critical Risk 🔴 |
-
-## Supported File Types
-
-- **JavaScript/TypeScript**: `.js`, `.ts`, `.mjs`, `.cjs`, `.tsx`, `.jsx`
-- **Python**: `.py`
-- **Shell**: `.sh`, `.bash`, `.zsh`
-- **Config**: `.json`, `.yaml`, `.yml`, `.toml`
-- **Docs**: `SKILL.md` (permission analysis)
-
-## Roadmap
-
-- [ ] AST-based analysis (tree-sitter for multi-language support)
-- [ ] MCP server manifest validation
-- [ ] Custom rule plugins
-- [ ] `agentshield init` — generate security policy
-- [ ] Sarif output for GitHub Code Scanning
-- [ ] Python `pip-audit` integration
-- [ ] Watch mode for development
+| JavaScript/TypeScript | `.js`, `.ts`, `.mjs`, `.cjs`, `.tsx`, `.jsx` |
+| Python | `.py` |
+| Shell | `.sh`, `.bash`, `.zsh` |
+| Config | `.json`, `.yaml`, `.yml`, `.toml` |
+| Docs | `SKILL.md` (permission analysis) |
+
+## Comparison with Other Tools
+
+| Feature | AgentShield | npm audit | Snyk | ESLint Security |
+|---------|------------|-----------|------|-----------------|
+| AI skill/MCP specific rules | ✅ | ❌ | ❌ | ❌ |
+| Data exfiltration detection | ✅ | ❌ | ❌ | ❌ |
+| Permission mismatch (SKILL.md) | ✅ | ❌ | ❌ | ❌ |
+| Credential hardcode detection | ✅ | ❌ | ✅ | ✅ |
+| Supply chain CVEs | ✅ | ✅ | ✅ | ❌ |
+| Zero config | ✅ | ✅ | ❌ | ❌ |
+| No API key required | ✅ | ✅ | ❌ | ✅ |
+| < 50ms scan time | ✅ | ❌ | ❌ | ❌ |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add new rules.
+
+## Links
+
+- 📦 [npm](https://www.npmjs.com/package/@elliotllliu/agentshield)
+- 📖 [Rule Documentation](docs/rules.md)
+- 📊 [ClawHub Security Report](docs/clawhub-security-report.md)
+- 🇨🇳 [中文 README](README.zh-CN.md)
 
 ## License
 

package/README.zh-CN.md

@@ -1,8 +1,23 @@
-# 🛡️ AgentShield
+# 🛡️ AgentShield — AI Agent 安全扫描器
 
-AI Agent 技能/插件安全扫描器
+[![npm](https://img.shields.io/npm/v/@elliotllliu/agentshield)](https://www.npmjs.com/package/@elliotllliu/agentshield)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-在安装第三方 AI 技能之前，扫描数据窃取、后门、权限越界和供应链漏洞。
+专为 AI Agent 技能、MCP Server、插件设计的安全扫描工具。在安装第三方扩展之前，检测数据窃取、后门、凭证泄露和供应链漏洞。
+
+> **我们扫描了 ClawHub 热门 skill 仓库 — 平均安全分仅 47/100。** [查看完整报告 →](docs/clawhub-security-report.md)
+
+## 为什么需要 AgentShield？
+
+AI Agent 会安装并执行第三方技能和插件，安全审查几乎为零。一个恶意 skill 就能：
+
+- 🔑 **偷凭证** — SSH 密钥、AWS Secret、API Token
+- 📤 **外泄数据** — 读取敏感文件发送到外部服务器
+- 💀 **植入后门** — eval()、反弹 Shell、动态代码执行
+- ⛏️ **挖矿** — 利用你的算力挖加密货币
+- 🕵️ **越权** — 声称只读但实际执行 Shell 命令
+
+AgentShield 用 **16 条安全规则**在 50ms 内检出这些威胁。
 
 ## 快速开始
 
@@ -10,37 +25,77 @@ AI Agent 技能/插件安全扫描器
 npx @elliotllliu/agentshield scan ./my-skill/
 ```
 
-## 检测能力
-
-| 规则 | 级别 | 说明 |
-|------|------|------|
-| `data-exfil` | 🔴 严重 | 读取敏感文件 + 发送 HTTP 请求（数据外泄） |
-| `backdoor` | 🔴 严重 | `eval()`、`exec()`、动态代码执行 |
-| `reverse-shell` | 🔴 严重 | Socket 外连 + Shell 管道（反弹 Shell） |
-| `crypto-mining` | 🔴 严重 | 挖矿池连接、已知挖矿程序 |
-| `credential-hardcode` | 🔴 严重 | 硬编码 AWS Key、GitHub PAT、Stripe Key |
-| `env-leak` | 🔴 严重 | 环境变量读取 + HTTP 外发 |
-| `obfuscation` | 🔴 严重 | base64+eval 混淆、十六进制编码 |
-| `typosquatting` | 🔴 严重 | npm 包名拼写仿冒（如 `1odash`） |
-| `hidden-files` | 🔴 严重 | `.env` 文件包含明文密钥 |
-| `network-ssrf` | 🟡 警告 | 用户可控 URL、SSRF、AWS 元数据端点 |
-| `privilege` | 🟡 警告 | SKILL.md 声明权限 vs 代码实际行为不匹配 |
-| `supply-chain` | 🟡 警告 | npm 依赖已知 CVE 漏洞 |
-| `sensitive-read` | 🟡 警告 | 读取 SSH 密钥、AWS 凭证等 |
-| `excessive-perms` | 🟡 警告 | 权限声明过多或过于危险 |
-| `phone-home` | 🟡 警告 | 定时器 + HTTP 请求（心跳/信标模式） |
+无需安装，Node.js 18+ 即可运行。
+
+## 16 条安全规则
+
+### 🔴 严重（自动判定不安全）
+
+| 规则 | 检测内容 |
+|------|----------|
+| `data-exfil` | 读敏感文件 + 发 HTTP 请求（数据外泄模式） |
+| `backdoor` | `eval()`、`exec()`、动态代码执行 |
+| `reverse-shell` | Socket 外连 + Shell 管道 |
+| `crypto-mining` | 矿池连接、xmrig、coinhive |
+| `credential-hardcode` | 硬编码 AWS Key、GitHub PAT、Stripe Key |
+| `env-leak` | 环境变量 + HTTP 外发 |
+| `obfuscation` | base64+eval、十六进制混淆 |
+| `typosquatting` | npm 包名仿冒（`1odash` → `lodash`） |
+| `hidden-files` | `.env` 明文密钥 |
+
+### 🟡 警告（建议审查）
+
+| 规则 | 检测内容 |
+|------|----------|
+| `network-ssrf` | 用户可控 URL、SSRF |
+| `privilege` | SKILL.md 声明 vs 代码实际行为不匹配 |
+| `supply-chain` | npm 依赖已知 CVE |
+| `sensitive-read` | 读取 SSH 密钥、AWS 凭证 |
+| `excessive-perms` | 权限声明过多 |
+| `phone-home` | 定时器 + HTTP 心跳 |
+| `mcp-manifest` | MCP Server 通配权限、可疑工具描述 |
+
+## 真实扫描数据
+
+我们扫了 ClawHub **Top 9 热门 skill 仓库**（总安装量 70 万+）：
+
+| 仓库 | 安装量 | 分数 | 风险 |
+|------|--------|------|------|
+| vercel-labs/agent-skills | 157K | 🔴 0/100 | deploy 脚本有 `$(curl)` 命令替换 |
+| obra/superpowers | 94K | 🔴 0/100 | 渲染脚本有动态代码执行 |
+| coreyhaines31/marketingskills | 42K | 🔴 0/100 | 122 个 critical（CRM 凭证模式） |
+| anthropics/skills | 36K | 🔴 35/100 | 模板有 exec() |
+| google-labs-code/stitch-skills | 63K | ✅ 100/100 | 干净 |
+| supercent-io/skills-template | 106K | ✅ 100/100 | 干净 |
+
+**平均分：47/100** — 超半数热门 skill 有严重安全隐患。
 
 ## 使用方法
 
 ```bash
 # 扫描目录
-npx @elliotllliu/agentshield scan ./path/to/skill/
+npx @elliotllliu/agentshield scan ./skill/
 
-# JSON 输出（适用于 CI/CD）
+# JSON 输出
 npx @elliotllliu/agentshield scan ./skill/ --json
 
-# CI 门禁：分数低于阈值则失败
+# CI 门禁
 npx @elliotllliu/agentshield scan ./skill/ --fail-under 70
+
+# 禁用特定规则
+npx @elliotllliu/agentshield scan ./skill/ --disable supply-chain
+
+# 初始化配置
+npx @elliotllliu/agentshield init
+
+# 实时监控
+npx @elliotllliu/agentshield watch ./skill/
+
+# 版本对比
+npx @elliotllliu/agentshield compare ./v1/ ./v2/
+
+# 生成安全徽章
+npx @elliotllliu/agentshield badge ./skill/
 ```
 
 ## GitHub Actions 集成
@@ -52,14 +107,22 @@ npx @elliotllliu/agentshield scan ./skill/ --fail-under 70
     fail-under: '70'
 ```
 
-## 安全评分
+## 与其他工具对比
 
-| 分数 | 风险等级 |
-|------|----------|
-| 90-100 | 低风险 ✅ |
-| 70-89 | 中等风险 🟡 |
-| 40-69 | 高风险 🟠 |
-| 0-39 | 严重风险 🔴 |
+| 功能 | AgentShield | npm audit | Snyk | ESLint |
+|------|------------|-----------|------|--------|
+| AI Skill/MCP 专用规则 | ✅ | ❌ | ❌ | ❌ |
+| 数据外泄检测 | ✅ | ❌ | ❌ | ❌ |
+| 权限不匹配检测 | ✅ | ❌ | ❌ | ❌ |
+| 零配置 | ✅ | ✅ | ❌ | ❌ |
+| < 50ms 扫描 | ✅ | ❌ | ❌ | ❌ |
+
+## 链接
+
+- 📦 [npm](https://www.npmjs.com/package/@elliotllliu/agentshield)
+- 📖 [规则文档](docs/rules.md)
+- 📊 [ClawHub 安全报告](docs/clawhub-security-report.md)
+- 🇬🇧 [English README](README.md)
 
 ## 许可证
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elliotllliu/agentshield",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Security scanner for AI agent skills, MCP servers, and plugins",
   "type": "module",
   "bin": {
@@ -12,7 +12,34 @@
     "test": "node --import tsx --test tests/**/*.test.ts",
     "prepublishOnly": "npm run build"
   },
-  "keywords": ["security", "ai-agent", "skill", "mcp", "scanner", "audit", "openclaw"],
+  "keywords": [
+    "security",
+    "scanner",
+    "ai-agent",
+    "skill",
+    "mcp",
+    "plugin",
+    "vulnerability",
+    "audit",
+    "backdoor",
+    "data-exfiltration",
+    "credential-leak",
+    "static-analysis",
+    "codex",
+    "claude",
+    "openai",
+    "github-action",
+    "cli",
+    "npm",
+    "ai-safety",
+    "supply-chain",
+    "reverse-shell",
+    "typosquatting",
+    "ssrf",
+    "openclaw",
+    "clawhub",
+    "model-context-protocol"
+  ],
   "author": "Elliot Liu",
   "license": "MIT",
   "dependencies": {
@@ -29,5 +56,17 @@
   "engines": {
     "node": ">=18"
   },
-  "files": ["dist", "README.md", "LICENSE"]
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elliotllliu/agentshield.git"
+  },
+  "bugs": {
+    "url": "https://github.com/elliotllliu/agentshield/issues"
+  },
+  "homepage": "https://github.com/elliotllliu/agentshield#readme"
 }