Bottle is a bot throttling plugin. It consists of a set of tools that can be used to reduce server load when excessive bot requests are made to a website.
It works by performing a variety of checks on each HTTP request made to WordPress, and throttling sessions or IPs when thresholds are exceeded. These include:
-
Too many sessions per IP. Since some bots don’t bother with cookies, Bottle sets a JWT session cookie for each request. If a single IP address creates too many new sessions within a given timeframe, it is likely a bot, and will be throttled.
-
Too many requests per session. Bottle calculates a request rate for each session. Bots that exceed that rate will be throttled.
-
Too many requests per IP. Bottle calculates a request rate per IP. For bots that don’t process cookies (and therefore sessions), this can throttle abusive IPs.
-
Too many requests per bot. Bottle calculates a request rate per bot (based on user agent reported). Since malicious bots forge user agents, this should be combined with other throttling mechanisms.
-
Bot verification check. Bottle checks bots such as Google, Bing, Meta, etc. against authoritative lists of IP addresses, when possible. Bottle allows for a higher verified bot rate than non-verified rate with the idea that verified bots are likely better behaved.
-
Overall request rate. Bottle can throttle specific sections of a website that are being abused by bots. (For instance, the courses catalog.) This is useful when a large website is being scraped by a bot network with rotating IPs.
-
Excessive 404s. If bots are scanning a website, or are misconfigured, excessive 404s can be time-consuming for WordPress to process. Bottle can either throttle all 404 requests, or can block 404s for static files (i.e. images) only.
-
Exclusions. Bottle can exclude certain URLs, IP addresses, or infrastructure (such as Stripe and Pingdom) from processing to prevent false positives.
When a client is throttled, Bottle can outright throttle it with a 429 response, or can serve a JavaScript-based cryptographic puzzle. If a client is legitimate, it will automatically compute the puzzle’s solution and submit it to the server for verification. (No user input is required.) After it has proven its human-ness, Bottle will permit that user entry to the site. At the moment, some bots, but not all, will solve these puzzles.
When a throttle condition is reached, Bottle terminates WordPress processing, which substantially reduces server load when under attack. Throttles end automatically at the end of their respective measurement windows.
Bottle is not a firewall and will not block or sanitize malicious attacks. However, since such attacks are typically performed in large quantities, Bottle can be effective at slowing such attacks and reducing server load, keeping the website operational for legitimate users.
Overall, Bottle is a set of tools designed to reduce server load with minimal disruption to real users.
Screenshots
Bottle offers a range of configurable tools, stats, and logging.
A heatmap shows the level of throttle activity per throttle type, grouped hourly.
A bot heatmap indicates the level of website usage per bot. Note that some bots are verified by IP address. (Bots may forge their reported user agent.)
The Live Requests log shows all requests, including reverse DNS lookup, identified bot, bot IP verification status, and throttle action. Its purpose is to help you configure each of the throttle tools.
The Throttle log shows which requests were throttled and why, including IP, user agent, bot, and bot verification status. It also shows when the PoW is solved (which allows a client to bypass the throttle).
The User Agents log shows which user agents were throttled. This can be useful for identifying forged user agents, scrapers, security tools, and more.
The Paths log shows which URLs triggered throttles. This can be helpful if there are patterns of abuse, or if certain parts of the site are being scraped.
The IPs log shows which IPs triggered the throttles, and the number of throttles per IP.
Session throttle settings allow you to throttle IPs that create too many sessions too quickly, and throttle sessions that access too many pages too quickly.
Request rates by IP address and by bot type allow you to throttle abusers. Verified bots can be provided a higher rate.
Overall Page Matching Throttle is a tool that throttles a specific section of a website that is being abused by bots. (For instance, the courses catalog.) This is useful when a large website is being scraped by a bot network with rotating IPs.
404s is a tool that can block IPs that make requests for too many non-existant static files. Or, it can throttle IPs that request too many non-existant pages.
Exclude is a tool that lets you configure overrides for the throttle tools (URL begins with, URL contains, and IP address). Known infrastructure services such as Stripe and Pingdom are verified by IP address and can be excluded from all throttles.
Proof-of-Work is an cryptographic puzzle displayed to users instead of an outright 429 HTTP code (throttle). Many bots do not process JavaScript and will not solve puzzles. The length is the complexity of the puzzle. A larger number generally takes longer to solve, so this is a measure of how long a delay your legitimate users will face when throttled.
Logging options includes log location and rotation settings. We recommend using the Request Logging tool only for setup or debugging and leave it disabled the rest of the time.
The Proof-of-Work presented to throttled clients.