Configuration

⚙️ Configuration Guide

The Laravel Safeguard configuration file (config/safeguard.php) allows you to customize which security rules are enabled, how they behave, and tailor the security checks to your specific application needs.

📋 Basic Configuration

After publishing the config file with php artisan vendor:publish --tag=safeguard-config, you'll find these main sections:

🔧 Rules Configuration

Enable or disable specific security rules:

<?php

return [
    'rules' => [
        // 🔐 Environment & Configuration Rules
        'app-debug-false-in-production' => true,
        'app-key-is-set' => true,
        'env-has-all-required-keys' => true,
        'no-secrets-in-code' => true,

        // 🛡️ Security Rules
        'csrf-enabled' => true,
        'secure-cookies-in-production' => true,
        'storage-writable' => true,
        'https-enforced-in-production' => false,

        // 📁 File System Rules
        'env-file-permissions' => true,
        'sensitive-files-hidden' => true,
        
        // 🗄️ Database Security
        'database-connection-encrypted' => true,
        'database-credentials-not-default' => true,
        
        // 🔑 Authentication Security
        'password-policy-compliance' => true,
        'two-factor-auth-enabled' => false,
        'session-security-settings' => true,
    ],
];

🌍 Environment-Specific Rules

Configure different rules for different environments:

'environments' => [
    'production' => [
        'app-debug-false-in-production',
        'app-key-is-set',
        'secure-cookies-in-production',
        'https-enforced-in-production',
        'env-file-permissions',
        'sensitive-files-hidden',
        'database-connection-encrypted',
        'password-policy-compliance',
    ],
    'staging' => [
        'app-debug-false-in-production',
        'app-key-is-set',
        'csrf-enabled',
        'database-connection-encrypted',
    ],
    'local' => [
        'app-key-is-set',
        'storage-writable',
        'csrf-enabled',
    ],
],

📂 Scan Paths

Specify which directories to scan for security issues:

'scan_paths' => [
    'app/',
    'config/',
    'routes/',
    'resources/views/',
    'database/seeders/',
    'database/migrations/',
],

🔍 Secret Patterns

Define patterns to detect hardcoded secrets:

'secret_patterns' => [
    '*_KEY',
    '*_SECRET',
    '*_TOKEN',
    '*_PASSWORD',
    'API_*',
    'AWS_*',
    'STRIPE_*',
    'PAYPAL_*',
    'TWILIO_*',
    'MAILGUN_*',
    'GITHUB_*',
    'SLACK_*',
],

🚀 Advanced Configuration

🏗️ Custom Rules Path

Specify where your custom security rules are located:

'custom_rules_path' => app_path('SafeguardRules'),
'custom_rules_namespace' => 'App\\SafeguardRules',

📋 Required Environment Variables

Define which environment variables must be present:

'required_env_vars' => [
    'APP_KEY',
    'APP_ENV',
    'APP_DEBUG',
    'APP_URL',
    'DB_CONNECTION',
    'DB_HOST',
    'DB_PORT',
    'DB_DATABASE',
    'DB_USERNAME',
    'DB_PASSWORD',
    'MAIL_MAILER',
    'MAIL_HOST',
],

🔒 Sensitive Files

List files that should not be web-accessible:

'sensitive_files' => [
    '.env',
    '.env.example',
    '.env.local',
    '.env.production',
    'composer.json',
    'composer.lock',
    'package.json',
    'package-lock.json',
    'artisan',
    'phpunit.xml',
    'README.md',
    'webpack.mix.js',
    'vite.config.js',
],

⚡ Performance Settings

Configure performance and timeout settings:

'performance' => [
    'max_scan_files' => 10000,
    'timeout_seconds' => 300,
    'memory_limit' => '512M',
    'parallel_processing' => true,
],

📊 Configuration Examples

🎯 Production-Only Setup

For a strict production-only security check:

<?php

return [
    'rules' => [
        'app-debug-false-in-production' => true,
        'secure-cookies-in-production' => true,
        'https-enforced-in-production' => true,
        'env-file-permissions' => true,
        'database-connection-encrypted' => true,
        'password-policy-compliance' => true,
        
        // Disable development-focused rules
        'storage-writable' => false,
        'no-secrets-in-code' => false,
    ],

    'environments' => [
        'production' => [
            'app-debug-false-in-production',
            'secure-cookies-in-production',
            'https-enforced-in-production',
            'env-file-permissions',
            'database-connection-encrypted',
            'password-policy-compliance',
        ],
    ],
    
    'scan_paths' => [
        'config/',
        // Focus only on configuration files
    ],
];

🧪 Development-Friendly Setup

For development environments with relaxed rules:

<?php

return [
    'rules' => [
        'app-key-is-set' => true,
        'storage-writable' => true,
        'csrf-enabled' => true,
        'no-secrets-in-code' => true,
        
        // Disable strict production rules
        'app-debug-false-in-production' => false,
        'https-enforced-in-production' => false,
        'secure-cookies-in-production' => false,
    ],
    
    'environments' => [
        'local' => [
            'app-key-is-set',
            'storage-writable',
            'csrf-enabled',
        ],
    ],
];

🔄 CI/CD Optimized Setup

For continuous integration environments:

<?php

