Read the Docs details record 5.5M requests-per-minute DDoS that evaded its CDN caches

Read the Docs has published a post-mortem of the largest and most sophisticated distributed denial-of-service attack in its history: a ten-day campaign in mid-to-late June 2026 that peaked at more than 5.5 million requests per minute, roughly 100 times the documentation host's normal daily peak of under 100,000 requests per minute.

How the attack worked

According to the post, what set the June attack apart from earlier traffic floods was its distribution and adaptability. Malicious requests arrived from millions of unique IP addresses spread across hundreds of networks, including residential IP blocks alongside both major and minor hosting providers. The traffic came from every country at once, which Read the Docs says made rate limiting rules applied per Cloudflare datacenter extremely hard to craft without also throttling legitimate bots fetching at reasonable rates. Attackers also systematically randomized HTTP headers and TLS connection parameters to defeat signature-based filters built on JA3/JA4 fingerprints.

The botnet was adaptive in other ways. When blocks or rate limits went into effect, it adjusted request rates, rotated through different target paths and spread traffic across wider IP pools to probe the defense boundaries. It also ran a "yo-yo" pattern, ramping up to discover rate limit thresholds and then backing off to let the windows expire — a tactic the company says is designed to maximize the financial cost of auto-scaled infrastructure and cause intermittent degradation, evidence the attackers knew a web application firewall with rate limits was in place.

Multiple Read the Docs properties were hit, including public community documentation, commercially hosted docs, and author-facing dashboards that require logins.

Aimed straight at the cache

The most consequential tactic was cache evasion. Rather than hitting popular documentation pages a CDN serves cheaply, the botnet deliberately requested URLs that produced cache misses: non-existent pages on unique paths returning 404s, and temporary 302 redirects served by the Python backend rather than the edge.

The incident began on a small number of domains where attackers found uncached redirects. The operations team was paged within minutes after a short outage — one readers may not have noticed because cached documentation kept serving — and within about half an hour had moved those redirects to Cloudflare's edge. The attackers responded by trying different tactics across other hosts and services for another week and a half, including a phase where enough traffic hit a hardcoded Nginx rewrite rule to cause dropped requests even on horizontally scaling infrastructure.

The defense that worked

Read the Docs says it could not have handled the attack without Cloudflare, but the vendor's automated DDoS protection only stopped traffic it attributed to "known botnets"; a large share passed through to the company's own rate limiting and WAF rules.

The team declined to enable Cloudflare's "Under Attack Mode," which would have presented a JavaScript challenge to every visitor. That would have broken API integrations and added friction for hundreds of thousands of documentation readers. Instead, the company leaned on dozens of rate limiting rules — managed through Terraform and keyed on IPs, hostnames, the hundreds of thousands of subdomains it hosts, ASNs and browser fingerprints — combined with bot probability scores to challenge suspicious traffic while leaving well-behaved users and bots alone. That approach explicitly accepts letting some malicious traffic through rather than risk challenging real users.

Caching carried much of the load. Because documentation changes infrequently, Read the Docs caches aggressively at the edge and purges a site's cache whenever new docs are rebuilt. The post notes that attackers could distinguish cached from uncached requests simply by how fast the CDN responded, so even a few uncached endpoints became the angle of attack — and even very short-lived cached responses for redirects and 200s, set via the Cache-Control header, shrink that surface. The overall lesson is framed as defense in depth: edge caching, WAFs, rate limiting, local caches and request fingerprinting, on the principle that the fastest request is the one the CDN answers.

The post also situates the incident in a broader trend: roughly two years of rising abuse as AI crawlers became prevalent, with AI-generated scrapers plugged into proxy networks, and peers in the dev infrastructure community reporting similar pressure. Even so, the June attack was more than ten times larger than anything Read the Docs had previously faced.

Why it matters

Any public documentation host — or any site behind a CDN — shares the structural weakness the attackers exploited: a handful of uncached endpoints, such as dynamic redirects and 404 paths, is enough to drag origin infrastructure into a volumetric flood that caching would otherwise absorb. The post-mortem is a practical template for operators: inventory what your CDN does not cache, push more logic out to the edge, treat short-TTL caching as a defensive tool, and decide in advance how much friction you will impose on real users — because an adaptive botnet will find whichever boundary you have not already tested.