Maatify Security Guard

PSR-compliant adaptive security engine for brute-force protection, abuse detection, security event tracking, high-level login-flow logic, and real-time blocking — powered by unified multi-driver architecture (MySQL, Redis, MongoDB).

---

---

🚀 Overview

Maatify Security Guard is a fully decoupled, high-performance, multi-driver security engine for:

• Brute-force attack protection
• Credential stuffing detection
• IP reputation & abuse control
• Distributed attack throttling
• Audit-grade event tracking (Phase 4)
• High-level login-flow decisions + auto-blocking (Phase 5)

The engine integrates seamlessly with:

• Native PHP
• Slim Framework
• Laravel
• Custom API Gateways
• Microservices

All storage is abstracted via:

• maatify/data-adapters → Real MySQL / Redis / MongoDB
• maatify/data-fakes → Deterministic testing engine

The library guarantees:

✔ Zero vendor lock ✔ Zero direct database clients ✔ Perfect testability ✔ Real–fake execution symmetry

---

📘 Full technical documentation: ➡️ docs/README.full.md

---

🆕 What’s New (Phase 3, 4 & 5 Completed)

🔥 Phase 3 — Drivers Layer Completed

• MySQLSecurityGuard
• RedisSecurityGuard
• MongoSecurityGuard

Each driver operates strictly through the unified AdapterInterface.

---

🔥 Phase 4 — Unified Event System Completed

• SecurityEventDTO
• EventFactory
• Extensible Actions/Platforms
• Null / Sync / PSR Logger Dispatchers
• Automatic event emission from service

---

🔥 Phase 5 — High-Level Logic & Auto-Blocking Engine

Security Guard now includes built-in login-flow intelligence:

• handleAttempt() API
• Automatic blocking after threshold
• Automatic reset on success
• Remaining block time reporting
• Runtime SecurityConfig
• Dispatching event metadata for all decisions
• Ready for future analytics layers

---

📦 Installation

composer require maatify/security-guard

---

⚡ Quick Usage

1️⃣ Initialize the Service

$svc = new SecurityGuardService($adapter, $identifier);

---

2️⃣ High-Level Login Flow (Phase 5)

$result = $svc->handleAttempt($dto, success: false);

if ($result === null) {
    echo "Login successful — attempts reset.";
} elseif (is_int($result)) {
    echo "Failure count = {$result}";
} else {
    echo "User blocked — remaining {$result} seconds.";
}

---

3️⃣ Manual failed login attempt (legacy Phase 4 style)

$count = $svc->recordFailure($dto);

---

4️⃣ Attach an Event Dispatcher

$svc->setEventDispatcher(
    new SyncDispatcher([
        fn(SecurityEventDTO $e) => error_log("SECURITY EVENT: " . json_encode($e)),
    ])
);

---

4️⃣ Create a manual block

$svc->block(
    new SecurityBlockDTO(
        ip: '192.168.1.10',
        subject: 'user@example.com',
        type: BlockTypeEnum::MANUAL,
        expiresAt: time() + 3600,
        createdAt: time()
    )
);

---

6️⃣ Emit a custom security event

$event = SecurityEventFactory::custom(
    action: SecurityAction::custom('password_reset'),
    platform: SecurityPlatform::custom('api'),
    ip: '192.168.1.10',
    subject: 'user@example.com',
    context: ['method' => 'email']
);

$svc->handleEvent($event);

---

🧩 Key Features

✔ Core Security Engine

• Adaptive brute-force handling
• Distributed blocking system
• Manual & automatic block control

✔ Unified DTO Layer

• LoginAttemptDTO
• SecurityBlockDTO
• SecurityEventDTO

✔ Unified Drivers (Phase 3)

• MySQL
• Redis
• MongoDB

✔ Event Pipeline (Phase 4)

• Factory-based event normalization
• Pluggable dispatchers
• Extensible actions & platforms

✔ High-Level Logic (Phase 5)

• Auto-blocking
• Success reset
• Remaining block time
• Config-driven thresholds
• Decision-level event emission

✔ Testing-Ready

• Fake drivers through maatify/data-fakes
• 100% deterministic behavior

---

🧱 Architecture

Application
   ↓
SecurityGuardService (Phase 5 logic)
   ↓
SecurityEventFactory → Dispatchers
   ↓
SecurityGuard Drivers
   ↓
maatify/data-adapters | maatify/data-fakes

---

📄 Documentation

• 📘 Full Documentation — docs/README.full.md
• 🔬 Examples — examples/Examples.md
• 🧾 Changelog — CHANGELOG.md
• 🔐 Security Policy — SECURITY.md

---

📚 Development Roadmap & Phase Plan

✅ Completed Phases

• Phase 1 – Environment Setup
• Phase 2 – Core Architecture & DTOs
• Phase 3 – Driver Implementations (MySQL / Redis / MongoDB)
• Phase 4 – Unified Event System + Dispatchers
• Phase 5 – High-Level Logic & Auto-Blocking Engine

⏳ Upcoming

• Phase 6 – Audit System
• Phase 7–14 – Monitoring, Webhooks, SIEM

---

📅 Roadmap (Updated)

Phase	Description	Status
1	Environment Setup	✅ Completed
2	Core Architecture & DTOs	✅ Completed
3	Driver Implementations	✅ Completed
4	Event System & Dispatchers	✅ Completed
5	High-Level Logic & Auto-Blocking Engine	✅ Completed
6	Audit System	⏳ Pending
7–14	Monitoring, Webhooks, SIEM	⏳ Pending

---

🧪 Testing

composer test

---

🪪 License

MIT License © Maatify.dev

---

👤 Author

Developed by Mohamed Abdulalim https://www.maatify.dev

---

_{Built with ❤️ by Maatify.dev}