@elliotllliu/agentshield 0.1.0 → 0.2.1

package/README.md

@@ -1,34 +1,81 @@
 # 🛡️ 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
 
 ```bash
-npx agentshield scan ./my-skill/
+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) |
+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
 
@@ -37,78 +84,172 @@ npx 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 pipelines)
+npx @elliotllliu/agentshield scan ./skill/ --json
+
+# Fail CI if score drops below threshold
+npx @elliotllliu/agentshield scan ./skill/ --fail-under 70
+
+# Disable specific rules
+npx @elliotllliu/agentshield scan ./skill/ --disable supply-chain,phone-home
 
-# JSON output (for CI/CD)
-agentshield scan ./skill/ --json
+# Only run specific rules
+npx @elliotllliu/agentshield scan ./skill/ --enable backdoor,data-exfil
 
-# Fail CI if score is below threshold
-agentshield scan ./skill/ --fail-under 70
+# Generate config files
+npx @elliotllliu/agentshield init
 
-# Shorthand (directory as first arg)
-agentshield ./skill/
+# Watch mode — re-scan on file changes
+npx @elliotllliu/agentshield watch ./skill/
+
+# Compare two versions
+npx @elliotllliu/agentshield compare ./skill-v1/ ./skill-v2/
+
+# Generate a security badge for your README
+npx @elliotllliu/agentshield badge ./skill/
 ```
 
 ## CI Integration
 
