Download the PHP package ados-labs/enterprise-security-shield without Composer

Enterprise Security Shield

Enterprise-Grade Web Application Firewall (WAF) for PHP 8.1+

A complete security solution with ML-based threat detection, bot verification, anomaly detection, and resilience patterns trained on real attack data.

Features

Core Security

Enterprise Security (NEW)

Resilience Patterns

Observability

Installation

Requirements

• PHP 8.1+ (uses enums, readonly properties, named arguments)
• ext-json (required)

Optional Extensions

Optional Dependencies

Quick Start

Minimal Setup (No Redis Required)

Production Setup (Redis)

SecurityMiddleware with ML

The SecurityMiddleware automatically integrates ML-based threat detection alongside pattern-based scoring.

How ML Scoring Works:

1. Pattern-based scoring (ThreatPatterns) runs first
2. ML analyzer classifies the request
3. ML score is weighted at 40% and added to pattern score
4. If ML confidence >= 85% with BAN decision → immediate block
5. Total score checked against threshold for auto-ban

TRUE Machine Learning (Online Learning)

The WAF includes a true online learning system that continuously improves from security events.

How It Works

1. Initial Knowledge: Pre-trained on 662 real security events (starting weights)
2. Continuous Learning: Every security event (ban, honeypot hit, SQLi block) trains the model
3. Concept Drift: Decay factor (0.995) ensures older patterns lose relevance over time
4. Persistence: Learned weights stored in Redis, survives restarts

Learning Status

Usage (Online Learning Classifier)

Auto-Learning Integration

The SecurityMiddleware automatically learns from every security event:

Static ML Threat Classifier

For deterministic classification (useful alongside online learning):

Training Data

• 662 security events from production logs
• 188 confirmed attack patterns
• Categories: SCANNER, IOT_EXPLOIT, CREDENTIAL_THEFT, CMS_PROBE, BRUTE_FORCE, LEGITIMATE

Features Detected

Usage

Bot Verification

Verifies legitimate bots (Googlebot, Bingbot, etc.) via DNS reverse lookup and IP range verification.

Supported Bots

Usage

DNS Verification

For search engine bots, the service performs reverse DNS lookup:

1. gethostbyaddr('66.249.66.1') → crawl-66-249-66-1.googlebot.com
2. Verify domain ends with .googlebot.com or .google.com
3. Forward lookup confirms IP matches

Anomaly Detection

Statistical anomaly detection using Z-Score and IQR (Interquartile Range) analysis.

Metrics Analyzed

Usage

XSS Detection

Multi-layer XSS detection with recursive HTML entity decoding.

Detection Patterns

• <script> tags and event handlers
• javascript: URLs
• SVG/XML payloads
• Encoded attacks (HTML entities, URL encoding, Unicode)

Usage

SQL Injection Detection

Pattern-based SQLi detection with behavioral analysis.

Detection Patterns

• UNION-based injection
• Boolean-based blind injection
• Time-based blind injection
• Error-based injection
• Stacked queries

Usage

Rate Limiting

Four algorithms for different use cases.

Algorithms

Usage

Honeypot System

69 trap endpoints to catch scanners.

Trap Endpoints

Usage

Resilience Patterns

Circuit Breaker

Retry Policy

Storage Backends

Security: Fail-Open vs Fail-Closed

By default, RedisStorage uses fail-open behavior:

• On Redis failure, returns "not banned" / score = 0
• Prioritizes availability over security
• Site stays online during outage

For high-security applications (banking, government), implement fail-closed:

Notifications

Health Checks

Admin Panel Integration

The package includes admin panel views for WordPress-style integration.

Views Included

• dashboard.php - Security overview with charts
• events.php - Security events log with filters
• ips.php - IP ban/whitelist management
• config.php - WAF configuration presets

CSS/JS Assets (CSP A+ Compliant)

All assets use external files (no inline CSS/JS):

Testing

File Structure

Enterprise Security Features

Request Smuggling Detection

Detects HTTP Request Smuggling attacks that exploit discrepancies between front-end and back-end servers.

Detected Attack Types:

