From 6009413c86857813e4144ce7346b2212ca246cd9 Mon Sep 17 00:00:00 2001 From: Timon de Groot Date: Wed, 17 Jun 2026 16:31:10 +0200 Subject: [PATCH 1/2] botstopper: Update documentation New cookie settings reflected in documentation. Country code example added. Weight added to botstopper log example --- .../botstopper/how-to-use-botstopper.md | 34 +++++++++++++++++++ .../botstopper/how-to-view-botstopper-logs.md | 6 ++-- 2 files changed, 37 insertions(+), 3 deletions(-) diff --git a/docs/hypernode-platform/botstopper/how-to-use-botstopper.md b/docs/hypernode-platform/botstopper/how-to-use-botstopper.md index 21bd956c..b7516935 100644 --- a/docs/hypernode-platform/botstopper/how-to-use-botstopper.md +++ b/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. diff --git a/docs/hypernode-platform/botstopper/how-to-view-botstopper-logs.md b/docs/hypernode-platform/botstopper/how-to-view-botstopper-logs.md index cc5c3d70..5d4e8db9 100644 --- a/docs/hypernode-platform/botstopper/how-to-view-botstopper-logs.md +++ b/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. From a83261e8c16f7bedfe4d1f7f7fe5fa93aec93d15 Mon Sep 17 00:00:00 2001 From: Timon de Groot Date: Wed, 17 Jun 2026 16:31:26 +0200 Subject: [PATCH 2/2] docs: Fix incorrect admonition type --- .../varnish/Investigating-varnish-errors-on-hypernode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hypernode-platform/varnish/Investigating-varnish-errors-on-hypernode.md b/docs/hypernode-platform/varnish/Investigating-varnish-errors-on-hypernode.md index ed5af16a..5b0f05b9 100644 --- a/docs/hypernode-platform/varnish/Investigating-varnish-errors-on-hypernode.md +++ b/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/). ```