Skip to content
Cline

Custom Patterns

Cloak uses regex patterns to identify and redact sensitive information. You can customize these patterns to match your application’s specific needs.

Default Patterns

Section titled “Default Patterns”

Cloak ships with patterns for common sensitive data:

Database Connections

Section titled “Database Connections”
'patterns' => [
    // MySQL connections
    '/mysql:\/\/([^:]+):([^@]+)@([^\/]+)\/(.+)/i',


    // PostgreSQL connections
    '/postgres:\/\/([^:]+):([^@]+)@([^\/]+)\/(.+)/i',


    // MongoDB connections
    '/mongodb:\/\/([^:]+):([^@]+)@([^\/]+)\/(.+)/i',


    // Redis connections
    '/redis:\/\/([^:]+):([^@]+)@([^\/]+)/i',
],

DSN Format

Section titled “DSN Format”
'patterns' => [
    '/host=([^\s;]+)/i',
    '/user=([^\s;]+)/i',
    '/password=([^\s;]+)/i',
    '/dbname=([^\s;]+)/i',
],

API Keys and Tokens

Section titled “API Keys and Tokens”
'patterns' => [
    // Generic API keys
    '/api[_-]?key["\']?\s*[:=]\s*["\']?([a-zA-Z0-9_\-]+)/i',


    // Tokens
    '/token["\']?\s*[:=]\s*["\']?([a-zA-Z0-9_\-\.]+)/i',


    // Bearer tokens
    '/bearer\s+([a-zA-Z0-9_\-\.]+)/i',
],

Cloud Provider Credentials

Section titled “Cloud Provider Credentials”
'patterns' => [
    // AWS Access Keys
    '/aws[_-]?access[_-]?key[_-]?id["\']?\s*[:=]\s*["\']?([A-Z0-9]+)/i',


    // AWS Secret Keys
    '/aws[_-]?secret[_-]?access[_-]?key["\']?\s*[:=]\s*["\']?([A-Za-z0-9\/\+]+)/i',
],

Adding Custom Patterns

Section titled “Adding Custom Patterns”

Add your own patterns in config/cloak.php:

'patterns' => [
    // Add to existing patterns
    ...config('cloak.patterns'),


    // Custom patterns
    '/your-custom-pattern-here/i',
    '/secret[_-]?token["\']?\s*[:=]\s*["\']?([a-zA-Z0-9]+)/i',
],

Pattern Best Practices

Section titled “Pattern Best Practices”

1. Use Case-Insensitive Matching

Section titled “1. Use Case-Insensitive Matching”

Always use the i flag for case-insensitive matching:

'/api[_-]?key/i'  // ✅ Matches "api_key", "API_KEY", "Api-Key"
'/api[_-]?key/'   // ❌ Only matches "api_key" or "api-key"

2. Capture Sensitive Values

Section titled “2. Capture Sensitive Values”

Use capture groups () to identify what to redact:

'/password=([^\s;]+)/i'  // ✅ Captures the password value
'/password=/i'           // ❌ Doesn't capture what to redact

3. Match Context, Not Just Values

Section titled “3. Match Context, Not Just Values”

Include context to avoid false positives:

'/api[_-]?key["\']?\s*[:=]\s*["\']?([a-zA-Z0-9_\-]+)/i'  // ✅ Requires "api_key=" prefix
'/[a-zA-Z0-9_\-]+/i'                                     // ❌ Matches everything

4. Test Your Patterns

Section titled “4. Test Your Patterns”

Test patterns against real exception messages:

use Cline\Cloak\Sanitizers\PatternBasedSanitizer;


$sanitizer = new PatternBasedSanitizer(
    patterns: ['/your-pattern/i'],
    replacement: '[REDACTED]',
);


$message = 'Error with secret_token=abc123';
$sanitized = $sanitizer->sanitizeMessage($message);


dump($sanitized); // "Error with [REDACTED]"

Environment-Specific Patterns

Section titled “Environment-Specific Patterns”

Use different patterns per environment:

'patterns' => env('APP_ENV') === 'production' ? [
    // Aggressive sanitization in production
    '/mysql:\/\//i',
    '/password/i',
    '/secret/i',
    '/token/i',
] : [
    // Minimal sanitization in development
    '/password=([^\s;]+)/i',
],

Common Pattern Examples

Section titled “Common Pattern Examples”

Credit Card Numbers

Section titled “Credit Card Numbers”
'/\b(?:\d{4}[-\s]?){3}\d{4}\b/'

Social Security Numbers

Section titled “Social Security Numbers”
'/\b\d{3}-\d{2}-\d{4}\b/'

Email Addresses

Section titled “Email Addresses”
'/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/'

IPv4 Addresses

Section titled “IPv4 Addresses”
'/\b(?:\d{1,3}\.){3}\d{1,3}\b/'

File Paths

Section titled “File Paths”
// Unix/Linux paths
'/\/home\/([^\/\s]+)/i',
'/\/Users\/([^\/\s]+)/i',


// Windows paths
'/C:\\\\Users\\\\([^\\\\]+)/i',

JWT Tokens

Section titled “JWT Tokens”
'/eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+/'

Custom Replacement Text

Section titled “Custom Replacement Text”

Change the redaction text globally:

'replacement' => '[SENSITIVE_DATA_REMOVED]',

Or use different text for different patterns by creating multiple sanitizers:

use Cline\Cloak\Sanitizers\PatternBasedSanitizer;


$dbSanitizer = new PatternBasedSanitizer(
    patterns: ['/mysql:\/\//i'],
    replacement: '[DATABASE_CREDENTIALS]',
);


$apiSanitizer = new PatternBasedSanitizer(
    patterns: ['/api[_-]?key/i'],
    replacement: '[API_KEY]',
);

Performance Considerations

Section titled “Performance Considerations”

Pattern Complexity

Section titled “Pattern Complexity”

Keep patterns efficient:

// ✅ Efficient - specific and bounded
'/api_key=([a-zA-Z0-9]{20,40})/i'


// ❌ Inefficient - too greedy
'/api_key=(.+)/i'

Pattern Count

Section titled “Pattern Count”

Too many patterns can impact performance. Consider:

// ✅ Single comprehensive pattern
'/(?:password|secret|token|key)=([^\s;]+)/i'


// ❌ Multiple similar patterns
'/password=([^\s;]+)/i',
'/secret=([^\s;]+)/i',
'/token=([^\s;]+)/i',
'/key=([^\s;]+)/i',

Debugging Patterns

Section titled “Debugging Patterns”

Enable pattern debugging:

use Cline\Cloak\Sanitizers\PatternBasedSanitizer;


$sanitizer = new PatternBasedSanitizer(
    patterns: config('cloak.patterns'),
    replacement: '[REDACTED]',
);


$message = 'Error with mysql://root:pass@localhost/db and api_key=secret123';


// Test each pattern
foreach (config('cloak.patterns') as $pattern) {
    if (preg_match($pattern, $message)) {
        dump("Pattern matched: {$pattern}");
    }
}


// See final result
dump($sanitizer->sanitizeMessage($message));

Next Steps

Section titled “Next Steps”