Configuración

FR Guard funciona bien sin tocar nada después de instalarlo. Pero si quieres ajustar la seguridad a las necesidades exactas de tu servidor, aquí tienes todas las opciones explicadas.

Hay dos niveles de configuración:

1. Variables de server.cfg — lo básico: token, idioma, fail-open, métricas.
2. config.lua — comportamiento avanzado: detectores, umbrales, whitelist de staff, etc.

---

1 · Variables de server.cfg

fiverank_token (obligatorio)

Tu API Key. Sin esto FR Guard no arranca.

set fiverank_token "frk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

fiverank_language — Idioma

Idioma de las tarjetas de conexión y mensajes al staff.

set fiverank_language "es"   # es | en | pt | fr | de

Por defecto es. Ver Idiomas para personalizar textos.

fiverank_fail_open — Si FiveRank cae

set fiverank_fail_open "1"

• "1" (recomendado) — Tu servidor sigue funcionando aunque fiverank.gg no responda. Pierdes protección solo mientras dure el incidente.
• "0" — Sin API, nadie entra. Solo para servidores ultra-estrictos.

fiverank_debug — Logs detallados

set fiverank_debug "0"

• "0" — solo logs importantes (por defecto).
• "1" — logs de cada chequeo. Actívalo solo para diagnosticar un problema.

fiverank_metrics — Contador de jugadores en vivo

Envía cada 30 s el número de jugadores online. Con esto activado tu ficha pública muestra:

• Contador en vivo (42 / 64) con punto verde animado.
• Gráfica de las últimas 24 h con media, máximos y mínimos.
• Picos del día, semana e histórico.
• Uptime % estimado de tu servidor.

set fiverank_metrics "1"   # recomendado

Solo envía el número de jugadores y slots. Nunca envía nombres, IDs ni IPs.

fiverank_presence — Following Activity

Adjunta la lista de identificadores Discord/license/steam al heartbeat para que los jugadores puedan ver "amigos jugando ahora" en sus perfiles de FiveRank.

set fiverank_presence "1"   # por defecto activo

Ver Following Activity para el detalle de privacidad.

fiverank_staff_discord_ids — Staff extra exento

Discord IDs adicionales que nunca generan detecciones aunque no tengan ACE ni estén en grupos admin del framework. Útil si tu staff no usa permisos tradicionales.

set fiverank_staff_discord_ids "506000000000000021,123000000000000045"

También configurable en config.lua → Config.Detections.staffDiscordIds.

---

2 · Config.Behavior — Comportamiento del core

Edita resources/fiverank_guard/config.lua. Todos los cambios requieren restart fiverank_guard.

failOpenNoDiscord — Jugadores sin Discord

Config.Behavior.failOpenNoDiscord = false  -- recomendado

• false (recomendado) — Sin Discord vinculado, no entran. Es la única forma de identificar al jugador y evitar que un cheater evite el sistema cerrando Discord.
• true — Se dejan pasar sin chequeo. No recomendado en servidores serios.

requireFiveRankAccount — Obligar cuenta FiveRank

Solo admite jugadores cuyo Discord esté vinculado a una cuenta en fiverank.gg.

Config.Behavior.requireFiveRankAccount = false  -- por defecto

• false (por defecto) — Cualquier jugador con buena reputación entra.
• true — Solo entran usuarios con cuenta FiveRank. Los demás ven la razón y un enlace de registro.

requireWhitelist — Obligar whitelist aprobada (v1.9+)

Exige que el jugador esté en la whitelist aprobada del servidor para poder entrar. Es la opción más restrictiva: solo acceden jugadores que hayas aceptado tú o tu staff a través del módulo de Whitelist de FiveRank.

Config.Behavior.requireWhitelist = false  -- por defecto

• false (por defecto) — La whitelist no se usa como puerta de entrada. El jugador entra si pasa fama y no tiene ban.
• true — El jugador solo entra si:
  1. Tiene una solicitud aprobada en la whitelist del servidor, O
  2. Ha sido pre-aprobado manualmente por el staff desde el panel (WhitelistAllowedUser), Y
  3. No tiene un veto activo (el veto siempre prevalece).

Orden de chequeo con requireWhitelist = true:

Jugador se conecta
  ├─ 1. ¿Baneado en el servidor? → KICK (ban prevalece siempre)
  ├─ 2. ¿Tiene cuenta FiveRank? → Si NO tiene: KICK
  ├─ 3. ¿Está en la whitelist aprobada? → Si NO: KICK
  ├─ 4. ¿Fama negativa? → Si SÍ: comprueba allowlist del Guard
  └─ 5. Resultado final: ALLOW o KICK por fama

Combinación recomendada para servidores RP serios

Config.Behavior.requireFiveRankAccount = true
Config.Behavior.requireWhitelist       = true
Config.Behavior.failOpenNoDiscord      = false

Con estas tres opciones, tu servidor es una fortaleza: solo entran jugadores verificados, whitelisted y con buena reputación.

El toggle vive aquí, no en el panel web

