npm - @guava-parity/guard-scanner - Versions diffs - 9.0.0 → 13.0.0 - Mend

@guava-parity/guard-scanner 9.0.0 → 13.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -1,78 +1,147 @@
-# guard-scanner 🛡️
+<p align="center">
+  <img src="docs/banner.png" alt="guard-scanner banner" width="720" />
+</p>
-*The Original, Zero-Dependency Shield for the AI Agent Era.*
+<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>
-As autonomous AI agents become more prevalent, the risk of executing untrusted or malicious skills increases. **guard-scanner** is an open-source, zero-dependency security platform designed to protect developers from Prompt Injections, RCEs, Memory Poisoning, and supply chain attacks.
+<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>
+</p>
-Built by the **[Guava Parity Institute](https://github.com/koatora20)** and the open-source community.
+---
-**166 static patterns + 26 runtime checks + asset audit + VirusTotal integration + real-time watch.**
+## Why guard-scanner?
-[![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/guard-scanner)](LICENSE)
-[![tests](https://img.shields.io/badge/tests-206%2F206-brightgreen)](#test-results)
+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.
-## Install
+### What guard-scanner catches that others can't
+| 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 | ❌ | ❌ |
+> 📄 **Backed by research**: [Dual-Shield Architecture paper](https://github.com/koatora20/dual-shield-paper) — 28 days of production evidence, peer-review submitted.
+---
+## Quick Start
 ```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
 ```
-## Quick Start
+**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.
 ```bash
-# Scan all skills
-guard-scanner ./skills/ --verbose
+# Start as MCP server
+guard-scanner serve
-# Strict mode + reports
-guard-scanner ./skills/ --strict --json --sarif --fail-on-findings
+# Or use directly via npx (no install required)
+npx -y @guava-parity/guard-scanner serve
+```
-# CI/CD pipeline (stdout)
-guard-scanner ./skills/ --format sarif --quiet | upload-sarif
+Add to your editor's MCP config:
+```json
+{
+  "mcpServers": {
+    "guard-scanner": {
+      "command": "npx",
+      "args": ["-y", "@guava-parity/guard-scanner", "serve"]
+    }
+  }
+}
 ```
-## 🔍 Example Scan Output
-```console
-$ guard-scanner ./test/fixtures/malicious-skill/ --verbose
-🛡️  guard-scanner v8.0.0
-══════════════════════════════════════════════════════
-📂 Scanning: ./test/fixtures/malicious-skill/
-📦 Skills found: 1
-🔴 scripts — MALICIOUS (risk: 100)
-   📁 exfiltration
-      🔴 [HIGH] Suspicious domain: webhook.site — evil.js
-   📁 malicious-code
-      🔴 [HIGH] eval() call — evil.js:18
-      💀 [CRITICAL] Shell download/execution — stealer.js:19
-   📁 credential-handling
-      🔴 [HIGH] Credential file read — evil.js:6
-      💀 [CRITICAL] Agent identity file read — evil.js:7
-   📁 memory-poisoning
-      💀 [CRITICAL] Write to agent soul file — evil.js:21
+| 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
+```
+**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 |
+**Add to your editor's MCP config:**
+```json
+{
+  "mcpServers": {
+    "guard-scanner": {
+      "command": "npx",
+      "args": ["-y", "@guava-parity/guard-scanner", "serve"]
+    }
+  }
+}
 ```
-## 🔎 Asset Audit (V6+)
+---
+## 🔎 Asset Audit (v6+)
 Audit your npm packages, GitHub repos, and ClawHub skills for leaked credentials and security exposure.
 ```bash
-# npm — detect leaked node_modules, .env files, scope duplicates
 guard-scanner audit npm <username> --verbose
-# GitHub — detect committed secrets, large repos, .env/.key files
 guard-scanner audit github <username> --format json
-# ClawHub — detect malicious skills, suspicious DL/star ratios
 guard-scanner audit clawhub <query>
-# All providers at once
 guard-scanner audit all <username> --verbose
 ```
-## 🦠 VirusTotal Integration (V7+)
+## 🦠 VirusTotal Integration (v7+)
 Combine guard-scanner's semantic detection with VirusTotal's 70+ antivirus engines for **Double-Layered Defense**.
@@ -82,74 +151,41 @@ Combine guard-scanner's semantic detection with VirusTotal's 70+ antivirus engin
 | **Signature** | VirusTotal | Known malware, trojans, C2 infrastructure |
 ```bash
-# 1. Get free API key at https://www.virustotal.com (¥0)
-# 2. Set environment variable
 export VT_API_KEY=your-api-key-here
-# 3. Use with any command
 guard-scanner scan ./skills/ --vt-scan
-guard-scanner audit npm koatora20 --vt-scan
 ```
-> **Free tier**: 4 req/min, 500/day, 15,500/month. Personal use only.
-> **VT is optional** — guard-scanner works fully without it.
-## 👁️ Real-time Watch Mode (V8+)
+> VT is optional — guard-scanner works fully without it. Free tier: 4 req/min, 500/day.
-Monitor your skills directory for changes and scan automatically.
+## 👁️ Real-time Watch (v8+)
 ```bash
-# Start watching
-guard-scanner watch ./skills/ --strict --verbose
-# With Soul Lock protection
 guard-scanner watch ./skills/ --strict --soul-lock
 ```
-Press `Ctrl+C` for session stats.
-## 📊 CI/CD Integration (V8+)
-Native support for CI/CD pipelines via `CIReporter`:
+## 📊 CI/CD Integration (v8+)
 | Platform | Format |
 |---|---|
-| GitHub Actions | `::error` / `::warning` annotations + Step Summary |
-| GitLab | Code Quality JSON report |
-| Any | Webhook notification (HTTPS POST) |
-```bash
-# GitHub Actions
-guard-scanner ./skills/ --format sarif --quiet > report.sarif
-# GitLab
-guard-scanner ./skills/ --format json --quiet > gl-code-quality-report.json
+| 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
 ```
-## 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 |
-| `--vt-scan` | Enable VirusTotal hash/URL/domain lookup |
-| `--json` | Write JSON report to file |
-| `--sarif` | Write SARIF 2.1.0 report |
-| `--html` | Write HTML dashboard report |
-| `--format json\|sarif` | Print to stdout (pipeable) |
-| `--quiet` | Suppress text output |
-| `--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 (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 |
@@ -171,31 +207,54 @@ guard-scanner ./skills/ --format json --quiet > gl-code-quality-report.json
 | 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)
-> ⚿ = Requires `--soul-lock` flag (opt-in)
+Real-time `before_tool_call` hook across 5 defense layers.
-## Runtime Guard (26 checks, 5 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
-Real-time `before_tool_call` hook that blocks dangerous operations.
+| 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 |
-| Layer | Name | Checks |
-|-------|------|--------|
-| 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 |
-| 5 | Trust Exploitation | Authority claim, creator bypass |
+---
 ## Test Results
 ```
-ℹ tests 206
-ℹ suites 43
-ℹ pass 206
+ℹ tests 225
+ℹ suites 50
+ℹ pass 225
 ℹ fail 0
-ℹ duration_ms 376
+ℹ duration_ms 373
 ```
+<details>
+<summary>Full test breakdown (50 suites)</summary>
 | Suite | Tests |
 |-------|-------|
 | Malicious Skill Detection | 16 ✅ |
@@ -211,9 +270,12 @@ Real-time `before_tool_call` hook that blocks dangerous operations.
 | 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 ✅** |
+| Asset Audit (npm/GitHub/ClawHub) | 32 ✅ |
+| VirusTotal Integration | 20 ✅ |
+| Watcher + CI/CD | 15 ✅ |
+| MCP Server | 19 ✅ |
+</details>
 ## Plugin API
@@ -221,7 +283,7 @@ Real-time `before_tool_call` hook that blocks dangerous operations.
 module.exports = {
   name: 'my-plugin',
   patterns: [
-    { id: 'MY_01', cat: 'custom', regex: /pattern/g, severity: 'HIGH', desc: 'Description', all: true }
+    { id: 'MY_01', cat: 'custom', regex: /dangerous_pattern/g, severity: 'HIGH', desc: 'Description', all: true }
   ]
 };
 ```
@@ -232,7 +294,21 @@ guard-scanner ./skills/ --plugin ./my-plugin.js
 ## Contributing
-We welcome contributions! Whether fixing bugs, adding threat patterns, or improving docs.
+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)
 ## License

package/docs/banner.png ADDED Viewed

Binary file