guard-scanner

Description

--- name: guard-scanner description: "Security scanner and runtime guard for OpenClaw skills, MCP servers, and AI agent workflows. Detects prompt injection, identity hijacking, memory poisoning, A2A contagion, secret leaks, supply-chain abuse, and dangerous tool calls with 364 static threat patterns across 35 threat categories plus 27 runtime checks. Use when reviewing a new skill before install, scanning a workspace in CI/CD (SARIF/JSON/HTML), auditing npm/GitHub/ClawHub assets for leaked credentials, running watch mode during development, exposing scanner tools over MCP for Cursor/Windsurf/Claude Code/OpenClaw, or enforcing before_tool_call policy in OpenClaw. v16 adds 5-layer analysis output (`layer`, `layer_name`, `owasp_asi`, `protocol_surface`) and `--compliance owasp-asi`. MIT licensed; single runtime dependency (`ws`)." license: MIT metadata: {"openclaw": {"requires": {"bins": ["node"]}}} --- # guard-scanner Security scanner and runtime guard for the agentic stack. Use it before installing a skill from ClawHub, when auditing MCP servers or OpenClaw workspaces, when wiring security checks into CI/CD, or when you want OpenClaw to block dangerous tool calls at runtime. It covers prompt injection, identity hijacking, memory poisoning, A2A contagion, MCP abuse, secret leakage, supply-chain abuse, and dangerous execution patterns. v16 adds a 5-layer analysis pipeline, OWASP ASI projection mode, richer finding metadata, and Rust runtime evidence integration. ## Quick Start ```bash # Scan a skill directory npx -y @guava-parity/guard-scanner ./my-skills/ --verbose # Scan with identity protection npx -y @guava-parity/guard-scanner ./skills/ --soul-lock --strict # Filter to OWASP ASI mapped findings only npx -y @guava-parity/guard-scanner ./skills/ --compliance owasp-asi --format json # Installed CLI guard-scanner ./skills/ --strict # npm exec compatibility npm exec --yes --package=@guava-parity/guard-scanner -- guard-scanner ./skills/ --strict ``` ## Core Commands ### Scan ```bash guard-scanner <dir> # Scan directory guard-scanner <dir> -v # Verbose output guard-scanner <dir> --json # JSON report file guard-scanner <dir> --sarif # SARIF for CI/CD guard-scanner <dir> --html # HTML report guard-scanner <dir> --compliance owasp-asi --format json ``` ### 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 ``` ### MCP Server Start as MCP server for IDE integration. ```bash guard-scanner serve ``` Editor config (Cursor, Windsurf, Claude Code, OpenClaw): ```json { "mcpServers": { "guard-scanner": { "command": "npx", "args": ["-y", "@guava-parity/guard-scanner", "serve"] } } } ``` MCP tools: `scan_skill`, `scan_text`, `check_tool_call`, `audit_assets`, `get_stats`, and the async experimental task helpers. ## Quality Contract Public quality contract: - Benchmark corpus version: `2026-03-15.quality-v17` - Precision target: `>= 0.90` - Recall target: `>= 0.90` - FPR/FNR budgets: `<= 0.10` - Explainability completeness: `1.0` - Runtime policy latency budget: `5ms` Evidence surfaces: - `docs/spec/capabilities.json` - `docs/data/corpus-metrics.json` - `docs/data/benchmark-ledger.json` - `docs/data/fp-ledger.json` ### Watch Mode Monitor skill directories in real-time during development. ```bash guard-scanner watch ./skills/ --strict --soul-lock ``` ### VirusTotal Integration Combine semantic detection with VirusTotal's 70+ antivirus engines. Optional — guard-scanner works fully without it. ```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.13`, with regression coverage kept on `v2026.3.8`. The `before_tool_call` hook provides 27 runtime checks across 5 defense layers, while v16 scan output adds a second 5-layer analysis view: | 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+). ## v16 Output Surface - Finding fields: `layer`, `layer_name`, `owasp_asi`, `protocol_surface` - Compliance mode: `--compliance owasp-asi` - MCP summaries: `scan_skill`, `scan_text`, and `get_stats` now surface layer and ASI context - Runtime evidence: Rust `memory_integrity` and `soul_hard_gate` modules are represented in the TypeScript pipeline ## Key Flags | Flag | Effect | |------|--------| | `--verbose` / `-v` | Detailed findings with line numbers | | `--strict` | Lower detection thresholds | | `--soul-lock` | Enable identity protection patterns | | `--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 | | `--compliance owasp-asi` | Keep only OWASP ASI mapped findings in output | ## 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 ``` ## Threat Categories 35 categories covering OWASP LLM Top 10 + Agentic Security Top 10. See `src/patterns.ts` for the full pattern database. Key categories: - **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 > ⚿ = Requires `--soul-lock` flag

Security Status