Pattern Server¶

AI Guardian can optionally fetch security patterns from a centralized pattern server, enabling enterprise-wide security policy management.

What is Pattern Server?¶

Pattern Server is an optional feature that allows organizations to: - 📡 Centralize security patterns - One source of truth for all detection rules - 🔄 Auto-update patterns - New threats distributed automatically to all users - 🏢 Enforce corporate policies - Organization-specific security rules - 🎯 Custom threat intelligence - Industry-specific attack patterns

Instead of each user maintaining their own pattern lists, everyone gets the same up-to-date patterns from a central server.

What It Manages¶

Pattern Server can provide patterns for all detection features:

Detection Feature	Pattern Type	Example Patterns
Secret Scanning	Secret regex patterns	API key formats, token patterns
SSRF Protection	Blocked IPs/domains	Internal networks, metadata endpoints
Unicode Attacks	Homoglyph mappings	Cyrillic/Greek lookalikes
Config Scanner	Exfiltration patterns	Credential theft commands
Secret Redaction	Masking rules	Which secrets to redact, how to mask

How It Works¶

Without Pattern Server (Default)¶

Each AI Guardian installation uses hardcoded patterns:

User A: Hardcoded patterns v1.5.0
User B: Hardcoded patterns v1.5.0
User C: Hardcoded patterns v1.5.0
  ↓
New threat discovered!
  ↓
Users must wait for next AI Guardian release

With Pattern Server (Enterprise)¶

All installations fetch from central server:

Pattern Server: Latest patterns (updated daily)
         ↓           ↓           ↓
    User A      User B      User C
         ↓           ↓           ↓
All users get new patterns automatically

Benefits¶

For Security Teams¶

✅ Instant threat response - New attack pattern discovered → Update server → All users protected - No waiting for software releases

✅ Centralized control - Single place to manage all security rules - Consistent policies across organization

✅ Custom threat intelligence - Add industry-specific patterns - Block organization-specific threats - Internal security research integration

For Users¶

✅ Always up-to-date - Automatic pattern updates - No manual configuration needed - Latest threat protection

✅ Consistent protection - Everyone uses same rules - No configuration drift - Compliance with corporate policies

Configuration¶

Enable pattern server in your config:

{
  "secret_redaction": {
    "pattern_server": {
      "enabled": true,
      "url": "https://patterns.corp.internal/api/v1/secrets",
      "cache_ttl": 3600,
      "fallback_to_defaults": true
    }
  }
}

Configuration Options¶

Option	Description	Default
`enabled`	Enable pattern server	`false`
`url`	Pattern server API endpoint	-
`cache_ttl`	Cache duration in seconds	`3600` (1 hour)
`fallback_to_defaults`	Use hardcoded patterns if server unavailable	`true`

Per-Feature Configuration¶

Each detection feature can have its own pattern server:

{
  "secret_redaction": {
    "pattern_server": {
      "url": "https://patterns.corp.internal/api/v1/secrets"
    }
  },
  "ssrf_protection": {
    "pattern_server": {
      "url": "https://patterns.corp.internal/api/v1/ssrf"
    }
  },
  "config_file_scanning": {
    "pattern_server": {
      "url": "https://patterns.corp.internal/api/v1/exfil"
    }
  }
}

Caching & Performance¶

How Caching Works¶

1. AI Guardian starts
   ↓
2. Check local cache (valid for cache_ttl)
   ↓
3. If expired, fetch from server
   ↓
4. Store in cache
   ↓
5. Use patterns for detection

Cache Behavior¶

Scenario	What Happens
First run	Fetches from server, caches locally
Cache valid	Uses cached patterns (fast)
Cache expired	Re-fetches from server, updates cache
Server unreachable	Uses cached patterns OR hardcoded defaults
No cache + server down	Falls back to hardcoded patterns

Performance: Pattern fetching happens at startup (~100-500ms), not during detection.

