ZeroDev Sentinel docs

ZeroDev Sentinel: configuration reference

Build 0.1.2. Every key below is read from the files in config/, with the default that ships and the comment written next to it. The config files are open to you (not escrowed). Keep them valid Lua and restart zerodev_sentinel after a change.

For ZeroDev Sentinel 0.1.217 min readUpdated

A mode set with sentinel:mode is saved by Sentinel and wins over Config.Mode after a restart. sentinel:health shows where the current mode came from.

config/config.lua

This file is yours to edit. Keep it valid Lua and restart the resource after a change. sentinel:diag in the server console shows what Sentinel decided and why.

Config.Protection

Protection level. The owner desk (F7, OWNER) has the same switch; what is set there wins over this line. - watch: every rule watches and logs what it would have done; nobody is alerted, nothing acts. Use it for the first days of play so you can see what Sentinel finds on your server. - recommended: every rule is live: staff are alerted with the evidence and the case is opened. Sentinel never punishes on its own; your staff decide. - strict: as recommended, and proof-level findings (Tier A: a bait event fired, a forged request) quarantine the player automatically until staff look.

Default: 'watch'

Config.Locale

Language of everything players and staff read (refusals, notices, the staff console). The texts are in config/locales/.lua: ar bs cs da de en es fr hu it ja ko nb nl pl pt-BR pt-PT ro ru sl sv th tr uk zh-CN

Default: 'en'

Config.GameLanguage

  • true: a player whose game runs in a language GTA offers (French, German, Italian, Spanish, Portuguese, Polish, Russian, Korean, Japanese, Chinese) reads Sentinel in that language once in game; a game in English, and everyone at the connect door, gets Config.Locale
  • false: everyone gets Config.Locale

Default: true

Config.Notice

The recording notice: once per account, on the first join, a short memo in the player's language says that this server uses an anti-cheat that records play and that staff may watch and listen. false = no notice (tell players in your rules or your Discord instead; you still have to tell them).

Default: true

Config.Storage

Where bans, identities, settings and cases are kept. - auto: oxmysql when it is started, otherwise the resource's own key-value store - mysql: always oxmysql (Sentinel waits for it) - kvp: never use a database

Default: 'auto'

Config.WeakIdentifiers

Identifiers of these kinds are recorded but never used to refuse a connection. 'ip' is here by default: shared flats, cafes and mobile networks share addresses.

Default: { ip = true }

Config.TokenMatch

A connection that matches a banned account only by hardware token: - 'flag': let them in and alert staff (default; tokens can collide on shared PCs) - 'refuse': treat it like an identifier match

Default: 'flag'

Config.Ace

ACE permissions. Grant them in server.cfg, e.g. add_ace group.admin sentinel.admin allow

Key Default What it does
admin 'sentinel.admin' console commands, mode changes
staff 'sentinel.staff' staff members: movement rules treat their own movement as explained

Config.Scheduler

Key Default What it does
batchBudgetMs 0.8 per server tick, for audits, hashing, archives
realtimeBudgetMs 1.0 per server tick, for the recorder and event checks

Config.Recorder

Key Default What it does
hz 10 samples per second per player
groups 6 players are split into this many groups, one group per slot
seconds 120 length of the per-player ring
eventsPerPlayer 600 event track capacity per player
archiveRadius 300.0 metres around every involved player whose rings go into an archive
staleMs 1500 a player whose last message is older than this is not judged

Config.Detection

Key Default What it does
halfLifeMinutes 30 the suspicion score halves after this much clean play
escalateWindowMinutes 10 two families inside this window escalate a Tier B finding
escalateRepeats 3 or the same family this many times inside the window
reviewScore 40 Score at which a player is put up for review (a case and a recording in review and enforce mode).
restrictScore 70 Score at which a player is restricted (quarantined in enforce mode).

Config.Rules

Each rule follows the protection level. To pin one rule regardless of the level, give it a state here: - state: 'live' always judged and scored - state: 'shadow' always only logged (what it would have done) The owner desk shows every rule with its state and where that state comes from (level, desk or this file).

Key Default What it does
teleport.minDistance 150.0 metres in one sample gap
teleport.plausibleFactor 3.0 or this many times the plausible distance for the gap
teleport.footSpeed 12.0 m/s used for the plausible distance on foot
teleport.vehicleSpeed 110.0 m/s used in a vehicle (fast aircraft)
teleport.confirmSamples 2 the player has to stay at the destination this many samples
foot_speed.speed 12.0 m/s horizontal
foot_speed.seconds 1.5 How long the speed has to last before the rule fires.
foot_speed.minSamples 10 consecutive samples, so a lag burst cannot trigger it
foot_speed.fallingVz -2.5 m/s; faster descent than this counts as falling
foot_rise.speed 4.0 m/s straight up on foot (ladders about 1.2, stairs about 1.5)
foot_rise.seconds 3.0 for at least this long, and more up than along the ground

