README

Security Middleware for PHP 8.1+

Honeypot, scanner detection, and resilience patterns for PHP applications.

What This Package Does

• Honeypot System - 69 trap endpoints to catch scanners (/.env, /wp-admin, etc.)
• Scanner Detection - Identifies sqlmap, nikto, masscan by signatures
• Rate Limiting - 4 algorithms: sliding window, token bucket, leaky bucket, fixed window
• IP Scoring - Accumulates threat scores based on behavior
• Bot Verification - DNS-based verification for Googlebot, Bingbot
• Geo-Blocking - Country-level restrictions via external GeoIP provider

What This Package Does NOT Do

• Not a WAF - No SQL injection, XSS, or OWASP Top 10 detection
• Not DDoS Protection - Cannot handle volumetric attacks (use Cloudflare/AWS Shield)
• Not ML-Based - No machine learning, just signature and statistical detection
• Not Penetration Tested - Has not undergone professional security audit

Use alongside a real WAF (ModSecurity, Cloudflare) for production.

Architecture

Resilience Patterns

Observability

Anomaly Detection

Installation

composer require senza1dio/security-shield

Quick Start

Option 1: No Dependencies (Development/Testing)

<?php
use Senza1dio\SecurityShield\Middleware\SecurityMiddleware;
use Senza1dio\SecurityShield\Config\SecurityConfig;
use Senza1dio\SecurityShield\Storage\NullStorage;

// In-memory storage - NO Redis/Database required
$config = (new SecurityConfig())
    ->setStorage(new NullStorage());

$security = new SecurityMiddleware($config);

if (!$security->handle($_SERVER)) {
    http_response_code(403);
    exit('Access Denied');
}

Note: NullStorage loses data between requests. Use for testing only.

Option 2: Database Storage (Production without Redis)

<?php
use Senza1dio\SecurityShield\Storage\DatabaseStorage;

// Use your existing database - NO Redis required
$pdo = new PDO('mysql:host=localhost;dbname=app', 'user', 'pass');

$config = (new SecurityConfig())
    ->setStorage(new DatabaseStorage($pdo));

$security = new SecurityMiddleware($config);

if (!$security->handle($_SERVER)) {
    http_response_code(403);
    exit('Access Denied');
}

Option 3: Redis Storage (Recommended for Production)

<?php
use Senza1dio\SecurityShield\Storage\RedisStorage;

// Fastest option - requires ext-redis
$redis = new Redis();
$redis->connect('127.0.0.1', 6379);

$config = (new SecurityConfig())
    ->setStorage(new RedisStorage($redis));

$security = new SecurityMiddleware($config);

if (!$security->handle($_SERVER)) {
    http_response_code(403);
    exit('Access Denied');
}

Usage Examples

Circuit Breaker

use Senza1dio\SecurityShield\Resilience\CircuitBreaker;

$breaker = new CircuitBreaker('redis', $storage, [
    'failure_threshold' => 5,    // Open after 5 failures
    'recovery_timeout' => 30,    // Try again after 30s
    'half_open_max_calls' => 3,  // Allow 3 test calls
]);

// State logged to error_log on transitions
$result = $breaker->call(
    fn() => $redis->get('key'),
    fn() => 'fallback-value'
);

Limitation: In PHP-FPM, each worker has independent in-memory state if Redis unavailable.

Retry Policy

use Senza1dio\SecurityShield\Resilience\RetryPolicy;

$policy = RetryPolicy::exponentialBackoffWithJitter(
    maxAttempts: 5,
    baseDelay: 1.0,
    maxDelay: 30.0
);

// Delays: ~1s, ~2s, ~4s, ~8s (with random jitter)
$result = $policy->execute(fn() => $api->call());

Rate Limiting

use Senza1dio\SecurityShield\RateLimiting\RateLimiter;

// Token bucket: 100 tokens, refills 10/second
$limiter = RateLimiter::tokenBucket($storage, 100, 10);

$result = $limiter->attempt('user:123');
if (!$result->allowed) {
    // $result->retryAfter contains seconds to wait
    http_response_code(429);
    exit;
}

Health Checks

use Senza1dio\SecurityShield\Health\HealthCheck;
use Senza1dio\SecurityShield\Health\Checks\RedisHealthCheck;

$health = new HealthCheck();
$health->addCheck('redis', new RedisHealthCheck($redis));

