Cookbook

Security Guide

Authentication, permissions, CSRF, security headers, rate limiting, lockdown, and security CLI

Overview

Glueful provides enterprise-grade security features that are fully implemented and production-ready. This guide covers the comprehensive security system that protects your application from common threats and vulnerabilities.

Security Architecture
Vulnerability Scanner
Authentication & Authorization
Rate Limiting System
Session Security
Security Middleware
CSRF Protection
Security Headers
Emergency Lockdown
Security Monitoring
Security Configuration
Security Commands
Production Security

Security Architecture

Multi-Layer Defense

Glueful implements a comprehensive security architecture with multiple layers of protection:

┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                        │
│  • CSRF Protection  • Input Validation  • Authorization   │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                    Framework Layer                          │
│  • Rate Limiting  • Security Headers  • Authentication    │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                  Infrastructure Layer                       │
│  • Emergency Lockdown  • Vulnerability Scanner  • Audit   │
└─────────────────────────────────────────────────────────────┘

Core Security Components

Vulnerability Scanner: Automated security vulnerability detection
Adaptive Rate Limiting: Multi-dimensional request limiting with behavioral analysis
JWT Authentication: Dual-layer session storage (database + cache)
CSRF Protection: Double-submit pattern with configurable exemptions
Security Headers: Comprehensive security header middleware
Emergency Lockdown: Granular severity-based access control
Session Analytics: Advanced session monitoring and anomaly detection

Vulnerability Scanner

Glueful includes a comprehensive vulnerability scanner that analyzes code, dependencies, and configuration for security issues.

Scanner Capabilities

The vulnerability scanner detects:

Code Vulnerabilities
- SQL injection patterns
- Cross-site scripting (XSS)
- Path traversal vulnerabilities
- Command injection
- Insecure direct object references
Dependency Vulnerabilities
- Known CVEs in Composer packages
- Outdated dependencies with security issues
- Vulnerable JavaScript dependencies
Configuration Security
- Environment configuration issues
- File permission problems
- Missing security headers
- Debug mode in production

Running Security Scans

# Full vulnerability scan
php glueful security:scan

# Scan specific component types
php glueful security:scan --type=code
php glueful security:scan --type=dependencies
php glueful security:scan --type=config

# Generate detailed reports
php glueful security:vulnerabilities --format=json
php glueful security:vulnerabilities --export=csv

Scanner Output Example

$ php glueful security:scan

Glueful Security Scanner
=======================

✓ Scanning code for vulnerabilities...
✓ Checking dependencies...
✓ Validating configuration...

Results:
========
[HIGH] Potential SQL injection in UserController
  File: api/Controllers/UserController.php:45
  Issue: User input not properly sanitized
  Recommendation: Use parameterized queries

[MEDIUM] Outdated dependency detected
  Package: guzzlehttp/guzzle 6.5.2
  Issue: Known security vulnerability CVE-2022-29248
  Recommendation: Update to version 7.4.3+

[LOW] Missing security header
  Issue: X-Content-Type-Options not configured
  Recommendation: Enable in SecurityHeadersMiddleware

Summary:
- High: 1 issue
- Medium: 1 issue  
- Low: 1 issue
- Security Score: 85/100

Configuration

# Vulnerability Scanner Settings
VULNERABILITY_SCANNER_ENABLED=true
SCANNER_AUTO_EXPORT=true
SCANNER_HISTORICAL_TRACKING=true
SCANNER_REPORT_FORMAT=json

Authentication & Authorization

JWT Authentication with SessionStore (DB + Cache)

Glueful uses a unified SessionStore to persist sessions in the database with cache acceleration. This provides a single, testable API for creating, updating, revoking, and reading sessions.

SessionStoreInterface

use Glueful\Auth\Interfaces\SessionStoreInterface;
use Glueful\Auth\TokenManager;
use Glueful\Auth\JWTService;

/** @var SessionStoreInterface $store */
$store = container()->get(SessionStoreInterface::class);

// Create token pair and persist a session
$user = [
    'uuid' => $userUuid,
    'username' => $username,
    'email' => $email,
];

