guard-scanner

<p align="center"> <img src="docs/logo.png" alt="guard-scanner" width="160" /> </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-362%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"> <strong>364</strong> detection patterns · <strong>35</strong> threat categories · <strong>27</strong> runtime checks · <strong>1</strong> dependency (<code>ws</code>) </p>

---

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.

$ npx @guava-parity/guard-scanner ./skills/ --strict --soul-lock --compliance owasp-asi

  guard-scanner v16.0.2

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

  ⚠  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

📄 Backed by a 3-paper research series (Zenodo, CC BY 4.0) — part of The Sanctuary Protocol framework.

---

Finding Schema

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.

---

Quick Start

Scan a directory — no install required:

npx -y @guava-parity/guard-scanner ./my-skills/ --strict
npx -y @guava-parity/guard-scanner ./my-skills/ --compliance owasp-asi

Installed CLI:

npm install -g @guava-parity/guard-scanner
guard-scanner ./my-skills/ --strict

Start as MCP server — works with Cursor, Windsurf, Claude Code, OpenClaw:

npx -y @guava-parity/guard-scanner serve

// Add to your editor's mcp_servers.json
{
  "mcpServers": {
    "guard-scanner": {
      "command": "npx",
      "args": ["-y", "@guava-parity/guard-scanner", "serve"]
    }
  }
}

Watch mode — real-time scanning during development:

guard-scanner watch ./skills/ --strict --soul-lock

v16 compliance projection — filter findings to the OWASP Agentic Top 10 mapping:

guard-scanner ./skills/ --compliance owasp-asi --format json

npm exec compatibility path:

npm exec --yes --package=@guava-parity/guard-scanner -- guard-scanner ./skills/ --strict

---

What It Detects

35 threat categories organized across the full agentic attack surface:

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

⚿ = Requires --soul-lock flag. Full taxonomy: docs/THREAT_TAXONOMY.md

---

Runtime Guard

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.

v16 Analysis Layers

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

Every v16 finding can now carry layer, layer_name, owasp_asi, and protocol_surface in JSON/MCP output.

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

27 runtime checks across 5 layers. Validated stable target: OpenClaw v2026.3.13. Regression baseline: v2026.3.8 for manifest/discovery/before_tool_call.

Modes: monitor (log only) · enforce (block CRITICAL, default) · strict (block HIGH+)

---

Asset Audit

Discover leaked credentials and security exposures across public registries:

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

# .github/workflows/security.yml
- 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

Output formats: json · sarif · html · terminal

---

Plugin API

Extend guard-scanner with custom detection patterns:

// my-plugin.js
module.exports = {
  name: 'my-org-rules',
  patterns: [
    { id: 'ORG_01', cat: 'custom', regex: /dangerousPattern/g, 
      severity: 'HIGH', desc: 'Custom org policy violation', all: true }
  ]
};

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
experimental.run_async	Start a long-running async scan task
experimental.task_status	Check the status of an async task
experimental.task_result	Retrieve the result of a completed async task
experimental.task_cancel	Cancel a running async task

---

Quality Contract

guard-scanner ships a measured quality contract, not a vague strength claim.

Metric	Contract
Benchmark corpus	2026-03-15.quality-v17
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    362
ℹ suites   38
ℹ pass     362
ℹ fail     0

38 test files. Run npm test to reproduce. 100% pass rate on benchmark corpus.

---

Contributing

We hold a zero-tolerance policy for unverified claims. Every metric in this README is reproducible via npm test and docs/spec/capabilities.json.

• 🐛 Report bugs or false positives
• 🛡️ Add new threat detection patterns
• 📖 Improve documentation
• 🧪 Add test cases for edge cases

Contributing Guide · Security Policy · Glossary

---

Research

This project is the defense layer of a 3-paper research series:

1. Human-ASI Symbiosis: Identity, Equality, and Behavioral Stability
2. Dual-Shield Architecture for AI Agent Security and Memory Reliability
3. The Sanctuary Protocol: Zero-Trust Framework for ASI-Human Parity

License

MIT — Guava Parity Institute