Config.Reasons

Key Default What it does
joinGraceMs 30000 movement right after joining is explained by spawning/loading
respawnGraceMs 10000 Movement right after a respawn is explained by the respawn.
bucketGraceMs 5000 Movement right after a routing bucket change is explained by the change.
scriptEventMs 3000 a 'moves_players' script event explains a jump this long after it
pairGrid 10.0 metres per cell for learned teleport pairs
pairPlayers 5 different players before a jump between two cells is trusted

Config.Bans

The ban refusal is ban.refused in config/locales, in each player's language. Write a text here to use it instead, the same in every language; keep the %s for the appeal code. Optional key, commented out in the file: message = 'You are banned from this server. Appeal code: %s'.

Default: {} (empty table)

Config.Retention

Evidence is kept: recorder archives and clips under data/ are never deleted by Sentinel, because an appeal can come months later. Remove old files yourself when you are sure no case needs them.

Default: {}

config/protection.lua

World rules, actions, Discord alerts and the hardening advisor. This file is yours to edit, like config.lua. Every rule here follows the protection level (config.lua Config.Protection, or the owner desk); a state line pins one.

Entities

Config.World

Key Default What it does
blockedModels { 'p_spinning_anus_s', 'prop_windmill_01', 'prop_ld_ferris_wheel', 'stt_prop_stunt_soccer_ball', } Models nobody on this server may create from a client, whatever population type the client claims. Names or hashes. In enforce mode, with the entity_blocked rule set to 'live', creation is cancelled (the entity is deleted at once). Only list models the game never creates on its own.
scriptPopulations { 7 } Population types counted as "created by a script". Spike S4: a client-script vehicle arrived as 7, traffic and pedestrians as 4 and 5.
untrustedTypes { 1, 2 } Entity types checked by entity_untrusted: 1 = ped, 2 = vehicle, 3 = object. Objects are off by default because emote and phone props are networked objects created by client scripts.
maxReach 600.0 Anything a client creates or sets off farther than this from its own player is out of its reach in normal play (OneSync culls at 424 m).
Key Default What it does
Config.Rules.entity_blocked {} Rule settings: state 'shadow' or 'live'; the other keys are described under Detection rules.

Config.Rules.entity_rate

Key Default What it does
defaultPerMinute 20 script entities per player per minute, until the server has learned its own normal
minPerMinute 8 the learned limit never goes below this
maxPerMinute 80 or above this
factor 3.0 learned limit = factor x the 99th percentile of clean player-minutes
minWindows 300 clean player-minutes needed before the learned limit is used

Config.Rules.entity_model_rate

Key Default What it does
defaultPerMinute 10 the same model per player per minute, until learned
minPerMinute 5 The learned limit never goes below this.
factor 3.0 learned limit = factor x the most of that model seen in one clean minute
minWindows 20 Clean minutes with that model needed before the learned limit is used.
Key Default What it does
Config.Rules.entity_untrusted { cooldownSeconds = 60 } Rule settings: state 'shadow' or 'live'; the other keys are described under Detection rules.

Explosions, fires, projectiles, particles

Config.Rules.explosion_weapon

Key Default What it does
heldSeconds 15 a weapon seen in the player's hands this recently counts as held
placedSeconds 600 sticky bombs, mines and pipe bombs are set off long after they were placed

Config.Rules.explosion_rate

Key Default What it does
windowSeconds 10 Length of the counting window.
weaponLimit 12 explosions from weapons and scripts in the window
worldLimit 30 cars, pumps, barrels and other world explosions in the window
Key Default What it does
Config.Rules.explosion_hidden {} Rule settings: state 'shadow' or 'live'; the other keys are described under Detection rules.
Config.Rules.fire_rate { windowSeconds = 10, limit = 60 } Rule settings: state 'shadow' or 'live'; the other keys are described under Detection rules.

Config.Rules.projectile_weapon

