Security Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require artisanpack-ui/security
   php artisan vendor:publish --tag=security-config
   

2. First Use Case: Sanitize user input and escape output in a form handler:

   use ArtisanPackUI\Security\Facades\Security;
   
   $cleanName = Security::sanitizeText(request('name'));
   echo Security::escHtml($cleanName);
   

   Or use global helpers:

   $cleanName = sanitizeText(request('name'));
   echo escHtml($cleanName);
   

3. Middleware Setup: Apply security middleware to routes:

   Route::middleware(['security.headers', 'xss.protection'])->group(function () {
       // Your routes here
   });
   

4. CSP Nonces in Blade:

   <script @csp_nonce>
       // Your JS here
   </script>
   

Where to Look First

• API Reference: docs/api-reference.md for all available functions
• Security Guidelines: docs/security-guidelines.md for best practices
• Artisan Commands: Run php artisan to see available security commands

Implementation Patterns

Core Workflows

1. Input Sanitization Pipeline

// In a controller or form request
$input = [
    'name' => request('name'),
    'email' => request('email'),
    'bio' => request('bio')
];

$cleanInput = Security::sanitizeArray($input);
// or use individual sanitizers
$cleanInput = [
    'name' => sanitizeText(request('name')),
    'email' => sanitizeEmail(request('email')),
    'bio' => kses(request('bio'), ['p', 'br', 'strong', 'em'])
];

2. Output Escaping Strategy

// Blade template
<p>{{ escHtml($userComment) }}</p>
<a href="{{ escUrl($userLink) }}">{{ escAttr($userLink) }}</a>
<script>
    const data = {{ escJs($jsonData) }};
</script>

3. CSP Implementation

// In routes/web.php
Route::middleware(['csp'])->group(function () {
    // Your routes
});

// Generate nonces in Blade
<button @csp_nonce>Click Me</button>

// Test CSP with Artisan
php artisan csp:test

4. Rate Limiting

// In routes/api.php
Route::middleware(['api.rate_limit:api'])->group(function () {
    // Your API routes
});

// Custom rate limit in middleware
Security::rateLimit('custom', function ($request) {
    return $request->ip();
});

5. Security Audits

# Run comprehensive security scan
php artisan security:audit

# Check current security headers
php artisan security:test-headers

# Benchmark performance impact
php artisan security:benchmark

Integration Tips

1. Form Request Validation:

   use ArtisanPackUI\Security\Rules\NoHtml;
   
   public function rules()
   {
       return [
           'bio' => ['required', new NoHtml],
           'website' => ['nullable', 'url', new SecureUrl]
       ];
   }
   

2. Livewire Component Security:

   use ArtisanPackUI\Security\Facades\Security;
   
   public function mount()
   {
       $this->safeContent = Security::kses($this->inputContent, ['p', 'strong']);
   }
   

3. API Security Layer:

   Route::middleware(['api.security', 'api.rate_limit:api'])->group(function () {
       // Your secure API endpoints
   });
   

4. Custom Sanitization Rules:

   Security::extendSanitizer('custom', function ($value) {
       // Your custom logic
       return $value;
   });
   
   // Usage
   Security::sanitize('custom', $value);
   

5. CSP Policy Customization:

   // In config/security.php
   'csp' => [
       'default-src' => ["'self'"],
       'script-src' => ["'self'", "'unsafe-inline'", "@csp_nonce"],
       'style-src' => ["'self'", "'unsafe-inline'", "@csp_nonce"],
       'img-src' => ["'self'", 'data:'],
       'connect-src' => ["'self'"],
       'font-src' => ["'self'"],
       'object-src' => ["'none'"],
       'base-uri' => ["'self'"],
       'form-action' => ["'self'"],
   ],
   

Gotchas and Tips

Common Pitfalls

1. Double Escaping:

   • Issue: Escaping output that's already been escaped (e.g., escHtml(escHtml($var)))
   • Fix: Only escape when outputting to HTML context, not when storing in database

2. CSP Over-Restriction:

   • Issue: Blocking legitimate resources by being too strict with CSP
   • Fix: Use csp:test command to identify blocked resources:

     php artisan csp:test --verbose
     

3. Nonce Management:

   • Issue: Forgetting to include @csp_nonce directive in dynamic content
   • Fix: Create a Blade directive for consistency:

     Blade::directive('csp', function ($expression) {
         return "<?php echo Security::generateNonce(); ?>";
     });
     

4. Rate Limit Configuration:

   • Issue: Setting too aggressive rate limits causing false positives
   • Fix: Start with conservative limits and monitor:

     'rate_limits' => [
         'api' => [
             'max' => 60, // requests
             'per' => 'minute',
             'key' => function ($request) {
                 return $request->ip();
             }
         ]
     ]
     

5. KSES Configuration:

   • Issue: Allowing unsafe attributes in KSES filter
   • Fix: Always specify allowed attributes:

     kses($html, ['p' => ['class' => true, 'id' => true]])
     

Debugging Tips

1. Security Headers:

   • Check headers with browser dev tools or:

     curl -I https://yourdomain.com
     

   • Common missing headers:
     • Content-Security-Policy
     • X-Content-Type-Options: nosniff
     • X-Frame-Options: DENY
     • X-XSS-Protection: 1; mode=block

2. CSP Violations:

   • View violations in /csp-violations endpoint
   • Check browser console for blocked resources
   • Use csp:stats command:

     php artisan csp:stats
     

3. Sanitization Issues:

   • Verify input with:

     dd(Security::sanitizeArray($input));
     

   • Check for false positives in sanitization

4. Performance Impact:

   • Benchmark with:

     php artisan security:benchmark
     

   • Look for bottlenecks in:
     • CSP nonce generation
     • Rate limiting checks
     • Complex KSES filtering

Configuration Quirks

1. CSP Reporting Endpoint:

   • Requires csp_violation_reports table (migration runs automatically)
   • Disable with:

     'csp' => [
         'report_uri' => null,
     ]
     

2. Middleware Order:

   • Ensure security.headers runs before other middleware that might modify headers
   • Typical order:
     1. security.headers
     2. xss.protection
     3. csp

3. Cache Dependencies:

   • CSP nonces are cache-dependent
   • Clear cache when changing CSP policies:

     php artisan cache:clear
     

4. Livewire Integration:

   • CSP dashboard requires Livewire (livewire/livewire)
   • Package auto-detects Livewire presence

Extension Points

1. Custom Sanitizers:

   Security::extendSanitizer('custom', function ($value, $options = []) {
       // Your sanitization logic
       return $sanitizedValue;
   });
   
   // Usage
   Security::sanitize('custom', $value);
   

2. Custom Validation Rules:

   use ArtisanPackUI\Security\Rules;
   
   class CustomRule extends Rules\BaseRule {
       public function passes($attribute, $value) {
           // Your validation logic
           return true;
       }
   }
   
   // Usage in Form Request
   $this->rules = [
       'field' => ['required', new CustomRule]
   ];
   

3. Custom CSP Directives:

   Security::extendCspDirective('custom-directive', function ($value) {
       return "custom-src $value";
   });
   
   // Usage in config
   'csp' => [
       'custom-directive' => ["'self'