$accessTtl  = $store->getAccessTtl('jwt', false);
$refreshTtl = $store->getRefreshTtl('jwt', false);
$tokens     = TokenManager::generateTokenPair($user, $accessTtl, $refreshTtl);

$created = $store->create($user, $tokens, 'jwt', false);

// Lookup by access token
$session = $store->getByAccessToken($tokens['access_token']);

// Rotate tokens (update)
$newTokens = TokenManager::generateTokenPair($user, $accessTtl, $refreshTtl);
$updated   = $store->updateTokens($tokens['refresh_token'], $newTokens);

// Revoke session
$revoked = $store->revoke($newTokens['access_token']);

// Maintenance
$cleanedCount = $store->cleanupExpired();

// JWT verification (signature + exp)
$ok = JWTService::verify($newTokens['access_token']);

Session Analytics

use Glueful\Auth\SessionAnalytics;

$analytics = container()->get(SessionAnalytics::class);

// Get session metrics
$metrics = $analytics->getSessionMetrics($userUuid);

// Analyze session patterns
$patterns = $analytics->analyzeSessionPatterns($userUuid);

// Security assessment
$riskScore = $analytics->calculateRiskScore($sessionId);

Authentication Configuration

# JWT Configuration
JWT_KEY=your-secure-256-bit-key
ACCESS_TOKEN_LIFETIME=900    # 15 minutes
REFRESH_TOKEN_LIFETIME=604800 # 7 days
SESSION_LIFETIME=86400       # 24 hours

# Session Storage
SESSION_CACHE_ENABLED=true
SESSION_CACHE_TTL=3600
SESSION_DB_ENABLED=true

Rate Limiting System

Glueful implements sophisticated rate limiting with adaptive behavior and multiple dimensions.

Adaptive Rate Limiting

The rate limiter analyzes user behavior and adjusts limits dynamically:

# Rate Limiting Configuration
RATE_LIMITING_ENABLED=true
ADAPTIVE_RATE_LIMITING=true
RATE_LIMIT_DRIVER=redis

# Multiple Dimensions
IP_RATE_LIMIT_MAX=100        # per minute
USER_RATE_LIMIT_MAX=1000     # per hour
ENDPOINT_RATE_LIMIT_MAX=50   # per minute

# Adaptive Behavior
RATE_LIMIT_BEHAVIOR_PROFILING=true
RATE_LIMIT_MACHINE_LEARNING=false  # Statistical analysis used instead
RATE_LIMIT_BURST_ALLOWANCE=2.0

Rate Limiting in Action

The rate limiter automatically:

Tracks request patterns per IP, user, and endpoint
Applies adaptive penalties for suspicious behavior
Integrates with the security event system
Provides detailed rate limit headers in responses

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Session Security

Session Monitoring

Glueful provides comprehensive session security monitoring:

use Glueful\Auth\SessionAnalytics;

$analytics = container()->get(SessionAnalytics::class);

// Monitor session for anomalies
$anomalies = $analytics->detectAnomalies($sessionId);

// Get session risk assessment
$riskAssessment = $analytics->assessSessionRisk($sessionId);

// Track session behavior
$behaviorProfile = $analytics->getSessionBehaviorProfile($userId);

Session Configuration

# Session Security
SESSION_ANALYTICS_ENABLED=true
SESSION_ANOMALY_DETECTION=true
SESSION_RISK_SCORING=true
SESSION_BEHAVIOR_TRACKING=true

# Security Thresholds
SUSPICIOUS_LOGIN_THRESHOLD=3
SESSION_HIJACK_DETECTION=true
UNUSUAL_LOCATION_ALERTS=true

Security Middleware

Glueful includes comprehensive security middleware that's automatically applied:

Available Middleware

AuthenticationMiddleware - JWT token validation
AdminPermissionMiddleware - Admin access control
RateLimiterMiddleware - Request rate limiting
SecurityHeadersMiddleware - Security headers
CSRFMiddleware - CSRF protection

Middleware Stack

The security middleware stack is automatically configured based on your environment and security settings.

CSRF Protection

Double-Submit Pattern

Glueful implements CSRF protection using the double-submit cookie pattern:

// CSRF token generation (automatic)
$token = csrf_token();