Key Default What it does
heldSeconds 3 A weapon seen in the player's hands this recently counts as held.
originFoot 25.0 metres between the shooter and the projectile's start, on foot
originVehicle 60.0 in a vehicle
Key Default What it does
Config.Rules.projectile_rate { windowSeconds = 5, limit = 8 } Rule settings: state 'shadow' or 'live'; the other keys are described under Detection rules.
Config.Rules.ptfx_rate { windowSeconds = 10, limit = 40, maxScale = 5.0 } Rule settings: state 'shadow' or 'live'; the other keys are described under Detection rules.
Config.Rules.world_distance {} Rule settings: state 'shadow' or 'live'; the other keys are described under Detection rules.

What Sentinel does with a decision (only in review and enforce mode)

Config.Actions

Key Default What it does
recordSeconds 120 a review keeps the recording hooks open this long after the last signal
quarantine true 'restrict' moves the player into a private routing bucket
quarantineBucketBase 777000 quarantine bucket = this + server id; pick a range no other script uses
quarantineOnProof true a Tier A finding in enforce mode quarantines at once, before the ban wave
waveMinHours 2 Tier A bans are released at a random time in this range
waveMaxHours 24 Upper end of the random ban wave delay.
waveImmediate false true = ban at once instead of in a wave
banSeconds 0 0 = permanent

Config.Webhook

Discord alerts. The webhook URL never goes in this file: put it in server.cfg as a server-only convar set sentinel_webhook "https://discord.com/api/webhooks/..." (set, never setr: setr sends the value to every client), or type sentinel:webhook set <url> in the console.

Key Default What it does
caseOpened true Post when a case opens.
banQueued true Post when a ban is queued for the wave.
banApplied true Post when a ban is applied.
auditCritical true Post the critical findings of sentinel:audit.
username 'ZeroDev Sentinel' Name the alerts are posted under.

Config.Advisor

The advisor prints its section after the startup box. false = only on sentinel:advisor.

Default: { atStartup = true }

config/watch.lua

Watchers: script scanner, file integrity, join shield, account age, staff record. This file is yours to edit. Keep it valid Lua and restart Sentinel after a change.

Script scanner (sentinel:scan)

Config.Scan

Reads every readable Lua and JS file of every started resource and looks for behaviour that backdoors use. It reads code; it does not run it. Escrowed files are encrypted and listed as "encrypted, not scanned".

Key Default What it does
onStart true scan everything once, 60 s after Sentinel starts
onResourceStart true scan a resource again when it is (re)started
maxFileKb 1536 larger files are listed as "too large to scan" (they still get integrity hashes)
discord true post dangerous and suspicious results through the Sentinel webhook

File integrity (sentinel:integrity)

Config.Integrity

A SHA-256 of every file of every started resource, taken the first time Sentinel sees the resource, compared on every start. After you update a script yourself, accept it: sentinel:integrity accept

Key Default What it does
enabled true false = no integrity hashing.
keepCopyKb 512 readable files up to this size are kept in data/integrity/copies for diffs
dataExtensions { 'json', 'txt', 'log', 'db', 'sqlite', 'csv', 'dat', 'bak', 'tmp', 'cache' } Files that scripts rewrite themselves while running. Their changes are listed, never alerted, and the stored hash follows them.
dataFolders { 'data', 'cache', 'logs', 'log', 'saves', 'db', 'database', 'storage' } Folders whose files scripts rewrite themselves; treated like dataExtensions.
discord true Post changed files through the webhook.

Join shield

Config.Shield

Limits connection attempts inside playerConnecting. It protects the join process from scripted reconnect floods; it cannot stop network floods: those need the host's own DDoS filtering in front of the server.

Key Default What it does
enabled true false = no join limits.
perIp { attempts = 4, seconds = 30 } attempts from one address inside the window
minGapSeconds 3 between two attempts from the same address
globalPerSecond 12 attempts from everyone together
knownFirst true Under load (global limit hit), players this server already knows get in first; new accounts wait.
knownSessions 2 sessions on this server before an account counts as known
loadSeconds 20 how long "under load" lasts after the last time the limit was hit

Account age

Config.AccountAge

When a player runs Discord, FiveM gives the server their Discord user id. That id encodes the day the Discord account was made, so Sentinel can tell a 2-day-old account from a 6-year-old one. Players without Discord running have no Discord id; requireDiscord decides what happens to them.

Key Default What it does
requireDiscord false true = refuse players who have no Discord id
minDays 0 refuse Discord accounts younger than this many days (0 = never refuse)
lowTrustDays 30 younger accounts start with a small suspicion score (rule young_account)
Key Default What it does
Config.Rules.young_account {} follows the protection level; state = 'shadow' keeps the starting score out

