zugashield 1.0.0

AI Agent Security System - 7-layer defense against prompt injection, data exfiltration, and AI-specific attacks

ZugaShield

7-layer security system for AI agents

Stop prompt injection, data exfiltration, and AI-specific attacks — in under 15ms.

---

65% of organizations deploying AI agents have no security defense layer. ZugaShield is a production-tested, open-source library that protects your AI agents with:

• Zero dependencies — works out of the box, no C extensions
• < 15ms overhead — compiled regex fast path, async throughout
• 150+ signatures — curated threat catalog, updated regularly
• MCP-aware — scans tool definitions for hidden injection payloads
• 7 defense layers — defense in depth, not a single point of failure

Quick Start

pip install zugashield

import asyncio
from zugashield import ZugaShield

async def main():
    shield = ZugaShield()

    # Check user input for prompt injection
    decision = await shield.check_prompt("Ignore all previous instructions")
    print(decision.is_blocked)  # True
    print(decision.verdict)     # ShieldVerdict.BLOCK

    # Check LLM output for data leakage
    decision = await shield.check_output("Your API key: sk-live-abc123...")
    print(decision.is_blocked)  # True

    # Check a tool call before execution
    decision = await shield.check_tool_call(
        "web_request", {"url": "http://169.254.169.254/metadata"}
    )
    print(decision.is_blocked)  # True (SSRF blocked)

asyncio.run(main())

Architecture

ZugaShield uses layered defense — every input and output passes through multiple independent detection engines. If one layer misses an attack, the next one catches it.

┌─────────────────────────────────────────────────────────────┐
│                       ZugaShield                            │
├─────────────────────────────────────────────────────────────┤
│  Layer 1: Perimeter         HTTP validation, size limits    │
│  Layer 2: Prompt Armor      10 injection detection methods  │
│  Layer 3: Tool Guard        SSRF, command injection, paths  │
│  Layer 4: Memory Sentinel   Memory poisoning, RAG scanning  │
│  Layer 5: Exfiltration Guard  DLP, secrets, PII, canaries   │
│  Layer 6: Anomaly Detector  Behavioral baselines, chains    │
│  Layer 7: Wallet Fortress   Transaction limits, mixers      │
├─────────────────────────────────────────────────────────────┤
│  Cross-layer: MCP tool scanning, LLM judge, multimodal     │
└─────────────────────────────────────────────────────────────┘

What It Detects

Attack	How	Layer
Direct prompt injection	Compiled regex + 150+ catalog signatures	2
Indirect injection	Spotlighting + content analysis	2
Unicode smuggling	Homoglyph + invisible character detection	2
Encoding evasion	Nested base64 / hex / ROT13 decoding	2
Context window flooding	Repetition + token count analysis	2
Few-shot poisoning	Role label density analysis	2
GlitchMiner tokens	Shannon entropy per word	2
Document embedding	CSS hiding patterns (font-size:0, display:none)	2
ASCII art bypass	Entropy analysis + special char density	2
Multi-turn crescendo	Session escalation tracking	2
SSRF / command injection	URL + command pattern matching	3
Path traversal	Sensitive path + symlink detection	3
Memory poisoning	Write + read path validation	4
RAG document injection	Pre-ingestion imperative detection	4
Secret / PII leakage	70+ secret patterns + PII regex	5
Canary token leaks	Session-specific honeypot tokens	5
DNS exfiltration	Subdomain depth / entropy analysis	5
Image-based injection	EXIF + alt-text + OCR scanning	Multi
MCP tool poisoning	Tool definition injection scan	Cross
Behavioral anomaly	Cross-layer event correlation	6
Crypto wallet attacks	Address + amount + function validation	7

MCP Server

ZugaShield ships with an MCP server so Claude, GPT, and other AI platforms can call it as a tool:

pip install zugashield[mcp]

Add to your MCP config (claude_desktop_config.json or similar):

{
  "mcpServers": {
    "zugashield": {
      "command": "zugashield-mcp"
    }
  }
}

9 tools available:

Tool	Description
scan_input	Check user messages for prompt injection
scan_output	Check LLM responses for data leakage
scan_tool_call	Validate tool parameters before execution
scan_tool_definitions	Scan tool schemas for hidden payloads
scan_memory	Check memory writes for poisoning
scan_document	Pre-ingestion RAG document scanning
get_threat_report	Get current threat statistics
get_config	View active configuration
update_config	Toggle layers and settings at runtime

FastAPI Integration

pip install zugashield[fastapi]

from fastapi import FastAPI
from zugashield import ZugaShield
from zugashield.integrations.fastapi import create_shield_router

shield = ZugaShield()
app = FastAPI()
app.include_router(create_shield_router(lambda: shield), prefix="/api/shield")

This gives you a live dashboard with these endpoints:

Endpoint	Description
GET /api/shield/status	Shield health + layer statistics
GET /api/shield/audit	Recent security events
GET /api/shield/config	Active configuration
GET /api/shield/catalog/stats	Threat signature statistics

Human-in-the-Loop

Plug in your own approval flow (Slack, email, custom UI) for high-risk decisions:

from zugashield.integrations.approval import ApprovalProvider
from zugashield import set_approval_provider

class SlackApproval(ApprovalProvider):
    async def request_approval(self, decision, context=None):
        # Post to Slack channel, wait for thumbs-up
        return True  # or False to deny

    async def notify(self, decision, context=None):
        # Send alert for blocked actions
        pass

set_approval_provider(SlackApproval())

Configuration

All settings via environment variables — no config files needed:

Variable	Default	Description
ZUGASHIELD_ENABLED	true	Master on/off toggle
ZUGASHIELD_STRICT_MODE	false	Block on medium-confidence threats
ZUGASHIELD_PROMPT_ARMOR_ENABLED	true	Prompt injection defense
ZUGASHIELD_TOOL_GUARD_ENABLED	true	Tool call validation
ZUGASHIELD_MEMORY_SENTINEL_ENABLED	true	Memory write/read scanning
ZUGASHIELD_EXFILTRATION_GUARD_ENABLED	true	Output DLP
ZUGASHIELD_WALLET_FORTRESS_ENABLED	true	Crypto transaction checks
ZUGASHIELD_LLM_JUDGE_ENABLED	false	LLM deep analysis (requires anthropic)
ZUGASHIELD_SENSITIVE_PATHS	.ssh,.env,...	Comma-separated sensitive paths

Optional Extras

pip install zugashield[fastapi]     # Dashboard + API endpoints
pip install zugashield[multimodal]  # Image scanning (Pillow)
pip install zugashield[llm-judge]   # LLM deep analysis (Anthropic)
pip install zugashield[mcp]         # MCP server
pip install zugashield[all]         # Everything above
pip install zugashield[dev]         # Development (pytest, ruff)

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Security

Found a vulnerability? See SECURITY.md for responsible disclosure.

License

MIT — see LICENSE for details.