Merge pull request #501 from ByteInternet/botstopper_improvements

Botstopper improvements

Author: tdgroot

docs/hypernode-platform/botstopper/how-to-use-botstopper.md

@@ -48,6 +48,10 @@ Enable it again for that vhost with:
 hypernode-manage-vhosts example.com --botstopper
 ```
 
+```{tip}
+Keep in mind that botstopper is only active for HTTPS domains, because it uses the Secure flag for its cookies, which requires TLS.
+```
+
 ## Choose an AI Policy
 
 Botstopper has three AI policies. The default policy is `aggressive`.
@@ -229,6 +233,19 @@ Allow JSON API requests, using [CEL expressions](https://anubis.techaro.lol/docs
       - 'path.startsWith("/api/")'
 ```
 
+Add suspicion weight for traffic from a specific country:
+
+```yaml
+- name: weigh-countries-with-high-bot-traffic
+  action: WEIGH
+  expression:
+    all:
+      - '"X-Country-Code" in headers'
+      - 'headers["X-Country-Code"] in ["BY", "RU"]'
+  weigh:
+    adjust: 10
+```
+
 You usually do not need allow rules for API or webhook traffic. Botstopper allows traffic by default. Use an `ALLOW` rule when you already have, or plan to add, a broader custom rule that could otherwise challenge or block this trusted traffic.
 
 ## Logging
@@ -237,6 +254,23 @@ The botstopper service logs to `/var/log/botstopper/botstopper.log`. The log fil
 
 To check the Botstopper logs in a human-readable manner, you can use the `hypernode-parse-botstopper-log` command. Read more about it in [How to View Botstopper Logs on Hypernode](./how-to-view-botstopper-logs.md).
 
+## Cookies
+
+In order to verify visitors, Botstopper uses cookies to track whether a visitor has passed a challenge. The following cookies are used:
+
+| Cookie Name                        | Purpose                                                            |
+| ---------------------------------- | ------------------------------------------------------------------ |
+| `hnbotstopper-auth`                | Used for authenticated sessions after a successful challenge.      |
+| `hnbotstopper-cookie-verification` | Temporary cookie to check whether the browser has cookies enabled. |
+
+Cookies sent by Botstopper have the following flags set:
+
+| Flag            | Purpose                                                                    |
+| --------------- | -------------------------------------------------------------------------- |
+| `Secure`        | Ensures cookies are only sent over HTTPS connections.                      |
+| `HttpOnly`      | Prevents client-side scripts from accessing the cookies.                   |
+| `SameSite=None` | Cross-domain requests will keep working, safe option with the Secure flag. |
+
 ## Safe Policy Changes
 
 Use specific rules whenever possible. Broad user-agent rules can block legitimate crawlers or integrations.

docs/hypernode-platform/botstopper/how-to-view-botstopper-logs.md

@@ -32,9 +32,9 @@ app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --today
 The output shows the timestamp, log level, message, and request metadata:
 
 ```console
-2026-06-05 01:40:05.717877576Z [INF] new challenge issued > host=example.com method=GET path=/ user_agent="Mozilla/5.0 (compatible; CensysInspect/1.1; +https://about.censys.io/)" client_ip=66.132.172.211 accept_language="" priority="" challenge=019e956f-ffd3-735d-9dce-5fe1aa40d534
-2026-06-05 02:07:11.959647899Z [INF] new challenge issued > host=example.com method=GET path=/ user_agent="Mozilla/5.0 (X11; Linux x86_64; rv:142.0) Gecko/20100101 Firefox/142.0" client_ip=134.209.40.161 accept_language=en-US,en;q=0.5 priority="u=0, i" challenge=019e9588-d054-7c99-8684-61bbcb099b2f
-2026-06-05 02:38:01.225327165Z [INF] new challenge issued > host=example.com method=GET path=/compete-track-tote.html user_agent="Mozilla/5.0 (Linux; Android 5.0) AppleWebKit/537.36 (KHTML, like Gecko) Mobile Safari/537.36 (compatible; TikTokSpider; ttspider-feedback@tiktok.com)" client_ip=47.128.111.110 accept_language=en-US,en;q=0.5 priority="u=0, i" challenge=019e95a5-0807-759a-80d7-f450d68a1923
+2026-06-05 01:40:05.717877576Z [INF] new challenge issued > host=example.com method=GET path=/ user_agent="Mozilla/5.0 (compatible; CensysInspect/1.1; +https://about.censys.io/)" client_ip=66.132.172.211 accept_language="" priority="" challenge=019e956f-ffd3-735d-9dce-5fe1aa40d534 weight=10
+2026-06-05 02:07:11.959647899Z [INF] new challenge issued > host=example.com method=GET path=/ user_agent="Mozilla/5.0 (X11; Linux x86_64; rv:142.0) Gecko/20100101 Firefox/142.0" client_ip=134.209.40.161 accept_language=en-US,en;q=0.5 priority="u=0, i" challenge=019e9588-d054-7c99-8684-61bbcb099b2f weight=10
+2026-06-05 02:38:01.225327165Z [INF] new challenge issued > host=example.com method=GET path=/compete-track-tote.html user_agent="Mozilla/5.0 (Linux; Android 5.0) AppleWebKit/537.36 (KHTML, like Gecko) Mobile Safari/537.36 (compatible; TikTokSpider; ttspider-feedback@tiktok.com)" client_ip=47.128.111.110 accept_language=en-US,en;q=0.5 priority="u=0, i" challenge=019e95a5-0807-759a-80d7-f450d68a1923 weight=10
 ```
 
 Common messages include `new challenge issued` for visitors or bots that received a browser challenge.

docs/hypernode-platform/varnish/Investigating-varnish-errors-on-hypernode.md

@@ -127,7 +127,7 @@ If errors continue, consider gradually increasing the workspace values further (
 
 If the problem persists after applying these fixes, contact support for further assistance.
 
-```{information}
+```{tip}
 For more information about Varnish configuration and tuning, see our [documentation on improving Varnish hit rate](https://docs.hypernode.com/hypernode-platform/varnish/improving-varnish-hit-rate-on-hypernode.html) and the official
 [Varnish documentation](https://varnish-cache.org/docs/).
 ```