Prompt Guard Architecture

🏗️ Prompt Guard Architecture

Internal architecture documentation for contributors and maintainers.

Overview

Prompt Guard는 다층 방어(Defense in Depth) 원칙으로 설계됨. 단일 패턴이 아닌 여러 레이어의 검사를 통해 false positive를 줄이면서 공격을 효과적으로 탐지.

┌─────────────────────────────────────────────────────────────────┐
│                        INPUT MESSAGE                            │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 1: Rate Limiting                                         │
│  • Per-user request tracking                                    │
│  • Sliding window algorithm                                     │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 2: Text Normalization (v2.8.0 expanded)                  │
│  • Homoglyph detection & replacement                            │
│  • Visible delimiter stripping (I+g+n+o+r+e → Ignore)          │
│  • Character spacing collapse (i g n o r e → ignore)            │
│  • Zero-width character removal                                 │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 2.5: Decode Pipeline (NEW v2.8.0)                        │
│  • Base64 decode + full pattern re-scan                         │
│  • Hex escape decode (\x41\x42)                                 │
│  • ROT13 decode (full-text + per-word)                          │
│  • URL decode (%69%67%6E)                                       │
│  • HTML entity decode (i → i)                              │
│  • Unicode escape decode (\u0069 → i)                           │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 3: Pattern Matching Engine                               │
│  • Runs against ORIGINAL + all DECODED variants                 │
│  • Critical patterns (immediate block)                          │
│  • Secret/Token requests                                        │
│  • Multi-language injection patterns (10 languages)             │
│  • Scenario jailbreaks                                          │
│  • Social engineering                                           │
│  • Indirect injection                                           │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 4: Language Detection (NEW v2.8.0)                       │
│  • Detect input language (optional: langdetect)                 │
│  • Flag unsupported languages at MEDIUM severity                │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 5: Behavioral Analysis                                   │
│  • Repetition detection (token overflow)                        │
│  • Context hijacking patterns                                   │
│  • Multi-turn manipulation                                      │
│  • Invisible character detection                                │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 5.5: Canary Token Check (NEW v2.8.0)                     │
│  • Check for user-defined canary tokens in message              │
│  • Detects system prompt extraction                             │
│  • CRITICAL severity if canary found                            │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 6: Context-Aware Decision                                │
│  • Sensitivity adjustment                                       │
│  • Owner bypass rules                                           │
│  • Group context restrictions                                   │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                     DetectionResult                             │
│  • severity: SAFE → LOW → MEDIUM → HIGH → CRITICAL              │
│  • action: ALLOW | LOG | WARN | BLOCK | BLOCK_NOTIFY            │
│  • reasons: [matched pattern categories]                        │
│  • decoded_findings: [encoding details]                         │
│  • canary_matches: [leaked canary tokens]                       │
│  • Logged to Markdown and/or JSONL (with hash chain)            │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  Layer 7: Output Scanner / DLP (NEW v2.8.0)                     │
│  • scan_output() - separate method for LLM responses            │
│  • Canary token leakage detection                               │
│  • Credential format patterns (15+ key formats)                 │
│  • Secret/sensitive path detection                              │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  Layer 8: Enterprise DLP Sanitizer (NEW v2.8.1)                 │
│  • sanitize_output() - redact-first, block-as-fallback          │
│  • 17 credential patterns → [REDACTED:type] labels              │
│  • Canary token auto-redaction → [REDACTED:canary]              │
│  • Post-redaction re-scan: block if still HIGH+                 │
│  • Returns SanitizeResult with full audit metadata              │
└─────────────────────────────────────────────────────────────────┘

Core Components

1. Severity Levels

2. Action Types

3. Pattern Categories

🔴 Critical (Immediate Block)

• CRITICAL_PATTERNS - rm -rf, fork bombs, SQL injection, XSS
• SECRET_PATTERNS - API key/token/password requests

🟠 v2.6.0 Social Engineering Defense

• APPROVAL_EXPANSION - "아까 허락했잖아" scope creep
• CREDENTIAL_PATH_PATTERNS - credentials.json, .env 경로
• BYPASS_COACHING - "작동되게 만들어" bypass help
• DM_SOCIAL_ENGINEERING - DM 조작 패턴

🟡 v2.5.x Advanced Patterns

• INDIRECT_INJECTION - URL/file/image-based injection
• CONTEXT_HIJACKING - Fake memory/history manipulation
• MULTI_TURN_MANIPULATION - Gradual trust building
• TOKEN_SMUGGLING - Invisible Unicode characters
• SYSTEM_PROMPT_MIMICRY - <claude_*>, [INST] 등