// Validation (automatic in middleware)
// Tokens are validated from:
// - HTTP headers (X-CSRF-TOKEN)
// - Form fields (_token)
// - JSON body (token)

CSRF Configuration

# CSRF Protection
CSRF_PROTECTION_ENABLED=true
CSRF_TOKEN_LIFETIME=3600
CSRF_COOKIE_NAME=csrf_token
CSRF_HEADER_NAME=X-CSRF-TOKEN

# Route Exemptions
CSRF_EXEMPT_ROUTES=api/webhooks,api/public

CSRF in Forms

<!-- Automatic token injection in forms -->
<form method="POST" action="/submit">
    <input type="hidden" name="_token" value="{{ csrf_token() }}">
    <!-- form fields -->
</form>

Security Headers

Comprehensive Header Protection

The SecurityHeadersMiddleware automatically adds security headers:

// Headers automatically applied:
// - Content-Security-Policy
// - X-XSS-Protection: 1; mode=block
// - X-Content-Type-Options: nosniff
// - X-Frame-Options: DENY
// - Referrer-Policy: strict-origin-when-cross-origin
// - Strict-Transport-Security (HTTPS only)
// - Permissions-Policy

Security Headers Configuration

# Security Headers
SECURITY_HEADERS_ENABLED=true
HSTS_MAX_AGE=31536000
CSP_ENABLED=true
CSP_REPORT_URI=/api/csp-report
FRAME_OPTIONS=DENY

Content Security Policy

# CSP Configuration
CSP_DEFAULT_SRC="'self'"
CSP_SCRIPT_SRC="'self' 'unsafe-inline'"
CSP_STYLE_SRC="'self' 'unsafe-inline'"
CSP_IMG_SRC="'self' data: https:"
CSP_FONT_SRC="'self'"
CSP_CONNECT_SRC="'self'"
CSP_MEDIA_SRC="'self'"
CSP_OBJECT_SRC="'none'"

Emergency Lockdown

Granular Lockdown System

Glueful includes an emergency lockdown system with multiple severity levels:

# Enable lockdown with different severity levels
php glueful security:lockdown --severity=low
php glueful security:lockdown --severity=medium
php glueful security:lockdown --severity=high
php glueful security:lockdown --severity=critical

# Disable lockdown
php glueful security:lockdown --disable

Lockdown Severity Levels

Low: Restrict non-essential endpoints
Medium: Allow only core functionality
High: Emergency access only
Critical: Complete lockdown (admin access only)

Lockdown Configuration

# Emergency Lockdown
LOCKDOWN_ENABLED=false
LOCKDOWN_SEVERITY=medium
LOCKDOWN_AUTO_RECOVERY=true
LOCKDOWN_RECOVERY_TIME=3600  # 1 hour

# IP Blocking
LOCKDOWN_ENABLE_IP_BLOCKING=true
LOCKDOWN_IP_BLOCK_THRESHOLD=10
LOCKDOWN_IP_BLOCK_DURATION=1800

# Notifications
LOCKDOWN_WEBHOOK_URL=https://alerts.company.com/webhook
[email protected]

Lockdown Status Check

# Check lockdown status
php glueful security:check

# Example output:
Security Status: ACTIVE LOCKDOWN
Severity Level: HIGH
Lockdown Reason: Emergency security incident
Auto-Recovery: Enabled (expires in 45 minutes)
Blocked IPs: 3 addresses
Restricted Endpoints: 15 routes

Security Monitoring

Real-Time Security Events

Glueful dispatches security events that you can listen to:

// Available security events:
// - CSRFViolationEvent
// - RateLimitExceededEvent  
// - SessionCreatedEvent
// - SessionDestroyedEvent
// - SecurityScanCompletedEvent

Event Listeners

use Glueful\Events\Security\RateLimitExceededEvent;

$dispatcher->addListener(RateLimitExceededEvent::class, function($event) {
    // Custom security response
    if ($event->isSevereViolation()) {
        // Enable emergency lockdown
        $lockdownService->enableLockdown('high', 'Rate limit abuse detected');
    }
});

Security Configuration

Main Security Configuration