La decisión de exigir whitelist es local de cada servidor (config.lua). El backend solo informa si el jugador está aprobado o no — la puerta la cierras tú.

Respuesta de la API cuando requireWhitelist = true:

El endpoint /api/guard/check devuelve un objeto whitelist junto con el resultado habitual:

{
  "allowed": true,
  "reason": "ok",
  "code": "OK",
  "hasAccount": true,
  "whitelist": {
    "approved": true,
    "status": "approved"
  }
}

Valores posibles de whitelist.status:

Status	Significado
approved	Solicitud aprobada por el staff
allowed	Pre-aprobado manualmente (sin formulario)
pending	Solicitud enviada, pendiente de revisión
rejected	Solicitud rechazada
vetoed	Veto permanente del servidor
none	No tiene solicitud ni está pre-aprobado

FR Guard solo permite la entrada si whitelist.approved == true.

banSweepMinutes — Sweep de bans en vivo

Cada N minutos FR Guard comprueba la lista de bans activos del panel web y kickea a los jugadores que estén conectados y baneados. Esto hace que un ban creado desde el panel web surta efecto inmediato sin esperar a que reconecten.

Config.Behavior.banSweepMinutes = 3   -- recomendado 2-5

0 = desactivado.

cacheTtlMinutes — Caché de chequeos

Config.Behavior.cacheTtlMinutes = 5

FR Guard recuerda durante N minutos si un jugador puede entrar. Reduce peticiones a la API. No tocar normalmente.

panelKey — Tecla para /fivepanel

Config.Behavior.panelKey = 'F6'

Tecla que abre el panel staff in-game. Acepta F1..F12, INSERT, HOME, PAGEUP, letras, etc. El jugador puede reasignarla en FiveM → Ajustes → Controles → "FiveRank Guard".

allowStaffMovementActions — Acciones in-game del staff

Config.Behavior.allowStaffMovementActions = true

• true (por defecto) — El staff puede usar Espectar, Ir a, Traer, Revivir, Curar y Congelar desde las tarjetas de jugador.
• false — Solo moderación clásica (Kick, Ban). Ideal para servidores roleplay estrictos.

bannerEnabled — Banner de consola

Config.Behavior.bannerEnabled = true

Imprime el logo ASCII coloreado al arrancar. Pon false si tu consola no soporta ANSI 256.

---

3 · Config.Detections — Detectores automáticos

Los detectores observan el comportamiento de los jugadores mientras están conectados. Todos arrancan en modo shadow para que veas qué detecta en tu servidor antes de activarlos.

Interruptor maestro

Config.Detections.allowAutoKick = false

Si está en false, ningún detector realiza kick aunque su modo sea 'active'. Solo se generan flags en el panel. Actívalo a true cuando hayas calibrado los detectores y confíes en sus resultados.

Modos de cada detector

Modo	Comportamiento
'off'	Desactivado. No se ejecuta.
'shadow'	Observa y registra en el panel. Sin acciones. (recomendado para empezar)
'active'	Actúa (kick si procede) según la política del detector.

Exención de staff

Config.Detections.exemptStaff = true

Si true, el staff del framework (ACE fiverank.admin, grupos admin de ESX/QBCore) nunca genera flags. El staff suele usar noclip, god mode y spawnear vehículos legítimamente — sin esto generarías falsos positivos masivos sobre tus propios admins.

Config.Detections.exemptStaffMode = 'silent'  -- 'silent' | 'log'

• 'silent' — descarta sin dejar rastro.
• 'log' — descarta pero deja entrada debug en consola.

Whitelist de Discord

Config.Detections.whitelistDiscord = {
  -- ['123456789012345678'] = true,  -- tu Discord ID de testing
}

Estos jugadores nunca generan flags, independientemente del framework.

Cooldown anti-spam de flags

Config.Detections.flagCooldownSeconds = 60

Tras un flag de un jugador + categoría, se ignoran nuevos del mismo tipo durante N segundos. Evita inundar el panel ante un patrón sostenido.

---

Detector: Event Spam

Detecta flood de TriggerServerEvent en ventana corta — patrón típico de cheat menus.

Config.Detections.eventSpam = {
  mode               = 'shadow',
  windowSeconds      = 10,
  maxEventsPerWindow = 200,
  severityWarn       = 200,
  severitySusp       = 400,
  severityCritical   = 800,
  ignoredEventPrefixes = { 'esx:', 'esx_', 'QBCore:', 'qb-', 'ox_', 'ox:', 'fiverank_guard:', ... },
}

Los prefijos del framework (esx:, QBCore:, ox_, etc.) están excluidos automáticamente para evitar falsos positivos en servidores con scripts activos.

---

Detector: Entity Spawn

Detecta spawn de vehículos militares, jets de combate y entidades blacklistadas.

