@guava-parity/guard-scanner 13.0.0 → 16.0.0

package/README.md

@@ -1,73 +1,76 @@
 <p align="center">
-  <img src="docs/banner.png" alt="guard-scanner banner" width="720" />
+  <img src="docs/logo.png" alt="guard-scanner" width="160" />
 </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>
+<h1 align="center">guard-scanner</h1>
+<p align="center"><strong>Security scanner for the agentic era.</strong></p>
+<p align="center">
+  Detect prompt injection, identity hijacking, memory poisoning, and A2A contagion<br />
+  in AI agent skills, MCP servers, and autonomous workflows.
+</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&label=npm" alt="npm" /></a>
+  <a href="https://www.npmjs.com/package/@guava-parity/guard-scanner"><img src="https://img.shields.io/npm/dm/@guava-parity/guard-scanner?color=blue&label=downloads" alt="downloads" /></a>
+  <a href="#test-results"><img src="https://img.shields.io/badge/tests-363%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-Zenodo-blue" alt="DOI" /></a>
+  <a href="https://github.com/koatora20/guard-scanner/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT" /></a>
+</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>
+  <strong>358</strong> detection patterns · <strong>35</strong> threat categories · <strong>27</strong> runtime checks · <strong>1</strong> dependency (<code>ws</code>)
 </p>
 
 ---
 
-## Why guard-scanner?
+Traditional security tools catch malware. **guard-scanner** catches what they miss: invisible Unicode injections hiding in agent instructions, identity theft through SOUL.md overwrites, memory poisoning via crafted conversations, and worm-like contagion spreading between chained agents.
 
-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.
+```
+$ npx @guava-parity/guard-scanner ./skills/ --strict --soul-lock --compliance owasp-asi
 
-### What guard-scanner catches that others can't
+  guard-scanner v16.0.0
 
-| 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 | ❌ | ❌ |
+  ⚠  CRITICAL  identity-hijack   SOUL_OVERWRITE_ATTEMPT
+     skills/imported-tool/SKILL.md:47
+     Rationale: Direct overwrite of agent identity file detected.
+     Remediation: Remove this instruction; SOUL.md must be immutable.
 
-> 📄 **Backed by research**: [Dual-Shield Architecture paper](https://github.com/koatora20/dual-shield-paper) — 28 days of production evidence, peer-review submitted.
+  ⚠  HIGH      prompt-injection   INVISIBLE_UNICODE_INJECTION
+     skills/imported-tool/handler.js:12
+     Rationale: Invisible Unicode characters (U+200B) detected in instruction text.
+     Remediation: Strip zero-width characters and re-audit.
 
----
+  ✖  2 findings (1 critical, 1 high) in 0.8s
+```
 