// Returns HealthResult with HTTP status code
$result = $health->readiness();

header('Content-Type: application/json');
http_response_code($result->getHttpStatusCode());
echo $result->toJson();

Distributed Tracing

use Senza1dio\SecurityShield\Telemetry\Tracer;
use Senza1dio\SecurityShield\Telemetry\SpanKind;

$tracer = new Tracer('my-service', '1.0.0');

// Extract parent context from incoming request
$parentContext = $tracer->extractContext(getallheaders());

$span = $tracer->startSpanFromContext('handle-request', $parentContext, SpanKind::SERVER);
$span->setAttribute('http.method', $_SERVER['REQUEST_METHOD']);

// ... process request ...

$span->setStatus(SpanStatus::OK);
$tracer->endSpan($span);
$tracer->flush(); // Export spans

Hot-Reload Configuration

use Senza1dio\SecurityShield\Config\ConfigProvider;

$config = new ConfigProvider($storage, [
    'cache_ttl' => 60,  // Reload from Redis every 60s
]);

$config->setDefaults(['threshold' => 50]);

// Update from anywhere - all instances pick up changes
$config->setRemote('threshold', 100);

// Later reads get new value after cache expires
$value = $config->get('threshold'); // 100

Note: Changes propagate on cache expiry, not instantly.

Notifications

use Senza1dio\SecurityShield\Notifications\NotificationManager;
use Senza1dio\SecurityShield\Notifications\TelegramNotifier;
use Senza1dio\SecurityShield\Notifications\SlackNotifier;

$manager = new NotificationManager();
$manager->addChannel(new TelegramNotifier($botToken, $chatId));
$manager->addChannel(new SlackNotifier($webhookUrl));

// Send to all channels
$result = $manager->broadcast('Security Alert', 'IP banned: 1.2.3.4', [
    'reason' => 'Honeypot access',
]);

// Check results
if (!$result->allSuccessful()) {
    foreach ($result->getErrors() as $channel => $error) {
        error_log("Notification to {$channel} failed: {$error}");
    }
}

Configuration Validation

use Senza1dio\SecurityShield\Config\ConfigValidator;

$validator = ConfigValidator::create()
    ->required()
    ->type('integer')
    ->min(1)
    ->max(1000);

$result = $validator->validate($value);
if (!$result->valid) {
    throw new InvalidArgumentException($result->error);
}

Requirements

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

Optional Extensions

• ext-redis (for RedisStorage - recommended for production)
• ext-pdo (for DatabaseStorage)
• ext-curl (for notification channels, GeoIP)

Storage Backends

Choose the right storage for your use case:

When to Use Each Backend

NullStorage - Development/Testing Only

$config = (new SecurityConfig())->setStorage(new NullStorage());

• ✅ Zero setup, no dependencies
• ✅ Perfect for unit tests
• ❌ Data lost between requests
• ❌ NOT for production

DatabaseStorage - Production without Redis

$pdo = new PDO('mysql:host=localhost;dbname=app', 'user', 'pass');
$config = (new SecurityConfig())->setStorage(new DatabaseStorage($pdo));

• ✅ No extra infrastructure needed
• ✅ Uses existing database
• ✅ Persistent across servers
• ⚠️ Slower than Redis (1-5ms vs 0.05ms)

RedisStorage - Production (Best Performance)

$redis = new Redis();
$redis->connect('127.0.0.1', 6379);
$config = (new SecurityConfig())->setStorage(new RedisStorage($redis));

• ✅ Ultra-fast (~0.05ms)
• ✅ Distributed state across servers
• ✅ Built-in TTL expiration
• ⚠️ Requires Redis server

Known Limitations

1. No Persistence in NullStorage - Data lost between requests
2. Clock Skew - Rate limiting assumes synchronized clocks
3. Memory Growth - Tracer spans queue in memory until flush
4. Blocking Operations - SMTP notifications block during send
5. No Clustering - Each PHP worker has independent memory state

Error Handling

All network operations log errors to error_log():

• SMTP failures
• Webhook failures
• Redis connection issues
• Circuit breaker state changes

Configure PHP error_log to capture these in production.

Testing

composer install
composer test          # PHPUnit tests
composer stan          # PHPStan level 8
composer cs-check      # Code style check

License

MIT License - see LICENSE