Fail-Safe Design¶

AI Guardian is designed to fail safely if pattern server is unavailable:

Pattern Server Down?
  ↓
Check Local Cache
  ↓ (expired or missing)
Fallback to Defaults (if enabled)
  ↓
Continue with hardcoded patterns
  ↓
✅ Protection still active (not blocked)

You are always protected - even if the pattern server goes offline.

Use Cases¶

Enterprise Deployment¶

Scenario: 500 developers across multiple teams

Without Pattern Server: - ❌ Each developer configures AI Guardian individually - ❌ Configuration drift (different patterns per team) - ❌ Slow threat response (wait for releases) - ❌ Manual updates required

With Pattern Server: - ✅ Security team controls patterns centrally - ✅ All developers get same protection - ✅ New threats blocked instantly (update server) - ✅ Zero manual updates needed

Industry-Specific Patterns¶

Example: Healthcare

{
  "secret_redaction": {
    "pattern_server": {
      "url": "https://hipaa-patterns.corp.internal/api/v1/secrets"
    }
  }
}

Pattern server provides: - PHI (Protected Health Information) patterns - Medical record number formats - Healthcare-specific API keys - HIPAA compliance rules

Compliance Requirements¶

Example: Financial Services - PCI DSS compliance patterns - Credit card number detection - Bank account formats - Financial API credentials

Example: Government - Classified information markers - Agency-specific secret formats - Clearance level indicators - Government cloud endpoints

Pattern Server API¶

Pattern server provides patterns via simple HTTP API:

Example Response (Secrets)¶

{
  "version": "2024.04.27",
  "patterns": [
    {
      "regex": "sk-proj-[A-Za-z0-9]{20,}",
      "strategy": "preserve_prefix_suffix",
      "secret_type": "OpenAI Project Key"
    },
    {
      "regex": "corp_api_key_[A-Za-z0-9]{32}",
      "strategy": "full_redact",
      "secret_type": "Corporate API Key"
    }
  ]
}

Example Response (SSRF)¶

{
  "version": "2024.04.27",
  "blocked_ip_ranges": [
    {"cidr": "10.0.0.0/8"},
    {"cidr": "192.168.0.0/16"}
  ],
  "blocked_domains": [
    {"domain": "metadata.google.internal"},
    {"domain": "*.corp.internal"}
  ]
}

Authentication¶

Default: Single Token for All Pattern Servers¶

By default, all pattern server sections use the same environment variable for authentication:

export AI_GUARDIAN_PATTERN_TOKEN="your-token"

This works when all pattern servers share the same credentials (the common case).

Each pattern server reads its auth config independently. If token_env is not specified in a section's auth block, it falls back to AI_GUARDIAN_PATTERN_TOKEN.

Per-Section Auth for Multiple Servers¶

When different detection features use different pattern servers with different credentials, override token_env in each section:

{
  "secret_scanning": {
    "pattern_server": {
      "url": "https://secrets-patterns.internal.com",
      "patterns_endpoint": "/patterns/gitleaks/8.27.0",
      "auth": {
        "method": "bearer",
        "token_env": "AI_GUARDIAN_SECRET_PATTERNS_TOKEN"
      }
    }
  },
  "ssrf_protection": {
    "pattern_server": {
      "url": "https://ssrf-patterns.internal.com",
      "patterns_endpoint": "/patterns/ssrf/v1",
      "auth": {
        "method": "bearer",
        "token_env": "AI_GUARDIAN_SSRF_PATTERNS_TOKEN"
      }
    }
  },
  "config_file_scanning": {
    "pattern_server": {
      "url": "https://exfil-patterns.internal.com",
      "patterns_endpoint": "/patterns/exfil/v1",
      "auth": {
        "method": "bearer",
        "token_env": "AI_GUARDIAN_EXFIL_PATTERNS_TOKEN"
      }
    }
  },
  "secret_redaction": {
    "pattern_server": {
      "url": "https://redaction-patterns.internal.com",
      "auth": {
        "method": "bearer",
        "token_env": "AI_GUARDIAN_REDACTION_PATTERNS_TOKEN"
      }
    }
  }
}

