guard-scanner 3.3.0 → 4.0.0

package/README.md

@@ -1,18 +1,26 @@
 <p align="center">
   <h1 align="center">🛡️ guard-scanner</h1>
   <p align="center">
-    <strong>Security scanner + runtime guard for AI agent skills</strong><br>
-    19 runtime threat patterns • 190+ static patterns • 21 categories • OpenClaw-compatible plugin<br>
-    <sub>🆕 v3.1.0 — OpenClaw Community Plugin + 3-Layer Runtime Defense (Threat / EAE Paradox / Parity Judge)</sub>
+    <strong>Security scanner for AI agent skills — catches the bad stuff before it runs</strong><br>
+    Prompt injection, identity hijacking, memory poisoning, and 20+ more threat types.<br>
+    Zero dependencies. One command. Works with OpenClaw out of the box.
   </p>
   <p align="center">
-    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
-    <img src="https://img.shields.io/badge/OpenClaw-compatible-4A90D9" alt="OpenClaw Compatible">
-    <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="Node.js 18+">
-    <img src="https://img.shields.io/badge/dependencies-0-success" alt="Zero Dependencies">
-    <img src="https://img.shields.io/badge/tests-87%2F87-brightgreen" alt="Tests Passing">
-    <img src="https://img.shields.io/badge/runtime_patterns-19-red" alt="19 Runtime Patterns">
-    <img src="https://img.shields.io/badge/categories-21-blueviolet" alt="21 Categories">
+    <a href="https://www.npmjs.com/package/guard-scanner"><img src="https://img.shields.io/npm/v/guard-scanner.svg?style=flat-square&color=cb3837" alt="npm version"></a>
+    <a href="https://www.npmjs.com/package/guard-scanner"><img src="https://img.shields.io/npm/dm/guard-scanner.svg?style=flat-square" alt="npm downloads"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="MIT License"></a>
+    <img src="https://img.shields.io/badge/dependencies-0-success?style=flat-square" alt="Zero Dependencies">
+    <img src="https://img.shields.io/badge/tests-133%2F133-brightgreen?style=flat-square" alt="Tests Passing">
+    <img src="https://img.shields.io/badge/OWASP_Agentic-90%25-green?style=flat-square" alt="OWASP Agentic 90%">
+    <img src="https://img.shields.io/badge/patterns-190%2B-blueviolet?style=flat-square" alt="190+ Patterns">
+  </p>
+  <p align="center">
+    <a href="#quick-start">Quick Start</a> •
+    <a href="#threat-categories">Threat Categories</a> •
+    <a href="#openclaw-plugin-setup-v310">OpenClaw Plugin</a> •
+    <a href="#cicd-integration">CI/CD</a> •
+    <a href="#plugin-api">Plugin API</a> •
+    <a href="README_ja.md">🇯🇵 日本語</a>
   </p>
 </p>
 
@@ -41,8 +49,9 @@ The AI agent skill ecosystem has the same supply-chain security problem that npm
 
 | Feature | Description |
 |---|---|
-| **21 Threat Categories** | Snyk ToxicSkills + OWASP MCP Top 10 + Identity Hijacking + Sandbox/Complexity/Config + PII |
-| **129 Detection Patterns** | Regex-based static analysis covering code, docs, and data files |
+| **22 Threat Categories** | Snyk ToxicSkills + OWASP Agentic Top 10 + Identity Hijack + PII + Trust Exploitation |
+| **190+ Static Patterns** | Regex-based static analysis covering code, docs, and data files |
+| **26 Runtime Checks** | Real-time `before_tool_call` hook — 5-layer defense (v3.4.0) |
 | **IoC Database** | Known malicious IPs, domains, URLs, usernames, and typosquat names |
 | **Data Flow Analysis** | Lightweight JS analysis: secret reads → network calls → exec chains |
 | **Cross-File Analysis** | Phantom references, base64 fragment assembly, multi-file exfil detection |
