121 lines
3.0 KiB
Markdown
121 lines
3.0 KiB
Markdown
# Koneko Security Logger Helper Guide
|
|
|
|
> ⚖️ Auditoría de eventos de seguridad en tiempo real y bajo demanda.
|
|
|
|
El logger `log_security()` forma parte de la infraestructura central de seguridad de Koneko Vuexy Admin y te permite registrar eventos sensibles como accesos, fallos de login, intentos sospechosos, detecciones de VPN, entre otros.
|
|
|
|
---
|
|
|
|
## ✨ Ventajas
|
|
|
|
* No requiere instanciar clases.
|
|
* Autoobtiene `Request`, `IP`, `UserAgent`, `Geolocalización`, etc.
|
|
* Flexible para ejecutarse desde controladores, middleware, jobs o Livewire.
|
|
* Compatible con `SecurityEvent` (modelo auditado).
|
|
* Almacena contexto extendido con `payload`, `is_proxy`, `user_id`, etc.
|
|
|
|
---
|
|
|
|
## ✨ Uso básico
|
|
|
|
```php
|
|
log_security('login_failed');
|
|
```
|
|
|
|
Esto registra un fallo de login con todos los metadatos de seguridad: IP, ciudad, dispositivo, agente, URL y más.
|
|
|
|
---
|
|
|
|
## ⚖️ Sintaxis Completa
|
|
|
|
```php
|
|
log_security(
|
|
string $type, // Tipo de evento (ej: login_failed, login_success)
|
|
?Request $request = null, // Puede inyectarse manualmente
|
|
?int $userId = null, // Usuario relacionado (opcional)
|
|
array $payload = [], // Datos adicionales como intentos, cabeceras, etc.
|
|
bool $isProxy = false // ¿Fue detectado uso de proxy/VPN?
|
|
);
|
|
```
|
|
|
|
Ejemplo completo:
|
|
|
|
```php
|
|
log_security(
|
|
'login_failed',
|
|
request(),
|
|
$user?->id,
|
|
['intentos' => 3, 'via' => 'formulario'],
|
|
detectaVpnProxy(request()->ip())
|
|
);
|
|
```
|
|
|
|
---
|
|
|
|
## 🔍 Eventos soportados por defecto
|
|
|
|
Puedes definirlos como constantes estáticas en tu código:
|
|
|
|
```php
|
|
SecurityEvent::EVENT_LOGIN_FAILED
|
|
SecurityEvent::EVENT_LOGIN_SUCCESS
|
|
```
|
|
|
|
O usar strings arbitrarios con sentido:
|
|
|
|
```php
|
|
'password_reset_attempt'
|
|
'blocked_login_from_blacklist'
|
|
'csrf_token_fail'
|
|
'geolocation_warning'
|
|
```
|
|
|
|
---
|
|
|
|
## ⌚ Modelo generado: `SecurityEvent`
|
|
|
|
El evento registrado se almacena en la tabla `security_events`, con campos como:
|
|
|
|
* `ip_address`
|
|
* `user_id`
|
|
* `event_type`
|
|
* `payload`
|
|
* `region`, `city`, `country`
|
|
* `is_proxy`, `device_type`, etc.
|
|
|
|
---
|
|
|
|
## 🌐 Geolocalización Automática
|
|
|
|
Si tienes habilitado el trait `HasGeolocation`, el sistema hace *GeoIP Lookup* por IP:
|
|
|
|
```php
|
|
use Koneko\VuexyAdmin\Support\Traits\Helpers\HasGeolocation;
|
|
```
|
|
|
|
---
|
|
|
|
## 🔐 Buenas prácticas
|
|
|
|
* Usa tipos semánticos: `login_success`, `vpn_blocked`, `csrf_fail`, etc.
|
|
* Agrega contexto extra en `payload` para debugging posterior.
|
|
* Detecta IPs sospechosas con `isProxy` (ideal para usar junto con sistemas de listas negras).
|
|
|
|
---
|
|
|
|
## ✨ Extras
|
|
|
|
Puedes extender la lógica de logging desde:
|
|
|
|
```php
|
|
Koneko\VuexyAdmin\Support\Logger\KonekoSecurityLogger
|
|
```
|
|
|
|
Este servicio puede adaptarse o sustituirse por otro para logs distribuidos o externos (ej: Sentry, Elastic, etc).
|
|
|
|
---
|
|
|
|
## ✅ Conclusión
|
|
|
|
El helper `log_security()` es una herramienta robusta, flexible y elegante para capturar eventos sensibles en tu ERP. Evita trabajar directamente con el modelo, mantén la consistencia de tu registro, y delega la trazabilidad a una capa preparada para el contexto empresarial.
|