BotRampart

Docs · How it works

A budget for every session, a cost for every path.

BotRampart does not try to tell bots from people. It meters what each session consumes and asks for a little work when a session wants more. This page explains the idea, the numbers behind it and what it does not cover.

Design, not product. BotRampart is not built yet. Everything below is the proposed design from the architecture plan of 16 November 2026. Default numbers are proposals to be tuned, and items marked later are outside the first build.

The idea

Bot defense usually asks one question: is this client a bot? That question has become expensive to answer and cheap to fool. Image puzzles are solved by published models,1 solver services sell passes by the thousand,2 and residential proxies make an IP address a disposable identity at prices starting near a dollar a gigabyte.3

BotRampart asks a different question: what has this session spent? Every session holds credit. Every path has a cost. Ordinary use refills faster than it spends; heavy use runs out and has to earn more by passing a challenge, and each repeat earns less. A pass buys credit, never a clearance.

Nobody is labelled a bot, so there is no verdict to dispute. Anyone can check the arithmetic, so every decision can be explained.

A session's life

Identity is one first-party cookie, __br_s, set by your own server with HttpOnly and signed with your site key. It carries a random session ID, its tier and its expiry; no device fingerprint. The token lives 30 minutes and is renewed while in use, inside a session of at most seven days, so a revoked session stops working within half an hour even on an app instance that missed a sync. That lifetime follows Cloudflare's own guidance for its clearance cookie, 30 minutes by default and 15 to 45 recommended.4

Because your server sets the cookie, page scripts cannot read it, and Safari's rule that deletes script-written cookies after seven days without interaction does not apply to it.5

TierWhat the visitor doesBuys (proposed)StopsScope
0 · provisionalNothing. First contact gets a cookie.30 units, general paths onlyNothing alone; makes requests attributablefirst build
1 · proof-of-workNothing visible. The browser SDK solves 16 to 50 small puzzles in a Web Worker.300, then refillPlain HTTP clients and anything without JavaScript. Not headless browsers.first build
2 · human checkTicks a box. Pointer, touch and key dynamics are scored. Works with a keyboard and a screen reader.3,000, halving on each repeat in 24 hUnattended automation that does not pay a solverfirst build
3 · step-upA pluggable method: email link, sign-in or passkey, an image puzzle, or a third-party widget. Always with a non-visual option.6,000, halvingRaises the price again; methods tied to an account are hardest to farmlater
ThrottleWaits. 429 with Retry-After.Refill onlySustained heavy use, whoever is behind itfirst build

Accessibility shapes the top tier. WCAG 2.2 success criterion 3.3.8 does not allow a cognitive test in an authentication step unless an alternative, a mechanism to help, or one of its narrow exceptions applies.6 So the image puzzle is one step-up option among several, not the fixed top of the ladder, and every step-up configuration must offer a method that needs no puzzle at all.

Request economics

Each request is charged the cost of its path class before your handler runs. The policy file names the classes; these are the proposed defaults:

Path classExample matchCostLowest tier
static/assets/*, *.css, *.png00
general/*10
search/api/search*51
loginPOST /login101
checkout/api/checkout*201

A session regains 20 units a minute up to a balance of 300, and three times as fast once your app attaches a login ID. When it cannot pay, the over-budget rule asks for the next challenge; when the shrinking grants are spent, it throttles. In code, the whole of it:

on request(session, path_class):
    cost = path_cost[path_class]                     # 0 for static
    rate = refill_per_min * multiplier(session)      # x3 when signed in
    session.credits = min(burst, session.credits + rate * minutes_since_last)
    if session.credits >= cost: session.credits -= cost; return ALLOW
    return over_budget(session)                      # next challenge, else throttle

on challenge passed(session, tier):
    n = passes of this tier by session in the last 24 h
    session.credits += grant[tier] * 0.5 ** n        # 300 / 3,000 / 6,000, halving

This is not a new idea, only a new place for it. GitHub's GraphQL API gives each user 5,000 points an hour and prices each query by the work it implies,7 Shopify limits its Admin API by calculated query cost,8 and Cloudflare's complexity-based rate limiting reads a cost your origin returns in a response header.9 BotRampart applies the same accounting to anonymous browser sessions. Your app can report the true cost of an expensive response in a BR-Cost header, and the difference is settled on the session.

Why a pass buys credit, not clearance

A design that challenges once per session and then waves the session through has a known flaw: once the challenge is solved, latency rises but throughput does not fall.10 Tying each pass to a fixed grant that halves on repeat gives every session a hard daily ceiling instead.

With the default policy, one session can spend at most 35,363 units in a day in the first build (tiers 0 to 2), and 47,175 once step-up methods exist: a day of refill, the burst, and every grant until a repeat would buy less than 100 units. At 5 units a search that is about 7,000 to 9,400 searches a day. Someone who wants a million searches a day needs more than a hundred sessions, and new sessions are rationed per network, below. These figures come from the reference implementation this site runs, and a test in the repository checks them.

A challenge is not an economic wall by itself. Solvers charge around $1 to $3 per thousand passes,2 so a paid pass that buys 600 searches adds a fraction of a cent per thousand searches. Challenges do three jobs: they shut out clients with no JavaScript engine, they produce interaction signals, and they meter credit. The ceiling and the mint buckets do the limiting.

Clients that throw cookies away

A client that discards its cookie arrives as a new session every time. If new sessions were free, that client would have unlimited budgets. So every new session starts at tier 0 with 30 units for general pages only, and new sessions are counted per network:

Mint bucketWindowDefault (proposed)Catches
Exact IP10 min20 new sessionsOne machine discarding cookies
/24 or /48 prefix10 min60 new sessionsA small block, or an IPv6 host rotating addresses
ASN10 min5 × its own baselineA proxy pool inside one provider
TLS fingerprint family10 min5 × baselineOne automation stack spread over many networks later

The response to pressure is a price, not a block: a proof-of-work 1.5 to 10 times harder, then a human check for new sessions on costly paths, and only at an extreme a 429. Sessions that are already established or signed in are exempt, so a café or a mobile carrier's shared address does not lock out the people already using your site. IP addresses are disposable to an attacker, and in one study 60% of residential proxy addresses were seen only once in 90 days,11 which is why the address is a bucket here and never the identity.

The five-minute loop

Some abuse is invisible one session at a time: a slow scrape spread over thousands of sessions, each under budget. Every five minutes Core merges the counters from your app instances, compares them with each cohort's own baseline for that hour of the week, and turns every number into a named band such as cost_vs_baseline: x6_plus or new_session_share: over_60pct. Free text is removed: paths become your class names, user agents become a family. The result is a small JSON state with nothing a visitor typed in it.

Core then asks a decision model four typed questions about that state: is this automated abuse (yes or no, with a probability), how risky is it (a five-level score), what is it most likely for (scraping, credential stuffing, fake sign-ups, an organic spike), and which is the least intrusive step that would contain it. This follows the guidance Google publishes for its Decisions API: compare numbers in code and pass a named bucket,12 and treat input as untrusted.13 Google launched that API with Gemini Decision 1 on 11 November 202614 at $0.10 per million input tokens,15 so one site-level question every five minutes costs on the order of a few dollars a month (our estimate at about 1,800 tokens a call). The provider sits behind one interface, and a self-hosted model can replace it so nothing leaves your network.

The answer never acts directly. It becomes fields such as ai.attack and ai.action, with an expiry, and your rules decide what to do with them. The model can raise a price or lower a cohort's budget; it can never block or allow a client. Answers are cached on a hash of the bands for up to an hour, so a quiet site asks rarely, and any change in a band is a new question at the next window.

First build: shadow mode. In the first build the model's answers are logged and shown beside what the rules actually did, so you can set thresholds from your own traffic before anything acts on them. Enforcing ai.* fields comes after.

What happensWhich loop reactsTime to effect
One session exceeds its budgetPer request, in the SDKThe same request
One network mints sessions in a burstPer requestSeconds on one instance; one sync interval across instances
Site-wide spend jumpsA deterministic tripwire, then the five-minute loopOne sync interval, then 5 to 10 minutes
Slow distributed scrape, every session under budgetFive-minute loop10 to 15 minutes: two windows must agree
The attack endsFive-minute loop15 minutes to step down a level; 60 at most
You disagree with a mitigationYou, in Slack or the policy fileThe next sync

Explaining a decision

Every non-allow decision is written to a decision log in your bucket with a reference such as BR-7F3K2Q, which the visitor sees on the challenge. The log records the rule, the policy version, the budget, the cost and the model answer in force, so "why was this person challenged?" is a lookup, not a reconstruction.

Look up a decision by the reference the visitor sawgetDecision

curl -H "Authorization: Bearer $BR_CONSOLE_TOKEN" \
  "https://core.internal:8787/v1/decisions/BR-7F3K2Q?include=answer"

{ "ref": "BR-7F3K2Q", "ts": "2026-11-16T10:12:41Z", "action": "challenge", "tier": "human",
  "rule_id": "over-budget", "policy_version": 12, "risk_score": 1,
  "credits": 3, "cost": 5, "path_class": "search", "ai_answer_id": null }

An agent with read-only access to the same log answers in Slack, by email or in the console. It uses named, fixed queries before any free-form SQL, attaches the query and rows to every answer, and cannot change anything: it proposes a policy change and a person approves it. That separation matters, because stored log text can carry instructions aimed at a model: injected log entries steered LLM log analysis up to 88.2% of the time in one 2026 study.16 The first build ships explanations and a daily digest; proposals and free SQL come later.

What it does not do

  • Floods and DDoS. The request reaches your app before it is refused. Keep your CDN or WAF for volume; BotRampart refuses before your handler runs, in about 300 bytes.
  • Cached pages and static files. They never reach your app. The browser SDK still starts a session from a cached page and protects the data APIs behind it.
  • Headless browsers driven by a patient operator. Proof-of-work does not stop them. Budgets ration them: they get bounded throughput per session and sessions are rationed per network.
  • Mobile apps and partner APIs later. They carry no cookie and run no JavaScript. Rules can pass requests signed with an API key; a mobile SDK and signed-agent verification are on the roadmap.

Next: Getting started walks through the planned install, and Architecture has the full component design.

Sources

Every figure from someone else on this page, with the words it rests on. Checked on the date shown; the full ledger is claims.yaml.

  1. Breaking reCAPTCHAv2 (arXiv 2409.08831). Our main result is that we can solve 100% of the captchas, while previous work only solved 68-71%. Checked 2026-11-18.
  2. 2Captcha: Captcha prices. $1 — $2.99 Checked 2026-11-18.
  3. ZenProxy: Residential Proxy Prices 2026 (secondary). published residential prices run from $0.99 to $7.35 per GB at the smallest amount each one sells, and from $0.78 to $5.51 per GB at their largest listed amounts up to 1 TB Checked 2026-11-18.
  4. Cloudflare docs: Challenge Passage. By default, the cf_clearance cookie has a lifetime of 30 minutes. Cloudflare recommends a setting between 15 and 45 minutes. Checked 2026-11-18.
  5. WebKit: Tracking Prevention in WebKit. ITP deletes all cookies created in JavaScript and all other script-writeable storage after 7 days of no user interaction with the website. Checked 2026-11-18.
  6. W3C WAI: Understanding Success Criterion 3.3.8: Accessible Authentication (Minimum). A cognitive function test (such as remembering a password or solving a puzzle) is not required for any step in an authentication process unless that step provides at least one of the following: Checked 2026-11-18.
  7. GitHub Docs: Rate limits and query limits for the GraphQL API. For users: 5,000 points per hour per user. Checked 2026-11-18.
  8. Shopify: GraphQL Admin API rate limits. Calls to the GraphQL Admin API are limited based on calculated query cost, which means you should consider the cost of requests over time rather than the number of requests. Checked 2026-11-18.
  9. Cloudflare WAF docs: Rate limiting parameters. Name of HTTP header in the response, set by the origin server, with the score for the current request. Applies to complexity-based rate limiting. Checked 2026-11-18.
  10. Everything Wrong With Anubis('s default configuration). would need to wait around half a second to connect to a site, after that it can continue hammering the server with the same throughput as it would otherwise INCREASING LATENCY DOES NOT DECREASE THROUGHPUT Checked 2026-11-18.
  11. IPinfo via HackerNoon: The Residential Proxy Problem: Shared Infrastructure and Rapid Rotation. 60% of residential proxy IPs are only observed once in a 90-day window (32% for IPv4, 87% for IPv6). Checked 2026-11-18.
  12. Google: Decisions API guide. Compare numbers, dates, and durations in code, then pass the result or a named bucket in the input. Checked 2026-11-18.
  13. Google: Decisions API guide. Treat input as untrusted. User-supplied text can argue for its own classification. Checked 2026-11-18.
  14. Google: Gemini Decisions API: Fast, calibrated multimodal decisions. Today, we’re introducing the Gemini Decisions API, a new endpoint for fast, closed-set decisions powered by our new Gemini Decision 1 model (gemini-decision-1) Checked 2026-11-18.
  15. Google: Gemini Decisions API: Fast, calibrated multimodal decisions. at $0.10 per 1M input tokens with zero output tokens billed Checked 2026-11-18.
  16. USENIX Security 2026: Context Contamination in LLM Analysis of Network Security Logs (PDF). Our findings reveal an up to 88.2% attack success rate (83.4% average across models) Checked 2026-11-18.