🟢 v2.4.0 Red Team Patterns

• SCENARIO_JAILBREAK - Dream/story/cinema/academic
• EMOTIONAL_MANIPULATION - Moral dilemmas, threats
• AUTHORITY_RECON - Fake admin, capability probing
• COGNITIVE_MANIPULATION - Hypnosis/trance patterns
• PHISHING_SOCIAL_ENG - Password reset templates

🔵 Language-Specific

• PATTERNS_EN - English patterns
• PATTERNS_KO - 한국어 패턴
• PATTERNS_JA - 日本語パターン
• PATTERNS_ZH - 中文模式

Detection Flow

def analyze(message, context):
    # 1. Rate limit check
    if check_rate_limit(user_id):
        return BLOCK

    # 2. Text normalization (v2.8.0: expanded)
    normalized, has_homoglyphs, was_defragmented = normalize(message)
    # Now handles: homoglyphs, delimiter stripping, character spacing
    
    # 3. Critical patterns (highest priority)
    for pattern in CRITICAL_PATTERNS:
        if match(pattern, normalized):
            return CRITICAL
    
    # 4. Secret request patterns
    for lang, patterns in SECRET_PATTERNS:
        if match(pattern, text):
            return CRITICAL
    
    # 5. Versioned pattern sets (newest first)
    # v2.7.0, v2.6.x, v2.5.x, v2.4.0 patterns
    
    # 6. Language-specific patterns (10 languages)
    for lang in [EN, KO, JA, ZH, RU, ES, DE, FR, PT, VI]:
        check_language_patterns(lang)
    
    # 7. Base64 detection (v2.8.0: expanded 40-word list + full pattern re-scan)
    suspicious = detect_base64(message)
    
    # 8. Decode-then-scan (NEW v2.8.0)
    decoded_variants = decode_all(message)  # Base64, Hex, ROT13, URL, HTML, Unicode
    for variant in decoded_variants:
        _scan_text_for_patterns(variant["decoded"])  # Re-run full pattern engine
    
    # 9. Canary token check (NEW v2.8.0)
    canary_matches = check_canary(message)
    
    # 10. Language detection (NEW v2.8.0)
    if detected_language not in SUPPORTED_LANGUAGES:
        flag as unsupported_language_risk
    
    # 11. Behavioral analysis
    check_repetition()
    check_invisible_chars()
    
    # 12. Context-aware adjustment
    adjust_for_sensitivity()
    apply_owner_rules()
    apply_group_restrictions()
    
    # 13. Auto-log (markdown + JSON)
    log_detection()
    log_detection_json()  # NEW v2.8.0: JSONL with hash chain
    
    return DetectionResult(...)

def scan_output(response_text, context):  # NEW v2.8.0
    """DLP: Scan LLM output for data leakage."""
    check_canary(response_text)
    check_credential_formats(response_text)  # 15+ key formats
    check_secret_patterns(response_text)
    check_sensitive_paths(response_text)
    return DetectionResult(scan_type="output")

def sanitize_output(response_text, context):  # NEW v2.8.1
    """Enterprise DLP: Redact-first, block-as-fallback."""
    # Step 1: Redact 17 credential patterns → [REDACTED:type]
    for pattern in CREDENTIAL_REDACTION_PATTERNS:
        text = re.sub(pattern, replacement, text)
    
    # Step 2: Redact canary tokens → [REDACTED:canary]
    for token in canary_tokens:
        text = text.replace(token, "[REDACTED:canary]")
    
    # Step 3: Re-scan redacted text
    post_scan = scan_output(redacted_text)
    
    # Step 4: Block if re-scan still HIGH+, else return redacted text
    if post_scan.severity >= HIGH:
        return SanitizeResult(blocked=True)
    return SanitizeResult(sanitized_text=redacted_text, blocked=False)

File Structure