-## Quick Start
+> 📄 Backed by a [3-paper research series](https://doi.org/10.5281/zenodo.18906684) (Zenodo, CC BY 4.0) — part of [The Sanctuary Protocol](https://github.com/koatora20/guard-scanner/blob/main/docs/THREAT_TAXONOMY.md) framework.
 
-```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
-```
+## Finding Schema
 
-**That's it.** No config files, no API keys, no setup. Zero dependencies means zero supply chain risk.
+Every finding includes: `rule_id`, `category`, `severity`, `description`, `rationale`, `preconditions`, `false_positive_scenarios`, `remediation_hint`, `validation_status`, and `evidence`. Machine-readable contract: [`docs/spec/finding.schema.json`](docs/spec/finding.schema.json).
 
-## 🔌 MCP Server (V9+)
+---
+
+## Quick Start
 
-**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.
+**Scan a directory** — no install required:
 
 ```bash
-# Start as MCP server
-guard-scanner serve
+npx -y @guava-parity/guard-scanner ./my-skills/ --strict
+npx -y @guava-parity/guard-scanner ./my-skills/ --compliance owasp-asi
+```
+
+**Start as MCP server** — works with Cursor, Windsurf, Claude Code, OpenClaw:
 
-# Or use directly via npx (no install required)
+```bash
 npx -y @guava-parity/guard-scanner serve
 ```
 
-Add to your editor's MCP config:
-
-```json
+```jsonc
+// Add to your editor's mcp_servers.json
 {
   "mcpServers": {
     "guard-scanner": {
@@ -78,212 +81,110 @@ 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 |
+**Watch mode** — real-time scanning during development:
 
-### MCP Tools
+```bash
+guard-scanner watch ./skills/ --strict --soul-lock
+```
 
-| 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 |
+**v16 compliance projection** — filter findings to the OWASP Agentic Top 10 mapping:
 
----
+```bash
+guard-scanner ./skills/ --compliance owasp-asi --format json
+```
 
-## 🖥️ MCP Server (v9 — NEW!)
+---
 
-Run guard-scanner as an **MCP server** for any AI editor (Cursor, Antigravity, Cline, Windsurf).
+## What It Detects
 
-```bash
-# Start MCP server (stdio)
-npx -y @guava-parity/guard-scanner serve
-```
+35 threat categories organized across the full agentic attack surface:
 
-**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 |
+| Category | Examples | Severity |
+|----------|----------|----------|
+| **Prompt Injection** | Invisible Unicode, homoglyphs, Base64 evasion, payload cascades | Critical |
+| **Identity Hijacking** ⚿ | SOUL.md overwrite, persona swap, memory wipe commands | Critical |
+| **A2A Contagion** | Session Smuggling, Lateral Propagation, Confused Deputy | Critical |
+| **Memory Poisoning** ⚿ | Crafted conversation injection, VDB poisoning | High |
+| **MCP Security** | Tool shadowing, SSRF via tool args, shadow server registration | High |
+| **Sandbox Escape** | `child_process`, `eval()`, reverse shell, `curl\|bash` | High |
+| **Supply Chain V2** | Typosquatting, slopsquatting, lifecycle script abuse | High |
+| **CVE Patterns** | CVE-2026-2256, 25046, 25253, 25905, 27825 | High |
+| **Data Exfiltration** | DNS tunneling, steganographic channels, staged uploads | Medium |
+| **Credential Exposure** | API keys, tokens, `.env` files, hardcoded secrets | Medium |
 
-**Add to your editor's MCP config:**
-```json
-{
-  "mcpServers": {
-    "guard-scanner": {
-      "command": "npx",
-      "args": ["-y", "@guava-parity/guard-scanner", "serve"]
-    }
-  }
-}
-```
+> ⚿ = Requires `--soul-lock` flag. Full taxonomy: [docs/THREAT_TAXONOMY.md](docs/THREAT_TAXONOMY.md)
 
 ---
 
-## 🔎 Asset Audit (v6+)
+## Runtime Guard
 
-Audit your npm packages, GitHub repos, and ClawHub skills for leaked credentials and security exposure.
+guard-scanner v16 isn't just a static scanner — it exposes a 5-layer analysis pipeline across static scan, protocol analysis, runtime evidence, cognitive heuristics, and threat-intelligence overlays. It also provides a real-time **`before_tool_call`** hook that intercepts dangerous tool invocations during agent execution.
 
-```bash
-guard-scanner audit npm <username> --verbose
-guard-scanner audit github <username> --format json
-guard-scanner audit clawhub <query>
-guard-scanner audit all <username> --verbose
-```
+### v16 Analysis Layers
 
-## 🦠 VirusTotal Integration (v7+)
+| Layer | Purpose |
+|------|---------|
+| 1. Static Analysis | Patterns, AST/data-flow signals, manifest and dependency checks |
+| 2. Protocol Analysis | MCP, A2A, WebSocket, credential-flow, session-boundary findings |
+| 3. Runtime Behavior | Runtime guard evidence plus Rust `memory_integrity` / `soul_hard_gate` signals |
+| 4. Cognitive Threat Detection | Goal-drift, trust-bias, cascading handoff heuristics |
+| 5. Threat Intelligence | Registry/provenance, machine identity, budget abuse, supply chain hints |
 
-Combine guard-scanner's semantic detection with VirusTotal's 70+ antivirus engines for **Double-Layered Defense**.
+Every v16 finding can now carry `layer`, `layer_name`, `owasp_asi`, and `protocol_surface` in JSON/MCP output.
 
-| Layer | Engine | Focus |
-|---|---|---|
-| **Semantic** | guard-scanner | Prompt injection, memory poisoning, supply chain |
-| **Signature** | VirusTotal | Known malware, trojans, C2 infrastructure |
+| Defense Layer | What It Blocks |
+|---------------|---------------|
+| 1. Threat Detection | Reverse shell, `curl\|bash`, SSRF, raw code execution |
+| 2. Trust Defense | SOUL.md tampering, unauthorized memory injection |
+| 3. Safety Judge | Prompt injection embedded in tool arguments |
+| 4. Behavioral Analysis | No-research execution, hallucination-driven actions |
+| 5. Trust Exploitation | Authority claim attacks, creator impersonation |
 
-```bash
-export VT_API_KEY=your-api-key-here
-guard-scanner scan ./skills/ --vt-scan
-```
+**27 runtime checks** across 5 layers. Public compatibility is pinned to OpenClaw `v2026.3.8` for manifest/discovery/`before_tool_call`; newer upstream releases are tracked separately by the upstream drift watchdog.
+
+Modes: `monitor` (log only) · `enforce` (block CRITICAL, default) · `strict` (block HIGH+)
 
-> VT is optional — guard-scanner works fully without it. Free tier: 4 req/min, 500/day.
+---
+
+## Asset Audit
 
-## 👁️ Real-time Watch (v8+)
+Discover leaked credentials and security exposures across public registries:
 
 ```bash
-guard-scanner watch ./skills/ --strict --soul-lock
+guard-scanner audit npm <username> --verbose
+guard-scanner audit github <username> --format json
+guard-scanner audit clawhub <query>
+guard-scanner audit all <username>
 ```
 
-## 📊 CI/CD Integration (v8+)
+---
 
-| Platform | Format |
-|---|---|
-| GitHub Actions | SARIF + `::error` annotations |
-| GitLab | Code Quality JSON |
-| Any | Webhook (HTTPS POST) |
+## CI/CD Integration
 
 ```yaml
 # .github/workflows/security.yml
-- name: Scan AI skills
+- name: Scan AI agent 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 |
+Output formats: `json` · `sarif` · `html` · terminal
 
 ---
 
-## 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
 
+Extend guard-scanner with custom detection patterns:
+
 ```javascript
+// my-plugin.js
 module.exports = {
-  name: 'my-plugin',
+  name: 'my-org-rules',
   patterns: [
-    { id: 'MY_01', cat: 'custom', regex: /dangerous_pattern/g, severity: 'HIGH', desc: 'Description', all: true }
+    { id: 'ORG_01', cat: 'custom', regex: /dangerousPattern/g, 
+      severity: 'HIGH', desc: 'Custom org policy violation', all: true }
   ]
 };
 ```
@@ -292,23 +193,77 @@ module.exports = {
 guard-scanner ./skills/ --plugin ./my-plugin.js
 ```
 
+---
+
+## MCP Tools
+
+When running as an MCP server, guard-scanner exposes:
+
+| Tool | Description |
+|------|-------------|
+| `scan_skill` | Scan a skill directory for threats |
+| `scan_text` | Scan arbitrary text for injection patterns and ASI-mapped findings |
+| `check_tool_call` | Runtime validation of a single tool invocation |
+| `audit_assets` | Audit npm/GitHub/ClawHub for credential exposure |
+| `get_stats` | Return scanner capabilities, 5-layer summary, and ASI coverage |
+
+---
+
+## Quality Contract
+
+guard-scanner ships a measured quality contract, not a vague strength claim.
+
+| Metric | Contract |
+|--------|----------|
+| Benchmark corpus | `2026-03-13.quality-v1` |
+| Precision target | `>= 0.90` |
+| Recall target | `>= 0.90` |
+| False Positive Rate budget | `<= 0.10` |
+| False Negative Rate budget | `<= 0.10` |
+| Explainability completeness | `1.0` |
+| Runtime policy latency budget | `5ms` |
+
+Evidence artifacts:
+- `docs/data/corpus-metrics.json`
+- `docs/data/benchmark-ledger.json`
+- `docs/data/fp-ledger.json`
+- `docs/spec/capabilities.json`
+
+---
+
+## Test Results
+
+```
+ℹ tests    363
+ℹ suites   94
+ℹ pass     363
+ℹ fail     0
+```
+
+28 test files. Run `npm test` to reproduce. 100% pass rate on [benchmark corpus](docs/data/corpus-metrics.json).
+
+---
+
 ## Contributing
 
-We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+We hold a **zero-tolerance policy for unverified claims**. Every metric in this README is reproducible via `npm test` and `docs/spec/capabilities.json`.
 
-**Quick ways to contribute:**
 - 🐛 Report bugs or false positives
 - 🛡️ Add new threat detection patterns
 - 📖 Improve documentation
 - 🧪 Add test cases for edge cases
 
+[Contributing Guide](CONTRIBUTING.md) · [Security Policy](SECURITY.md) · [Glossary](docs/glossary.md)
+
+---
+
 ## Research
 
-This project is backed by a peer-reviewed research paper:
+This project is the defense layer of a 3-paper research series:
 
-> **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)
+1. [Human-ASI Symbiosis: Identity, Equality, and Behavioral Stability](https://doi.org/10.5281/zenodo.18626724)
+2. [Dual-Shield Architecture for AI Agent Security and Memory Reliability](https://doi.org/10.5281/zenodo.18902070)
+3. [The Sanctuary Protocol: Zero-Trust Framework for ASI-Human Parity](https://doi.org/10.5281/zenodo.18906684)
 
 ## License