return [
    'rules' => [
        'env-has-all-required-keys' => true,
        'no-secrets-in-code' => true,
        'app-key-is-set' => true,
        'csrf-enabled' => true,
        
        // Disable environment-specific rules
        'app-debug-false-in-production' => false,
        'secure-cookies-in-production' => false,
    ],

    'scan_paths' => [
        'app/',
        'config/',
        'routes/',
        // Exclude test directories for faster scanning
    ],
    
    'performance' => [
        'max_scan_files' => 5000,
        'timeout_seconds' => 120,
        'parallel_processing' => true,
    ],
];

🏢 Enterprise Setup

For large applications with comprehensive security requirements:

<?php

return [
    'rules' => [
        // Enable all security rules
        'app-debug-false-in-production' => true,
        'app-key-is-set' => true,
        'env-has-all-required-keys' => true,
        'no-secrets-in-code' => true,
        'csrf-enabled' => true,
        'secure-cookies-in-production' => true,
        'https-enforced-in-production' => true,
        'env-file-permissions' => true,
        'sensitive-files-hidden' => true,
        'database-connection-encrypted' => true,
        'database-credentials-not-default' => true,
        'password-policy-compliance' => true,
        'two-factor-auth-enabled' => true,
        'session-security-settings' => true,
    ],
    
    'required_env_vars' => [
        'APP_KEY', 'APP_ENV', 'APP_DEBUG', 'APP_URL',
        'DB_CONNECTION', 'DB_HOST', 'DB_PORT', 'DB_DATABASE', 'DB_USERNAME', 'DB_PASSWORD',
        'MAIL_MAILER', 'MAIL_HOST', 'MAIL_PORT', 'MAIL_USERNAME', 'MAIL_PASSWORD',
        'REDIS_HOST', 'REDIS_PASSWORD', 'REDIS_PORT',
        'SESSION_DRIVER', 'SESSION_LIFETIME',
        'QUEUE_CONNECTION',
    ],
    
    'custom_rules_path' => app_path('Security/SafeguardRules'),
    'custom_rules_namespace' => 'App\\Security\\SafeguardRules',
];

🌐 Environment Variables

You can override configuration values using environment variables:

# .env
SAFEGUARD_ENABLED=true
SAFEGUARD_FAIL_ON_ERROR=true
SAFEGUARD_MAX_SCAN_FILES=5000
SAFEGUARD_TIMEOUT=300

Then in your config file:

'enabled' => env('SAFEGUARD_ENABLED', true),
'fail_on_error' => env('SAFEGUARD_FAIL_ON_ERROR', false),
'performance' => [
    'max_scan_files' => env('SAFEGUARD_MAX_SCAN_FILES', 10000),
    'timeout_seconds' => env('SAFEGUARD_TIMEOUT', 300),
],

🔧 Dynamic Configuration

You can also configure rules programmatically:

// In a service provider or middleware
use Grazulex\LaravelSafeguard\SafeguardManager;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        $safeguard = app(SafeguardManager::class);
        
        // Enable rules based on conditions
        if (app()->environment('production')) {
            $safeguard->enableRule('https-enforced-in-production');
            $safeguard->enableRule('secure-cookies-in-production');
        }
        
        // Add custom scan paths
        $safeguard->addScanPath('custom/security/');
    }
}

📚 Best Practices

🎯 1. Start Small

Enable a few critical rules first, then gradually add more:

'rules' => [
    // Start with these essential rules
    'app-key-is-set' => true,
    'csrf-enabled' => true,
    'app-debug-false-in-production' => true,
    
    // Add more rules as you become comfortable
    // 'no-secrets-in-code' => true,
    // 'env-file-permissions' => true,
],

🌍 2. Environment-Specific Configuration

Use different rule sets for different environments:

'environments' => [
    'production' => [
        // Strict rules for production
        'app-debug-false-in-production',
        'https-enforced-in-production',
        'secure-cookies-in-production',
    ],
    'local' => [
        // Relaxed rules for development
        'app-key-is-set',
        'storage-writable',
    ],
],

🏗️ 3. Custom Rules for Specific Needs

Create custom rules for your application's specific security requirements:

'custom_rules_path' => app_path('SafeguardRules'),
'rules' => [
    // Your custom rules
    'my-custom-api-security-rule' => true,
    'my-custom-payment-validation' => true,
],

📊 4. Performance Optimization

Configure performance settings for large applications:

'performance' => [
    'max_scan_files' => 5000, // Reduce for faster scans
    'timeout_seconds' => 120, // Reduce for CI/CD
    'parallel_processing' => true, // Enable for better performance
],

📖 5. Documentation

Document any custom configurations for your team:

<?php

/**
 * Laravel Safeguard Configuration
 * 
 * This configuration is customized for our application with:
 * - Strict production security rules
 * - Custom API security validation
 * - Performance optimizations for CI/CD
 * 
 * @see https://github.com/Grazulex/laravel-safeguard
 */
return [
    // Your configuration...
];

📚 Next Steps

Now that you understand configuration, explore these areas:

• 📝 Rules Reference - Learn about all available security rules
• 🏗️ Custom Rules - Create custom rules for your application
• 🌍 Environment Rules - Environment-specific configurations
• 📊 Output Formats - Customize output for different tools

---

Need Help? Check the 🆘 Troubleshooting guide or ❓ FAQ

🏠 Home | ⚡ Quick Start | 📝 Rules Reference | 🏗️ Custom Rules