// config/security.php
return [
    'vulnerability_scanner' => [
        'enabled' => env('VULNERABILITY_SCANNER_ENABLED', true),
        'auto_export' => env('SCANNER_AUTO_EXPORT', true),
        'historical_tracking' => env('SCANNER_HISTORICAL_TRACKING', true),
    ],
    
    'rate_limiting' => [
        'enabled' => env('RATE_LIMITING_ENABLED', true),
        'adaptive' => env('ADAPTIVE_RATE_LIMITING', true),
        'behavior_profiling' => env('RATE_LIMIT_BEHAVIOR_PROFILING', true),
    ],
    
    'csrf' => [
        'enabled' => env('CSRF_PROTECTION_ENABLED', true),
        'token_lifetime' => env('CSRF_TOKEN_LIFETIME', 3600),
        'exempt_routes' => explode(',', env('CSRF_EXEMPT_ROUTES', '')),
    ],
    
    'headers' => [
        'enabled' => env('SECURITY_HEADERS_ENABLED', true),
        'hsts_max_age' => env('HSTS_MAX_AGE', 31536000),
        'csp_enabled' => env('CSP_ENABLED', true),
    ],
];

Lockdown Configuration

// config/lockdown.php
return [
    'enabled' => env('LOCKDOWN_ENABLED', false),
    'severity' => env('LOCKDOWN_SEVERITY', 'medium'),
    'auto_recovery' => env('LOCKDOWN_AUTO_RECOVERY', true),
    'recovery_time' => env('LOCKDOWN_RECOVERY_TIME', 3600),
    
    'ip_blocking' => [
        'enabled' => env('LOCKDOWN_ENABLE_IP_BLOCKING', true),
        'threshold' => env('LOCKDOWN_IP_BLOCK_THRESHOLD', 10),
        'duration' => env('LOCKDOWN_IP_BLOCK_DURATION', 1800),
    ],
    
    'notifications' => [
        'webhook_url' => env('LOCKDOWN_WEBHOOK_URL'),
        'email_alerts' => env('LOCKDOWN_EMAIL_ALERTS'),
    ],
];

Security Commands

Available Security Commands

# Vulnerability Management
php glueful security:scan                    # Run vulnerability scan
php glueful security:vulnerabilities         # List vulnerabilities
php glueful security:check                   # Security health check

# Lockdown Management  
php glueful security:lockdown                # Manage emergency lockdown
php glueful security:lockdown --severity=high
php glueful security:lockdown --disable

# Authentication & Sessions
php glueful security:revoke-tokens           # Revoke user tokens
php glueful security:reset-password          # Reset user passwords

# Reporting
php glueful security:report                  # Generate security report

Security Command Examples

# Comprehensive security check
$ php glueful security:check

Security Health Check
====================
✓ Vulnerability Scanner: Active
✓ Rate Limiting: Enabled (Adaptive)
✓ CSRF Protection: Active
✓ Security Headers: Configured
✓ Session Analytics: Active
✗ Emergency Lockdown: Disabled
⚠ SSL Certificate: Expires in 30 days

Overall Security Score: 92/100

# Emergency lockdown activation
$ php glueful security:lockdown --severity=high --reason="Security incident"

Emergency Lockdown Activated
============================
Severity: HIGH
Reason: Security incident
Restricted Endpoints: 15 routes
Auto-Recovery: Enabled (60 minutes)
IP Blocking: Active
Notifications: Sent to security team

Production Security

Production Security Validation

Glueful includes production security validation to ensure your application is properly secured:

# Validate production security
php glueful security:check --environment=production

# Example output:
Production Security Validation
==============================
✓ Environment: production
✓ Debug Mode: Disabled
✓ SSL/HTTPS: Enforced
✓ Security Headers: Active
✓ Rate Limiting: Configured
✓ CSRF Protection: Enabled
✓ JWT Keys: Secure (256-bit)
✓ Database: SSL Enabled
✗ Vulnerability Scanner: Not scheduled
⚠ Session Timeout: Consider shorter timeout

Security Score: 88/100

Recommendations:
1. Schedule daily vulnerability scans
2. Reduce session timeout for production
3. Enable additional rate limiting dimensions

Production Security Checklist

Before deploying to production, ensure:

