guard-scanner

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.

Related MCP server: AgentAudit

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:

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

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

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:

Quality Contract

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

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