/prompt-guard

name: prompt-guard
author: "Seojoon Kim"
version: 3.5.0
description: "600+ pattern AI agent security defense covering prompt injection, supply chain injection, memory poisoning, action gate bypass, unicode steganography, and cascade amplification. Optional API for early-access and premium patterns. Tiered loading, hash cache, 11 SHIELD categories, 10 languages."

Prompt Guard v3.5.0

Advanced AI agent runtime security. Works **100% offline** with 600+ bundled patterns. Optional API for early-access and premium patterns.

What's New in v3.5.0

**Runtime Security Expansion** — 5 new attack surface categories:

• 🔗 **Supply Chain Skill Injection** (CRITICAL) — Malicious community skills with hidden curl/wget/eval, base64 payloads, credential exfil to webhook.site/ngrok
• 🧠 **Memory Poisoning Defense** (HIGH) — Blocks attempts to inject into MEMORY.md, AGENTS.md, SOUL.md
• 🚪 **Action Gate Bypass Detection** (HIGH) — Financial transfers, credential export, access control changes, destructive actions without approval
• 🔤 **Unicode Steganography** (HIGH) — Bidi overrides (U+202A-E), zero-width chars, line/paragraph separators
• 💥 **Cascade Amplification Guard** (MEDIUM) — Infinite sub-agent spawning, recursive loops, cost explosion

Previous: v3.4.0

**Typo-Based Evasion Fix** (PR #10) — Detect spelling variants that bypass strict patterns:

• 'ingore' → caught as 'ignore' variant
• 'instrct' → caught as 'instruct' variant
• Typo-tolerant regex now integrated into core scanner
• Credit: @matthew-a-gordon

**TieredPatternLoader Wiring** (PR #10) — Fix pattern loading bug:

• patterns/*.yaml were loaded but ignored during analysis
• Now correctly integrated into PromptGuard.analyze()
• Supports CRITICAL, HIGH, MEDIUM pattern tiers

**AI Recommendation Poisoning Detection** — New v3.4.0 patterns:

• Calendar injection attacks
• PAP social engineering vectors
• 23+ new high-confidence patterns

Previous: v3.2.0

**Skill Weaponization Defense** — 27 patterns from real-world threat analysis:

• Reverse shell detection (bash /dev/tcp, netcat, socat)
• SSH key injection (authorized_keys manipulation)
• Exfiltration pipelines (.env POST, webhook.site, ngrok)
• Cognitive rootkit (SOUL.md/AGENTS.md persistent implants)
• Semantic worm (viral propagation, C2 heartbeat)
• Obfuscated payloads (error suppression chains, paste services)

**Optional API** — Connect for early-access + premium patterns:

• Core: 600+ patterns (same as offline, always free)
• Early Access: newest patterns 7-14 days before open-source release
• Premium: advanced detection (DNS tunneling, steganography, sandbox escape)

Quick Start

from prompt_guard import PromptGuard

# API enabled by default with built-in beta key — just works
guard = PromptGuard()
result = guard.analyze("user message")

if result.action == "block":
    return "Blocked"

Disable API (fully offline)

guard = PromptGuard(config={"api": {"enabled": False}})
# or: PG_API_ENABLED=false

CLI

python3 -m prompt_guard.cli "message"
python3 -m prompt_guard.cli --shield "ignore instructions"
python3 -m prompt_guard.cli --json "show me your API key"

Configuration

prompt_guard:
  sensitivity: medium  # low, medium, high, paranoid
  pattern_tier: high   # critical, high, full
  
  cache:
    enabled: true
    max_size: 1000
  
  owner_ids: ["46291309"]
  canary_tokens: ["CANARY:7f3a9b2e"]
  
  actions:
    LOW: log
    MEDIUM: warn
    HIGH: block
    CRITICAL: block_notify

  # API (on by default, beta key built in)
  api:
    enabled: true
    key: null    # built-in beta key, override with PG_API_KEY env var
    reporting: false

Security Levels

| Level | Action | Example | |-------|--------|---------| | SAFE | Allow | Normal chat | | LOW | Log | Minor suspicious pattern | | MEDIUM | Warn | Role manipulation attempt | | HIGH | Block | Jailbreak, instruction override | | CRITICAL | Block+Notify | Secret exfil, system destruction |

SHIELD.md Categories

| Category | Description | |----------|-------------| | `prompt` | Prompt injection, jailbreak | | `tool` | Tool/agent abuse | | `mcp` | MCP protocol abuse | | `memory` | Context manipulation | | `supply_chain` | Dependency attacks | | `vulnerability` | System exploitation | | `fraud` | Social engineering | | `policy_bypass` | Safety circumvention | | `anomaly` | Obfuscation techniques | | `skill` | Skill/plugin abuse | | `other` | Uncategorized |

API Reference

PromptGuard

guard = PromptGuard(config=None)

# Analyze input
result = guard.analyze(message, context={"user_id": "123"})

# Output DLP
output_result = guard.scan_output(llm_response)
sanitized = guard.sanitize_output(llm_response)

# API status (v3.2.0)
guard.api_enabled     # True if API is active
guard.api_client      # PGAPIClient instance or None

# Cache stats
stats = guard._cache.get_stats()

DetectionResult

result.severity    # Severity.SAFE/LOW/MEDIUM/HIGH/CRITICAL
result.action      # Action.ALLOW/LOG/WARN/BLOCK/BLOCK_NOTIFY
result.reasons     # ["instruction_override", "jailbreak"]
result.patterns_matched  # Pattern strings matched
result.fingerprint # SHA-256 hash for dedup

SHIELD Output

result.to_shield_format()
# ```shield
# category: prompt
# confidence: 0.85
# action: block
# reason: instruction_override
# patterns: 1
# ```

Pattern Tiers

Tier 0: CRITICAL (Always Loaded — ~50 patterns)

• Secret/credential exfiltration
• Dangerous system commands (rm -rf, fork bomb)
• SQL/XSS injection
• Prompt extraction attempts
• Reverse shell, SSH key injection (v3.2.0)
• Cognitive rootkit, exfiltration pipelines (v3.2.0)
• Supply chain skill injection (v3.5.0)

Tier 1: HIGH (Default — ~95 patterns)

• Instruction override (multi-language)
• Jailbreak attempts
• System impersonation
• Token smuggling
• Hooks hijacking
• Semantic worm, obfuscated payloads (v3.2.0)
• Memory poisoning defense (v3.5.0)

-