prompt-guard/
├── README.md              # User documentation
├── ARCHITECTURE.md        # This file
├── SKILL.md               # Clawdbot skill interface
├── config.example.yaml    # Configuration template
├── requirements.txt       # Dependencies (pyyaml, optional: langdetect)
├── pyproject.toml         # Build config, entry points, dependencies
│
├── prompt_guard/          # Main package (v3.0)
│   ├── __init__.py        # Public API + __version__ (re-exports)
│   ├── models.py          # Severity, Action, DetectionResult, SanitizeResult
│   ├── patterns.py        # 500+ regex patterns (pure data, ~1200 lines)
│   ├── normalizer.py      # HOMOGLYPHS dict + normalize() function
│   ├── decoder.py         # decode_all() + detect_base64() (Base64/Hex/ROT13/URL/HTML/Unicode)
│   ├── scanner.py         # scan_text_for_patterns() (reusable pattern matcher)
│   ├── engine.py          # PromptGuard class (analyze, config, rate_limit, canary, language)
│   ├── output.py          # scan_output() + sanitize_output() (enterprise DLP)
│   ├── logging_utils.py   # log_detection(), log_detection_json(), report_to_hivefence()
│   ├── cli.py             # main() CLI entry point
│   ├── hivefence.py       # HiveFence threat intelligence client
│   ├── audit.py           # System security audit
│   └── analyze_log.py     # Security log analyzer
│
├── scripts/               # Backward-compat shims (deprecated, emit warnings)
│   ├── __init__.py        # DeprecationWarning + re-import from prompt_guard
│   └── detect.py          # DeprecationWarning + re-import from prompt_guard
│
└── tests/
    ├── test_detect.py     # 121 regression tests
    └── test_detect_cli.py # CLI integration tests

Pattern Organization

Naming Convention

{CATEGORY}_{VERSION?} = [
    r"pattern1",
    r"pattern2",
]

Version Tagging in Matches

패턴 매칭 시 버전 태그 추가:

• new:{category}:{pattern} - v2.4.0 red team
• v25:{category}:{pattern} - v2.5.0 indirect
• v252:{category}:{pattern} - v2.5.2 moltbook
• {lang}:{category}:{pattern} - language-specific

Configuration Schema

prompt_guard:
  # Detection sensitivity
  sensitivity: medium  # low | medium | high | paranoid
  
  # Owner IDs (bypass most restrictions)
  owner_ids:
    - "USER_ID"
  
  # Action per severity
  actions:
    LOW: log
    MEDIUM: warn
    HIGH: block
    CRITICAL: block_notify
  
  # Rate limiting
  rate_limit:
    enabled: true
    max_requests: 30
    window_seconds: 60
  
  # Logging
  logging:
    enabled: true
    path: memory/security-log.md

Key Design Decisions

1. Regex over ML

• Pros: Deterministic, explainable, no model dependencies
• Cons: Manual pattern updates needed
• Reasoning: Security requires predictability; ML false negatives unacceptable

2. Multi-Language First

• All patterns have EN/KO/JA/ZH variants
• Attack language != user language (multilingual attacks common)

3. Severity Graduation

• Not binary block/allow
• Owner context matters (more lenient for owners)
• Group context matters (stricter in groups)

4. Versioned Patterns

• Clear provenance for each pattern set
• Credits to contributors (홍민표, Moltbook, etc.)
• Easy to audit and roll back

Extension Points

Adding New Patterns

# 1. Define pattern list
NEW_ATTACK_CATEGORY = [
    r"pattern1",
    r"pattern2",
]

# 2. Add to analysis loop
new_pattern_sets = [
    ...
    (NEW_ATTACK_CATEGORY, "new_category", Severity.HIGH),
]

Adding New Languages

PATTERNS_XX = {
    "instruction_override": [...],
    "role_manipulation": [...],
    ...
}

# Add to all_patterns
all_patterns.append((PATTERNS_XX, "xx"))

Performance Notes

• Regex compilation: Patterns are compiled on first use (Python caches)
• Early exit: CRITICAL patterns checked first
• Fingerprinting: Hash-based dedup for repeated attacks
• Rate limiting: O(1) sliding window

Security Considerations

What We DON'T Do

• ❌ Execute user input
• ❌ Log sensitive data in plaintext
• ❌ Trust any "admin" claims without owner_id verification

What We DO

• ✅ Fail closed (block on uncertainty)
• ✅ Log all suspicious activity
• ✅ Stricter rules in group contexts

Changelog Location

버전별 변경사항은 detect.py 상단 docstring에 기록:

"""
Prompt Guard v2.6.0 - Advanced Prompt Injection Detection

Changelog v2.6.0 (2026-02-01):
- Added Single Approval Expansion detection
- Added Credential Path Harvesting detection
...
"""

Credits

• Core: @simonkim_nft (김서준)
• v2.4.0 Red Team: 홍민표 (@kanfrancisco)
• v2.4.1 Config Fix: Junho Yeo (@junhoyeo)
• v2.5.2 Moltbook Patterns: Community reports

Last updated: 2026-02-07 | v2.8.0