+### GitHub Action (recommended)
+
+```yaml
+# .github/workflows/security.yml
+name: Security Scan
+on: [push, pull_request]
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: elliotllliu/agentshield@main
+        with:
+          path: './skills/'
+          fail-under: '70'
+```
+
+### npx one-liner
+
 ```yaml
-# GitHub Actions
 - name: Security scan
-  run: npx agentshield scan ./skills/ --fail-under 70
+  run: npx -y @elliotllliu/agentshield scan ./skills/ --fail-under 70
+```
+
+### Action Inputs & Outputs
+
+| Input | Default | Description |
+|-------|---------|-------------|
+| `path` | `.` | Directory to scan |
+| `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

@@ -0,0 +1,129 @@
+# 🛡️ AgentShield — 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 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 内检出这些威胁。
+
+## 快速开始
+
+```bash
+npx @elliotllliu/agentshield scan ./my-skill/
+```
+
+无需安装，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 ./skill/
+
+# JSON 输出
+npx @elliotllliu/agentshield scan ./skill/ --json
+
+# 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 集成
+
+```yaml
+- uses: elliotllliu/agentshield@main
+  with:
+    path: './skills/'
+    fail-under: '70'
+```
+
+## 与其他工具对比
+
+| 功能 | 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)
+
+## 许可证
+
+MIT

package/dist/cli.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { resolve } from "path";
-import { existsSync, statSync } from "fs";
+import { resolve, join } from "path";
+import { existsSync, statSync, writeFileSync, watch as fsWatch, mkdirSync } from "fs";
 import { scan } from "./scanner/index.js";
 import { printReport } from "./reporter/terminal.js";
 import { printJsonReport } from "./reporter/json.js";
+import { generateBadgeSvg, generateBadgeMarkdown } from "./reporter/badge.js";
+import { DEFAULT_CONFIG, DEFAULT_IGNORE } from "./config.js";
 const program = new Command();
 program
     .name("agentshield")
@@ -16,27 +18,195 @@ program
     .argument("<directory>", "Target directory to scan")
     .option("--json", "Output results as JSON")
     .option("--fail-under <score>", "Exit with code 1 if score is below threshold", parseInt)
+    .option("--disable <rules>", "Comma-separated rules to disable")
+    .option("--enable <rules>", "Comma-separated rules to enable (only these)")
     .action((directory, options) => {
     const target = resolve(directory);
     if (!existsSync(target) || !statSync(target).isDirectory()) {
         console.error(`Error: "${directory}" is not a valid directory`);
         process.exit(1);
     }
-    const result = scan(target);
+    const configOverride = {};
+    if (options.disable || options.enable) {
+        configOverride.rules = {};
+        if (options.disable) {
+            configOverride.rules.disable = options.disable.split(",").map((s) => s.trim());
+        }
+        if (options.enable) {
+            configOverride.rules.enable = options.enable.split(",").map((s) => s.trim());
+        }
+    }
+    const result = scan(target, configOverride);
     if (options.json) {
         printJsonReport(result);
     }
     else {
         printReport(result);
     }
+    const threshold = options.failUnder ?? result.score;
     if (options.failUnder !== undefined && result.score < options.failUnder) {
         process.exit(1);
     }
 });
+program
+    .command("init")
+    .description("Generate .agentshield.yml and .agentshieldignore config files")
+    .argument("[directory]", "Target directory", ".")
+    .action((directory) => {
+    const target = resolve(directory);
+    if (!existsSync(target)) {
+        mkdirSync(target, { recursive: true });
+    }
+    const configPath = join(target, ".agentshield.yml");
+    const ignorePath = join(target, ".agentshieldignore");
+    if (existsSync(configPath)) {
+        console.log(`⚠️  ${configPath} already exists, skipping`);
+    }
+    else {
+        writeFileSync(configPath, DEFAULT_CONFIG);
+        console.log(`✅ Created ${configPath}`);
+    }
+    if (existsSync(ignorePath)) {
+        console.log(`⚠️  ${ignorePath} already exists, skipping`);
+    }
+    else {
+        writeFileSync(ignorePath, DEFAULT_IGNORE);
+        console.log(`✅ Created ${ignorePath}`);
+    }
+});
+program
+    .command("watch")
+    .description("Watch a directory and re-scan on file changes")
+    .argument("<directory>", "Target directory to watch")
+    .option("--json", "Output results as JSON")
+    .action((directory, options) => {
+    const target = resolve(directory);
+    if (!existsSync(target) || !statSync(target).isDirectory()) {
+        console.error(`Error: "${directory}" is not a valid directory`);
+        process.exit(1);
+    }
+    console.log(`👀 Watching ${target} for changes... (Ctrl+C to stop)\n`);
+    const runScan = () => {
+        console.clear();
+        console.log(`👀 Watching ${target} — last scan: ${new Date().toLocaleTimeString()}\n`);
+        const result = scan(target);
+        if (options.json) {
+            printJsonReport(result);
+        }
+        else {
+            printReport(result);
+        }
+    };
+    // Initial scan
+    runScan();
+    // Watch for changes
+    try {
+        const watcher = fsWatch(target, { recursive: true }, () => {
+            runScan();
+        });
+        process.on("SIGINT", () => {
+            watcher.close();
+            process.exit(0);
+        });
+    }
+    catch {
+        console.error("⚠️  fs.watch recursive not supported on this platform. Use: nodemon --exec 'agentshield scan .'");
+    }
+});
+program
+    .command("compare")
+    .description("Compare security scores between two directories or git refs")
+    .argument("<dirA>", "First directory")
+    .argument("<dirB>", "Second directory")
+    .option("--json", "Output as JSON")
+    .action((dirA, dirB, options) => {
+    const targetA = resolve(dirA);
+    const targetB = resolve(dirB);
+    for (const [label, dir] of [["A", targetA], ["B", targetB]]) {
+        if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+            console.error(`Error: directory ${label} "${dir}" is not valid`);
+            process.exit(1);
+        }
+    }
+    const resultA = scan(targetA);
+    const resultB = scan(targetB);
+    if (options.json) {
+        console.log(JSON.stringify({
+            before: { target: resultA.target, score: resultA.score, findings: resultA.findings.length },
+            after: { target: resultB.target, score: resultB.score, findings: resultB.findings.length },
+            delta: resultB.score - resultA.score,
+        }, null, 2));
+        return;
+    }
+    console.log("\n🔄 AgentShield Comparison\n");
+    console.log(`  A: ${dirA} — Score: ${resultA.score}/100 (${resultA.findings.length} findings)`);
+    console.log(`  B: ${dirB} — Score: ${resultB.score}/100 (${resultB.findings.length} findings)`);
+    console.log();
+    const delta = resultB.score - resultA.score;
+    if (delta > 0) {
+        console.log(`  ✅ Improved by ${delta} points`);
+    }
+    else if (delta < 0) {
+        console.log(`  🔴 Degraded by ${Math.abs(delta)} points`);
+    }
+    else {
+        console.log(`  ➡️  No change`);
+    }
+    // Show new findings in B that aren't in A
+    const aKeys = new Set(resultA.findings.map((f) => `${f.rule}:${f.file}:${f.line}`));
+    const newFindings = resultB.findings.filter((f) => !aKeys.has(`${f.rule}:${f.file}:${f.line}`));
+    const fixedFindings = resultA.findings.filter((f) => {
+        const bKeys = new Set(resultB.findings.map((bf) => `${bf.rule}:${bf.file}:${bf.line}`));
+        return !bKeys.has(`${f.rule}:${f.file}:${f.line}`);
+    });
+    if (newFindings.length > 0) {
+        console.log(`\n  🆕 New findings (${newFindings.length}):`);
+        for (const f of newFindings.slice(0, 10)) {
+            console.log(`     ${f.file}${f.line ? `:${f.line}` : ""} — [${f.rule}] ${f.message}`);
+        }
+    }
+    if (fixedFindings.length > 0) {
+        console.log(`\n  ✅ Fixed (${fixedFindings.length}):`);
+        for (const f of fixedFindings.slice(0, 10)) {
+            console.log(`     ${f.file}${f.line ? `:${f.line}` : ""} — [${f.rule}] ${f.message}`);
+        }
+    }
+    console.log();
+});
+program
+    .command("badge")
+    .description("Generate a security badge for your project")
+    .argument("<directory>", "Target directory to scan")
+    .option("--svg", "Output raw SVG")
+    .option("--markdown", "Output markdown badge (default)")
+    .option("-o, --output <file>", "Save SVG to file")
+    .action((directory, options) => {
+    const target = resolve(directory);
+    if (!existsSync(target) || !statSync(target).isDirectory()) {
+        console.error(`Error: "${directory}" is not a valid directory`);
+        process.exit(1);
+    }
+    const result = scan(target);
+    if (options.svg || options.output) {
+        const svg = generateBadgeSvg(result);
+        if (options.output) {
+            writeFileSync(resolve(options.output), svg);
+            console.log(`✅ Badge saved to ${options.output}`);
+        }
+        else {
+            console.log(svg);
+        }
+    }
+    else {
+        // Default: markdown
+        const md = generateBadgeMarkdown(result.score);
+        console.log(md);
+        console.log(`\nPaste this in your README.md to show the badge.`);
+    }
+});
 // Default: if first arg looks like a directory, treat as scan
 const args = process.argv.slice(2);
-if (args.length > 0 && !args[0].startsWith("-") && args[0] !== "scan" && args[0] !== "help") {
-    // Rewrite: `agentshield ./dir` → `agentshield scan ./dir`
+if (args.length > 0 && !args[0].startsWith("-") && !["scan", "init", "watch", "compare", "badge", "help"].includes(args[0])) {
     process.argv.splice(2, 0, "scan");
 }
 program.parse();