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.
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.Localefalse: 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:
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. |