Documentation | php-next WebShield™

Installation

Via Composer

composer require php-next/webshield-open

This will install WebShield Open-Core and all dependencies.

Configuration

Create a config file at config/webshield.config.php:

return [
    'mode' => 'protect', // observe | protect | deceive | aggressive
    'sensitivity' => 3, // 1-5
    'log_level' => 'info', // info | debug | forensic
    'honeypots' => ['login', 'db', 'api'],
    'allowed_ips' => [],
    'blocked_ips' => [],
    'log_path' => __DIR__ . '/logs/webshield.log',
];
                    

Defense Modes

observe – Never blocks, only logs threats. Perfect for testing and monitoring.
protect – Blocks requests with threat_level 'high' or 'critical'. Recommended for production.
deceive – Serves honeypot responses instead of blocking. Useful for intelligence gathering.
aggressive – Adds delays and blocks faster. Use when under active attack.

Logging Format

Logs are written as JSON lines, one event per line:

{"ts":"2025-11-30T18:00:00Z","ip":"1.2.3.4","url":"/wp-admin","level":"high","mode":"protect","rules":["scanner_paths"],"plan":"block"}
                    

This format is compatible with log aggregators like ELK, Splunk, and Grafana.

Detection Rules

SQL Injection

UNION SELECT patterns
OR-based attacks (' OR 1=1)
Time-based (sleep, benchmark)
Information schema probing
Stacked queries (; DROP TABLE)
URL-encoded variants

XSS (Cross-Site Scripting)

Script tags (<script>)
Event handlers (onerror, onload, onclick)
JavaScript URIs (javascript:)
Iframe/SVG injection
Script chaining patterns

Scanner Paths

WordPress paths (/wp-admin, /wp-login.php)
Database tools (/phpmyadmin, /adminer.php)
Shell scripts (/shell.php, /c99.php)
Config files (/.env, /.git/config)

Brute-Force Detection

Tracks multiple failed login attempts from the same IP within a time window (default: 10 attempts in 5 minutes).

How Thresholds Work

Threat levels are calculated based on score thresholds:

Low (0-4) – No threats detected
Medium (5-14) – Suspicious patterns
High (15-29) – Likely attack
Critical (30+) – Definite attack

Thresholds are configurable in webshield.config.php.

Quick Start

Use WebShieldFactory for easy setup:

use PhpNext\WebShieldOpen\WebShield\WebShieldFactory;

$shield = WebShieldFactory::fromDefaults();
$response = $shield->handle($_SERVER, $_GET, $_POST, getallheaders());

if ($response !== null) {
    http_response_code($response['status']);
    foreach ($response['headers'] as $k => $v) {
        header("$k: $v");
    }
    echo $response['body'];
    exit;
}
                    

Or try the demo site included in the package.

Open-Core Documentation