Radar
Radar
Console page: Authentication › Radar in an environment console, with three tabs — Decisions, Rules and Allow & deny lists.
Radar judges every sign-in and every sign-up in an environment and decides one of three things:
- Allow — the attempt goes ahead.
- Challenge — the person proves it is them before a session exists. On a password sign-in that is their authenticator app if they have one, and a one-time code emailed to them if they do not. On a sign-up it is the CAPTCHA (Cloudflare Turnstile) when one is configured, and otherwise a one-time code emailed to the address they signed up with, before their first session. A passkey or a magic link already proves possession of something, so a challenge adds no step to those.
- Block — the attempt is refused with one generic sentence, "We could not process this request. Please try again later.", in the visitor's language. The sentence never says which rule fired: telling an attacker that is telling them what to change.
Every verdict is recorded — with the rule that decided it, every other rule that fired, the reasons, and the facts it was decided on — and shown on the Decisions tab.
Monitor first, then enforce
Each environment has a mode:
- Monitor — every verdict is recorded and none is acted on. A blocked attempt goes
ahead; the decision row says
monitor only. This is what you read before you enforce. - Enforce — blocks refuse and challenges ask for proof.
Until an environment chooses, it follows the deployment's default, RISK_MODE (which is
monitor unless the operator set it). Switching is a critical change: the console asks
for your password first, and over the API it needs the radar:manage scope — a key that
may only tune rules (radar:write) cannot turn protection off.
Run in monitor for at least a week of real traffic. Filter the Decisions tab by Verdict: Block and Challenge and read who would have been stopped. If it is people you know, fix the rule before you enforce.
What Radar looks at
| Fact | Where it comes from |
|---|---|
| Country, network (ASN) and owner | IP intelligence — see below. Unknown without it. |
| Tor exit node | The local Tor exit list (risk:refresh-tor), and IP intelligence that reports it. |
| VPN, open proxy, hosting network | IP intelligence that reports them (MaxMind's paid Anonymous IP database, IPinfo's paid privacy data). |
| New device | The account's own history of browsers it has successfully signed in from. |
| Impossible travel | The distance and time since the account's last successful sign-in that could be placed on a map. |
| Velocity | Attempts per IP (last minute, last hour), different addresses tried per IP (last 10 minutes), failures per IP and per address (last hour), attempts per device (last hour). |
| Disposable email | A bundled list of throwaway mail providers, refreshable. |
| Risk score | The scored signals that came before Radar — IP reputation, honeypot, user agent, MX — see Adaptive risk. |
A fact Radar cannot establish is unknown, and an unknown fact matches no condition. With no IP intelligence configured, a rule on country never fires — it does not challenge everyone because nobody can be placed.
The order Radar asks in
- Deny list. A match blocks; nothing else is asked.
- Allow list. A match allows; no rule is asked — built-in rules included.
- Your rules, top to bottom. The first whose conditions all hold decides,
allowincluded — which is how you carve an exception out of the built-in rules. - Built-in rules, all of them. The strictest action among those that fire decides.
- Nothing matched: allow.
An address or IP on both lists is refused: deny wins.
The built-in rules are evaluated even when a list or one of your rules decided, and the decision shows them under triggered. "Allowed by Office network, though Credential stuffing fired" is exactly what you need to see after writing that rule.
Built-in rules
| Rule | Fires when | Default |
|---|---|---|
| Credential stuffing | 10 or more different addresses tried from one IP in 10 minutes (sign-in) | on, block |
| Bot-like velocity | 20 or more attempts from one IP in a minute | on, block |
| Repeated failures on one account | 10 or more failed sign-ins on one address in an hour, from anywhere | on, challenge |
| Impossible travel | travel faster than 900 km/h since the last successful sign-in (sign-in) | on, challenge |
| New device | a browser this account has never signed in from (sign-in) | off, challenge |
| Tor, VPN or open proxy | the address is one | on, challenge |
| Hosting or data centre network | the address belongs to one | off, challenge |
| Disposable email domain | a sign-up with a throwaway address | on, block |
| Risk score: reject | the risk score reached its reject threshold | on, block |
| Risk score: elevated | the risk score reached its challenge or step-up threshold | on, challenge |
Each can be switched off, given another action, and — where it counts — another threshold,
on the Rules tab or with radar.settings.update. New device and Hosting network start
off because under enforcement each would send a code to everybody on a new laptop or behind
a corporate egress; their facts are recorded anyway, so the Decisions tab shows what switching
them on would do.
The two Risk score rules are the behaviour the app had before Radar: a reject blocked, an
elevated score asked for a second factor. With nothing else configured, enforcing Radar does
what RISK_MODE=enforce did, plus the velocity, travel, network and disposable-address rules.
Your own rules
A rule is when every condition holds, then allow / challenge / block, on sign-in, sign-up or both. A condition compares one fact with a value:
{
"name": "Challenge sign-ins from outside the Nordics",
"action": "challenge",
"applies_to": "sign_in",
"conditions": [
{ "field": "country", "operator": "not_in", "values": ["DK", "SE", "NO"] }
]
}
| Type | Fields | Operators |
|---|---|---|
| text | email, email_domain, user_agent, as_organization, method |
eq, neq, in, not_in, contains, not_contains, starts_with, ends_with |
| country | country (ISO 3166-1 alpha-2) |
eq, neq, in, not_in |
| IP | ip |
eq, neq, in, not_in, in_cidr, not_in_cidr |
| number | asn, risk_score, travel_kmh, ip_attempts_1m, ip_attempts_1h, ip_distinct_emails_10m, ip_failures_1h, email_attempts_1h, email_failures_1h, device_attempts_1h |
eq, neq, gt, gte, lt, lte, in, not_in |
| yes/no | is_hosting, is_vpn, is_proxy, is_tor, disposable_email, new_device, impossible_travel |
eq, neq |
value is one value written as text ("DK", "20", "true"); values is a list, for in,
not_in, in_cidr and not_in_cidr. Text compares case-insensitively. Rules are checked
when they are saved — an operator a field does not take, a country that is not two letters, a
range that is not CIDR is refused with the reason. Nothing in a rule is ever executed: there is
no expression syntax, no regular expression, and evaluation is a handful of comparisons. An
environment holds at most 100 rules of up to 10 conditions each.
Some rules that work well:
- Allow your office past velocity rules —
ip in_cidr [203.0.113.0/24]→ allow, placed first. A load test from CI is the same shape with your runner's range or ASN. - Challenge outside where you operate —
country not_in [DK, SE, NO]→ challenge. - Block a headless browser —
user_agent contains headlesschrome→ block. - Challenge new devices for your admins only —
email_domain eq yourcompany.comandnew_device eq true→ challenge.
Allow and deny lists
An entry is an IP address or CIDR range (IPv4 or IPv6), an email address, a mail domain (which covers its subdomains), or a device — the 64-character device id a decision shows, which the Deny this device button on a decision fills in for you. An entry may expire. Use the allow list for your own networks and test accounts, not for a whole country: an allow entry skips every rule, the ones that stop credential stuffing included.
A device entry recognises the device cookie. Somebody who clears their cookies is a new device; deny their IP or their address too.
IP intelligence
Off by default (CBOX_ID_RADAR_IP_INTELLIGENCE=none): nothing is looked up and nothing about
an address leaves the deployment. The operator can choose:
maxmind— MaxMind database files on the deployment's disk, read locally; nothing is fetched while signing in. Download them under MaxMind's licence (GeoLite2 is free with an account and attribution; GeoIP2 is paid) and point at them:CBOX_ID_RADAR_MAXMIND_CITY_DB(country and location — GeoLite2-City),CBOX_ID_RADAR_MAXMIND_ASN_DB(network — GeoLite2-ASN) and optionallyCBOX_ID_RADAR_MAXMIND_ANONYMOUS_DB(VPN, hosting, proxy and Tor — GeoIP2 Anonymous IP, paid). Keep them updated with MaxMind'sgeoipupdate; Cbox ID does not download them.ipinfo— IPinfo's API with your token (CBOX_ID_RADAR_IPINFO_TOKEN). One HTTPS request per address the cache has not seen, with a 1.5-second timeout. The address is sent to IPinfo — that is what choosing this driver means; say so in your privacy notice. VPN, proxy, Tor and hosting flags need IPinfo's paid privacy data.
Lookups are cached for a day (CBOX_ID_RADAR_IP_CACHE_TTL) under a keyed pseudonym of the
address. Private and reserved addresses are never looked up. A lookup that fails or times out
is "unknown" — it never blocks a sign-in. To use another source, bind your own
App\Platform\Radar\IpIntelligence\IpIntelligence.
Throwaway mail domains
Radar ships a curated list of about 600 disposable mail providers, and the risk score's
email.disposable signal reads the same list. New providers appear weekly, so for real
coverage run php artisan radar:refresh-disposable-domains, which fetches the
community-maintained disposable-email-domains
blocklist (CC0) to storage/app/radar/disposable-domains.txt and merges it with the bundled
one. It is not scheduled for you — it is an outbound request, and whether the deployment
makes one is yours to decide; schedule it weekly if you want it. A response that is not a
domain list, or holds fewer than 100 domains, leaves the current list in place. Workers read
the list once per process, so restart them (or wait for the next deploy) after a refresh.
Devices, privately
Radar recognises a browser with a first-party cookie (cbox_device): set by this host for
this host, HttpOnly, SameSite=Lax, Secure wherever the session cookie is, holding 128 random
bits and nothing derived from the person or the machine. It is set when somebody submits a
sign-in or a sign-up, as part of securing the sign-in they asked for — the category of cookie
consent rules treat as strictly necessary. There is no third-party script, no canvas or font
fingerprinting and no other storage.
For a client that keeps no cookies — an app on the Frontend API, a private window — the
fallback is a coarse fingerprint: the user agent with every version cut to its major
number, the Sec-CH-UA client hints the browser sends anyway, and its first language. Two
colleagues on the same browser and OS look alike; that is the right failure for "have we seen
this before?".
Devices are remembered only after a sign-in succeeds — through any door: password, passkey, magic link, Enterprise SSO, social login, a completed challenge. Typing somebody's address cannot add a device or a location to their history, and a failed attempt from the other side of the world does not make their next real sign-in look like impossible travel.
What is stored, and for how long
| Where | What | How long |
|---|---|---|
risk_decisions |
Per attempt: verdict, mode, deciding rule, rules that fired, reasons, risk score, country, ASN, mail domain, keyed pseudonyms of the IP, the address and the device cookie, and the facts (counts, flags, travel speed). Never the IP, the address or the user agent. | CBOX_ID_RISK_TRAIL_RETENTION_DAYS (90) |
radar_devices |
Per account and browser: pseudonyms of the account, the device cookie and the fingerprint; the country and a point rounded to one decimal (~11 km) of the last successful sign-in on it. | CBOX_ID_RADAR_DEVICE_RETENTION_DAYS (180) after the last sign-in on it |
| Cache | Velocity counters and IP lookups, keyed by pseudonyms. | Two windows (at most two hours); lookups a day |
radar_rules, radar_list_entries, radar_settings |
What administrators wrote. A list entry holds the IP, range, address or domain as typed — it is configuration, kept readable on purpose. | Until removed |
Pseudonyms are HMAC-SHA256 under app.key, and everything Radar remembers about an account is
keyed under the environment too, so the same address in two environments is two people.
Erasing a person (users.erase) deletes their remembered devices and unlinks their address and
device from every decision in the environment (the erasure receipt lists app.radar_devices
and app.risk_decisions). It does not remove an allow- or deny-list entry naming their
address — that is the environment's own fraud-prevention record; remove it with
radar.lists.remove if the request covers it.
The API, MCP and the CLI
Every console action is an action on the environment's management API and its MCP server:
| Action | REST | Scope |
|---|---|---|
radar.settings.get / .update |
GET / PATCH /api/v1/radar/settings |
radar:read / radar:write |
radar.mode.set (critical) |
PUT /api/v1/radar/mode |
radar:manage |
radar.rules.list / .get / .create / .update / .delete |
/api/v1/radar/rules[/{id}] |
radar:read / radar:write |
radar.rules.reorder |
PUT /api/v1/radar/rules/order |
radar:write |
radar.lists.list / .add / .remove |
/api/v1/radar/lists[/{id}] |
radar:read / radar:write |
radar.decisions.list / .get |
GET /api/v1/radar/decisions[/{id}] |
radar:read |
radar.decisions.list filters by verdict, flow, rule (deciding or fired), country,
email and ip (matched by pseudonym, never returned), device, enforced, from and to,
newest first; pass next_cursor as after for the next page.
Honest limits
- IP intelligence is approximate. A GeoIP country is right most of the time and a city
often wrong; mobile carriers, satellite links and corporate VPNs place people far from where
they are. Impossible travel ignores hops under 300 km (
CBOX_ID_RADAR_TRAVEL_MIN_KM) for that reason, and still produces false positives for people on VPNs. Start it in monitor. - The free GeoLite2 databases report no VPN, proxy or hosting flags. Without the paid Anonymous IP database (or IPinfo's privacy data) the Tor, VPN or open proxy rule sees only Tor, from the local exit list, and Hosting network never fires.
- Velocity is only as shared as the cache. On more than one replica the counters must live
in a shared store (
CBOX_ID_RADAR_CACHE_STORE, e.g.redis); a per-process store counts each pod's traffic separately. Counts use a two-bucket sliding window and the distinct-address count saturates at 1,000 per window — approximations, chosen to cost two cache reads. - Credential stuffing from a botnet spreads across many IPs and stays under any per-IP threshold. Repeated failures on one account and the account lockout catch the guessing on each account; nothing per-IP catches a slow, wide spray. A shared NAT (an office, a mobile carrier) can also trip the per-IP rules — allow-list it.
- Device recognition is not identification. Clearing cookies makes any device new; the fingerprint fallback is deliberately coarse. A deny-listed device is a speed bump, not a ban.
- Passkey and magic-link attempts are judged before anybody is known, so their facts carry
no address: rules on
email,new_deviceor travel do not apply to them, and a challenge adds no step (they already prove possession). Blocks, lists and per-IP rules do apply. - Enterprise SSO sign-ins are the identity provider's to judge. A federated sign-in is vouched for by the customer's IdP; Radar records the device and location it succeeded from, but does not challenge or block it.
- A sign-up challenge without Turnstile is an emailed code, which proves an inbox — a disposable inbox included, which is why the disposable-domain rule blocks rather than challenges by default.
- Decisions are not on the audit chain. They are pre-authentication telemetry and live in
risk_decisionswith their own retention (the reasons are in Adaptive risk). Changes to Radar's configuration — the mode, rules, lists — are on the audit chain, with who made them. - The bundled disposable list is a starter. Refresh it, or point
CBOX_ID_RADAR_DISPOSABLE_DOMAINS_PATHat your own.