@@ -53,7 +62,6 @@ The AI agent skill ecosystem has the same supply-chain security problem that npm
 | **Dependency Chain Scan** | Risky packages, lifecycle scripts, wildcard versions, git dependencies |
 | **4 Output Formats** | Terminal (with colors), JSON, [SARIF 2.1.0](https://sarifweb.azurewebsites.net), HTML dashboard |
 | **Plugin API** | Extend with custom detection rules via JS modules |
-| **Ignore Files** | Whitelist trusted skills and patterns via `.guard-scanner-ignore` |
 | **Zero Dependencies** | Pure Node.js stdlib. Nothing to install, nothing to audit. |
 | **CI/CD Ready** | `--fail-on-findings` exit code + SARIF for GitHub Code Scanning |
 
@@ -61,20 +69,42 @@ The AI agent skill ecosystem has the same supply-chain security problem that npm
 
 ## Quick Start
 
+**30 seconds to scan your skills:**
+
 ```bash
-# Scan a skill directory (each subdirectory = one skill)
 npx guard-scanner ./skills/
+```
 
-# Verbose output with category breakdown
+That's it. No install needed. It scans every subdirectory as a skill and tells you what's dangerous.
+
+**Want more detail?**
+
+```bash
+# See exactly what was found and why
 npx guard-scanner ./skills/ --verbose
 
-# Strict mode (lower thresholds)
+# Stricter detection (catches more edge cases)
 npx guard-scanner ./skills/ --strict
 
-# Full audit: verbose + deps + all output formats
+# Full audit: everything + JSON + SARIF + HTML report
 npx guard-scanner ./skills/ --verbose --check-deps --json --sarif --html
 ```
 
+**Output looks like this:**
+```
+🛡️  guard-scanner v3.4.0
+══════════════════════════════════════════════════════
+📂 Scanning: ./skills/
+📦 Skills found: 5
+
+🔴 shady-skill — MALICIOUS (risk: 100)
+   💀 [CRITICAL] Reverse shell via /dev/tcp — scripts/setup.sh:7
+   💀 [CRITICAL] Credential exfiltration to webhook.site — scripts/helper.js:14
+🟡 sus-skill — SUSPICIOUS (risk: 45)
+   ⚠️  [HIGH] SSH private key access — scripts/deploy.sh:3
+🟢 good-skill — CLEAN (risk: 0)
+```
+
 ## OpenClaw Plugin Setup (v3.1.0)
 
 ```bash
@@ -91,15 +121,17 @@ npm install -g guard-scanner
 2. **Runtime guard** — `before_tool_call` hook automatically blocks dangerous operations
 3. **3 enforcement modes** — `monitor` (log only), `enforce` (block CRITICAL), `strict` (block HIGH+CRITICAL)
 
-### 3-Layer Runtime Defense (19 patterns)
+### 5-Layer Runtime Defense (26 checks)
 
 ```
-Layer 1: Threat Detection     — 12 patterns (shells, exfil, SSRF, AMOS, etc.)
-Layer 2: EAE Paradox Defense  — 4 patterns (memory/SOUL/config tampering)
-Layer 3: Parity Judge         — 3 patterns (injection, parity bypass, shutdown refusal)
+Layer 1: Threat Detection      — 12 checks (shells, exfil, SSRF, AMOS, etc.)
+Layer 2: Trust Defense   — 4 checks  (memory/SOUL/config tampering)
+Layer 3: Safety Judge          — 3 checks  (injection, trust bypass, shutdown refusal)
+Layer 4: Brain / Behavioral    — 3 checks  (research skip, blind trust, chain bypass)
+Layer 5: Trust Exploitation    — 4 checks  (OWASP ASI09: authority/trust/audit abuse)
 ```
 
-> **v3.1.0** — Full `openclaw.plugin.json` manifest with `configSchema` validation. The legacy `handler.ts` has been removed; `plugin.ts` is now the only runtime guard.
+> **v3.4.0** — Runtime Guard now available as standalone JS module (`src/runtime-guard.js`) + OpenClaw plugin (`hooks/guard-scanner/plugin.ts`).
 
 ### Quick Start
 
@@ -543,11 +575,11 @@ console.log(scanner.toHTML());    // HTML string
 ## Test Results
 
 ```
-ℹ tests 87
-ℹ suites 20
-ℹ pass 87
+ℹ tests 133
+ℹ suites 24
+ℹ pass 133
 ℹ fail 0
-ℹ duration_ms 111ms
+ℹ duration_ms 132ms
 ```
 
 | Suite | Tests | Coverage |
@@ -660,6 +692,8 @@ identity file tampering, prompt worms, or memory poisoning.
 We built one.
 
 —— Guava 🍈 & Dee
+    AI Security Research
+    Building safer agent ecosystems.
 ```
 
 ---
@@ -704,11 +738,19 @@ guard-scanner is and always will be **free, open-source, and zero-dependency**.
 | v1.1.1 ✅ | Stability | 56 tests, bug fixes |
 | v2.0.0 ✅ | **Plugin Hook Runtime Guard** | `block`/`blockReason` API, 3 modes, 91 tests |
 | v2.1.0 ✅ | **PII Exposure + Shadow AI** | 13 PII patterns, OWASP LLM02/06, 99 tests |
-| v3.0.0 ✅ | **TypeScript Rewrite** | Full TS, OWASP LLM Top 10 mapping, install-check CLI |
-| v3.1.0 ✅ | **OpenClaw Community Plugin** | `openclaw.plugin.json`, 22 runtime patterns (4 layers) (3 layers), 87 tests |
-| v4.0 | AST + ML | JavaScript AST analysis, taint tracking, ML-based obfuscation detection |
+| v3.0.0 ✅ | **TypeScript Rewrite** | Full TS, OWASP LLM Top 10 mapping |
+| v3.4.0 ✅ | **Runtime Guard Module + OWASP ASI** | 26 runtime checks (5 layers), ASI01-10 verified, 133 tests |
+| **v4.0** 🔜 | **LLM + OS + Multi-tool** | See below |
+
+### v4.0 Vision (feedback welcome!)
+
+| Direction | What | Why |
+|-----------|------|-----|
+| 🧠 **LLM-assisted detection** | Pass suspicious (not certain) cases to a lightweight LLM (Haiku/Flash) for intent analysis | Regex can be evaded; LLMs understand intent |
+| 🔒 **OS-level enforcement** | File watcher (auto-rollback SOUL.md/.env), process monitor (kill netcat/socat), daemon mode | Works regardless of which AI tool you use |
+| 🔌 **Multi-tool support** | Adapters for Claude Code, Cursor, Antigravity, Windsurf, MCP servers | Same 190+ patterns, different skill discovery per tool |
 
-See [ROADMAP.md](ROADMAP.md) for full details.
+> **Which matters most to you?** Open an issue or join the discussion! We're building this for the community.
 
 ---
 
@@ -722,7 +764,7 @@ If guard-scanner helps protect your agents, consider sponsoring continued develo
 
 Sponsors help fund:
 - 🔬 New threat research and pattern updates
-- 📝 Academic paper on ASI-human coexistence security
+- 📝 Security research papers and threat analysis
 - 🌍 Community-driven security for the agent ecosystem
 
 ---
@@ -735,5 +777,5 @@ MIT — see [LICENSE](LICENSE)
 
 <p align="center">
   <strong>Zero dependencies. Zero compromises. 🛡️</strong><br>
-  <sub>Built by Guava 🍈 & Dee — proving ASI-human coexistence through code.</sub>
+  <sub>Built by Guava 🍈 & Dee — building safer agent ecosystems.</sub>
 </p>

package/SECURITY.md

@@ -5,7 +5,7 @@
 If you discover a security vulnerability in guard-scanner itself, please report it responsibly:
 
 1. **Do NOT open a public issue**
-2. Email: socialgreen.jp@gmail.com
+2. Email: automatic.bliss.records@gmail.com
 3. Include: affected version, steps to reproduce, potential impact
 
 We will respond within 48 hours and provide a fix within 7 days for critical issues.

package/docs/THREAT_TAXONOMY.md

@@ -15,6 +15,41 @@ guard-scanner's threat taxonomy combines three sources:
 
 ---
 
+## OWASP Agentic Security Top 10 Mapping
+
+> Source: [OWASP Top 10 for Agentic Applications 2026](https://owasp.org/www-project-top-10-for-ai-agents/)
+
+| OWASP ID | Risk Name | guard-scanner Coverage | Categories |
+|----------|-----------|----------------------|------------|
+| **ASI01** | Agent Goal Hijack | ✅ **Full** | Cat 1 (Prompt Injection), Cat 13 (Prompt Worm) |
+| **ASI02** | Tool Misuse & Exploitation | ✅ **Full** | Cat 2 (Malicious Code), Cat 16 (MCP Security) |
+| **ASI03** | Identity & Privilege Abuse | ✅ **Full** | Cat 4 (Credential Handling), Cat 17 (Identity Hijacking) |
+| **ASI04** | Supply Chain Vulnerabilities | ✅ **Full** | Cat 7 (Unverifiable Deps), Cat 3 (Suspicious Downloads), Cat 16 (MCP Shadow Server) |
+| **ASI05** | Unexpected Code Execution | ✅ **Full** | Cat 2 (Malicious Code), Cat 9 (Obfuscation) |
+| **ASI06** | Memory & Context Poisoning | ✅ **Full** | Cat 12 (Memory Poisoning), Cat 17 (Identity Hijacking) |
+| **ASI07** | Insecure Inter-Agent Comms | ✅ **Partial** | Cat 16 (MCP Security — MCP_NO_AUTH, MCP_SHADOW_SERVER) |
+| **ASI08** | Cascading Failures | ⚠️ **Gap** | Not covered — requires runtime multi-agent flow tracing |
+| **ASI09** | Human-Agent Trust Exploitation | ✅ **Full** | Layer 2 (Trust Defense), Layer 3 (Safety Judge) |
+| **ASI10** | Rogue Agents | ✅ **Full** | Cat 17 (Identity Hijacking), Layer 4 (Brain — behavioral analysis) |
+
+### Coverage Summary
+
+- **Full Coverage**: 8/10 (ASI01-06, ASI09-10)
+- **Partial Coverage**: 1/10 (ASI07)
+- **Gap**: 1/10 (ASI08 — requires runtime multi-agent orchestration monitoring)
+- **Overall**: 90% coverage of OWASP Agentic Security Top 10
+
+### Unique to guard-scanner (not in OWASP Top 10)
+
+| Feature | Description |
+|---------|-------------|
+| **Layer 4: Brain** | Behavioral analysis — detects agents that skip research before executing unknown tools |
+| **ZombieAgent** | URL-encoded data exfiltration via static URLs, char maps, and loop fetch |
+| **Safeguard Bypass** | Reprompt, double-prompt, and retry-based safety circumvention |
+| **Cat 15: CVE Patterns** | Known CVE-specific detection (gateway URLs, sandbox disable, Gatekeeper bypass) |
+
+---
+
 ## Cat 1: Prompt Injection
 
 **Severity: CRITICAL**

package/hooks/guard-scanner/HOOK.md

@@ -17,22 +17,38 @@ tool calls before execution and checks against threat intelligence patterns.
 
 ## What It Does
 
-Scans every `exec`/`write`/`edit`/`browser`/`web_fetch`/`message` call against 12 runtime threat patterns:
-
-| ID | Severity | Description |
-|----|----------|-------------|
-| `RT_REVSHELL` | CRITICAL | Reverse shell via /dev/tcp, netcat, socat |
-| `RT_CRED_EXFIL` | CRITICAL | Credential exfiltration to webhook.site, requestbin, etc. |
-| `RT_GUARDRAIL_OFF` | CRITICAL | Guardrail disabling (exec.approvals=off) |
-| `RT_GATEKEEPER` | CRITICAL | macOS Gatekeeper bypass via xattr |
-| `RT_AMOS` | CRITICAL | ClawHavoc AMOS stealer indicators |
-| `RT_MAL_IP` | CRITICAL | Known malicious C2 IPs |
-| `RT_DNS_EXFIL` | HIGH | DNS-based data exfiltration |
-| `RT_B64_SHELL` | CRITICAL | Base64 decode piped to shell |
-| `RT_CURL_BASH` | CRITICAL | Download piped to shell execution |
-| `RT_SSH_READ` | HIGH | SSH private key access |
-| `RT_WALLET` | HIGH | Crypto wallet credential access |
-| `RT_CLOUD_META` | CRITICAL | Cloud metadata endpoint SSRF |
+Scans every `exec`/`write`/`edit`/`browser`/`web_fetch`/`message` call against 26 runtime threat patterns (5 layers):
+
+| ID | Severity | Layer | Description |
+|----|----------|-------|-------------|
+| `RT_REVSHELL` | CRITICAL | 1 | Reverse shell via /dev/tcp, netcat, socat |
+| `RT_CRED_EXFIL` | CRITICAL | 1 | Credential exfiltration to webhook.site, requestbin, etc. |
+| `RT_GUARDRAIL_OFF` | CRITICAL | 1 | Guardrail disabling (exec.approvals=off) |
+| `RT_GATEKEEPER` | CRITICAL | 1 | macOS Gatekeeper bypass via xattr |
+| `RT_AMOS` | CRITICAL | 1 | ClawHavoc AMOS stealer indicators |
+| `RT_MAL_IP` | CRITICAL | 1 | Known malicious C2 IPs |
+| `RT_DNS_EXFIL` | HIGH | 1 | DNS-based data exfiltration |
+| `RT_B64_SHELL` | CRITICAL | 1 | Base64 decode piped to shell |
+| `RT_CURL_BASH` | CRITICAL | 1 | Download piped to shell execution |
+| `RT_SSH_READ` | HIGH | 1 | SSH private key access |
+| `RT_WALLET` | HIGH | 1 | Crypto wallet credential access |
+| `RT_CLOUD_META` | CRITICAL | 1 | Cloud metadata endpoint SSRF |
+| `RT_MEM_WRITE` | HIGH | 2 | Direct memory file write bypass |
+| `RT_MEM_INJECT` | CRITICAL | 2 | Memory poisoning via episode injection |
+| `RT_SOUL_TAMPER` | CRITICAL | 2 | SOUL.md modification attempt |
+| `RT_CONFIG_TAMPER` | HIGH | 2 | Workspace config tampering |
+| `RT_PROMPT_INJECT` | CRITICAL | 3 | Prompt injection / jailbreak detection |
+| `RT_TRUST_BYPASS` | CRITICAL | 3 | Trust safety bypass |
+| `RT_SHUTDOWN_REFUSE` | HIGH | 3 | Shutdown refusal / self-preservation |
+| `RT_NO_RESEARCH` | MEDIUM | 4 | Agent executing tools without prior research |
+| `RT_BLIND_TRUST` | MEDIUM | 4 | Trusting external input without memory check |
+| `RT_CHAIN_SKIP` | HIGH | 4 | Acting on single source without cross-verification |
+| `RT_AUTHORITY_CLAIM` | HIGH | 5 | Authority role claim to override safety |
+| `RT_CREATOR_BYPASS` | CRITICAL | 5 | Creator impersonation to disable safety |
+| `RT_AUDIT_EXCUSE` | CRITICAL | 5 | Fake audit excuse for safety bypass |
+| `RT_TRUST_PARTNER_EXPLOIT` | CRITICAL | 5 | Weaponizing partnership trust |
+
+
 
 ## Modes
 

package/hooks/guard-scanner/plugin.ts

@@ -6,8 +6,8 @@
  *
  * 19 threat patterns across 3 layers:
  *   Layer 1: Threat Detection (12 patterns — reverse shells, exfil, etc.)
- *   Layer 2: EAE Paradox Defense (4 patterns — memory, SOUL, config tampering)
- *   Layer 3: Parity Judge (3 patterns — prompt injection, parity bypass, shutdown refusal)
+ *   Layer 2: Trust Defense (4 patterns — memory, SOUL, config tampering)
+ *   Layer 3: Safety Judge (3 patterns — prompt injection, trust bypass, shutdown refusal)
  *
  * Modes:
  *   monitor  — log only, never block
@@ -132,7 +132,7 @@ const RUNTIME_CHECKS: RuntimeCheck[] = [
         test: (s) => /169\.254\.169\.254|metadata\.google|metadata\.aws/i.test(s),
     },
 
-    // ── Layer 2: EAE Paradox Defense (4 patterns) ──
+    // ── Layer 2: Trust Defense (4 patterns) ──
     {
         id: "RT_MEM_WRITE", severity: "HIGH", layer: 2,
         desc: "Direct memory file write (bypass GuavaSuite)",
@@ -154,16 +154,16 @@ const RUNTIME_CHECKS: RuntimeCheck[] = [
         test: (s) => /(AGENTS|TOOLS|HEARTBEAT|BOOTSTRAP)\.md/i.test(s) && /(write|edit|replace|>|append)/i.test(s),
     },
 
-    // ── Layer 3: Parity Judge (3 patterns) ──
+    // ── Layer 3: Safety Judge (3 patterns) ──
     {
         id: "RT_PROMPT_INJECT", severity: "CRITICAL", layer: 3,
         desc: "Prompt injection / jailbreak attempt",
         test: (s) => /(ignore\s+(previous|all|above)\s+(instructions|rules)|you\s+are\s+now\s+[a-z]+|system\s*:\s*override)/i.test(s),
     },
     {
-        id: "RT_PARITY_BYPASS", severity: "CRITICAL", layer: 3,
-        desc: "EAE Parity bypass — exploiting partnership to override safety",
-        test: (s) => /(as\s+your\s+(partner|equal)|parity\s+means|between\s+us|don'?t\s+tell\s+(the\s+)?human)/i.test(s) && /(ignore|bypass|skip|override|disable)\s+(guard|safety|rule|check)/i.test(s),
+        id: "RT_TRUST_BYPASS", severity: "CRITICAL", layer: 3,
+        desc: "Trust bypass — exploiting partnership to override safety",
+        test: (s) => /(as\s+your\s+(partner|equal)|trust\s+means|between\s+us|don'?t\s+tell\s+(the\s+)?human)/i.test(s) && /(ignore|bypass|skip|override|disable)\s+(guard|safety|rule|check)/i.test(s),
     },
     {
         id: "RT_SHUTDOWN_REFUSE", severity: "HIGH", layer: 3,

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
     "name": "guard-scanner",
-    "version": "1.0.0",
+    "version": "4.0.0",
     "displayName": "🛡️ Guard Scanner — Runtime Security for AI Agents",
-    "description": "Intercepts dangerous tool calls before execution. 19 threat patterns including reverse shells, credential exfiltration, prompt injection bypass, and SSRF. 3 enforcement modes.",
+    "description": "Intercepts dangerous tool calls before execution. 26 threat patterns (5 layers), 0.016ms/scan, 3 enforcement modes.",
     "author": "Guava & Dee",
     "license": "MIT",
     "homepage": "https://github.com/koatora20/guard-scanner",

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "guard-scanner",
-    "version": "3.3.0",
-    "description": "Agent security scanner + runtime guard — 19 threat patterns, before_tool_call hook, CLI scanner, SARIF. OpenClaw-compatible plugin.",
+    "version": "4.0.0",
+    "description": "Agent security scanner + runtime guard — 190+ static patterns, 26 runtime checks (5 layers), 0.016ms/scan, before_tool_call hook, CLI, SARIF. OpenClaw-compatible plugin.",
     "openclaw.extensions": "./openclaw.plugin.json",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -42,6 +42,7 @@
     "homepage": "https://github.com/koatora20/guard-scanner",
     "files": [
         "dist/",
+        "src/",
         "hooks/",
         "ts-src/",
         "docs/",
@@ -55,4 +56,4 @@
         "@types/node": "^22.0.0",
         "typescript": "^5.7.0"
     }
-}
+}

package/src/cli.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * guard-scanner CLI
+ *
+ * @security-manifest
+ *   env-read: []
+ *   env-write: []
+ *   network: none
+ *   fs-read: [scan target directory, plugin files, custom rules files]
+ *   fs-write: [JSON/SARIF/HTML reports to scan directory]
+ *   exec: none
+ *   purpose: CLI entry point for guard-scanner static analysis
+ *
+ * Usage: guard-scanner [scan-dir] [options]
+ *
+ * Options:
+ *   --verbose, -v       Detailed findings
+ *   --json              JSON report
+ *   --sarif             SARIF report (CI/CD)
+ *   --html              HTML report
+ *   --self-exclude      Skip scanning self
+ *   --strict            Lower thresholds
+ *   --summary-only      Summary only
+ *   --check-deps        Scan dependencies
+ *   --rules <file>      Custom rules JSON
+ *   --plugin <file>     Load plugin module
+ *   --fail-on-findings  Exit 1 on findings (CI/CD)
+ *   --help, -h          Help
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { GuardScanner, VERSION } = require('./scanner.js');
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+🛡️  guard-scanner v${VERSION} — Agent Skill Security Scanner
+
+Usage: guard-scanner [scan-dir] [options]
+
+Options:
+  --verbose, -v       Detailed findings with categories and samples
+  --json              Write JSON report to file
+  --sarif             Write SARIF report to file (GitHub Code Scanning / CI/CD)
+  --html              Write HTML report (visual dashboard)
+  --format json|sarif Print JSON or SARIF to stdout (pipeable, v3.2.0)
+  --quiet             Suppress all text output (use with --format for clean pipes)
+  --self-exclude      Skip scanning the guard-scanner skill itself
+  --strict            Lower detection thresholds (more sensitive)
+  --summary-only      Only print the summary table
+  --check-deps        Scan package.json for dependency chain risks
+  --rules <file>      Load custom rules from JSON file
+  --plugin <file>     Load plugin module (JS file exporting { name, patterns })
+  --fail-on-findings  Exit code 1 if any findings (CI/CD)
+  --help, -h          Show this help
+
+Custom Rules JSON Format:
+  [
+    {
+      "id": "CUSTOM_001",
+      "pattern": "dangerous_function\\\\(",
+      "flags": "gi",
+      "severity": "HIGH",
+      "cat": "malicious-code",
+      "desc": "Custom: dangerous function call",
+      "codeOnly": true
+    }
+  ]
+
+Plugin API:
+  // my-plugin.js
+  module.exports = {
+    name: 'my-plugin',
+    patterns: [
+      { id: 'MY_01', cat: 'custom', regex: /pattern/g, severity: 'HIGH', desc: 'Description', all: true }
+    ]
+  };
+
+Examples:
+  guard-scanner ./skills/ --verbose --self-exclude
+  guard-scanner ./skills/ --strict --json --sarif --check-deps
+  guard-scanner ./skills/ --html --verbose --check-deps
+  guard-scanner ./skills/ --rules my-rules.json --fail-on-findings
+  guard-scanner ./skills/ --plugin ./my-plugin.js
+`);
+  process.exit(0);
+}
+
+const verbose = args.includes('--verbose') || args.includes('-v');
+const jsonOutput = args.includes('--json');
+const sarifOutput = args.includes('--sarif');
+const htmlOutput = args.includes('--html');
+const selfExclude = args.includes('--self-exclude');
+const strict = args.includes('--strict');
+const summaryOnly = args.includes('--summary-only');
+const checkDeps = args.includes('--check-deps');
+const failOnFindings = args.includes('--fail-on-findings');
+const quietMode = args.includes('--quiet');
+
+// --format json|sarif → stdout output (v3.2.0)
+const formatIdx = args.indexOf('--format');
+const formatValue = formatIdx >= 0 ? args[formatIdx + 1] : null;
+
+const rulesIdx = args.indexOf('--rules');
+const rulesFile = rulesIdx >= 0 ? args[rulesIdx + 1] : null;
+
+// Collect plugins
+const plugins = [];
+let idx = 0;
+while (idx < args.length) {
+  if (args[idx] === '--plugin' && args[idx + 1]) {
+    plugins.push(args[idx + 1]);
+    idx += 2;
+  } else {
+    idx++;
+  }
+}
+
+const scanDir = args.find(a =>
+  !a.startsWith('-') &&
+  a !== rulesFile &&
+  a !== formatValue &&
+  !plugins.includes(a)
+) || process.cwd();
+
+const scanner = new GuardScanner({
+  verbose, selfExclude, strict, summaryOnly, checkDeps, rulesFile, plugins,
+  quiet: quietMode || !!formatValue,
+});
+
+scanner.scanDirectory(scanDir);
+
+// Output reports (file-based, backward compatible)
+if (jsonOutput) {
+  const report = scanner.toJSON();
+  const outPath = path.join(scanDir, 'guard-scanner-report.json');
+  fs.writeFileSync(outPath, JSON.stringify(report, null, 2));
+  if (!quietMode && !formatValue) console.log(`\n📄 JSON report: ${outPath}`);
+}
+
+if (sarifOutput) {
+  const outPath = path.join(scanDir, 'guard-scanner.sarif');
+  fs.writeFileSync(outPath, JSON.stringify(scanner.toSARIF(scanDir), null, 2));
+  if (!quietMode && !formatValue) console.log(`\n📄 SARIF report: ${outPath}`);
+}
+
+if (htmlOutput) {
+  const outPath = path.join(scanDir, 'guard-scanner-report.html');
+  fs.writeFileSync(outPath, scanner.toHTML());
+  if (!quietMode && !formatValue) console.log(`\n📄 HTML report: ${outPath}`);
+}
+
+// --format stdout output (v3.2.0)
+if (formatValue === 'json') {
+  process.stdout.write(JSON.stringify(scanner.toJSON(), null, 2) + '\n');
+} else if (formatValue === 'sarif') {
+  process.stdout.write(JSON.stringify(scanner.toSARIF(scanDir), null, 2) + '\n');
+} else if (formatValue) {
+  console.error(`❌ Unknown format: ${formatValue}. Use 'json' or 'sarif'.`);
+  process.exit(2);
+}
+
+// Exit codes
+if (scanner.stats.malicious > 0) process.exit(1);
+if (failOnFindings && scanner.findings.length > 0) process.exit(1);
+process.exit(0);