Score bands
How the 1–99 score maps to bands relative to your project threshold, and how rules turn bands into allow / challenge / block actions.
A raw score is precise but hard to act on. Botect classifies each score into a band relative to your project's threshold T, and your rules map bands to actions. This keeps the decision surface simple: most customers never touch a raw number.
The bands
| Band | Score range | Meaning |
|---|---|---|
not_computed | 0 | No signals yet, or a degraded lookup. Always allowed (fail-open). |
definite | 1 | The browser or request admitted automation (e.g. navigator.webdriver). Never assigned by inference. |
confident_automated | 2 … 5 | Overwhelming accumulated evidence — as certain as inference gets, without an admission. Target this band for block-level rules if you want strict enforcement; keep blocking only definite if you want the most cautious posture. |
likely_automated | 6 … T-1 | Below the threshold — probably a bot. |
likely_human | T … 99 | At or above the threshold — probably human. Earned: this band requires at least one positive human signal (touch, typing, a return visit). A session whose evidence all leans bot can never drift into it on arithmetic alone — it reads not_computed instead. |
verified | — | A recognized verified bot; set by short-circuit, independent of score. |
The threshold T (default 30) is a project setting. Raising it makes Botect more suspicious (more sessions land in likely_automated); lowering it is more permissive.
Rules: bands → actions
Rules are the only place enforcement is decided. Every project ships with two starter rules that map the two enforceable bands, and they arrive inactive — so enabling scoring never breaks legitimate traffic before you opt in.
| Starter rule | Expression | Action |
|---|---|---|
| Block confirmed automation | band == "definite" | block |
| Challenge likely-automated traffic | band == "likely_automated" | challenge |
Activate one from the project's Rules page, or via Update a rule. A rule can match on far more than the band — path, country, user agent, detections, individual behavioral signals — so these two are a starting point, not a ceiling.
The starter rules ship inactive. Enable scoring, watch real traffic land in bands, and activate enforcement only when the bands look right for your site.
Guards: who skips checking
Two booleans live on the project's bot_settings. They are guards, not enforcement — they decide who is exempt from being checked at all, and they run before any rule.
{
"allow_verified": true,
"protect_static": true
}
| Guard | Default | Effect |
|---|---|---|
allow_verified | true | Verified bots → allow, regardless of score, before rules run |
protect_static | true | When false, static-resource requests are skipped (allow) |
Change a guard or the threshold via Update settings. Verdicts already cached for a session are served until they expire, so allow up to the verdict cache TTL (60s by default).
Resolution order
When your backend reads a verdict, the action is resolved in this order — the first match wins:
Verified short-circuit
Verified bot + allow_verified on → allow.
Static-resource skip
Static resource + protect_static off → allow.
Rules
Active rules in sort_order. Every action except log terminates — allow and delay end evaluation just as block and challenge do — so the first match wins. log records the match and keeps going.
If the session carries a logged-in assertion and the project sets a protective policy, the matched action may be downgraded here — never for the definite or confident_automated bands.
Default
allow.
Because rules are evaluated in order and the first terminating match wins, order matters: put a narrow exemption (say, an allow for your own monitoring) above the broad band rule you want it to override.
Actions
The action returned in a verdict is one of the BotAction values:
| Action | Meaning |
|---|---|
allow | Let the request through |
challenge | Interpose a challenge (e.g. CAPTCHA / interstitial) |
block | Reject the request |
log | Record only — no enforcement, and evaluation continues |
delay | Apply a soft delay |