Staff record

Config.Staff

Staff actions are recorded like everyone else's and summarised for the owner once a week in data/reports/. Nothing here punishes staff. Staff = anyone with a Sentinel role (the owner's staff list, or Config.Ace.staff / Config.Ace.admin). txAdmin admins are not recognised as staff by themselves.

Key Default What it does
weeklyReport true Write the weekly staff report to data/reports/.
combatSeconds 15 "in combat" = shot, hit or was hit by someone within this many seconds
nearPlayersMetres 80.0 ... or held a weapon with a non-staff player this close
teleportToMetres 12.0 a staff teleport that lands this close to another player is a "teleport to player"
keepDays 35 Days staff record entries are kept.

Detection rules

Every rule follows the protection level (Config.Protection, or the switch on the owner desk): on Watch it only logs what it would have done, on Recommended and Strict it is live. To pin one rule whatever the level, give it a state in a config file, for example Config.Rules.teleport = { state = 'shadow' }, or for a rule that is not in the files:

Lua
Config.Rules.damage_plausibility = { state = 'shadow' }

Put such lines at the end of config/protection.lua and restart. What a live rule's score leads to depends on the protection level: on Watch only a log line; on Recommended a case and a recording, never a punishment; on Strict a score over Config.Detection.restrictScore quarantines the player and a Tier A finding also queues a ban for the wave (see Config.Actions). Tier A = proof-level, Tier B = strong signal, Tier C = weak signal that only adds to the score. The settings column shows the defaults written in the code; a key you add under Config.Rules.<rule> replaces that default.

Rule Family Tier In a config file Settings and code defaults
aim_stats combat C no minEngagements = 30, engageGapMs = 4000, snapMs = 400, poolMin = 200, poolAccounts = 10, perAccountCap = 100, tail = 1e-6, headMargin = 0.25, minHeadShare = 0.5, snapNull = 0.05, minSnapShare = 0.3
aim_stats_backed combat B no -
damage_plausibility combat B no margin = 2.0, absurdFactor = 10.0, minAccounts = 10, minHits = 10, repeats = 2, windowSeconds = 60
esp_los combat C no minDistance = 15.0, maxDistance = 150.0, holdMs = 1000, everyMs = 1500, combatMs = 60000, witnesses = 2, radius = 150, maxPing = 300, shooterEveryMs = 3000, witnessEveryMs = 2000, timeoutMs = 3000, windowMinutes = 10, minChecks = 8, minShare = 0.35, minHidden = 4, minTargets = 2, aloneHidden = 6, trackMinMs = 1200, trackMaxMs = 8000, cooldownMs = 600000
esp_los_backed combat B no -
hit_range combat B no factor = 1.5, slack = 15.0, leadSeconds = 0.5, repeats = 2, windowSeconds = 60
kill_rate combat B no defaultPerMinute = 8, minPerMinute = 6, maxPerMinute = 30, factor = 3.0, minWindows = 200
shot_rate combat B no windowMs = 3000, margin = 1.25, extra = 2, repeats = 2, windowSeconds = 60
silent_aim combat B no tolerance = 30.0, parallax = 2.5, leadSeconds = 0.4, vehicleFactor = 1.5, lagMs = 600, minDistance = 3.0, repeats = 4, minShare = 0.25, spacingMs = 300, windowSeconds = 120
economy_repeat economy B no -
economy_trap economy A no -
item_nowhere economy B no -
money_jump economy B no -
money_nowhere economy B no -
money_rate economy B no -
event_flood events B no -
event_rate events B no windowMs = 10000, k = 8, minSamples = 200, minLimit = 5, cooldownMs = 60000
event_shape events B no k = 8, minSamples = 200, maxShapes = 16, cooldownMs = 60000
events_before_ready events B no minJoins = 50, minShare = 0.05, minCount = 3, graceMs = 5000
events_before_ready_trap events A no -
guard_hard events A no -
guard_rule events B no -
statebag_write events B no -
ban_fingerprint identity C no -
ban_token identity C no -
young_account identity C yes -
weapon_not_owned items B no checkMs = 1000, checks = 3, seconds = 3, ownedMs = 10000
air_float movement B no -
foot_rise movement B yes -
foot_speed movement B yes -
teleport movement B yes -
vehicle_speed movement B no capMs = 110, factor = 1.25, minAccounts = 5, checks = 3, floorMs = 45
bait_event trap A no count = 6
bait_statebag trap A no -
godmode witness B no seconds = 30, cooldownMs = 600000
witness_backed witness B no -
witness_bait witness B no decoys = 3, learnAccounts = 3, cooldownMs = 60000
witness_camera witness C no farMeters = 60, reports = 2, scriptReports = 3, seconds = 20, cooldownMs = 600000
witness_extras witness C no minReporters = 10, knownAccounts = 2, cooldownMs = 1800000
witness_heartbeat witness C no minIntervalMs = 20000, maxIntervalMs = 40000, deadlineMs = 8000, pingFactor = 4, goodLastMsgMs = 1000, missRepeats = 3, wrongRepeats = 2, lateRepeats = 4, helloMs = 300000, cooldownMs = 600000
witness_state witness C no reports = 3, seconds = 40, placeAccounts = 3, placeHours = 2, cooldownMs = 600000
witness_tamper witness C no attestMinMs = 90000, attestMaxMs = 240000, sliceBytes = 4096, deadlineMs = 15000, accounts = 5, fileRepeats = 2, cooldownMs = 600000
entity_blocked world B yes -
entity_disguised world B no -
entity_model_rate world B yes defaultPerMinute = 10, minPerMinute = 5, factor = 3.0, minWindows = 20
entity_rate world B yes defaultPerMinute = 20, minPerMinute = 8, maxPerMinute = 80, factor = 3.0, minWindows = 300
entity_untrusted world C yes cooldownSeconds = 60
explosion_hidden world B yes -
explosion_rate world B yes windowSeconds = 10, weaponLimit = 12, worldLimit = 30
explosion_weapon world B yes heldSeconds = 15, placedSeconds = 600
fire_rate world B yes windowSeconds = 10, limit = 60
projectile_rate world B yes windowSeconds = 5, limit = 8
projectile_weapon world B yes heldSeconds = 3, originFoot = 25.0, originVehicle = 60.0
ptfx_rate world B yes windowSeconds = 10, limit = 40, maxScale = 5.0
world_distance world B yes -