Config.Detections.entitySpawn = {
  mode      = 'shadow',
  cooldownSeconds = 5,
  blacklist = {
    'lazer', 'hydra', 'b11', 'besra', 'starling',
    'rhino', 'khanjali', 'apc', 'halftrack', 'insurgent3',
    'akula', 'savage', 'hunter', 'annihilator', 'valkyrie',
    'a_c_shark', 'a_c_killerwhale', 'a_c_humpback',
  },
}

En modo 'active' cancela la creación de la entidad con CancelEvent(). Amplía el blacklist con los modelos que quieras prohibir en tu servidor.

---

Detector: Explosion

Detecta rate abusivo de explosiones y tipos de explosión no permitidos.

Config.Detections.explosion = {
  mode              = 'shadow',
  rateWindowSeconds = 10,
  rateMaxPerWindow  = 6,
  whitelistTypes    = { [2]=true, [3]=true, [5]=true, [9]=true, ... },
}

Dos reglas independientes:

1. Whitelist de tipos — cualquier tipo no listado en whitelistTypes genera flag.
2. Rate-limit — más de 6 explosiones en 10 segundos genera flag.

---

Detector: Weapon Mod

Detecta daño de arma modificado (multiplicadores, damage hack).

Config.Detections.weaponMod = {
  mode              = 'shadow',
  anomaliesNeeded   = 3,
  anomalyWindowSec  = 20,
  factor            = 3.0,
  minDamageEvaluated = 50,
  ignoredWeapons    = {},
}

Requiere 3 anomalías en 20 segundos antes de flag (histéresis). Solo evalúa daños > 50 HP. El factor define el multiplicador mínimo sobre el daño esperado para considerar anomalía.

---

Detector: God Mode

Detecta HP + Armor intactos tras daño real confirmado por el servidor.

Config.Detections.godMode = {
  mode             = 'shadow',
  sampleIntervalMs = 1500,
  requiredAnomalies = 3,
  minExpectedDamage = 10,
}

Solo evalúa durante la ventana inmediata tras un weaponDamageEvent. Requiere 3 muestras consecutivas sin bajar HP + Armor. Diseñado para no falsear con scripts médicos o chaleco.

---

Detector: Movement (Noclip / Teleport / Superspeed)

Detecta movimiento imposible por polling de coordenadas server-side.

Config.Detections.movement = {
  mode            = 'shadow',
  sampleSeconds   = 2,
  onFootMaxMps    = 30,      -- ~108 km/h
  vehicleMaxMps   = 90,      -- ~324 km/h
  teleportMeters  = 120,
  anomaliesNeeded = 3,
  flagCooldownSec = 60,
  defaultGraceMs  = 5000,
}

Cubre tres casos: noclip (velocidad a pie imposible), teleport (salto > 120 m entre 2 muestras) y superspeed (velocidad en vehículo sostenida > 90 m/s).

Integración con tus scripts: si tienes un script que teletransporta al jugador legítimamente (revivir, salas, misiones), llama al export para evitar falsos positivos:

exports.fiverank_guard:setMovementGrace(source, 5000)  -- 5 s de gracia

---

Detector: VPN / Proxy

Consulta proxycheck.io con la IP del jugador en playerConnecting.

Config.Detections.vpn = {
  mode             = 'shadow',
  apiKey           = '',        -- opcional, sube el límite diario
  cacheTtlSeconds  = 3600,
  requestTimeoutMs = 1500,
  whitelistIps = {
    ['127.0.0.1'] = true,
    ['localhost']  = true,
  },
}

En modo 'active' rechaza la conexión. Añade IPs de staff a whitelistIps para evitar falsos positivos con VPNs de trabajo o gaming.

---

Detector: Unknown Event

Detecta eventos de red con namespace desconocido — firma típica de cheat menus que usan prefijos propios (lambda_menu:*, evilmenu:*, etc.).

Config.Detections.unknownEvent = {
  mode               = 'shadow',   -- no tiene modo 'active' por seguridad
  cooldownSeconds    = 300,
  extraKnownPrefixes = {},
  extraKnownNames    = {},
}

Hereda los prefijos ignorados de eventSpam. Amplía extraKnownPrefixes con los namespaces de tus propios scripts custom para evitar falsos positivos.

Severity fijo 'warn'. Nunca kickea por sí mismo — es solo informativo.

---

4 · Config.Frameworks — Grupos admin

Define qué grupos del framework se consideran admin para permisos del panel y exención de detectores.

Config.Frameworks = {
  esx    = { resource = 'es_extended', adminGroups = { 'admin', 'superadmin', 'mod' } },
  qbcore = { resource = 'qb-core',     adminGroups = { 'admin', 'god' } },
}

FR Guard detecta el framework automáticamente. Si estás en standalone, los permisos se gestionan vía ACE fiverank.admin.

---

Cambiar tu token

Si crees que tu token se ha filtrado:

1. Ve a Panel → FR Guard → Revocar la key actual.
2. Genera una nueva.
3. Actualiza set fiverank_token en server.cfg.
4. Reinicia: restart fiverank_guard.

Nunca compartas tu token

No subas tu server.cfg con el token a GitHub, Pastebin ni Discord público. Cada token es único por servidor.