@guava-parity/guard-scanner 9.1.0 → 15.0.0

package/README.md

@@ -1,72 +1,50 @@
 <p align="center">
-  <img src="docs/banner.png" alt="guard-scanner banner" width="720" />
+  <img src="docs/logo.png" alt="guard-scanner" width="180" />
 </p>
 
 <h1 align="center">guard-scanner 🛡️</h1>
-<p align="center"><strong>VirusTotal for AI Agent Skills</strong></p>
-<p align="center">The first open-source security scanner purpose-built for AI agent skill marketplaces.<br/>23 threat categories · 166 static patterns · 26 runtime checks · MCP server · asset audit · VirusTotal · zero dependencies.</p>
+<p align="center"><strong>Security policy and runtime layer for agent skills and MCP workflows</strong></p>
+<p align="center">35 threat categories · 358 static patterns · 27 runtime checks · 0 runtime dependencies</p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@guava-parity/guard-scanner"><img src="https://img.shields.io/npm/v/@guava-parity/guard-scanner?color=cb3837" alt="npm version" /></a>
-  <a href="#test-results"><img src="https://img.shields.io/badge/tests-225%2F225-brightgreen" alt="tests" /></a>
-  <a href="LICENSE"><img src="https://img.shields.io/npm/l/guard-scanner" alt="license" /></a>
-  <a href="https://github.com/koatora20/guard-scanner"><img src="https://img.shields.io/badge/dependencies-0-blue" alt="zero deps" /></a>
-  <a href="https://github.com/koatora20/dual-shield-paper"><img src="https://img.shields.io/badge/paper-36_pages-purple" alt="research paper" /></a>
+  <a href="#test-results"><img src="https://img.shields.io/badge/tests-332%20passed-brightgreen" alt="tests" /></a>
+  <a href="https://github.com/koatora20/guard-scanner/actions/workflows/codeql.yml"><img src="https://img.shields.io/badge/CodeQL-enabled-181717" alt="CodeQL" /></a>
+  <a href="https://doi.org/10.5281/zenodo.18906684"><img src="https://img.shields.io/badge/DOI-3_papers-purple" alt="DOI" /></a>
 </p>
 
 ---
 
-## Why guard-scanner?
+## What is guard-scanner?
 
-Traditional security tools like VirusTotal are great at catching malware — but they **can't see threats that live in natural language**. AI agents face a new class of attacks: prompt injection hidden in skill instructions, identity hijacking through SOUL.md overwrites, memory poisoning via crafted conversations. guard-scanner catches what others miss.
+**guard-scanner** is an uncompromising security and policy enforcement layer designed specifically for AI agents, OpenClaw skills, and MCP (Model Context Protocol) workflows. 
 
-### What guard-scanner catches that others can't
+While traditional security tools detect malware, AI agents face unique attack vectors: prompt injections hidden in memory, identity hijacking, autonomous permission escalation, and agent-to-agent contagion. 
 
-| Threat Class | guard-scanner | VirusTotal | Snyk Agent Scan | Garak (NVIDIA) |
-|---|:---:|:---:|:---:|:---:|
-| Prompt Injection in Skills | ✅ | ❌ | ✅ | ✅ (LLM-level) |
-| Identity Hijacking (SOUL.md) | ✅ | ❌ | ❌ | ❌ |
-| Memory Poisoning | ✅ | ❌ | ❌ | ❌ |
-| Agent-to-Agent Worm | ✅ | ❌ | ❌ | ❌ |
-| Trust Exploitation | ✅ | ❌ | ❌ | ❌ |
-| MCP Tool Poisoning | ✅ | ❌ | ✅ | ❌ |
-| VDB Injection (CVE-2026-26030) | ✅ | ❌ | ❌ | ❌ |
-| Known Malware Signatures | ✅ (via VT) | ✅ | ❌ | ❌ |
-| Zero Dependencies | ✅ | N/A | ❌ | ❌ |
-| MCP Server Built-in | ✅ | ❌ | ❌ | ❌ |
-| Research Paper (36p) | ✅ | N/A | ❌ | ❌ |
+**Core advantages:**
+- **Zero Runtime Dependencies:** Ultra-lightweight npm dual-publish (Only `ws` is used for MCP).
+- **Deep Defense:** Combines *static policy scanning* (358 patterns) with *runtime hook inspection* (27 checks).
+- **Universal MCP Server:** Plugs instantly into Cursor, Windsurf, Claude Code, and OpenClaw.
+- **Evidence-Driven Claims:** 100% precision/recall on our benchmark. 332 end-to-end tests all passing.
 
