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

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

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:

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:

SecurityEvent::EVENT_LOGIN_FAILED
SecurityEvent::EVENT_LOGIN_SUCCESS

O usar strings arbitrarios con sentido:

'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:

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:

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.

3.0 KiB Raw Blame History