From 4578be2c82bfa26bd01c34373f763a44927d0f2c Mon Sep 17 00:00:00 2001 From: mrhid6 Date: Mon, 24 Aug 2026 12:50:44 +0000 Subject: [PATCH] docs: Updated troubleshotting doc --- docs/reference/troubleshooting.md | 47 +++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index 548c50a..93dba82 100644 --- a/docs/reference/troubleshooting.md +++ b/docs/reference/troubleshooting.md @@ -95,6 +95,53 @@ instantaneous. - The keyword no longer appears in the response body. - Retries are `0`, so a single dropped packet flips the state. +### The check gets a 403, 429 or a CAPTCHA page + +The endpoint is fine and answers a browser normally, but the monitor records a +status it never sees by hand. Something between Vantage and the service is +blocking automated traffic: a CDN, a WAF, a bot-protection product, a reverse +proxy rule, or a rate limiter. The response usually comes from that layer and +never reaches the origin at all, so nothing appears in the application's own +logs. + +Two things make it hard to spot. The check runs from the control plane's or the +agent's address rather than yours, and those addresses are often datacenter +ranges that bot protection scores badly. And a browser test proves nothing, +because a browser is exactly what the blocking layer is willing to serve. + +Every HTTP check Vantage makes identifies itself: + +``` +User-Agent: Vantage-Monitor/1.0 (+https://vantage.hostxtra.co.uk) +``` + +That string is the hook to allow the check through. In whichever product is +doing the blocking, add a rule that skips bot protection, managed rules and rate +limiting for requests carrying it — Cloudflare, AWS WAF, Azure Front Door, +Akamai, Fastly, Imperva, Sucuri, ModSecurity, nginx and HAProxy all match on a +request header. The shape of the rule is the same everywhere: + +> If the host is *yours*, the path is *the one being monitored*, and the +> User-Agent contains `Vantage-Monitor`, then skip the protection. + +Three details are worth getting right: + +- **Match on `contains`, not equality.** The version in the string moves. An + exact match breaks silently on an upgrade, and the symptom is a monitor that + goes down on deploy day. +- **Keep the rule narrow.** Scope it to the specific host and path being + monitored. A User-Agent is not a secret — anyone can send it — so a rule that + skips protection site-wide on that string alone is a bypass you have + published. +- **Allow the source address too, where you can.** Combining the User-Agent with + the checker's IP is stronger than either alone. Find the address in your + blocking product's own event log; it is whichever client IP was blocked on the + monitored path. + +If the endpoint genuinely needs authentication rather than an exception, monitor +a purpose-built health path that does not, and leave the protected paths +protected. + ## Notifications are not arriving Use the channel **Test** button. It goes through the real delivery path, so a