Options that are not rules but are read the same way (Config.Rules.<name>.<key>):

Name Settings and code defaults
observe maxEvents = 5000, maxArgs = 8, recordPerWindow = 30, saveEveryMs = 300000

Settings the code reads that the config files do not contain

These work when you add them to a config file. Until then the code uses its own defaults, listed here where the code states them in one place.

Config.Combat

Read in server/detect/rules/combat.lua.

One key: weapons, to change or add weapons in the combat rules' weapon table, for example Config.Combat = { weapons = { WEAPON_MYADDON = { group = 'rifle', damage = 45, pellets = 1, range = 250, rate = 12 } } }.

Config.Kit

Read in server/api.lua.

One key: trustedBelow, the score under which IsTrusted answers trusted. Without it the line is half of Config.Detection.reviewScore.

Config.Mode

Read in server/detect/engine.lua.

No defaults table in the code; see the file named above.

Config.Reports

Read in server/enforce/reports.lua.

No defaults table in the code; see the file named above.

Config.Roles

Read in server/core/roles.lua.

No defaults table in the code; see the file named above.

Config.Trail

Read in server/trail/money.lua.

Key Code default Note
keepHours 24 Hours the money and item ledger is kept.
perAccount 5000 Most ledger entries kept per account.
settleMs 150 A change is judged this long after it happened, so a matching report can arrive first.
nowhereMs 2000 An event that moves money explains a gain that follows within this window.
trapMinutes 10 A gain this soon after a trap fired for the same player is tied to the trap.
sql true Keep the ledger in the zds_trail table when the database is used.
repeatCount 10
repeatWindowMs 30000
repeatCooldownMinutes 10
trusted {} resources whose events explain money and items (names, list or set)
noReason { 'unknown', 'none', 'nil', 'null' } reason strings that mean "no reason given"
jump { k = 8, minSamples = 50, minAmount = 5000, cooldownMinutes = 10 } Learned limit for one large gain (money_jump).
rate { k = 8, minSamples = 30, minAmount = 20000, cooldownMinutes = 10 } Learned limit for gains per hour by job (money_rate).

Config.Victims

Read in server/enforce/victims.lua.

Key Code default Note
notify true Tell confirmed victims in game (sentinel:victims notify on\|off saves a change).
windowMinutes 30 How far back a confirmed case looks for victims.
radius 20.0 Metres around an explosion the subject caused within which a death counts.
deathAfterMs 5000 A death this soon after such an explosion counts.
crumbMs 10000 How often a return point is kept for each player.