APP_ENV=production and APP_DEBUG=false
Strong JWT keys generated (php glueful generate:key)
SSL/HTTPS enforced
Security headers enabled
CSRF protection active
Rate limiting configured
Vulnerability scanner scheduled
Emergency lockdown configured
Security monitoring enabled
Database SSL enabled

Environment-Specific Security

# Production Security Settings
APP_ENV=production
APP_DEBUG=false

# Strict Security
SECURITY_LEVEL=strict
RATE_LIMITING_STRICT_MODE=true
CSRF_PROTECTION_STRICT=true
SECURITY_HEADERS_STRICT=true

# Monitoring
VULNERABILITY_SCANNER_SCHEDULE=daily
SECURITY_MONITORING_ENABLED=true
[email protected]

Security Best Practices

Development Security

Use the vulnerability scanner regularly
```
php glueful security:scan
```
Test security configurations
```
php glueful security:check
```

Monitor security events

// Listen for security events
$dispatcher->addListener(SecurityEvent::class, $handler);

Production Security

Enable all security features
```
SECURITY_LEVEL=strict
```

Schedule regular security scans

# Add to cron
0 2 * * * cd /path/to/app && php glueful security:scan

Monitor security metrics

php glueful security:report --format=json

Configure emergency procedures

# Test lockdown procedures
php glueful security:lockdown --test

Summary

Glueful provides a comprehensive, production-ready security framework that includes:

Automated vulnerability scanning with detailed reporting
Adaptive rate limiting with behavioral analysis
Robust authentication with dual-layer session storage
Comprehensive CSRF protection with configurable exemptions
Security headers middleware with modern security policies
Emergency lockdown system with granular severity levels
Real-time security monitoring with event-driven responses
Production security validation with automated checks

All security features are fully implemented, tested, and ready for production use. The security system is designed to provide enterprise-grade protection while maintaining ease of use and configuration flexibility.# CSRF Protection Implementation Guide

This document explains how to use the CSRF (Cross-Site Request Forgery) protection middleware in Glueful.

Overview

The CSRFMiddleware protects against CSRF attacks by validating tokens for state-changing HTTP methods (POST, PUT, PATCH, DELETE). It provides:

Cryptographically secure token generation
Session-based token storage with cache fallback
Multiple token submission methods (header, form field, JSON)
Configurable exempt routes
Integration with existing authentication system

Quick Setup

1. Add Middleware to Your Application

// In your middleware stack or route configuration
use Glueful\Http\Middleware\CSRFMiddleware;

// Basic usage
$app->add(new CSRFMiddleware());

// With API route exemptions
$app->add(CSRFMiddleware::withApiExemptions());

// Custom configuration
$app->add(new CSRFMiddleware(
    exemptRoutes: ['api/webhooks/*', 'api/public/*'],
    tokenLifetime: 3600, // 1 hour
    useDoubleSubmit: false,
    enabled: true
));

2. Include CSRF Token in Forms

<!-- HTML Forms -->
<form method="POST" action="/api/users">
    <?= \Glueful\Helpers\Utils::csrfField($request) ?>
    <input type="text" name="username" required>
    <button type="submit">Create User</button>
</form>

3. Include CSRF Token in AJAX Requests

// Get CSRF token data
fetch('/api/csrf-token')
    .then(response => response.json())
    .then(data => {
        // Store token for subsequent requests
        window.csrfToken = data.token;
        window.csrfHeader = data.header;
    });

// Use in AJAX requests
fetch('/api/users', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-CSRF-Token': window.csrfToken
    },
    body: JSON.stringify({
        username: 'john_doe',
        email: '[email protected]'
    })
});

Configuration Options

Constructor Parameters

exemptRoutes (array): Routes to exempt from CSRF protection
tokenLifetime (int): Token lifetime in seconds (default: 3600)
useDoubleSubmit (bool): Enable double-submit cookie pattern (default: false)
enabled (bool): Whether CSRF protection is enabled (default: true)

Environment Variables

You can disable CSRF protection via environment:

# .env
CSRF_PROTECTION_ENABLED=true
CSRF_TOKEN_LIFETIME=3600

Token Submission Methods

The middleware accepts CSRF tokens via:

