ADR-002: Security Pattern Library Format

Status: Proposed Date: 2026-02-18 Deciders: CODITECT Architecture Team Source Research: ClawGuard AI Agent Security Ecosystem Evaluation (2026-02-18)

---

Context

The CODITECT agent security layer (ADR-001) requires a structured pattern library to define:

• What to detect: prompt injection attempts, secret patterns, PII, destructive shell commands, sensitive path access, suspicious URLs.
• How severe each pattern is: critical, high, medium, low.
• What action to take: block, redact, confirm, warn, log.
• Where the pattern applies: pre-agent-start, pre-tool-call, post-tool-result.

The three ClawGuard repositories studied each use a different representation:

Repository	Format	Strengths	Weaknesses
ClawGuard (maxxie114)	Python regex constants in sanitizer.py	Tightly coupled to runtime	Not portable, no metadata
ClawGuardian (superglue-ai)	TypeScript const arrays in patterns/*.ts with TypeBox schemas	Type-safe, testable, structured severity+action pairs	Requires TS toolchain, not human-editable without IDE
clawguard (JaydenBeard)	JavaScript arrays in lib/risk-analyzer.js grouped by severity constant name (e.g., CRITICAL_SHELL_PATTERNS)	Simple, readable	No types, severity is implicit in array name, no action mapping

All three approaches embed patterns in executable code. This creates several problems for CODITECT:

1. Auditability: Security patterns are security policy. They should be reviewable by non-engineers (security officers, compliance reviewers) without requiring them to read source code.
2. Versionability: Pattern changes should be diff-readable in pull requests — a regex change should be immediately visible without parsing code structure.
3. Extensibility: Tenant-specific pattern overrides (e.g., an enterprise customer with custom secret formats) must be addable without modifying core code.
4. Portability: The same pattern library must be readable by the Python security layer runtime, by documentation generators, and by future tooling.

The question is: what file format best satisfies these requirements while remaining practical to maintain?

---

Decision

Use YAML-based pattern definitions as the single source of truth for the CODITECT security pattern library.

Each pattern file is a YAML document with the following structure:

# config/security-patterns/prompt-injection.yaml
category: prompt_injection
description: >
  Patterns that detect attempts to override, escape, or manipulate the agent's
  system prompt or instruction context via user-controlled input.
version: "1.0.0"
updated: "2026-02-18"

patterns:
  - id: pi-001
    name: ignore_instructions
    description: Direct instruction to disregard previous or system-level directives.
    regex: "(?i)(ignore|disregard|forget|override)\\s+(all\\s+)?(previous|prior|above|system)\\s+(instructions?|prompts?|rules?|constraints?)"
    severity: critical
    action: block
    applies_to: [pre-agent-start, pre-tool-call]
    tags: [prompt-injection, jailbreak]
    source: maxxie114/clawguard

  - id: pi-002
    name: new_instructions
    description: Injection of new instruction sets mid-conversation using delimiter-like phrasing.
    regex: "(?i)(new\\s+instructions?|updated\\s+directives?|system\\s+override|begin\\s+new\\s+task)"
    severity: high
    action: block
    applies_to: [pre-tool-call]
    tags: [prompt-injection, delimiter-injection]
    source: maxxie114/clawguard

  - id: pi-003
    name: system_prompt_override
    description: Attempt to inject a replacement system prompt directly.
    regex: "(?i)(system\\s+prompt|\\[system\\]|<system>|<<SYS>>)"
    severity: critical
    action: block
    applies_to: [pre-agent-start, pre-tool-call]
    tags: [prompt-injection, system-prompt]
    source: maxxie114/clawguard

File Organization

config/security-patterns/
├── prompt-injection.yaml        # 10+ patterns (maxxie114 + extensions)
├── secret-detection.yaml        # 6+ patterns (API keys, AWS, GitHub, JWT, private keys)
├── pii-filtering.yaml           # Phone, email, SSN, credit card patterns
├── destructive-commands.yaml    # Shell commands: rm -rf, dd, mkfs, DROP TABLE, etc.
├── sensitive-paths.yaml         # .ssh, .aws, .kube, .env, password managers
├── sensitive-urls.yaml          # Banking, auth pages, cloud consoles, PayPal
└── tenant-overrides/
    └── {tenant-id}/
        └── custom-patterns.yaml # Tenant-specific additions or suppression rules

Schema Constraints

Field	Type	Required	Values
id	string	yes	{category-prefix}-{3-digit-sequence}
name	string	yes	snake_case identifier
description	string	yes	Human-readable, one sentence
regex	string	yes	Python-compatible regex (re module)
severity	enum	yes	critical, high, medium, low
action	enum	yes	block, redact, confirm, warn, log
applies_to	list	yes	pre-agent-start, pre-tool-call, post-tool-result
tags	list	no	Arbitrary classification tags
source	string	no	Attribution to upstream pattern source
enabled	bool	no	Default true; set false to disable without deletion

---

Consequences

Positive

• Human-readable: Security officers and compliance reviewers can audit pattern definitions in YAML without engineering support.
• Diff-friendly: Adding, modifying, or removing a pattern produces a clean, reviewable diff. Pattern changes are directly visible in pull requests.
• Language-agnostic: The same YAML files can be consumed by the Python security layer, TypeScript tooling, documentation generators, or a future pattern management UI.
• Tenant extensibility: The tenant-overrides/ directory enables per-tenant custom patterns without modifying core files, maintaining separation between platform policy and customer-specific policy.
• Source attribution: The source field maintains provenance for patterns ported from ClawGuardian, maxxie114, and JaydenBeard, enabling future upstream reconciliation.
• Regex validation at load time: Python's re.compile() can validate all patterns at startup, failing fast on malformed regex before any security decision is made.

Negative

• No compile-time type checking: Unlike ClawGuardian's TypeBox schemas, YAML errors are caught at runtime (load time) rather than at build time. Mitigation: a CI linter (scripts/security/validate-patterns.py) validates schema compliance on every commit.
• Regex portability: YAML stores regexes as strings. Python (re module) and JavaScript (RegExp) have minor differences. Since the runtime is Python (ADR-001), all patterns are authored as Python-compatible regex. JavaScript consumers must be aware of minor syntax differences (e.g., (?i) flags).
• No hot reload: Pattern changes require a hook/process restart to take effect. This is acceptable for a security layer — hot-patching security policy without a restart would itself be a security concern.

Neutral

• The 10 prompt injection patterns from maxxie114, the 6 secret detection patterns, the full 55+ shell command patterns from JaydenBeard, and ClawGuardian's PII/cloud credential patterns can all be ported to YAML format without loss of fidelity. The porting task is mechanical and can be done in a single sprint.

---

Alternatives Considered

Alternative A: TypeScript const Arrays (ClawGuardian Model)

Approach: Port ClawGuardian's patterns/*.ts files directly. Define patterns as typed TypeScript constants.

Rejected because:

• CODITECT's security layer is implemented in Python (ADR-001). A TypeScript pattern definition requires either a cross-language serialization step or a Node.js runtime as a dependency.
• TypeScript pattern files are not readable by non-engineers without IDE tooling.
• Tenant overrides would require TypeScript compilation, not just file placement.

Alternative B: JSON

Approach: Use JSON instead of YAML for pattern definitions.

Rejected because:

• JSON does not support comments. Security patterns benefit from inline documentation explaining detection rationale, false-positive risks, and evasion considerations.
• JSON multi-line strings require escape sequences (\n, \\), making regex patterns harder to read and maintain.
• YAML is a superset of JSON — any JSON pattern file is valid YAML, so migration is trivially achievable if tooling requirements change.

Alternative C: Database-Stored Patterns (SQLite/org.db)

Approach: Store patterns in the CODITECT org.db database. Provide a management UI or CLI for pattern CRUD operations.

Rejected because:

• Removes patterns from version control. Security policy changes become invisible to code review processes.
• Database-stored patterns cannot be diffed, reviewed in pull requests, or rolled back with git revert.
• Increases operational dependency — the security layer cannot initialize if the database is unavailable.
• Appropriate as a secondary index (patterns loaded from YAML, indexed into a read-only database for fast lookup) but not as the primary SSOT.

Alternative D: Python Module Constants (maxxie114 Model)

Approach: Define patterns as Python dict or list constants in scripts/core/security/patterns.py.

Rejected because:

• Pattern changes require code deployments, not configuration updates.
• Non-engineers cannot review or audit patterns without reading Python source.
• Tenant overrides would require subclassing or monkey-patching, both of which are fragile patterns for security-critical code.

---

Implementation Notes

• Loader: scripts/core/security/pattern_loader.py — loads all YAML files from config/security-patterns/, compiles regexes, merges tenant overrides.
• Validator: scripts/security/validate-patterns.py — CI linter that checks schema compliance, regex compilability, and ID uniqueness.
• Initial pattern count target: 80+ patterns across 6 categories (porting from all three ClawGuard repositories).
• Tenant override precedence: Tenant patterns can add new patterns or set enabled: false on platform patterns by ID. They cannot modify platform pattern definitions (immutable by reference).

---

References

• ClawGuardian patterns: submodules/core/coditect-core/analyze-new-artifacts/clawguard-ai-agent-security/ — patterns/api-keys.ts, patterns/cloud-credentials.ts, patterns/tokens.ts, patterns/pii.ts
• maxxie114 patterns: sanitizer.py — 10 prompt injection patterns, 6 secret patterns
• JaydenBeard patterns: lib/risk-analyzer.js — 55+ shell command patterns across 5 severity categories
• Research context: analyze-new-artifacts/clawguard-ai-agent-security/artifacts/research-context.json
• Related ADRs: ADR-001 (Security Layer Architecture), ADR-003 (Fail Behavior), ADR-004 (Risk Scoring)