The infrastructure at Read the Docs endured a major DDoS attack from mid-to-late June 2026. It was the largest and most sophisticated such assault the organization has faced to date. The peak load saw more than 5.5 million requests arriving per minute, which is roughly 100 times the usual volume of traffic. The incident stretched across almost ten days.
A vast assault arrived from millions of distinct IP addresses distributed across hundreds of networks worldwide. The assault changed its approach quickly and deliberately focused on paths that avoided caching. Since the small ops crew is finally getting normal sleep again, they have released a thorough account of the incident, describing both the damage and the measures that proved effective.
The anatomy of the attack
For many years, Read the Docs allowed spiders and bots to scrape its documentation without much trouble. IP-based rate limiting handled most cases of misuse. Then, about two years ago, AI crawlers grew far more common, and it became easy to connect an AI-driven scraper to a proxy network.
The June assault surpassed by a wide margin any previous challenge the team had encountered, with a scale some 10x greater than anything they had faced before. Several notable traits defined it.
- Massive volume: 5.5 million requests per minute at peak, versus a normal daily peak of under 100k requests per minute.
- Global distribution: Malicious requests came from residential IP blocks and major and minor hosting providers across hundreds of ASNs.
- Header & TLS randomization: Attackers randomized HTTP request headers and TLS connection parameters to evade signature-based filters like JA3 and JA4.
- Cache evasion: Attackers found and deliberately targeted URLs that resulted in cache misses, such as non-existent pages with unique paths (404s) and temporary redirects (302s).
- Adaptive behavior: When blocks or rate limits were implemented, the botnet adjusted its request rates, rotated through different target paths, and spread traffic across broader IP pools.
In past smaller distributed denial-of-service attacks, the sources tended to be limited — a narrow selection of nations, IP addresses, or browser identifiers. That is no longer true of this particular assault.
“This attack was truly global. It came from every country all at once, which is a nightmare when rate limiting rules are applied per Cloudflare colo.”
Why rate limiting only partially worked
Cloudflare is relied upon by Read the Docs for caching and rate limiting purposes. A great number of rate limiting rules are maintained via Terraform, guarding infrastructure according to IPs, hostnames, subdomains, ASNs, and browser fingerprints.
Cloudflare’s automated DDoS protection mitigated some traffic from what it called “known botnets.” But a big part of the attack passed that first check and reached Read the Docs’ own rate limiting and WAF rules.
The spread of attacks across many locations made crafting effective rules difficult. It is hard to limit a distributed attack without hitting legitimate bots scraping at a reasonable rate from a single IP or subnet. When rate limiting rules are applied per Cloudflare colo, a truly global attack is a nightmare to contain.
One time, attackers targeted redirects. They bombarded a hardcoded Nginx redirect — a single rewrite regex directive — with so much traffic that requests were dropped even across horizontal scaling. That kind of Nginx redirect is built to handle thousands of requests per second.
The yo-yo pattern
A limited set of domains became the focus when attackers found temporary redirects (302) that weren’t kept in cache at the edge and were handled by the Python backend. A brief outage triggered a page to the operations team within a few minutes. Half an hour later, the redirects were rerouted to be served at the edge through Cloudflare rather than their servers.
The group believed the matter was settled. Yet the aggressors kept changing their approach, moving from one machine to another, from one service to the next, for roughly another week and a half.
An attacker ramps up to find the point where a system’s rate limits kick in, then backs off to allow those limits to reset. This approach, known as a yo-yo pattern, is built to push auto-scaled systems to their limits, driving up financial costs while producing brief, recurring drops in service quality.
The people who attacked Read the Docs were aware that it ran a WAF with rate limits. They also knew how to inflict the greatest possible harm.
Why not just block everyone?
Cloudflare offered an “Under Attack Mode” that would give every site visitor, legitimate or otherwise, a JavaScript challenge. The team chose not to use it.
The team avoided breaking every API integration by relying on rate limiting and targeted challenges, along with adding more caching and pushing more features out to the edge, rather than risking friction for the hundreds of thousands of real docs readers.
Several Read the Docs assets were targeted, including public community documentation and commercially hosted docs. The assault also aimed at author-facing dashboards that need logins.
| Defense strategy | What it does | How it fared |
|---|---|---|
| Cloudflare automated DDoS protection | Filters traffic from known botnets | Mitigated some traffic, but a big part passed through |
| IP-based rate limiting | Limits requests per IP or subnet | Solved past abuse, partially effective against global attack |
| WAF rules | Filters malicious request patterns | Required constant adjustment as attackers adapted |
| Moving redirects to the edge | Serves 302s from Cloudflare instead of Python backend | Fixed the initial vulnerability within half an hour |
| JavaScript challenges | Blocks all visitors until they solve a challenge | Rejected — would break API integrations and frustrate readers |
What the team learned
The team credits Cloudflare as essential. “There’s no way we could have handled this attack without Cloudflare,” they wrote.
Read the Docs faced an attack that dwarfed anything it had seen before by a factor of 10. It was more distributed, more adaptive, and more sophisticated than the simpler traffic floods of the past. The attackers deliberately targeted points that went around the caching system.
The attack put infrastructure, edge defenses, and incident response procedures under pressure. The group has returned to their usual sleep schedule after resolving the situation. Their account details the structure of the assault, explains why existing rate limiting only partly slowed it down, and describes which tactics truly kept services running without interruption.
The takeaway for smaller ops teams is simple: an assault that hits from multiple angles, adjusts itself to your defenses, and aims at your cache misses is unlike anything else. A single limit on requests will not be enough to protect you.
Source: about.readthedocs.com
Get the Notebook.
The day's best stories and every fresh verdict, in plain English, in your inbox by seven. One email a day, no more.