easystream-main/docs/SECURITY.md

Security Guide

EasyStream implements comprehensive security measures to protect against common web application vulnerabilities and ensure data integrity.

Security Framework Overview

Core Security Classes

• VSecurity - Input validation and sanitization
• VAuth - Authentication management
• VRBAC - Role-based access control
• VIPTracker - IP monitoring and blocking
• VFingerprint - Browser fingerprinting
• VLogger - Security event logging

Input Validation and Sanitization

Safe Input Handling

Always use the security wrapper functions for user input:

// GET parameters
$id = get_param('id', 'int');
$email = get_param('email', 'email');
$filename = get_param('file', 'filename');

// POST parameters
$username = post_param('username', 'alphanum');
$content = post_param('content', 'text');
$url = post_param('url', 'url');

Validation Types

• int - Integer values only
• email - Valid email addresses
• url - Valid URLs
• alpha - Alphabetic characters only
• alphanum - Alphanumeric characters
• slug - URL-safe slugs
• filename - Safe filenames
• boolean - Boolean values
• text - General text with XSS protection

Custom Validation

$input = VSecurity::validateInput($value, [
    'type' => 'custom',
    'pattern' => '/^[A-Z0-9]{6,12}$/',
    'min_length' => 6,
    'max_length' => 12
]);

Output Escaping

HTML Context

echo secure_output($user_content);

JavaScript Context

echo '<script>var data = ' . secure_js($data) . ';</script>';

URL Context

echo '<a href="' . secure_url($url) . '">Link</a>';

CSRF Protection

Form Protection

// In templates
{csrf_field('form_action')}

// In PHP
echo csrf_field('form_action');

Validation

if (!validate_csrf('form_action')) {
    throw new SecurityException('CSRF token validation failed');
}

Authentication System

Password Security

• Minimum 8 characters
• Bcrypt/Argon2 hashing
• Salt generation
• Password strength validation

// Password hashing
$hash = VAuth::hashPassword($password);

// Password verification
if (VAuth::verifyPassword($password, $hash)) {
    // Login successful
}

Session Management

• Secure session configuration
• Session regeneration on login
• Automatic session timeout
• Session hijacking protection

// Start secure session
VAuth::startSecureSession();

// Regenerate session ID
VAuth::regenerateSession();

// Destroy session
VAuth::destroySession();

Multi-Factor Authentication

// Generate TOTP secret
$secret = VAuth::generateTOTPSecret();

// Verify TOTP code
if (VAuth::verifyTOTP($code, $secret)) {
    // MFA successful
}

Authorization (RBAC)

Role Management

// Check user role
if (VRBAC::hasRole($userId, 'admin')) {
    // Admin access
}

// Check specific permission
if (VRBAC::hasPermission($userId, 'video.delete')) {
    // Can delete videos
}

Resource-Level Permissions

// Check resource access
if (VRBAC::canAccess($userId, 'video', $videoId, 'edit')) {
    // Can edit this specific video
}

Rate Limiting

Implementation

// Check rate limit
if (!check_rate_limit('login_' . $ip, 5, 300)) {
    throw new SecurityException('Too many login attempts');
}

// Custom rate limiting
if (!VSecurity::checkRateLimit($key, $maxAttempts, $windowSeconds)) {
    // Rate limit exceeded
}

Common Rate Limits

• Login attempts: 5 per 5 minutes
• API requests: 100 per hour
• File uploads: 10 per hour
• Password resets: 3 per hour

File Upload Security

Validation

$result = validate_file_upload($_FILES['upload'], [
    'allowed_types' => ['image/jpeg', 'image/png', 'video/mp4'],
    'max_size' => 100 * 1024 * 1024, // 100MB
    'scan_content' => true
]);

if (!$result['valid']) {
    throw new SecurityException($result['error']);
}

Security Measures

• MIME type validation
• File extension checking
• Content scanning
• Size limitations
• Virus scanning (if available)
• Secure file storage

IP Tracking and Blocking

Automatic Monitoring

// Log user activity
VIPTracker::logActivity($ip, 'login_attempt', [
    'user_id' => $userId,
    'success' => $success
]);

// Check if IP is banned
if (VIPTracker::isBanned($ip)) {
    throw new SecurityException('IP address is banned');
}

Manual IP Management

// Ban IP address
VIPTracker::banIP($ip, 'Suspicious activity', 3600); // 1 hour

// Unban IP address
VIPTracker::unbanIP($ip);

Browser Fingerprinting

Fingerprint Generation