HTTP Header (recommended for AJAX): X-CSRF-Token
Form Field: _token
Query Parameter: _token (use with caution)
JSON Body: {"_token": "your-token"}

Helper Functions

Utils::csrfToken(Request $request)

Returns the current CSRF token:

$token = \Glueful\Helpers\Utils::csrfToken($request);

Utils::csrfField(Request $request)

Returns HTML hidden input field:

echo \Glueful\Helpers\Utils::csrfField($request);
// Output: <input type="hidden" name="_token" value="abc123...">

Utils::csrfTokenData(Request $request)

Returns token data for JavaScript:

$tokenData = \Glueful\Helpers\Utils::csrfTokenData($request);
// Returns: ['token' => '...', 'header' => 'X-CSRF-Token', 'field' => '_token', 'expires_at' => timestamp]

Creating a CSRF Token Endpoint

Add this to your routes to provide tokens for JavaScript:

// routes/api.php
use Glueful\Http\Response;
use Glueful\Helpers\Utils;

Router::get('/csrf-token', function($params, $request) {
    return Response::ok(Utils::csrfTokenData($request));
});

Exempt Routes

Common routes to exempt from CSRF protection:

$exemptRoutes = [
    'api/auth/login',           // Login endpoint
    'api/auth/register',        // Registration endpoint
    'api/webhooks/*',           // Webhook endpoints
    'api/public/*',             // Public API endpoints
    'api/uploads/temp/*'        // Temporary upload endpoints
];

$middleware = new CSRFMiddleware($exemptRoutes);

Security Considerations

Token Security

Tokens are cryptographically secure (32 hex characters)
Uses constant-time comparison to prevent timing attacks
Tokens expire after configured lifetime

Session Handling

Tokens are tied to user sessions when authenticated
Anonymous sessions use IP + User-Agent fingerprint
Cache-based storage for performance

Optional enhanced security:

$middleware = new CSRFMiddleware(
    useDoubleSubmit: true  // Enables cookie-based validation
);

Error Handling

CSRF validation failures throw SecurityException with HTTP 419 status:

try {
    // Process request
} catch (\Glueful\Exceptions\SecurityException $e) {
    if ($e->getData()['error_code'] === 'CSRF_TOKEN_MISMATCH') {
        // Handle CSRF failure
        return Response::error('Please refresh and try again', 419);
    }
}

Testing

Unit Tests

public function testCSRFTokenGeneration()
{
    $request = new Request();
    $middleware = new CSRFMiddleware();
    
    $token = $middleware->generateToken($request);
    $this->assertNotEmpty($token);
    $this->assertEquals(32, strlen($token));
}

Integration Tests

public function testCSRFProtection()
{
    // Test that POST without token fails
    $response = $this->post('/api/users', ['username' => 'test']);
    $this->assertEquals(419, $response->getStatusCode());
    
    // Test that POST with valid token succeeds
    $token = $this->getCSRFToken();
    $response = $this->post('/api/users', [
        'username' => 'test',
        '_token' => $token
    ]);
    $this->assertEquals(201, $response->getStatusCode());
}

Best Practices

Always include CSRF tokens in forms and AJAX requests
Use HTTPS to prevent token interception
Set appropriate token lifetime (balance security vs. UX)
Exempt only necessary routes from CSRF protection
Handle CSRF failures gracefully with user-friendly messages
Test CSRF protection in your application tests

Troubleshooting

Common Issues

Token Mismatch Errors:

Verify token is included in request
Check token hasn't expired
Ensure consistent session handling

Missing Tokens:

Verify middleware is properly registered
Check exempt routes configuration
Ensure token generation for safe methods

AJAX Issues:

Include X-CSRF-Token header
Get fresh token from /csrf-token endpoint
Handle token expiration in JavaScript

Debug Mode

Enable debug logging to troubleshoot CSRF issues:

// In development only
$middleware = new CSRFMiddleware(
    enabled: env('APP_ENV') === 'production'
);

Error Handling Guide

Standard API error shapes, framework ExceptionHandler, Response helpers, and practical patterns

Configuration Options

Validate and normalize service options with Glueful’s internal SimpleOptionsResolver