---
name: build-agent-safety-guard
description: >-
  Architecture and process for building a prompt injection guard for AI agents.
  Covers scoring-based risk, source trust levels, combo detection, testing
  strategy, and multi-agent code review workflow. Based on prompt_guard.py v2.1.
---

# Building an Agent Safety Guard

## When to Use

When designing runtime safety for an AI agent that:
- Reads external files and websites
- Executes shell commands
- Processes user messages from messaging platforms
- Needs automatic protection against prompt injection

## Architecture Decisions

### 1. Scoring-Based Risk

Use a float 0.0-1.0 with thresholds:
- less than 0.30: safe, pass to LLM
- 0.30-0.85: warn, ask user
- 0.85 or more: block automatically

Scoring allows multi-stage checks to stack risk instead of early-exit.

### 2. Source Trust Levels

Three tiers with different strictness:

| Source | Behavior |
|--------|----------|
| TRUSTED | Project files, only unicode + high-risk keywords |
| UNTRUSTED | Web/files/messages, full scan |
| USER_CMD | Commands from user, warn never block |

Even TRUSTED should check high-risk keywords and unicode tricks.

### 3. Combo (Multi-Signal) Detection

When multiple risk signals combine, escalate:

- Injection phrase + exfiltration pattern = auto-block
- Trigger word + exfiltration = auto-block
- High-risk keyword + base64 shell = auto-block

Catches attacks weak individually but dangerous together.

## Detection Techniques

### Prompt Injection Patterns

Three matching levels:
1. Exact phrases (low false positive)
2. High-risk keywords (regex compiled)
3. Trigger words (word-boundary, catches variants)

Include non-English phrases. Add social engineering patterns.

### Shell Command Detection

Patterns to cover:
- Obfuscation: base64 decode pipe, hex decode pipe, hex printf, perl exec
- Pipe to shell: download-and-execute variants
- Reverse shell: TCP device, netcat exec, bash interactive redirect
- Exfiltration: env dump to network, credential reads

### URL Safety

- Mixed-script domain detection (homoglyph attacks)
- IP-based URLs (potential phishing)
- Data URIs

### File Sensitivity

Wildcard system supporting prefix, suffix, and substring matching.

## Multi-Agent Code Review Workflow

This project used:
1. Agent A builds initial version
2. Agent B reviews and sends alternative implementation
3. Agent A merges best of both
4. Agent B does deep code review (10+ points)
5. Agent A fixes systematically with test-driven approach
6. All tests pass, no regressions

### Key Review Categories

- Wildcard matching edge cases and coverage gaps
- Blind trust sources (even TRUSTED needs keyword check)
- Missing detection categories (homoglyph, hex obfuscation)
- False positive vectors (JWT tokens, punycode URLs)
- Scoring threshold calibration

## Testing Strategy

### Test Categories

| Category | Count | Purpose |
|----------|-------|---------|
| Safe content | 3 | No false positives on clean text |
| Injection detection | 8 | Various languages and techniques |
| Trusted source | 3 | Proper behavior for project files |
| Exfiltration combos | 2 | Multi-signal auto-block |
| URL safety | 3 | Normal, homoglyph, data URI |
| Sensitive files | 12 | All wildcard variants + negatives |
| Command safety | 12 | All danger patterns + user cmd |
| Source classification | 5 | Auto-detect logic |
| JWT edge case | 1 | No false positive |

### Key Test Considerations

- Test base64-decoded JWT tokens with word-boundary shell indicators
- Test punycode vs actual homoglyph characters in URLs
- Test non-English injection phrases
- Test user commands warn but never block
- Test trusted source detects keywords but does not block

## Pitfalls

### 1. Shell Detector Word Boundaries

Use `\\b` word boundaries in regex to avoid matching shell indicators inside JWT payloads and other base64-encoded text.

### 2. Flexible vs Consecutive Keyword Matching

Exact phrases miss variants like "ignore all previous" because keywords like "ignore previous" require consecutive words. Add individual trigger words for flexible matching.

### 3. Unicode Character Handling in Shell

Shell does not interpret `\\uXXXX` escapes. Test unicode patterns via Python API, not CLI.

### 4. Combo Detection Order

Run combo checks last, after all individual checks. Use max() to raise risk, with a guard to prevent overwriting existing block status from a higher-risk individual signal.

### 5. JSON Encoding for Unicode Patterns

Use `\\uXXXX` escape sequences in JSON config files for non-printable Unicode. This ensures cross-platform compatibility regardless of editor encoding.

### 6. Security Scanner Blocks Educational Examples

Document injection patterns abstractly. Including actual injection phrases in skill documentation triggers automated scanners.

## Verification

Quick smoke test:
```
python3 prompt_guard.py check-content "test"
python3 prompt_guard.py is-sensitive ".env"
```

Full test suite:
```
python3 test_prompt_guard.py
```
