Cloudflare bot management ML

01 · CONTEXT

Good bot, bad bot, and the problem of classifying each request

A bot is an autonomous program that imitates or replaces a person's behavior. Cloudflare separates useful bots, such as those from search engines, from malicious ones, such as credential stuffing, third-party scraping, and spam. Managing bots, under this definition, means blocking unwanted traffic without stopping useful bots from accessing the site.

Two product requirements set the tone for the design. The first is precision: almost no human visitor should be mistaken for a bot. The second is recoverability: if a wrong prediction happens, the person must still be able to access the site and good bots must get through.

1. The diagram shows the simplest path: the visitor arrives at the edge and the edge forwards the request to the origin.

2. The design question is in this stretch: at what point along the path to classify the visitor before the origin serves them.

02 · REQUIREMENTS

What the platform had to deliver

Beyond the product requirements, engineering put together a list of mandatory demands. The table summarizes the ones the source highlights as among the most critical.

03 · THE SCORE

A score as a contract between detection and customer

The answer to the problem was a single concept, the score: a number from 0 to 100 that indicates the probability that the request came from a person (high score) or from an automated program (low score).

The score became a field in the firewall rules. Each customer adjusts the threshold according to their sensitivity to false positives and false negatives, and Cloudflare can expand the detections under the hood without the customer changing any configuration.

1. The visitor's request goes through the Bot Management module, which runs on every edge machine.

2. When the module produces the necessary fields, among them the score, the firewall takes over mitigation.

3. Based on the score and the configured threshold, the firewall blocks, challenges, or logs suspicious requests and forwards legitimate ones to the origin.

4. The module also records the details of each detection in ClickHouse through the data pipelines.

5. The core services process the data received from the edge datacenters.

Those who want more flexibility over what to do with the score can use Cloudflare Workers, in addition to the firewall actions.

04 · LAYERED DETECTION

Several mechanisms, a single score

The platform combines five complementary detection mechanisms, each with its own score, into a single score sent to the firewall. Most run on every request and some are enabled per customer.

Not every problem calls for machine learning. The source notes that, in certain cases, models tend to yield less than basic heuristics, and that sometimes a single request attribute gives the bot away. Heuristics still feed the learning: the requests they classify are used to train the models.

1. The request reaches the module and its attributes are extracted and transformed to feed the detection mechanisms.

2. The machine learning models receive request attributes and cross-request attributes delivered by the Gagarin platform.

3. The heuristics engine applies simple rules; any match assigns the lowest possible score, and the requests it classifies are used to train the models.

4. The other mechanisms complete the set: behavioral analysis, which is unsupervised; validation of good bots by IP grouping; and the JavaScript challenge injected into the page by the edge.

5. The mechanisms' scores are combined into the single score that goes on to the firewall.

05 · INFERENCE AT THE EDGE

Speed, shadow mode, and model deployment

The core of the machine learning detection is CatBoost, a gradient boosting library over decision trees. According to the source, applying any of the models takes less than 50 microseconds, and hundreds of heuristics run in a little under 20 microseconds. Most of the edge's business logic is written in Lua (LuaJIT), and the library's C and Rust API provides the compatible FFI interface for applying the models.

Several CatBoost models run in shadow mode on every request on every machine, and one of them runs in active mode, influencing the final score. The results and attributes of every ML detection are logged in ClickHouse for analysis and improvement of the models.

New models go into production within seconds through Quicksilver, the configuration database, and the same mechanism defines which model version runs in active mode for a specific customer.

1. The module at the edge applies several models to each request: one active and the others in shadow mode.

2. Only the active model influences the final score that goes on to the firewall.

3. The results and attributes of the ML detections are logged in ClickHouse.

4. These records serve the analysis and improvement of the models.

5. New models reach the edge through Quicksilver in seconds, and the same configuration chooses each customer's active version.

06 · CRITICAL READING

What to take into the interview

The source's numbers are from the time the text was published. Cloudflare said it covered more than 26 million properties on the internet, processed an average of 11 million requests per second, with peaks above 14 million, and examined more than 250 attributes of each request.

Computing the score on every request and for all customers has benefits the source lists: evaluating how protection would work for a customer before turning on active mode, and maintaining a feedback loop that improves the detection mechanisms.