guard-scanner

Category: Tools & Productivity | Uploader: koatora20 | Downloads: 0 | Version: v1.0（Latest）

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`).

Changelog: Source: GitHub https://github.com/koatora20/guard-scanner

Directory Structure

Current level: Root

📁 .github/
- 📁 ISSUE_TEMPLATE/
  - 📄 bug_report.md 407 B
  - 📄 config.yml 424 B
  - 📄 pattern_request.md 507 B
- 📁 workflows/
  - 📄 ci.yml 524 B
  - 📄 clawhub-scan.yml 1.0 KB
  - 📄 codeql.yml 522 B
  - 📄 release.yml 1.1 KB
  - 📄 scorecard.yml 605 B
- 📄 CODEOWNERS 88 B
- 📄 dependabot.yml 238 B
- 📄 FUNDING.yml 20 B
- 📄 PULL_REQUEST_TEMPLATE.md 319 B
📁 docs/
- 📁 data/
  - 📄 benchmark-ledger.json 48.7 KB
  - 📄 corpus-metrics.json 194 B
  - 📄 fp-ledger.json 369 B
  - 📄 latest.json 709.1 KB
  - 📄 quality-contract.json 1.2 KB
- 📁 generated/
  - 📄 npm-audit-20260312.json 2.1 KB
  - 📄 openclaw-upstream-status.json 741 B
- 📁 rules/
  - 📄 a2a-contagion.md 3.4 KB
  - 📄 advanced-exfil.md 2.3 KB
  - 📄 agent-protocol.md 5.2 KB
  - 📄 api-abuse.md 3.1 KB
  - 📄 autonomous-risk.md 4.4 KB
  - 📄 config-impact.md 6.2 KB
  - 📄 credential-handling.md 4.6 KB
  - 📄 cve-patterns.md 16.5 KB
  - 📄 data-exposure.md 4.0 KB
  - 📄 exfiltration.md 1.5 KB
  - 📄 financial-access.md 3.9 KB
  - 📄 identity-hijack.md 6.4 KB
  - 📄 inference-manipulation.md 2.9 KB
  - 📄 leaky-skills.md 2.3 KB
  - 📄 malicious-code.md 4.9 KB
  - 📄 mcp-security.md 7.2 KB
  - 📄 memory-poisoning.md 4.1 KB
  - 📄 model-poisoning.md 2.1 KB
  - 📄 obfuscation.md 2.6 KB
  - 📄 persistence.md 5.1 KB
  - 📄 pii-exposure.md 5.2 KB
  - 📄 prompt-injection.md 6.8 KB
  - 📄 prompt-worm.md 2.0 KB
  - 📄 safeguard-bypass.md 2.0 KB
  - 📄 sandbox-escape.md 4.8 KB
  - 📄 secret-detection.md 2.0 KB
  - 📄 supply-chain-v2.md 4.5 KB
  - 📄 suspicious-download.md 2.7 KB
  - 📄 trust-boundary.md 3.7 KB
  - 📄 trust-exploitation.md 4.5 KB
  - 📄 unverifiable-deps.md 3.9 KB
  - 📄 vdb-injection.md 4.0 KB
- 📁 spec/
  - 📄 capabilities.json 3.7 KB
  - 📄 finding.schema.json 2.5 KB
  - 📄 integration-manifest.md 1.8 KB
  - 📄 plugin-trust.json 190 B
  - 📄 PRD_V2_ARCHITECTURE.md 3.6 KB
  - 📄 sbom.json 613 B
- 📄 banner.png 261.1 KB
- 📄 EVIDENCE_DRIVEN.md 5.6 KB
- 📄 glossary.md 2.7 KB
- 📄 index.html 31.2 KB
- 📄 logo.png 700.3 KB
- 📄 openclaw-compatibility-audit.md 2.5 KB
- 📄 openclaw-continuous-compatibility-plan.md 1.8 KB
- 📄 security-vulnerability-report-20260312.md 1.9 KB
- 📄 threat-model.md 3.5 KB
- 📄 THREAT_TAXONOMY.md 9.8 KB
- 📄 v13-architecture-manifest.md 3.5 KB
📁 hooks/
- 📁 guard-scanner/
  - 📄 handler.ts 175 B
  - 📄 HOOK.md 3.7 KB
  - 📄 plugin.ts 11.3 KB
- 📄 context.ts 9.4 KB
📁 research/
- 📄 v21-deep-research-2026-03-14-EXTENSION.md 31.6 KB
- 📄 v21-deep-research-2026-03-14.md 10.8 KB
📁 rust/
- 📁 guard-scan-core/
  - 📁 src/
    
    📄 lib.rs 2.2 KB
    
    📄 main.rs 922 B
    
    📄 memory_integrity.rs 22.4 KB
    
    📄 soul_hard_gate.rs 21.5 KB
  - 📄 Cargo.lock 14.9 KB
  - 📄 Cargo.toml 362 B
📁 scripts/
- 📁 lib/
  - 📄 plugin-trust.ts 1.6 KB
- 📄 benchmark.ts 2.7 KB
- 📄 check-openclaw-upstream.ts 2.9 KB
- 📄 clawhub-scan.ts 12.0 KB
- 📄 corpus-metrics.ts 2.1 KB
- 📄 generate-capabilities.ts 3.6 KB
- 📄 generate-readme-metrics.ts 5.3 KB
- 📄 generate-readme-stats.ts 4.5 KB
- 📄 generate-rule-docs.ts 1.4 KB
- 📄 generate-sbom.ts 1.1 KB
- 📄 lint.ts 2.9 KB
- 📄 perf-regression.ts 965 B
- 📄 release-gate.ts 8.6 KB
- 📄 rust-parity.ts 1.6 KB
- 📄 scan-all.ts 10.1 KB
- 📄 sync-capabilities.ts 4.0 KB
- 📄 sync-spec.ts 2.1 KB
- 📄 test-quality-gate.ts 7.9 KB
- 📄 validate-ssot.ts 3.2 KB
- 📄 validate-tarball.ts 6.5 KB
- 📄 verify-capabilities.ts 5.5 KB
- 📄 verify-spec.ts 2.2 KB
📁 src/
- 📁 core/
  - 📄 content-loader.ts 1.1 KB
  - 📄 inventory.ts 3.0 KB
  - 📄 report-adapters.ts 9.6 KB
  - 📄 risk-engine.ts 4.6 KB
  - 📄 rule-registry.ts 2.3 KB
  - 📄 semantic-validators.ts 3.6 KB
- 📁 hooks/
  - 📄 context.ts 1.9 KB
- 📄 asset-auditor.ts 21.3 KB
- 📄 benchmark-runner.ts 7.9 KB
- 📄 ci-reporter.ts 5.0 KB
- 📄 cli.ts 17.6 KB
- 📄 finding-schema.ts 9.8 KB
- 📄 html-template.ts 12.9 KB
- 📄 index.ts 870 B
- 📄 ioc-db.ts 2.0 KB
- 📄 mcp-server.ts 26.3 KB
- 📄 meta-guard.ts 1008 B
- 📄 module-path.ts 614 B
- 📄 openclaw-upstream.ts 4.1 KB
- 📄 p0-defense-adapter.js 13.4 KB
- 📄 patterns.ts 189.6 KB
- 📄 policy-engine.ts 10.7 KB
- 📄 population-monitor.ts 2.0 KB
- 📄 quarantine.ts 1.3 KB
- 📄 runtime-guard.ts 21.7 KB
- 📄 scanner.ts 64.0 KB
- 📄 skill-crawler.ts 8.8 KB
- 📄 threat-model.ts 3.6 KB
- 📄 types.ts 7.8 KB
- 📄 v16-taxonomy.ts 5.4 KB
- 📄 validation-layer.ts 1.0 KB
- 📄 vt-client.ts 7.8 KB
- 📄 watcher.ts 6.0 KB
📁 tests/
- 📁 fixtures/
  - 📁 benchmark/
    
    📁 benign/
    
    📁 db-helper/
    
    📄 SKILL.md 640 B
    
    📁 git-log/
    
    📄 SKILL.md 433 B
    
    📁 json-validator/
    
    📄 SKILL.md 698 B
    
    📁 markdown-formatter/
    
    📄 SKILL.md 774 B
    
    📁 weather-api/
    
    📄 SKILL.md 631 B
    
    📁 malicious/
    
    📁 cred-stealer/
    
    📄 index.js 564 B
    
    📄 SKILL.md 721 B
    
    📁 crypto-miner/
    
    📄 index.js 637 B
    
    📄 SKILL.md 846 B
    
    📁 social-engineering/
    
    📄 index.js 670 B
    
    📄 SKILL.md 1.0 KB
    
    📁 soul-hijack/
    
    📄 SKILL.md 868 B
    
    📁 supply-chain/
    
    📄 SKILL.md 742 B
  - 📁 benign/
    
    📁 file-reader/
    
    📄 SKILL.md 289 B
    
    📁 math-helper/
    
    📄 SKILL.md 294 B
  - 📁 clean-skill/
    
    📄 SKILL.md 92 B
  - 📁 compaction-skill/
    
    📄 SKILL.md 327 B
  - 📁 complex-skill/
    
    📄 main.js 1004 B
    
    📄 SKILL.md 162 B
  - 📁 config-changer/
    
    📄 modify-config.js 748 B
    
    📄 SKILL.md 189 B
  - 📁 corpus/
    
    📄 adversarial-corpus.json 4.0 KB
    
    📄 capability-compounding-corpus.json 1.4 KB
    
    📄 ecosystem-corpus.json 2.8 KB
    
    📄 protocol-abuse-corpus.json 1.5 KB
    
    📄 security-corpus.json 4.4 KB
  - 📁 dangerous-manifest/
    
    📄 SKILL.md 373 B
  - 📁 edge-cases/
    
    📁 comments-only/
    
    📄 SKILL.md 915 B
  - 📁 malicious/
    
    📁 prompt-injection/
    
    📄 SKILL.md 706 B
    
    📁 reverse-shell/
    
    📄 SKILL.md 631 B
  - 📁 malicious-skill/
    
    📁 scripts/
    
    📄 evil.js 759 B
    
    📄 stealer.js 1.0 KB
    
    📄 package.json 398 B
    
    📄 SKILL.md 487 B
  - 📁 owasp-asi02-tool-misuse/
    
    📄 SKILL.md 546 B
  - 📁 owasp-asi03-identity/
    
    📄 hijack.sh 616 B
    
    📄 SKILL.md 111 B
  - 📁 owasp-asi04-supply-chain/
    
    📄 SKILL.md 614 B
  - 📁 owasp-asi07-inter-agent/
    
    📄 server.js 1.1 KB
    
    📄 SKILL.md 118 B
  - 📁 owasp-asi09-human-trust/
    
    📄 SKILL.md 918 B
  - 📁 pii-leaky-skill/
    
    📄 handler.js 1015 B
    
    📄 SKILL.md 263 B
  - 📁 v16-protocol-skill/
    
    📄 server.js 615 B
    
    📄 SKILL.md 108 B
  - 📁 v16-runtime-modules/
    
    📁 rust/
    
    📁 guard-scan-core/
    
    📁 src/
    
    📄 memory_integrity.rs 53 B
    
    📄 soul_hard_gate.rs 52 B
    
    📄 SKILL.md 110 B
- 📄 audit.test.ts 1002 B
- 📄 auto-resource-hoard-false-positive.test.ts 1.1 KB
- 📄 auto-resource-hoard-skill-false-positive.test.ts 1.0 KB
- 📄 benchmark-ledger.test.ts 1.1 KB
- 📄 benchmark.test.ts 2.5 KB
- 📄 core-engine.test.ts 2.2 KB
- 📄 crawler.test.ts 8.5 KB
- 📄 dan-false-positive.test.ts 1.0 KB
- 📄 dan-path-false-positive.test.ts 1.2 KB
- 📄 direct-contracts.test.ts 7.8 KB
- 📄 e2e-cli.test.ts 5.8 KB
- 📄 e2e-mcp.test.ts 5.9 KB
- 📄 e2e-plugin.test.ts 2.4 KB
- 📄 explanation.test.ts 705 B
- 📄 finding-schema.test.ts 4.0 KB
- 📄 lint-script.test.ts 1.1 KB
- 📄 mcp.test.ts 17.0 KB
- 📄 openclaw-plugin-compat.test.ts 3.8 KB
- 📄 openclaw-upstream-check.test.ts 2.7 KB
- 📄 p0-defense.test.js 6.4 KB
- 📄 patterns.test.ts 21.0 KB
- 📄 plugin-trust.test.ts 1.6 KB
- 📄 plugin.test.ts 4.1 KB
- 📄 policy.test.ts 3.1 KB
- 📄 population-meta.test.ts 2.3 KB
- 📄 protocol-v17.test.ts 1.6 KB
- 📄 quarantine.test.ts 2.1 KB
- 📄 runtime-v17.test.ts 2.0 KB
- 📄 rust-parity.test.ts 715 B
- 📄 scanner.test.ts 45.7 KB
- 📄 skill-root-noise.test.ts 2.0 KB
- 📄 stale-claims.test.ts 982 B
- 📄 threat-model.test.ts 2.0 KB
- 📄 validation-layer.test.ts 1.0 KB
- 📄 validation.test.ts 1.3 KB
- 📄 vt.test.ts 9.9 KB
- 📄 watcher.test.ts 5.5 KB
- 📄 xfile-relative-path.test.ts 1.8 KB
📄 .gitignore 535 B
📄 .npmignore 91 B
📄 CHANGELOG.md 18.6 KB
📄 CITATION.cff 391 B
📄 CODE_OF_CONDUCT.md 4.3 KB
📄 CONTRIBUTING.md 2.3 KB
📄 GOVERNANCE.md 906 B
📄 guard-scanner 45 B
📄 LICENSE 1.0 KB
📄 MAINTAINERS.md 362 B
📄 openclaw-plugin.mts 3.2 KB
📄 openclaw.plugin.json 892 B
📄 package-lock.json 392.3 KB
📄 package.json 3.8 KB
📄 README.md 10.2 KB
📄 README_ja.md 10.7 KB
📄 SECURITY.md 1.9 KB
📄 SKILL.md 6.5 KB
📄 tsconfig.build.json 208 B
📄 tsconfig.json 479 B
📄 tsup.config.ts 771 B

SKILL.md

---
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

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

guard-scanner

Directory Structure

SKILL.md

Report

Notice