Then set each environment variable:

export AI_GUARDIAN_SECRET_PATTERNS_TOKEN="token-for-secrets-server"
export AI_GUARDIAN_SSRF_PATTERNS_TOKEN="token-for-ssrf-server"
export AI_GUARDIAN_EXFIL_PATTERNS_TOKEN="token-for-exfil-server"
export AI_GUARDIAN_REDACTION_PATTERNS_TOKEN="token-for-redaction-server"

Auth Options¶

Each pattern server auth block supports:

Option	Description	Default
`method`	Auth method	`"bearer"`
`token_env`	Env var containing the token	`"AI_GUARDIAN_PATTERN_TOKEN"`
`token_file`	File path containing the token	`"~/.config/ai-guardian/pattern-token"`

Token resolution order: 1. Environment variable (token_env) — checked first 2. Token file (token_file) — used if env var is not set

Using token_file instead of env vars:

{
  "secret_scanning": {
    "pattern_server": {
      "url": "https://secrets-patterns.internal.com",
      "auth": {
        "method": "bearer",
        "token_file": "~/.config/ai-guardian/secret-patterns-token"
      }
    }
  }
}

Token files are read at runtime. Permissions are restricted to 0600 when written by AI Guardian.

Which Sections Support Pattern Server?¶

Config Section	Pattern Type	Default Token Env
`secret_scanning.pattern_server`	Secret detection rules	`AI_GUARDIAN_PATTERN_TOKEN`
`secret_redaction.pattern_server`	Secret redaction/masking rules	`AI_GUARDIAN_PATTERN_TOKEN`
`ssrf_protection.pattern_server`	Blocked IPs/domains	`AI_GUARDIAN_PATTERN_TOKEN`
`config_file_scanning.pattern_server`	Exfiltration patterns	`AI_GUARDIAN_PATTERN_TOKEN`

All default to AI_GUARDIAN_PATTERN_TOKEN unless overridden with token_env.

Security Considerations¶

Server Authentication¶

Recommended: Use authentication for pattern server:

{
  "pattern_server": {
    "url": "https://patterns.corp.internal/api/v1/secrets",
    "auth": {
      "method": "bearer",
      "token_env": "PATTERN_SERVER_TOKEN"
    }
  }
}

AI Guardian sends:

GET /api/v1/secrets
Authorization: Bearer <token from PATTERN_SERVER_TOKEN env var>

Pattern Validation¶

All patterns from the server are validated before use: - ✅ Regex syntax validation (prevents ReDoS) - ✅ Pattern complexity analysis - ✅ Malformed pattern rejection - ✅ Safe fallback if validation fails

Protection: Malicious or broken patterns won't crash AI Guardian.

Supply Chain Security¶

Risk: Compromised pattern server could weaken detection

Mitigations: 1. TLS/HTTPS required - Encrypted transport 2. Pattern validation - Regex safety checks 3. Fallback to defaults - If server seems compromised 4. Audit logging - Track pattern changes 5. Version pinning - Optionally lock to specific version

Summary¶

Pattern Server provides:

🎯 Centralized management - One source of truth for all security patterns
🎯 Automatic updates - New threats blocked instantly across organization
🎯 Custom patterns - Industry-specific and corporate security rules
🎯 Fail-safe design - Protection continues even if server is down
🎯 Enterprise compliance - Meet regulatory requirements easily

Optional feature for organizations that need centralized security policy management.

Version History¶

v1.5.0 - Initial pattern server support (secrets, SSRF, Unicode, config scanner, redaction)
v1.5.1 - Added authentication and cache improvements
v1.6.0 - Enhanced validation and audit logging