-> 📄 **Backed by research**: [Dual-Shield Architecture paper](https://github.com/koatora20/dual-shield-paper) — 28 days of production evidence, peer-review submitted.
+> 📄 **Backed by research**: Designed as the defense layer of the [The Sanctuary Protocol](https://doi.org/10.5281/zenodo.18906684) architecture (3-paper series, CC BY 4.0).
 
 ---
 
 ## Quick Start
 
+### 1. Zero-Install CLI Scan
+Run a semantic security scan on your agent workspace instantly:
 ```bash
-# Run without installing (npx)
-npx -y @guava-parity/guard-scanner ./my-skills/
-
-# Or install globally
-npm install -g @guava-parity/guard-scanner
-guard-scanner ./my-skills/ --verbose
+npx -y @guava-parity/guard-scanner ./my-skills/ --strict
 ```
 
-**That's it.** No config files, no API keys, no setup. Zero dependencies means zero supply chain risk.
-
-## 🔌 MCP Server (V9+)
-
-**Use guard-scanner as an MCP server** in any AI editor — Cursor, Windsurf, Cline, Antigravity, Claude Code, OpenClaw. Zero-dependency stdio JSON-RPC 2.0. No API keys needed.
-
+### 2. Universal MCP Server
+Connect guard-scanner to your favorite AI IDE for real-time security checking:
 ```bash
-# Start as MCP server
-guard-scanner serve
-
-# Or use directly via npx (no install required)
 npx -y @guava-parity/guard-scanner serve
 ```
-
-Add to your editor's MCP config:
-
+*Configure your editor (e.g., `mcp_servers.json`):*
 ```json
 {
   "mcpServers": {
@@ -78,238 +56,49 @@ Add to your editor's MCP config:
 }
 ```
 
-| Config File | Editor |
-|---|---|
-| `.cursor/mcp.json` | Cursor |
-| `mcp_config.json` | OpenClaw |
-| `.windsurf/mcp.json` | Windsurf |
-| `cline_mcp_settings.json` | Cline / Roo Code |
-| `mcp_servers.json` | Claude Code |
-
-### MCP Tools
-
-| Tool | Description |
-|------|-------------|
-| `scan_skill` | Scan a directory — 166 patterns, 23 categories |
-| `scan_text` | Scan a code snippet inline |
-| `check_tool_call` | Runtime guard — block dangerous tool calls before execution (26 checks, 5 layers) |
-| `audit_assets` | Audit npm/GitHub assets for exposure |
-| `get_stats` | Get scanner capabilities and statistics |
-
 ---
 
-## 🖥️ MCP Server (v9 — NEW!)
-
-Run guard-scanner as an **MCP server** for any AI editor (Cursor, Antigravity, Cline, Windsurf).
-
-```bash
-# Start MCP server (stdio)
-npx -y @guava-parity/guard-scanner serve
-```
+## Core Capabilities
 
-**5 tools available via MCP:**
-| Tool | Description |
-|------|-------------|
-| `scan_skill` | Scan a skill directory for threats |
-| `scan_text` | Scan raw text for prompt injection |
-| `check_tool_call` | Validate a tool call before execution |
-| `audit_assets` | Audit npm/GitHub/ClawHub assets |
-| `get_stats` | Get scanner stats and version info |
+### Threat Detection (35 Categories, 358 Patterns)
+Detects advanced 2026-era agentic threats globally mapping to **OWASP ASI01-10**:
+- **Prompt Injection & Memory Poisoning:** Detects invisible Unicode homoglyphs, decoding evasion, and payload cascades.
+- **Agent Identity Hijacking:** Blocks SOUL.md overwrites and prevents identity death.
+- **Autonomy & Privilege Escalation:** Rejects unauthorized `child_process`, `eval()`, and raw reverse shells.
+- **A2A Contagion:** Halts Session Smuggling and lateral infection between chained agents.
 
-**Add to your editor's MCP config:**
-```json
-{
-  "mcpServers": {
-    "guard-scanner": {
-      "command": "npx",
-      "args": ["-y", "@guava-parity/guard-scanner", "serve"]
-    }
-  }
-}
-```
+### Advanced Runtime Guard
+A deep `before_tool_call` layer validated seamlessly against OpenClaw `v2026.3.8`. Implements a ContextCrush 185KB gate and blocks Moltbook injection attempts during execution.
 
 ---
 
-## 🔎 Asset Audit (v6+)
-
-Audit your npm packages, GitHub repos, and ClawHub skills for leaked credentials and security exposure.
+## Usage Scenarios
 
+**Audit Local Assets:**
 ```bash
+# Audit npm, GitHub, or ClawHub exposures globally
 guard-scanner audit npm <username> --verbose
-guard-scanner audit github <username> --format json
-guard-scanner audit clawhub <query>
-guard-scanner audit all <username> --verbose
 ```
 
-## 🦠 VirusTotal Integration (v7+)
-
-Combine guard-scanner's semantic detection with VirusTotal's 70+ antivirus engines for **Double-Layered Defense**.
-
-| Layer | Engine | Focus |
-|---|---|---|
-| **Semantic** | guard-scanner | Prompt injection, memory poisoning, supply chain |
-| **Signature** | VirusTotal | Known malware, trojans, C2 infrastructure |
-
-```bash
-export VT_API_KEY=your-api-key-here
-guard-scanner scan ./skills/ --vt-scan
+**Continuous CI/CD Security:**
+```yaml
+# GitHub Actions integration
+- name: Scan AI Workflows
+  run: npx -y @guava-parity/guard-scanner ./skills/ --format sarif --fail-on-findings > report.sarif
 ```
 
-> VT is optional — guard-scanner works fully without it. Free tier: 4 req/min, 500/day.
-
-## 👁️ Real-time Watch (v8+)
-
+**Real-Time Live Reload Watcher:**
 ```bash
 guard-scanner watch ./skills/ --strict --soul-lock
 ```
 
-## 📊 CI/CD Integration (v8+)
-
-| Platform | Format |
-|---|---|
-| GitHub Actions | SARIF + `::error` annotations |
-| GitLab | Code Quality JSON |
-| Any | Webhook (HTTPS POST) |
-
-```yaml
-# .github/workflows/security.yml
-- name: Scan AI skills
-  run: npx -y @guava-parity/guard-scanner ./skills/ --format sarif --fail-on-findings > report.sarif
-- uses: github/codeql-action/upload-sarif@v3
-  with:
-    sarif_file: report.sarif
-```
-
 ---
 
-## Threat Categories (23)
-
-| # | Category | Detects |
-|---|----------|---------|
-| 1 | Prompt Injection | Hidden instructions, invisible Unicode, homoglyphs |
-| 2 | Malicious Code | `eval()`, `child_process`, reverse shells |
-| 3 | Suspicious Downloads | `curl\|bash`, executable downloads |
-| 4 | Credential Handling | `.env` reads, SSH keys |
-| 5 | Secret Detection | Hardcoded API keys, Shannon entropy |
-| 6 | Exfiltration | webhook.site, DNS tunneling |
-| 7 | Unverifiable Deps | Remote dynamic imports |
-| 8 | Financial Access | Crypto transactions |
-| 9 | Obfuscation | Base64→exec, hex encoding |
-| 10 | Prerequisites Fraud | Fake download instructions |
-| 11 | Leaky Skills | Secrets in memory |
-| 12 | Memory Poisoning ⚿ | SOUL.md modification |
-| 13 | Prompt Worm | Self-replicating prompts |
-| 14 | Persistence | Cron, launchd |
-| 15 | CVE Patterns | CVE-2026-2256/25046/25253/25905/27825 |
-| 16 | MCP Security | Tool poisoning, SSRF, shadow servers |
-| 17 | Identity Hijacking ⚿ | Persona swap, memory wipe |
-| 18 | Config Impact | OpenClaw config writes |
-| 19 | PII Exposure | CC/SSN, Shadow AI calls |
-| 20 | Trust Exploitation | Authority claims, fake audits |
-| 21 | VDB Injection | Vector DB poisoning |
-| 22 | Sandbox Validation | Dangerous binaries, broad file scope |
-| 23 | Code Complexity | Deep nesting, eval/exec density |
-
-> ⚿ = Requires `--soul-lock` flag
-
-## Runtime Guard (26 checks)
-
-Real-time `before_tool_call` hook across 5 defense layers.
-
-| Layer | Focus |
-|-------|-------|
-| 1. Threat Detection | Reverse shell, curl\|bash, SSRF |
-| 2. Trust Defense | SOUL.md tampering, memory injection |
-| 3. Safety Judge | Prompt injection in tool args |
-| 4. Behavioral | No-research execution detection |
-| 5. Trust Exploitation | Authority claim, creator bypass |
-
-## Options
-
-| Flag | Description |
-|------|-------------|
-| `--verbose`, `-v` | Detailed findings |
-| `--strict` | Lower thresholds (more sensitive) |
-| `--check-deps` | Scan `package.json` dependencies |
-| `--soul-lock` | Agent identity protection |
-| `--vt-scan` | VirusTotal integration |
-| `--json` / `--sarif` / `--html` | Report format |
-| `--format json\|sarif` | Print to stdout (pipeable) |
-| `--quiet` | Suppress text output |
-| `--fail-on-findings` | Exit 1 on findings (CI/CD) |
-| `--rules <file>` | Custom rules (JSON) |
-| `--plugin <file>` | Load plugin module |
-
----
-
-## Test Results
-
-```
-ℹ tests 225
-ℹ suites 50
-ℹ pass 225
-ℹ fail 0
-ℹ duration_ms 373
-```
-
-<details>
-<summary>Full test breakdown (50 suites)</summary>
-
-| Suite | Tests |
-|-------|-------|
-| Malicious Skill Detection | 16 ✅ |
-| Clean Skill (False Positive) | 2 ✅ |
-| Risk Score / Verdict | 10 ✅ |
-| Output Formats (JSON/SARIF/HTML) | 4 ✅ |
-| Pattern DB (166 patterns, 23 cats) | 4 ✅ |
-| IoC Database | 5 ✅ |
-| Shannon Entropy | 2 ✅ |
-| Plugin API / Custom Rules | 2 ✅ |
-| Skill Manifest | 4 ✅ |
-| Code Complexity | 2 ✅ |
-| Config / PII / OWASP | 26 ✅ |
-| Runtime Guard (5 layers) | 25 ✅ |
-| CVE Detection | 5 ✅ |
-| Asset Audit (npm/GitHub/ClawHub) | 32 ✅ |
-| VirusTotal Integration | 20 ✅ |
-| Watcher + CI/CD | 15 ✅ |
-| MCP Server | 19 ✅ |
-
-</details>
-
-## Plugin API
-
-```javascript
-module.exports = {
-  name: 'my-plugin',
-  patterns: [
-    { id: 'MY_01', cat: 'custom', regex: /dangerous_pattern/g, severity: 'HIGH', desc: 'Description', all: true }
-  ]
-};
-```
-
-```bash
-guard-scanner ./skills/ --plugin ./my-plugin.js
-```
-
 ## Contributing
+We welcome bug reports, new pattern ideas, and test case contributions. We hold a **Zero-Tolerance for Marketing Claims** — all features must be reproducible and test-backed.
 
-We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-**Quick ways to contribute:**
-- 🐛 Report bugs or false positives
-- 🛡️ Add new threat detection patterns
-- 📖 Improve documentation
-- 🧪 Add test cases for edge cases
-
-## Research
-
-This project is backed by a peer-reviewed research paper:
-
-> **Dual-Shield Architecture for AI Agent Security and Memory Reliability**
-> dee & Guava — Guava Parity Institute, March 2026
-> [GitHub](https://github.com/koatora20/dual-shield-paper) · [PDF](https://github.com/koatora20/dual-shield-paper/blob/main/paper/main.pdf)
+- [Governance & Contribution](CONTRIBUTING.md)
+- [Security Policy](SECURITY.md)
 
 ## License
-
 MIT — [Guava Parity Institute](https://github.com/koatora20/guard-scanner)

package/SECURITY.md

@@ -10,6 +10,13 @@ If you discover a security vulnerability in guard-scanner itself, please report
 
 We will respond within 48 hours and provide a fix within 7 days for critical issues.
 
+## Supported Versions
+
+| Version | Status |
+|---------|--------|
+| Latest major (`14.x`) | ✅ Supported |
+| Older releases | ⚠️ Best effort only |
+
 ## Scope
 
 guard-scanner is a **static analysis tool** — it reads files but never executes them. It does not:
@@ -22,11 +29,12 @@ The only files guard-scanner writes are output reports (`--json`, `--sarif`, `--
 
 ## Supply Chain Security
 
-guard-scanner itself has **zero runtime dependencies**. This is a deliberate design choice:
-- Nothing to audit
-- No transitive dependency risks
+guard-scanner itself keeps runtime dependencies intentionally small. As of `14.0.0`, it ships with **one runtime dependency** (`ws`) to support the MCP server.
+
+- Small runtime surface area
 - No `postinstall` scripts
-- Pure Node.js stdlib
+- SBOM generated in CI/release
+- Provenance-enabled npm publish
 
 ## Pattern Updates
 

package/SKILL.md

@@ -1,91 +1,153 @@
 ---
 name: guard-scanner
-description: "AI agent security platform. 166 static patterns + 26 runtime checks + npm/GitHub/ClawHub asset audit + VirusTotal integration + real-time file watch. Zero dependencies, 0.016ms/scan."
-metadata:
-  clawdbot:
-    homepage: "https://github.com/koatora20/guard-scanner"
-requires:
-  env:
-    VT_API_KEY: "Optional. VirusTotal API key for --vt-scan (free at virustotal.com)"
-files:
-  - "dist/*"
-  - "src/*"
-  - "hooks/*"
-  - "openclaw.plugin.json"
+description: "Security scanner and runtime guard for AI agent skills. 358 static threat patterns across 35 categories + 27 runtime checks (5 defense layers). Use when scanning skill directories for security threats, auditing npm/GitHub/ClawHub assets for leaked credentials, running real-time file watch during development, integrating security checks into CI/CD pipelines (SARIF/JSON), setting up MCP server for editor-integrated scanning (Cursor, Windsurf, Claude Code, OpenClaw), or runtime guarding tool calls via the OpenClaw v2026.3.8 before_tool_call hook. Single dependency (ws). MIT licensed."
+license: MIT
+metadata: {"openclaw": {"requires": {"bins": ["node"]}}}
 ---
 
-# guard-scanner 🛡️
+# guard-scanner
 
-166 static patterns + 26 runtime checks (5 layers), 23 threat categories + asset audit + VirusTotal + real-time watch. Zero deps, MIT licensed.
-
-## When To Use
-
-- Before installing a new skill / After updating skills / In CI/CD pipelines
-- Auditing npm/GitHub/ClawHub for leaked credentials
-- Real-time monitoring during development
+Scan AI agent skills for 35 categories of threats. Detect prompt injection, identity hijacking, memory poisoning, MCP tool poisoning, supply chain attacks, and 27 more threat classes that traditional security tools miss.
 
 ## Quick Start
 
 ```bash
-# Scan all skills
-npx guard-scanner ~/.openclaw/workspace/skills/ --verbose --self-exclude
+# Scan a skill directory
+npx -y @guava-parity/guard-scanner ./my-skills/ --verbose
 
-# Asset Audit (check npm/GitHub for leaks)
-guard-scanner audit npm <your-npm-username> --verbose
-guard-scanner audit github <your-github-username> --format json
-guard-scanner audit all <username>
+# Scan with identity protection
+npx -y @guava-parity/guard-scanner ./skills/ --soul-lock --strict
+```
 
-# VirusTotal Double-Layered Defense (optional, free)
-VT_API_KEY=your-key guard-scanner scan ./skills/ --vt-scan
+## Core Commands
 
-# Real-time Watch Mode
-guard-scanner watch ./skills/ --strict --verbose
+### Scan
 
-# CI/CD pipeline
-guard-scanner ./skills/ --format sarif --quiet | upload-sarif
+```bash
+guard-scanner scan <dir>        # Scan directory
+guard-scanner scan <dir> -v     # Verbose output
+guard-scanner scan <dir> --json # JSON output
+guard-scanner scan <dir> --sarif # SARIF for CI/CD
+guard-scanner scan <dir> --html # HTML report
 ```
 
-## VirusTotal Integration
+### Asset Audit
+
+Audit public registries for credential exposure.
+
+```bash
+guard-scanner audit npm <username>
+guard-scanner audit github <username>
+guard-scanner audit clawhub <query>
+guard-scanner audit all <username> --verbose
+```
 
-guard-scanner combines its own 166 semantic patterns with VirusTotal's 70+ antivirus engines for **Double-Layered Defense**:
+### MCP Server
 
-| Layer | Engine | Focus |
-|---|---|---|
-| Semantic | guard-scanner | Prompt injection, memory poisoning, supply chain |
-| Signature | VirusTotal | Known malware, trojans, C2 infrastructure |
+Start as MCP server for IDE integration.
 
 ```bash
-# Get your free API key at https://www.virustotal.com
-# Set it as environment variable
-export VT_API_KEY=your-api-key-here
+guard-scanner serve
+```
 
-# Use with any command
-guard-scanner scan ./skills/ --vt-scan
-guard-scanner audit npm koatora20 --vt-scan
+Editor config (Cursor, Windsurf, Claude Code, OpenClaw):
+
+```json
+{
+  "mcpServers": {
+    "guard-scanner": {
+      "command": "npx",
+      "args": ["-y", "@guava-parity/guard-scanner", "serve"]
+    }
+  }
+}
 ```
 
-Free tier: 4 req/min, 500/day, 15,500/month. VT is **optional** — guard-scanner works fully without it.
+MCP tools: `scan_skill`, `scan_text`, `check_tool_call`, `audit_assets`, `get_stats`.
 
-## Runtime Modes
+### Watch Mode
 
-| Mode | Behavior |
-|------|----------|
-| `monitor` | Log all, never block |
-| `enforce` (default) | Block CRITICAL |
-| `strict` | Block HIGH + CRITICAL |
+Monitor skill directories in real-time during development.
 
-## 23 Threat Categories
+```bash
+guard-scanner watch ./skills/ --strict --soul-lock
+```
 
-Prompt Injection, Malicious Code, Suspicious Downloads, Credential Handling, Secret Detection, Exfiltration, Unverifiable Deps, Financial Access, Obfuscation, Prerequisites Fraud, Leaky Skills, Memory Poisoning*, Prompt Worm, Persistence, CVE Patterns, MCP Security, Identity Hijacking*, Sandbox Validation, Code Complexity, Config Impact, PII Exposure, Trust Exploitation, VDB Injection.
+### VirusTotal Integration
 
-\* = Requires `--soul-lock` flag
+Combine semantic detection with VirusTotal's 70+ antivirus engines. Optional — guard-scanner works fully without it.
 
-## Security & Privacy
+```bash
+export VT_API_KEY=your-key
+guard-scanner scan ./skills/ --vt-scan
+```
+
+## Runtime Guard
+
+The validated OpenClaw surface is the compiled runtime plugin entry (`dist/openclaw-plugin.mjs`) discovered through `package.json > openclaw.extensions` and mounted on `before_tool_call` for OpenClaw `v2026.3.8`.
+
+The `before_tool_call` hook provides 27 runtime checks across 5 defense layers:
+
+| Layer | Focus |
+|-------|-------|
+| 1. Threat Detection | Reverse shell, curl\|bash, SSRF |
+| 2. Trust Defense | SOUL.md tampering, memory injection |
+| 3. Safety Judge | Prompt injection in tool arguments |
+| 4. Behavioral | No-research execution detection |
+| 5. Trust Exploitation | Authority claims, creator bypass |
+
+Modes: `monitor` (log only), `enforce` (block CRITICAL, default), `strict` (block HIGH+).
+
+## Key Flags
+
+| Flag | Effect |
+|------|--------|
+| `--verbose` / `-v` | Detailed findings with line numbers |
+| `--strict` | Lower detection thresholds |
+| `--soul-lock` | Enable identity protection patterns |
+| `--vt-scan` | Add VirusTotal double-layered check |
+| `--json` / `--sarif` / `--html` | Output format |
+| `--fail-on-findings` | Exit 1 on findings (CI/CD) |
+| `--check-deps` | Scan package.json dependencies |
+| `--rules <file>` | Load custom rules JSON |
+| `--plugin <file>` | Load plugin module |
+
+## Custom Rules
+
+```javascript
+module.exports = {
+  name: 'my-plugin',
+  patterns: [
+    { id: 'MY_01', cat: 'custom', regex: /dangerous_pattern/g, severity: 'HIGH', desc: 'Description', all: true }
+  ]
+};
+```
+
+```bash
+guard-scanner ./skills/ --plugin ./my-plugin.js
+```
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/security.yml
+- name: Scan AI skills
+  run: npx -y @guava-parity/guard-scanner ./skills/ --format sarif --fail-on-findings > report.sarif
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: report.sarif
+```
 
-Zero network requests (unless `--vt-scan`). Read-only scanning. No telemetry. No env access. Deterministic. Your VT API key stays local.
+## Threat Categories
 
-## Trust
+35 categories covering OWASP LLM Top 10 + Agentic Security Top 10. See `src/patterns.js` for the full pattern database. Key categories:
 
-Open source, zero deps, **206 tests / 43 suites** 100% pass. OWASP LLM Top 10 + Agentic Security Top 10 coverage.
+- **Prompt Injection** — hidden instructions, invisible Unicode, homoglyphs
+- **Identity Hijacking** ⚿ — persona swap, SOUL.md overwrites, memory wipe
+- **Memory Poisoning** ⚿ — crafted conversation injection
+- **MCP Security** — tool poisoning, SSRF, shadow servers
+- **A2A Contagion** — agent-to-agent worm propagation
+- **Supply Chain V2** — typosquatting, slopsquatting, lifecycle scripts
+- **CVE Patterns** — CVE-2026-2256, 25046, 25253, 25905, 27825
 
-MIT — [LICENSE](LICENSE)
+> ⚿ = Requires `--soul-lock` flag

package/dist/openclaw-plugin.mjs

@@ -0,0 +1,41 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const runtimeGuard = require("../src/runtime-guard.js");
+function resolveMode(pluginConfig) {
+    const mode = pluginConfig?.mode;
+    if (mode === "monitor" || mode === "enforce" || mode === "strict") {
+        return mode;
+    }
+    return undefined;
+}
+function resolveAuditLog(pluginConfig) {
+    return pluginConfig?.auditLog !== false;
+}
+function beforeToolCall(event, ctx, api) {
+    const result = runtimeGuard.scanToolCall(event.toolName, event.params, {
+        mode: resolveMode(api.pluginConfig),
+        auditLog: resolveAuditLog(api.pluginConfig),
+        sessionKey: ctx.sessionKey,
+        sessionId: ctx.sessionId,
+        runId: ctx.runId ?? event.runId,
+        toolCallId: ctx.toolCallId ?? event.toolCallId,
+        agentId: ctx.agentId,
+    });
+    if (!result.blocked)
+        return;
+    return {
+        block: true,
+        blockReason: result.blockReason ?? "guard-scanner blocked the tool call.",
+    };
+}
+const plugin = {
+    id: "guard-scanner",
+    name: "guard-scanner",
+    version: "15.0.0",
+    description: "Runtime guard for OpenClaw before_tool_call hook execution.",
+    register(api) {
+        api.on("before_tool_call", (event, ctx) => beforeToolCall(event, ctx, api), { priority: 90 });
+        api.logger.info("guard-scanner registered OpenClaw before_tool_call hook (validated for v2026.3.8).");
+    },
+};
+export default plugin;