// Generate fingerprint
$fingerprint = VFingerprint::generateFingerprint($_SERVER, $_POST);

// Track fingerprint
VFingerprint::trackFingerprint($fingerprint, $userId);

Threat Detection

// Check for suspicious fingerprints
if (VFingerprint::isBanned($fingerprint)) {
    // Handle banned fingerprint
}

// Detect fingerprint anomalies
$risk = VFingerprint::calculateRiskScore($fingerprint);
if ($risk > 0.8) {
    // High risk - additional verification required
}

Security Headers

HTTP Security Headers

// Set in Caddy configuration or PHP
header('X-Content-Type-Options: nosniff');
header('X-Frame-Options: DENY');
header('X-XSS-Protection: 1; mode=block');
header('Strict-Transport-Security: max-age=31536000; includeSubDomains');
header('Content-Security-Policy: default-src \'self\'');

Database Security

Query Protection

// Always use prepared statements
$result = $db->execute("SELECT * FROM users WHERE id = ?", [$userId]);

// Validate table/field names
$table = VDatabase::validateTableName($table);
$field = VDatabase::validateFieldName($field);

Connection Security

• Use dedicated database user with minimal privileges
• Enable SSL/TLS for database connections
• Regular password rotation
• Connection pooling with limits

Logging and Monitoring

Security Event Logging

// Log security events
VLogger::security('Failed login attempt', [
    'ip' => $ip,
    'username' => $username,
    'user_agent' => $_SERVER['HTTP_USER_AGENT']
]);

// Log admin actions
VLogger::admin('User deleted', [
    'admin_id' => $adminId,
    'target_user_id' => $userId
]);

Log Analysis

• Monitor failed login attempts
• Track privilege escalation attempts
• Detect unusual access patterns
• Alert on security threshold breaches

Vulnerability Prevention

SQL Injection

• Use prepared statements exclusively
• Validate all input parameters
• Escape dynamic table/field names
• Limit database user privileges

XSS Prevention

• Escape all output by default
• Use Content Security Policy
• Validate and sanitize rich text input
• Implement proper encoding for different contexts

CSRF Protection

• Use anti-CSRF tokens for all forms
• Validate tokens on server side
• Implement SameSite cookie attributes
• Use double-submit cookie pattern for AJAX

Directory Traversal

• Validate file paths
• Use whitelisted directories
• Implement proper access controls
• Sanitize filename inputs

Security Testing

Automated Testing

# Run security tests
./run-tests.sh --filter=Security

# Run specific security test
phpunit tests/Security/AuthSecurityTest.php

Manual Testing Checklist

• Input validation on all forms
• CSRF protection on state-changing operations
• Authentication bypass attempts
• Authorization escalation tests
• File upload security validation
• SQL injection testing
• XSS payload testing

Incident Response

Security Incident Handling

1. Detection - Monitor logs and alerts
2. Analysis - Investigate the incident
3. Containment - Limit damage and exposure
4. Eradication - Remove the threat
5. Recovery - Restore normal operations
6. Lessons Learned - Improve security measures

Emergency Procedures

// Emergency IP ban
VIPTracker::emergencyBan($ip, 'Security incident');

// Disable user account
VAuth::disableUser($userId, 'Security breach');

// Clear all sessions
VAuth::clearAllSessions();

Security Configuration

Environment Variables

# Security settings
SECURITY_LEVEL=high
CSRF_PROTECTION=enabled
RATE_LIMITING=enabled
IP_TRACKING=enabled
FINGERPRINTING=enabled

# Session security
SESSION_SECURE=true
SESSION_HTTPONLY=true
SESSION_SAMESITE=strict

Database Configuration

-- Create security-focused database user
CREATE USER 'easystream_app'@'%' IDENTIFIED BY 'strong_password';
GRANT SELECT, INSERT, UPDATE, DELETE ON easystream.* TO 'easystream_app'@'%';
FLUSH PRIVILEGES;

Compliance and Standards

Security Standards

• OWASP Top 10 compliance
• PCI DSS requirements (if handling payments)
• GDPR data protection requirements
• SOC 2 Type II controls

Regular Security Tasks

• Security dependency updates
• Vulnerability scanning
• Penetration testing
• Security code reviews
• Access control audits
• Log analysis and monitoring

Security Resources

Documentation

• OWASP Security Guide
• PHP Security Best Practices
• Web Application Security Testing

Tools

• Static analysis: PHPStan, Psalm
• Dependency scanning: Composer audit
• Vulnerability scanning: OWASP ZAP
• Code review: SonarQube