• CL.TE (Front-end uses Content-Length, back-end uses Transfer-Encoding)
• TE.CL (Front-end uses Transfer-Encoding, back-end uses Content-Length)
• TE.TE (Both use Transfer-Encoding but parse obfuscation differently)

WebSocket Protection

Validates WebSocket upgrade requests and detects Cross-Site WebSocket Hijacking (CSWSH).

JWT Security Validation

Validates JWT tokens for common attack patterns. Does NOT verify signatures - use with a JWT library.

Detected Attacks:

• ALG_NONE_ATTACK - Algorithm set to "none" (bypass signature)
• ALG_CONFUSION - RS256→HS256 confusion (use public key as HMAC secret)
• HEADER_INJECTION - Malicious jku/x5u/jwk headers
• SUSPICIOUS_CLAIMS - Admin role escalation attempts

GraphQL Protection

Protects against GraphQL-specific DoS and abuse patterns.

Detected Attacks:

• DEPTH_ATTACK - Query depth exceeds limit
• COMPLEXITY_ATTACK - Query too expensive
• BATCH_ABUSE - Too many operations in batch
• INTROSPECTION_BLOCKED - Schema discovery attempt
• ALIAS_ABUSE - Excessive aliases (amplification)

DDoS Layer 7 Protection

Detects application-layer DDoS attacks. Works best with server metrics.

Detected Attacks:

• HTTP_FLOOD - Excessive request rate
• SLOWLORIS - Slow HTTP headers
• RUDY - Slow POST body (R-U-Dead-Yet)
• CONNECTION_FLOOD - Too many concurrent connections
• RESOURCE_EXHAUSTION - Expensive endpoint abuse

HTTP/2 Protection

Detects HTTP/2 protocol-specific attacks. Requires server metrics for full detection.

Detected Attacks:

• CONTINUATION_FLOOD - CVE-2024-27983
• RAPID_RESET - CVE-2023-44487
• HPACK_BOMB - Header compression abuse
• SETTINGS_FLOOD - Excessive SETTINGS frames

API Rate Limiting

Advanced rate limiting with per-endpoint, per-API-key, and tier-based limits.

Threat Intelligence Feeds

Auto-updating threat intelligence from public feeds.

Included Feeds:

• FireHOL Level 1 (high confidence malicious IPs)
• Emerging Threats Compromised IPs
• Abuse.ch Feodo Tracker (botnet C&C)
• Spamhaus DROP (Do Not Route Or Peer)
• Tor Exit Nodes (disabled by default)

SecurityShield Integration

All enterprise features are integrated into the main SecurityShield class:

What This WAF Actually Does

Attack Detection & Blocking

Machine Learning (Real, Not Marketing)

DDoS Protection (Layer 7)

Rate Limiting (4 Algorithms)

All use atomic operations (Lua scripts) to prevent race conditions:

• Sliding Window (most accurate)
• Token Bucket (burst-tolerant)
• Leaky Bucket (smooth enforcement)
• Fixed Window (simple)

Architecture: Where This WAF Fits

Use BOTH layers for complete protection.

Known Limitations

1. Fail-Open Default - Allows traffic during Redis outage (configurable to fail-closed)
2. DNS Timeout - Bot verification can block up to 30s on slow DNS (timeout configurable)
3. No L3/L4 Protection - Cannot stop volumetric network floods (use edge WAF)
4. No Third-Party Audit - Not penetration tested by external security firm
5. ML Warm-Up - Online learning needs ~50 samples before improving

Transparency

This project is honest about what it does and doesn't do:

• No penetration test - We haven't paid for a third-party security audit
• Defense in depth - Use alongside Cloudflare/AWS WAF, not instead of
• Open source - All code is inspectable, no black boxes
• Security audit included - See docs/SECURITY-AUDIT.md for known vulnerabilities we've documented ourselves

License

MIT License - see LICENSE

Credits

• Initial ML model trained on security events from real production environments
• Online Learning Classifier uses Naive Bayes with Laplace smoothing
• Concept drift handling via exponential decay (0.995 factor)
• Feature extraction from 40+ attack patterns across 11 threat categories